From: Mike Brady <4265913+mikebrady@users.noreply.github.com> Date: Wed, 5 Oct 2022 09:08:16 +0000 (+0100) Subject: Update from master branch. X-Git-Tag: 4.1-rc2~1^2~17 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=90402c6002adb86137e676a6451995a357fac5a4;p=thirdparty%2Fshairport-sync.git Update from master branch. --- diff --git a/ADVANCED TOPICS/Events.md b/ADVANCED TOPICS/Events.md index 26a777de..ff5c8190 100644 --- a/ADVANCED TOPICS/Events.md +++ b/ADVANCED TOPICS/Events.md @@ -1,18 +1,54 @@ -## Events -Shairport Sync can run programs when certain "events" occur. The events are: -1. When Shairport Sync become `active` or `inactive`. Shairport Sync is normally in the `inactive` state when no audio is being played. When audio is sent to Shairport Sync, it will transition from `inactive` to `active`. When the audio stops, Shairport Sync will start a timer. If audio restarts before the timer reaches the value of the `active_state_timeout` configuration setting (10 seconds by default), Shairport Sync will stay `active`. However, if no more audio is received before the timer reaches the `active_state_timeout` value, Shairport Sync will transition to `inactive`. The overall effect of this is that Shairport Sync will go `active` when a track is played and will stay active in the interval between tracks, so long as the interval is less than the `active_state_timeout`. - 1. Set the `run_this_before_entering_active_state` setting to the full path name to the program to run before Shairport Sync goes `active`. - 2. Set the `run_this_after_exiting_active_state` setting to the full path name to the program to run after Shairport Sync goes `inactive`. - 3. Set the `active_state_timeout` setting to the maximum amount of time to wait for play to resume before going `inactive`. -3. When audio starts and stops playing. - 1. Set the `run_this_before_play_begins` setting to the full path name to the program to run just before Shairport Sync starts playing. - 2. Set the `run_this_after_play_ends` setting to the full path name to the program to run after Shairport Sync stops playing. -5. When the volume is adjusted. Shairport Sync can run a program whenever the volume is set or changed. You specify the full path name to the program to run using the `general` group setting `run_this_when_volume_changes`. +# Events +Shairport Sync can run programs when certain _events_ occur. The events are: +1. When Shairport Sync goes _active_ or _inactive,_ +3. When audio play starts or stops, +5. When the volume is set or changed. + + +### Active / Inactive Events +Shairport Sync is normally in the `inactive` state when no audio is being played. + +When audio is sent to Shairport Sync, it will transition from `inactive` to `active`. + +When the audio stops, Shairport Sync will start a timer. If audio restarts before the timer reaches the value of the `active_state_timeout` setting (10 seconds by default), Shairport Sync will stay `active`. However, if no more audio is received before the timer reaches the `active_state_timeout` value, Shairport Sync will transition to `inactive`. + +The overall effect of this is that Shairport Sync will go `active` when a track starts and stays active in the interval between tracks, so long as the interval is less than the `active_state_timeout`. When the sequence of tracks ends, Shairport Sync will go `inactive`. + +* Set the `run_this_before_entering_active_state` setting to the full path name to the program to run before Shairport Sync goes `active`. +* Set the `run_this_after_exiting_active_state` setting to the full path name to the program to run after Shairport Sync goes `inactive`. +* Set the `active_state_timeout` setting to the maximum amount of time to wait for play to resume before going `inactive`. + +### Play Start / Play Stop +**Note:** Play events have been superceded by Active/Inactive events, which works better in AirPlay 2 operation. + +When audio starts, the `play begins` event occurs. When it stops, the `play ends` event occurs. + +* Set the `run_this_before_play_begins` setting to the full path name to the program to run just before Shairport Sync starts playing. +* Set the `run_this_after_play_ends` setting to the full path name to the program to run after Shairport Sync stops playing. + +### Volume Adjustment +Shairport Sync can run a program whenever the volume is set or changed. + +* Set `run_this_when_volume_changes` to the full path name to the program to run using the `general` group setting `run_this_when_volume_changes` _but also_ add a space character to the end of the name. This is because when a volume event occurs, Shairport Sync will append the new volume to the text you have specified in `run_this_when_volume_changes` and will then try to execute it. + +For example, to use the `echo` command to log the volume setting, let's say that you have found that the full path name for `echo` is `/usr/bin/echo`, then you would specify `run_this_when_volume_is_set` as follows: +``` +run_this_when_volume_is_set = "/usr/bin/echo "; +``` +(Note the extra space at the end of the path name.) Suppose the volume is set or changed to `-24.6`, then Shairport Sync will execute the command `/usr/bin/echo -24.6`. (Without that extra space, it would try to execute `/usr/bin/echo24.6`.) + +### Waiting for Completion Set the `wait_for_completion` value to `"yes"` for Shairport Sync to wait until the respective commands have been completed before continuing. -Note that the full path to the programs must be specified, and script files will not be executed unless they are marked as executable -and have the appropriate shebang `#!/bin/...` as the first line. (This behaviour may be different from other Shairports.) +### Program +The environment in which the program you specify will be very different to a login environment. In particular, the `PATH` variable will be different. This means that you can't assume that the system will look in the right directories for programs or documents. Therefore, it is _vital_ that you specify everything using a _full path name_. + +For example, to get the `logger` command to log `Active Start` when Shairport Sync goes active, set `run_this_before_entering_active_state` as follows: + +``` +run_this_before_entering_active_state = "/usr/bin/logger \"Active Start\""; +``` -Shairport Sync can run a program whenever the volume is set or changed. You specify it using the `general` group setting `run_this_when_volume_changes`. -This is to facilitate situations where something has to be done when the volume changes, e.g. adjust an external mixer value. Set the `wait_for_completion` value to `"yes"` for Shairport Sync to wait until the command has been completed before continuing. Again, please note that the full path to the program must be specified, and script files will not be executed unless they are marked as executable and have the appropriate shebang `#!/bin/...` as the first line. +You can specify a program to be executed or you can specify a script. Make sure the script file is marked as executable +and has the appropriate shebang `#!/bin/...` as the first line. Within the script, make sure all references to files are full path names.