From: Mike Brady Date: Mon, 28 Oct 2019 08:53:04 +0000 (+0000) Subject: Fix a compilation error and tidy up some messages. X-Git-Tag: 3.3.4~3 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=54d132385114fafe1aee73aeff98f44fef4d8c3c;p=thirdparty%2Fshairport-sync.git Fix a compilation error and tidy up some messages. --- diff --git a/FFTConvolver/convolver.cpp b/FFTConvolver/convolver.cpp index f115cf85..3f08f0c6 100644 --- a/FFTConvolver/convolver.cpp +++ b/FFTConvolver/convolver.cpp @@ -5,8 +5,11 @@ #include "FFTConvolver.h" #include "Utilities.h" -extern "C" void die(const char *format, ...); -extern "C" void debug(int level, const char *format, ...); +extern "C" void _die(const char *filename, const int linenumber, const char *format, ...); +extern "C" void _debug(const char *filename, const int linenumber, int level, const char *format, ...); + +#define die(...) _die(__FILE__, __LINE__, __VA_ARGS__) +#define debug(...) _debug(__FILE__, __LINE__, __VA_ARGS__) static fftconvolver::FFTConvolver convolver_l; static fftconvolver::FFTConvolver convolver_r; diff --git a/configure.ac b/configure.ac index 00dae632..f5cad1b2 100644 --- a/configure.ac +++ b/configure.ac @@ -298,7 +298,7 @@ AC_ARG_WITH(convolution, [ --with-convolution = choose audio DSP convolution su REQUESTED_CONVOLUTION=1 AM_INIT_AUTOMAKE([subdir-objects]) AC_DEFINE([CONFIG_CONVOLUTION], 1, [Needed by the compiler.]) - AC_CHECK_LIB([sndfile], [sf_open], , AC_MSG_ERROR(Convolution support requires the sndfile library!))], ) + AC_CHECK_LIB([sndfile], [sf_open], , AC_MSG_ERROR(Convolution support requires the sndfile library -- libsndfile1-dev suggested!))], ) AM_CONDITIONAL([USE_CONVOLUTION], [test "x$REQUESTED_CONVOLUTION" = "x1"]) # Look for dns_sd flag diff --git a/man/shairport-sync.html b/man/shairport-sync.html index c16a56ea..316f47fe 100644 --- a/man/shairport-sync.html +++ b/man/shairport-sync.html @@ -1,1199 +1,28 @@

shairport-sync

Synchronised Audio Player for iTunes / AirPlay

- - -

Synopsis

- - - shairport-sync [-djvuw] - [-a name] - [-A latency] - [-B command] - [-c configurationfile] - [-E command] - [--get-cover-art] - [--logOutputLevel] - [-L latency] - [-m backend] - [--meta-dir=directory] - [-o backend] - [--password=secret] - [-r threshold] - [--statistics] - [-S mode] - [-t timeout] - [--tolerance=frames] - [-- audio_backend_options] -
- - shairport-sync -k
- - shairport-sync -h
- - shairport-sync -V
- - - - -

Description

- -

Shairport Sync plays - audio streamed from iTunes - or from an AirPlay device to an ALSA-compatible audio output device (available on - Linux and FreeBSD), to a "sndio" output device (available on OpenBSD, FreeBSD and - Linux), to a PulseAudio output stream or to Jack Audio.

- -

Shairport Sync offers full audio synchronisation. - Full audio synchronisation means that audio is played on the output device at exactly - the time specified by the audio source. - This means that if many devices are playing the same stream at the same - time, all the outputs will stay in synchrony with one another. - This allows multiple devices to play the same source without getting out of step with - one another, enabling, for example, simultaneous multi-room operation. -

- -

Shairport Sync can stream synchronised audio to a unix - pipe or to standard output, or to audio systems that do not provide timing - information. This could perhaps be described as partial audio synchronisation, where - synchronised audio is provided by Shairport Sync, but what happens to it in the - subsequent processing chain, before it reaches the listener's ear, is outside the - control of shairport-sync.

Shairport Sync can be compiled to stream metadata, including cover art, to a pipe - or socket.

Shairport Sync can be compiled to offer a standard MPRIS interface, a "native" - D-Bus interface and an MQTT client interface. Through these interfaces, it can provide - metadata, including cover art, and can offer remote control of the audio source.

- -

Settings can be made using the configuration file (recommended for all new - installations) or by using command-line options.

- -

The name of the Shairport Sync executable is shairport-sync. - Both names are used in these man pages.

- - - - - -

Configuration File Settings

- -

