webrtc-cli is a small command-line tool allowing to stream to and from audio devices and files via WebRTC.
Features:
- Generating SDP offers and answers.
- Connecting incoming and outgoing WebRTC tracks with local audio devices and files.
- Unidirectional and bidirectional operation.
- Restoring lost packets using Opus FEC and PLC.
Configurations:
- single incoming and/or single outcoming track
Media types:
- audio
Audio devices:
- PulseAudio sources and sinks
File formats:
- WAV files
RTP codecs:
- Opus codec
Operating systems:
- tested only on Linux
Install dependencies:
sudo apt-get install gcc make pkg-config libopus-dev libopusfile-dev libpulse-dev
Install recent Go (at least 1.12 is needed):
sudo add-apt-repository ppa:longsleep/golang-backports
sudo apt-get update
sudo apt-get install golang-go
Clone and build:
git clone https://github.com/gavv/webrtc-cli.git
cd webrtc-cli
make
Run the tool:
./webrtc-cli -h
You can also install the tool system-wide, e.g.:
sudo cp ./webrtc-cli /usr/local/bin
Alternatively, you can install webrtc-cli into GOPATH using go get.
First make sure that the Go version is at least 1.12:
go version
And then run this command:
go get -v github.com/gavv/webrtc-cli
It will automatically fetch sources and build and install webrtc-cli executable into $GOPATH/bin directory or into ~/go/bin if $GOPATH is not set.
$ webrtc-cli --help
Usage of webrtc-cli:
--offer enable offer mode
--answer enable answer mode
--source string pulseaudio source or input wav file
--sink string pulseaudio sink
--timeout duration exit if can't connect during timeout
--ice string STUN or TURN server URL (default "stun:stun.l.google.com:19302")
--ports string use specific UDP port range (e.g. "3100:3200")
--override-ip string override IP address in SDP offer/answer
--rate uint sample rate (default 48000)
--chans uint # of channels (default 2)
--source-frame duration source frame size (default 40ms)
--sink-frame duration sink frame size (default 40ms)
--jitter-buf duration jitter buffer size (default 120ms)
--pulse-buf duration pulseaudio buffer size (default 20ms)
--max-drift duration maximum jitter buffer drift (default 30ms)
--mode string opus encoder mode: voip|audio|lowdelay (default "voip")
--complexity uint opus encoder complexity (default 10)
--loss-perc uint expected packet loss percent, passed to opus encoder (default 25)
--simulate-loss-perc uint simulate given loss percent when receiving packets
--debug enable more logs
The tool works in one of the two operation modes:
-
Offer mode: the tool generates an SDP offer and prints it to stdout. Then the tool reads an SDP answer from stdin. Then the tool starts streaming.
-
Answer mode: the tool reads an SDP offer from stdin. Then the tool generates an SDP answer and prints it to stdout. Then the tool starts streaming.
In both modes, the user is responsible to deliver SDP offer and answer between the two peers (e.g. between the two instances of the tool or between the tool and the browser).
When the tool reads SDP offer or answer from stdin, it reads all bytes until EOF is reached. If you're manually pasting it in the terminal, press ^D after pasting the text.
The tool may also work in one of the two direction modes:
-
Unidirectional mode: only a source or only a sink is specified.
-
Bidirectional mode: both a source and a sink are specified.
It does not matter what peer is generating an offer or answer and what peer has a sink or source or both. All combinations are allowed.
Recording (source) latency is the sum of:
- PulseAudio buffer size
- source frame size, also used as the Opus packet size
Playback (sink) latency is the sum of:
- jitter buffer size
- PulseAudio buffer size
- sink frame size
The overall latency is the sum of recoding latency, network latency, and playback latency.
The following frame sizes are supported: 10ms, 20ms, 40ms, and 60ms.
To employ FEC, jitter buffer should be at least two packet sizes. However, for seamless playback, it is recommended to set it to three packet sizes. The maximum drift parameter specifies how much the actual jitter buffer size may differ from the configured size.
PulseAudio usually doesn't handle very low latencies well. It's recommended to set PulseAudio buffer size at least to 20ms.
-
This tool does not implement clock drift compensation. Instead, it monitors the incoming queue size and just restarts the stream when the queue size goes out of bounds. This is quite unnoticeable for speech, but may be annoying for music.
-
Lost packets are recovered using Opus FEC (Forward Erasure Correction) and Opus PLC (Packet Loss Concealment). Opus FEC recovers packets from a redundant lower-bitrate stream, and PLC recreates packets using interpolation. Again, these methods work pretty good for speech, but may be annoying for music.
-
PLC is triggered only when a packet arrives. If jitter buffer is empty and no packets have arrived yet, zero samples will be produced instead of PLC. This problem usually arises only on high packet loss ratios.
-
I didn't try to perform any optimizations. Likely, the tool will not handle very low latencies well.
This repo also provides WebRTC demo (source code). It contains a sample JavaScript code that can interact with this tool. The demo was tested on the Chromium browser.
If you allow it to access the microphone, it will play sound from the remote peer and send sound from the microphone to the remote peer. Otherwise, it will only play sound from the remote peer.
First peer:
webrtc-cli --offer --source ./test.wav
Second peer:
webrtc-cli --answer --sink alsa_output.pci-0000_00_1f.3.analog-stereo
First peer:
webrtc-cli --offer --source alsa_input.pci-0000_00_1f.3.analog-stereo
Second peer:
webrtc-cli --answer --sink alsa_output.usb-Burr-Brown_from_TI_USB_Audio_CODEC-00.analog-stereo
First peer:
webrtc-cli --offer \
--source alsa_input.pci-0000_00_1f.3.analog-stereo \
--sink alsa_input.pci-0000_00_1f.3.analog-stereo
Second peer:
webrtc-cli --answer \
--source alsa_output.usb-Burr-Brown_from_TI_USB_Audio_CODEC-00.analog-stereo \
--sink alsa_output.usb-Burr-Brown_from_TI_USB_Audio_CODEC-00.analog-stereo
First peer: WebRTC demo (source code)
Second peer:
webrtc-cli --answer \
--source alsa_output.usb-Burr-Brown_from_TI_USB_Audio_CODEC-00.analog-stereo \
--sink alsa_output.usb-Burr-Brown_from_TI_USB_Audio_CODEC-00.analog-stereo
webrtc-cli \
--pulse-buf 20ms \
--source-frame 10ms --sink-frame 10ms \
--jitter-buf 20ms --max-drift 20ms \
...
webrtc-cli --offer --override-ip 93.184.216.34 --ports 5100:5200 ...
This will restrict what UDP ports can be used to given range and replace IP addresses of all ICE candidates in generated SDP offer with given IP.
Build tools:
- Go >= 1.12
- GCC (for cgo)
- pkg-config (for cgo)
Go libraries:
- pion/webrtc (pure Go WebRTC implementation)
- gavv/opus, forked from hraban/opus (Go bindings for libopus)
- mesilliac/pulse-simple (Go bindings for libpulse-simple)
- youpy/go-wav (pure Go WAVE file library)
- spf13/pflag (command-line parsing library)
- mattn/go-isatty (isatty function for Go)
- x/time/rate (rate-limiter library)
C libraries:
- libopus and libopusfile
- libpulse-simple (part of PulseAudio)
This tool was initially developed for a freelance project. Big thanks to my customer who has kindly allowed to open-source it!
I'm working on another related open-source project, Roc Toolkit. It offers a wider functionality and better service quality, but so far has no WebRTC support.
Feel free to report bugs, suggest improvements, and send pull requests!
Build:
make
Run checks:
make check
Format code:
make fmt
See here.
