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.

• libao: Selects libao drivers.
• libavdevice: Selects libavdevice outputs or libavdevice protocols.

DEVICE {device}

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

• libao: Specifies a device to use.
• gstreamer: Select gstreamer plug-ins for output using the grammar allowed by gst-launch. May describe a pipeline.
• libsdl: Selects libsdl outputs.

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.

CROSSFADE DURATION {seconds}

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 ₅ seconds, soft rock 5–10 seconds.

CROSSFADE LEVEL {level}

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.

PREROLL DURATION {seconds}

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:

• Don’t run the daemon as root.
• Isolate the daemon in its own user account, without access to other users’ files.
• Prevent Internet access to pianod via a firewall.
• Keep visitor privilege level set low.
• Use good passwords on administrator accounts.

Linux

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:

MIN_FLUSH_TIME

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.

MAX_FLUSH_TIME

The maximum time, in milliseconds, before pianod closes audio, even if it’s allegedly still buffering. Default is 2000, or 2 seconds.

Example:

room reconfigure options "min_flush_time=2000; max_flush_time=5000"

ffmpeg/libavdevice with ALSA

libavdevice may not default to the ALSA driver.

ROOM RECONFIGURE DRIVER "alsa"

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

ROOM RECONFIGURE OPTIONS "strict=experimental"