Provides an easy way to work with audio applications in a containerized environment.
The audio block is a docker image that runs a PulseAudio server optimized for balenaOS.
- PulseAudio v15 audio server
- Configuration optimized for balenaOS, extendable via PA config files
- Supports both TCP and UNIX socket communication
- Bluetooth and ALSA support out of the box
- Companion library to send PA commands and handle events using JavaScript
We maintain images for this block on balenaHub Container Registry. The images can be accessed using:
bh.cr/balenalabs/audio-<arch> or bhcr.io/balenalabs/audio-<arch> where <arch> is one of: rpi, armv7hf, aarch64 or amd64.
For details on how to select a specific version or commit version of the image see our documentation.
To use this image, create a container in your docker-compose.yml file as shown below:
version: '2'
volumes:
pulse: # Only required if using PA over UNIX socket
services:
audio:
image: bh.cr/balenalabs/audio-<arch> # where <arch> is one of rpi, armv7hf, aarch64 or amd64
privileged: true
labels:
io.balena.features.dbus: 1 # Only required for bluetooth support
ports:
- 4317:4317 # Only required if using PA over TCP socket
volumes:
- 'pulse:/run/pulse' # Only required if using PA over UNIX socket
my-audio-app:
build: ./my-audio-app
volumes:
- 'pulse:/run/pulse' # Only required if using PA over UNIX socketIn order to route audio through the audio block there are a few environment variables you'll need to set. Note that they must be set on your client container, where your audio application is running and not on the block itself. We recommend setting them in the Dockerfile.
| Environment variable | Description |
|---|---|
PULSE_SERVER |
Required Address of the PulseAudio server which you want to connect to. Depending on the communication protocol you want to use it can be: - UNIX socket: PULSE_SERVER=unix:/run/pulse/pulseaudio.socket- TCP socket: PULSE_SERVER=tcp:audio:4317 |
PULSE_SINK |
Optional The PulseAudio sink your application will send audio to. If not set, the block will use the PulseAudio default sink. Unless you are building a complex audio application we don't recommend setting this variable. If you want to select which output to use, for example HDMI or audio jack for a Raspberry Pi use the AUDIO_OUTPUT env var on the block to select the output device. |
PULSE_SOURCE |
Optional The PulseAudio source your application will get audio from. |
Setting these environment variables will instruct your application to route audio to the PulseAudio server on the audio container. For this to work your application must have built-in support for PulseAudio as an audio backend. Most applications do, though some might require installing or configuring additional packages. If your application does not have native support for the PulseAudio backend you'll need to use your container's ALSA backend to bridge over to PulseAudio.
Read on for details on both alternatives. We've also included some examples in the examples folder (along with the docker-compose.yml file) so be sure to check that as well for implementation details.
PulseAudio backend
For applications with PulseAudio support, the audio is routed as follows:
[client-container] audio-app --> [audio] PulseAudio --> [audio] ALSA --> Audio Hardware
Here is a non-exhaustive list of applications with PulseAudio backend that have been tested to work, feel free to PR more:
- SoX: PA backend distributed via
libsox-fmt-pulsepackage - MPlayer: Native PA backend
- FFmpeg: Native PA backend
ALSA bridge
For audio applications that don't have built-in PulseAudio support you can use ALSA to brige the gap:
[client-container] audio-app --> [client-container] ALSA --> [audio] PulseAudio --> [audio] ALSA --> Audio Hardware
Setting up the ALSA bridge requires extra configuration steps on your containers so we created a few bash scripts to simplify the process:
Before making use of audio capabilities you should run this script. An easy way to do so is by including the following instruction in your Dockerfile:
RUN curl -skL https://raw.githubusercontent.com/balena-labs-projects/audio/master/scripts/alsa-bridge/debian-setup.sh| shYou can extend the audio block to include custom configuration as you would with any other Dockerfile. Just make sure you don't override the ENTRYPOINT as it contains important system configuration.
Here are some of the most common extension cases:
- Pass a flag to the PulseAudio server:
FROM bh.cr/balenalabs/audio-aarch64
CMD [ "--disallow-module-loading" ]- Add custom configuration files:
FROM bh.cr/balenalabs/audio-aarch64
COPY custom.pa /usr/src/custom.pa
CMD [ "pulseaudio", "--file /usr/src/custom.pa" ]- Start PulseAudio from your own bash script:
FROM bh.cr/balenalabs/audio-aarch64
COPY custom.pa /usr/src/custom.pa
COPY start.sh /usr/src/start.sh
CMD [ "/bin/bash", "/usr/src/start.sh" ]The following environment variables allow some degree of configuration:
| Environment variable | Description | Default | Options |
|---|---|---|---|
AUDIO_LOG_LEVEL |
PulseAudio log level. | WARN |
ERROR, WARN, NOTICE, INFO, DEBUG. |
AUDIO_OUTPUT |
Select the default audio output device. Can also be changed at runtime by using the companion library |
AUTO |
For all device types: - AUTO: Let PulseAudio decide. Priority is USB > DAC > HEADPHONES > HDMI- DAC: Force default output to be an attached GPIO based DAC- <PULSE_SINK_NAME>: If you know the sink name you can force set it too. Note that you can't use this to set custom sinks as default, in that case use set-default-sink on your custom pa script. For Raspberry Pi devices: - RPI_AUTO: BCM2835 automatic audio switching as described here. Deprecated for devices running Linux kernel 5.4 or newer. - RPI_HEADPHONES: 3.5mm audio jack - RPI_HDMI0: Main HDMI port - RPI_HDMI1: Secondary HDMI port (only Raspberry Pi 4) For Intel NUC: - NUCs have automatic output detection and switching. If you plug both the HDMI and the 3.5mm audio jack it will use the latter. |
AUDIO_VOLUME |
Initial volume level for the default audio output device. | 75% |
Any value between 0-100%. |
If you need to manipulate the block's behavior at runtime you can connect to the PulseAudio server, send commands and receive data or events from it. You should be able to use any existing library that implements the PA client protocol over TCP/UNIX sockets (some examples: Python, Rust, JavaScript), or you could even write your own. Libraries that manipulate PA over dbus won't work because we don't run the pulse dbus daemon.
On this note, we built a companion javascript library that exposes the most common use cases with an easy to use interface, these include changing the volume, listening to play/stop events, etc.
You can install it with npm install balena-audio; see https://github.com/balena-io-modules/balena-audio for usage and examples.
Bluetooth support for PulseAudio is enabled out of the box. Note that this only provides the backend that routes bluetooth packets over to PulseAudio, this does not include the Bluetooth agent that's required for initiating a connection and pairing devices. Check out our Bluetooth block for an easy to use Bluetooth agent.
The audio block has been tested to work on the following devices:
| Device Type | Supported interface (driver) |
|---|---|
| Raspberry Pi (v1 / Zero / Zero W) | - Audio jack (bcm2835): ✔ - HDMI ( bcm2835): ✔- I2S DAC ( snd-rpi-simple): ✔ - USB ( snd-usb-audio): ✔ |
| Raspberry Pi 2 | - Audio jack (bcm2835): ✔ - HDMI ( bcm2835): ✔- I2S DAC ( snd-rpi-simple): ✔ - USB ( snd-usb-audio): ✔ |
| Raspberry Pi 3 | - Audio jack (bcm2835): ✔ - HDMI ( bcm2835): ✔- I2S DAC ( snd-rpi-simple): ✔ - USB ( snd-usb-audio): ✔ |
| Raspberry Pi 4 | - Audio jack (bcm2835): ✔ - HDMI ( bcm2835): ✔- I2S DAC ( snd-rpi-simple): ✔ - USB ( snd-usb-audio): ✔ |
| Intel NUC | - Audio jack (snd_hda_intel): ✔- HDMI ( snd_hda_intel): ✔- USB ( snd-usb-audio): ✔ |
| Jetson Nano 1 | - HDMI (tegrahda): ✘ - I2S DAC ( tegrasndt210ref): ?2 - USB ( snd-usb-audio): ✔ |
| BeagleBone Black | - USB (snd-usb-audio): ✔ |
1: Audio block crashes if no USB/DAC present. See: #35 2: Not tested. PR's welcome.