Paraslash Audio Streaming
	About   News   Download   Documentation   Development

para_audiod

para_audiod - connect to para_server, receive, decode and play audio streams

para_audiod [--help] [--detailed-help] [--version] [--config-file=<filename>] [--loglevel=<severity>] [--logfile=<filename>] [--color=<when>] [--log-color=<color_spec>] [--log-timing] [--daemon] [--user=<username>] [--group=<groupname>] [--priority=<prio>] [--force] [--mode=<mode>] [--socket=<path>] [--user-allow=<username>] [--clock-diff-count=<count>] [--receiver=<receiver_spec>] [--filter=<filter_spec>] [--writer=<writer_spec>] [--stream-delay=<count>]

para_audiod runs on a host with an audio device and connects para_server to obtain status information and receive the current audio stream. The stream is transformed through any number of filters and then written to the configured output device.

Moreover, para_audiod listens on a local socket and sends status information to local clients on request. Access to the local socket can be restricted by means of Unix socket credentials, if available.

Common options
The following options are implemented generically and are available for many of the commands.
-h, --help

print help and exit

--detailed-help

print help, including all details, and exit

-V, --version

print version and exit

-c, --config-file=<filename>

path to alternative config file

default: ~/.paraslash/audiod.conf

para_audiod reads its config file right after parsing the options that were given at the command line. If an option is given both at the command line and in the config file, the value that was specified at the command line takes precedence.

-l, --loglevel=<severity>

control amount of logging

values: debug, info, notice, warning, error, crit, emerg

Log only messages with severity greater or equal than the given value. Possible values:

debug: Produces really noisy output. info: Still noisy, but won’t fill up the disk quickly. notice: Indicates normal, but significant event. warning: Unexpected events that can be handled. error: Unhandled error condition. crit: System might be unreliable. emerg: Last message before exit.

-L, --logfile=<filename>

where to write log output

If this option is not given, para_audiod writes the log messages to stderr.

-C, --color=<when>

activate color output

values: yes, no, auto

--log-color=<color_spec>

select a color for one type of log message

The format of <color_spec> is [<fg> [<bg>]] [<attr>].

Valid colors for <fg> and <bg> are "normal", "black", "red", "green", "yellow", "blue", "magenta", "cyan", and "white".

The <attr> value must be one of "bold", "dim", "ul", "blink", "reverse".

Examples:

--log-color "debug:green" --log-color "info:yellow bold" --log-color "notice:white red bold"

-T, --log-timing

show milliseconds in log messages

Selecting this option causes milliseconds to be included in the log message output. This allows measuring of the interval between log messages in milliseconds which is useful for identifying timing problems.

-d, --daemon

run as background daemon

If this option is given and no logfile was specified, all messages go to /dev/null.

-u, --user=<username>

run as the given user

para_audiod does not need any special privileges.

If started as root (EUID == 0) this option must be given at the command line (not in the configuration file) so that para_audiod can drop the root privileges right after parsing the command line options, but before parsing the configuration file. In this case, real/effective/saved UID are all set to the UID of <username>. As the configuration file is read afterwards, those options that have a default value depending on the UID (e.g. the directory for the configuration file) are computed by using the uid of <username>. This option has no effect if para_audiod is started as a non-root user (i.e. EUID != 0).

-g, --group=<groupname>

set group id

This option sets the group id according to <group>. This option is silently ignored if EUID != 0. Otherwise, real/effective GID and the saved set-group ID are all set to the GID given by <group>. Must not be given in the config file.

--priority=<prio>

adjust scheduling priority

default: 0

The priority (also known as nice value) is a value in the range -20 to 19. Lower priorities cause more favorable scheduling. Since only privileged processes may request a negative priority, specifying a negative value works only if the daemon is started with root privileges.

Options for para_audiod
-F, --force

force startup

If this flag is not given, para_audiod refuses to start if the well-known socket file (see the --socket option) already exists because this usually means that para_audiod is already running and listening on that socket. After a crash or if para_audiod received a SIGKILL signal, a stale socket file might remain and you have to use --force once to force startup of para_audiod.

