...noise space for Batuhan BozkurtSubscribe to my feed!
deQuencher Tutorial

Videos:
You can watch the video presentation for this tutorial in here:
Video for this tutorial

You can also find a .rtf copy of this tutorial that you can open with SuperCollider from the tutorial directory which residing in your program directory.

Here we go:
deQuencher is a front end for SuperCollider audio synthesis programming language. So you need to be using SC in order to make something meaningful with dQ. Go launch SC now.
Before booting server, run these:

//This is absolutely necessary for deQuencher to work properly. s.options.numAudioBusChannels = 1040; //Adjust memory according to your needs s.options.memSize = 512000;

You can put the above into your startup.rtf file so you won't have to run them each time you boot SuperCollider.

s.boot;

To get FreeSound(http://www.freesound.org) integration working you need to have the following 2 synths sent to server already. These synths are also included in the defaults.rtf file in your program folder. You also need to have a FreeSound account. Once you signup for an account, you need to edit the fsounder.py file which is located in your program folder, with a text editor and enter your username and password to the relevant fields. The fields are at near to the beginning of the file, you need to put them between the double quotes. Now send these synths to server.

( SynthDef("fsplayer_stereo", //freesound player for stereo files. { arg bufferNo, fxBusNo = 1038, fxMul = 0, t_trig100 = 0; var free = FreeSelf.kr(t_trig100); var needle = Phasor.ar(0, BufRateScale.kr(bufferNo), 0, BufFrames.kr(bufferNo)); var source = BufRd.ar(2, bufferNo, needle, 0, 2); Out.ar(fxBusNo, source.dup * fxMul); } ).send(s); SynthDef("fsplayer_mono", //freesound player for mono files. { arg bufferNo, fxBusNo = 1038, fxMul = 0, t_trig100 = 0; var free = FreeSelf.kr(t_trig100); var needle = Phasor.ar(0, BufRateScale.kr(bufferNo), 0, BufFrames.kr(bufferNo)); var source = BufRd.ar(1, bufferNo, needle, 0, 2); Out.ar(fxBusNo, source.dup * fxMul); } ).send(s); )

If you've followed all the directions above, you are now ready to use dQ. But to make something meaningful with it, you need to have some synth definitions sent to server for dQ to play with. Let's start with a simple one. The following synth is intended to be used as a "type 1" synth, meaning a "synth agent" for dQ. dQ does not care about the inputs of type 1 agents, but can control their outputs. The following synth gets input from your sound card inputs and lets dQ control its outputs. It will be called by its name by dQ.

( SynthDef("hardwarein", //To get audio from mono hardware input(left). //There are some arguments that you need to define, so that dQ can control //this synth. { arg fxBusNo = 1038, //dQ controls this argument to route the output //of this synth to the correct bus. The //initial value is the blackhole bus. fxMul = 0, //This argument controls the output level //of this synth. When an fx agent comes close, //that agent will control this argument based //on their distance between each other.The range //of this argument is between 0 and 1. t_trig100 = 0; //This is a reserved trigger. When you //delete an agent from dQ canvas, dQ will //send a trigger to this argument. You need //to handle it with some kind of system //that will to free this synth from server //(like FreeSelf.kr or doneAction: 2), //or else, it will be orphaned. //Here we are handling the t_trig100 trigger with FreeSelf.kr. var free = FreeSelf.kr(t_trig100); var inp = SoundIn.ar(0); //here we get an input from our sound card. //Now we need an Out UGen, with parameters as shown so that //dQ will be able to route the output from this synth properly. //All bus allocations in dQ are stereo(2 channels) so if you //want stereo output from a single channel you need to call .dup //in output. We also multiply the input with fxMul so that the //level will be controlled by the proximity of the approaching fx agent. Out.ar(fxBusNo, inp.dup * fxMul); //type 1(sAgent) } ).send(s); )

Now send this synth to server. This is a very simple synth, that just gets audio from sound card input and routes it. You can easily convert most of your sound generating synths by adding the above arguments and Out.ar UGen with the specified set of parameters.

To hear the audio that is being sent from this "hardwarein" synth, we need to define another synth, in this case an "fx synth" whose inputs are going to be controlled by dQ. Fx synths are called "type 3" synths. dQ does not care about their outputs, but allocates their inputs by itself. When an fx synth comes close to a type 1 or type 5(explained later) synth, their outputs are routed to the inputs of the fx synth. Fx synths can't be chained! You need to use type 4 agents to do chaining, it will be explained later. Here is a simple fx synth(type 3) that routes its input to sound card hardware outputs:

( SynthDef("out", //a terminal output synth, can't be chained. //Can be connected to type 1 synths and type 5 freesound synths. { arg inFxBusNo = 16, //dQ allocates a free bus and sets it to this //argument. Initialization is arbitrary. t_trig100 = 0; //What this does is explained before. Check //the above "hardwarein" synth. var free = FreeSelf.kr(t_trig100); //We HAVE TO use InFeedback when we are getting //inputs with dQ instead of In.ar. Because dQ //do not always handle the orderings of synths //in SC audio chain. We get the input from the //inFxBus argument. var in = InFeedback.ar(inFxBusNo, 2); //And here is our out statement. dQ does not care about //the outputs of type 3 synths, we are sending our input //to hardware outputs. You might have noticed that in //fx synths, we don't have an fxMul argument. Because //dQ sends the proximity data of fx agents to their "input" //agents as fxMul arguments. So the position of this synth will //control the fxMul argument of the master synth agent connected //to it. We are not using .dup here because the with the "in" variable, //InFeedback.ar already gives us 2 channels of //audio(the second argument is 2). Out.ar(0, in); }).send(s); //type 3(fAgent) )

Send the above synth to server and launch dQ. If you've read through the documentation(supplied in the docs folder and online) you probably know what to do, but let me repeat the procedure. In the dQ console, write "type 1" (or "t 1") without the quotes and press enter. dQ will reply: "Type set to 1". This means that we are now creating a type 1 agent. Then write "synth hardwarein" (or s hardwarein) then click on an empty space on the canvas.

You should see an empty circle(the visual representation of type 1 agents) with the name "hardwarein". You should also observe that in your SC server window you have Synths: 1 meaning you have a synth running on server at the moment. To hear the output from this synth, you need to connect it to an fx agent.

So now write "t 3"(enter) and "s out"(enter) then, click on an empty space on canvas. You will see a filled circle, which is the visual representation of an fx agent. You should have two synths running on server now. If the agents are close enough, you will see a link between them and also hear the input from your sound card in your speakers(use headphones to avoid feedback!). If they are not close enough, you need to move one closer to the other. To do that, first select one by right clicking and dragging on the canvas(if you don't have right button on your mouse, use shift click). Once it is selected it should grow in size. While it is selected, middle click and drag to move that agent closer to the other one. (if you don't have a middle button on your mouse, use "option click"). When they come close enough, you will be able to hear the sound coming from your hardware inputs at your outputs. The closer the agents, louder the sound. Here is another type 1 agent that emits a sine wave:

( SynthDef("sine", { arg fxBusNo = 10, fxMul = 0, t_trig100 = 0, param1, //this parameter will be controlled //by a parameter agent in dQ. t_trig1; //this trigger will be used //by a trigger agent in dQ. var free = FreeSelf.kr(t_trig100); var sine = SinOsc.ar(220 + (880 * param1.lag(0.1)), 0, 0.2 + (Decay.kr(t_trig1, 1) * 0.8)); Out.ar(fxBusNo, sine.dup * fxMul); //type 1(sAgent) } ).send(s); )

Send the above synth to server. There are two new things you need to notice. They are the new arguments defined at the beginning of the synth definition: param1 and t_trig1. dQ can control arguments with the format paramX and t_trigY, where X and Y are integers with its built-in parameter(type 0) and trigger(type 2) agents. In this case, we defined the arguments as param1 and t_trig1.

To create the synth, write "t 1" then "s sine" to dQ console and click somewhere to create the sine agent. Now select it and move it close to the "out" fx agent we created earlier. If you want to delete your "hardwarein" synth that you crated earlier, just select it and press "del". You should now be hearing a 220hz sine tone with its gain multiplied by 0.2. In the synth definition, we have "(220 + (880 * param1.lag(0.1))" as the freq argument of SinOsc. So when a parameter agent sending the value with the name param1 comes close to the "sine" agent, the frequency will approach to 880 + 220 = 1100. (param agents sends values between 0 and 1 based on its distance with the nearby agent).

To create the parameter agent which is of type 0 by definition, write "t 0"(or type 0) then "param 1" to the dQ console. dQ will now be ready to create a parameter agent. Now make a gesture with your mouse around the sine agent with your mouse(by holding left click). You will observe that the param agent influences the frequency of the sine agent.

Parameter and trigger agents are defined only in dQ, in other words, SC is not really aware of them. They are just sending osc messages when they encounter a synth/fx/chain fx(described later) agent in range.

You can now create a trigger agent that will send a trigger to the t_trig1 argument. To do this, type "t 2" and then "trig 1" to console and record a gesture around sine with your mouse by click-dragging. You should see that, when trig comes into range, it sends a trigger, and you will then see the amplitude of sine rise to 1, then decay to 0.2 again in 0.8 seconds as defined in the synth definition.

Combining synth agents with fx agents is cool, in the example we saw, the fx agent was a simple hardware out synth, that did no processing on its input signal whatsoever. However you can do any kind of signal processing with an fx agent. The limitation is that, you CANNOT chain them. They are terminal.

To make chains with your fx agents, you need fx chain agents, that are, "type 4" agents by definition. dQ controls their inputs as well as their outputs. Here is an example chain agent, that connects its input to its output:

( SynthDef("linker", //does nothing, connects its input to output. { arg inFxBusNo = 16, //As in fx agents outFxBusNo = 1038, //This argument is unique to type 4 agents. //Output is sent to the blackhole bus by default. t_trig100 = 0, fxMul = 0; var free = FreeSelf.kr(t_trig100); //Again, we need to use InFeedback instead of In. var in = InFeedback.ar(inFxBusNo, 2); //In type 4 agents, we use Out.ar to output to //outFxBusNo bus. dQ will handle the routing //of the busses by using these arguments. Out.ar(outFxBusNo, in * fxMul); }).send(s); //type 4(cAgent) )

Chaining fx agents can connect to type 1, 4(themselves), and 5(covered later) agents. To avoid feedbacks, a chaining fx agent searches for nearby agents that are ONLY on its top, visually. Signal flows from top to bottom. To get output from a chain, we need a chainout synth:

( SynthDef("chainout", //can be used to get sound out from a type 4 chain. { arg inFxBusNo = 16, outFxBusNo = 1038, //We won't use this argument here, because //we want the output in hardware //outputs(busses 0 and 1) t_trig100 = 0, fxMul = 0; //We won't also use this argument because this one is //designed to be the last synth on chain. Other agents //residing below this one will modify this argument but //we won't be using it in Out.ar, hence gain will be //constant. var free = FreeSelf.kr(t_trig100); var in = InFeedback.ar(inFxBusNo, 2); //we are omitting fxMul. Out.ar(0, in); }).send(s); //type 4(cAgent) )

Send "linker" and "chainout" synths to server. From dQ console, run "t 4", "s linker" and create two type 4 agents with the name linker. Move one below to the other and verify that they are connected visually. Now move your "sine" synth we created earlier close to the top "linker". They will be connected. Beware here that for sine agent to be connected to our chain, it should be disconnected from the "out" fx agent we connected to it earlier. The visual representation of type 4 agents is a filled circle with a horizontal line passing from its center.

Then create the "chainout" synth by running "t 4", "s chainout" from dQ console. Create and move the chainout agent close to the bottom linker, and they will connect. You should now hear the sine tone on your speakers.

These agents do nothing to the audio. Just connect stuff. Its up to you to do something interesting with them. For example, here is a dandy chorus effect:

( SynthDef("chorus", { arg inFxBusNo = 16, outFxBusNo = 1038, t_trig100 = 0, t_trig1 = 0, fxMul = 0; var free = FreeSelf.kr(t_trig100); var in = InFeedback.ar(inFxBusNo, 2); var nV = 10; //number of voices var delays = Mix.fill(nV,{Pan2.ar(DelayC.ar(in, 0.2, LFNoise2.kr(0.2).range(0, 0.2), nV.reciprocal * 2), LFNoise1.kr(1)); } ); Out.ar(outFxBusNo, delays * fxMul); //type 4(cAgent) }).send(s); )

Send this synth to your server, then create it with dQ by running "t 4" and "s chorus". Then create it on your canvas by clicking to an empty space. If you have the previous chain connected, you will observe that your new chorus agent will not connect itself to anything. To bring it into your chain, break the connections for example from between two linkers we previously connected(by selecting the linker and chainout by right click and dragging then moving them with middle click dragging) and move the chorus in between. Make necessary adjustments by moving stuff around to make the msee each other. You should now hear a cheaply chorused sine tone.

Branching from the middle of the chain is not allowed, and an agent in the middle of the chain does not connect itself to any other agents. However, any number of synth and freesound(covered later) agents can be connected to the TOPMOST agent in chain.

dQ goes online with Freesound:
There is one more type of agent we need to cover, namely "type 5" agents or "FreeSound sampler" agents. You need to have an active internet connection to use them and you need to have the necessary steps at the top of this document completed(adding your username and password to fsampler.py file and sending the FreeSound sampler synths to scserver).

What they do is, you give a tag to dQ, and dQ searches the FreeSound database, then downloads a relevant audio file from the Internet, loads it up into a buffer and the agent starts emitting/playing/looping the downloaded sound file. From this point, it behaves like a type 1 agent(but does not accept parameter and triggers).

To create a type 5 agent, run "t 5" and "s keyword" on dQ console. Substitute keyword with anything you want. When you first create the agent, you will see an unfilled rectangle, meaning no file is downloaded yet. When a file is found and downloaded, the square will fill up, from that point on, you can connect that agent to fx and chaining fx agents. If no match is found in database, or if there is a connection error, you will see a diagonal line over the agent meaning "something has gone wrong". Just delete the agent and try another.

That is all for this tutorial. Hope you find it useful.