alsa

Linux ALSA sound system driver. More...

Linux ALSA sound system driver.

This driver provides access to sound playing and recording functionality through the Advanced Linux Sound Architecture (ALSA) system available on 2.6 series kernels (and before via patches/separate libraries).

Not all of the audio interface is supported. Currently supported features are:

PLAYER_AUDIO_CMD_WAV_PLAY - Play raw PCM wave data PLAYER_AUDIO_CMD_SAMPLE_PLAY - Play locally stored and remotely provided samples PLAYER_AUDIO_CMD_WAV_STREAM_REC - Toggle streamed-to-client recording PLAYER_AUDIO_CMD_MIXER_CHANNEL - Change volume levels PLAYER_AUDIO_REQ_MIXER_CHANNEL_LIST - Get channel details PLAYER_AUDIO_REQ_MIXER_CHANNEL_LEVEL - Get volume levels PLAYER_AUDIO_REQ_SAMPLE_LOAD - Store samples provided by remote clients (max 1MB) PLAYER_AUDIO_REQ_SAMPLE_RETRIEVE - Send stored samples to remote clients (max 1MB) PLAYER_AUDIO_REQ_SAMPLE_REC - Record new samples directly on the server

Known bugs:

• Sounds may skip just as they finish playing. This is something to do with the call to snd_pcm_drain.

Samples

Locally stored samples are preferred to samples loaded over the network or using the PLAYER_AUDIO_CMD_WAV_PLAY message for a number of reasons:

• It takes time to transfer large quantities of wave data over the network.
• Remotely provided samples are stored in memory, local samples are only loaded when played. If you have a lot of samples provided remotely, the memory use will be high.
• Local samples are not limited to only the formats (bits per sample, sample rate, etc) that player supports. They can be any standard WAV format file that uses a format for the audio data supported by ALSA.
• Remote samples can only be up to 1MB in size. This limits you to about 6 seconds of audio data at 44100Hz, 16 bit, stereo. Local samples can be as big as you have memory. A future version of the driver will implement play-on-read, meaning local samples will only be limited by disc space to store them.

When retrieving samples from the server via the PLAYER_AUDIO_REQ_SAMPLE_RETRIEVE request, note that any sample with a data length greater than PLAYER_AUDIO_WAV_BUFFER_SIZE will be truncated to this size.

When using the PLAYER_AUDIO_REQ_SAMPLE_LOAD and PLAYER_AUDIO_REQ_SAMPLE_REC messages to store samples, currently only appending and overwriting existing samples is allowed. Trying to store at a specific index greater than the number of currently stored samples will result in an error. Note that the samples indices are 0-based, so if there are 5 samples stored and you request to store one at index 5 (technically beyond the end of the list), it will append to the end and become the sample at index 5. TODO: Talk to Toby to clarify his intentions for the index in this message.

Provides

The driver provides a single audio interface.

Configuration file options

• samples (tuple of strings)
  • Default: empty
  • The path of wave files to have as locally stored samples.
• pbdevice (string)
  • Default: none
  • The device to use for playback.
  • If none, playback functionality will not be available.
  • e.g. "plughw:0,0"
  • The order of arguments in this string, according to the ALSA documentation, are card number or identifier, device number and subdevice.
• pb_bufferlength (integer)
  • Default: 500ms
  • The length of the playback buffer. A longer buffer means less chance of skipping during playback.
• pb_periodlength (integer)
  • Default: 50ms
  • The length of a period. This is used to change how frequently the buffer is written to. The longer the period, the longer it takes to write, but also the less frequently it will be done.
• pb_silence (integer)
  • Default: 0ms
  • The length of silence to play between consecutive sounds. Useful if you don't want your sounds played right up next to eachother, but bad if you're streaming a sound that's bigger than a single wave data message.
  • If usequeue is false, this will be ignored.
• usequeue (boolean)
  • Default: true
  • Turns the queuing system on/off. When true, all PLAYER_AUDIO_CMD_WAV_PLAY and PLAYER_AUDIO_CMD_SAMPLE_PLAY commands will be added to a queue and played in order of request. When off, sending a new command will stop the currently playing sound and start the new one.
• recdevice (string)
  • Default: none
  • The device to use for recording.
  • If none, record functionality will not be available.
  • e.g. "plughw:0,0"
  • The order of arguments in this string, according to the ALSA documentation, are card number or identifier, device number and subdevice.
• rec_bufferlength (integer)
  • Default: 500ms
  • The length of the record buffer. A longer buffer means less chance of an underrun while recording.
• rec_storelength (integer)
  • Default: Same as rec_bufferlength
  • The length of recorded data to store before sending that data to clients. Can be less than rec_bufferlength.
• rec_periodlength (integer)
  • Default: 50ms
  • The length of a period for recording. This is used to change how frequently the buffer is read from. The longer the period, the longer between reads, but also the less frequently it will be done.
• rec_nch (integer)
  • Default: 1
  • Number of recording channels.
• rec_sr (integer)
  • Default: 44100
  • Recording sample rate.
• rec_bits (integer)
  • Default: 16
  • Bits per sample for recording.
• mixerdevice (string)
  • Default: none
  • The device to attach the mixer interface to
  • If none, mixer functionality will not be available.
  • e.g. "default"
• mixerfilters (tuple of strings)
  • Default: none
  • A typical ALSA mixer contains a large number of elements, providing detailed control over all aspects of the sound system. The disadvantage of this is that many of them will be irrelevant to your needs. This driver option allows the list of available elements presented to clients to be filtered by name. Only those elements whose names include one of the strings in this list will be seen by clients.
  • The strings in this list are case insensitive, and by default do not need to match an element's entire name. If you want to change this, use the mixerfilterexact option.
  • The best way to find the names of the elements you need is to run without a filter list first, get the elements from the server and print them out. Then check which ones you need and use those as the filters.
• mixerfilterexact (bool)
  • Default: false
  • When set to false, filters listed in mixerfilters will not need to match an element's entire name nor be case sensitive.
  • When set to true, an element's name must exactly match a filter to pass.

Example

driver
(
  name "alsa"
  provides ["audio:0"]
  samples ["sample1.wav" "sample2.wav" "sample3.wav"]
  mixerfilters ["master" "pcm" "capture"]
)

Author

Geoffrey Biggs, Lorenz Moesenlechner