PCM (digital audio) plugins

PCM plugins extends functionality and features of PCM devices. The plugins take care about various sample conversions, sample copying among channels and so on.

Slave definition

The slave plugin can be specified directly with a string or the definition can be entered inside a compound configuration node. Some restrictions can be also specified (like static rate or count of channels).

pcm_slave.NAME {
        pcm STR         # PCM name
        # or
        pcm { }         # PCM definition
        format STR      # Format or "unchanged"
        channels INT    # Count of channels or "unchanged" string
        rate INT        # Rate in Hz or "unchanged" string
        period_time INT # Period time in us or "unchanged" string
        buffer_time INT # Buffer time in us or "unchanged" string
}

Example:

pcm_slave.slave_rate44100Hz {
        pcm "hw:0,0"
        rate 44100
}

pcm.rate44100Hz {
        type plug
        slave slave_rate44100Hz
}

The equivalent configuration (in one compound):

pcm.rate44100Hz {
        type plug
        slave {
                pcm "hw:0,0"
                rate 44100
        }
}

Plugin: hw

This plugin communicates directly with the ALSA kernel driver. It is a raw communication without any conversions. The emulation of mmap access can be optionally enabled, but expect worse latency in the case.

pcm.name {
        type hw                 # Kernel PCM
        card INT/STR            # Card name (string) or number (integer)
        [device INT]            # Device number (default 0)
        [subdevice INT]         # Subdevice number (default -1: first available)
        [mmap_emulation BOOL]   # Enable mmap emulation for ro/wo devices
}

Function reference

• snd_pcm_hw_open()
• _snd_pcm_hw_open()

Plugin: shm

This plugin communicates with aserver via shared memory. It is a raw communication without any conversions, but it can be expected worse performance.

pcm.name {
        type shm                # Shared memory PCM
        server STR              # Server name
        pcm STR                 # PCM name
}

Function reference

• snd_pcm_shm_open()
• _snd_pcm_shm_open()

Plugin: Null

This plugin discards contents of a PCM stream or creates a stream with zero samples.

Note: This implementation uses devices /dev/null (playback, must be writable) and /dev/full (capture, must be readable).

pcm.name {
        type null               # Null PCM
}

Function reference

• snd_pcm_null_open()
• _snd_pcm_null_open()

Plugin: copy

This plugin copies samples from master copy PCM to given slave PCM. The channel count, format and rate must match for both of them.

pcm.name {
        type copy               # Copy PCM
        slave STR               # Slave name
        # or
        slave {                 # Slave definition
                pcm STR         # Slave PCM name
                # or
                pcm { }         # Slave PCM definition
        }
}

Function reference

• snd_pcm_copy_open()
• _snd_pcm_copy_open()

Plugin: linear

This plugin converts linear samples from master linear conversion PCM to given slave PCM. The channel count, format and rate must match for both of them.

pcm.name {
        type linear             # Linear conversion PCM
        slave STR               # Slave name
        # or
        slave {                 # Slave definition
                pcm STR         # Slave PCM name
                # or
                pcm { }         # Slave PCM definition
        }
}

Function reference

• snd_pcm_linear_open()
• _snd_pcm_linear_open()

Plugin: linear<->float

This plugin converts linear to float samples and float to linear samples from master linear<->float conversion PCM to given slave PCM. The channel count, format and rate must match for both of them.

pcm.name {
        type lfloat             # Linear<->Float conversion PCM
        slave STR               # Slave name
        # or
        slave {                 # Slave definition
                pcm STR         # Slave PCM name
                # or
                pcm { }         # Slave PCM definition
        }
}

Function reference

• snd_pcm_lfloat_open()
• _snd_pcm_lfloat_open()

Plugin: Mu-Law

This plugin converts Mu-Law samples to linear or linear to Mu-Law samples from master Mu-Law conversion PCM to given slave PCM. The channel count, format and rate must match for both of them.

pcm.name {
        type mulaw              # Mu-Law conversion PCM
        slave STR               # Slave name
        # or
        slave {                 # Slave definition
                pcm STR         # Slave PCM name
                # or
                pcm { }         # Slave PCM definition
        }
}

Function reference

• snd_pcm_mulaw_open()
• _snd_pcm_mulaw_open()

Plugin: A-Law

This plugin converts A-Law samples to linear or linear to A-Law samples from master A-Law conversion PCM to given slave PCM. The channel count, format and rate must match for both of them.

pcm.name {
        type alaw               # A-Law conversion PCM
        slave STR               # Slave name
        # or
        slave {                 # Slave definition
                pcm STR         # Slave PCM name
                # or
                pcm { }         # Slave PCM definition
        }
}

Function reference

• snd_pcm_alaw_open()
• _snd_pcm_alaw_open()

Plugin: Ima-ADPCM

This plugin converts Ima-ADPCM samples to linear or linear to Mu-Law samples from master Ima-ADPCM conversion PCM to given slave PCM. The channel count, format and rate must match for both of them.

