diff --git a/docs/sources/main.adoc b/docs/sources/main.adoc index cb00c40..49f846a 100644 --- a/docs/sources/main.adoc +++ b/docs/sources/main.adoc @@ -40,7 +40,7 @@ endif::[] = Introduction -`Overtone` is an audio programming library using the Supercollider synthesizer engine via the expressive programming language `Clojure`. It combines the power of Supercollider and Clojure enabeling many artistic endeavors, including: +`Overtone` is an audio programming library using the Supercollider synthesizer engine via the expressive programming language `Clojure`. It combines the power of Supercollider and Clojure enabling many artistic endeavours, including: * Sound design * Musical composition @@ -50,15 +50,15 @@ endif::[] * Live-coding * DAW integration * AbletonLive clock synchronization via AbletonLink -* RaspberryPI/Bela/Monome compatability +* RaspberryPI/Bela/Monome compatibility == Preface It is my hope that this book will be a gentle introduction to `Overtone` for a complete beginner as well as for a novice. I hope to approach the topic of Overtone with a grain of cynicism; "what can go wrong will go wrong". Overtone is still a highly unstable library and for a workshop of 6-8 participants, it takes usually half an hour or less to get everyone started. That said, you'll most likely encounter redundant details and/or debugging instructions for highly improbable scenarios while reading this book. Keep in mind that what may seem obvious to you isn't necessarily obvious to everyone. -The computer can be an amazing, exciting tool to fulfill our creative needs. But at the same time the computer, and its building blocks, computer programs and code, can be at times indescribably painful, misconfigured and unpredictive. The hurdles you may encounter may include tooling, mac/linux/windows specific problems, files and libraries mislocated, version incompatibilities, and the list can go on forever. Luckily we will be getting ourselves comfortable with the programming language Clojure, which in the total 10 years of its existence, has seen an explosion of book publications, tutorials, workshops and stackoverflow questions/answers. So if you find youself in the unfortunate situation of getting stuck with something unrelated to Overtone, your odds are good that someone else on the internet already had the same problem as you, and you're only one google search away from getting yourself back on track. At any point in time for any problem you are facing, you should always feel welcome to open a ticket on github, ask question on stackoverflow, the irc(freenode) or on slack(clojurians). The software community as a whole is riddled with micro-aggressive "bromance" behaviour and hence can be at times quite intimidating for beginners to reach out for help. Which among other factors(in my subjective opinion), means that we end up with demographics of coders, be it art related or not, completely out of proportion to the demographics of the general population. Please be aware that the Clojure community has on all social-media platforms, meetups and conferences a set of guidelines for behaviour, protocols in case of violation and a group of confidentials to report violations to. I believe that these measures has made the Clojure community relatively more inclusive and diverse, every day I see experienced developers go out of their way to help someone in need of help and I hope you will enjoy the benefits of the Clojure community in the same way as I did when I was a total beginner. +The computer can be an amazing, exciting tool to fulfil our creative needs. But at the same time the computer, and its building blocks, computer programs and code, can be at times indescribably painful, misconfigured and unproductive. The hurdles you may encounter may include tooling, mac/linux/windows specific problems, files and libraries mislocated, version incompatibilities, and the list can go on forever. Luckily we will be getting ourselves comfortable with the programming language Clojure, which in the total 10 years of its existence, has seen an explosion of book publications, tutorials, workshops and stackoverflow questions/answers. So if you find yourself in the unfortunate situation of getting stuck with something unrelated to Overtone, your odds are good that someone else on the internet already had the same problem as you, and you're only one google search away from getting yourself back on track. At any point in time for any problem you are facing, you should always feel welcome to open a ticket on github, ask question on stackoverflow, the irc(freenode) or on slack(clojurians). The software community as a whole is riddled with micro-aggressive "bromance" behaviour and hence can be at times quite intimidating for beginners to reach out for help. Which among other factors(in my subjective opinion), means that we end up with demographics of coders, be it art related or not, completely out of proportion to the demographics of the general population. Please be aware that the Clojure community has on all social-media platforms, meetups and conferences a set of guidelines for behaviour, protocols in case of violation and a group of confidentials to report violations to. I believe that these measures has made the Clojure community relatively more inclusive and diverse, every day I see experienced developers go out of their way to help someone in need of help and I hope you will enjoy the benefits of the Clojure community in the same way as I did when I was a total beginner. -As my personal advice as an artist to artists stepping into the journey of creative coding: don't believe everything software engineers tell you about software, in the same way you shouldn't believe everything an artist tells you about how art should be. An artist and software-engineer will and should approach code in different ways. You will never hear stories about Beethoven implementing a Continous Integration test to determine if his 7th symphony accidentally lost a note while he was writing his 8th, or Stravinsky trip out on his Bassoon type checker when he wrote the introduction to the Rite of Spring. Learning from the best is always a good approach and becoming better at programming is only going to make you faster and more effective, but do watch out for the abyss of infinite information and take moderate actions. If our goal is to create art for the real world, be completely shameless if your code isn't orthodox as long as it produces the desired result and you had fun writing it. While the "old-school" composer is sitting next to a piano with pen and empty staff notation paper, in the same way you will find ourself with an empty text document in your text editor, with your fingers on the keyboard, ready to explore the physical boundaries of music, sound and time. +As my personal advice as an artist to artists stepping into the journey of creative coding: don't believe everything software engineers tell you about software, in the same way you shouldn't believe everything an artist tells you about how art should be. An artist and software-engineer will and should approach code in different ways. You will never hear stories about Beethoven implementing a Continuous Integration test to determine if his 7th symphony accidentally lost a note while he was writing his 8th, or Stravinsky trip out on his Bassoon type checker when he wrote the introduction to the Rite of Spring. Learning from the best is always a good approach and becoming better at programming is only going to make you faster and more effective, but do watch out for the abyss of infinite information and take moderate actions. If our goal is to create art for the real world, be completely shameless if your code isn't orthodox as long as it produces the desired result and you had fun writing it. While the "old-school" composer is sitting next to a piano with pen and empty staff notation paper, in the same way you will find yourself with an empty text document in your text editor, with your fingers on the keyboard, ready to explore the physical boundaries of music, sound and time. == About this Book @@ -76,7 +76,7 @@ This source for this book is hosted on https://github.com/overtone/overtone.gith The examples and code used in this book will try to be as neutral as possible when it comes to choice of text-editor. All modern text editors have some sort of plugin to run and evaluate Clojure code. If you are starting out with the programming language Clojure, you may easily get confused or lost on how to replicate some of the examples in your text editor. Therefore we aim to make all of our examples replicable using nothing but Leiningen in the terminal via `lein repl`, and assume from the reader basic understanding of the terminal/cmd (if you know how to explore directories and install apps with the terminal, you probably know enough). Leiningen is the most popular build tool in Clojure and is the build tool that glues Overtone's sources and dependencies together. Overtone does work with alternative build tools like `boot`, as well as a standalone java jar file, but that and how to integrate Overtone to any specific text-editor will not be included in this book. -Please be also aware that topics often overlap. If something isn't clear, have a look at the chapter titles to see if the concepts you're trying to understand are explained elswhere in the book. +Please be also aware that topics often overlap. If something isn't clear, have a look at the chapter titles to see if the concepts you're trying to understand are explained elsewhere in the book. = Installation @@ -117,7 +117,7 @@ $ nix-env -i libjack2 == Setting up a project -Although it is possible to start Overtone directly from the https://github.com/overtone/overtone[github repository] by downloading it as zip or cloning it with `git clone https://github.com/overtone/overtone.git` in the terminal, it is recommended that `Overtone` is used as any other Clojure library in your own project. So we will do exacly that. +Although it is possible to start Overtone directly from the https://github.com/overtone/overtone[github repository] by downloading it as zip or cloning it with `git clone https://github.com/overtone/overtone.git` in the terminal, it is recommended that `Overtone` is used as any other Clojure library in your own project. So we will do exactly that. First create an empty directory, we'll call it overtone (the name is irrelevant here) and go into it @@ -126,7 +126,7 @@ $ mkdir overtone $ cd overtone ``` -Then in your text-editor, create a new textfile and save it into the newly created directory as `project.clj`. This is file that leiningen looks for inside the folder leiningen was started from (ie. you can't start leiningen in directory x and expect it to find `project.clj` in directory y). Then paste the following code into `project.clj` and save the file again. +Then in your text-editor, create a new text file and save it into the newly created directory as `project.clj`. This is file that leiningen looks for inside the folder leiningen was started from (ie. you can't start leiningen in directory x and expect it to find `project.clj` in directory y). Then paste the following code into `project.clj` and save the file again. [subs="verbatim,attributes"] ```clojure @@ -144,7 +144,7 @@ $ lein deps TIP: `lein deps` is actually a redundant command as `lein repl` implicitly fetches Clojure dependencies before starting the REPL. It is only useful if you want to fetch the dependencies without starting the REPL. -If you're running leiningen for the first time you should see a whole bunch of text appearing on the screen, indicating that leiningen is downloading the Clojure dependencies needed to run Overtone. After this process, directories `target` and `native` should have been created, both of these directories can be safely omitted if you're planning on saving your code on for example github, and `target` can even be deleted at any time, by literally deleteing it or by running `lein clean` which by default deletes `target`, that will only be useful if you're trying to debug your program as `target` gets created every time you run leiningen to store various information irrelevant to us at this moment. But do keep `native` untouched as it stores the necessary files needed to run Supercollider from within Overtone. +If you're running leiningen for the first time you should see a whole bunch of text appearing on the screen, indicating that leiningen is downloading the Clojure dependencies needed to run Overtone. After this process, directories `target` and `native` should have been created, both of these directories can be safely omitted if you're planning on saving your code on for example github, and `target` can even be deleted at any time, by literally deleting it or by running `lein clean` which by default deletes `target`, that will only be useful if you're trying to debug your program as `target` gets created every time you run leiningen to store various information irrelevant to us at this moment. But do keep `native` untouched as it stores the necessary files needed to run Supercollider from within Overtone. Now let's start Clojure via `lein repl` @@ -221,7 +221,7 @@ user=> If something went wrong, see if the stacktrace gave you any meaningful information and proceed to <> and try to rule out that something isn't misconfigured. And come back here and try to start Overtone again before continuing. A good rule of thumb is to read stacktraces from top to bottom, the uppermost lines being the most important ones in most of the cases. -TIP: If you're on Linux too and encounter `Cannot allocate memory` and/or `Cannot use real-time scheduleing` you can totally ignore that, it just means that you're not running preempt realtime-kernel. Switching to rt-kernel can potentially improve your audio performance by allowing Jack to send audio on top priority, but at the cost potentially make things very complicated and possibly insecure, as rt-kernels are usually released that much later than other kernels. If you want to run proprietary nvidia/ati drivers on preemt rt-kernel, you're most likely going too have a bad time, irrelevant if you're a linux expert or a beginner. +TIP: If you're on Linux too and encounter `Cannot allocate memory` and/or `Cannot use real-time scheduling` you can totally ignore that, it just means that you're not running preempt realtime-kernel. Switching to rt-kernel can potentially improve your audio performance by allowing Jack to send audio on top priority, but at the cost potentially make things very complicated and possibly insecure, as rt-kernels are usually released that much later than other kernels. If you want to run proprietary nvidia/ati drivers on preemt rt-kernel, you're most likely going too have a bad time, irrelevant if you're a linux expert or a beginner. Now that we have Overtone running successfully. We can start all the functions that Overtone provides at our disposal. Among them is an important helper function called `doc`, which will print the documentation to any function in your scope/reach. Let's try it on the symbols `demo` and `sin-osc`. @@ -375,9 +375,9 @@ The following two expressions will be played exactly the same. ``` === Other ways to envelope -Since an envelope can be any modulating signal, we can create an envelope shape using low-frequency-oscillators or LFO for short. A low-frequency-oscillator is typically an oscillator that oscillates at a frequency under the lower limit of human hearing range ~22Hz. In overtone you can find LFO oscillators starting with LF, which include `lf-saw`, `lf-par`, `lf-pulse`, `lf-tri` and countless more. They differ only from traditional oscillators in that they are not band-limited and are more performant, since they don't try to anti-aliase high frequencies. When working with LFO's in most cases, it doesn't matter if you use band-limited or non-band-limited oscillators, they behave exactly the same on low frequencies. +Since an envelope can be any modulating signal, we can create an envelope shape using low-frequency-oscillators or LFO for short. A low-frequency-oscillator is typically an oscillator that oscillates at a frequency under the lower limit of human hearing range ~22Hz. In overtone you can find LFO oscillators starting with LF, which include `lf-saw`, `lf-par`, `lf-pulse`, `lf-tri` and countless more. They differ only from traditional oscillators in that they are not band-limited and are more performant, since they don't try to anti-alias high frequencies. When working with LFO's in most cases, it doesn't matter if you use band-limited or non-band-limited oscillators, they behave exactly the same on low frequencies. -The following expression plays a sawtooth oscillator for 1 second with even attack and decay time created from the shape of sinewave. Note that we are converting Hertz(1/sec) to seconds, as reference 1Hz takes 1 second to finish 1 cycle. As we are using sinewave shape from `sin-osc:kr` we are only concerned with the positive values from 0 to 1, which occupy the first half of the sinewave. Therefore we multiply the wanted note duration by 2, so that the signal cuts off exacly before the sinewave goes from 0 to a negative value. The `line:kr` serves as timeout that frees the synth node after 1 second and hence prevents it from playing the full 4 seconds which the demo time defaults to. +The following expression plays a sawtooth oscillator for 1 second with even attack and decay time created from the shape of sinewave. Note that we are converting Hertz(1/sec) to seconds, as reference 1Hz takes 1 second to finish 1 cycle. As we are using sinewave shape from `sin-osc:kr` we are only concerned with the positive values from 0 to 1, which occupy the first half of the sinewave. Therefore we multiply the wanted note duration by 2, so that the signal cuts off exactly before the sinewave goes from 0 to a negative value. The `line:kr` serves as timeout that frees the synth node after 1 second and hence prevents it from playing the full 4 seconds which the demo time defaults to. ```Clojure (demo (let [dur 1 @@ -433,12 +433,12 @@ Here are some tutorial videos about envelopes, not related specifically to Overt This section will cover oscillators in Overtone and more specifically wavetable oscillators; How we can create wavetable oscillators, how we can mix them and how we can use envelopes to give a dull sound more liveness. First we will look at wavetables in depth for educational purposes and then at ever more practical applications of wavetable synthesis in Overtone. === Wavetable -Wavetable synthesis with computers, explained at its essence, is the way of creating a signal by reading phase values from a table and sending those values in sample-rate to a given audio source (also refered to as https://en.wikipedia.org/wiki/Pulse-code_modulation[Liner Pulse-Code Modulation]). In Overtone the phase values are stored between -1 and 1. As opposed to a 16-bit .wav file which stores its values as integers from 0 to 65,535 or −32,768 to 32,767 depending if it's unsigned or signed integers respectively. Same goes for the audio hardware in your computer, if it's set to 16-bits resolution, then supercollider will remap the floats between -1 and 1 to an integer range that the audio hardware expects to receive. When refering to phase in this context, can be misleading to newcomers. For oversimplification you can think of phase stored from samples and audio files purely as amplitude, since a signal going from -1 to 1 is playing audio on full amplitude strength. Whereas you may play your Overtone instruments with amplitudes that are in the range of 0 and 1 (there's no such thing as negative amplitude), the supercollider engine will create a signal that has phase values from -1 to 1 and the audio module will take the signal from Supercollider and remap it to −32,768 to 32,767 (for 16-bit). +Wavetable synthesis with computers, explained at its essence, is the way of creating a signal by reading phase values from a table and sending those values in sample-rate to a given audio source (also referred to as https://en.wikipedia.org/wiki/Pulse-code_modulation[Liner Pulse-Code Modulation]). In Overtone the phase values are stored between -1 and 1. As opposed to a 16-bit .wav file which stores its values as integers from 0 to 65,535 or −32,768 to 32,767 depending if it's unsigned or signed integers respectively. Same goes for the audio hardware in your computer, if it's set to 16-bits resolution, then Supercollider will remap the floats between -1 and 1 to an integer range that the audio hardware expects to receive. When referring to phase in this context, can be misleading to newcomers. For oversimplification you can think of phase stored from samples and audio files purely as amplitude, since a signal going from -1 to 1 is playing audio on full amplitude strength. Whereas you may play your Overtone instruments with amplitudes that are in the range of 0 and 1 (there's no such thing as negative amplitude), the Supercollider engine will create a signal that has phase values from -1 to 1 and the audio module will take the signal from Supercollider and remap it to −32,768 to 32,767 (for 16-bit). -TIP: As a possible source of terminological misunderstanding. The concept of "table" here refers to an indexed iterateable list of values. Clojure has no concept of "table", so when discussing tables in Clojure land, we would be a refering to a vector (or some other sequenceable list). If refering to a table in Supercollider land, we would be refering to a `Buffer`. +TIP: As a possible source of terminological misunderstanding. The concept of "table" here refers to an indexed iteratable list of values. Clojure has no concept of "table", so when discussing tables in Clojure land, we would be a referring to a vector (or some other sequenceable list). If referring to a table in Supercollider land, we would be referring to a `Buffer`. -That trivial knowledge above is quite irrelevant to our task of makeing wavetables in Overtone, but the connection of phase, amplitude, table and storage of audio is important to understand before we proceed. But let's create a sinewave table with the following formula stem:[sum_(n=0)^L=sin(frac{2pin}{L})**A]. Where `L` stands for table length (typically a number which is stem:[2^x]) and `A` stands for the amplitude. +That trivial knowledge above is quite irrelevant to our task of making wavetables in Overtone, but the connection of phase, amplitude, table and storage of audio is important to understand before we proceed. But let's create a sinewave table with the following formula stem:[sum_(n=0)^L=sin(frac{2pin}{L})**A]. Where `L` stands for table length (typically a number which is stem:[2^x]) and `A` stands for the amplitude. ```Clojure (let [L (Math/pow 2 10) @@ -473,15 +473,15 @@ Next thing to look out for is the relationship between the sample-rate and table Bravissimo Houston! By multiplying the wanted frequency to the ratio between table-size and sample-rate as defined in `playback-rate` above, we can modify the frequency as we wish. Later in the manual we will discuss samples, where the function `play-buf:ar` plays a huge role. With the difference that in wavetable synthesis we generate table representing one cycle, therefore we need to loop over the values multiple times a second to create an audible signal, whereas a sample is usually only played once trough. -Now we have to power to generate a vector in Clojure, send it to supercollider-land as a buffer and play back the values stored in the buffer with `play-buf:ar`. Now let's proceed. +Now we have to power to generate a vector in Clojure, send it to Supercollider-land as a buffer and play back the values stored in the buffer with `play-buf:ar`. Now let's proceed. // stem:[f(n)=sum_(k=1)^N P_k sin(frac{2pikn}{L})] // = Sound Designing -// By calling the process of modifying and manipulateing the mechanism of which a wave with energy travels trough a medium, sound-designing, we are effectivly being as broad as possible with our definition and nothing is left out. The amount of books, research papers and publications done on the topic of sound designing is enormous. Take for example the classic book https://mitpress.mit.edu/books/microsound[Microsound by Curtis Roads], it covers in over 400 tightly packed pages the various aspects and applications of granular-synthesis. The mathematics required to grasp the contents of that book would be a level of advanced calculus. +// By calling the process of modifying and manipulating the mechanism of which a wave with energy travels trough a medium, sound-designing, we are effectively being as broad as possible with our definition and nothing is left out. The amount of books, research papers and publications done on the topic of sound designing is enormous. Take for example the classic book https://mitpress.mit.edu/books/microsound[Microsound by Curtis Roads], it covers in over 400 tightly packed pages the various aspects and applications of granular-synthesis. The mathematics required to grasp the contents of that book would be a level of advanced calculus. -// Luckily for us we don't need to concern ourselves with low-level synthesis algorithmis, because inside the Supercollider engine we will find hundreds of functions made to manipulate sound. Functions which gives us more pleasureable interface to the complex mathematics on which they are built upon, in some cases with over two decades of battle tested experience by the Supercollider community on algorithms based on decades of research and hard work by scientists and universities all over the world. +// Luckily for us we don't need to concern ourselves with low-level synthesis algorithms, because inside the Supercollider engine we will find hundreds of functions made to manipulate sound. Functions which gives us more pleasurable interface to the complex mathematics on which they are built upon, in some cases with over two decades of battle tested experience by the Supercollider community on algorithms based on decades of research and hard work by scientists and universities all over the world. // When it comes to sound designing, more often than not, less is more. Case in point would be to analyze the almost infinite sonic possibilities you can fit inside one Twitter tweet with Supercollider code, http://sctweets.tumblr.com/[click to see some examples]. I leave it as home assignment to you after reading this book to write few of those Twitter tweets in Overtone, a great practice to improve your Overtone skills.