diff --git a/CAR INSTALL.md b/CAR INSTALL.md index 879015ade..062b6df52 100644 --- a/CAR INSTALL.md +++ b/CAR INSTALL.md @@ -19,7 +19,7 @@ In this example, a Raspberry Pi Zero W and a Pimoroni PHAT DAC are used. This co ### Prepare the initial SD Image * Download the latest version of Raspbian Lite -- Stretch Lite of 2018-03-13 at the time of writing -- and install it onto an SD Card. * Mount the card on a Linux machine. Two drives should appear -- a `boot` drive and a `rootfs` drive. Both of these need a little modification. -* Enable SSH service by creating a file called `ssh` on the `boot` drive. To do this, mount the drive and CD to its `boot` partiton (since my username is `mike`, the drive is at `/media/mike/boot`): +* Enable SSH service by creating a file called `ssh` on the `boot` drive. To do this, mount the drive and CD to its `boot` partition (since my username is `mike`, the drive is at `/media/mike/boot`): ``` $ touch ssh ``` diff --git a/INSTALL.md b/INSTALL.md index 8d8dc7dfa..a5a61991a 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -2,7 +2,7 @@ Simple Installation Instructions == Here are simple instructions for building and installing Shairport Sync on a Raspberry Pi B, 2B, 3B or 3B+. It is assumed that the Pi is running Raspbian Stretch Lite – a GUI isn't needed, since Shairport Sync runs as a daemon program. For a more thorough treatment, please go to the [README.md](https://github.com/mikebrady/shairport-sync/blob/master/README.md#building-and-installing) page. -In the commands below, note the convention that a `#` prompt means you are in superuser mode and a `$` prompt means you are in a regular non-priviliged user mode. You can use `sudo` *("SUperuser DO")* to temporarily promote yourself from user to superuser, if permitted. For example, if you want to execute `apt-get update` in superuser mode and you are in user mode, enter `sudo apt-get update`. +In the commands below, note the convention that a `#` prompt means you are in superuser mode and a `$` prompt means you are in a regular unprivileged user mode. You can use `sudo` *("SUperuser DO")* to temporarily promote yourself from user to superuser, if permitted. For example, if you want to execute `apt-get update` in superuser mode and you are in user mode, enter `sudo apt-get update`. ### Configure and Update Do the usual update and upgrade: diff --git a/README-DEVELOPMENT.md b/README-DEVELOPMENT.md index 233676095..8193f84e4 100644 --- a/README-DEVELOPMENT.md +++ b/README-DEVELOPMENT.md @@ -81,7 +81,7 @@ Please refer to the relevant pages for building for the above systems. **Determine The Configuration Needed** -Shairport Sync has a number of different "backends" that connnect it to the system's audio handling infrastructure. Most recent Linux distributions that have a GUI – including Ubuntu, Debian and others – use PulseAudio to handle sound. In such cases, it is inadvisable to attempt to disable or remove PulseAudio. Thus, if your system uses PulseAudio, you should build Shairport Sync with the PulseAudio backend. You can check to see if PulseAudio is running by opening a Terminal window and entering the command `$ pactl info`. Here is an example of what you'll get if PulseAudio is installed, though the exact details may vary: +Shairport Sync has a number of different "backends" that connect it to the system's audio handling infrastructure. Most recent Linux distributions that have a GUI – including Ubuntu, Debian and others – use PulseAudio to handle sound. In such cases, it is inadvisable to attempt to disable or remove PulseAudio. Thus, if your system uses PulseAudio, you should build Shairport Sync with the PulseAudio backend. You can check to see if PulseAudio is running by opening a Terminal window and entering the command `$ pactl info`. Here is an example of what you'll get if PulseAudio is installed, though the exact details may vary: ``` $ pactl info Server String: unix:/run/user/1000/pulse/native diff --git a/README.md b/README.md index 5a7acbe7d..d9976d820 100644 --- a/README.md +++ b/README.md @@ -97,7 +97,7 @@ You should also remove the initialisation script files `/etc/systemd/system/shai **Determine The Configuration Needed** -Shairport Sync has a number of different "backends" that connnect it to the system's audio handling infrastructure. Most recent Linux distributions that have a GUI – including Ubuntu, Debian and others – use PulseAudio to handle sound. In such cases, it is inadvisable to attempt to disable or remove PulseAudio. Thus, if your system uses PulseAudio, you should build Shairport Sync with the PulseAudio backend. You can check to see if PulseAudio is running by opening a Terminal window and entering the command `$ pactl info`. Here is an example of what you'll get if PulseAudio is installed, though the exact details may vary: +Shairport Sync has a number of different "backends" that connect it to the system's audio handling infrastructure. Most recent Linux distributions that have a GUI – including Ubuntu, Debian and others – use PulseAudio to handle sound. In such cases, it is inadvisable to attempt to disable or remove PulseAudio. Thus, if your system uses PulseAudio, you should build Shairport Sync with the PulseAudio backend. You can check to see if PulseAudio is running by opening a Terminal window and entering the command `$ pactl info`. Here is an example of what you'll get if PulseAudio is installed, though the exact details may vary: ``` $ pactl info Server String: unix:/run/user/1000/pulse/native @@ -609,7 +609,7 @@ This will be followed by the statistics themselves at regular intervals, for exa "Output frames per second" is the actual rate at which frames of audio are taken by the output device. On a system with a well-conditioned `ntp`-based clock (and without output underruns) this figure should be very accurate after playing material continuously for a period. -"Source clock drift in ppm" is an estimate of the difference in timekeeping between the audio source and the Shairport Sync devive. It is calculated from a linear regression of drift sample data. The number of samples the estimate is based on is given in the next column, "Source clock drift sample count". +"Source clock drift in ppm" is an estimate of the difference in timekeeping between the audio source and the Shairport Sync device. It is calculated from a linear regression of drift sample data. The number of samples the estimate is based on is given in the next column, "Source clock drift sample count". "Rough calculated correction in ppm" is a very crude estimate of the amount of interpolation that needs to applied, on average, to keep sync. It is not really to be relied on at this time. diff --git a/RELEASENOTES-DEVELOPMENT.md b/RELEASENOTES-DEVELOPMENT.md index a5fc6ce84..da976bb92 100644 --- a/RELEASENOTES-DEVELOPMENT.md +++ b/RELEASENOTES-DEVELOPMENT.md @@ -90,7 +90,7 @@ Version 3.3d56 to Version 3.3d40 **Enhancements** * Changes to the Jack Audio back end. The back end for Jack Audio, `audio_jack.c`, has been extensively rewritten by [Jörn Nettingsmeier](https://github.com/nettings) in a way that is more in keeping with the Jack Audio style. It uses native Jack Audio lockless buffers and offers autoconnect facilities that the previous version didn't have. Many thanks to him. -* The volume-control software has been completely rewritten. From a user's point of view, the result should be a much smoother response to volume contol changes, free from artefacts. It is now also possible to combine the hardware mixer and the software attenuator in two ways -- giving priority to the software mixer or giving priority to the hardware mixer. see the new `volume_range_combined_hardware_priority` setting in the `general` section opf the configuration file. +* The volume-control software has been completely rewritten. From a user's point of view, the result should be a much smoother response to volume control changes, free from artefacts. It is now also possible to combine the hardware mixer and the software attenuator in two ways -- giving priority to the software mixer or giving priority to the hardware mixer. see the new `volume_range_combined_hardware_priority` setting in the `general` section opf the configuration file. * The muting/unmuting code has been rewritten to be simpler and more consistent. * In the `alsa` backend, new `play()` and `delay()` functions minimise the use of `snd_pcm_recover()` to prevent unnecessary resets of the output DACs. * In the `alsa` backend driver, hardware isn't accessed until the first time it is needed. That is, when Shairport Sync starts up, it no longer needs to access the device momentarily. Instead, it waits for the first use. @@ -378,7 +378,7 @@ Update [TROUBLESHOOTING.md](https://github.com/mikebrady/shairport-sync/blob/dev Version 3.2d45 ==== **Enhancement** -* Restore the old method for calculating latency for older AirPlay sources: an AirPlay source displaying an AirPlay User Agent string verion of 353 or older -- corresponding to iOS 11.1.2 or older -- will add an extra 0.25 seconds to the latency requested. This seems to be right. +* Restore the old method for calculating latency for older AirPlay sources: an AirPlay source displaying an AirPlay User Agent string version of 353 or older -- corresponding to iOS 11.1.2 or older -- will add an extra 0.25 seconds to the latency requested. This seems to be right. Version 3.2d44 ==== @@ -398,7 +398,7 @@ Version 3.2d41 Version 3.2d40 ==== **Bug Fixes** -* A number of serious and long-standing bugs have been identified and fixed in the threads that handle audio, control and timing packets. Specifically, if UDP reception or transmission errors occured (a rare occurence on a good network, but possible on noisy or congested networks), the threads would quit. In this way, an error on the reception of the first control packet could mute an entire play session. +* A number of serious and long-standing bugs have been identified and fixed in the threads that handle audio, control and timing packets. Specifically, if UDP reception or transmission errors occurred (a rare occurrence on a good network, but possible on noisy or congested networks), the threads would quit. In this way, an error on the reception of the first control packet could mute an entire play session. **Enhancements** * The code used to request the retransmission of missing audio packets has been significantly improved. @@ -427,7 +427,7 @@ Version 3.2d34 * `pfls` and `prsm` messages are less frequent, especially when a play session starts. **Other Developments** -* Shairport Sync now uses about an extra half megabyte of RAM for compatability with TuneBlade's option to have a very long latency -- up to five seconds. +* Shairport Sync now uses about an extra half megabyte of RAM for compatibility with TuneBlade's option to have a very long latency -- up to five seconds. Version 3.2d33 ==== @@ -437,7 +437,7 @@ Version 3.2d30 ==== **Enhancements** * A "native" D-Bus Remote Control permits remote control of the current AirPlay or iTunes client. It includes status information about whether the remote control connection is viable or not, i.e. whether it can still be used to control the client. -A remote control connection to the audio client becomes valid when the client starts AirPlaying to Shairport Sync. The connections remains valid until the audio source deselects Shairport Sync for AirPlay, or until the client disappears, or until another client starts AirPlaying to Shairport Sync. It is likely that a time limit will be put on this, so that after, say, 30 minutes of inactivity, the remote contol connection will be dropped. +A remote control connection to the audio client becomes valid when the client starts AirPlaying to Shairport Sync. The connections remains valid until the audio source deselects Shairport Sync for AirPlay, or until the client disappears, or until another client starts AirPlaying to Shairport Sync. It is likely that a time limit will be put on this, so that after, say, 30 minutes of inactivity, the remote control connection will be dropped. Version 3.2d29 ==== @@ -577,7 +577,7 @@ Shairport Sync is more stable playing audio from YouTube and SoundCloud on the M * When you update from a previous version of Shairport Sync, your output device may have been left in a muted state. You should use a command line tool like `alsamixer` or `amixer` to unmute the output device before further use. **Change of Default** -* The default value for the `alsa` setting `mute_using_playback_switch` has been changed to `"no"` for compatability with other audio players on the same machine. The reason is that when this setting is set to `"yes"`, the output device will be muted when Shairport Sync releases it. Unfortunately, other audio players using the output device expect it to be unmuted, causing problems. Thanks to [Tim Curtis](https://github.com/moodeaudio) at [Moode Audio](http://moodeaudio.org) and [Peter Pablo](https://github.com/PeterPablo) for clarifying the issue. +* The default value for the `alsa` setting `mute_using_playback_switch` has been changed to `"no"` for compatibility with other audio players on the same machine. The reason is that when this setting is set to `"yes"`, the output device will be muted when Shairport Sync releases it. Unfortunately, other audio players using the output device expect it to be unmuted, causing problems. Thanks to [Tim Curtis](https://github.com/moodeaudio) at [Moode Audio](http://moodeaudio.org) and [Peter Pablo](https://github.com/PeterPablo) for clarifying the issue. **Bug Fixes** * Fixed bugs that made Shairport Sync drop out or become unavailable when playing YouTube videos, SoundCloud streams etc. from the Mac. Background: there has been a persistent problem with Shairport Sync becoming unavailable after playing, say, a YouTube clip in a browser on the Mac. Shairport Sync 3.1.2 incorporates a change to how certain AirPlay messages are handled. Introduced in nascent form in 3.1.1, further follow-on changes have improved the handling of player lock and have simplified and improved the handling of unexpected loss of connection. Shairport Sync also now works properly with SoundCloud clips played in a browser on the Mac. @@ -604,7 +604,7 @@ Version 3.1 brings two new backends, optional loudness and convolution filters, **Pesky Changes You Should Know About** * The `audio_backend_buffer_desired_length_in_seconds` and `audio_backend_latency_offset_in_seconds` settings have been moved from individual backend stanzas to the `general` stanza. They now have an effect on every type of backend. -* If you are using a System V (aka `systemv`) installation, please note that the default location for PID file has moved -- it is now stored at `/var/run/shairport-sync/shairport-sync.pid`. This change is needed to improve security a little and to improve compatability across platforms. If you're not doing anything strange, this should make no difference. +* If you are using a System V (aka `systemv`) installation, please note that the default location for PID file has moved -- it is now stored at `/var/run/shairport-sync/shairport-sync.pid`. This change is needed to improve security a little and to improve compatibility across platforms. If you're not doing anything strange, this should make no difference. **Enhancements** * Resynchronisation, which happens when the synchronisation is incorrect by more than 50 ms by default, should be a lot less intrusive when it occurs – it should now either insert silence or skip frames, as appropriate. @@ -707,7 +707,7 @@ Version 3.0d20 – Development Version Note: all Version 3 changes are summarized above. **Bug Fix** -* Fix a small and generally silent error in configure.ac so that it only looks for the systemd direcotry if systemd has been chosen. It caused a warning when cross-compiling. +* Fix a small and generally silent error in configure.ac so that it only looks for the systemd directory if systemd has been chosen. It caused a warning when cross-compiling. Version 3.0d19 – Development Version ---- @@ -850,7 +850,7 @@ The following is a summary of the bug fixes and enhancements since version 2.8.3 * Metadata can now be provided via UDP -- thanks to [faceless2](https://github.com/faceless2). * Statistics output is more machine readable -- thanks to [Jörg Krause](https://github.com/joerg-krause) -* The `shairport-sync.spec` file has been updated for compatability with building Debian packages using `checkinstall` -- thanks to [vru1](https://github.com/vru1). +* The `shairport-sync.spec` file has been updated for compatibility with building Debian packages using `checkinstall` -- thanks to [vru1](https://github.com/vru1). Version 2.8.3.11 – Development Version ---- @@ -971,13 +971,13 @@ For full details, please refer to the release notes here, back as far as 2.9.1. Version 2.9.2 – Development Version ---- -Version 2.9.2 focusses on further bug fixes and stability improvements. +Version 2.9.2 focuses on further bug fixes and stability improvements. * Enhanced stability: an important bug has been fixed in the handling of missing audio frames – i.e. what happens when a frame of audio is truly missing, after all attempts to fetch it have been unsuccessful. The bug would cause Shairport Sync to do an unnecessary resynchronisation, or, if resync was turned off, to jump out of sync. This is a long-standing bug – thanks to [Jörg Krause](https://github.com/joerg-krause) for identifying it. * An extra diagnostic has been added which gives the mean, standard deviation and maximum values for inter-packet reception time on the audio port. It may be useful for exploring line quality. Version 2.9.1 – Development Version ---- -Version 2.9.1 focusses on bug fixes and stability improvements. +Version 2.9.1 focuses on bug fixes and stability improvements. * Stability improvements are concentrated on what happens when a play sessions ends and is followed immediately by a new session. This happens in iOS 9.2 when you click to the next track or to the previous track. It also happens playing YouTube videos when a Mac's System Audio is routed through AirPlay. Thanks to [Tim Curtis](https://github.com/moodeaudio) for help with these issues. * A workaround for an apparent flushing issue in TuneBlade has been included. Thanks to [gibman](https://github.com/gibman) for reporting this issue. * A number of bug fixes have been made to `configure.ac` – thanks to [Jörg Krause](https://github.com/joerg-krause). @@ -1056,7 +1056,7 @@ Version 2.7.5 -- Development Version Version 2.7.4 -- Development Version ---- **Enhancements** -* Use the correct method for finding the `systemd` unit path, as recomended by debain maintainers and +* Use the correct method for finding the `systemd` unit path, as recommended by Debian maintainers and http://www.freedesktop.org/software/systemd/man/daemon.html#Installing%20Systemd%20Service%20Files. Thanks to [dantheperson](https://github.com/dantheperson). * Rather than hardwire the path `/usr/local/bin` as the path to the shairport-sync executable, the value of `$PREFIX` is now used during configuration. Thanks to [Nick Steel](https://github.com/kingosticks). * Add some extra diagnostic messages if the hardware buffer in the DAC is smaller than desired. @@ -1088,7 +1088,7 @@ Version 2.7.1 -- Development Version Version 2.7 -- Development Version ---- **New Features** -* Extend the volume range for some DACs. Background: some of the cheaper DACS have a very small volume range (that is, the ratio of the highest to the lowest volume, expressed in decibels, is very small). In some really cheap DACs it's only around 30 dB. That means that the difference betweeen the lowest and highest volume settings isn't large enough. With the new feature, if you set the `general` `volume_range_db` to more than the hardware mixer's range, Shairport Sync will combine the hardware mixer's range with a software attenuator to give the desired range. For example, suppose you want a volume range of 70 dB and the hardware mixer offers only 30 dB, then Shairport Sync will make up the other 40 dB with a software attenuator. One drawback is that, when the volume is being changed, there may be a slight delay (0.15 seconds by default) as the audio, whose volume may have been adjusted in software, propagates through the system. Another slight possible drawback is a slightly heavier load on the processor. +* Extend the volume range for some DACs. Background: some of the cheaper DACS have a very small volume range (that is, the ratio of the highest to the lowest volume, expressed in decibels, is very small). In some really cheap DACs it's only around 30 dB. That means that the difference between the lowest and highest volume settings isn't large enough. With the new feature, if you set the `general` `volume_range_db` to more than the hardware mixer's range, Shairport Sync will combine the hardware mixer's range with a software attenuator to give the desired range. For example, suppose you want a volume range of 70 dB and the hardware mixer offers only 30 dB, then Shairport Sync will make up the other 40 dB with a software attenuator. One drawback is that, when the volume is being changed, there may be a slight delay (0.15 seconds by default) as the audio, whose volume may have been adjusted in software, propagates through the system. Another slight possible drawback is a slightly heavier load on the processor. * Check for underflow a little better when buffer aliasing occurs on very bad connections... * Add extra debug messages to the alsa back end to diagnose strange DACs. * Add configuration file for the `libao` back end -- to change the buffer size and the latency offset, same as for stdout. @@ -1110,7 +1110,7 @@ This is basically version 2.4.2 with two small fixes. It's been bumped to 2.6 be Version 2.4.2 ---- -This release has important enhancements, bug fixes and documentation updates. It also appears to bring compatiblity with Synology NAS devices. +This release has important enhancements, bug fixes and documentation updates. It also appears to bring compatibility with Synology NAS devices. **New Features** @@ -1129,7 +1129,7 @@ Using source-specified latencies is now automatic unless non-standard static lat * Volume ratios expressed in decibels are now consistently denominated in voltage decibels rather than power decibels. The rationale is that the levels refer to voltage levels, and power is proportional to the square of voltage. Thus a ratio of levels of 65535 to 1 is 96.3 dB rather than the 48.15 dB used before. * The latency figure returned to the source as part of the response to an rtsp request packet is 11,025, which may (?) be meant to indicate the minimum latency the device is capable of. -* An experimental handler for a GET_PARAMETER rtsp request has been added. It does nothing except log the occurence. +* An experimental handler for a GET_PARAMETER rtsp request has been added. It does nothing except log the occurrence. * The RTSP request dispatcher now logs an event whenever an unrecognised rtsp has been made. @@ -1141,8 +1141,8 @@ This release has three small bug fixes and some small documentation updates. Changes from the previous stable version -- 2.4 -- are summarised here: * The USE_CUSTOM_LOCAL_STATE_DIR macro was still being used when it should have been USE_CUSTOM_PID_DIR. This could affect users using a custom location for the PID directory. - * A compiler error has been fixed that occured if metadata was enabled and tinysvcmdns was included. - * A crash has been fixed that occured if metadata was enabled and a metadata pipename was not specified. + * A compiler error has been fixed that occurred if metadata was enabled and tinysvcmdns was included. + * A crash has been fixed that occurred if metadata was enabled and a metadata pipe name was not specified. (Thanks to the contributors who reported bugs.) **Small Changes** @@ -1189,7 +1189,7 @@ Version 2.3.12 **Enhancements** -* Larger range of interpolation. Shairport Sync was previously constrained not to make interpolations ("corrections") of more than about 1 per 1000 frames. This contraint has been relaxed, and it is now able to make corrections of up to 1 in 352 frames. This might result in a faster and undesirably sudden correction early during a play session, so a number of further changes have been made. The full set of these changes is as follows: +* Larger range of interpolation. Shairport Sync was previously constrained not to make interpolations ("corrections") of more than about 1 per 1000 frames. This constraint has been relaxed, and it is now able to make corrections of up to 1 in 352 frames. This might result in a faster and undesirably sudden correction early during a play session, so a number of further changes have been made. The full set of these changes is as follows: * No corrections happen for the first five seconds. * Corrections of up to about 1 in 1000 for the next 25 seconds. * Corrections of up to 1 in 352 thereafter. @@ -1208,7 +1208,7 @@ Bug fix * The "pipe" backend used output code that would block if the pipe didn't have a reader. This has been replaced by non-blocking code. Here are some implications: * When the pipe is created, Shairport Sync will not block if a reader isn't present. * If the pipe doesn't have a reader when Shairport Sync wants to output to it, the output will be discarded. - * If a reader disappears while writing is occuring, the write will time out after five seconds. + * If a reader disappears while writing is occurring, the write will time out after five seconds. * Shairport Sync will only close the pipe on termination. Version 2.3.9 @@ -1285,7 +1285,7 @@ Version 2.3.1 Some big changes "under the hood" have been made, leading to limited support for unsynchronised output to `stdout` or to a named pipe and continuation of defacto support for unsynchronised PulseAudio. Also, support for a configuration file in preference to command line options, an option to ignore volume control and other improvements are provided. In this release, Shairport Sync gains the ability to read settings from `/etc/shairport-sync.conf`. -This gives more flexibility in adding features gives better compatability across different versions of Linux. +This gives more flexibility in adding features gives better compatibility across different versions of Linux. Existing command-line options continue to work, but some will be deprecated and may disappear in a future version of Shairport Sync. New settings will only be available via the configuration file. Note that, for the present, settings in the configuration will have priority over command line options for Shairport Sync itself, in contravention of the normal unix convention. Audio back end command line options, i.e. those after the `--`, have priority over configuration file settings for the audio backends. @@ -1363,7 +1363,7 @@ Version 2.2 ----- * Enhancements: * New password option: `--password=SECRET` - * New tolerance option: `--tolerance=FRAMES`. Use this option to specify the largest synchronisation error to allow before making corrections. The default is 88 frames, i.e. 2 milliseconds. The default tolerance is fine for streaming over wired ethernet; however, if some of the stream's path is via WiFi, or if the source is a third-party product, it may lead to much overcorrection -- i.e. the difference between "corrections" and "net correction" in the `--statistics` option. Increasing the tolerence may reduce the amount of overcorrection. + * New tolerance option: `--tolerance=FRAMES`. Use this option to specify the largest synchronisation error to allow before making corrections. The default is 88 frames, i.e. 2 milliseconds. The default tolerance is fine for streaming over wired ethernet; however, if some of the stream's path is via WiFi, or if the source is a third-party product, it may lead to much overcorrection -- i.e. the difference between "corrections" and "net correction" in the `--statistics` option. Increasing the tolerance may reduce the amount of overcorrection. Version 2.1.15 ----- @@ -1418,7 +1418,7 @@ With this feature, you can allow Shairport Sync always to advertise and provide * Annoying things you should know about if you're updating from a previous version: * Options `--with-openssl`, `--with-polarssl` have been replaced with a new option `--with-ssl=