#lang scribble/manual
@(require (for-label racket))

@title{Aggregate Device}
@section{categories}
  Platform>macOS (OS X)
 How to access the built-in soundcard on macOS 10.4+@section{related}
  Classes/ServerOptions

@section{note}
 
This information is slightly out-of-date. There is no longer a requirement to set up an aggregate device for making the built-in soundcard work. Although in some situations this feature might still be useful e.g. when combining multiple soundcards into a single device.
::

Since macOS 10.4 (Tiger), the built-in soundcard of the Mac is formally represented as separate input and output devices. On the MacBook for example, there are two input devices (named Built-in Microphone and Built-in Input) and a mutable output device (Built-in Output which appears under the names Line-Out or Internal Speakers in the sound preferences).

In SuperCollider, you specify your sound card in the device field of the link::Classes/ServerOptions::. However, you cannot distinguish between an input and an output device. Therefore, to use your built-in microphone for input and your built-in headphones for output, strong::you need to create a virtual "aggregate" device:: (a virtual device that wraps two or more other devices). If you create an aggregate of your microphone and headphones, you can use this single aggregate device as a soundcard for SuperCollider. You need to set up this aggregate device only once.

To do so, you have to open the Audio MIDI Setup application (in /Applications/Utilities)


@racketblock[
"open -a 'Audio MIDI Setup'".unixCmd; // execute this to launch it
::

- you should do this from an user account with administrator privileges. From the Audio menu choose Open Aggregate Device Editor and click on the Plus button to add a new aggregate device. Double click on its name in the list (by default "Aggregate Device") and use a more specific name, for example "Built-in Audio". Then check the Use column for the devices you want to combine, that is your microphone or line input and the built-in output. Here is would it should look like:

Close the editor and quit the Audio MIDI Setup. Now you need to tell SuperCollider to use your new aggregate device. A good place to do this is your default startup file so that SuperCollider will automatically use the new device every time. The startup file is called ]

@racketblock[startup.rtf:: and is placed in the folder ~/Application Support/SuperCollider/, where "~" stands for your home folder.
If you haven't created such a file yet, create a new folder named SuperCollider in your ~/Application Support/ folder, open a new empty document in SuperCollider and save it as startup.rtf in this new folder (~/Application Support/SuperCollider/startup.rtf).
Add these lines to the startup file:

]

@racketblock[
Server.local.options.device = "Built-in Audio";
Server.internal.options.device = "Built-in Audio";
::

to cover both the localhost server and the internal server. Recompile the SuperCollider library (Cmd+K). Now when booting either server, if all goes well, you should find these lines in SuperCollider's post window:

]

@racketblock[
[...]
"Built-in Audio" Input Device
[...]
"Built-in Audio" Output Device
::

voila!

known issues: QuickTime (as of v7.1) has problems using the aggregate sound device (it will take a few seconds before each sound playback starts). Therefore you probably do not want to use your new aggregate device as your system's default device. Note that when you specify a sound device in SuperCollider's ServerOption, there is no need to use the aggregate device as the system preference's default device.
]