pcm.name {
        type adpcm              # Ima-ADPCM conversion PCM
        slave STR               # Slave name
        # or
        slave {                 # Slave definition
                pcm STR         # Slave PCM name
                # or
                pcm { }         # Slave PCM definition
        }
}

Function reference

• snd_pcm_adpcm_open()
• _snd_pcm_adpcm_open()

Plugin: Route & Volume

This plugin converts channels and applies volume during the conversion. The format and rate must match for both of them.

pcm.name {
        type route              # Route & Volume conversion PCM
        slave STR               # Slave name
        # or
        slave {                 # Slave definition
                pcm STR         # Slave PCM name
                # or
                pcm { }         # Slave PCM definition
        }
}

Function reference

• snd_pcm_route_open()
• _snd_pcm_route_open()

Plugin: Rate

This plugin converts a stream rate. The input and output formats must be linear.

pcm.name {
        type rate               # Rate PCM
        slave STR               # Slave name
        # or
        slave {                 # Slave definition
                pcm STR         # Slave PCM name
                # or
                pcm { }         # Slave PCM definition
        }
}

Function reference

• snd_pcm_rate_open()
• _snd_pcm_rate_open()

Automatic conversion plugin

This plugin converts channels, rate and format on request.

pcm.name {
        type plug               # Automatic conversion PCM
        slave STR               # Slave name
        # or
        slave {                 # Slave definition
                pcm STR         # Slave PCM name
                # or
                pcm { }         # Slave PCM definition
                [format STR]    # Slave format (default nearest) or "unchanged"
                [channels INT]  # Slave channels (default nearest) or "unchanged"
                [rate INT]      # Slave rate (default nearest) or "unchanged"
        }
        route_policy STR        # route policy for automatic ttable generation
                                # STR can be 'default', 'average', 'copy', 'duplicate'
                                # average: result is average of input channels
                                # copy: only first channels are copied to destination
                                # duplicate: duplicate first set of channels
                                # default: copy policy, except for mono capture - sum
        ttable {                # Transfer table (bi-dimensional compound of cchannels * schannels numbers)
                CCHANNEL {
                        SCHANNEL REAL   # route value (0.0 - 1.0)
                }
        }
}

Function reference

• snd_pcm_plug_open()
• _snd_pcm_plug_open()

Plugin: File

This plugin stores contents of a PCM stream to file.

pcm.name {
        type file               # File PCM
        slave STR               # Slave name
        # or
        slave {                 # Slave definition
                pcm STR         # Slave PCM name
                # or
                pcm { }         # Slave PCM definition
        }
        file STR                # Filename
        or
        file INT                # File descriptor number
        [format STR]            # File format (only "raw" at the moment)
}

Function reference

• snd_pcm_file_open()
• _snd_pcm_file_open()

Plugin: Multiple streams to One

This plugin converts multiple streams to one.

pcm.name {
        type multi              # Multiple streams conversion PCM
        slaves {                # Slaves definition
                ID STR          # Slave PCM name
                # or
                ID {
                        pcm STR         # Slave PCM name
                        # or
                        pcm { }         # Slave PCM definition
                        channels INT    # Slave channels
                }
        }
        bindings {              # Bindings table
                N {
                        slave STR       # Slave key
                        channel INT     # Slave channel
                }
        }
        [master INT]            # Define the master slave
}

Function reference

• snd_pcm_multi_open()
• _snd_pcm_multi_open()

Plugin: Share

This plugin allows sharing of multiple channels with more clients. The access to each channel is exlusive (samples are not mixed together). It means, if the channel zero is used with first client, the channel cannot be used with second one. If you are looking for a mixing plugin, use the dmix plugin.

pcm.name {
        type share              # Share PCM
        slave STR               # Slave name
        # or
        slave {                 # Slave definition
                pcm STR         # Slave PCM name
        }
        bindings {
                N INT           # Slave channel INT for client channel N
        }
}

Function reference

• snd_pcm_share_open()
• _snd_pcm_share_open()

Plugin: hooks

# Hook arguments definition
hook_args.NAME {
        ...                     # Arbitrary arguments
}

# PCM hook type
pcm_hook_type.NAME {
        [lib STR]               # Library file (default libasound.so)
        [install STR]           # Install function (default _snd_pcm_hook_NAME_install)
}

# PCM hook definition
pcm_hook.NAME {
        type STR                # PCM Hook type (see pcm_hook_type)
        [args STR]              # Arguments for install function (see hook_args)
        # or
        [args { }]              # Arguments for install function
}

# PCM hook plugin
pcm.NAME {
        type hooks              # PCM with hooks
        slave STR               # Slave name
        # or
        slave {                 # Slave definition
                pcm STR         # Slave PCM name
                # or
                pcm { }         # Slave PCM definition
        }
        hooks {
                ID STR          # Hook name (see pcm_hook)
                # or
                ID { }          # Hook definition (see pcm_hook)
        }
}

