Audio device selection:
Filter:
Reference | Server

Audio device selection

A reference for making audio device selection

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.

NOTE: Device selection won't take effect until the server is (re)booted.

macOS

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:

Sample rate mismatch

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:

Aggregate device

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.

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.

Linux

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.

Setup with JACK server

NOTE: 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 ServerOption's device can be used in two ways:

A nil device is equivalent to Server.default.options.device = "default:SuperCollider";

The JACK connections can be configured via the environment variables SC_JACK_DEFAULT_INPUTS and SC_JACK_DEFAULT_OUTPUTS. The format is either a string that specifies another jack client or a comma-separated list of jack ports.

Windows

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. MME, WASAPI, 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).

Choosing the device and the API

The following list provides basic reference for different APIs. The most recommended APIs are listed first.

List of available APIs

ASIO
  • Maximum channel count: Supports an arbitrary number of input/output channels, if supported by the hardware
  • Typical latency: Low
  • Caveats: Dedicated ASIO driver needs to be provided by the audio device's manufacturer; this is common for most (semi-)professional interfaces, but not necessarily for internal soundcards
  • More info: Designed for pro-audio devices; control over sampling rate and hardware buffer size is usually provided by the driver's control panel (i.e. not settable by SuperCollider); ASIO stands for Audio Stream Input/Output and was developed by Steinberg

WASAPI
  • Maximum channel count: Usually supports mono or stereo only
  • Typical latency: Low
  • Caveats: If the requested sample rate is different than the device's sample rate, the server will not boot
  • More info: WASAPI stands for Windows Audio Session API and is the most modern Windows audio API

WDM-KS
  • Maximum channel count: Usually supports mono or stereo only
  • Typical latency: Low
  • Caveats: On some systems SuperCollider will prevent other applications from using the audio device when using this API
  • More info: WDM-KS stands for Windows Driver Model Kernel Streaming. It was the first native Windows API providing reasonably low latency

DirectSound
  • Maximum channel count: Usually supports mono or stereo only
  • Typical latency: Moderate/high
  • Caveats: It is an older API and typically provides worse performance than the newer ones
  • More info: DirectSound is part of DirectX and was originally created with game audio in mind

MME
  • Maximum channel count: Usually supports mono or stereo only
  • Typical latency: High
  • Caveats: It is the oldest API on this list; it is chosen by default if the user does not specify which device to use
  • More info: This API might work out-of-the-box, but choosing a newer one instead will usually provide better performance; MME stands for Multimedia Extension (for Windows 3.0)

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.

NOTE: On Windows, ASIO driver is likely the only option for multichannel operation (allowing to use more than 2 inputs/outputs simultaneously).

ASIO4ALL

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.

NOTE: ASIO4ALL will usually not provide a better performance than a dedicated ASIO driver.

After installing ASIO4ALL, it can be selected as follows (confirm in the post window when the server boots):