Repository navigation
Device Capture macOS
This guide walks you through capturing device configuration data from your Apollo on macOS using DTrace. This data is essential for supporting Apollo models we don't have physical access to.
The capture script is read-only — it observes data the UA driver is already exchanging with its mixer software. It makes zero writes to hardware.
DTrace requires System Integrity Protection to be disabled. SIP is a macOS security feature that restricts certain system-level operations, including kernel tracing.
SIP prevents modification of protected system files and restricts debugging tools like DTrace from attaching to system processes. It is an important security layer, and you should only disable it temporarily for this capture.
With SIP disabled, software running as root has fewer restrictions on what it can access. This is why you should:
- Only disable SIP on a machine you trust
- Run only the capture script while SIP is disabled
- Re-enable SIP immediately after capturing
Apple's official SIP documentation: https://support.apple.com/en-us/102149
- Shut down your Mac
- Boot into Recovery Mode:
- Apple Silicon: Hold the power button until "Loading startup options" appears, then select Options
- Intel: Hold Cmd+R during startup
- Open Terminal from the Utilities menu
- Run:
csrutil disable
- Restart your Mac normally
Verify SIP is disabled:
csrutil status
# Should say: "System Integrity Protection status: disabled"Make sure:
- Your Apollo is connected via Thunderbolt and powered on
- UA Console or UA Connect is running (the capture observes communication between the UA mixer software and the driver)
- UAD software is installed
Clone the repository if you haven't already:
git clone https://github.com/rolotrealanis98/open-apollo.git
cd open-apolloNote: The macOS capture script is a work-in-progress placeholder and may not produce complete capture data yet. We are actively improving it — partial captures are still useful, so please submit what you get.
sudo ./tools/contribute/macos/capture.shThe script will:
- Verify SIP is disabled
- Check that the UA driver is loaded
- Capture device configuration from IORegistry
- Run DTrace probes for 30 seconds to capture routing data (
--seconds Nchanges the duration) - Save everything to a JSON file
The output file is saved in the current directory with a timestamp, for example: apollo-macos-capture-YYYYMMDD-HHMMSS.json. Use --output path.json to choose the location.
Before submitting, open the JSON file and review its contents. It contains:
- System info: macOS version and architecture
- Device info: Apollo model name, device type, channel counts
- Routing data: How audio channels are mapped between DMA and DSP
It does not contain: personal information, audio data, filesystem paths, network information, or any data unrelated to the Apollo hardware configuration.
This is critical. Do not leave SIP disabled longer than necessary.
- Shut down your Mac
- Boot into Recovery Mode (same method as Step 1)
- Open Terminal from the Utilities menu
- Run:
csrutil enable - Restart your Mac normally
Verify SIP is re-enabled:
csrutil status
# Should say: "System Integrity Protection status: enabled"The DTrace probes target IOConnectCallStructMethod, the standard macOS API for kernel driver communication. The probes intercept calls from the UA Mixer Engine process to read:
- Selector 171 (routing table): Maps audio channels between DMA and DSP — this is the key data needed for Linux support
- Device identification: Model type and hardware capabilities
These are the same calls the UA software makes during normal operation. The probes only observe — they do not inject, modify, or replay any calls.
See tools/contribute/macos/WHAT-THIS-DOES.md in the repository for a line-by-line explanation of the capture script.
The DTrace capture above records the routing table (how DMA and DSP channels map). The mixer daemon additionally needs a device map — the full control tree (preamps, buses, plugins, routes) for the model. This is captured separately, over TCP, and does not require SIP to be disabled.
With your Apollo connected and UA Console open (so the UA Mixer Engine is serving on port 4710), run the tree dumper from the repo:
python3 mixer-engine/tools/dump_x8p_tree.py --host 127.0.0.1 \
--device-name "Apollo x8p" --out capture.json--device-name is the model you are capturing from ("Apollo Twin X", "Apollo x8", …) — it is stamped into the capture and carried through to the device map, so set it to match your hardware. It walks the engine's control tree node by node (a full map is a few MB, so allow ~a minute). Then flatten the raw tree into the daemon's device-map format:
python3 mixer-engine/tools/tree_to_device_map.py capture.json \
-o mixer-engine/device_maps/device_map_apollo_<model>.jsonAdd a devices/apollo-<model>.json descriptor with the matching device_type, and the daemon will select the new map automatically for that model. See Daemon Configuration for details.
- Submitting Your Data — how to submit your capture
- How to Contribute — other ways to help
Getting Started
Driver
Mixer Daemon
Contributing
Architecture
- Architecture Overview
- Register Map
- DSP Protocol
- Initialization Sequence
- USB Apollo Reverse Engineering
- Experimental Features
Legal