You should use the configuration file for setting up Shairport Sync. - This file is usually shairport-sync.conf and is generally located in the - System Configuration Directory, which is normally the /etc directory in - Linux or the /usr/local/etc directory in BSD unixes. - You may need to have root privileges to modify it.

- -

(Note: Shairport Sync may have been compiled to use a different configuration - directory. You can determine which by performing the command $ shairport-sync - -V. One of the items in the output string is the value of the - sysconfdir, - i.e. the System Configuration Directory.)

- - -

Within the configuraton file, settings are organised into groups, for - example, there is a "general" group of - standard settings, and there is an "alsa" group with settings that pertain to the ALSA - back end. Here is an example of a typical configuration file:

- -

general = {

name = "Mike's Boombox";

interpolation = "soxr";

password = "secret";

output_backend = "alsa";

};

alsa = {

output_device = "hw:0";

mixer_control_name = "PCM";

};

- -

Most settings have sensible default values, so -- as in the example above -- users - generally only need to set (1) the service name, (2) a password (if desired) and - (3) the output device. If the output device has a mixer that can be used for volume - control, then (4) the volume control's name should be specified. It is highly - desirable to use the output device's mixer for volume control, if available -- - response time is reduced to zero and the processor load is reduced. In the example - above, "soxr" interpolation was also enabled.

- -

A sample configuration file with all possible settings, but with all of them - commented out, is installed at shairport-sync.conf.sample, within the - System Configuration Directory -- /etc in Linux, - /usr/local/etc in BSD unixes.

- -

To retain backwards compatibility with previous versions of shairport-sync - you can use still use command line options, but any new features, etc. will - be available only via configuration file settings.

- -

The configuration file is processed using the libconfig library - -- see http://www.hyperrealm.com/libconfig/libconfig_manual.html.

- -

"GENERAL" SETTINGS

These are the settings available within the general group:

- - -

name="service_name";

- -

Use this service_name to identify this player in iTunes, etc.

The following substitutions are allowed: - %h for the computer's hostname, - %H for the computer's hostname with the first letter capitalised (ASCII - only), - %v for the shairport-sync version number, e.g. "3.0.1" and - %V for the shairport-sync version string, e.g. - "3.0.1-OpenSSL-Avahi-ALSA-soxr-metadata-sysconfdir:/etc".

The default is "%H", which is replaced by the hostname with the first letter - capitalised.

- - - - -

password="password";

Require the password password to connect to the service. If you - leave this setting commented out, no password is needed.

- - - -

interpolation="mode";

Interpolate, or "stuff", the audio stream using the mode. - Interpolation here refers to the - process of adding or removing frames of audio to or from the - stream sent to the output device to keep it exactly in synchrony - with the player. - The default mode, "basic", is normally almost completely inaudible. - The alternative mode, "soxr", is even less obtrusive but - requires much more processing power. For this mode, support for - libsoxr, the SoX Resampler Library, must be selected when - shairport-sync is compiled. -

- - - -

output_backend="backend";

shairport-sync has a number of modules of code ("backends") through which - audio is output. Normally, the first audio backend that works is selected. This - setting forces the selection of the specific audio backend. Perform the - command shairport-sync -h to get a list of available audio backends -- the - default is the first on this list. Only the "alsa", "sndio" and "pa" backends support - synchronisation.

- - - -

mdns_backend="backend";

shairport-sync has a number of modules of code ("backends") for - interacting with the mDNS service to be used to advertise itself. Normally, the first - mDNS backend that works is selected. This setting forces the selection of the specific - mDNS backend. The default is "avahi". Perform the command - shairport-sync -h to get a list of available mDNS modules.

- - - -

port=portnumber;

Use this to specify the portnumber shairport-sync uses to - listen for service requests from iTunes, etc. The default is port 5000.

- - - -

udp_port_base=portnumber;

When shairport-sync starts to play audio, it establises three UDP - connections to the audio source. Use this setting to specify the starting - portnumber for these three ports. It will pick the first three unused ports - starting from portnumber. The default is port 6001.

- - - -

udp_port_range=range;

Use this in conjunction with the prevous setting to specify the - range of ports that can be checked for availability. Only three ports are - needed. - The default is 100, thus 100 ports will be checked from port 6001 upwards until three - are found.

- - - -

drift_tolerance_in_seconds=seconds;

Allow playback to drift up to seconds out of exact - synchronization before attempting to correct it. - The default is 0.002 seconds, i.e. 2 milliseconds. The smaller the tolerance, the more - likely it is that overcorrection will occur. - Overcorrection is when more corrections (insertions and deletions) are made than are - strictly necessary to keep the stream in sync. Use the statistics setting - to monitor correction levels. Corrections should not greatly exceed net corrections. - This setting replaces the deprecated drift setting. -

