Q: How do I install FoxDot?
A: Check out the install guide here: http://foxdot.org/index.php/installation/
Q. When trying to use pip install FoxDot, why do I get an error "pip is not a recognised command" or "no command 'pip' found"?
A. If you don't have Python 2.7 installed, you need to make sure you do that first. Windows - If you have installed Python and still get this error, it means Python (and 'pip') are not on your system path; this is usually done automatically at install but sometimes requires it to be added manually. To add it to your path in Windows, first find where Python is installed (usually C:/Python27) and copy that location and the location of the folder named 'Scripts'. Then go to Windows Explorer and right click on 'My Computer' / 'This PC' and go to 'Properties'. From there go to 'Advanced System Settings' and press the button labelled 'Environment Variables'. In the box marked 'User Variables for...' look for a variable called PATH in all capitals - if it does not exist then create it and add the Python locations from before separated with a semi-colon so it looks something like this:
C:\Python27\Scripts;C:\Python27\
If it does exist, just edit it and add the locations to any other file location that's there but make sure you separate them with a semi-colon.
Q. pip wasn't installed when I installed Python - can I install FoxDot without it?
A. Sure! You can download the .zip from the GitHub page and use that to install it. Once download, extract the contents and use you command line interface to navigate to where it's extracted (usually cd path/to/file). Once there type:
python setup.py install
This should install FoxDot in the same way pip install FoxDot would. You can run FoxDot going to your command line interface and running python -m FoxDot as you would normally.
Q. SuperCollider won't download the FoxDot Quark / the FoxDot Quark was installed correctly but running FoxDot.start raises an error: Class not defined. How do I fix this?
A. You can download and run the SuperCollider code from this link: http://foxdot.org/wp-content/uploads/foxdot.scd. Run the code by opening the file and pressing Ctrl+Return once opened. SuperCollider should then begin listening for messages from FoxDot. This problem occurs when using SuperCollider 3.6 or earlier and my first suggestion would be to upgrade to a newer version, such as 3.8. If this is not possible, if you're on some Linux distributions for example, then the steps below describe a more permanent fix and can be used to install other SuperCollider Quark files:
- Manually download / clone the Quark from the GitHub repository - https://github.com/Qirky/FoxDotQuark - you can find other SuperCollider Quark information at https://github.com/supercollider-quarks/quarks.
- Put the .sc file - FoxDot.sc in this case - in the SuperCollider class library directory
- Linux / Mac: /usr/share/SuperCollider/SCClassLibrary/
- Windows: C:/Program Files/SuperCollider-x.x.x/SCClassLibrary
- Recompile the class library by going to Language -> Recompile Class Library or pressing Ctrl+Shift+L
Q: FoxDot Quark installed correctly but I still don't sound output (using jack). The QjackCtl Connect window's Audio tab shows no outputs available.
A: Go to QjackCtl's Setup window and change the "output" setting until you get the right device for your soundcard. One thing to note, if SuperCollider / Jack fails then you will need to restart both SuperCollider and FoxDot in that order.
Q: How do I install on a Raspberry Pi?
A: You can install FoxDot as you would on any other machine using the installation guide but you will need to take some extra steps when installing SuperCollider. Two useful guides for installing SuperCollider on a Raspberry Pi can be found here:
- https://supercollider.github.io/development/building-raspberrypi.html
- https://github.com/redFrik/supercolliderStandaloneRPI2/
Using FoxDot
Q: How do I add my own samples?
A: You can open the directory where FoxDot stores audio files by opening the editor and going to "Help & Settings" then "Open Samples Folder". In here you'll find a series of folders with one-character names. Each of these characters refers to the character used to play the samples in FoxDot. Just add your audio file to the folder of your choice and restart FoxDot. For example you want to add a file called new.wav to be played using the upper case "N" character, add your file to the /snd/n/upper/ folder. If there is already a file in there, then you can play your audio file by specifying it with the sample keyword in FoxDot like so:
p1 >> play("N", sample=1)
Q: How do I use my own SynthDefs?
A: If you have a SynthDef in SuperCollider you want to use from FoxDot, you just need to give FoxDot a reference to it by initiating a FoxDot SynthDef object. If your SynthDef is called \mySynth, for example, you would create the reference like so:
mySynth = SynthDef("mySynth")
It's good practice to use the same variable name as the string given. If your custom SynthDef has arguments, just specify them as you would with any other FoxDot SynthDef:
p1 >> mySynth(new_arg=[0,10,100])
Q: How do I change the colour scheme?
A: Currently, you can change the colour-scheme by editing the configuration file in FoxDot, which can be accessed from the GUI by going to "Help & Settings" then "Open config file (advanced)".
Q: How do I add sharps / flats in a melody?
Right now if you want to add a sharp or flat to the pitch of you can specify the pitch as a floating point number. e.g. 0.5 would be C# in the default scale. However if you specify a value between two pitches separated by only 1 semitone, you'll get a microtonal value between the two. For instance using a pitch value of 2.5 in the default scale gives you the note between E and F where there is no middle semitone.
You can also use the pshift keyword argument to shift the note a number of semitones (this can also be used with the play synth to create melodic sequences with samples). For example, the melody created with the code below would be non-trivial to recreate without pshift (see second line):
# Use pshift to increase every third note by a semitone so we play the flat 7th p1 >> pluck(var([0,3,4,3]) + [0, 2, 2, 2], pshift=[0,0,1,0])Using floating points to play a “sharp” (flat 7th)
p2 >> blip([[0, 4], [2, 6], [3, 7], [2, 6], 3, 5, 5.5, 5])
Q: FoxDot uses a lot of my CPU, how do I decrease this?
FoxDot schedules everything using a continually running loop in the background and sleeps for 0.0001 seconds at every loop to avoid taking up all of the CPU. This does still take up a fairly large chunk. You can change how long FoxDot sleeps for (and therefore decrease the number of loop iterations per second) to decrease the amount of CPU usage. You need to change the Clock.sleep_time variable like so:
Clock.sleep_time = 0.05However, the draw back is that note durations will need to be larger than this value or else they will be scheduled late and you'll get lots of jitter and "late" messages in SuperCollider. For example, running the code below with a sleep_time of 0.05 is fine because 1/8 beat at 120 bpm is 0.0625, which is larger than the sleep time:
p1 >> play("x-", dur=1/8)Changing the duration to 1/16 however, doesn't actually play the samples at 1/16 beat, only as fast as the sleep_time allows it and you'll see lots of "late" messages being displayed in the SuperCollider post window. You can see how long a duration lasts in seconds by running:
print(Clock.beat_dur(1/16))This example returns 0.03125, which is less than our given sleep_time, and so does not function correctly. Increase the Clock.sleep_time value to decrease CPU usage but make sure you set the duration for your players high enough to be scheduled properly.
Troubleshooting Bugs and Errors
ERROR: server failed to start in SuperCollider when starting the FoxDot quark
This is an issue with SuperCollider as opposed to FoxDot and could be happening for a number of reasons. One possible cause could be that there is another application on your machine running on ports 57110 or 57120 (those used by SuperCollider).
In SuperCollider FoxDot.start gives me ERROR: Message 'activate' not understood.
This is caused when you don't have the BatLib quark installed in SuperCollider. Install this by running the command include("BatLib") in SuperCollider and try starting the FoxDot quark again. If you don't have "git" installed (a useful program for managing installing open-source applications) then you can use the following code in SuperCollider instead:
Quarks.install("https://github.com/supercollider-quarks/BatLib.git")
ImportError: DLL load failed %1 is not a valid Win32 Application on Windows
This is caused when you are running a 32-bit version of Python on a 64-bit machine. Make sure you are running the correct version of Python for your system. Typing python into your terminal and pressing enter will enter the interpreter mode and will display the version info.
ImportError: No module named tkinter
The Tkinter libraries are usually packaged together with the standard distribution of Python but you'll get this error if this is not the case. You can find detailed instructions on installing Tkinter for Python here: http://www.tkdocs.com/tutorial/install.html. It's often the case of re-installing Python or running a simple command from your terminal.
SuperCollider: Buffer UGen channel mismatch: expected 2, yet buffer has 1 channels
This is caused when SuperCollider reads an audio file and is expecting it to be stereo but it's actually mono. It will treat it the same and it will play back fine but you'll get this warning message frequently. It's a known issue and is being investigated.
[Errno 61] Connection Refused
This means that Python can't properly connect with SuperCollider. Make sure you have run "FoxDot.start" in SuperCollider and that the server has booted correctly (look for the green numbers in the bottom right of your screen). If you are using Linux/Mac OS you may need to install Jack Audio for SuperCollider to work properly.
Getting Started
Q: How do I install FoxDot?
A: Check out the install guide here: http://foxdot.org/index.php/installation/
Q. When trying to use pip install FoxDot, why do I get an error "pip is not a recognised command" or "no command 'pip' found"?
A. If you don't have Python 2.7 installed, you need to make sure you do that first. Windows - If you have installed Python and still get this error, it means Python (and 'pip') are not on your system path; this is usually done automatically at install but sometimes requires it to be added manually. To add it to your path in Windows, first find where Python is installed (usually C:/Python27) and copy that location and the location of the folder named 'Scripts'. Then go to Windows Explorer and right click on 'My Computer' / 'This PC' and go to 'Properties'. From there go to 'Advanced System Settings' and press the button labelled 'Environment Variables'. In the box marked 'User Variables for...' look for a variable called PATH in all capitals - if it does not exist then create it and add the Python locations from before separated with a semi-colon so it looks something like this:
C:\Python27\Scripts;C:\Python27\
If it does exist, just edit it and add the locations to any other file location that's there but make sure you separate them with a semi-colon.
Q. pip wasn't installed when I installed Python - can I install FoxDot without it?
A. Sure! You can download the .zip from the GitHub page and use that to install it. Once download, extract the contents and use you command line interface to navigate to where it's extracted (usually cd path/to/file). Once there type:
python setup.py install
This should install FoxDot in the same way pip install FoxDot would. You can run FoxDot going to your command line interface and running python -m FoxDot as you would normally.
Q. SuperCollider won't download the FoxDot Quark / the FoxDot Quark was installed correctly but running FoxDot.start raises an error: Class not defined. How do I fix this?
A. You can download and run the SuperCollider code from this link: http://foxdot.org/wp-content/uploads/foxdot.scd. Run the code by opening the file and pressing Ctrl+Return once opened. SuperCollider should then begin listening for messages from FoxDot. This problem occurs when using SuperCollider 3.6 or earlier and my first suggestion would be to upgrade to a newer version, such as 3.8. If this is not possible, if you're on some Linux distributions for example, then the steps below describe a more permanent fix and can be used to install other SuperCollider Quark files:
- Manually download / clone the Quark from the GitHub repository - https://github.com/Qirky/FoxDotQuark - you can find other SuperCollider Quark information at https://github.com/supercollider-quarks/quarks.
- Put the .sc file - FoxDot.sc in this case - in the SuperCollider class library directory
- Linux / Mac: /usr/share/SuperCollider/SCClassLibrary/
- Windows: C:/Program Files/SuperCollider-x.x.x/SCClassLibrary
- Recompile the class library by going to Language -> Recompile Class Library or pressing Ctrl+Shift+L
Q: FoxDot Quark installed correctly but I still don't sound output (using jack). The QjackCtl Connect window's Audio tab shows no outputs available.
A: Go to QjackCtl's Setup window and change the "output" setting until you get the right device for your soundcard. One thing to note, if SuperCollider / Jack fails then you will need to restart both SuperCollider and FoxDot in that order.
Q: How do I install on a Raspberry Pi?
A: You can install FoxDot as you would on any other machine using the installation guide but you will need to take some extra steps when installing SuperCollider. Two useful guides for installing SuperCollider on a Raspberry Pi can be found here:
- https://supercollider.github.io/development/building-raspberrypi.html
- https://github.com/redFrik/supercolliderStandaloneRPI2/
Using FoxDot
Q: How do I add my own samples?
A: You can open the directory where FoxDot stores audio files by opening the editor and going to "Help & Settings" then "Open Samples Folder". In here you'll find a series of folders with one-character names. Each of these characters refers to the character used to play the samples in FoxDot. Just add your audio file to the folder of your choice and restart FoxDot. For example you want to add a file called new.wav to be played using the upper case "N" character, add your file to the /snd/n/upper/ folder. If there is already a file in there, then you can play your audio file by specifying it with the sample keyword in FoxDot like so:
p1 >> play("N", sample=1)
Q: How do I use my own SynthDefs?
A: If you have a SynthDef in SuperCollider you want to use from FoxDot, you just need to give FoxDot a reference to it by initiating a FoxDot SynthDef object. If your SynthDef is called \mySynth, for example, you would create the reference like so:
mySynth = SynthDef("mySynth")
It's good practice to use the same variable name as the string given. If your custom SynthDef has arguments, just specify them as you would with any other FoxDot SynthDef:
p1 >> mySynth(new_arg=[0,10,100])
Q: How do I change the colour scheme?
A: Currently, you can change the colour-scheme by editing the configuration file in FoxDot, which can be accessed from the GUI by going to "Help & Settings" then "Open config file (advanced)".
Q: How do I add sharps / flats in a melody?
Right now if you want to add a sharp or flat to the pitch of you can specify the pitch as a floating point number. e.g. 0.5 would be C# in the default scale. However if you specify a value between two pitches separated by only 1 semitone, you'll get a microtonal value between the two. For instance using a pitch value of 2.5 in the default scale gives you the note between E and F where there is no middle semitone.
You can also use the pshift keyword argument to shift the note a number of semitones (this can also be used with the play synth to create melodic sequences with samples). For example, the melody created with the code below would be non-trivial to recreate without pshift (see second line):
# Use pshift to increase every third note by a semitone so we play the flat 7th p1 >> pluck(var([0,3,4,3]) + [0, 2, 2, 2], pshift=[0,0,1,0])Using floating points to play a “sharp” (flat 7th)
p2 >> blip([[0, 4], [2, 6], [3, 7], [2, 6], 3, 5, 5.5, 5])
Q: FoxDot uses a lot of my CPU, how do I decrease this?
FoxDot schedules everything using a continually running loop in the background and sleeps for 0.0001 seconds at every loop to avoid taking up all of the CPU. This does still take up a fairly large chunk. You can change how long FoxDot sleeps for (and therefore decrease the number of loop iterations per second) to decrease the amount of CPU usage. You need to change the Clock.sleep_time variable like so:
Clock.sleep_time = 0.05However, the draw back is that note durations will need to be larger than this value or else they will be scheduled late and you'll get lots of jitter and "late" messages in SuperCollider. For example, running the code below with a sleep_time of 0.05 is fine because 1/8 beat at 120 bpm is 0.0625, which is larger than the sleep time:
p1 >> play("x-", dur=1/8)Changing the duration to 1/16 however, doesn't actually play the samples at 1/16 beat, only as fast as the sleep_time allows it and you'll see lots of "late" messages being displayed in the SuperCollider post window. You can see how long a duration lasts in seconds by running:
print(Clock.beat_dur(1/16))This example returns 0.03125, which is less than our given sleep_time, and so does not function correctly. Increase the Clock.sleep_time value to decrease CPU usage but make sure you set the duration for your players high enough to be scheduled properly.
Troubleshooting Bugs and Errors
ERROR: server failed to start in SuperCollider when starting the FoxDot quark
This is an issue with SuperCollider as opposed to FoxDot and could be happening for a number of reasons. One possible cause could be that there is another application on your machine running on ports 57110 or 57120 (those used by SuperCollider).
In SuperCollider FoxDot.start gives me ERROR: Message 'activate' not understood.
This is caused when you don't have the BatLib quark installed in SuperCollider. Install this by running the command include("BatLib") in SuperCollider and try starting the FoxDot quark again. If you don't have "git" installed (a useful program for managing installing open-source applications) then you can use the following code in SuperCollider instead:
Quarks.install("https://github.com/supercollider-quarks/BatLib.git")
ImportError: DLL load failed %1 is not a valid Win32 Application on Windows
This is caused when you are running a 32-bit version of Python on a 64-bit machine. Make sure you are running the correct version of Python for your system. Typing python into your terminal and pressing enter will enter the interpreter mode and will display the version info.
ImportError: No module named tkinter
The Tkinter libraries are usually packaged together with the standard distribution of Python but you'll get this error if this is not the case. You can find detailed instructions on installing Tkinter for Python here: http://www.tkdocs.com/tutorial/install.html. It's often the case of re-installing Python or running a simple command from your terminal.
SuperCollider: Buffer UGen channel mismatch: expected 2, yet buffer has 1 channels
This is caused when SuperCollider reads an audio file and is expecting it to be stereo but it's actually mono. It will treat it the same and it will play back fine but you'll get this warning message frequently. It's a known issue and is being investigated.
[Errno 61] Connection Refused
This means that Python can't properly connect with SuperCollider. Make sure you have run "FoxDot.start" in SuperCollider and that the server has booted correctly (look for the green numbers in the bottom right of your screen). If you are using Linux/Mac OS you may need to install Jack Audio for SuperCollider to work properly.
