Create D-Bus.md [skip ci]
This commit is contained in:
Mike Brady
@@ -0,0 +1,169 @@
|
||||
## Shairport Sync D-Bus Interface
|
||||
|
||||
Shairport Sync can have a D-Bus interface, which can be used to control aspects of its operation and get status information from it.
|
||||
|
||||
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:
|
||||
```
|
||||
$ shairport-sync -V
|
||||
5.0.0-1-gc956d763-AirPlay2-smi10-OpenSSL-Avahi-ALSA-soxr-metadata-dbus-sysconfdir:/etc
|
||||
|
||||
```
|
||||
Once Shairport Sync has been built with the D-Bus interface, it must then be installed correctly to provide a Shairport Sync service, on either the D-Bus system bus or the D Bus session bus.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
### Sample Test Client
|
||||
|
||||
There is a simple test client that you can build when building Shairport Sync itself. To build it, simply add the `--with-dbus-test-client` flag at the `./configure…` stage. Along with `shairport-sync` itself, you'll get another executable called `shairport-sync-dbus-test-client` which you can run from the command line.
|
||||
|
||||
After attempting to send some commands, it will listen for property changes on the D-Bus interface and report them on the console.
|
||||
|
||||
### Command Line Examples
|
||||
|
||||
The examples below are based on Shairport Sync running as a system service and use the standard CLI tool `dbus-send`:
|
||||
* Get "Active" Status -- `true` when Shairport Sync is playing (and for a short time later); `false` otherwise.
|
||||
```
|
||||
dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Get string:org.gnome.ShairportSync string:Active
|
||||
```
|
||||
* Get Log Verbosity
|
||||
```
|
||||
dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Get string:org.gnome.ShairportSync.Diagnostics string:Verbosity
|
||||
```
|
||||
* Return Log Verbosity
|
||||
```
|
||||
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`
|
||||
```
|
||||
* Set Log Verbosity to 2
|
||||
```
|
||||
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
|
||||
```
|
||||
* Get Statistics-Requested Status
|
||||
```
|
||||
dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Get string:org.gnome.ShairportSync.Diagnostics string:Statistics
|
||||
```
|
||||
* Set Statistics-Requested Status to `true`
|
||||
```
|
||||
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
|
||||
```
|
||||
* Are File Name and Line Number included in Log Entries?
|
||||
```
|
||||
dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Get string:org.gnome.ShairportSync.Diagnostics string:FileAndLine
|
||||
```
|
||||
* Include File Name and Line Number in Log Entries
|
||||
```
|
||||
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
|
||||
```
|
||||
* Is Elapsed Time included in Log Entries?
|
||||
```
|
||||
dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Get string:org.gnome.ShairportSync.Diagnostics string:ElapsedTime
|
||||
```
|
||||
* Include Elapsed Time in Log Entries
|
||||
```
|
||||
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
|
||||
```
|
||||
* Get Drift Tolerance
|
||||
```
|
||||
dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Get string:org.gnome.ShairportSync string:DriftTolerance
|
||||
```
|
||||
* Set Drift Tolerance to 1 millisecond
|
||||
```
|
||||
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
|
||||
```
|
||||
* Is Loudness enabled:
|
||||
```
|
||||
dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Get string:org.gnome.ShairportSync string:LoudnessEnabled
|
||||
```
|
||||
* Enable Loudness Filter
|
||||
```
|
||||
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
|
||||
```
|
||||
* Get Loudness Threshold
|
||||
```
|
||||
dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Get string:org.gnome.ShairportSync string:LoudnessThreshold
|
||||
```
|
||||
* Set Loudness Threshold
|
||||
```
|
||||
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
|
||||
```
|
||||
* Is Convolution enabled:
|
||||
```
|
||||
dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Get string:org.gnome.ShairportSync string:ConvolutionEnabled
|
||||
```
|
||||
* Enable Convolution
|
||||
```
|
||||
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
|
||||
```
|
||||
* Get Convolution Gain:
|
||||
```
|
||||
dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Get string:org.gnome.ShairportSync string:ConvolutionGain
|
||||
```
|
||||
* Set Convolution Gain -- the gain applied after convolution is applied -- to -10.0 dB
|
||||
```
|
||||
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
|
||||
```
|
||||
* Get Convolution Impulse Response Files:
|
||||
```
|
||||
dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Get string:org.gnome.ShairportSync string:ConvolutionImpulseResponseFiles
|
||||
```
|
||||
* Set Convolution Impulse Response Files:
|
||||
```
|
||||
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'"
|
||||
```
|
||||
* Get Convolution Impulse Response File Maximum Length:
|
||||
```
|
||||
dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Get string:org.gnome.ShairportSync string:ConvolutionMaximumLengthInSeconds
|
||||
```
|
||||
* Set Convolution Impulse Response File Maximum Length:
|
||||
```
|
||||
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
|
||||
```
|
||||
* Get the Protocol that Shairport Sync was built for -- AirPlay or AirPlay 2:
|
||||
```
|
||||
dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Get string:org.gnome.ShairportSync string:Protocol
|
||||
```
|
||||
* 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.
|
||||
```
|
||||
dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Get string:org.gnome.ShairportSync string:Volume
|
||||
```
|
||||
* 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.
|
||||
```
|
||||
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
|
||||
```
|
||||
* 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.
|
||||
```
|
||||
dbus-send --system --print-reply --type=method_call --dest=org.gnome.ShairportSync '/org/gnome/ShairportSync' org.gnome.ShairportSync.DropSession
|
||||
```
|
||||
#### Control the player using Remote Control.
|
||||
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.
|
||||
|
||||
**Note** Unfortunately, at this time -- early 2026 -- these requests are ignored, so remote control doesn't work.
|
||||
|
||||
* Send the `play` command to the player:
|
||||
```
|
||||
dbus-send --system --print-reply --type=method_call --dest=org.gnome.ShairportSync '/org/gnome/ShairportSync' org.gnome.ShairportSync.RemoteControl.Play
|
||||
```
|
||||
Remote Control commands include: `Play`, `Pause`, `PlayPause`, `Resume`, `Stop`, `Next`, `Previous`, `VolumeUp`, `VolumeDown`, `ToggleMute`, `FastForward`, `Rewind`, `ShuffleSongs`.
|
||||
|
||||
* 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.
|
||||
```
|
||||
dbus-send --system --print-reply --type=method_call --dest=org.gnome.ShairportSync '/org/gnome/ShairportSync' org.gnome.ShairportSync.RemoteControl.SetAirplayVolume double:-10.0
|
||||
```
|
||||
AdvancedRemoteControl interface. Some commands and properties are accessible only through the AdvancedRemoteControl interface. However, support for this is very limited in recent implementations.
|
||||
|
||||
* You can check to see if AdvancedRemoteControl is available using the command:
|
||||
```
|
||||
dbus-send --print-reply --system --dest=org.gnome.ShairportSync /org/gnome/ShairportSync org.freedesktop.DBus.Properties.Get string:org.gnome.ShairportSync.AdvancedRemoteControl string:Available
|
||||
```
|
||||
* Set Volume using Advanced Remote Control -- only works if the org.gnome.ShairportSync.AdvancedRemoteControl is available.
|
||||
```
|
||||
dbus-send --system --print-reply --type=method_call --dest=org.gnome.ShairportSync '/org/gnome/ShairportSync' org.gnome.ShairportSync.AdvancedRemoteControl.SetVolume int32:50
|
||||
```
|
||||
MPRIS interface commands. For MPRIS support, Shairport Sync must be built with the MPRIS interface support. Add the `--with-mpris-interface` flag at the `./configure…` stage. There is a simple test client that you can have built -- add the '--with-mpris-test-client' flag at the ./configure stage. You'll get an executable called shairport-sync-mpris-test-client. This is mostly compatible with the MPRIS standard, except that Volume is read-only, with a separate SetVolume method.
|
||||
|
||||
* Set Volume, which must be between 0.0 and 1.0 and maps linearly onto the slider.
|
||||
```
|
||||
dbus-send --system --print-reply --type=method_call --dest=org.mpris.MediaPlayer2.ShairportSync '/org/mpris/MediaPlayer2' org.mpris.MediaPlayer2.Player.SetVolume double:0.3
|
||||
```
|
||||
Reference in New Issue
Block a user