- - - -

resync_threshold_in_seconds=threshold;

Resynchronise if timings differ by more than threshold seconds. - If the output timing differs from the source timing by more than - the threshold, output will be muted and a full resynchronisation - will occur. The default threshold is 0.050 seconds, i.e. 50 - milliseconds. Specify 0.0 to disable resynchronisation. - This setting replaces the deprecated resync_threshold setting. -

- - - -

ignore_volume_control="choice";

Set this choice to "yes" if you want the volume to - be at 100% no matter what the source's volume control is set to. - This might be useful if you want to set the volume on the output device, independently - of the setting at the source. The default is "no".

- - - -

volume_range_db=dBvalue;

Use this dBvalue to reduce or increase the attenuation range, - in decibels, between the minimum and maximum volume.

For example, if a mixer has a minimum volume of -80 dB and a maximum of +20 dB, you - might wish to use only 60 dB of the 100 dB available. - This might be because the sound becomes inaudible at the lowest setting and unbearably - loud at the highest setting -- - indeed, many domestic HiFi systems have a volume control range of just 60 to 80dB.

Another potential use might be where the range specified by the mixer does not - match the capabilities of the device. - For example, the Raspberry Pi's DAC that feeds the built-in audio jack claims a range - of 106 dB but has a useful range of only about 30 dB. - The setting allows you to specify the maximum range from highest to lowest. - The range suggested for the Raspberry Pi's built-in audio DAC, which feeds the - headphone jack, is 30. - Using it in this case gives the volume control a much more useful range of - settings.

As a third example, you can actually extend the range provided by a mixer. - Many cheaper DACs have hardware mixers that offer a restricted attenuation range. - If you specify a volume range greater than the range of the mixer, software - attenuation and hardware attenuation will be combined to give the specified range.

If you omit this setting, the native range of the mixer is used.

- - - -

volume_max_db=dBvalue;

Specify the maximum output level to be used with the hardware mixer, if - used. If no hardware mixed is used, this setting specifies the maximum setting - permissible in the software mixer, which has an attenuation range from 0.0 dB down to - -96.3 dB. -

- - - -

volume_control_profile="choice";

Use this advanced setting to specify how the airplay volume is transferred - to the mixer volume. The "standard" profile, which is the default, makes - the volume change more quickly at lower volumes and slower at higher volumes. Choose - the "flat" profile to makes the volume change at the same rate at all - volume levels. -

- - - -

volume_range_combined_hardware_priority= - "choice";

Use this advanced setting to specify how to combine the hardware - attenuator with software attenuation to provide a greater attenuation range than the - hardware attenuator alone can provide. Choosing "yes" means that when - attenuation is required, the hardware attenuator will be used in preference. - If more attenuation than it can provide is needed, the hardware attenuator is set to - its greatest attenuation and software attenuation is added.

For example, if 40 dB of attenuation is required and the hardware attenuator - offers a maximum of 30 dB, then the hardware attenuator will be set to give 30 dB - attenuation and 10 dB of software attenuation will be added.

Unfortunately, certain hardware attenuators will mute at their greatest - attenuation, so can't be combined with software attenuation in this way. Choosing - "no" means that software attenuation is used to bring the remaining - attenuation required into the range offered by the hardware attenuator. - This is the default. -

- - - -

run_this_when_volume_is_set= - "/full/path/to/application/and/args";

Here you can specify a program and its arguments that will be run when the - volume is set or changed. Be careful to include the full path to the application. - The application must be marked as executable and, if it is a script, its first line - must begin with the standard shebang #!/bin/... as appropriate.

The desired AirPlay volume is appended to the end of the command line -- leave a - space at the end of the command line you specify here if you want it treated as an - extra argument. - AirPlay volume goes from 0.0 to -30.0 and -144.0 means "mute".

- - - -

regtype="regTypeString";

Use this advanced setting to set the service type and transport to be - advertised by Zeroconf/Bonjour. Default is "_raop._tcp".

- - - -

playback_mode="mode";

The mode can be "stereo", "mono", "reverse stereo", "both left" - or "both right". Default is "stereo". Note that dither will be added to the signal in - the mono mode.

- - - -

alac_decoder="decodername";

This can be "hammerton" or "apple". This advanced setting allows you to - choose the original Shairport decoder by David Hammerton or the Apple Lossless Audio - Codec (ALAC) decoder written by Apple. Shairport Sync must have been compiled with the - configuration setting "--with-apple-alac" and the Apple ALAC decoder library must be - present for this to work.

- - - -

interface="name";

Use this advanced setting if you want to confine Shairport Sync to the - named interface. Leave it commented out to get the default bahaviour.

