# 6 - Configuration
### 6.1. Sending Osc Messages

**Open Sound Control**

Open Sound Control (OSC) is a digital music communication protocol and is becoming more and more prevalent in modern audio software. Applications using OSC will have a server listening for messages from a client – this is how FoxDot communicates with SuperCollider to generate audio. Here’s a quick run through of how to send these messages to other OSC applications from FoxDot.

It’s really simple; you just need to tell FoxDot to “forward” any OSC messages. Let’s say your application is running on the local host on port 12345, here’s the code for connecting to it:

`Server.add_forward("localhost", 12345)`

And that’s it! Any time FoxDot sends an OSC message to SuperCollider, it will also send it to the other OSC application too. These messages are usually sent as a group together called an “OSC Bundle” which contain a message about the note being played, and also a message for each effect being applied. Here’s what the note message looks like:

`[address, synth-name, synth-id, add-action, target-id, arg-1, value-1, arg-2, value-2, ...]`

The “address” is basically the name of the function that the OSC application should process the rest of the message with; for SuperCollider this is usually /s_new and means “trigger synth” and the “synth-name” is name of the SynthDef being triggered. The “synth-id”, “add-action” and “target-id” values relate specifically to SuperCollider so your application can probably ignore these. Then come the arguments used, such as frequency and amplitude, which are written in turn and separated by commas. Here’s what a typical messages might look like

`["/s_new", "pluck", 1001, 1, 0, "freq", 440, "amp", 1, "pan", -1, "sus", 1]`

So a “pluck” synth is creating a note with an amplitude of 1 at a frequency of 440Hz with a sustain of 1 and a panning of -1. The arguments all relate to the names of keyword arguments used by FoxDot.
Other information

If you are getting this error – `FoxDot.lib.OSC3.OSCClientError: while sending: [Errno 111]` Connection refused then please check your network connection settings are correct. On Windows this will be ignored but MacOS and Linux will throw this error every time you want to play a note.

For more information about how OSC messages are handled by SuperCollider, here is a link to a great resource on the server command architecture.

### 6.2. Setting Up Midi

**Introduction**

This section is all about using FoxDot players to sequence musical events using an external MIDI device. This requires the most up-to-date versions of FoxDot and SuperCollider “FoxDot Quark”. You can find out more about keeping updated here.
Sending messages to a MIDI device

The first thing to do is connect your laptop to your MIDI device and make sure the correct drivers are installed – this usually happens automatically but not always. Next, make sure that SuperCollider can “see” the device. To do this, open SuperCollider and run this line of code:

FoxDot.midi

You should then see a message in the “post window” along these lines:

MIDI: device 0 2 -1202759152  (Microsoft GS Wavetable Synth)
MIDI: device 1 3 -1202759144  (USB2.0-MIDI)
MIDI Sources:
    MIDIEndPoint("USB2.0-MIDI", "USB2.0-MIDI")
MIDI Destinations:
    MIDIEndPoint("Microsoft GS Wavetable Synth", "Microsoft GS Wavetable Synth")
    MIDIEndPoint("USB2.0-MIDI", "USB2.0-MIDI")
-> MIDIClient

If not, then please consult the SuperCollider documentation on MIDIClient. This a list of the MIDI devices that SuperCollider (and FoxDot) can send messages to. On Windows (as in the example above) the first device is Microsoft’s internal MIDI synth for Windows and the second is an external device connected by USB (these might have different names depending on the device and connection). By default, FoxDot will send messages to the first MIDI destination (“Microsoft GS Wavetable Synth” in this example) but you can select a different device by running the same code but with the index of the preferred device in brackets. So to select the “USB2.0-MIDI” device you would run:

`FoxDot.midi(1)`

You can now send messages to your MIDI device from FoxDot! To do this, you need to use the MidiOut synth. It operates the same as a normal synth but sends pitch and amplitude messages to a MIDI device e.g.

`p1 >> MidiOut([0,1,2,3,4,5], dur=PDur(3,8), amp=[1,1/2,1/2]).every(6, "stutter", 4, dur=3, oct=6)`

You can specify the MIDI channel as you would do any other attribute e.g. using channel = 1, which defaults to 0.

`p1 >> MidiOut([0,1,2,3], channel = 1)`