--mode=<mode>

select startup mode

values: on, off, sb

para_audiod supports three modes of operation: On, off and standby (sb). This option selects the mode that should be used at startup. If mode is "on", para_audiiod connects para_server to receive status information. If the server announces the availability of an audio stream, para_audiod downloads, decodes and plays the audio stream according to the given stream I/O options, see below.

In "standby" mode, para_audiod only receives the status information from para_server but does not download the audio stream.

In "off" mode, para_audiod does not connect para_server at all, but still listens on the local socket.

-s, --socket=<path>

path to the well-known socket

para_audiod listens on a "well-known" socket for connections from para_audioc. This socket is a special file in the file system; its location defaults to /var/paraslash/audiod_sock.$hostname.

para_audioc, the client program used to connect to para_audiod, opens this socket in order to talk to para_audiod. If the default value for para_audiod is changed, para_audioc must be instructed to use also <path> to connect para_audiod.

--user-allow=<username>

allow this user to connect to audiod

Allow the user identified by username (either a string or a UID) to connect to para_audiod. This option may be given multiple times. If not specified at all, all users are allowed to connect.

This feature is based on the ability to send unix credentials through local sockets using ancillary data (SCM_CREDENTIALS). Currently it only works on Linux. On other operating systems the option is silently ignored and all local users are allowed to connect.

--clock-diff-count=<count>

sync clock on startup

Check the clock difference between the host running para_server and the local host running para_audiod this many times before starting any stream I/0. Set this to non-zero for non-local setups if the clocks of these two hosts are not synchronized by ntp or similar.

Stream I/O options
-r, --receiver=<receiver_spec>

select receiver

default: http

This option may be given multiple times, for each audio format separately. If multiple definitions for an audio format are given, the first one is selected.

The <receiver_spec> consists of an audio format specifier and one or more receiver arguments, separated by a colon.

The audio format specifier is a regular expression which specifies the set of audio formats for which this option should apply.

If any receiver options are present, the whole receiver argument must be quoted:

-r ’mp3:http -i my.host.org -p 8009’

Since a single dot ’.’ matches the name of any audio format, specifying ’.’ instead of ’mp3’ above activates the http receiver for all audio formats.

-f, --filter=<filter_spec>

specify the filter configuration

This option may be given multiple times. The <filter_spec< consists of an audio format specifier (see above), the name of the filter, and any options for that filter. Note that order matters.

The compiled-in defaults apply to all audio formats for which no --filter option was given. These defaults depend on the receiver being used.

For HTTP streams, only the decoder for the current audio format is activated. UDP and DCCP streams, on the other hand, are sent FEC-encoded by para_server. In order to play such streams, the receiver output must be FEC-decoded first, i.e. fed to the fecdec filter. Therefore the default for UDP and DCCP streams is to activate the fecdec filter, followed by the decoding filter for the audio format.

Examples:

--filter ’mp3:mp3dec’

--filter ’mp3|aac:compress --inertia 5 --damp 2’

--filter ’.:fecdec’

-w, --writer=<writer_spec>

specify one or more stream writers

May be given multiple times, even multiple times for the same audio format. The default is to use the first supported writer. Example:

--writer ’aac|wma:oss’

--stream-delay=<count>

specify time interval for client sync

Check the clock difference between the host running para_server and the local host running para_audiod this many times before starting any stream I/0. Set this to non-zero for non-local setups if the clocks of these two hosts are not synchronized by ntp or similar.

cycle - switch to next operating mode
Usage: cycle

Cycle through the three operation modes (on, standby, off).

help - list available commands or print command-specific help
Usage: help [--long] [--] [subcommand]

When executed without any arguments, the available audiod commands are listed. Otherwise, if the first argument is the name of an audiod command, the description of this command is shown.
-l, --long

show the long help text

If no non-option argument is supplied to the help subcommand and --long is not given, only the names of all subcommands are shown. With --long the purpose of each command is printed as well.