- - - -

audio_backend_latency_offset_in_seconds= - offset_in_seconds;

Set this offset_in_seconds to compensate for a fixed delay in - the audio back end. For example, if the output device delays by 100 ms, set this to - -0.1.

- - - -

audio_backend_buffer_desired_length_in_seconds= - length_in_seconds;

Use this length_in_seconds to set the desired length of the - queue of audio frames in the backend's output buffer.

The default is 0.15 seconds for the ALSA backend, 0.35 seconds for the PA backend - and one second for all other backends.

If this value is set too small, underflow may occur on low-powered machines. - If set too large, the response times to the volume control may become excessive, or it - may exceed the backend's buffer size. - It may need to be larger on low-powered machines that are also performing other tasks, - such as processing metadata.

- - - -

audio_backend_buffer_interpolation_threshold_in_seconds= - time_in_seconds;

This is an advanced feature. If the length of the audio backend buffer - size drops below this, it's a sign that shairport sync can not process frames of audio - quickly enough. It this threshold is reached, shairport sync will stop using - time-consuming interpolation like soxr to avoid underruns.

- - - -

audio_backend_silent_lead_in_time= - lead_in_time_in_seconds;

This is an advanced setting. Use the lead_in_time_in_seconds to - set the desired length of the period of silence (a "silent lead-in") played before a - play session begins.

The purpose of this silent lead-in is to give the backend sufficient time to - prepare for operation and to make an estimate (and, importantly, to correct the - estimate) of the exact time at which to begin playing audio to achieve initial - synchronisation. The value can be from 0.0 up to a maximum of either 4.0 seconds. The - actual duration will be close to the setting but can not exceed the latency set by the - client, usually 2 seconds or a little more.

If the value chosen is too short for synchronised backends such as the ALSA, sndio - or PA backends, then audio will not be synchronised correctly at the start of play. - The default is to have a silent lead-in of approximately the same time as the latency - set by the client.

- - - -

dbus_service_bus= - "bus_name";

If shairport sync is compiled with the D-Bus interface, it can offer it on - the "system" or the "session" D-Bus "bus". - Use this to specify which. The default is to use the "system" bus.

- - - -

mpris_service_bus= - "bus_name";

If shairport sync is compiled with the MPRIS interface, it can offer the - service on the "system" or the "session" D-Bus "bus". - Use this to specify which. The default is to use the "system" bus.

- - -

"SESSIONCONTROL" SETTINGS

- - -

run_this_before_play_begins="/path/to/application and - args";

Here you can specify a program and its arguments that will be run just - before a play session begins. Be careful to include the full path to the application. - The application must be marked as executable and, if it is a script, its first line - must begin with the standard shebang #!/bin/... as - appropriate.

- - - -

run_this_after_play_ends="/path/to/application and - args";

Here you can specify a program and its arguments that will be run just - after a play session ends. Be careful to include the full path to the application. - The application must be marked as executable and, if it is a script, its first line - must begin with the standard shebang #!/bin/... as - appropriate.

- - - -

run_this_before_entering_active_state="/path/to/application and - args";

Here you can specify a program and its arguments that will be run just - before shairport-sync goes active.

- -

Shairport Sync goes "active" when a play session starts. When the play - session ends, the system will stay active until the time - specified in the active_state_timeout setting elapses. - If a new play session starts before that, the system will remain active. Otherwise, - the system will go inactive. -

- -

Be careful to include the full path to the application. - The application must be marked as executable and, if it is a script, its first line - must begin with the standard shebang #!/bin/... as - appropriate.

- - - -

run_this_after_exiting_active_state="/path/to/application and - args";

Here you can specify a program and its arguments that will be run just - after shairport-sync goes inactive (see the previous entry for an explanation - of the idea). - Be careful to include the full path to the application. - The application must be marked as executable and, if it is a script, its first line - must begin with the standard shebang #!/bin/... as - appropriate.

- - - -

active_state_timeout=seconds;

After a play session has ended, the system will remain active for - seconds seconds. If a new play session starts before this time has elapsed, - the system will remain active. However, if no new session starts in the interval, the - system will go inactive at the end of it. The default is 10 seconds.

- - - -

run_this_if_an_unfixable_error_is_detected="/path/to/application - and args";

Here you can specify a program and its arguments that will be run if the - system detects an unfixable error. At present, there are two types of - unfixable errors. One is where a play session cannot be terminated. - The second is if an output device has "stalled" -- that is, if an output device - refuses to accept any more output frames.

Although the first problem could, in principle, be fixed by restarting - Shairport Sync, it is usually caused by a malfunctioning output device. - Typically, the most reliable way to recover from either of these errors - is to reboot the entire machine.

