PulseAudio volume control in the odio API
The PulseAudio backend provides full control over the node’s audio: server info, output selection, global and per-client volume/mute. Works with both PulseAudio and PipeWire (via pipewire-pulse).
Uses a pure-Go PulseAudio native protocol implementation — no libpulse dependency.
Endpoints
Section titled “Endpoints”Combined state
Section titled “Combined state”GET /audioReturns the server kind, outputs, and clients in a single response, each list in the same shape as its dedicated route below:
{ "kind": "pulseaudio", "outputs": [ /* same as GET /audio/outputs */ ], "clients": [ /* same as GET /audio/clients */ ]}Server
Section titled “Server”GET /audio/server{ "kind": "pulseaudio", "default_sink": "alsa_output.platform-soc_sound.stereo-fallback", "volume": 1, "muted": false}kind is pulseaudio or pipewire. volume is a float from 0 to 1.
POST /audio/server/mutePOST /audio/server/volumeOutputs (sinks)
Section titled “Outputs (sinks)”GET /audio/outputs[ { "id": 0, "name": "alsa_output.platform-soc_sound.stereo-fallback", "description": "Built-in Audio Stereo", "nick": "Built-in Audio Stereo", "muted": false, "volume": 1, "state": "running", "default": true, "driver": "module-alsa-card.c", "active_port": "analog-output", "props": { "alsa.card": "1", "alsa.card_name": "snd_rpi_hifiberry_dacplus", "alsa.class": "generic" // ...every sink property reported by the server } }]name is the {output} used in the routes below. Network sinks carry "is_network": true.
POST /audio/outputs/{output}/defaultPOST /audio/outputs/{output}/mutePOST /audio/outputs/{output}/volumeClients (sink inputs)
Section titled “Clients (sink inputs)”GET /audio/clients[ { "id": 0, "name": "Playback", "app": "Shairport Sync", "muted": false, "volume": 1, "corked": true, "backend": "pulseaudio", "binary": "shairport-sync", "user": "odio", "host": "raspodio", "props": { "application.name": "Shairport Sync", "media.class": "Stream/Output/Audio" // ...every sink input property reported by the server } }]id is the {sink} used in the routes below. corked means the stream is paused. Clients streaming from another machine (a PulseAudio tunnel) report that machine’s user and host.
POST /audio/clients/{sink}/mutePOST /audio/clients/{sink}/volumePulseAudio cookie
Section titled “PulseAudio cookie”GET /audio/cookieDownloads the PulseAudio authentication cookie — useful for setting up network audio sinks.
Events
Section titled “Events”| Event | Trigger |
|---|---|
audio.updated | Sink input added or changed |
audio.removed | Sink input removed |
Configuration
Section titled “Configuration”pulseaudio: enabled: true serve_cookie: true volumeStep: 0.05serve_cookie exposes GET /audio/cookie — save the downloaded cookie on your client as ~/.config/pulse/cookie with 600 permissions to enable network audio streaming.
volumeStep is how far a remote moves the default output on volume.up and volume.down, from 0.01 to 1. Since v0.18.0.
How it works
Section titled “How it works”The backend connects to PulseAudio via its native protocol over the Unix socket. Real-time events are captured through PulseAudio’s built-in monitoring mechanism.