Devious Fish
pianod2 music server
profile for Perette at Stack Overflow, Q&A for professional and enthusiast programmers

Audio Configuration

The ROOM CREATE and ROOM RECONFIGURE commands provide options to redirect or reconfigure output. Audio options are as follows:

LIBRARY {library}

Select an output library. Unless specifically configured otherwise, you will only have one output library. When using Mac OS X’s AVFoundation as the media engine, this setting is ignored. Valid values (assuming they are compiled in) are:

  • libao
  • libsdl
  • libavdevice (part of ffmpeg)
  • gstreamer
DRIVER {driver}

Select a driver. See the various libraries’ documentation for values.

DEVICE {device}

Specify a device. See the various libraries’ documentation for values.

ID {#id}
For libao, to specify a libao output by number.
OPTIONS {options}

Other options for the audio device. See the various libraries’ documentation for values.

  • libavdevice: A string with option name-value pairs applied when opening the driver.
SERVER {server}

Destination and/or parameters applicable when an audio server driver is in use.

  • libao: Used by streaming media drivers to specify a destination.
  • libavdevice: Passed to the library as a filename when opening the output.
VOLUME {level}
The initial volume level of the room. Defaults 0dB gain.
The duration of crossfade (overlap) between songs. Defaults to 0, in which case songs are not cross-faded. Cross-fading helps reduce the sense of breaks between songs, but used wrong can be annoying; violin concertos mixing can sound like cats in heat. Fast-paced songs seem to do well with 2–2.5 seconds, classical either 0 or 5 seconds, soft rock 5–10 seconds.
The amount of volume adjustment to apply when crossfading, in decibels. This is a positive number; the default is 10dB. The cueing song is faded from current_volume - crossfade_level to current_volume; the ending song concurrently undergoes the reverse transition.
The number of seconds early an audio player is created, relative to start of crossfade (or end of song, if crossfade is 0). This affords a chance to open devices, establish connections and begin buffering streams. If set to 0, crossfade must also be disabled. Disabling preroll is necessary with somes media engines when an audio device can’t be opened more than once, to prevent skipping alternate songs due to device-busy errors.

Options available, exact meaning and behavior depends on the platform (i.e., Linux, Mac, etc.) and compile options. For more information on options, see libao drivers, libsdl outputs, libavdevice outputs, libavdevice protocols and gstreamer plug-ins.

Platform- & Library-Specific Audio Issues

gstreamer security

A pipeline may be specified for the gstreamer output, which has potential for security issues and abuse. When using gstreamer, it’s extra important to lock down security via means such as:


ffmpeg/libavdevice flush control

FFmpeg reports when audio has been fully flushed, but has proven unreliable with their built-in devices. Some devices report they are flushed, but closing them cuts off the audio (for example: ALSA); others indefinitely report they are still in the process of flushing (for example: Pulse).

To work around this, pianod adds two FFmpeg-style parameters to the OPTIONS string to control flushing:

The minimum amount of time, in milliseconds, allowed for flushing. Default is 0. If crossfading is disabled, and this value is too large, it will produce gaps between tracks. If crossfading, setting this value too large is innocuous.
The maximum time, in milliseconds, before pianod closes audio, even if it’s allegedly still buffering. Default is 2000, or 2 seconds.


room reconfigure options "min_flush_time=2000; max_flush_time=5000"
ffmpeg/libavdevice with ALSA

libavdevice may not default to the ALSA driver.


Furthermore, some implementations/versions consider the ALSA driver experimental:

ROOM RECONFIGURE OPTIONS "strict=experimental"