- - - -

wait_for_completion="choice";

Set choice to "yes" to make shairport-sync wait until the - programs specified in the run_this_... settings have - completed execution before continuing. The default is "no".

- - - -

allow_session_interruption="choice";

If choice is set to "yes", then another source will be able to - interrupt an existing play session and start a new one. - When set to "no" (the default), other devices attempting to interrupt a session will - fail, receiving a busy signal.

- - - -

session_timeout=seconds;

If a play session has been established and the source disappears without - warning (such as a device going out of range of a network) - then wait for the number of seconds specified before ending the session. - Once the session has terminated, other devices can use it. The default is 120 - seconds.

- - - -

"ALSA" SETTINGS

These settings are for the ALSA back end, used to communicate with audio output - devices in the ALSA system. (By the way, you can use tools such as - alsamixer or aplay to discover what devices are available.) - Use these settings to select the output device and the mixer control to be used to - control the output volume. - You can additionally set the desired size of the output buffer and you can adjust - overall latency. Here are the alsa group settings:

- - -

output_device="output_device";

Use the output device called output_device. The default is the - device called "default".

- - - -

mixer_control_name="name";

Specify the name of the mixer control to be used by - shairport-sync to control the volume. - The mixer control must be on the mixer device, which by default is the output device. - If you do not specify a mixer control name, shairport-sync will adjust the volume in - software.

- - - -

mixer_device="mixer_device";

By default, the mixer is assumed to be output_device. Use this setting to - specify a device other than the output device.

- - - -

output_rate=frame rate;

Use this setting to specify the frame rate to output to the ALSA device. - Allowable values are 44100 (default), 88200, 176400 and 352800. The device must have - the capability to accept the format you specify. There is no particular reason to use - anything other than 44100 if it is available. -

- - - -

output_format="format";

Use this setting to specify the format that should be used to send data to - the ALSA device. Allowable values are "U8", "S8", "S16", "S24", "S24_3LE", "S24_3BE" - or "S32". The device must have the capability to accept the format you - specify.

"S" means signed; "U" means unsigned; BE means big-endian and LE means - little-endian. Except where stated (using *LE or *BE), endianness matches that of the - processor. The default is "S16".

If you are using a hardware mixer, the best - setting is S16, as audio will pass through Shairport Sync unmodifed except for - interpolation. If you are using the software mixer, use 32- or 24-bit, if your device - is capable of it, to get the lowest possible levels of dither. -

- - - -

disable_synchronization="no";

This is an advanced setting and is for debugging only. Set to - "yes" to disable synchronization. Default is "no". - If you use it to disable synchronisation, then sooner or later you'll experience audio - glitches due to audio buffer overflow or underflow. -

- - - -

period_size=number;

Use this optional advanced setting to set the alsa period size near to - this value.

- - - -

buffer_size=number;

Use this optional advanced setting to set the alsa buffer size near to - this value.

- - - -

use_mmap_if_available="yes";

Use this optional advanced setting to control whether MMAP-based output - is used to communicate with the DAC. Default is "yes".

- - - -

mute_using_playback_switch="no";

- -

This is an advanced setting and the default is "no". If it is set to - "yes", hardware mute will be used where it is available. - Set it to "no" to prevent the hardware mute being used.

If Shairport Sync is sharing the output device with other applications, it is best - to leave this set to "no" for compatibility with those applications.

Another motivation for this is to allow the ALSA function call - "snd_mixer_selem_set_playback_switch_all" to be avoided. It is incorrectly implemented - on certain soundcards, including the emulated card in VMWare Fusion 8.5.

- - - - -

maximum_stall_time=seconds;

If an output device fails to accept any audio frames for more than the - time, in seconds, specified here (0.2 seconds by default), - it is considered to have malfunctioned. It will result in the - run_this_if_an_unfixable_error_is_detected program, - if any, being called.

Implemented for the ALSA back end only.

- - - - -

disable_standby_mode="never";

- -

Shairport Sync has a "Disable Standby" feature to eliminate certain - faint-but-annoying audible pops and clicks. When activsted, it prevents - an output device from entering standby mode and thus it minimises standby/busy - transitions, which can sometimes be heard. Use this setting to control when the - Disable Standby feature is active: "never" means it will never be activated, "always" - means it will be active as soon as shairport-sync starts running, and "auto" - means it will be active while shairport-sync is in the "active" state.

Shairport Sync goes "active" when a play session starts. When the play - session ends, the system will stay active until the time - specified in the active_state_timeout setting elapses. - If a new play session starts before that, the system will remain active. Otherwise, - the system will go inactive. -

