1shairport-sync(7) Miscellaneous Information Manual shairport-sync(7)
2
6 shairport-sync - Synchronised Audio Player for iTunes / AirPlay
7
9 shairport-sync [-djvw] [-a name] [-A latency] [-B command] [-c configu‐
10 rationfile] [-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 -D
16 shairport-sync -k
18 shairport-sync -h
20 shairport-sync -R
22 shairport-sync -V
24
26 shairport-sync plays audio streamed from iTunes or from an AirPlay
27 device to an ALSA compatible audio output device (available on Linux
28 and FreeBSD) , to a "sndio" output device (available on OpenBSD, Free‐
29 BSD and Linux) or to a PulseAudio output stream (available on Linux).
30 A feature of shairport-sync is that it offers full audio synchronisa‐
32 tion. Full audio synchronisation means that audio is played on the out‐
33 put device at exactly the time specified by the audio source. This
34 means that if many devices are playing the same stream at the same
35 time, all the outputs will stay in step with one another. This allows
36 multiple devices to play the same source without getting out of phase
37 with one another, enabling, for example, simultaneous multi-room opera‐
38 tion.
39 shairport-sync can be compiled to stream audio synchronised audio out‐
41 put to a unix pipe or to standard output, or to audio systems that do
42 not provide timing information. This could perhaps be described as par‐
43 tial audio synchronisation, where synchronised audio is provided by
44 shairport-sync, but what happens to it in the subsequent processing
45 chain, before it reaches the listener's ear, is outside the control of
46 shairport-sync.
47 shairport-sync can be compiled to stream metadata to a pipe or socket.
49 Settings can be made using the configuration file (recommended for all
51 new installations) or by using command-line options.
52
54 You should use the configuration file for setting up shairport-sync.
55 This file is usually shairport-sync.conf and is generally located in
56 the System Configuration Directory, which is normally the /etc direc‐
57 tory in Linux or the /usr/local/etc directory in BSD unixes. You may
58 need to have root privileges to modify it.
59 (Note: Shairport Sync may have been compiled to use a different config‐
61 uration directory. You can determine which by performing the command $
62 shairport-sync -V. One of the items in the output string is the value
63 of the sysconfdir, i.e. the System Configuration Directory.)
64 Within the configuraton file, settings are organised into groups, for
66 example, there is a "general" group of standard settings, and there is
67 an "alsa" group with settings that pertain to the ALSA back end. Here
68 is an example of a typical configuration file:
69 general = {
71 name = "Mike's Boombox";
73 interpolation = "soxr";
75 password = "secret";
77 output_backend = "alsa";
79 };
81 alsa = {
85 output_device = "hw:0";
87 mixer_control_name = "PCM";
89 };
91 Most settings have sensible default values, so -- as in the example
93 above -- users generally only need to set (1) the service name, (2) a
94 password (if desired) and (3) the output device. If the output device
95 has a mixer that can be used for volume control, then (4) the volume
96 control's name should be specified. It is highly desirable to use the
97 output device's mixer for volume control, if available -- response time
98 is reduced to zero and the processor load is reduced. In the example
99 above, "soxr" interpolation was also enabled.
100 A sample configuration file with all possible settings, but with all of
102 them commented out, is installed at shairport-sync.conf.sample, within
103 the System Configuration Directory -- /etc in Linux, /usr/local/etc in
104 BSD unixes.
105 To retain backwards compatibility with previous versions of shairport-
107 sync you can use still use command line options, but any new features,
108 etc. will be available only via configuration file settings.
109 The configuration file is processed using the libconfig library -- see
111 http://www.hyperrealm.com/libconfig/libconfig_manual.html.
112 "GENERAL" SETTINGS
114 These are the settings available within the general group:
115 name="service_name";
117 Use this service_name to identify this player in iTunes, etc.
118 The following substitutions are allowed: %h for the computer's
120 hostname, %H for the computer's hostname with the first letter
121 capitalised (ASCII only), %v for the shairport-sync version num‐
122 ber, e.g. "3.0.1" and %V for the shairport-sync version string,
123 e.g. "3.0.1-OpenSSL-Avahi-ALSA-soxr-metadata-sysconfdir:/etc".
124 The default is "%H", which is replaced by the hostname with the
126 first letter capitalised.
127 password="password";
129 Require the password password to connect to the service. If you
130 leave this setting commented out, no password is needed.
131 interpolation="mode";
133 Interpolate, or "stuff", the audio stream using the mode. Inter‐
134 polation here refers to the process of adding or removing frames
135 of audio to or from the stream sent to the output device to keep
136 it exactly in synchrony with the player. The default mode,
137 "basic", is normally almost completely inaudible. The alterna‐
138 tive mode, "soxr", is even less obtrusive but requires much more
139 processing power. For this mode, support for libsoxr, the SoX
140 Resampler Library, must be selected when shairport-sync is com‐
141 piled.
142 statistics="setting";
144 Use this setting to enable ("yes") or disable ("no") the output
145 of some statistical information on the console or in the log.
146 The default is to disable statistics.
147 mdns_backend="backend";
149 shairport-sync has a number of modules of code ("backends") for
150 interacting with the mDNS service to be used to advertise
151 itself. Normally, the first mDNS backend that works is selected.
152 This setting forces the selection of the specific mDNS backend.
153 The default is "avahi". Perform the command shairport-sync -h to
154 get a list of available mDNS modules.
155 output_backend="backend";
157 shairport-sync has a number of modules of code ("backends")
158 through which audio is output. Normally, the first audio backend
159 that works is selected. This setting forces the selection of the
160 specific audio backend. Perform the command shairport-sync -h to
161 get a list of available audio backends -- the default is the
162 first on this list. Only the "alsa", "sndio" and "pa" backends
163 support synchronisation.
164 port=portnumber;
166 Use this to specify the portnumber shairport-sync uses to listen
167 for service requests from iTunes, etc. The default is port 5000.
168 udp_port_base=portnumber;
170 When shairport-sync starts to play audio, it establises three
171 UDP connections to the audio source. Use this setting to specify
172 the starting portnumber for these three ports. It will pick the
173 first three unused ports starting from portnumber. The default
174 is port 6001.
175 udp_port_range=range;
177 Use this in conjunction with the prevous setting to specify the
178 range of ports that can be checked for availability. Only three
179 ports are needed. The default is 100, thus 100 ports will be
180 checked from port 6001 upwards until three are found.
181 drift_tolerance_in_seconds=seconds;
183 Allow playback to drift up to seconds out of exact synchroniza‐
184 tion before attempting to correct it. The default is 0.002 sec‐
185 onds, i.e. 2 milliseconds. The smaller the tolerance, the more
186 likely it is that overcorrection will occur. Overcorrection is
187 when more corrections (insertions and deletions) are made than
188 are strictly necessary to keep the stream in sync. Use the sta‐
189 tistics setting to monitor correction levels. Corrections should
190 not greatly exceed net corrections. This setting replaces the
191 deprecated drift setting.
192 resync_threshold_in_seconds=threshold;
194 Resynchronise if timings differ by more than threshold seconds.
195 If the output timing differs from the source timing by more than
196 the threshold, output will be muted and a full resynchronisation
197 will occur. The default threshold is 0.050 seconds, i.e. 50 mil‐
198 liseconds. Specify 0.0 to disable resynchronisation. This set‐
199 ting replaces the deprecated resync_threshold setting.
200 log_verbosity=0;
202 Use this to specify how much debugging information should be
203 output or logged. The value 0 means no debug information, 3
204 means most debug information. The default is 0.
205 ignore_volume_control="choice";
207 Set this choice to "yes" if you want the volume to be at 100% no
208 matter what the source's volume control is set to. This might be
209 useful if you want to set the volume on the output device, inde‐
210 pendently of the setting at the source. The default is "no".
211 volume_max_db=dBvalue;
213 Specify the maximum output level to be used with the hardware
214 mixer, if used. If no hardware mixed is used, this setting
215 speciies the maximum setting permissible in the software mixer,
216 which has an attenuation of from 0.0 dB down to -96.3 dB.
217 volume_range_db=dBvalue;
219 Use this dBvalue to reduce or increase the attenuation range, in
220 decibels, between the minimum and maximum volume.
221 For example, if a mixer has a minimum volume of -80 dB and a
223 maximum of +20 dB, you might wish to use only 60 dB of the 100
224 dB available. This might be because the sound becomes inaudible
225 at the lowest setting and unbearably loud at the highest setting
226 -- indeed, many domestic HiFi systems have a volume control
227 range of just 60 to 80dB.
228 Another potential use might be where the range specified by the
230 mixer does not match the capabilities of the device. For exam‐
231 ple, the Raspberry Pi's DAC that feeds the built-in audio jack
232 claims a range of 106 dB but has a useful range of only about 30
233 dB. The setting allows you to specify the maximum range from
234 highest to lowest. The range suggested for the Raspberry Pi's
235 built-in audio DAC, which feeds the headphone jack, is 30. Using
236 it in this case gives the volume control a much more useful
237 range of settings.
238 As a third example, you can actually extend the range provided
240 by a mixer. Many cheaper DACs have hardware mixers that offer a
241 restricted attenuation range. If you specify a volume range
242 greater than the range of the mixer, software attenuation and
243 hardware attenuation will be combined to give the specified
244 range.
245 If you omit this setting, the native range of the mixer is used.
247 regtype="regTypeString";
249 Use this advanced setting to set the service type and transport
250 to be advertised by Zeroconf/Bonjour. Default is "_raop._tcp".
251 playback_mode="mode";
253 The mode can be "stereo", "mono", "reverse stereo", "both left"
254 or "both right". Default is "stereo".
255 interface="name";
257 Use this advanced setting if you want to confine Shairport Sync
258 to the named interface. Leave it commented out to get the
259 default bahaviour.
260 alac_decoder="decodername";
262 This can be "hammerton" or "apple". This advanced setting allows
263 you to choose the original Shairport decoder by David Hammerton
264 or the Apple Lossless Audio Codec (ALAC) decoder written by
265 Apple. Shairport Sync must have been compiled with the configu‐
266 ration setting "--with-apple-alac" and the Apple ALAC decoder
267 library must be present for this to work.
268 audio_backend_latency_offset_in_seconds=offset_in_seconds;
270 Set this offset_in_seconds to compensate for a fixed delay in
271 the audio back end. For example, if the output device delays by
272 100 ms, set this to -0.1.
273 audio_backend_buffer_desired_length_in_seconds=length_in_seconds;
275 Use this length_in_seconds to set the desired length of the
276 queue of audio frames in the backend's output buffer.
277 The default is 0.15 seconds for the ALSA backend, 0.35 seconds
279 for the PA backend and one second for all other backends.
280 If this value is set too small, underflow may occur on low-pow‐
282 ered machines. If set too large, the response times to the vol‐
283 ume control may become excessive, or it may exceed the backend's
284 buffer size. It may need to be larger on low-powered machines
285 that are also performing other tasks, such as processing meta‐
286 data.
287 audio_backend_silent_lead_in_time=lead_in_time_in_seconds;
289 This is an advanced setting. Use the lead_in_time_in_seconds to
290 set the desired length of the period of silence (a "silent lead-
291 in") played before a play session begins.
292 The purpose of this silent lead-in is to give the backend suffi‐
294 cient time to prepare for operation and to make an estimate
295 (and, importantly, to correct the estimate) of the exact time at
296 which to begin playing audio to achieve initial synchronisation.
297 The value can be from 0.0 up to a maximum of either 4.0 seconds.
298 The actual duration will be close to the setting but can not
299 exceed the latency set by the client, usually 2 seconds or a
300 little more.
301 If the value chosen is too short for synchronised backends such
303 as the ALSA, sndio or PA backends, then audio will not be syn‐
304 chronised correctly at the start of play. The default is to have
305 a silent lead-in of approximately the same time as the latency
306 set by the client.
307 run_this_when_volume_is_set="/full/path/to/application/and/args";
309 Here you can specify a program and its arguments that will be
310 run when the volume is set or changed. Be careful to include the
311 full path to the application. The application must be marked as
312 executable and, if it is a script, its first line must begin
313 with the standard shebang #!/bin/... as appropriate.
314 The desired AirPlay volume is appended to the end of the command
316 line - leave a space if you want it treated as an extra argu‐
317 ment. AirPlay volume goes from 0.0 to -30.0 and -144.0 means
318 "mute".
319 "ALSA" SETTINGS
321 These settings are for the ALSA back end, used to communicate
322 with audio output devices in the ALSA system. (By the way, you
323 can use tools such as alsamixer or aplay to discover what
324 devices are available.) Use these settings to select the output
325 device and the mixer control to be used to control the output
326 volume. You can additionally set the desired size of the output
327 buffer and you can adjust overall latency. Here are the alsa
328 group settings:
329 output_device="output_device";
331 Use the output device called output_device. The default is the
332 device called "default".
333 mixer_control_name="name";
335 Specify the name of the mixer control to be used by shairport-
336 sync to control the volume. The mixer control must be on the
337 mixer device, which by default is the output device. If you do
338 not specify a mixer control name, shairport-sync will adjust the
339 volume in software.
340 mixer_device="mixer_device";
342 By default, the mixer is assumed to be output_device. Use this
343 setting to specify a device other than the output device.
344 output_rate=frame rate;
346 Use this setting to specify the frame rate to output to the ALSA
347 device. Allowable values are 44100 (default), 88200, 176400 and
348 352800. The device must have the capability to accept the format
349 you specify. There is no particular reason to use anything other
350 than 44100 if it is available.
351 output_format="format";
353 Use this setting to specify the format that should be used to
354 send data to the ALSA device. Allowable values are "U8", "S8",
355 "S16", "S24", "S24_3LE", "S24_3BE" or "S32". The device must
356 have the capability to accept the format you specify.
357 "S" means signed; "U" means unsigned; BE means big-endian and LE
359 means little-endian. Except where stated (using *LE or *BE),
360 endianness matches that of the processor. The default is "S16".
361 If you are using a hardware mixer, the best setting is S16, as
363 audio will pass through Shairport Sync unmodifed except for
364 interpolation. If you are using the software mixer, use 32- or
365 24-bit, if your device is capable of it, to get the lowest pos‐
366 sible levels of dither.
367 disable_synchronization="no";
369 This is an advanced setting and is for debugging only. Set to
370 "yes" to disable synchronization. Default is "no". If you use it
371 to disable synchronisation, then sooner or later you'll experi‐
372 ence audio glitches due to audio buffer overflow or underflow.
373 period_size=number;
375 Use this optional advanced setting to set the alsa period size
376 near to this value.
377 buffer_size=number;
379 Use this optional advanced setting to set the alsa buffer size
380 near to this value.
381 use_mmap_if_available="yes";
383 Use this optional advanced setting to control whether MMAP-based
384 output is used to communicate with the DAC. Default is "yes".
385 mute_using_playback_switch="no";
387 This is an advanced setting and the default is "no". If it is
388 set to "yes", hardware mute will be implemented using a feature
389 called a 'playback switch', where one is available. Set it to
390 "no" to prevent the playback switch being used.
391 If Shairport Sync is sharing the output device with other appli‐
393 cations, it is best to leave this set to "no" for compatibility
394 with those applications.
395 Another motivation for this is to allow the alsa function call
397 "snd_mixer_selem_set_playback_switch_all" to be avoided. It is
398 incorrectly implemented on certain soundcards, including the
399 emulated card in VMWare Fusion 8.5.
400 "SNDIO" SETTINGS
402 These settings are for the SNDIO back end, used to communicate
403 with audio output devices in the SNDIO system.
404 device="snd/0";
406 Use this optional setting to specify the name of the output
407 device, e.g. "snd/0". The default is to use the SNDIO system's
408 default.
409 rate=44100;
411 Use this optional setting to specify the output rate in frames
412 per second. Valid rates are 44100, 88200, 176400 or 352800. The
413 output device must have the capability to accept data at the
414 specified rate. The default is 44100.
415 format="S16";
417 Use this optional setting to specify the output format. Allow‐
418 able values are "U8", "S8", "S16", "S24", "S24_3LE", "S24_3BE"
419 or "S32". The device must have the capability to accept the for‐
420 mat you specify.
421 "S" means signed; "U" means unsigned; BE means big-endian and LE
423 means little-endian. Except where stated (using *LE or *BE),
424 endianness matches that of the processor. The default is "S16".
425 Since the SNDIO backend does not use a hardware mixer for volume
427 control, dither will be introduced into the output if it is less
428 than full volume. Thus, (unless you are ignoring the volume con‐
429 trol setting), consider using 32- or 24-bit output if your
430 device is capable of it, to get the lowest possible levels of
431 dither.
432 Please note that 32- or 24-bit has not been extensively tested
434 on SNDIO.
435 round=value;
437 Use this optional advanced setting to specify the period size of
438 the SNDIO channel. If omitted, a SNDIO system default value will
439 be used.
440 bufsiz=value;
442 Use this optional advanced setting to specify the buffer size of
443 the SNDIO channel. If omitted, a SNDIO system default value will
444 be used.
445 "PA" SETTINGS
447 These settings are for the new PulseAudio backend.
448 application_name="Shairport Sync";
450 Use this to set the name to appear in the Sounds "Applications"
451 tab when Shairport Sync is active. The default is the name
452 "Shairport Sync".
453 "PIPE" SETTINGS
455 These settings are for the PIPE backend, used to route audio to
456 a named unix pipe. The audio is in raw CD audio format: PCM 16
457 bit little endian, 44,100 samples per second, interleaved
458 stereo.
459 name="/path/to/pipe";
461 Use this to specify the name and location of the pipe. The pipe
462 will be created and opened when shairport-sync starts up and
463 will be closed upon shutdown. Frames of audio will be sent to
464 the pipe in packets of 352 frames and will be discarded if the
465 pipe has not have a reader attached. The sender will wait for up
466 to five seconds for a packet to be written before discarding it.
467 "STDOUT" SETTINGS
469 There are no settings for the STDOUT backend.
470 "AO" SETTINGS
472 There are no configuration file settings for the AO backend.
473 "METADATA" SETTINGS
475 shairport-sync can process metadata provided by the source, such
476 as Track Number, Album Name, cover art, etc. and can provide
477 additional metadata such as volume level, pause/resume, etc. It
478 sends the metadata to a pipe, by default /tmp/shairport-sync-
479 metadata. To process metadata, shairport-sync must have been
480 compiled with metadata support included. You can check that this
481 is so by running the command $ shairport-sync -V; the identifi‐
482 cation string will contain the word metadata.
483 Please note that different sources provide different levels of
485 metadata. Some provide a lot; some provide almost none.
486 The metadata group of settings allow you to enable metadata han‐
488 dling and to control certain aspects of it:
489 enabled="choice";
491 Set the choice to "yes" to enable shairport-sync to look for
492 metadata from the audio source and to forward it, along with
493 metadata generated by shairport-sync itself, to the metadata
494 pipe. The default is "no".
495 include_cover_art="choice";
497 Set the choice to "yes" to enable shairport-sync to look for
498 cover art from the audio source and to include it in the feed to
499 the metadata pipe. You must also enable metadata (see above).
500 One reason for not including cover art is that the images can
501 sometimes be very large and may delay transmission of subsequent
502 metadata through the pipe. The default is "no".
503 pipe_name="filepathname";
505 Specify the absolute path name of the pipe through which meta‐
506 data should be sent The default is /tmp/shairport-sync-metadata.
507 socket_address="hostnameOrIP";
509 If hostnameOrIP is set to a host name or and IP address, UDP
510 packets containing metadata will be sent to this address. May be
511 a multicast address. Additionally, socket-port must be non-zero
512 and enabled must be set to "yes".
513 socket_port=port;
515 If socket_address is set, use port to specify the port to send
516 UDP packets to. Must not be zero.
517 socket_msglength=65000;
519 The maximum packet size for any UDP metadata. This must be
520 between 500 or 65000. The default is 500.
521 "SESSIONCONTROL" SETTINGS
523 shairport-sync can run programs just before it starts to play an
524 audio stream and just after it finishes. You specify them using
525 the sessioncontrol group settings run_this_before_play_begins
526 and run_this_after_play_ends.
527 run_this_before_play_begins="/path/to/application and args";
529 Here you can specify a program and its arguments that will be
530 run just before a play session begins. Be careful to include the
531 full path to the application. The application must be marked as
532 executable and, if it is a script, its first line must begin
533 with the standard shebang #!/bin/... as appropriate.
534 run_this_after_play_ends="/path/to/application and args";
536 Here you can specify a program and its arguments that will be
537 run just after a play session ends. Be careful to include the
538 full path to the application. The application must be marked as
539 executable and, if it is a script, its first line must begin
540 with the standard shebang #!/bin/... as appropriate.
541 wait_for_completion="choice";
543 Set choice to "yes" to make shairport-sync wait until the pro‐
544 grams specified in the run_this_before_play_begins,
545 run_this_after_play_ends and run_this_when_volume_is_set have
546 completed execution before continuing. The default is "no".
547 allow_session_interruption="choice";
549 If choice is set to "yes", then another source will be able to
550 interrupt an existing play session and start a new one. When set
551 to "no" (the default), other devices attempting to interrupt a
552 session will fail, receiving a busy signal.
553 session_timeout=seconds;
555 If a play session has been established and the source disappears
556 without warning (such as a device going out of range of a net‐
557 work) then wait for seconds seconds before ending the session.
558 Once the session has terminated, other devices can use it. The
559 default is 120 seconds.
560
562 This section is about the command-line options available in shairport-
563 sync.
564 Note: if you are setting up shairport-sync for the first time or are
566 updating an existing installation, you are encouraged to use the con‐
567 figuration file settings described above. Most of the command-line
568 options described below simply replicate the configuration settings and
569 are retained to provide backward compatibility with older installations
570 of shairport-sync.
571 Many command-line options take sensible default values, so you can nor‐
573 mally ignore most of them. See the EXAMPLES section for typical usages.
574 There are two kinds of command-line options for shairport-sync: regular
576 program options and audio backend options. Program options are always
577 listed first, followed by any audio backend options, preceded by a --
578 symbol.
579
581 These command-line options are used by shairport-sync itself.
582 -a service name | --name=service name
584 Use this service name to identify this player in iTunes, etc.
585 The following substitutions are allowed: %h for the computer's
587 hostname, %H for the computer's hostname with the first letter
588 capitalised (ASCII only), %v for the shairport-sync version num‐
589 ber, e.g. "3.0.1" and %V for the shairport-sync version string,
590 e.g. "3.0.1-OpenSSL-Avahi-ALSA-soxr-metadata-sysconfdir:/etc".
591 The default is "%H", which is replaced by the hostname with the
593 first letter capitalised.
594 -B program | --on-start=program
596 Execute program when playback is about to begin. Specify the
597 full path to the program, e.g. /usr/bin/logger. Executable
598 scripts can be used, but they must have the appropriate shebang
599 (#!/bin/sh in the headline.
600 If you want shairport-sync to wait until the command has com‐
602 pleted before starting to play, select the -w option as well.
603 -c filename | --configfile=filename
605 Read configuration settings from filename. The default is to
606 read them from the shairport-sync.conf in the System Configura‐
607 tion Directory -- /etc in Linux, /usr/local/etc in BSD unixes.
608 For information about configuration settings, see the "Configu‐
609 ration File Settings" section above.
610 -D | --disconnectFromOutput
612 Disconnect the shairport-sync daemon from the output device and
613 exit. (Requires that the daemon has written its PID to an agreed
614 file -- see the -d option).
615 Please note that this feature is deprecated and will be removed
617 in a future version of shairport-sync.
618 -d | --daemon
620 Instruct shairport-sync to demonise itself. It will write its
621 Process ID (PID) to a file, usually at /var/run/shairport-
622 sync/shairport-sync.pid, which is used by the -k, -D and -R
623 options to locate the daemon at a later time. See also the -j
624 option.
625 -E program | --on-stop=program
627 Execute program when playback has ended. Specify the full path
628 to the program, e.g. /usr/bin/logger. Executable scripts can be
629 used, but they must have the appropriate shebang (#!/bin/sh in
630 the headline.
631 If you want shairport-sync to wait until the command has com‐
633 pleted before continuing, select the -w option as well.
634 --get-coverart
636 This option requires the --meta-dir option to be set, and
637 enables shairport-sync to request cover art from the source and
638 to transmit it through the metadata pipe.
639 Please note that cover art data may be very large, and may place
641 too great a burden on your network.
642 -h | --help
644 Print brief help message and exit.
645 -j Instruct shairport-sync to demonise itself. Unlike the -d
647 option, it will not write a Process ID (PID) to a file -- it
648 will just (hence the "j") demonise itself.
649 -k | --kill
651 Kill the shairport-sync daemon and exit. (Requires that the dae‐
652 mon has written its PID to an agreed file -- see the -d option).
653 --logOutputLevel
655 Use this to log the volume level when the volume is changed. It
656 may be useful if you are trying to determine a suitable value
657 for the maximum volume level. Not available as a configuration
658 file setting.
659 -L | --latency=latency
661 Use this to set the default latency, in frames, for audio coming
662 from an unidentified source or from an iTunes Version 9 or ear‐
663 lier source. The standard value for the default latency is
664 88,200 frames, where there are 44,100 frames to the second.
665 Please note that this feature is deprecated and will be removed
667 in a future version of shairport-sync.
668 --meta-dir=directory
670 Listen for metadata coming from the source and send it, along
671 with metadata from shairport-sync itself, to a pipe called
672 shairport-sync-metadata in the directory you specify. If you add
673 the --get-cover-art then cover art will be sent through the pipe
674 too. See https://github.com/mikebrady/shairport-sync-metadata-
675 reader for a sample metadata reader.
676 -m mdnsbackend | --mdns=mdnsbackend
678 Force the use of the specified mDNS backend to advertise the
679 player on the network. The default is to try all mDNS backends
680 until one works.
681 -o outputbackend | --output=outputbackend
683 Force the use of the specified output backend to play the audio.
684 The default is to try the first one.
685 -p port | --port=port
687 Listen for play requests on port. The default is to use port
688 5000.
689 --password=secret
691 Require the password secret to be able to connect and stream to
692 the service.
693 -R | --reconnectToOutput
695 Reconnect the shairport-sync daemon to the output device and
696 exit. It may take a few seconds to synchronise. (Requires that
697 the daemon has written its PID to an agreed file -- see the -d
698 option).
699 Please note that this feature is deprecated and will be removed
701 in a future version of shairport-sync.
702 -r threshold | --resync=threshold
704 Resynchronise if timings differ by more than threshold frames.
705 If the output timing differs from the source timing by more than
706 the threshold, output will be muted and a full resynchronisation
707 will occur. The default threshold is 2,205 frames, i.e. 50 mil‐
708 liseconds. Specify 0 to disable resynchronisation. This setting
709 is deprecated and will be removed in a future version of shair‐
710 port-sync.
711 --statistics
713 Print some statistics in the standard output, or in the logfile
714 if in daemon mode.
715 -S mode | --stuffing=mode
717 Stuff the audio stream using the mode. "Stuffing" refers to the
718 process of adding or removing frames of audio to or from the
719 stream sent to the output device to keep it exactly in synchrony
720 with the player. The default mode, basic, is normally almost
721 completely inaudible. The alternative mode, soxr, is even less
722 obtrusive but requires much more processing power. For this
723 mode, support for libsoxr, the SoX Resampler Library, must be
724 selected when shairport-sync is compiled.
725 -t timeout | --timeout=timeout
727 Exit play mode if the stream disappears for more than timeout
728 seconds.
729 When shairport-sync plays an audio stream, it starts a play ses‐
731 sion and will return a busy signal to any other sources that
732 attempt to use it. If the audio stream disappears for longer
733 than timeout seconds, the play session will be terminated. If
734 you specify a timeout time of 0, shairport-sync will never sig‐
735 nal that it is busy and will not prevent other sources from
736 "barging in" on an existing play session. The default value is
737 120 seconds.
738 --tolerance=frames
740 Allow playback to be up to frames out of exact synchronization
741 before attempting to correct it. The default is 88 frames, i.e.
742 2 ms. The smaller the tolerance, the more likely it is that
743 overcorrection will occur. Overcorrection is when more correc‐
744 tions (insertions and deletions) are made than are strictly nec‐
745 essary to keep the stream in sync. Use the --statistics option
746 to monitor correction levels. Corrections should not greatly
747 exceed net corrections. This setting is deprecated and will be
748 removed in a future version of shairport-sync.
749 -V | --version
751 Print version information and exit.
752 -v | --verbose
754 Print debug information. Repeat up to three times to get more
755 detail.
756 -w | --wait-cmd
758 Wait for commands specified using -B or -E to complete before
759 continuing execution.
760
762 These command-line options are passed to the chosen audio backend. The
763 audio backend options are preceded by a -- symbol to introduce them and
764 to separate them from any program options. In this way, option letters
765 can be used as program options and also as audio backend options with‐
766 out ambiguity.
767 In the ALSA backend, audio is sent to an output device which you can
769 specify using the -d option. The output level (the "volume") is con‐
770 trolled using a level control associated with a mixer. By default, the
771 mixer is implemented in shairport-sync itself in software. To use a
772 hardware level control on a mixer on the sound card, specify the name
773 of the mixer control with the -c option. If the mixer is not associated
774 with the output device, then you need to specify where the mixer is to
775 be found with the -m option.
776 -c controlname
778 Use the level control called controlname on the hardware mixer
779 for controlling volume. This is needed if the mixer type is
780 specified, using the -t option, to be hardware. There is no
781 default.
782 -d device
784 Use the specified output device. You may specify a card, e.g.
785 hw:0, in which case the default output device on the card will
786 be chosen. Alternatively, you can specify a specific device on a
787 card, e.g. hw:0,0. The default is the device named default.
788 -m mixer
790 Use the specified hardware mixer for volume control. Use this to
791 specify where the mixer is to be found. For example, if the
792 mixer is associated with a card, as is often the case, specify
793 the card, e.g. hw:0. If (unusually) the mixer is associated with
794 a specific device on a card, specify the device, e.g. hw:0,1.
795 The default is the device named in the -d option, if given, or
796 the device named default.
797 -t devicetype
799 This option is deprecated and is ignored. For your information,
800 its functionality has been automatically incorporated in the -c
801 option -- if you specify a mixer name with the -c option, it is
802 assumed that the mixer is implemented in hardware.
803
805 Here is a slightly contrived example:
806 shairport-sync -d -a "Joe's Stereo" -S soxr -- -d hw:1,0 -m hw:1 -c PCM
808 The program will run in daemon mode ( -d ), will be visible as "Joe's
810 Stereo" ( -a "Joe's Stereo" ) and will use the SoX Resampler Library-
811 based stuffing ( -S soxr ). The audio backend options following the --
812 separator specify that the audio will be output on output 0 of sound‐
813 card 1 ( -d hw:1,0 ) and will take advantage of the same sound card's
814 mixer ( -m hw:1 ) using the level control named "PCM" ( -c "PCM" ).
815 The example above is slightly contrived in order to show the use of the
817 -m option. Typically, output 0 is the default output of a card, so the
818 output device could be written -d hw:1 and then the mixer option would
819 be unnecessary, giving the following, simpler, command:
820 shairport-sync -d -a "Joe's Stereo" -S soxr -- -d hw:1 -c PCM
822
824 Mike Brady developed shairport-sync from the original Shairport by
825 James Laird.
826 shairport-sync can be found at https://github.com/mikebrady/shairport-
828 sync.
829 Shairport can be found at https://github.com/abrasive/shairport.
831
833 This man page was written using xml2man(1) by Oliver Kurth.
834Manuals User shairport-sync(7)