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