- - - -

"SNDIO" SETTINGS

These settings are for the SNDIO back end, used to communicate with audio output - devices in the SNDIO system.

- - -

device="snd/0";

Use this optional setting to specify the name of the output device, e.g. - "snd/0". The default is to use the SNDIO system's default.

- - - -

rate=44100;

Use this optional setting to specify the output rate in frames per second. - Valid rates are 44100, 88200, 176400 or 352800. - The output device must have the capability to accept data at the specified rate. The - default is 44100.

- - - -

format="S16";

Use this optional setting to specify the output format. Allowable values - are "U8", "S8", "S16", "S24", "S24_3LE", "S24_3BE" or "S32". - The device must have the capability to accept the format you specify.

"S" means - signed; "U" means unsigned; BE means big-endian and LE means little-endian. - Except where stated (using *LE or *BE), endianness matches that of the processor. The - default is "S16".

- Since the SNDIO backend does not use a hardware mixer for volume control, dither will - be introduced into the output if it is less than full volume. - Thus, (unless you are ignoring the volume control setting), - consider using 32- or 24-bit output if your device is capable of it, to get the lowest - possible levels of dither.

Please note that 32- or 24-bit has not been extensively tested on - SNDIO.

- - - -

round=value;

Use this optional advanced setting to specify the period size of the SNDIO - channel. If omitted, a SNDIO system default value will be used.

- - - -

bufsiz=value;

Use this optional advanced setting to specify the buffer size of the SNDIO - channel. If omitted, a SNDIO system default value will be used.

- - -

"PA" SETTINGS

These settings are for the new PulseAudio backend.

- - -

application_name="Shairport Sync";

Use this to set the name to appear in the Sounds "Applications" tab when - Shairport Sync is active. The default is the name "Shairport Sync".

- - -

"PIPE" SETTINGS

These settings are for the PIPE backend, used to route audio to a named unix pipe. - The audio is in raw CD audio format: PCM 16 bit little endian, 44,100 samples per - second, interleaved stereo.

- - -

name="/path/to/pipe";

Use this to specify the name and location of the pipe. The pipe will be - created and opened when shairport-sync starts up and will be closed upon shutdown. - Frames of audio will be sent to the pipe in packets of 352 frames and will be - discarded if the pipe has not have a reader attached. - The sender will wait for up to five seconds for a packet to be written before - discarding it.

- - -

"STDOUT" SETTINGS

There are no settings for the STDOUT backend.

- -

"AO" SETTINGS

There are no configuration file settings for the AO backend.

- -

"METADATA" SETTINGS

shairport-sync can process metadata provided by the source, such as Track Number, - Album Name, cover art, etc. and can provide additional metadata such as volume level, - pause/resume, etc. It sends the metadata to a pipe, by default - /tmp/shairport-sync-metadata. - To process metadata, shairport-sync must have been compiled with metadata support - included. - You can check that this is so by running the command $ shairport-sync -V; - the identification string will contain the word metadata.

Please note that different sources provide different levels of metadata. Some - provide a lot; some provide almost none.

The metadata group of settings allow you to enable metadata handling and - to control certain aspects of it:

- - -

enabled="choice";

Set the choice to "yes" to enable shairport-sync to look for - metadata from the audio source and to forward it, along with metadata generated by - shairport-sync itself, to the metadata pipe. The default is "no".

- - - -

include_cover_art="choice";

Set the choice to "yes" to enable shairport-sync to look for - cover art from the audio source and to include it in the feed to the metadata pipe. - You must also enable metadata (see above). - One reason for not including cover art is that the images can sometimes be very large - and may delay transmission of subsequent metadata through the pipe. - The default is "no".

- - - -

pipe_name="filepathname";

Specify the absolute path name of the pipe through which metadata should - be sent The default is /tmp/shairport-sync-metadata.

- - - -

socket_address="hostnameOrIP";

If hostnameOrIP is set to a host name or and IP address, UDP - packets containing metadata will be sent to this address. - May be a multicast address. Additionally, socket-port must be non-zero and - enabled must be set to "yes".

- - - -

socket_port=port;

If socket_address is set, use port to specify the - port to send UDP packets to. Must not be zero.

- - - -

socket_msglength=65000;

The maximum packet size for any UDP metadata. This must be between 500 or - 65000. The default is 500.

- - -

"DIAGNOSTICS" SETTINGS

- -

statistics="setting";

Use this setting to enable ("yes") or disable ("no") the output - of some statistical information on the console or in the log. The default is to - disable statistics.

- - - -

log_verbosity=0;

Use this to specify how much debugging information should be output or - logged. The value 0 means no debug information, 3 means most - debug information. The default is 0.