If the name of a subcommand is supplied and --long is given, the help text for the given subcommand contains the synopsis, the purpose and the description of the specified command, followed by the option list including summary and help text of each option. Without --long the description of the command and the option help are omitted.

grab - grab the audio stream
Usage: grab [--mode=<mode>] [--parent=<node>] [--name[=<string>]] [--one-shot]

grab (’splice’) the audio stream at any position in the buffer tree and send that data back to the client.
-m, --mode=<mode>

change grab mode

default: s

The various grab modes only differ in what happens if an attempt to write the grabbed audio data would block. Sloppy mode ("s") ignores the write, pedantic mode ("p") aborts and aggressive mode ("a") tries to write anyway.

-p, --parent=<node>

Grab output of the given node of the buffer tree

-n, --name[=<string>]

Name of the new buffer tree node. Defaults to ’grab’

-o, --one-shot

One-shot mode: Stop grabbing if audio file changes

ll - Query or set the log level of the daemon
Usage: ll [severity]

If no argument is given, the command prints the severity string (one of the possible string arguments to --loglevel) which corresponds to the current loglevel. Otherwise, if the given argument is a severity string, the current log level is set accordingly.

off - deactivate para_audiod
Usage: off

Close connection to para_server and stop all decoders.

on - activate para_audiod
Usage: on

Establish connection to para_server, retrieve para_server’s current status. If playing, start corresponding decoder. Otherwise stop all decoders.

sb - enter standby mode
Usage: sb

Stop all decoders but leave connection to para_server open.

stat - print status information
Usage: stat [--parser-friendly] [--] [item...]

Dump given status items (all if none given) to stdout.
-p, --parser-friendly

use parser-friendly output format

version - print the version of para_audiod
Usage: version [--verbose]
-v, --verbose

print detailed (multi-line) version text

tasks - list current tasks
Usage: tasks

Print the list of task ids together with the status of each task.

term - terminate para_audiod
Usage: term

Stop all decoders, shut down connection to para_server and exit.

afh - make an audio stream from a local file
Usage: afh [--filename=<filename>] [--begin-chunk=<chunk_num>] [--end-chunk=<chunk_num>] [--just-in-time] [--no-header]

The afh (audio format handler) receiver extracts selected parts of the given audio file without decoding the file. Only complete chunks with respect to the underlying audio format are extracted.
-f, --filename=<filename>

file to open

-b, --begin-chunk=<chunk_num>

skip the beginning of the file

The argument must be an integer between -num_chunks and num_chunks - 1, inclusively, where num_chunks is the total number of chunks. If chunk_num is negative, the given number of chunks are counted backwards from the end of the file. For example --begin-chunk -100 instructs the afh receiver to start at chunk num_chunks - 100. This is useful for cutting off the beginning of an audio file.

-e, --end-chunk=<chunk_num>

only write up to chunk chunk_num

For the chunk_num argument the same rules as for --begin-chunk apply. The default is to write up to the last chunk.

-j, --just-in-time

use timed writes

Write the specified data chunks ’just in time’, i.e., delay the write until data is needed by the decoder/player for an uninterrupted audio stream. This may be useful for third-party software.

-h, --no-header

do not write an audio file header

Some audio formats store information about the audio file in a format-specific header which is needed to decode any part of the file. For such formats the afh receiver generates a suitable header. This option changes the default behaviour, i.e. no header is written.

http - receive an audio stream over HTTP
Usage: http [--host=<host>] [--port=<portnumber>]
-i, --host=<host>

IP address or hostname

default: localhost

Both IPv4 and IPv6 addresses are supported.

-p, --port=<portnumber>

TCP port to connect to

default: 8000

dccp - receive an audio stream over DCCP
Usage: dccp [--host=<host>] [--port=<portnumber>] [--ccid=<id>]
-i, --host=<host>

IP address or hostname

default: localhost

Both IPv4 and IPv6 addresses are supported.

-p, --port=<portnumber>

TCP port to connect to

default: 8000

-c, --ccid=<id>

CCID preference(s) for this connection

