# Mac Audio Setup — Routing System Audio into Conductør

## Why this is needed

macOS has no built-in way to let an app listen to the audio your system is already playing. On Linux that's `pulseaudio monitor`; on Windows it's `WASAPI loopback`. On a Mac, we have to build the loopback ourselves using a free virtual audio driver called **BlackHole** and a **Multi-Output Device** that plays to your speakers *and* BlackHole at the same time.

Once this is set up, you do it once. Conductør will remember it forever.

## What you need

- **BlackHole 2ch** — a free MIT-licensed virtual audio driver
- **Audio MIDI Setup** — already installed on your Mac (`/Applications/Utilities/`)
- **About 5 minutes**

---

## Step 1 — Install BlackHole

1. Go to <https://existential.audio/blackhole/>
2. Download the **2ch** installer (the one most guides use — 16ch is overkill)
3. Run the `.pkg` installer; you'll be prompted for your password
4. You may need to restart the Music/Spotify/browser app you plan to play audio from (BlackHole won't appear as an output option until the app refreshes its audio device list)

You don't need to restart your Mac. Paid alternative: **Loopback.app** by Rogue Amoeba ($109) has a nicer UI, but BlackHole does the same job for $0.

## Step 2 — Create a Multi-Output Device

A Multi-Output Device sends audio to multiple destinations at once. We want audio going to your **speakers/headphones** (so you can hear it) *and* **BlackHole** (so Conductør can see it).

1. Open **Audio MIDI Setup** (spotlight → "Audio MIDI Setup" or `/Applications/Utilities/Audio MIDI Setup.app`)
2. In the device list (left pane), click the **+** at the bottom-left and pick **Create Multi-Output Device**
3. In the right pane, a list of devices appears with checkboxes. Check **both**:
   - Your speakers/headphones (e.g. "MacBook Air Speakers", "External Headphones", AirPods, etc.)
   - **BlackHole 2ch**
4. **Master Device** (dropdown near the top right) — set this to your speakers/headphones (**not** BlackHole). This controls which device drives the audio clock
5. **Drift Correction** — check the box next to **BlackHole 2ch** (not your speakers). This keeps the two devices in sync
6. Rename the device if you want (double-click its name in the left pane) — e.g. "Conductør Out"

## Step 3 — Set the Multi-Output Device as system output

Audio MIDI Setup *creates* the device; System Settings decides whether to *use* it.

1. Open **System Settings → Sound**
2. Under the **Output** tab, click your new Multi-Output Device
3. Play something to verify you still hear audio

If you **can't hear anything**: go back to Audio MIDI Setup and confirm your speakers are checked *and* they're set as Master Device. If your speakers aren't master, playback often goes silent.

## Step 4 — Point Conductør at BlackHole

1. Back in Conductør's dashboard, scroll to **Settings → Audio Input**
2. Pick **BlackHole 2ch** from the dropdown
3. Click **Save**

The input-level meter underneath should start moving when audio plays.

If it doesn't: click the **Test Audio** button. Conductør will play a short tone and confirm whether the signal makes it back around the loop.

---

## Troubleshooting

**No sound after switching output to Multi-Output Device.** Your Master Device is probably set to BlackHole instead of your speakers. Open Audio MIDI Setup, select the Multi-Output Device, change Master Device to your speakers.

**Conductør sees no signal but audio is playing.** Open System Settings → Sound → Output. The active output must be the Multi-Output Device, not your speakers directly. This is the single most common issue.

**Switched headphones and now the Multi-Output Device plays to nothing.** A Multi-Output Device binds to *specific* devices. If your original speakers went away (AirPods disconnected, dock unplugged), the multi-output partially fails. Open Audio MIDI Setup and re-check the currently-connected device.

**BlackHole doesn't appear in Audio MIDI Setup.** Restart the Audio MIDI Setup app, or log out and back in. In rare cases you need to restart the Mac after install.

**There's an echo when I talk.** If you also checked a microphone input anywhere in this chain, you've created a feedback loop. Multi-Output Devices should only send *output* to BlackHole.

---

## Reference

- BlackHole project: <https://github.com/ExistentialAudio/BlackHole>
- Apple's docs on Multi-Output Devices: <https://support.apple.com/guide/audio-midi-setup/welcome/mac>
- Conductør website guide (with screenshots): <https://conductor.lighting/docs/mac-audio-setup>
