Current Status of the Application:
The current version is the rewrite of an initial prototype that was coded with the processing language. You can still download the old processing version from the main project page. But the old version is not really recommended. During the rewrite, many bugs were fixed and there are some features in the current version that are not present in the prototype. So just grab the current copy and start deQuenching.
You might want to check out the tutorial as the documentation makes things look more complicated than it really is.
1- Setting Things Up and Running
2- Setting Up SuperCollider
3- Theory of Operation
4- Sound Engine
5- Requirements For Your SC Synths
6- What You Need to Add to Your SynthDefs
7- Multislider Views
8- The Console
9- Keyboard Accelerators
10- Future Directions
Setting Things Up and Running:
This software is developed under Os X Leopard and a Universal Binary is provided in the main project page. So if you are using a mac and don't want to get your hands dirty with compiling the code yourself, you can just grab the binary. The important thing to note here is that dQ is an interface for SuperCollider, so in order to hear any kind of audio, you should be using it with SC. It talks to SC with OpenSoundControl.
I haven't tested dQ in any other platforms so to use it with Linux and Windows, you'll need to try to compile it yourself. There is very little os dependent code(i think they are in places where I'm setting the paths, and executing the python script from within the application that connects to FreeSound) so you'll probably need to hack it a bit. You can contact me if you have any questions, or need any pointers. There is a link to the current sources in the main project page. The main application is written in C++ but your system will also need python if you want to utilize the FreeSound integration.
There is one more optional thing you need to do, if you want to use mouse wheel for switching between multislider views. The GLUT library dQ uses has some problems with mouse wheel events, so you need to get the modified GLUT framework from this page and replace it with the one you have in your system. Just grab the binary for your system and copy. If you don't want to use your mouse wheel, you can always use the left and right arrow keys on your keyboard to switch between views without modifying anything.
Setting Up SuperCollider:
There are some little modifications you need to make in the SuperCollider environment to make it work with deQuencher properly. First of all, dQ uses audio busses extensively, so the default number of busses that SC allows(128) will not be enough. In fact, the default blackhole bus dQ uses to route unnecessary audio is bus no 1038 so you need to set this value to 1040. And if you are planning to do some sampling or planning to use FreeSound agents, you should change the maximum realtime memory allowed to be allocated by SC. The commands necessary to do these are:
You can adjust memSize to any value you want, but the default value(8192) won't be enough so be sure to change this too. You can execute these BEFORE booting your server each time, or you can put these lines to your startup.rtf file, so that SuperCollider executes them on each launch automatically.
To use the FreeSound agents, you need to send the supplied "fsplayer_stereo" and "fsplayer_mono" synths in defaults.rtf file(in program folder) to your server. The downloaded sounds from Freesound will be loaded to those synths by dQ. And you will also need a FreeSound account. Open the fsounder.py file with a text editor and fill in the required fields for your username and password, or else, dQ will not be able to do searches and downloads. The fields are at the beginning of the file. Add them between the quotes(""), save and exit.
Theory of Operation:
The interface of dQ consists of a canvas, a multislider and a console. You draw your objects(called as agents from now on) with mouse gestures to the canvas and your gestures are recorded then played back continuously, you can change properties of individual agents with the multisliders and give directives to the software about the initial properties of your next agent from the console.
However you don't absolutely have to rely on gestures in a performance. You can as well place stationary agents on canvas and move them around as needed.
The console is active as long as the program window is focused, you draw your agents on canvas by dragging your left mouse button, you can select them by dragging your right mouse button. In selection mode, you'll see a transparent blue rectangle and the agents within the area covered by this rectangle at the moment you release your right mouse button, will be selected(they will look bigger so you will know which ones are selected). To deselect the agents, simply right click on an empty space on canvas. If there are selected agents, the modifier sliders for the non-selected agents will be locked so you will be able to alter the behavior of selected agents without worrying about the unselected ones. If you want to move/add offset to the origin of motion of selected agents, you should drag with your middle mouse button pressed and selected agents will be affected. If you press delete, the selected agents will be deleted from the canvas.
If you are not using a multibutton mouse, you can get the same functionality by using the shift and option keys while clicking. Holding shift before clicking will allow you to select(substitute for right click) and option clicking will let you move stuff around(substitute for middle click). But I'd suggest you to get a three button mouse to use dQ.
Sound Engine:
The program uses SuperCollider as the sound engine, and communicates with it via OSC. dQ uses reserved parameter and trigger names for your synths defined in SC and to be able to control your synths with dQ, you need to make sure that your synths are ordered to receive and interpret messages sent by dQ. Before seeing how it is done in SC, we need to look at the agent types defined in dQ. In dQ, you are able to create:
- Parameter agents(type 0)
- Synth agents(type 1)
- Trigger agents(type 2)
- Fx agents(type 3)
- Chaining Fx agents(type 4)
- FreeSound sampler agents(type 5)
From the technical perspective of SC, synths, fxs, chaining fxs and FreeSound sampler agents are of the same type, that is, they are all defined SynthDefs on scserver. But from the perspective of dQ, however, they have different properties. For dQ, Synths have parameter-trigger inputs and audio outputs. Fx agents have Audio-parameter-trigger inputs and audio outputs, but they can't be chained. FreeSound sampler agents only emit audio and can be connected to fx or chaining fx agents. These limitations are from the perspective of dQ, in other words, your Synths can also have audio inputs defined from within SC, but these inputs will not be controlled nor altered by dQ, as it won't be aware of them. dQ allocates busses starting from bus no 16, so if you use those busses by yourself on the same server, they will clash. Ideally, dQ should run on its own server. I haven't tried it yet.
Requirements For Your SC Synths:
Getting SC to run with dQ is easy. There are some defined variables that are controlled by dQ, and when you include them in your synth definitions, you basically render them controllable with dQ. Here is a quick list, we'll see how exactly they should be used in a while. Keep reading.
- fxBusNo (each synth and FreeSound sampler can output audio to an fx or a chaining fx agent, this argument is used for specifying the correct bus number for output to an fx)
- fxMul (this argument is used for the dry-wet ratio for the bounding fx. When the fx, or a chaining fx agent comes closer to the synth or fs sampler agent, this argument approaches to 1, if there are no nearby fx agent, this is 0)
- t_trig100 (this is a trigger, when an agent is deleted from canvas, the corresponding synth running in SC is sent a trigger to this argument. You should handle this trigger with a "doneAction: 2" to free the synth from your SC server, or it will be orphaned)
- param[x] (parameters are optional. If you want a parameter agent to affect the behavior of a synth, you need to handle that parameter from within your synth. When a parameter agent comes close, this parameter approaches to 1. Otherwise it is 0. parameters are defined as: param0, param1, param42 etc...)
- t_trig[x] (same as param[x], but these are used as triggers. When a trig agent comes close enough to an agent, it sends a trigger.
- inFxBusNo (this one is used by chaining fx agents. Since they have inputs to receive and outputs to pass on, a single fxBusNo variable would not suffice. this defines the input bus of the chaining fx agent.)
- outfxBusNo (this one is also used by chaining fx agents. Since they have inputs to receive and outputs to pass on, a single fxBusNo variable would not suffice. this defines the output bus of the chaining fx agent.)
For example, when you are creating an synth agent, you'll need to define an output via Out.ar for outputting to a nearby fx. This Out.ar should be separate from your normal output that directs to your sound card. Should be defined as this:
The appropriate busses and fxMul multiplier for your synth will be controlled by dQ. We'll see in detail, what exactly we need to add to our synths to make them work with dQ later in this document.
Also, a simple example demonstrating all these in a simple scenario can be found here in the tutorial.
Parameter and trigger agents are defined in dQ only, they will just send messages to targets defined by their names. Parameters are in param[x] format where [x] is an unique number(you can have more than one parameter agent sharing the same name) and trigger agents are named in t_trig[x] format.
What Exactly You Need to Add:
Parameter agents(type 0): These are defined within dQ. If you have arguments defined in your Synth definitions in SC with names like param1, param2, param100, param200 etc... dQ will control them when this agents come close to a sound producing agent. They connect and send data to type 1, 3 and 4 agents.
Synth agents(type 1): These agents have no audio inputs, but have outputs. To make your synths compatible with dq, you need to add these:
... to the beginning of your synth definitions. And you'll want dQ to route its output to a correct target so you will need to add this:
... where sound is the variable that holds the sound your synth generates. These agents connect to type 0, 2, 3 and 4 agents.
Trigger agents(type 2): These are like parameter agents. They are defined only in dQ. If you synth has arguments like t_trig1, t_trig10, t_trig42 ...etc, dQ will send triggers to them when a trigger agent is in their range. t_trig100 trigger is reserved for freeing the synths from server. When you delete an agent from dQ canvas, dQ will send a t_trig100 trigger to the corresponding synth, and you need to take care of that trigger with "doneAction: 2", or else, that synth will be orphaned. They connect and send data to type 1, 3 and 4 agents.
Fx agents(type 3): These agents are just like synth agents, the difference between them is that dQ cares about an fx agents inputs, and doesn't care about the output. When an fxAgent comes close to a sound generating agent, it routes that agent to its own input. You are responsible for routing that input to your sound cards. Here is a template fxAgent you can use to start with:
Between InFeedback.ar and Out.ar, you can do whatever you want with the audio. Out.ar will output it to your soundcard. So fxAgents are TERMINAL. You cannot chain them. They connect to type 1 and 5 agents to route audio. To use fx chains, you need to use chaining fx agents.
Chaining Fx agents(type 4): These agents are like fxAgents, the difference is that, well, you can chain them before sending to an output. Here is a template chaining agent that links its input to its output. Including all the variables you need.
You can see that inFxBusNo and outFxBusNo arguments are needed in type 4 agents. The bus number 1038 is called the "blackhole" bus, if a synth on SC side is not connected to anything, its output is sent to this blackhole bus so that it does not overwrite anything we want to hear with silence. To route the chains output to your sound card, you will need to have a chainout synth that will output to busses 0 and 1 at some point. They route audio to and from type 1, 4 and 5 agents.
FreeSound sample agents(type 5): The only type of agents with guaranteed fun. You don't need to define anything yourself for these in SC, just load the supplied set of synths in the downloaded package and it will work. These agents use their name as a keyword/tag, connect to FreeSound, download a file with that tag/name, load it to a buffer and start emitting/looping it. You can then connect them to fx agents or chaining fx agents. When you create a type 5 agent, you'll see an unfilled square at first. When dQ manages to download a relevant sound and load it to a buffer, the square will be filled with its own color. If download fails, you'll see a diagonal line over it, meaning "something has gone bad". It won't retry, so you can delete it and try creating another. Internally, when you create a type 5 agent, dQ runs a python script to search and download a file from FreeSound. The script will notify dQ and dQ will notify SC. For this to work, you need to have a FreeSound account, and you need to enter your username and password to the python script supplied, as mentioned in "setting things up and running" section of the documentation.
Multislider Views:
Above the console, there is a multislider view that lets you modify various properties of currently active agents. They are populated dynamically so number of sliders will always be equal to number of agents on canvas, each with matching colors to their master agents. There are 4 different views, you can switch between them using your mouse wheel or using your computers left-right arrows. Here are the views and their explanations:
- Scale view: This is the default view, scales the movement of the recorded mouse gesture. In other words, it will scale the amplitude of the recorded gesture.
- Bond distance scaling view: In dQ, agents interact with each other based on proximity. When an agent comes close to another within a specified distance, a bond is created between them and they start to share information. In this view, you can set the bounds of "sensing area" of an individual agent. This only affects the active agents. Type 1 and 5 are passive.
- Frame clipping view: In this view, you can decide to chop off a percentage of the recording gesture from its ends. So If your agent traverses a path consisting of 100 frames, moving this slider to halfway down for an individual agent will set the loop point of movement to frame number 50. Moving it all the way down will force the agent to stay stationery.
- Noise view: Simply adds 5px random x and y offset to movement of an agent.
The Console:
Before creating an agent, you need to tell dQ what type of agent you are willing to create, and the name/parameter number of the agent. You can also set other parameters before creating agents, and all these settings will be valid for all future agents about to be created, until you change them again with your console. You can also use keyboard accelerators for various tasks, so that you will have to do minimal typing. But first, the harder way, here is the command reference:
type: To tell dQ, what kind of agent you are willing to create, you use the type command, following the agent type as an integer. The defined types are as follows:
- type 0: parameter agent
- type 1: synth agent
- type 2: trigger agent
- type 3: fx agent agent
- type 4: chaining fx agent
- type 5: FreeSound sampler agent
So, to change the type for your next agent to a synth, you need to write "type 1" to the console(without the quotes) and press return. You should get a response telling "Type set to 1...". you can also type the "t" letter as a shortcut instead of "type".
param/trig: If you are creating a parameter or trigger agent, you'll want to tell dQ which parameter or trigger you want to control. Write "param" or "trig" to console followed by an integer to change the parameter/trigger id number for the following agents. For example if you write "param 12", your parameter object will control the "param12" argument of the synth/fx when it comes close to one. You can also type "p" as a shortcut, instead of "param" or "trig".
synth: If you are creating a synth or fx agent, you'll want to tell dQ which of the defined synths on scserver you want to create. This can be done as simply as writing "synth mysynthname" on console and pressing return. the following synth or fx agents will try to load a synth named "mysynthname" if it is loaded on scserver. If you are about the create a type 5(FreeSounder) agent, the synthname is treated as a keyword to search in the FreeSound database. You can also type "s" instead of "synth" as a shortcut.
b: The letter "b" followed by an integer will set the minimum distance(in pixels) for an agent to connect and affect another agent. Changes the proximity range. This value then can be scaled with the corresponding multislider view.
q: The letter "q" followed by an integer will set the maximum number of frames to be recorded. If you want some agents to move in sync and in phase, you can set this value to a fixed number and the gesture recording will stop when this number is reached. if you set 0, that means unlimited, which is the default value.
z: The letter "z" can be followed by either 0 or 1. This variable affects parameter agents only. If you set z to 1, when a parameter agent loses its connection with a synth/fx agent, the parameter agent will send "0" to the disconnected agent. There is this option because this "resetting when disconnecting" does not happen automatically in most cases. For example, if a parameter agent gets out of the scope of a synth agent far too quickly, because of the limited frame-rate of the opengl window, a value between 0 and 1 might get stuck in the synth. By setting z to 1, you make sure that when a bond between a synth and parameter is lost, the value "0" is sent to that synth for that parameter. Sending zeroes is the default so you probably won't need to change this value.
Keyboard Accelerators
In a live performance situation, you probably wouldn't want to do much typing. This is where keyboard shortcuts become handy. With dQ, you can load a text file defining bindings between your computer keyboards keys and your synth definitions. The file format is very simple: each line in the file should contain the key, synth type and synth name in this order. You need to write "end" without the quotes to the end of the file to be safe. An example accelerator file could look like this:
Say, we've saved this file as keys.txt in the program folder. To use the accelerators, you need to write "accel keys.txt" to the dQ console without the quotes and press enter. You should see a confirmation message on console saying that the file is successfully loaded. Now you can switch between normal typing mode and accelerators mode by pressing F2. In accelerators mode, with this file, when you press "l", your next agent will be a type 4(chaining fx agent) linker(this is the synthname that should be loaded in scserver). If you press 0, it will be a type 0(parameter) agent sending values to param1. Be aware that at this point not much error checking is done over the file so you need to make sure there are no duplicates, the second parameter in a line is always an integer etc...
Future Directions...
I've started developing dQ for my own musical needs as it hints possible solutions to my problems about music created with live sequencing. These problems are of course germinating from my own understanding of music with a specific aesthetic, and I failed to stumble upon a tool that I would feel comfortable working with.
deQuencher...
- is context independent,
- allows improvisation, in a very natural fashion
- allows one to stay within the "moment" most of the time during a performance,
- lets one to perform non-linearly, yet still makes things sound coherent from a humanly perspective,
- has vast potential for serendipities,
- is free software.
There is a very huge room for improvement as it is kind of a toddler right now. Here is a small list of thing I'd like to solve and/or add:
- While it feels natural for the average computer user, dependence on mouse and keyboard is lame. I'd really like to collaborate with other people that would help me to control such a system with better interfaces. Better interfacing would also allow collaborative performances with dQ. I'm planning to implement a multi-touch surface interface for the project.
- I'd like to add a generalized OSC support so one would not have to use it with SuperCollider. And I'd like to add some kind of midi support for controlling applications that do not support OSC. I'd need to find ways of adding these without cluttering the workspace or without making usage difficult in live performance situations.
- Saving and loading of performances!
- Networking is also a must. Multiple users sharing the same canvas to make music over a network...
- ... ...
If you are using deQuencher, I'd be very happy to hear about what you are doing with it. Comments, suggestions and flames are always welcome.
