This repo provides macOS Virtual Audio Device (VAD) for streaming audio to or from remote devices. It is part of Roc Toolkit project and is interoperable with both Roc and third-party software.
After installing Roc VAD, you can:
- create and control one or several virtual audio devices, using a command-line tool;
- connect a virtual device to remote sender or receiver;
- configure you local apps to use a virtual device instead of real microphone or speakers.
When you configure an app (e.g. iTunes) to use virtual device as a speaker, all sound that the app plays to the device is streamed to a remote receiver. Remote receiver could be Roc PipeWire source, or an app using Roc Toolkit library, or even a generic RTP receiver.
And vice versa, when you configure an app (e.g. Zoom) to use virtual device as a microphone, the sound is streamed from a remote sender to the virtual device, and the app reads the received stream.
Key features of Roc Toolkit:
- real-time streaming with guaranteed latency;
- robust work on unreliable networks like Wi-Fi, due to use of Forward Erasure Correction codes;
- CD-quality audio;
- multiple profiles for different CPU and latency requirements;
- relying on open, standard protocols, like RTP and FECFRAME;
- interoperability with both Roc and third-party software.
Compatible Roc Toolkit senders and receivers include:
- cross-platform command-line tools
- modules for sound servers (PulseAudio, PipeWire)
- C library and bindings for other languages
- end-user apps
macOS 10.15 (Catalina) or later is required.
Both x86_64 (Intel) and arm64 (ARM) architectures are supported.
Install driver and command-line tool:
sudo /bin/bash -c \
"$(curl -fsSL https://raw.githubusercontent.com/roc-streaming/roc-vad/HEAD/install.sh)"
To uninstall everything, run:
sudo roc-vad uninstall
Then reboot your Mac.
Prerequisites:
- Install XCode Command Line Tools
- Install Homebrew
Install build dependencies:
brew install cmake scons autoconf automake pkg-config libtool go
Clone repo:
git clone https://github.com/roc-streaming/roc-vad.git
Go to the project directory:
cd roc-vad
Build:
make
Install:
sudo make install
Now, either reboot your Mac, or run:
sudo make kickstart
This command will restart macOS sound server. Usually it's enough, but some apps may not handle sound server restart well, so reboot is preferred.
To uninstall everything, run:
sudo make uninstall
First, check that sound server driver was successfully loaded:
$ roc-vad info
driver is loaded
driver:
version: 0.0.1
commit: 76ca125
client:
version: 0.0.1
commit: 76ca125
To enable verbose logging of the command line tool, use -v flag. Specify it multiple times to increase verbosity:
$ roc-vad -vv info
debug: opened driver bundle at "/Library/Audio/Plug-Ins/HAL/roc_vad.driver"
debug: obtained value "127.0.0.1:9712" for key "DriverSocket" from driver bundle
info: trying to connect to driver at 127.0.0.1:9712
debug: creating rpc channel
debug: sending ping command
...
To print logs from driver, use logcat command. It connects to driver via RPC and streams its logs to stdout:
$ roc-vad logcat
03:30:33.511 [DD] received stream_logs command
03:30:33.511 [DD] attaching log sender to dist sink
...
Alternatively, you can use syslog makefile target. It streams logs that driver sends to system log. Basically they are the same logs as produced by logcat command, but in slightly different format, and possibly truncated and deduplicated:
$ make syslog
log stream --predicate 'sender == "roc_vad"'
Filtering the log data using "process == "coreaudiod" OR sender == "roc_vad""
Timestamp Thread Type Activity PID TTL
2023-04-13 03:31:54.896185+0400 0xe38a Default 0x0 11980 0
com.apple.audio.Core-Audio-Driver-Service: (roc_vad) [DD] received ping command
2023-04-13 03:31:54.897686+0400 0xe38a Default 0x0 11980 0
com.apple.audio.Core-Audio-Driver-Service: (roc_vad) [DD] received get_info command
...
-
Can't connect to driver
Make sure you did not forget to reboot computer (preferably) or restart
coreaudiodafter installing Roc VAD. -
Network connectivity
Ensure that sent packets reach receiver.
When you start streaming from sender to receiver, you should see information about connected sender in receiver's logs. If you don't, it indicates problems with network connection, e.g. you use incorrect address or port, or a firewall is blocking traffic.
-
Playback shuttering
If you hear shuttering, try increasing target latency on the receiving side. For example, for Roc VAD receiver, try using
--target-latency=200msto increase latency to 200 milliseconds. -
Decreasing latency
If your network allows lower latency, use
--target-latency(receiver buffer size) option on receiving side and--packet-length(packet size),--nbsrc, and--nbrpr(FEC block size) on sending side.Each FEC block consists of
--nbsrcpackets of--packet-lengthlength;--nbrprshould be about 2/3 of--nbsrc;--target-latencyshould be greater than FEC block size to allow packet repair to work.
You can control Roc VAD driver from any programming language via gRPC interface.
You can to do everything you can do via command-line tool, which itself is just a wrapper for the same RPC calls. Unlike the command-line tool, gRPC interface will maintain backward compatibility on updates.
More details are available here:
- driver_protocol.proto - protocol definition
- RPC.md - generated protocol documentation
By default, driver starts (unauthenticated) gRPC server at 127.0.0.1:9712.
If you want to change the address, you can edit DriverSocket entry in /Library/Audio/Plug-Ins/HAL/roc_vad.driver/Contents/Info.plist plist file. Both driver and command-line tool read address from there.
Contributions in any form are always welcome! You can find issues needing help using help wanted and good first issue labels.
If you would like to dig into the project internals, have a look at HACKING.md.
If you would like to support the project financially, see details on this page.
Thank you!
See here.
Contents of the repository is licensed under MPL-2.0.
For details on Roc Toolkit licensing, see here.