When present exactly once, this option mandates the CCID for the sender-receiver connection. If it is passed more than once, it sets a preference list where the order of appearance signifies descending priority. For example, passing 4, 2, 3 creates the preference list (CCID-4, CCID-2, CCID-3), assigning CCID-4 highest preference.

The request is reconciled with the CCIDs on the server through the ’server-priority’ mechanism of RFC 4340 6.3.1/10. The server CCIDs can be listed by calling ’para_client sender dccp status’.

udp - receive an audio stream over UDP
Usage: udp [--host=<host>] [--port=<portnumber>] [--iface=<iface-name>]
-i, --host=<host>

IP address or hostname

default: 224.0.1.38

The default address resolves to DANTZ.MCAST.NET and activates multicast.

-p, --port=<portnumber>

TCP port to connect to

default: 8000

--iface=<iface-name>

receiving udp multicast interface

aacdec - decode an aac stream
Usage: aacdec

amp - amplify (scale) a raw audio stream
Usage: amp [--amp=<number>]
-a, --amp=<number>

amplification value

default: 32

The amplification value determines the scaling factor by which the amplitude of the audio stream is multiplied. The formula for the scaling factor is

factor = 1 + amp / 64.

For example, an amplification value of zero results in a scaling factor of one while an amplification value of 64 means to double the volume.

compress - dynamically adjust the volume of an audio stream
Usage: compress [--blocksize=<bits>] [--aggressiveness=<bits>] [--inertia=<bits>] [--target-level=<level>] [--damp=<bits>]
-b, --blocksize=<bits>

adjust volume after each block of size 2**bits (1-31)

default: 15

Larger blocksize means fewer volume adjustments per time unit.

-a, --aggressiveness=<bits>

controls the maximum amount to amplify by (0-10)

default: 4

This controls the maximal gain factor. Zero means to not amplify at all while the value 10 corresponds to maximal gain factor which results in a 4-fold increase in volume.

-i, --inertia=<bits>

how much inertia ramping has (1-14)

default: 6

Larger values cause smaller volume adjustments.

-t, --target-level=<level>

target signal level (0-32767)

default: 16384

If the peak of the previous block is less than the target level, volume is increased slightly for the next block. Otherwise it is decreased. The default value is chosen to minimize clipping. There is usually no reason to change it.

-d, --damp=<bits>

if non-zero, scale down after normalizing (0-16)

default: 0

This scales down the volume of the audio stream by factor 2**bits. This is mostly useful if another audio application (e.g., a video game) is running in parallel and the relative volume of the audio stream is too high.

fecdec - decode a (lossy) input stream using forward error correction
Usage: fecdec

flacdec - decode a flac stream
Usage: flacdec

mp3dec - decode an mp3 stream
Usage: mp3dec [--ignore-crc]
-i, --ignore-crc

ignore CRC information in the audio stream

This causes frames with CRC errors to be decoded and played anyway. This option is not recommended, but since some encoders have been known to generate bad CRC information, this option is a work-around to play streams from such encoders.

oggdec - decode an ogg/vorbis stream
Usage: oggdec

opusdec - decode an ogg/opus stream
Usage: opusdec

prebuffer - delay processing of an audio stream
Usage: prebuffer [--duration=<milliseconds>] [--size=<bytes>]
-d, --duration=<milliseconds>

length of the prebuffer period

default: 200

Wait this many milliseconds before letting data go through. The time interval starts when the first data byte is seen in the input queue.

-s, --size=<bytes>

amount of data to prebuffer

default: 0

Wait until this many data bytes are available in the input queue. The default value of zero means to not prebuffer by size. If both --duration and --size are given and non-zero, the prebuffer filter waits until both conditions are met.

resample - transform raw audio to a different sample rate
Usage: resample [--converter=<type>] [--dest-sample-rate=<rate>] [--channels=<num>] [--sample-rate=<rate>] [--sample-format=<format>]
-C, --converter=<type>

set conversion algorithm

values: best, medium, fastest, zero_order_hold, linear

