shairport-sync(7)

📦 version 3.3.8, in debian bookworm, ubuntu jammy, ubuntu noble

✨ shairport-sync 💖

okay bestie, welcome to the manual page for shairport-sync — it lives in the Miscellaneous Information Manual, section 7, and it's literally the moment your whole music setup levels up. grab a snack, we're doing this. 🍓

🎀 NAME 🎀

shairport-sync — Synchronised Audio Player for iTunes / AirPlay. yes, that's the whole vibe. 👑

🌈 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

like, four whole ways to summon it. pick your fighter. 💅

💜 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. so many doors, all of them open. 🚪✨

Shairport Sync offers full audio synchronisation. and bestie, what that means is: audio is played on the output device at exactly the time specified by the audio source. so if a bunch of devices are playing the same stream at the same time, all the outputs stay in synchrony with one another. no drift, no chaos, no one being 0.3 seconds behind. this lets multiple devices play the same source without getting out of step with one another, enabling, for example, simultaneous multi-room operation. whole house, one song, zero fighting. 🔥

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. it's giving "i did my part, the rest is on y'all." 🫶

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. iconic behaviour honestly. 👑

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. yes it's the same girl, two nicknames. 💖

🌸 CONFIGURATION FILE SETTINGS 🌸

You should use the configuration file for setting up Shairport Sync. not optional-bestie behaviour, it's the recommended path. 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. yes, root. the big one. 🔐

