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