Example:

        hooks.0 {
                type ctl_elems
                hook_args [
                        {
                                name "Wave Surround Playback Volume"
                                preserve true
                                lock true
                                value [ 0 0 ]
                        }
                        {
                                name "EMU10K1 PCM Send Volume"
                                index { @func private_pcm_subdevice }
                                lock true
                                value [ 0 0 0 0 0 0 255 0 0 0 0 255 ]
                        }
                ]
        }

Function reference

• The function ctl_elems - _snd_pcm_hook_ctl_elems_install() - installs CTL settings described by given configuration.
• snd_pcm_hooks_open()
• _snd_pcm_hooks_open()

Plugin: dmix

This plugin provides direct mixing of multiple streams. The resolution for 32-bit mixing is only 24-bit. The low significant byte is filled with zeros. The extra 8 bits are used for the saturation.

pcm.name {
        type dmix               # Direct mix
        ipc_key INT             # unique IPC key
        ipc_key_add_uid BOOL    # add current uid to unique IPC key
        slave STR
        # or
        slave {                 # Slave definition
                pcm STR         # slave PCM name
                # or
                pcm { }         # slave PCM definition
                format STR      # format definition
                rate INT        # rate definition
                channels INT
                period_time INT # in usec
                # or
                period_size INT # in bytes
                buffer_time INT # in usec
                # or
                buffer_size INT # in bytes
                periods INT     # when buffer_size or buffer_time is not specified
        }
        bindings {              # note: this is client independent!!!
                N INT           # maps slave channel to client channel N
        }
}

Function reference

• snd_pcm_dmix_open()
• _snd_pcm_dmix_open()

Plugin: dshare

This plugin provides sharing channels.

pcm.name {
        type dshare             # Direct sharing
        ipc_key INT             # unique IPC key
        ipc_key_add_uid BOOL    # add current uid to unique IPC key
        slave STR
        # or
        slave {                 # Slave definition
                pcm STR         # slave PCM name
                # or
                pcm { }         # slave PCM definition
                format STR      # format definition
                rate INT        # rate definition
                channels INT
                period_time INT # in usec
                # or
                period_size INT # in bytes
                buffer_time INT # in usec
                # or
                buffer_size INT # in bytes
                periods INT     # when buffer_size or buffer_time is not specified
        }
        bindings {              # note: this is client independent!!!
                N INT           # maps slave channel to client channel N
        }
}

Function reference

• snd_pcm_dshare_open()
• _snd_pcm_dshare_open()

Plugin: dsnoop

This plugin splits one capture stream to more.

pcm.name {
        type dsnoop             # Direct snoop
        ipc_key INT             # unique IPC key
        ipc_key_add_uid BOOL    # add current uid to unique IPC key
        slave STR
        # or
        slave {                 # Slave definition
                pcm STR         # slave PCM name
                # or
                pcm { }         # slave PCM definition
                format STR      # format definition
                rate INT        # rate definition
                channels INT
                period_time INT # in usec
                # or
                period_size INT # in bytes
                buffer_time INT # in usec
                # or
                buffer_size INT # in bytes
                periods INT     # when buffer_size or buffer_time is not specified
        }
        bindings {              # note: this is client independent!!!
                N INT           # maps slave channel to client channel N
        }
}

Function reference

• snd_pcm_dsnoop_open()
• _snd_pcm_dsnoop_open()

Plugin: LADSPA <-> ALSA

This plugin allows to apply a set of LADPSA plugins. The input and output format is always SND_PCM_FORMAT_FLOAT (note: this type can be either little or big-endian depending on architecture).

The policy duplicate means that there must be only one binding definition for channel zero. This definition is automatically duplicated for all channels.

Instances of LADSPA plugins are created dynamically.

pcm.name {
        type ladspa             # ALSA<->LADSPA PCM
        slave STR               # Slave name
        # or
        slave {                 # Slave definition
                pcm STR         # Slave PCM name
                # or
                pcm { }         # Slave PCM definition
        }
        [path STR]              # Path (directory) with LADSPA plugins
        plugins |               # Definition for both directions
        playback_plugins |      # Definition for playback direction
        capture_plugins {       # Definition for capture direction
                N {             # Configuration for LADPSA plugin N
                        [id INT]        # LADSPA plugin ID (for example 1043)
                        [label STR]     # LADSPA plugin label (for example 'delay_5s')
                        [filename STR]  # Full filename of .so library with LADSPA plugin code
                        [policy STR]    # Policy can be 'none' or 'duplicate'
                        input | output {
                                bindings {
                                        C INT or STR    # C - channel, INT - audio port index, STR - audio port name
                                }
                                controls {
                                        I INT or REAL   # I - control port index, INT or REAL - control value
                                        # or
                                        STR INT or REAL # STR - control port name, INT or REAL - control value
                                }
                        }
                }
        }
}

Function reference

• snd_pcm_ladspa_open()
• _snd_pcm_ladspa_open()

---