(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 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";

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 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. 😭 do not let your speakers be silent by accident, that's so not the vibe.

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. a whole menu, everything crossed out. cute. 🎀

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. so the old ways work, but they don't get the new stuff. lowkey sad for the CLI girlies. 🙈

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.3.6" and %V for the shairport-sync version string, e.g. "3.3.6-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. it's giving "come on in" energy. 🔓
  • 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 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 compiled. The default setting is "auto", which will choose "soxr" if support for it has been compiled into the build of Shairport Sync and if the CPU is fast enough. Otherwise, "basic" stuffing will be chosen. 🧚 auto is out here making decisions for you and honestly? slay.
  • 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. ⚠️ note that, bestie, only those three keep the sync.
  • 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 previous 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;</p> 🎚️

This sets the maximum output level for the hardware mixer, if you're using one. And if you're not using a hardware mixer, this instead sets the max setting allowed in the software mixer — which has an attenuation range from 0.0 dB all the way down to -96.3 dB. Slay.

volume_control_profile="choice";</p> 🎀

An advanced one, bestie — this decides how the AirPlay volume maps onto the mixer volume.

  • "standard" — the default! Volume moves faster at lower volumes and slower at higher volumes.
  • "flat" — volume changes at the same rate at all volume levels.

Pick your fighter.

volume_range_combined_hardware_priority= "choice";</p> 🔥

Advanced setting time 💅 — this is about how you combine the hardware attenuator with software attenuation so you get a bigger attenuation range than the hardware can manage on its own.

  • "yes" — when attenuation is needed, the hardware attenuator gets used first, in preference. If you need more attenuation than it can give, the hardware attenuator is set to its greatest attenuation and software attenuation is added on top.

So like, if 40 dB of attenuation is required and the hardware attenuator maxes out at 30 dB? Then hardware gives you 30 dB of attenuation and 10 dB of software attenuation gets added. Math! ✨

⚠️ The catch, and it's a real one: certain hardware attenuators will mute at their greatest attenuation, so they can't be combined with software attenuation this way.
  • "no" — software attenuation is used to bring the remaining attenuation required into the range the hardware attenuator offers. This is the default.

run_this_when_volume_is_set= "/full/path/to/application/and/args";</p> 🫶

Here's where you name a program and its arguments to run whenever the volume is set or changed. Be careful — include the full path to the application, okay? It has to be marked as executable, and if it's 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 — so 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". Noted 📝

regtype="regTypeString";</p> 🌈

Advanced setting alert — this sets the service type and transport to be advertised by Zeroconf/Bonjour. Default is "_raop._tcp".

playback_mode="mode";</p> 🎧

The mode can be "stereo", "mono", "reverse stereo", "both left" or "both right". Default is "stereo".

Heads up: dither will be added to the signal in mono mode. That's just how it is, fr fr.

alac_decoder="decodername";</p> 🍓

This one can be "hammerton" or "apple". It's an advanced setting that lets you pick between the original Shairport decoder by David Hammerton, or the Apple Lossless Audio Codec (ALAC) decoder written by Apple.

Lowkey important: for this to work, Shairport Sync must have been compiled with the configuration setting "--with-apple-alac", and the Apple ALAC decoder library must be present. No library, no vibes. 😭

interface="name";</p> 🦋

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

audio_backend_latency_offset_in_seconds= offset_in_seconds;</p> ⏱️

Set 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;</p> 💜

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

Now listen — 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. And it may need to be larger on low-powered machines that are also performing other tasks, such as processing metadata. It's giving delicate balance 👑.

audio_backend_buffer_interpolation_threshold_in_seconds= time_in_seconds;</p> 🧚

This is an advanced feature, bestie. If the length of the audio backend buffer size drops below this, it's a sign that shairport sync cannot process frames of audio quickly enough. If 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;</p> 🌸

This is an advanced setting. Use 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 cannot 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";</p> ⭐

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";</p> ⭐

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 ✨

Okay this whole section is about controlling the vibes of a session — what runs when, and how long stuff sticks around. Iconic behaviour, honestly.

run_this_before_play_begins="/path/to/application and args";</p> 🎬

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";</p> 🎬

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";</p> 👑

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";</p> 🎬

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;</p> ⏳

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";</p> 🚨

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:

  1. A play session cannot be terminated.
  2. 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";</p> ⏸️

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";</p> 🙅‍♀️

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. Respect the queue, bestie.

session_timeout=seconds;</p> ⌛

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 ✨

okay so this whole group is for the ALSA back end — that's the bit that talks to your audio output devices in the ALSA system. 💖 (psst: you can use tools like alsamixer or aplay to go find out what devices you actually have, iykyk.) These settings are how you pick your output device, pick the mixer control that's gonna run your output volume, set the size of the output buffer you want, and adjust overall latency. Here's the whole alsa group, bestie:

  • output_device="output_device"; — use the output device literally called output_device. Default is the device called "default".
  • mixer_control_name="name"; — names the mixer control that shairport-sync uses to control the volume. Heads up: that mixer control has to live on the mixer device, which by default is the output device. And if you don't name a mixer control at all, shairport-sync will just adjust the volume in software instead. 🎚️
  • mixer_device="mixer_device"; — by default the mixer is assumed to be output_device. Use this setting when you want to point at a device that isn't the output device.
  • output_rate=frame rate; — sets the frame rate that gets output to the ALSA device. Allowable values are "auto" (the default), 44100, 88200, 176400 and 352800. The device must be able to accept the rate you pick. fr, there's no particular reason to use anything other than 44100 if it's available, and if "auto" is selected, the lowest of these rates that's available — starting at 44100 — gets chosen.
  • output_format="format"; — sets the format used to send data to the ALSA device. Allowable values are "auto" (default), "U8", "S8", "S16", "S24", "S24_3LE", "S24_3BE" or "S32". Again, your device must be capable of accepting the format you specify.

quick decode for you: "S" means signed, "U" means unsigned, BE means big-endian and LE means little-endian. Except where it's stated (using *LE or *BE), the endianness matches that of the processor. The default is "S16".

Now, if you're running a hardware mixer, S16 is totally fine — the audio passes through Shairport Sync unmodified except for interpolation — but any of the higher-resolution formats are okay too. If you're on the software mixer, use 32- or 24-bit if your device can handle it, so you get the lowest possible levels of dither. And the "auto" setting? That makes Shairport Sync choose the highest resolution available. 👑

  • disable_synchronization="no"; — this one is an advanced setting and it's for debugging only. Set it to "yes" to disable synchronization. Default is "no".
⚠️ bestie if you use this to disable synchronisation, then sooner or later you will hit audio glitches from audio buffer overflow or underflow. no cap.
  • period_size=number; — optional advanced setting, sets the alsa period size near to this value.
  • buffer_size=number; — optional advanced setting, sets the alsa buffer size near to this value.
  • use_mmap_if_available="yes"; — optional advanced setting that controls whether MMAP-based output is used to communicate with the DAC. Default is "yes".
  • mute_using_playback_switch="no"; — advanced setting, default is "no". If you set it to "yes", hardware mute will be used wherever it's available. Set it to "no" to stop the hardware mute from being used.

If Shairport Sync is sharing the output device with other applications, it's best to leave this at "no" so you stay compatible with those apps. 🫶

Another motivation for this is to let the ALSA function call snd_mixer_selem_set_playback_switch_all be avoided — it's 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 longer than the time, in seconds, specified here (0.2 seconds by default), it's considered to have malfunctioned. That 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 activated, it stops an output device from entering standby mode, and that 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'll be active as soon as shairport-sync starts running, and "auto" means it'll 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 stays active until the time specified in the active_state_timeout setting elapses. If a new play session starts before that happens, the system remains active. Otherwise, the system goes inactive. 🦋

🌸 "SNDIO" SETTINGS 🌸

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

  • device="snd/0"; — optional setting for the name of the output device, e.g. "snd/0". The default is to use the SNDIO system's default.
  • rate=44100; — optional setting for the output rate in frames per second. Valid rates are 44100, 88200, 176400 or 352800. Your output device must be able to accept data at the rate you specify. Default is 44100.
  • format="S16"; — optional setting for the output format. Allowable values are "U8", "S8", "S16", "S24", "S24_3LE", "S24_3BE" or "S32". The device must be capable of accepting the format you specify.

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

Since the SNDIO backend doesn't use a hardware mixer for volume control, dither gets introduced into the output if it's less than full volume. So (unless you're ignoring the volume control setting) consider using 32- or 24-bit output if your device can do 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; — optional advanced setting for the period size of the SNDIO channel. If you omit it, a SNDIO system default value will be used.
  • bufsiz=value; — optional advanced setting for the buffer size of the SNDIO channel. If you omit it, 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 that appears in the Sounds "Applications" tab when Shairport Sync is active. The default is the name "Shairport Sync".

🍓 "PIPE" SETTINGS 🍓

These ones are for the PIPE backend, which routes 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"; — specifies the name and location of the pipe. The pipe gets created and opened when shairport-sync starts up, and gets closed upon shutdown. Frames of audio are sent to the pipe in packets of 352 frames and get discarded if the pipe doesn't 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. that's it, that's the section. 💀✨

🌈 "AO" SETTINGS 🌈

There are no configuration file settings for the AO backend. also iconic for having nothing to say. 🎀

🦋 "METADATA" SETTINGS 🦋

shairport-sync can process metadata provided by the source — stuff like Track Number, Album Name, cover art, etc. — and it can also 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 it was 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 lets you enable metadata handling and 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 an 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" — turn the stats output on ("yes") or off ("no"). Where do these stats go? To the system log, or to STDERR if you picked the -u command line option 🫶. Default? disabled, bestie. No stats for you unless you ask.
  • log_verbosity=0 — this one controls how much debug tea gets spilled into the system log (or STDERR again, if -u is on the menu ☕). 0 = literally zero debug info, 3 = the most debug info you can get. Default is 0, so it's giving silence until you turn it up 📈.

✨ OPTIONS ✨

okay so this section is all about the command-line options that ship with shairport-sync 💅

Note: if you're setting up shairport-sync for the very first time, or you're updating an existing install, pleaseeee use the configuration file settings we talked about above 🙏. Most of the command-line options down here are just copies of those config settings, kept around so older installations don't break. Backward compatibility, we love her 💖.

A lot of these options come with sensible defaults already baked in, so honestly you can just ignore most of them, no cap. Peep the EXAMPLES section for typical usages 👀.

So there are two kinds of command-line options for shairport-sync:

  1. regular program options
  2. audio backend options

Program options always come first 🥇, then any audio backend options follow, and those are preceded by a -- symbol 🎀.

🎧 PROGRAM OPTIONS 🎧

These are the options used by shairport-sync itself, bestie.

  • -a service name, --name=service name — use this service name to identify this player in iTunes and friends 🌸. Here's the substitution menu, and yes they're all allowed:
    • %h — the computer's hostname
    • %H — the computer's hostname but with the first letter capitalised (ASCII only, okurrr)
    • %v — the shairport-sync version number, like "3.0.1"
    • %V — the shairport-sync version string, like "3.0.1-OpenSSL-Avahi-ALSA-soxr-metadata-sysconfdir:/etc"

The default is "%H", which gets swapped out for the hostname with the first letter capitalised 👑.

  • -B program, --on-start=program — run program right when playback is about to begin 🎬. Give it the full path to the program, e.g. /usr/bin/logger. You can absolutely use executable scripts too, but they must have the right shebang (#!/bin/sh in the headline 🐚).

If you want shairport-sync to actually wait for the command to finish before it starts playing, go ahead and also select the -w option 🫡.

  • -c filename, --configfile=filename — read configuration settings from filename 📂. Default is to read them from shairport-sync.conf in the System Configuration Directory — that's /etc on Linux and /usr/local/etc on BSD unixes 💻. Wanna know about the config settings? Scroll up to the "Configuration File Settings" section, bestie.
  • -d, --daemon — tells shairport-sync to demonise itself 😈. It'll write its Process ID (PID) to a file, usually at /var/run/shairport-sync/shairport-sync.pid, which the -k, -D and -R options use later to find the daemon again 🔍. Also check the -j option. Only available if shaiport-sync was compiled with libdaemon support.
  • -E program, --on-stop=program — run program when playback has ended 🛑. Full path to the program, e.g. /usr/bin/logger. Executable scripts work too, but again they need the correct shebang (#!/bin/sh in the headline 🐚).

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

  • --get-coverart — this option requires the --meta-dir option to be set, and it lets shairport-sync request cover art from the source and send it through the metadata pipe 🎨.
Heads up: cover art data can be very large, and it might put wayyy too much strain on your network 😭. Be careful, bestie.
  • -h, --help — print a short help message and exit 👋.
  • -j — tells shairport-sync to demonise itself 😈. Unlike the -d option, it will not write a Process ID (PID) to a file — it just demonises itself (hence the "j", get it? 😌). Only available if shaiport-sync was compiled with libdaemon support.
  • -k, --kill — kill the shairport-sync daemon and exit 💀. (This requires that the daemon has written its PID to an agreed file — see the -d option. Only available if shaiport-sync was compiled with libdaemon support.)
  • --logOutputLevel — use this to log the volume level whenever the volume changes 🔊. Could be useful if you're trying to figure out a good value for the maximum volume level. Not available as a configuration file setting, just so you know 🚫.
  • -L, --latency=latency — sets 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.
Warning: 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 also add the --get-cover-art then cover art gets sent through the pipe too 🎨. Peep 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 gets muted and a full resynchronisation happens. The default threshold is 2,205 frames, i.e. 50 milliseconds. Specify 0 to disable resynchronisation entirely. This setting is deprecated and will be removed in a future version of shairport-sync 😭.
  • --statistics — print some statistics to the standard output, or to the logfile if you're in daemon mode 📊.
  • -S mode, --stuffing=mode — stuff the audio stream using the mode 🧸. "Stuffing" means the process of adding or removing frames of audio to or from the stream sent to the output device, so it stays exactly in sync with the player. The default mode, basic, is normally almost completely inaudible 🤫. The alternative mode, soxr, is even less obtrusive but needs 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 ⏳. Here's the tea: when shairport-sync plays an audio stream, it starts a play session and returns a busy signal to any other sources trying to use it. If the audio stream disappears for longer than timeout seconds, the play session gets terminated. If you specify a timeout of 0, shairport-sync will never signal that it's busy and won't stop other sources from "barging in" on an existing play session 😳. Default value is 120 seconds.
  • --tolerance=frames — allow playback to be up to frames out of exact synchronization before it tries to correct it 🎯. The default is 88 frames, i.e. 2 ms. The smaller the tolerance, the more likely overcorrection is gonna happen. Overcorrection = 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're running shairport-sync from the command line and you want logs to show up there, use this option 💻. Otherwise, logs may go to the system log.
  • -V, --version — print version information and exit 🏷️.
  • -v, --verbose — print debug information to the system log, or to STDERR if the -u command line option is also chosen 🐛. 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 ⏸️.

Okay bestie, this is the part where we talk about the audio backend — like, the actual place your music goes to get heard. Buckle up. 🎧✨

🔥 AUDIO BACKEND OPTIONS 🔥

So here's the tea: these command-line options get passed along to whichever audio backend you picked. They're introduced by a -- symbol — that's the little separator that keeps them from getting mixed up with your program options. The whole point of that -- is so the same option letters can be used as program options and as audio backend options without any ambiguity. Iconic, honestly. 💅

Now, in the ALSA backend, audio gets sent to an output device, and you pick which one with the -d option. The output level — aka the "volume" — is controlled using a level control that's associated with a mixer. And here's the plot twist: by default, that mixer is implemented inside shairport-sync itself, in software.

But if you want to use a hardware level control on a mixer that lives on the sound card, you specify the name of that mixer control with the -c option. And if the mixer isn't associated with the output device at all? Then bestie, you gotta tell it where to find the mixer using the -m option. Periodt. 🎀

  • -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 can specify a card, e.g. hw:0, and in that case the default output device on the card will be chosen. Or you can go specific and name a particular 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 say where the mixer is to be found. For example, if the mixer is associated with a card — which is, like, usually 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 (iykyk), its functionality has been automatically incorporated into 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's a slightly contrived example, and yes the man page itself calls it contrived, so we're being honest here: 🌸

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

Let's break it down, bestie. 🫶

  • The program will run in daemon mode (-d)
  • It will be visible as "Joe's Stereo" (-a "Joe's Stereo")
  • And it'll use the SoX Resampler Library-based stuffing (-S soxr)

Then, the audio backend options following that -- 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"). Chef's kiss. 👑

Now, the example above is slightly contrived on purpose — it's doing all that just to show off the -m option. Typically, output 0 is the default output of a card, so the output device could just be written -d hw:1, and then the mixer option would be totally unnecessary. Which gives you this much simpler command: 🦋

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

💖 CREDITS 💖

Giving credit where it's due, because we are nothing if not grateful:

📝 COMMENTS 📝

This man page was written using xml2man(1) by Oliver Kurth. 🎀

And that's a wrap on shairport-sync(7), bestie! 🎉 This page lives in the Manuals section, it's a User manual, and it's dated and versioned as shairport-sync(7) — so if you're ever lost, just remember: man 7 shairport-sync and I gotchu. 💖 Stay slaying, keep your volume levels cute, and never forget your -- separator. Byeee! 🦋✨💅

📦 where this page comes from