best: This is a bandlimited interpolator derived from the mathematical sinc function and this is the highest quality sinc based converter, providing a worst case Signal-to-Noise Ratio (SNR) of 97 decibels (dB) at a bandwidth of 97%.

medium: This is another bandlimited interpolator much like the previous one. It has an SNR of 97dB and a bandwidth of 90%. The speed of the conversion is much faster than the previous one.

fastest: This is the fastest bandlimited interpolator and has an SNR of 97dB and a bandwidth of 80%.

zero_order_hold: A Zero Order Hold converter (interpolated value is equal to the last value). The quality is poor but the conversion speed is blindlingly fast.

linear: A linear converter. Again the quality is poor, but the conversion speed is blindingly fast.

-d, --dest-sample-rate=<rate>

sample rate to convert to

default: 44100

-c, --channels=<num>

specify number of channels

default: 2

It is only necessary to specify this option for raw audio. If it is not given, the channel count is queried from the parent buffer tree nodes (e.g. the decoder) or the wav header. Only if this query fails, the default value applies.

-s, --sample-rate=<rate>

do not guess the input sample rate

default: 44100

It is only necessary to specify this for raw audio. See the discussion of the --channels option.

-f, --sample-format=<format>

specify sample format

values: S8, U8, S16_LE, S16_BE, U16_LE, U16_BE

It is only necessary to specify this for raw audio. See the discussion of the --channels option.

spxdec - decode an ogg/speex stream
Usage: spxdec

sync - synchronize playback between multiple clients
Usage: sync [--buddy=<url>] [--port=<portnumber>] [--timeout=<milliseconds>]
-b, --buddy=<url>

client to synchronize with

This option may be given multiple times, one per buddy. Each value may be given as a host, port pair in either IPv4 or IPv6 form, with port being optional. If no port was specified the listening port (as specified with --port, see below) is used to send the synchronization packet to this buddy.

-p, --port=<portnumber>

UDP port for incoming synchronization packets

default: 29900

The sync filter expects incoming synchronization packets on this UDP port.

-t, --timeout=<milliseconds>

how long to wait for other clients

default: 2000

Once the sync filter receives its first chunk of input, a synchronization period of the given number of milliseconds begins. Playback is deferred until a synchronization packet has been received from each defined buddy, or until the end of the period. Buddies which did not send a synchronization packet in time are temporarily disabled and are not waited for during subsequent synchronization periods. They are re-enabled automatically when another synchronization packet arrives.

wav - insert a Microsoft wave header into a raw audio stream
Usage: wav

wmadec - decode a wma stream
Usage: wmadec

alsa - native ALSA output plugin
Usage: alsa [--device=<device>] [--buffer-time=<milliseconds>]
-d, --device=<device>

set PCM device

default: default

Check for the presence of a /proc/asound/ directory to see if ALSA is present in your kernel. The file /proc/asound/devices contains all devices ALSA knows about.

-B, --buffer-time=<milliseconds>

duration of the ALSA buffer

default: 170

This is only a hint as ALSA might pick a slightly different time, depending on the sound hardware. The chosen value is shown in debug output as BUFFER_TIME.

If synchronization between multiple clients is desired, the same buffer time should be configured for all clients.

ao - output plugin for libao
Usage: ao [--driver=<name>] [--ao-option=<key:value>]
-d, --driver=<name>

select a output driver by name

If this is not given, the driver with the highest priority will be used. The list of available drivers and their priorities is shown in debug mode.

-o, --ao-option=<key:value>

pass a key-value pair to the libao driver

For each time this option is given, the supplied key-value pair is appended to the list of options for the driver. Invalid keys are silently ignored. The list of available keys is shown in debug mode.

oss - output plugin for the Open Sound System
Usage: oss [--device=<path>]
-d, --device=<path>

set PCM device

default: /dev/dsp

file - output plugin that writes to a local file
Usage: file [--filename=<path>]
-f, --filename=<path>

specify output file name

Defaults to a random filename in ~/.paraslash.

Written by Andre Noll
Copyright (C) 2024 Andre Noll
License: GNU GPL version 2
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Report bugs to Andre Noll