shairport-sync

Synchronised Audio Player for iTunes / AirPlay

Synopsis

Description

shairport-sync plays audio streamed from iTunes or from an AirPlay device to an audio device connected via an audio back end. At present, the only fully-implemented back end is for ALSA.

A feature of shairport-sync is that the audio is played synchronously. This means that if many devices are playing the same stream at the same time, all the outputs will stay in step with one another. This allows multiple devices play the same source without getting out of phase with one another, enabling, for example, simultaneous multi-room operation.

Options

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

The command line for shairport-sync can take two kinds of options: 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 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 name is "Shairport Sync on <hostname>".

-A | --AirPlayLatency=latency

Use this latency, in frames, for audio streamed from an AirPlay device. The default is 88,200 frames, where there are 44,100 frames to the second.

-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 #!/bin/sh (or whatever is appropriate) 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.

-D | --disconnectFromOutput

Disconnect the shairport-sync daemon from the output device and exit. (Requires that the daemon has written its PID to an agreed file -- see the -d option).

-d | --daemon

Instruct shairport-sync to demonise itself. It will write its Process ID (PID) to a file, usually at /var/run/shairport-sync.pid, which is used by the -k, -D and -R options to locate the daemon at a later time.

-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 #!/bin/sh (or whatever is appropriate) in the headline.

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

--forkedDaapdLatency=latency

Use this latency, in frames, for audio streamed from a forked-daapd based source. The default is 99,400 frames, where there are 44,100 frames to the second.

-h | --help

Print brief help message and exit.

-i | --iTunesLatency=latency

Use this latency, in frames, for audio streamed from an iTunes source, where iTunes is Version 10 or later. The default is 99,400 frames, where there are 44,100 frames to the second. If the source is iTunes but is earler than Version 10, the default latency is used (see the -L option). Some third party programs masquerade as older versions of iTunes.

-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).

-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.

-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. (This is not used at present.)

-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 | --reconnectToOutput

Reconnect the shairport-sync daemon to the output device and exit. It may take a few seconds to synchronise. (Requires that the daemon has written its PID to an agreed file -- see the -d option).

-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.

--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 startes 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.

-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 options are passed to the chosen audio backend. (At present, the only backend implemented is for ALSA.) 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, i.e. the type of the mixer is "software". To use a level control on a mixer on the sound card, you must (a) specify that the mixer's type is "hardware" with the -t option; (b) you must specify where the mixer is to be found using the -m option and finally (c) you must specify the name of the level control you are using with the -c 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

The type of the output device is devicetype which must be hardware or software. The default is software. If you specify hardware you must also specify the output device using the -d option and the name of the volume control using the -c option. You may also need to specify the mixer using the -m option.

Examples

Here is a slightly contrived but typical example:

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 hardware (-t hardware) 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:

Credits

Mike Brady developed shairport-sync from the original shairport by James Laird.

shairport-sync can be found at https://github.com/mikebrady/shairport-sync.

shairport can be found at https://github.com/abrasive/shairport.

Comments

This man page was written using xml2man by Oliver Kurth.