1shairport-sync(7) Miscellaneous Information Manual shairport-sync(7)
2
6 shairport-sync - Synchronised Audio Player for iTunes / AirPlay
7
9 shairport-sync [-djvuw] [-a name] [-A latency] [-B command] [-c config‐
10 urationfile] [-E command] [--get-cover-art] [--logOutputLevel] [-L la‐
11 tency] [-m backend] [--meta-dir=directory] [-o backend] [--password=se‐
12 cret] [-r threshold] [--statistics] [-S mode] [-t timeout] [--toler‐
13 ance=frames] [-- audio_backend_options]
14 shairport-sync -k
16 shairport-sync -h
18 shairport-sync -V
20
22 Shairport Sync plays audio streamed from iTunes or from an AirPlay de‐
23 vice to an ALSA-compatible audio output device (available on Linux and
24 FreeBSD), to a "sndio" output device (available on OpenBSD, FreeBSD and
25 Linux), to a PulseAudio output stream or to Jack Audio.
26 Shairport Sync offers full audio synchronisation. Full audio synchroni‐
28 sation means that audio is played on the output device at exactly the
29 time specified by the audio source. This means that if many devices are
30 playing the same stream at the same time, all the outputs will stay in
31 synchrony with one another. This allows multiple devices to play the
32 same source without getting out of step with one another, enabling, for
33 example, simultaneous multi-room operation.
34 Shairport Sync can stream synchronised audio to a unix pipe or to stan‐
36 dard output, or to audio systems that do not provide timing informa‐
37 tion. This could perhaps be described as partial audio synchronisation,
38 where synchronised audio is provided by Shairport Sync, but what hap‐
39 pens to it in the subsequent processing chain, before it reaches the
40 listener's ear, is outside the control of shairport-sync.
41 Shairport Sync can be compiled to stream metadata, including cover art,
43 to a pipe or socket.
44 Shairport Sync can be compiled to offer a standard MPRIS interface, a
46 "native" D-Bus interface and an MQTT client interface. Through these
47 interfaces, it can provide metadata, including cover art, and can offer
48 remote control of the audio source.
49 Settings can be made using the configuration file (recommended for all
51 new installations) or by using command-line options.
52 The name of the Shairport Sync executable is shairport-sync. Both names
54 are used in these man pages.
55
57 You should use the configuration file for setting up Shairport Sync.
58 This file is usually shairport-sync.conf and is generally located in
59 the System Configuration Directory, which is normally the /etc direc‐
60 tory in Linux or the /usr/local/etc directory in BSD unixes. You may
61 need to have root privileges to modify it.
62 (Note: Shairport Sync may have been compiled to use a different config‐
64 uration directory. You can determine which by performing the command $
65 shairport-sync -V. One of the items in the output string is the value
66 of the sysconfdir, i.e. the System Configuration Directory.)
67 Within the configuration file, settings are organised into groups, for
69 example, there is a "general" group of standard settings, and there is
70 an "alsa" group with settings that pertain to the ALSA back end. Here
71 is an example of a typical configuration file:
72 general = {
74 name = "Mike's Boombox";
76 password = "secret";
78 output_backend = "alsa";
80 };
82 alsa = {
86 output_device = "hw:0";
88 mixer_control_name = "PCM";
90 };
92 Most settings have sensible default values, so -- as in the example
94 above -- users generally only need to set (1) the service name, (2) a
95 password (if desired) and (3) the output device. If the output device
96 has a mixer that can be used for volume control, then (4) the mixer
97 name should be specified. It is important to do this if the mixer ex‐
98 ists. Otherwise, the maximum output from the output device will be
99 whatever setting the mixer happens to have, which will be a matter of
100 chance and which could be very low or even silent.
101 A sample configuration file with all possible settings, but with all of
103 them commented out, is installed at shairport-sync.conf.sample, within
104 the System Configuration Directory -- /etc in Linux, /usr/local/etc in
105 BSD unixes.
106 To retain backwards compatibility with previous versions of shairport-
108 sync you can use still use command line options, but any new features,
109 etc. will be available only via configuration file settings.
110 The configuration file is processed using the libconfig library -- see
112 http://www.hyperrealm.com/libconfig/libconfig_manual.html.
113 "GENERAL" SETTINGS
115 These are the settings available within the general group:
116 name="service_name";
118 Use this service_name to identify this player in iTunes, etc.
119 The following substitutions are allowed: %h for the computer's
121 hostname, %H for the computer's hostname with the first letter
122 capitalised (ASCII only), %v for the shairport-sync version num‐
123 ber, e.g. "3.3.6" and %V for the shairport-sync version string,
124 e.g. "3.3.6-OpenSSL-Avahi-ALSA-soxr-metadata-sysconfdir:/etc".
125 The default is "%H", which is replaced by the hostname with the
127 first letter capitalised.
128 password="password";
130 Require the password password to connect to the service. If you
131 leave this setting commented out, no password is needed.
132 interpolation="mode";
134 Interpolate, or "stuff", the audio stream using the mode. Inter‐
135 polation here refers to the process of adding or removing frames
136 of audio to or from the stream sent to the output device to keep
137 it exactly synchronised with the player. The "basic" mode is
138 normally almost completely inaudible. The alternative mode,
139 "soxr", is even less obtrusive but requires much more processing
140 power. For this mode, support for libsoxr, the SoX Resampler Li‐
141 brary, must be selected when shairport-sync is compiled. The de‐
142 fault setting is "auto", which will choose "soxr" if support for
143 it has been compiled into the build of Shairport Synce and if
144 the CPU is fast enough. Otherwise, "basic" stuffing will be cho‐
145 sen.
146 output_backend="backend";
148 shairport-sync has a number of modules of code ("backends")
149 through which audio is output. Normally, the first audio backend
150 that works is selected. This setting forces the selection of the
151 specific audio backend. Perform the command shairport-sync -h to
152 get a list of available audio backends -- the default is the
153 first on this list. Only the "alsa", "sndio" and "pa" backends
154 support synchronisation.
155 mdns_backend="backend";
157 shairport-sync has a number of modules of code ("backends") for
158 interacting with the mDNS service to be used to advertise it‐
159 self. Normally, the first mDNS backend that works is selected.
160 This setting forces the selection of the specific mDNS backend.
161 The default is "avahi". Perform the command shairport-sync -h to
162 get a list of available mDNS modules.
163 port=portnumber;
165 Use this to specify the portnumber shairport-sync uses to listen
166 for service requests from iTunes, etc. The default is port 5000.
167 udp_port_base=portnumber;
169 When shairport-sync starts to play audio, it establises three
170 UDP connections to the audio source. Use this setting to specify
171 the starting portnumber for these three ports. It will pick the
172 first three unused ports starting from portnumber. The default
173 is port 6001.
174 udp_port_range=range;
176 Use this in conjunction with the previous setting to specify the
177 range of ports that can be checked for availability. Only three
178 ports are needed. The default is 100, thus 100 ports will be
179 checked from port 6001 upwards until three are found.
180 drift_tolerance_in_seconds=seconds;
182 Allow playback to drift up to seconds out of exact synchroniza‐
183 tion before attempting to correct it. The default is 0.002 sec‐
184 onds, i.e. 2 milliseconds. The smaller the tolerance, the more
185 likely it is that overcorrection will occur. Overcorrection is
186 when more corrections (insertions and deletions) are made than
187 are strictly necessary to keep the stream in sync. Use the sta‐
188 tistics setting to monitor correction levels. Corrections should
189 not greatly exceed net corrections. This setting replaces the
190 deprecated drift setting.
191 resync_threshold_in_seconds=threshold;
193 Resynchronise if timings differ by more than threshold seconds.
194 If the output timing differs from the source timing by more than
195 the threshold, output will be muted and a full resynchronisation
196 will occur. The default threshold is 0.050 seconds, i.e. 50 mil‐
197 liseconds. Specify 0.0 to disable resynchronisation. This set‐
198 ting replaces the deprecated resync_threshold setting.
199 ignore_volume_control="choice";
201 Set this choice to "yes" if you want the volume to be at 100% no
202 matter what the source's volume control is set to. This might be
203 useful if you want to set the volume on the output device, inde‐
204 pendently of the setting at the source. The default is "no".
205 volume_range_db=dBvalue;
207 Use this dBvalue to reduce or increase the attenuation range, in
208 decibels, between the minimum and maximum volume.
209 For example, if a mixer has a minimum volume of -80 dB and a
211 maximum of +20 dB, you might wish to use only 60 dB of the 100
212 dB available. This might be because the sound becomes inaudible
213 at the lowest setting and unbearably loud at the highest setting
214 -- indeed, many domestic HiFi systems have a volume control
215 range of just 60 to 80dB.
216 Another potential use might be where the range specified by the
218 mixer does not match the capabilities of the device. For exam‐
219 ple, the Raspberry Pi's DAC that feeds the built-in audio jack
220 claims a range of 106 dB but has a useful range of only about 30
221 dB. The setting allows you to specify the maximum range from
222 highest to lowest. The range suggested for the Raspberry Pi's
223 built-in audio DAC, which feeds the headphone jack, is 30. Using
224 it in this case gives the volume control a much more useful
225 range of settings.
226 As a third example, you can actually extend the range provided
228 by a mixer. Many cheaper DACs have hardware mixers that offer a
229 restricted attenuation range. If you specify a volume range
230 greater than the range of the mixer, software attenuation and
231 hardware attenuation will be combined to give the specified
232 range.
233 If you omit this setting, the native range of the mixer is used.
235 volume_max_db=dBvalue;
237 Specify the maximum output level to be used with the hardware
238 mixer, if used. If no hardware mixed is used, this setting spec‐
239 ifies the maximum setting permissible in the software mixer,
240 which has an attenuation range from 0.0 dB down to -96.3 dB.
241 volume_control_profile="choice";
243 Use this advanced setting to specify how the airplay volume is
244 transferred to the mixer volume. The "standard" profile, which
245 is the default, makes the volume change more quickly at lower
246 volumes and slower at higher volumes. Choose the "flat" profile
247 to makes the volume change at the same rate at all volume lev‐
248 els.
249 volume_range_combined_hardware_priority= "choice";
251 Use this advanced setting to specify how to combine the hardware
252 attenuator with software attenuation to provide a greater atten‐
253 uation range than the hardware attenuator alone can provide.
254 Choosing "yes" means that when attenuation is required, the
255 hardware attenuator will be used in preference. If more attenua‐
256 tion than it can provide is needed, the hardware attenuator is
257 set to its greatest attenuation and software attenuation is
258 added.
259 For example, if 40 dB of attenuation is required and the hard‐
261 ware attenuator offers a maximum of 30 dB, then the hardware at‐
262 tenuator will be set to give 30 dB attenuation and 10 dB of
263 software attenuation will be added.
264 Unfortunately, certain hardware attenuators will mute at their
266 greatest attenuation, so can't be combined with software attenu‐
267 ation in this way. Choosing "no" means that software attenuation
268 is used to bring the remaining attenuation required into the
269 range offered by the hardware attenuator. This is the default.
270 run_this_when_volume_is_set= "/full/path/to/application/and/args";
272 Here you can specify a program and its arguments that will be
273 run when the volume is set or changed. Be careful to include the
274 full path to the application. The application must be marked as
275 executable and, if it is a script, its first line must begin
276 with the standard shebang #!/bin/... as appropriate.
277 The desired AirPlay volume is appended to the end of the command
279 line -- leave a space at the end of the command line you specify
280 here if you want it treated as an extra argument. AirPlay volume
281 goes from 0.0 to -30.0 and -144.0 means "mute".
282 regtype="regTypeString";
284 Use this advanced setting to set the service type and transport
285 to be advertised by Zeroconf/Bonjour. Default is "_raop._tcp".
286 playback_mode="mode";
288 The mode can be "stereo", "mono", "reverse stereo", "both left"
289 or "both right". Default is "stereo". Note that dither will be
290 added to the signal in the mono mode.
291 alac_decoder="decodername";
293 This can be "hammerton" or "apple". This advanced setting allows
294 you to choose the original Shairport decoder by David Hammerton
295 or the Apple Lossless Audio Codec (ALAC) decoder written by Ap‐
296 ple. Shairport Sync must have been compiled with the configura‐
297 tion setting "--with-apple-alac" and the Apple ALAC decoder li‐
298 brary must be present for this to work.
299 interface="name";
301 Use this advanced setting if you want to confine Shairport Sync
302 to the named interface. Leave it commented out to get the de‐
303 fault behaviour.
304 audio_backend_latency_offset_in_seconds= offset_in_seconds;
306 Set this offset_in_seconds to compensate for a fixed delay in
307 the audio back end. For example, if the output device delays by
308 100 ms, set this to -0.1.
309 audio_backend_buffer_desired_length_in_seconds= length_in_seconds;
311 Use this length_in_seconds to set the desired length of the
312 queue of audio frames in the backend's output buffer.
313 The default is 0.15 seconds for the ALSA backend, 0.35 seconds
315 for the PA backend and one second for all other backends.
316 If this value is set too small, underflow may occur on low-pow‐
318 ered machines. If set too large, the response times to the vol‐
319 ume control may become excessive, or it may exceed the backend's
320 buffer size. It may need to be larger on low-powered machines
321 that are also performing other tasks, such as processing meta‐
322 data.
323 audio_backend_buffer_interpolation_threshold_in_seconds= time_in_sec‐
325 onds;
326 This is an advanced feature. If the length of the audio backend
327 buffer size drops below this, it's a sign that shairport sync
328 can not process frames of audio quickly enough. It this thresh‐
329 old is reached, shairport sync will stop using time-consuming
330 interpolation like soxr to avoid underruns.
331 audio_backend_silent_lead_in_time= lead_in_time_in_seconds;
333 This is an advanced setting. Use the lead_in_time_in_seconds to
334 set the desired length of the period of silence (a "silent lead-
335 in") played before a play session begins.
336 The purpose of this silent lead-in is to give the backend suffi‐
338 cient time to prepare for operation and to make an estimate
339 (and, importantly, to correct the estimate) of the exact time at
340 which to begin playing audio to achieve initial synchronisation.
341 The value can be from 0.0 up to a maximum of either 4.0 seconds.
342 The actual duration will be close to the setting but can not ex‐
343 ceed the latency set by the client, usually 2 seconds or a lit‐
344 tle more.
345 If the value chosen is too short for synchronised backends such
347 as the ALSA, sndio or PA backends, then audio will not be syn‐
348 chronised correctly at the start of play. The default is to have
349 a silent lead-in of approximately the same time as the latency
350 set by the client.
351 dbus_service_bus= "bus_name";
353 If shairport sync is compiled with the D-Bus interface, it can
354 offer it on the "system" or the "session" D-Bus "bus". Use this
355 to specify which. The default is to use the "system" bus.
356 mpris_service_bus= "bus_name";
358 If shairport sync is compiled with the MPRIS interface, it can
359 offer the service on the "system" or the "session" D-Bus "bus".
360 Use this to specify which. The default is to use the "system"
361 bus.
362 "SESSIONCONTROL" SETTINGS
364 run_this_before_play_begins="/path/to/application and args";
366 Here you can specify a program and its arguments that will be
367 run just before a play session begins. Be careful to include the
368 full path to the application. The application must be marked as
369 executable and, if it is a script, its first line must begin
370 with the standard shebang #!/bin/... as appropriate.
371 run_this_after_play_ends="/path/to/application and args";
373 Here you can specify a program and its arguments that will be
374 run just after a play session ends. Be careful to include the
375 full path to the application. The application must be marked as
376 executable and, if it is a script, its first line must begin
377 with the standard shebang #!/bin/... as appropriate.
378 run_this_before_entering_active_state="/path/to/application and args";
380 Here you can specify a program and its arguments that will be
381 run just before shairport-sync goes active.
382 Shairport Sync goes "active" when a play session starts. When
384 the play session ends, the system will stay active until the
385 time specified in the active_state_timeout setting elapses. If a
386 new play session starts before that, the system will remain ac‐
387 tive. Otherwise, the system will go inactive.
388 Be careful to include the full path to the application. The ap‐
390 plication must be marked as executable and, if it is a script,
391 its first line must begin with the standard shebang #!/bin/...
392 as appropriate.
393 run_this_after_exiting_active_state="/path/to/application and args";
395 Here you can specify a program and its arguments that will be
396 run just after shairport-sync goes inactive (see the previous
397 entry for an explanation of the idea). Be careful to include the
398 full path to the application. The application must be marked as
399 executable and, if it is a script, its first line must begin
400 with the standard shebang #!/bin/... as appropriate.
401 active_state_timeout=seconds;
403 After a play session has ended, the system will remain active
404 for seconds seconds. If a new play session starts before this
405 time has elapsed, the system will remain active. However, if no
406 new session starts in the interval, the system will go inactive
407 at the end of it. The default is 10 seconds.
408 run_this_if_an_unfixable_error_is_detected="/path/to/application and
410 args";
411 Here you can specify a program and its arguments that will be
412 run if the system detects an unfixable error. At present, there
413 are two types of unfixable errors. One is where a play session
414 cannot be terminated. The second is if an output device has
415 "stalled" -- that is, if an output device refuses to accept any
416 more output frames.
417 Although the first problem could, in principle, be fixed by
419 restarting Shairport Sync, it is usually caused by a malfunc‐
420 tioning output device. Typically, the most reliable way to re‐
421 cover from either of these errors is to reboot the entire ma‐
422 chine.
423 Be careful to include the full path to the application. The ap‐
425 plication must be marked as executable and, if it is a script,
426 its first line must begin with the standard shebang #!/bin/...
427 as appropriate.
428 wait_for_completion="choice";
430 Set choice to "yes" to make shairport-sync wait until the pro‐
431 grams specified in the run_this_... settings have completed exe‐
432 cution before continuing. The default is "no".
433 allow_session_interruption="choice";
435 If choice is set to "yes", then another source will be able to
436 interrupt an existing play session and start a new one. When set
437 to "no" (the default), other devices attempting to interrupt a
438 session will fail, receiving a busy signal.
439 session_timeout=seconds;
441 If a play session has been established and the source disappears
442 without warning (such as a device going out of range of a net‐
443 work) then wait for the number of seconds specified before end‐
444 ing the session. Once the session has terminated, other devices
445 can use it. The default is 120 seconds.
446 "ALSA" SETTINGS
448 These settings are for the ALSA back end, used to communicate
449 with audio output devices in the ALSA system. (By the way, you
450 can use tools such as alsamixer or aplay to discover what de‐
451 vices are available.) Use these settings to select the output
452 device and the mixer control to be used to control the output
453 volume. You can additionally set the desired size of the output
454 buffer and you can adjust overall latency. Here are the alsa
455 group settings:
456 output_device="output_device";
458 Use the output device called output_device. The default is the
459 device called "default".
460 mixer_control_name="name";
462 Specify the name of the mixer control to be used by shairport-
463 sync to control the volume. The mixer control must be on the
464 mixer device, which by default is the output device. If you do
465 not specify a mixer control name, shairport-sync will adjust the
466 volume in software.
467 mixer_device="mixer_device";
469 By default, the mixer is assumed to be output_device. Use this
470 setting to specify a device other than the output device.
471 output_rate=frame rate;
473 Use this setting to specify the frame rate to output to the ALSA
474 device. Allowable values are "auto" (default), 44100, 88200,
475 176400 and 352800. The device must have the capability to accept
476 the rate you specify. There is no particular reason to use any‐
477 thing other than 44100 if it is available, and if "auto" is se‐
478 lected, the lowest of these rates available, starting at 44100,
479 will be selected.
480 output_format="format";
482 Use this setting to specify the format that should be used to
483 send data to the ALSA device. Allowable values are "auto" (de‐
484 fault), "U8", "S8", "S16", "S24", "S24_3LE", "S24_3BE" or "S32".
485 The device must have the capability to accept the format you
486 specify.
487 "S" means signed; "U" means unsigned; BE means big-endian and LE
489 means little-endian. Except where stated (using *LE or *BE), en‐
490 dianness matches that of the processor. The default is "S16".
491 If you are using a hardware mixer, S16 is fine, as audio will
493 pass through Shairport Sync unmodified except for interpolation,
494 but any of the higher-resolution formats are okay too. If you
495 are using the software mixer, use 32- or 24-bit, if your device
496 is capable of it, in order to get the lowest possible levels of
497 dither. The "auto" setting will cause Shairport Sync to choose
498 the highest resolution available.
499 disable_synchronization="no";
501 This is an advanced setting and is for debugging only. Set to
502 "yes" to disable synchronization. Default is "no". If you use it
503 to disable synchronisation, then sooner or later you'll experi‐
504 ence audio glitches due to audio buffer overflow or underflow.
505 period_size=number;
507 Use this optional advanced setting to set the alsa period size
508 near to this value.
509 buffer_size=number;
511 Use this optional advanced setting to set the alsa buffer size
512 near to this value.
513 use_mmap_if_available="yes";
515 Use this optional advanced setting to control whether MMAP-based
516 output is used to communicate with the DAC. Default is "yes".
517 mute_using_playback_switch="no";
519 This is an advanced setting and the default is "no". If it is
520 set to "yes", hardware mute will be used where it is available.
521 Set it to "no" to prevent the hardware mute being used.
522 If Shairport Sync is sharing the output device with other appli‐
524 cations, it is best to leave this set to "no" for compatibility
525 with those applications.
526 Another motivation for this is to allow the ALSA function call
528 "snd_mixer_selem_set_playback_switch_all" to be avoided. It is
529 incorrectly implemented on certain soundcards, including the em‐
530 ulated card in VMWare Fusion 8.5.
531 maximum_stall_time=seconds;
533 If an output device fails to accept any audio frames for more
534 than the time, in seconds, specified here (0.2 seconds by de‐
535 fault), it is considered to have malfunctioned. It will result
536 in the run_this_if_an_unfixable_error_is_detected program, if
537 any, being called.
538 Implemented for the ALSA back end only.
540 disable_standby_mode="never";
542 Shairport Sync has a "Disable Standby" feature to eliminate cer‐
543 tain faint-but-annoying audible pops and clicks. When activsted,
544 it prevents an output device from entering standby mode and thus
545 it minimises standby/busy transitions, which can sometimes be
546 heard. Use this setting to control when the Disable Standby fea‐
547 ture is active: "never" means it will never be activated, "al‐
548 ways" means it will be active as soon as shairport-sync starts
549 running, and "auto" means it will be active while shairport-sync
550 is in the "active" state.
551 Shairport Sync goes "active" when a play session starts. When
553 the play session ends, the system will stay active until the
554 time specified in the active_state_timeout setting elapses. If a
555 new play session starts before that, the system will remain ac‐
556 tive. Otherwise, the system will go inactive.
557 "SNDIO" SETTINGS
559 These settings are for the SNDIO back end, used to communicate
560 with audio output devices in the SNDIO system.
561 device="snd/0";
563 Use this optional setting to specify the name of the output de‐
564 vice, e.g. "snd/0". The default is to use the SNDIO system's de‐
565 fault.
566 rate=44100;
568 Use this optional setting to specify the output rate in frames
569 per second. Valid rates are 44100, 88200, 176400 or 352800. The
570 output device must have the capability to accept data at the
571 specified rate. The default is 44100.
572 format="S16";
574 Use this optional setting to specify the output format. Allow‐
575 able values are "U8", "S8", "S16", "S24", "S24_3LE", "S24_3BE"
576 or "S32". The device must have the capability to accept the for‐
577 mat you specify.
578 "S" means signed; "U" means unsigned; BE means big-endian and LE
580 means little-endian. Except where stated (using *LE or *BE), en‐
581 dianness matches that of the processor. The default is "S16".
582 Since the SNDIO backend does not use a hardware mixer for volume
584 control, dither will be introduced into the output if it is less
585 than full volume. Thus, (unless you are ignoring the volume con‐
586 trol setting), consider using 32- or 24-bit output if your de‐
587 vice is capable of it, to get the lowest possible levels of
588 dither.
589 Please note that 32- or 24-bit has not been extensively tested
591 on SNDIO.
592 round=value;
594 Use this optional advanced setting to specify the period size of
595 the SNDIO channel. If omitted, a SNDIO system default value will
596 be used.
597 bufsiz=value;
599 Use this optional advanced setting to specify the buffer size of
600 the SNDIO channel. If omitted, a SNDIO system default value will
601 be used.
602 "PA" SETTINGS
604 These settings are for the new PulseAudio backend.
605 application_name="Shairport Sync";
607 Use this to set the name to appear in the Sounds "Applications"
608 tab when Shairport Sync is active. The default is the name
609 "Shairport Sync".
610 "PIPE" SETTINGS
612 These settings are for the PIPE backend, used to route audio to
613 a named unix pipe. The audio is in raw CD audio format: PCM 16
614 bit little endian, 44,100 samples per second, interleaved
615 stereo.
616 name="/path/to/pipe";
618 Use this to specify the name and location of the pipe. The pipe
619 will be created and opened when shairport-sync starts up and
620 will be closed upon shutdown. Frames of audio will be sent to
621 the pipe in packets of 352 frames and will be discarded if the
622 pipe has not have a reader attached. The sender will wait for up
623 to five seconds for a packet to be written before discarding it.
624 "STDOUT" SETTINGS
626 There are no settings for the STDOUT backend.
627 "AO" SETTINGS
629 There are no configuration file settings for the AO backend.
630 "METADATA" SETTINGS
632 shairport-sync can process metadata provided by the source, such
633 as Track Number, Album Name, cover art, etc. and can provide ad‐
634 ditional metadata such as volume level, pause/resume, etc. It
635 sends the metadata to a pipe, by default /tmp/shairport-sync-
636 metadata. To process metadata, shairport-sync must have been
637 compiled with metadata support included. You can check that this
638 is so by running the command $ shairport-sync -V; the identifi‐
639 cation string will contain the word metadata.
640 Please note that different sources provide different levels of
642 metadata. Some provide a lot; some provide almost none.
643 The metadata group of settings allow you to enable metadata han‐
645 dling and to control certain aspects of it:
646 enabled="choice";
648 Set the choice to "yes" to enable shairport-sync to look for
649 metadata from the audio source and to forward it, along with
650 metadata generated by shairport-sync itself, to the metadata
651 pipe. The default is "no".
652 include_cover_art="choice";
654 Set the choice to "yes" to enable shairport-sync to look for
655 cover art from the audio source and to include it in the feed to
656 the metadata pipe. You must also enable metadata (see above).
657 One reason for not including cover art is that the images can
658 sometimes be very large and may delay transmission of subsequent
659 metadata through the pipe. The default is "no".
660 pipe_name="filepathname";
662 Specify the absolute path name of the pipe through which meta‐
663 data should be sent The default is /tmp/shairport-sync-metadata.
664 socket_address="hostnameOrIP";
666 If hostnameOrIP is set to a host name or and IP address, UDP
667 packets containing metadata will be sent to this address. May be
668 a multicast address. Additionally, socket-port must be non-zero
669 and enabled must be set to "yes".
670 socket_port=port;
672 If socket_address is set, use port to specify the port to send
673 UDP packets to. Must not be zero.
674 socket_msglength=65000;
676 The maximum packet size for any UDP metadata. This must be be‐
677 tween 500 or 65000. The default is 500.
678 "DIAGNOSTICS" SETTINGS
680 statistics="setting";
682 Use this setting to enable ("yes") or disable ("no") the output
683 of some statistical information to the system log (or to STDERR
684 if the -u command line option is chosen). The default is to dis‐
685 able statistics.
686 log_verbosity=0;
688 Use this to specify how much debugging information should sent
689 to the system log (or to STDERR if the -u command line option is
690 chosen). The value 0 means no debug information, 3 means most
691 debug information. The default is 0.
692
694 This section is about the command-line options available in shairport-
695 sync.
696 Note: if you are setting up shairport-sync for the first time or are
698 updating an existing installation, you are encouraged to use the con‐
699 figuration file settings described above. Most of the command-line op‐
700 tions described below simply replicate the configuration settings and
701 are retained to provide backward compatibility with older installations
702 of shairport-sync.
703 Many command-line options take sensible default values, so you can nor‐
705 mally ignore most of them. See the EXAMPLES section for typical usages.
706 There are two kinds of command-line options for shairport-sync: regular
708 program options and audio backend options. Program options are always
709 listed first, followed by any audio backend options, preceded by a --
710 symbol.
711
713 These command-line options are used by shairport-sync itself.
714 -a service name | --name=service name
716 Use this service name to identify this player in iTunes, etc.
717 The following substitutions are allowed: %h for the computer's
719 hostname, %H for the computer's hostname with the first letter
720 capitalised (ASCII only), %v for the shairport-sync version num‐
721 ber, e.g. "3.0.1" and %V for the shairport-sync version string,
722 e.g. "3.0.1-OpenSSL-Avahi-ALSA-soxr-metadata-sysconfdir:/etc".
723 The default is "%H", which is replaced by the hostname with the
725 first letter capitalised.
726 -B program | --on-start=program
728 Execute program when playback is about to begin. Specify the
729 full path to the program, e.g. /usr/bin/logger. Executable
730 scripts can be used, but they must have the appropriate shebang
731 (#!/bin/sh in the headline.
732 If you want shairport-sync to wait until the command has com‐
734 pleted before starting to play, select the -w option as well.
735 -c filename | --configfile=filename
737 Read configuration settings from filename. The default is to
738 read them from the shairport-sync.conf in the System Configura‐
739 tion Directory -- /etc in Linux, /usr/local/etc in BSD unixes.
740 For information about configuration settings, see the "Configu‐
741 ration File Settings" section above.
742 -d | --daemon
744 Instruct shairport-sync to demonise itself. It will write its
745 Process ID (PID) to a file, usually at /var/run/shairport-
746 sync/shairport-sync.pid, which is used by the -k, -D and -R op‐
747 tions to locate the daemon at a later time. See also the -j op‐
748 tion. Only available if shaiport-sync has been compiled with
749 libdaemon support.
750 -E program | --on-stop=program
752 Execute program when playback has ended. Specify the full path
753 to the program, e.g. /usr/bin/logger. Executable scripts can be
754 used, but they must have the appropriate shebang (#!/bin/sh in
755 the headline.
756 If you want shairport-sync to wait until the command has com‐
758 pleted before continuing, select the -w option as well.
759 --get-coverart
761 This option requires the --meta-dir option to be set, and en‐
762 ables shairport-sync to request cover art from the source and to
763 transmit it through the metadata pipe.
764 Please note that cover art data may be very large, and may place
766 too great a burden on your network.
767 -h | --help
769 Print brief help message and exit.
770 -j Instruct shairport-sync to demonise itself. Unlike the -d op‐
772 tion, it will not write a Process ID (PID) to a file -- it will
773 just (hence the "j") demonise itself. Only available if
774 shaiport-sync has been compiled with libdaemon support.
775 -k | --kill
777 Kill the shairport-sync daemon and exit. (Requires that the dae‐
778 mon has written its PID to an agreed file -- see the -d option.
779 Only available if shaiport-sync has been compiled with libdaemon
780 support.)
781 --logOutputLevel
783 Use this to log the volume level when the volume is changed. It
784 may be useful if you are trying to determine a suitable value
785 for the maximum volume level. Not available as a configuration
786 file setting.
787 -L | --latency=latency
789 Use this to set the default latency, in frames, for audio coming
790 from an unidentified source or from an iTunes Version 9 or ear‐
791 lier source. The standard value for the default latency is
792 88,200 frames, where there are 44,100 frames to the second.
793 Please note that this feature is deprecated and will be removed
795 in a future version of shairport-sync.
796 --meta-dir=directory
798 Listen for metadata coming from the source and send it, along
799 with metadata from shairport-sync itself, to a pipe called
800 shairport-sync-metadata in the directory you specify. If you add
801 the --get-cover-art then cover art will be sent through the pipe
802 too. See https://github.com/mikebrady/shairport-sync-metadata-
803 reader for a sample metadata reader.
804 -m mdnsbackend | --mdns=mdnsbackend
806 Force the use of the specified mDNS backend to advertise the
807 player on the network. The default is to try all mDNS backends
808 until one works.
809 -o outputbackend | --output=outputbackend
811 Force the use of the specified output backend to play the audio.
812 The default is to try the first one.
813 -p port | --port=port
815 Listen for play requests on port. The default is to use port
816 5000.
817 --password=secret
819 Require the password secret to be able to connect and stream to
820 the service.
821 -r threshold | --resync=threshold
823 Resynchronise if timings differ by more than threshold frames.
824 If the output timing differs from the source timing by more than
825 the threshold, output will be muted and a full resynchronisation
826 will occur. The default threshold is 2,205 frames, i.e. 50 mil‐
827 liseconds. Specify 0 to disable resynchronisation. This setting
828 is deprecated and will be removed in a future version of shair‐
829 port-sync.
830 --statistics
832 Print some statistics in the standard output, or in the logfile
833 if in daemon mode.
834 -S mode | --stuffing=mode
836 Stuff the audio stream using the mode. "Stuffing" refers to the
837 process of adding or removing frames of audio to or from the
838 stream sent to the output device to keep it exactly in synchrony
839 with the player. The default mode, basic, is normally almost
840 completely inaudible. The alternative mode, soxr, is even less
841 obtrusive but requires much more processing power. For this
842 mode, support for libsoxr, the SoX Resampler Library, must be
843 selected when shairport-sync is compiled.
844 -t timeout | --timeout=timeout
846 Exit play mode if the stream disappears for more than timeout
847 seconds.
848 When shairport-sync plays an audio stream, it starts a play ses‐
850 sion and will return a busy signal to any other sources that at‐
851 tempt to use it. If the audio stream disappears for longer than
852 timeout seconds, the play session will be terminated. If you
853 specify a timeout time of 0, shairport-sync will never signal
854 that it is busy and will not prevent other sources from "barging
855 in" on an existing play session. The default value is 120 sec‐
856 onds.
857 --tolerance=frames
859 Allow playback to be up to frames out of exact synchronization
860 before attempting to correct it. The default is 88 frames, i.e.
861 2 ms. The smaller the tolerance, the more likely it is that
862 overcorrection will occur. Overcorrection is when more correc‐
863 tions (insertions and deletions) are made than are strictly nec‐
864 essary to keep the stream in sync. Use the --statistics option
865 to monitor correction levels. Corrections should not greatly ex‐
866 ceed net corrections. This setting is deprecated and will be re‐
867 moved in a future version of shairport-sync.
868 -u If you are running shairport-sync from the command line and want
870 logs to appear there, use this option. Otherwise, logs may go to
871 the system log.
872 -V | --version
874 Print version information and exit.
875 -v | --verbose
877 Print debug information to the system log, or or to STDERR if
878 the -u command line option is also chosen. Repeat up to three
879 times to get more detail.
880 -w | --wait-cmd
882 Wait for commands specified using -B or -E to complete before
883 continuing execution.
884
886 These command-line options are passed to the chosen audio backend. The
887 audio backend options are preceded by a -- symbol to introduce them and
888 to separate them from any program options. In this way, option letters
889 can be used as program options and also as audio backend options with‐
890 out ambiguity.
891 In the ALSA backend, audio is sent to an output device which you can
893 specify using the -d option. The output level (the "volume") is con‐
894 trolled using a level control associated with a mixer. By default, the
895 mixer is implemented in shairport-sync itself in software. To use a
896 hardware level control on a mixer on the sound card, specify the name
897 of the mixer control with the -c option. If the mixer is not associated
898 with the output device, then you need to specify where the mixer is to
899 be found with the -m option.
900 -c controlname
902 Use the level control called controlname on the hardware mixer
903 for controlling volume. This is needed if the mixer type is
904 specified, using the -t option, to be hardware. There is no de‐
905 fault.
906 -d device
908 Use the specified output device. You may specify a card, e.g.
909 hw:0, in which case the default output device on the card will
910 be chosen. Alternatively, you can specify a specific device on a
911 card, e.g. hw:0,0. The default is the device named default.
912 -m mixer
914 Use the specified hardware mixer for volume control. Use this to
915 specify where the mixer is to be found. For example, if the
916 mixer is associated with a card, as is often the case, specify
917 the card, e.g. hw:0. If (unusually) the mixer is associated with
918 a specific device on a card, specify the device, e.g. hw:0,1.
919 The default is the device named in the -d option, if given, or
920 the device named default.
921 -t devicetype
923 This option is deprecated and is ignored. For your information,
924 its functionality has been automatically incorporated in the -c
925 option -- if you specify a mixer name with the -c option, it is
926 assumed that the mixer is implemented in hardware.
927
929 Here is a slightly contrived example:
930 shairport-sync -d -a "Joe's Stereo" -S soxr -- -d hw:1,0 -m hw:1 -c PCM
932 The program will run in daemon mode ( -d ), will be visible as "Joe's
934 Stereo" ( -a "Joe's Stereo" ) and will use the SoX Resampler Library-
935 based stuffing ( -S soxr ). The audio backend options following the --
936 separator specify that the audio will be output on output 0 of sound‐
937 card 1 ( -d hw:1,0 ) and will take advantage of the same sound card's
938 mixer ( -m hw:1 ) using the level control named "PCM" ( -c "PCM" ).
939 The example above is slightly contrived in order to show the use of the
941 -m option. Typically, output 0 is the default output of a card, so the
942 output device could be written -d hw:1 and then the mixer option would
943 be unnecessary, giving the following, simpler, command:
944 shairport-sync -d -a "Joe's Stereo" -S soxr -- -d hw:1 -c PCM
946
948 Mike Brady developed shairport-sync from the original Shairport by
949 James Laird.
950 shairport-sync can be found at https://github.com/mikebrady/shairport-
952 sync.
953 Shairport can be found at https://github.com/abrasive/shairport.
955
957 This man page was written using xml2man(1) by Oliver Kurth.
958Manuals User shairport-sync(7)