- - - - - -

Options

- -

This section is about the command-line options available in shairport-sync.

Note: if you are setting up shairport-sync for the first time or are updating an - existing installation, you are encouraged to use the configuration file settings - described above. Most of the command-line options described below - simply replicate the configuration settings and are retained to provide backward - compatibility with older installations of shairport-sync.

- -

Many command-line options take sensible default values, so you can normally - ignore most of them. See the EXAMPLES section for typical usages.

- -

There are two kinds of command-line options for shairport-sync: - regular program options and audio backend options. - Program options are - always listed first, followed by any audio backend options, preceded by - a -- symbol.

- -

Program Options

- -

These command-line options are used by shairport-sync itself.

- - - - -

-a service name | --name=service - name

- Use this service name to identify this player in iTunes, etc.

- -

The default is "%H", which is replaced by the hostname with the first letter - capitalised.

- - - - -

-B program | --on-start=program

- Execute program when playback is about to begin. Specify the - full path to the program, e.g. /usr/bin/logger. - Executable scripts can be used, but they must have the appropriate shebang - (#!/bin/sh in the headline.

- -

If you want shairport-sync to wait until the command has - completed before starting to play, select the -w option as well. -

- - - -

-c filename | --configfile=filename

- Read configuration settings from filename. The default is to read them from - the shairport-sync.conf in the System Configuration Directory -- - /etc in Linux, /usr/local/etc in BSD unixes. - For information about configuration settings, see the "Configuration File Settings" - section above. -

- - - -

-d | --daemon

- Instruct shairport-sync to demonise itself. It will write its - Process ID (PID) to a file, usually at - /var/run/shairport-sync/shairport-sync.pid, which is used by the - -k, -D and -R options to locate - the daemon at a later time. See also the -j option. Only available if - shaiport-sync has been compiled with libdaemon support. -

- - - -

-E program | --on-stop=program

- Execute program when playback has ended. Specify the - full path to the program, e.g. /usr/bin/logger. - Executable scripts can be used, but they must have the appropriate shebang - (#!/bin/sh in the headline.

If you want shairport-sync to wait until the command has - completed before continuing, select the -w option as well. -

- - - -

--get-coverart

- This option requires the --meta-dir option to be set, and enables - shairport-sync to request cover art from the source and to transmit it through - the metadata pipe.

Please note that cover art data may be very large, and may place too great a - burden on your network. -

- - - -

-h | --help

- Print brief help message and exit. -

- - - -

-j

- Instruct shairport-sync to demonise itself. Unlike the -d option, it will - not write a Process ID (PID) to a file -- it will just (hence the "j") demonise - itself. Only available if shaiport-sync has been compiled with libdaemon support. -

- - - -

-k | --kill

- Kill the shairport-sync daemon and exit. (Requires that the daemon has - written its PID to an agreed file -- see the -d option. Only available if - shaiport-sync has been compiled with libdaemon support.) -

- - - -

--logOutputLevel

- Use this to log the volume level when the volume is changed. It may be useful if you - are trying to determine a suitable value for the maximum volume level. Not available - as a configuration file setting. -

- - - - -

-L | --latency=latency

- Use this to set the default latency, in frames, for audio coming from an - unidentified source or from an iTunes Version 9 or earlier source. The standard value - for the default latency is 88,200 frames, where there are 44,100 - frames to the second. -

Please note that this feature is deprecated and will be removed in a future version - of shairport-sync.

- - - - -

--meta-dir=directory

- Listen for metadata coming from the source and send it, along with metadata from - shairport-sync itself, to a pipe called shairport-sync-metadata - in the directory you specify. If you add the --get-cover-art - then cover art will be sent through the pipe too. See https://github.com/mikebrady/shairport-sync-metadata-reader - for a sample metadata reader. -

- - - -

-m mdnsbackend | --mdns=mdnsbackend

- Force the use of the specified mDNS backend to advertise the - player on the network. The default is to try all mDNS backends until one - works. -

- - - -

-o outputbackend | - --output=outputbackend

- Force the use of the specified output backend to play the audio. - The default is to try the first one. -

- - - -

-p port | --port=port

- Listen for play requests on port. The default is to use port - 5000. -

- - - -

--password=secret

- Require the password secret to be able to connect and stream to the - service. -

- - - -

-r threshold | --resync=threshold

- Resynchronise if timings differ by more than threshold frames. - If the output timing differs from the source timing by more than - the threshold, output will be muted and a full resynchronisation - will occur. The default threshold is 2,205 frames, i.e. 50 - milliseconds. Specify 0 to disable resynchronisation. This setting is - deprecated and will be removed in a future version of shairport-sync. -

- - - -

--statistics

- Print some statistics in the standard output, or in the logfile if in daemon mode. -

- - - -

-S mode | --stuffing=mode

- Stuff the audio stream using the mode. "Stuffing" refers to the - process of adding or removing frames of audio to or from the - stream sent to the output device to keep it exactly in synchrony - with the player. - The default mode, basic, is normally almost completely inaudible. - The alternative mode, soxr, is even less obtrusive but - requires much more processing power. For this mode, support for - libsoxr, the SoX Resampler Library, must be selected when - shairport-sync is compiled. -

- - - -

-t timeout | --timeout=timeout

- Exit play mode if the stream disappears for more than timeout - seconds.

When shairport-sync plays an audio stream, it starts a play - session and will return a busy signal to any other sources that - attempt to use it. If the audio stream disappears for longer - than timeout seconds, the play session will be terminated. - If you specify a timeout time of 0, - shairport-sync will never signal that - it is busy and will not prevent other sources from "barging in" - on an existing play session. The default value is 120 seconds. -

- - - -

--tolerance=frames

- Allow playback to be up to frames out of exact synchronization before - attempting to correct it. - The default is 88 frames, i.e. 2 ms. The smaller the tolerance, the more likely it is - that overcorrection will occur. - Overcorrection is when more corrections (insertions and deletions) are made than are - strictly necessary to keep the stream in sync. Use the --statistics option - to monitor correction levels. Corrections should not greatly exceed net corrections. - This setting is deprecated and will be removed in a future version of shairport-sync. -

- - - -

-u

- If you are running shairport-sync from the command line and want logs to appear there, - use this option. Otherwise, logs may go to the system log. -

- - - -

-V | --version

- Print version information and exit. -

- - - -

-v | --verbose

- Print debug information. Repeat up to three times to get more detail. -

- - - -

-w | --wait-cmd

- Wait for commands specified using -B or -E to complete before - continuing execution. -

- - -

Audio Backend Options

- -

These command-line options are passed to the chosen audio backend. The audio - backend options are - preceded by a -- symbol to introduce them and to separate them from any - program options. In this way, option letters can be used as program - options and also as audio backend options without ambiguity.

- -

In the ALSA backend, audio is sent to an output device - which you can specify using the -d option. - The output level (the "volume") is controlled using a level control associated with a - mixer. - By default, the mixer is implemented in shairport-sync itself in software. - To use a hardware level control on a mixer on the sound card, specify the name of the - mixer control with the -c option. - If the mixer is not associated with the output device, then you need to specify where - the mixer is to be found with the -m option.

- - - - -

-c controlname

- Use the level control called controlname on the hardware mixer for - controlling volume. - This is needed if the mixer type is specified, using the -t option, - to be hardware. There is no default. -

- - - -

-d device

- Use the specified output device. You may specify a card, e.g. - hw:0, in which case the default output device on the card will be chosen. - Alternatively, you can specify a specific device on a card, e.g. hw:0,0. - The default is the device named default. -

- - - -

-m mixer

- Use the specified hardware mixer for volume control. Use this to specify - where the mixer is to be found. For example, if the mixer is associated with a card, - as is often the case, specify the card, e.g. hw:0. - If (unusually) the mixer is associated with a specific device on a card, - specify the device, e.g. hw:0,1. - The default is the device named in the -d option, - if given, or the device named default. -

- - - -

-t devicetype

- -

- This option is deprecated and is ignored. For your information, its functionality has - been automatically incorporated in the -c option - -- if you specify a mixer name with the -c option, it is assumed that the mixer is - implemented in hardware. -

- - - -

Examples

- -

Here is a slightly contrived example:

- shairport-sync -d - -a "Joe's Stereo" - -S soxr - -- - -d hw:1,0 - -m hw:1 - -c PCM -
- -

The program will run in daemon mode ( -d ), will be visible as - "Joe's Stereo" ( -a "Joe's Stereo" ) and will use the SoX Resampler - Library-based stuffing ( -S soxr ). - The audio backend options following the -- separator specify - that the audio will be output on output 0 of soundcard 1 - ( -d hw:1,0 ) and will take advantage of the same sound card's mixer - ( -m hw:1 ) using the level control named "PCM" ( -c "PCM" ). -

The example above is slightly contrived in order to show the use of the -m - option. Typically, output 0 is the default output of a card, so the output device could - be written -d hw:1 and then the mixer option would be unnecessary, giving the following, simpler, command:

- shairport-sync -d - -a "Joe's Stereo" - -S soxr - -- - -d hw:1 - -c PCM -
- - - - - -