Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/balena-io-experimental/audio
Audio building block for balenaOS, based on pulseaudio.
https://github.com/balena-io-experimental/audio
alsa audio-applications balenablock linux pulseaudio raspberry-pi
Last synced: 3 months ago
JSON representation
Audio building block for balenaOS, based on pulseaudio.
- Host: GitHub
- URL: https://github.com/balena-io-experimental/audio
- Owner: balena-io-experimental
- Created: 2020-05-22T13:51:20.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2022-11-15T22:58:24.000Z (almost 2 years ago)
- Last Synced: 2024-06-09T01:34:15.641Z (5 months ago)
- Topics: alsa, audio-applications, balenablock, linux, pulseaudio, raspberry-pi
- Language: Shell
- Homepage: https://hub.balena.io/blocks
- Size: 286 KB
- Stars: 31
- Watchers: 1
- Forks: 13
- Open Issues: 20
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# balena audio block
Provides an easy way to work with audio applications in a containerized environment.
The `audio` block is a docker image that runs a [PulseAudio](https://www.freedesktop.org/wiki/Software/PulseAudio/) server optimized for balenaOS.
## Features
- 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
## Usage
#### Prebuilt images
We maintain images for this block on balenaHub Container Registry. The images can be accessed using:
`bh.cr/balenalabs/audio-` or `bhcr.io/balenalabs/audio-` where `` 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](https://github.com/balena-io/open-balena-registry-proxy/#usage).
#### docker-compose file
To use this image, create a container in your `docker-compose.yml` file as shown below:
```yaml
version: '2'
volumes:
pulse: # Only required if using PA over UNIX socket
services:
audio:
image: bh.cr/balenalabs/audio- # where 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 socket
```
#### Send/receive audio
In 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](#environment-variables) 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](http://sox.sourceforge.net/): PA backend distributed via `libsox-fmt-pulse` package
- [MPlayer](http://www.mplayerhq.hu/): Native PA backend
- [FFmpeg](https://ffmpeg.org/): 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:
- [Debian](scripts/alsa-bridge/debian-setup.sh)
- [Alpine](scripts/alsa-bridge/alpine-setup.sh)
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`:
```Dockerfile
RUN curl -skL https://raw.githubusercontent.com/balena-labs-projects/audio/master/scripts/alsa-bridge/debian-setup.sh| sh
```
## Customization
### Extend image configuration
You 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:
```Dockerfile
FROM bh.cr/balenalabs/audio-aarch64
CMD [ "--disallow-module-loading" ]
```
- Add custom configuration files:
```Dockerfile
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:
```Dockerfile
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" ]
```
### Environment variables
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](#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
- ``: 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](https://web.archive.org/web/20200427023741/https://www.raspberrypi.org/documentation/configuration/audio-config.md). 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%. |
### Companion library
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](https://pypi.org/project/pulsectl/), [Rust](https://docs.rs/libpulse-binding/2.16.0/libpulse_binding/), [JavaScript](https://github.com/stanford-oval/node-pulseaudio#readme)), or you could even [write your own](https://freedesktop.org/software/pulseaudio/doxygen/). 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
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](https://github.com/balena-labs-projects/bluetooth) for an easy to use Bluetooth agent.
## Supported devices
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: https://github.com/balena-labs-projects/audio/issues/35
2: Not tested. PR's welcome.