,---. . ,-_/
| -' ,-. ,-. |- ,-. . ,-. ' | ,-. ,-. . ,
| . ,-| | | | ,-| | | | | ,-| | |/
`---' `-^ |-' `' `-^ ' ' ' | `-^ `-' |\
| / | ' `
' `--'
captain jack audio device
github.com/qix-/captainjack
copyright (c) 2016 josh junon
released under the MIT license
I've halted production on Captain Jack until JACK has improved. See #3.
Captain Jack is a JACK-enabled audio device for OS/X.
Through the use of the new AudioServerPlugin API (since 10.5), Captain Jack provides a means of routing system audio into the JACK subsystem through either a system mix port or one or more per-application (namely, per-process) audio ports.
You must have an implementation of JACK installed on the system. You can (and should) do this by downloading and building the latest source from either JACK1 or JACK2, though it's worth mentioning JACK2 does not currently build on OS/X.
To build Captain Jack:
$ makeTo install Captain Jack:
$ sudo make installTo start Captain Jack:
$ sudo make startUse Console.app (in /Applications/Utilities). Select system.log on the side
and filter for CaptainJack.
All daemon log messages have the CaptainJack tag, and all device messages
have the CaptainJack-Device tag.
Captain Jack is made up of two pieces: the device and the daemon.
The Captain Jack Device is a CoreAudio HAL Plugin .driver bundle that uses
the latest APIs in lieu of the deprecated AudioHardwarePlugin APIs.
The device is a user-space plugin that requires no Kext signing nor does it require disabling of SIP.
Since coreaudiod, the system service that manages audio and thus loads
Captain Jack's device plugin, resides within the
System bootstrap
space, and since coreaudiod runs everything inside a sandbox, getting
audio out of coreaudiod and into JACK requires some clever IPC.
XPC is Apple's version of IPC and is one of the two methods of IPC really
available to Mach services. Its major (and deal-breaking) drawback is that
it requires some sort of main dispatch loop, which isn't possible in an
AudioServerPlugin bundle since everything inside of the device is just a
callback and anything that blocks would effectively block not only coreaudiod
but other launch daemons as well (I notice my RGB key board freeze up if
Captain Jack blocks!).
Therefore, the network was the only other means of IPC (I heard that shared memory regions were allowed, but I never could figure out how to get them to work).
When a connection has been established to the daemon (a user-space launchd
daemon; see below), all callbacks forward their data to an Xmit RPC call (see
src/xmit.c) that in turn passes the data along the loopback socket and into
the less-restrictive daemon process.
The reason why the daemon is even necessary and why the device cannot simply connect to JACK directly is that the sandbox prevents any IPC other than network IPC. Since we can't really guarantee that JACK is going to support network communication this becomes unreliable. As well, things like RO filesystem calls, the inability to trigger window apps or even look up PID process names were very restrictive, and the device quickly turned into a trampoline for audio events.
The Captain Jack Daemon is a user-space launchd LaunchDaemon that relays
Xmit-RPC'd audio data from the device to JACK. It also manages a light state
for whatever might be necessary to track (e.g. client name => PID map, etc).
The device and daemon communicate over a very opaque and light network layer
dubbed Xmit (see src/xmit.c) that uses read buffer polling to achieve
asynchronicity. Since it uses the TCP protocol, there is little chance of
audio frames to be mixed up during transmission.
Using the network also gives us nearly free IPC with almost zero added latency (assuming the loopback interface is used, which it is in this case).
The only externalized Xmit calls are those that set up the callback functions.
All transportation specifics are statically defined and managed inside of
xmit.c.
Captain Jack is licensed under the MIT License. All JACK works are licensed under their respective licenses.