|
| 1 | +## Shairport Sync D-Bus Interface |
| 2 | + |
| 3 | +Shairport Sync can have a D-Bus interface, which can be used to control aspects of its operation and get status information from it. |
| 4 | + |
| 5 | +To include the D-Bus interface at build time, add the `--with-dbus-interface` flag at the `./configure…` stage. When the D-Bus interface is included in Shairport Sync, its Version String will include the term `dbus`, for instance: |
| 6 | +``` |
| 7 | +$ shairport-sync -V |
| 8 | +5.0.0-1-gc956d763-AirPlay2-smi10-OpenSSL-Avahi-ALSA-soxr-metadata-dbus-sysconfdir:/etc |
| 9 | +
|
| 10 | +``` |
| 11 | +Once Shairport Sync has been built with the D-Bus interface, it must then be installed correctly to provide a Shairport Sync service either on the D-Bus `system` bus or the D Bus `session` bus. |
| 12 | +To become available as a system-wide service on the D-Bus `system` bus, it must be installed as a system service using the `# make install` step of the build process. This installs the appropriate service files and sets required permissions. |
| 13 | +Remember to enable Shairport Sync to start as a system service. You may also need to restart the entire system to allow the service to be seen. |
| 14 | + |
| 15 | +If Shairport Sync is installed as a user service, it will not be able to become a service on the D-Bus `system` bus, but it can be added to the D-Bus `session` bus. Edit the configuration file to select the `session` bus, or add the option `--dbus_default_message_bus=session` to the command line. |
| 16 | + |
| 17 | +### D-Feet |
| 18 | +On desktop Linuxes with a GUI, e.g. Ubuntu, D-Feet is a great tool for examining a D-Bus service: |
| 19 | + |
| 20 | + |
| 21 | + |
| 22 | +### Sample Test Client |
| 23 | + |
| 24 | +A simple test client, written in C, can be built when you are building Shairport Sync itself. To build it, simply add the `--with-dbus-test-client` flag at the `./configure…` stage. Along with the `shairport-sync` executable application, you'll get another executable called `shairport-sync-dbus-test-client` which you can run from the command line. |
| 25 | + |
| 26 | +After attempting to send some commands, it will listen for property changes on the D-Bus interface and report them on the console. |
| 27 | + |
| 28 | +### Command Line Examples |
| 29 | + |
| 30 | +The examples below are based on Shairport Sync running as a `system` service and use the standard CLI tool `dbus-send`: |
| 31 | +* Get `Active` Status -- `true` when Shairport Sync is playing (and for a short time later); `false` otherwise. |
| 32 | +``` |
| 33 | + $ dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Get string:org.gnome.ShairportSync string:Active |
| 34 | +``` |
| 35 | +* Get Log Verbosity |
| 36 | +``` |
| 37 | + $ dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Get string:org.gnome.ShairportSync.Diagnostics string:Verbosity |
| 38 | +``` |
| 39 | +* Return Log Verbosity |
| 40 | +``` |
| 41 | + $ echo `dbus-send --print-reply=literal --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Get string:org.gnome.ShairportSync.Diagnostics string:Verbosity` |
| 42 | +``` |
| 43 | +* Set Log Verbosity to 2 |
| 44 | +``` |
| 45 | + $ dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Set string:org.gnome.ShairportSync.Diagnostics string:Verbosity variant:int32:2 |
| 46 | +``` |
| 47 | +* Get Statistics-Requested Status |
| 48 | +``` |
| 49 | + $ dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Get string:org.gnome.ShairportSync.Diagnostics string:Statistics |
| 50 | +``` |
| 51 | +* Set Statistics-Requested Status to `true` |
| 52 | +``` |
| 53 | + $ dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Set string:org.gnome.ShairportSync.Diagnostics string:Statistics variant:boolean:true |
| 54 | +``` |
| 55 | +* Are File Name and Line Number included in Log Entries? |
| 56 | +``` |
| 57 | + $ dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Get string:org.gnome.ShairportSync.Diagnostics string:FileAndLine |
| 58 | +``` |
| 59 | +* Include File Name and Line Number in Log Entries |
| 60 | +``` |
| 61 | + $ dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Set string:org.gnome.ShairportSync.Diagnostics string:FileAndLine variant:boolean:true |
| 62 | +``` |
| 63 | +* Is Elapsed Time included in Log Entries? |
| 64 | +``` |
| 65 | + $ dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Get string:org.gnome.ShairportSync.Diagnostics string:ElapsedTime |
| 66 | +``` |
| 67 | +* Include Elapsed Time in Log Entries |
| 68 | +``` |
| 69 | + $ dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Set string:org.gnome.ShairportSync.Diagnostics string:ElapsedTime variant:boolean:true |
| 70 | +``` |
| 71 | +* Get Drift Tolerance |
| 72 | +``` |
| 73 | + $ dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Get string:org.gnome.ShairportSync string:DriftTolerance |
| 74 | +``` |
| 75 | +* Set Drift Tolerance to 1 millisecond |
| 76 | +``` |
| 77 | + $ dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Set string:org.gnome.ShairportSync string:DriftTolerance variant:double:0.001 |
| 78 | +``` |
| 79 | +* Is Loudness enabled: |
| 80 | +``` |
| 81 | + $ dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Get string:org.gnome.ShairportSync string:LoudnessEnabled |
| 82 | +``` |
| 83 | +* Enable Loudness Filter |
| 84 | +``` |
| 85 | + $ dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Set string:org.gnome.ShairportSync string:LoudnessEnabled variant:boolean:true |
| 86 | +``` |
| 87 | +* Get Loudness Threshold |
| 88 | +``` |
| 89 | + $ dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Get string:org.gnome.ShairportSync string:LoudnessThreshold |
| 90 | +``` |
| 91 | +* Set Loudness Threshold |
| 92 | +``` |
| 93 | + $ dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Set string:org.gnome.ShairportSync string:LoudnessThreshold variant:double:-15.0 |
| 94 | +``` |
| 95 | +* Is Convolution enabled: |
| 96 | +``` |
| 97 | + $ dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Get string:org.gnome.ShairportSync string:ConvolutionEnabled |
| 98 | +``` |
| 99 | +* Enable Convolution |
| 100 | +``` |
| 101 | + $ dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Set string:org.gnome.ShairportSync string:ConvolutionEnabled variant:boolean:true |
| 102 | +``` |
| 103 | +* Get Convolution Gain: |
| 104 | +``` |
| 105 | + $ dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Get string:org.gnome.ShairportSync string:ConvolutionGain |
| 106 | +``` |
| 107 | +* Set Convolution Gain -- the gain applied after convolution is applied -- to -10.0 dB |
| 108 | +``` |
| 109 | + $ dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Set string:org.gnome.ShairportSync string:ConvolutionGain variant:double:-10 |
| 110 | +``` |
| 111 | +* Get Convolution Impulse Response Files: |
| 112 | +``` |
| 113 | + $ dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Get string:org.gnome.ShairportSync string:ConvolutionImpulseResponseFiles |
| 114 | +``` |
| 115 | +* Set Convolution Impulse Response Files: |
| 116 | +``` |
| 117 | + $ dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Set string:org.gnome.ShairportSync string:ConvolutionImpulseResponseFiles variant:string:"'/home/pi/filters/Sennheiser HD 205 minimum phase 48000Hz.wav', '/home/pi/filters/Sennheiser HD 205 minimum phase 44100Hz.wav'" |
| 118 | +``` |
| 119 | +* Get Convolution Impulse Response File Maximum Length: |
| 120 | +``` |
| 121 | + $ dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Get string:org.gnome.ShairportSync string:ConvolutionMaximumLengthInSeconds |
| 122 | +``` |
| 123 | +* Set Convolution Impulse Response File Maximum Length: |
| 124 | +``` |
| 125 | + $ dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Set string:org.gnome.ShairportSync string:ConvolutionMaximumLengthInSeconds variant:double:1 |
| 126 | +``` |
| 127 | +* Get the Protocol that Shairport Sync was built for -- AirPlay or AirPlay 2: |
| 128 | +``` |
| 129 | + $ dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Get string:org.gnome.ShairportSync string:Protocol |
| 130 | +``` |
| 131 | +* Get the current volume level. This returns a value between -30.0 and 0.0, which is linear on the UI volume control. It can also return -144.0 to indicate mute. |
| 132 | +``` |
| 133 | + $ dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Get string:org.gnome.ShairportSync string:Volume |
| 134 | +``` |
| 135 | +* Set the current volume level. This should be a value between -30.0 and 0.0. Set a value of -144.0 to mute. Note that all this is done locally on the Shairport Sync device itself. The volume control of audio source (e.g. iTunes / macOS Music / iOS) is not updated to reflect any changes. |
| 136 | +``` |
| 137 | + $ dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Set string:org.gnome.ShairportSync string:Volume variant:double:-10.0 |
| 138 | +``` |
| 139 | +* Drop the current session immediately. Shairport Sync will immediately stop playing and drop the connection from the audio source. This may show up as an error at the source. |
| 140 | +``` |
| 141 | + $ dbus-send --system --print-reply --type=method_call --dest=org.gnome.ShairportSync '/org/gnome/ShairportSync' org.gnome.ShairportSync.DropSession |
| 142 | +``` |
| 143 | +#### Remote Control |
| 144 | +Remote Control commands are sent as requests to the player (iOS, iTunes, macOS Music, etc.). Different versions of the players implement different subsets of the following commands. |
| 145 | + |
| 146 | +**Note:** Unfortunately, at this time -- early 2026 -- these requests are ignored, so remote control doesn't work. |
| 147 | + |
| 148 | +* Check if Remote Control is available: |
| 149 | +``` |
| 150 | + $ dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Get string:org.gnome.ShairportSync.RemoteControl string:Available |
| 151 | +``` |
| 152 | +* Send the `play` command to the player: |
| 153 | +``` |
| 154 | + $ dbus-send --system --print-reply --type=method_call --dest=org.gnome.ShairportSync '/org/gnome/ShairportSync' org.gnome.ShairportSync.RemoteControl.Play |
| 155 | +``` |
| 156 | + Remote Control commands include: `Play`, `Pause`, `PlayPause`, `Resume`, `Stop`, `Next`, `Previous`, `VolumeUp`, `VolumeDown`, `ToggleMute`, `FastForward`, `Rewind`, `ShuffleSongs`. |
| 157 | + |
| 158 | +* Set Airplay Volume using Remote Control. Airplay Volume is between -30.0 and 0.0 and maps linearly onto the slider, with -30.0 being lowest and 0.0 being highest. |
| 159 | +``` |
| 160 | + $ dbus-send --system --print-reply --type=method_call --dest=org.gnome.ShairportSync '/org/gnome/ShairportSync' org.gnome.ShairportSync.RemoteControl.SetAirplayVolume double:-10.0 |
| 161 | +``` |
| 162 | +#### Advanced Remote Control |
| 163 | +Some commands and properties are accessible only through the `AdvancedRemoteControl` interface. |
| 164 | + |
| 165 | +**Note:** Unfortunately, at this time -- early 2026 -- these requests are ignored, so advanced remote control doesn't work. |
| 166 | + |
| 167 | +* Check if Advanced Remote Control is available: |
| 168 | +``` |
| 169 | + $ dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Get string:org.gnome.ShairportSync.AdvancedRemoteControl string:Available |
| 170 | +``` |
| 171 | +* Set Volume using Advanced Remote Control: |
| 172 | +``` |
| 173 | + $ dbus-send --system --print-reply --type=method_call --dest=org.gnome.ShairportSync '/org/gnome/ShairportSync' org.gnome.ShairportSync.AdvancedRemoteControl.SetVolume int32:50 |
| 174 | +``` |
0 commit comments