This reference provides information on audio device selection, including platform-specific details.
Specific devices can be selected through an instance of ServerOptions. To access
ServerOptions instance of the default server, you can use
Server.default.options. ServerOptions also allows you to specify other important parameters of the device - the sample rate and hardware buffer size.
By default the server will boot to your system's default audio devices. If you want to explicitly tell the server to use the internal soundcard, you need to specify both input and output device. The following example comes from a MacBook Pro:
In case of a dedicated audio interface, you might need to specify a single device, e.g.
On Windows and macOS you can programmatically obtain a list of available audio devices without booting the server:
One possible reason why a server may fail to boot is a mismatch between input and output devices' sample rates, which may occur when using a different device for input and output (which is the case when using a Mac's internal soundcard). If the server fails to boot due to sample rate mismatch, an error will be posted accordingly.
You should set both input and output devices' sample rate to the same value. You can do this in Audio MIDI Setup:
Sometimes you might want to use multiple devices for input or output. macOS provides a way to combine multiple physical devices into a virtual Aggregate Device. To create one, you have to open the Audio MIDI Setup application (in
/Applications/Utilities). You should do this from an user account with administrator privileges.
Audio Deviceswindow click on the Plus button on the bottom left and choose
Create Aggregate Device.
Usecolumn on the right for the devices you want to combine.
Now you need to tell SuperCollider to use your new aggregate device.
After rebooting the server (
Server.default.reboot) you should see in the post window that it now uses the Aggregate Device instead of system defaults:
[...] "Aggregate Device" Input Device [...] "Aggregate Device" Output Device
Note that when you specify a sound device through SuperCollider's
ServerOptions, there is no need to use the aggregate device as the system's default device.
By default, SuperCollider on Linux uses JACK, and the audio device selection is managed by the JACK server.
ServerOptions cannot override JACK's selection of audio hardware.
The SuperCollider server is considered a JACK client. In the following section, the term client will refer to the SuperCollider server, from the perspective of JACK.
When the server is compiled to use JACK as the audio backend, the
device can be used in two ways: to set the client name to register with JACK:
to use a specific JACK server, as well as set the client name:
nil device is equivalent to
Server.default.options.device = "default:SuperCollider";
The JACK connections can be configured via the environment variables
SC_JACK_DEFAULT_OUTPUTS. These allow SuperCollider to detect system preferences for Jack inputs and outputs to/from the scsynth server.
These variables are written as a string that specifies another jack client or a comma-separated list of jack ports formatted as a string.
If these are not set, SuperCollider will default to connecting SuperCollider's inputs and outputs to your system's inputs and outputs. This is the recommended way of changing the Jack environment variables for SuperCollider from within a SuperCollider script:
As an alternative, these may be also be changed by setting the following environment variables in your .bash_profile, .zsh_profile or similar startup file for your shell:
By default the server will boot to your system's default audio devices using
MME driver (which usually means higher latency).
On Windows there are multiple audio driver APIs (e.g.
ASIO etc.) that can be used to communicate with audio devices. The API (listed before the device name) needs to match between the input and the output, for example:
You can programmatically obtain a list of available audio devices without booting the server:
Partial device name matching is supported in Windows (though not in macOS).
ASIOdevice will likely result in setting the hardware to run at 44100 Hz.
.inDevice, as well as
.outDevice), unless you use ASIO
The following list provides basic reference for different APIs. The most recommended APIs are listed first.
If ASIO driver is available, it is probably the best choice to ensure low input/output latency. ASIO drivers usually provide both inputs and outputs through a single device.
If you are using an internal soundcard or a device which does not come with an ASIO driver, an alternative is to use ASIO4ALL. It is a virtual ASIO driver, communicating with the soundcard using Windows' native APIs. It might provide better performance with built-in soundcards and it should allow for multichannel operation with such devices (if supported by the hardware). Use a web search engine to find a download link.
After installing ASIO4ALL, it can be selected as follows (confirm in the post window when the server boots):