 |
|
| |
shairport-sync(1) |
FreeBSD General Commands Manual |
shairport-sync(1) |
shairport-sync - AirPlay and AirPlay 2 Audio Player
shairport-sync [-djvw] [-a
service-name |
--name=service-name] [-B
command |
--onstart=command] [-c
configurationfile |
--configfile=configurationfile] [-d |
--daemon] [-E command |
--onstop=command] [-g | --get-cover-art]
[-j | --justDaemoniseNoPIDFile] [--logOutputLevel]
[--log-to-syslog] [-L latency |
--latency=latency] [-m
backend | --mdns=backend]
[-M | --metadata-enable] [-o backend |
--output=backend] [-p port
| --port=port]
[--password=secret] [-r
threshold |
--resync=threshold] [--statistics] [-S
mode | --stuffing=mode] [-t
timeout |
--timeout=timeout]
[--tolerance=frames] [-v | --verbose] [-w
| --wait-cmd] [--
audio_backend_options]
shairport-sync -X | --displayConfig
shairport-sync -h
shairport-sync -k
shairport-sync -V
Shairport Sync plays AirPlay audio. It can be built to stream
either from "classic" AirPlay (aka "AirPlay 1") or from
AirPlay 2 devices.
AirPlay 2 support is limited, and AirPlay 2 from iTunes for
Windows is not supported. For AirPlay 2 operation, a companion program
called nqptp must be installed.
Please see https://github.com/mikebrady/shairport-sync for
details.
The name of the Shairport Sync executable is
shairport-sync.
You should use the configuration file for setting up Shairport
Sync because -- apart from a few special-purpose commands -- it has a much
richer set of options than are available on the command line. 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. The last item in the output string is the value
of the sysconfdir, i.e. the System Configuration Directory.)
Within the configuration 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";
};
alsa = {
output_device = "hw:0";
mixer_control_name = "PCM";
};
Users generally only need to set (1) the service name and (2) the
output device. If the name setting is omitted, the service name is
derived from the system's hostname. By default, the ALSA backend will
be chosen if included in the build. If the (alsa) output device has a mixer
that can be used for volume control, then (3) the mixer name should be
specified. It is important to do this if the mixer exists. Otherwise, the
maximum output from the output device will be whatever setting the mixer
happens to have, which will be a matter of chance and which could be very
low or even silent.
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.
The sample configuration file includes extensive documentation of
the settings. and is also available at
https://github.com/mikebrady/shairport-sync/blob/master/scripts/shairport-sync.conf.
Please refer to it for the most up-to-date information on configuration file
settings.
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.
See the EXAMPLES section for sample usages.
Program 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 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.
- -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 shairport-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.
- -g | --get-coverart
- This option requires the -M | --metadata-enable option to be set,
and enables shairport-sync to request cover art from the source and to
process it as metadata.
- -h | --help
- Print brief help message and exit.
- -j |
justDaemoniseNoPIDFile
- 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 shairport-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 shairport-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.
- --log-to-syslog
- Warnings, error messages and messages are sent, by default, to
STDERR. Use this option to route these messages to the
syslog instead. This is intended for use when Shairport Sync is
operating as a daemon.
See also --displayConfig.
- -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.
- -M |
--metadata-enable
- Ask the client to send metadata. It will be sent, along with metadata
generated by shairport-sync itself, to a pipe and will also be sent as UDP
packets. If you add the -g | --get-cover-art then cover art
included, where available. See
https://github.com/mikebrady/shairport-sync-metadata-reader for a
sample metadata reader.
- --metadata-pipename=pathname
- Specify the path name for the metadata pipe. Note that
shairport-sync will need write permission on that directory and
pipe. The default is /tmp/shairport-sync-metadata. If you rename
the shairport-sync executable, the default pipe name will change
accordingly.
- -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 in order 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
for AirPlay and 7000 for AirPlay 2.
- --password=secret
- Require the password secret to be able to connect and stream to the
service. (This only works for AirPlay and not for AirPlay 2.)
- -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 performance information to STDERR, or to syslog
if the -log-to-syslog command line option is also chosen.
- -S mode |
--stuffing=mode
- Interpolate ("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 in order to keep it
synchronised with the player. The basic mode 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 built. The default setting, auto, allows
Shairport Sync to choose soxr mode if the system is powerful
enough.
- -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.
- -V | --version
- Print version information and exit.
- -v | --verbose
- Print debug information to the STDERR, or to syslog if the
-log-to-syslog command line option is also chosen. Repeat up to
three times (i.e. -vv or -vvv) for more detail. You should
use -vvv very sparingly -- it is really noisy.
- -w | --wait-cmd
- Wait for commands specified using -B or -E to complete
before continuing execution.
- -X | --displayConfig
- This logs information relating to the configuration of Shairport Sync. It
can be very useful for debugging. The information logged is some host OS
information, the Shairport Sync version string (which indicates the build
options used when shairport-sync was built), the contents of the
command line that invoked Shairport Sync, the name of the configuration
file and the active settings therein.
If this is the only option on the command line,
shairport-sync will terminate after displaying the
information.
Audio Backend Options are command-line options that are passed to
the chosen audio backend. They are always preceded by the -- symbol
to introduce them and to separate them from any preceding program options.
In this way, option letters can be used as program options and reused as
audio backend options without ambiguity.
Audio backends are listed with their corresponding Audio Backend
Options in the help text provided by the help (-h or --help)
option.
Here is a slightly contrived example:
shairport-sync -a "Joe's Stereo" -o alsa
-- -d hw:1,0 -m hw:1 -c PCM
The program will be visible as "Joe's Stereo" ( -a
"Joe's Stereo" ). The program option -o alsa specifies
that the alsa backend be used, thus that audio should be output into
the ALSA audio subsystem. The audio backend options following the
-- separator are passed to the alsa backend and specify that
the audio will be output on subdevice 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: Firstly, if the
alsa backend has been included in the build, it will be the default,
so it doesn't need to be specified and the -o alsa option could be
omitted. Secondly, subdevice 0 is the default for a soundcard, so the output
device could simply be written -d hw:1. Thirdly, when a mixer name is
given ( -c "PCM" ), the default is that the mixer is on the
output device, so the -m hw:1 is unnecessary here. Using these
defaults and simplifications gives the following command:
shairport-sync -a "Joe's Stereo" -- -d
hw:1 -c PCM
Mike Brady (https://github.com/mikebrady) developed
Shairport Sync from Shairport by James Wah
(https://github.com/abrasive).
This man page was written using xml2man(1) by Oliver
Kurth.
Visit the GSP FreeBSD Man Page Interface. Output converted with ManDoc.
|