README.media-keys-API
1This is very simple documentation to gnome-settings-daemon's
2D-Bus API for media players.
3
4gnome-settings-daemon will send key press events from multimedia
5keys to applications that register their interest in those events.
6This allows the play/pause button to control an audio player that's
7not focused for example.
8
9The D-Bus API is described in gsd-media-keys-manager.c (look for
10introspection_xml), but a small explanation follows here.
11
121. Create yourself a proxy object for the remote interface:
13Object path: /org/gnome/SettingsDaemon/MediaKeys
14D-Bus name: org.gnome.SettingsDaemon.MediaKeys
15Interface name: org.gnome.SettingsDaemon.MediaKeys
16
172. Register your application with gnome-settings-daemon
18GrabMediaPlayerKeys ("my-application", 0)
19with the second argument being the current time (usually 0,
20or the time passed to you from an event, such as a mouse click)
21
223. Listen to the MediaPlayerKeyPressed() signal
23
244. When receiving a MediaPlayerKeyPressed() signal,
25check whether the first argument (application) matches
26the value you passed to GrabMediaPlayerKeys() and apply the
27action depending on the key (2nd argument)
28
29Possible values of key are:
30- Play
31- Pause
32- Stop
33- Previous
34- Next
35- Rewind
36- FastForward
37- Repeat
38- Shuffle
39
405. Every time your application is focused, you should call
41GrabMediaPlayerKeys() again, so that gnome-settings-daemon knows
42which one was last used. This allows switching between a movie player
43and a music player, for example, and have the buttons control the
44last used application.
45
466. When your application wants to stop using the functionality
47it can call ReleaseMediaPlayerKeys(). If your application does
48not call ReleaseMediaPlayerKeys() and releases its D-Bus connection
49then the application will be automatically removed from the list of
50applications held by gnome-settings-daemon.
51
52