From: Mike Brady <4265913+mikebrady@users.noreply.github.com> Date: Mon, 3 Oct 2022 16:52:08 +0000 (+0100) Subject: Update Events.md X-Git-Tag: 4.1-rc1~1^2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=da6526f5609b79bad04fefdd20d1eae410402842;p=thirdparty%2Fshairport-sync.git Update Events.md --- diff --git a/ADVANCED TOPICS/Events.md b/ADVANCED TOPICS/Events.md index 9390da84..ff5c8190 100644 --- a/ADVANCED TOPICS/Events.md +++ b/ADVANCED TOPICS/Events.md @@ -1,42 +1,54 @@ -## Events -Shairport Sync can run programs when certain "events" occur. The events are: -1. Shairport Sync goes `active`, -2. Shairport Sync goes `inactive`, -3. Play starts, -4. Play stops, -5. Volume changes -6 +# 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` 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`. +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 is played and will stay 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`. +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`. - 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`. +* 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. - 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. - -**Note** Play events havbe been superceded by Active/Inactive events -- they are less "noisy" and work better in AirPlay 2 operation. + +* 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. You specify the full path name to the program to run using the `general` group setting `run_this_when_volume_changes` but you should 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. +Shairport Sync can run a program whenever the volume is set or changed. -For example, if the program you wish to execute is `usr/local/vc` and the new volume is `-24.6`, then, if you have specified `run_this_when_volume_changes` to be `usr/local/vc ` (note the extra space at then end), then Shairport Sync will execute the command `usr/local/vc -24.6`. (Without the extra space at the end, it would look like this: `usr/local/vc24.6`.) +* 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. ### 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. Theremore, it is _vital_ that you specify everything using a _full path name_. +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\""; +``` -You can specify a normal 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. And within the script, make sure all references to files are full path names also. +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.