Note: Be careful when repeating the same note with the same duration; if a MIDI note-on event is triggered slightly before the MIDI note-off for the previous event, it will be stopped by the note-off. This is a known bug and being looked into.
Synchronising MIDI messages and FoxDot messages

If you are using both FoxDot and your MIDI device, you may notice that the sound events are not in sync. To fix this you need to manually set the Clock.midi_nudge value, which adds a delay to the MIDI messages. Here is some example code to help sync up the messages:

p1 >> MidiOut([0,4])

p2 >> play("x * ")

# Value is usually between 0.15 and 0.25
Clock.midi_nudge = 0.2

When the sounds are in sync they will stay in sync until the next time you start FoxDot, so remember this value!

### 6.3. Using Your Own Synthdefs

**Creating a SynthDef**

While FoxDot does come with its own range of SynthDefs for you to control, you may want to write your own or use one you have already created. This page takes you through how you go about writing a SynthDef to be used with FoxDot. It will require a basic understanding of SuperCollider SynthDefs; if you would like to find out more, you can visit the SuperCollider documentation on the topic.

Let’s start with a very basic SynthDef written in SuperCollider made from a sine wave and a basic percussive envelope. If we’re controlling amplitude and panning as well, it might look something like this:

SynthDef.new(\sine,
    {|amp=1, sus=1, pan=0, freq=0|
        var osc, env;
        osc=SinOsc.ar(freq, mul: amp);
        env=EnvGen.ar(
            Env.perc(attackTime: 0.01, releaseTime: sus),
            doneAction: 2
        );
        osc=(osc * env);
        osc = Pan2.ar(osc, pan);
        Out.ar(0, osc)}).add;

To trigger synth messages in SuperCollider from FoxDot, you just need to give FoxDot a reference to the SynthDef. You can do this by running the following code in FoxDot:

`sine = SynthDef("sine")`

The sine on the left is what FoxDot will refer to the synth as, and the "sine" in brackets on the right is the name of the SynthDef in SuperCollider. They don’t have to have the same name but it makes sense to keep things consistent. Once you have the sine SynthDef in FoxDot, you can use it with a player object just like any other. e.g.

`p1 >> sine([0, 4, 6, 7], dur=1/2)`

However, if you try and use effects in FoxDot, you’ll find it doesn’t work:

`p1 >> sine([0, 4, 6, 7], dur=1/2, shape=0.5, chop=4)`

To be able to “chain” effects you need to make a few adjustments to the SuperCollider SynthDef. First of all you need to be able to supply the SynthDef with a bus argument, which will store the output of the synth as effects are added. Then you need to use In.kr for the freq value (you are actually reading it from a bus, not supplying it directly) and then ReplaceOut.ar instead of Out.ar on the last line so that we write the audio signal out to the effects bus instead of your computer’s audio device. Your new SynthDef should look something like this:

SynthDef.new(\sine,
     {|amp=1, sus=1, pan=0, bus=0, freq=0|
         var osc, env;
         freq = In.kr(bus, 1);
         osc=SinOsc.ar(freq, mul: amp);
         env=EnvGen.ar(
             Env.perc(attackTime: 0.01, releaseTime: sus),
             doneAction: 0
         );
         osc=(osc * env);
         osc = Pan2.ar(osc, pan);
         ReplaceOut.ar(bus, osc)}).add;

**Saving your SynthDef**

If you want to save your SynthDef (or have already saved it) and wish to load it into memory from FoxDot you can use the FileSynthDef class. You will need to name the file the same name as the SynthDef itself. So in our example above, we would need to save it as sine.scd. The file needs to be saved in `FoxDot/osc/scsyndef`, in which you’ll find the other .scd files used by FoxDot. You can find this by going to your Python installation directory then going to `/site-packages/FoxDot/osc/scsyndef`.

To load the SynthDef during a FoxDot session, create the SynthDef and use the `.add()` method to load it into SuperCollider like so:

sine = FileSynthDef("sine")
sine.add()

**Important**

Make sure that any doneAction arguments are set to 0 so that the node isn’t immediately released. Effects such as reverb or echo require the synth not to be released until later. Using a doneAction value of 4 will not free up all of the nodes and will cause SuperCollider to run out of memory – so be careful! Now try running the FoxDot code from above and you should hear the sound with effects applied!

`p1 >> sine([0, 4, 6, 7], dur=1/2, shape=0.5, chop=4)`