Debian Codegraph @

Mopidy_MPRIS.egg-info/PKG-INFO

raw
1 Metadata-Version: 2.1
2 Name: Mopidy-MPRIS
3 Version: 3.0.3
4 Summary: Mopidy extension for controlling Mopidy through the MPRIS D-Bus interface
5 Home-page: https://github.com/mopidy/mopidy-mpris
6 Author: Stein Magnus Jodal
7 Author-email: [email protected]
8 License: Apache License, Version 2.0
9 Description: ************
10 Mopidy-MPRIS
11 ************
12
13 .. image:: https://img.shields.io/pypi/v/Mopidy-MPRIS
14 :target: https://pypi.org/project/Mopidy-MPRIS/
15 :alt: Latest PyPI version
16
17 .. image:: https://img.shields.io/circleci/build/gh/mopidy/mopidy-mpris
18 :target: https://circleci.com/gh/mopidy/mopidy-mpris
19 :alt: CircleCI build status
20
21 .. image:: https://img.shields.io/codecov/c/gh/mopidy/mopidy-mpris
22 :target: https://codecov.io/gh/mopidy/mopidy-mpris
23 :alt: Test coverage
24
25 `Mopidy`_ extension for controlling Mopidy through D-Bus using the `MPRIS
26 specification`_.
27
28 Mopidy-MPRIS supports the minimum requirements of the `MPRIS specification`_
29 as well as the optional `Playlists interface`_. The `TrackList interface`_
30 is currently not supported.
31
32 .. _Mopidy: https://www.mopidy.com/
33 .. _MPRIS specification: https://specifications.freedesktop.org/mpris-spec/latest/
34 .. _Playlists interface: https://specifications.freedesktop.org/mpris-spec/latest/Playlists_Interface.html
35 .. _TrackList interface: https://specifications.freedesktop.org/mpris-spec/latest/Track_List_Interface.html
36
37
38 Table of contents
39 =================
40
41 - Requirements_
42 - Installation_
43 - Configuration_
44 - Usage_
45 - Clients_
46
47 - `GNOME Shell builtin`_
48 - `gnome-shell-extensions-mediaplayer`_
49 - `gnome-shell-extensions-mpris-indicator-button`_
50 - `Ubuntu Sound Menu`_
51
52 - `Advanced setups`_
53
54 - `Running as a service`_
55 - `MPRIS on the system bus`_
56 - `UPnP/DLNA with Rygel`_
57
58 - `Development tips`_
59
60 - `Browsing the MPRIS API with D-Feet`_
61 - `Testing the MPRIS API with pydbus`_
62
63 - `Project resources`_
64 - Credits_
65
66
67 Requirements
68 ============
69
70 - `pydbus`_ D-Bus Python bindings, which again depends on ``python-gi``. Thus
71 it is usually easiest to install with your distribution's package manager.
72
73 .. _pydbus: https://github.com/LEW21/pydbus
74
75
76 Installation
77 ============
78
79 Install by running::
80
81 sudo python3 -m pip install Mopidy-MPRIS
82
83 See https://mopidy.com/ext/mpris/ for alternative installation methods.
84
85
86 Configuration
87 =============
88
89 No configuration is required for the MPRIS extension to work.
90
91 The following configuration values are available:
92
93 - ``mpris/enabled``: If the MPRIS extension should be enabled or not.
94 Defaults to ``true``.
95
96 - ``mpris/bus_type``: The type of D-Bus bus Mopidy-MPRIS should connect to.
97 Choices include ``session`` (the default) and ``system``.
98
99
100 Usage
101 =====
102
103 Once Mopidy-MPRIS has been installed and your Mopidy server has been
104 restarted, the Mopidy-MPRIS extension announces its presence on D-Bus so that
105 any MPRIS compatible clients on your system can interact with it. Exactly how
106 you control Mopidy through MPRIS depends on which MPRIS client you use.
107
108
109 Clients
110 =======
111
112 The following clients have been tested with Mopidy-MPRIS.
113
114 GNOME Shell builtin
115 -------------------
116
117 State:
118 Not working
119 Tested versions:
120 Ubuntu 18.10,
121 GNOME Shell 3.30.1-2ubuntu1,
122 Mopidy-MPRIS 2.0.0
123
124 GNOME Shell, which is the default desktop on Ubuntu 18.04 onwards, has a
125 builtin MPRIS client. This client seems to work well with Spotify's player,
126 but Mopidy-MPRIS does not show up here.
127
128 If you have any tips on what's missing to get this working, please open an
129 issue.
130
131 gnome-shell-extensions-mediaplayer
132 ----------------------------------
133
134 State:
135 Working
136 Tested versions:
137 Ubuntu 18.10,
138 GNOME Shell 3.30.1-2ubuntu1,
139 gnome-shell-extension-mediaplayer 63,
140 Mopidy-MPRIS 2.0.0
141 Website:
142 https://github.com/JasonLG1979/gnome-shell-extensions-mediaplayer
143
144 gnome-shell-extensions-mediaplayer is a quite feature rich MPRIS client
145 built as an extension to GNOME Shell. With the improvements to Mopidy-MPRIS
146 in v2.0, this extension works very well with Mopidy.
147
148 gnome-shell-extensions-mpris-indicator-button
149 ---------------------------------------------
150
151 State:
152 Working
153 Tested versions:
154 Ubuntu 18.10,
155 GNOME Shell 3.30.1-2ubuntu1,
156 gnome-shell-extensions-mpris-indicator-button 5,
157 Mopidy-MPRIS 2.0.0
158 Website:
159 https://github.com/JasonLG1979/gnome-shell-extensions-mpris-indicator-button/
160
161 gnome-shell-extensions-mpris-indicator-button is a minimalistic version of
162 gnome-shell-extensions-mediaplayer. It works with Mopidy-MPRIS, with the
163 exception of the play/pause button not changing state when Mopidy starts
164 playing.
165
166 If you have any tips on what's missing to get the play/pause button display
167 correctly, please open an issue.
168
169 Ubuntu Sound Menu
170 -----------------
171
172 State:
173 Unknown
174
175 Historically, Ubuntu Sound Menu was the primary target for Mopidy-MPRIS'
176 development. Since Ubuntu 18.04 replaced Unity with GNOME Shell, this is no
177 longer the case. It is currently unknown to what degree Mopidy-MPRIS works
178 with old Ubuntu setups.
179
180 If you run an Ubuntu setup with Unity and have tested Mopidy-MPRIS, please
181 open an issue to share your results.
182
183
184 Advanced setups
185 ===============
186
187 Running as a service
188 --------------------
189
190 If you have input on how to best configure Mopidy-MPRIS when Mopidy is
191 running as a service, please add a comment to `issue #15`_.
192
193 .. _issue #15: https://github.com/mopidy/mopidy-mpris/issues/15
194
195 MPRIS on the system bus
196 -----------------------
197
198 You can set the ``mpris/bus_type`` config value to ``system``. This will lead
199 to Mopidy-MPRIS making itself available on the system bus instead of the
200 logged in user's session bus.
201
202 .. note::
203 Few MPRIS clients will try to access MPRIS devices on the system bus, so
204 this will give you limited functionality. For example, media keys in
205 GNOME Shell does not work with media players that expose their MPRIS
206 interface on the system bus instead of the user's session bus.
207
208 The default setup will often not permit Mopidy to publish its service on the
209 D-Bus system bus, causing a warning similar to this in Mopidy's log::
210
211 MPRIS frontend setup failed (g-dbus-error-quark:
212 GDBus.Error:org.freedesktop.DBus.Error.AccessDenied: Connection ":1.3071"
213 is not allowed to own the service "org.mpris.MediaPlayer2.mopidy" due to
214 security policies in the configuration file (9))
215
216 To solve this, create the file
217 ``/etc/dbus-1/system.d/org.mpris.MediaPlayer2.mopidy.conf`` with the
218 following contents:
219
220 .. code:: xml
221
222 <!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
223 "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
224 <busconfig>
225 <!-- Allow mopidy user to publish the Mopidy-MPRIS service -->
226 <policy user="mopidy">
227 <allow own="org.mpris.MediaPlayer2.mopidy"/>
228 </policy>
229
230 <!-- Allow anyone to invoke methods on the Mopidy-MPRIS service -->
231 <policy context="default">
232 <allow send_destination="org.mpris.MediaPlayer2.mopidy"/>
233 <allow receive_sender="org.mpris.MediaPlayer2.mopidy"/>
234 </policy>
235 </busconfig>
236
237 If you run Mopidy as another user than ``mopidy``, you must
238 update ``user="mopidy"`` in the above file accordingly.
239
240 Once the file is in place, you must restart Mopidy for the change to take
241 effect.
242
243 To test the setup, you can run the following command as any user on the
244 system to play/pause the music::
245
246 dbus-send --system --print-reply \
247 --dest=org.mpris.MediaPlayer2.mopidy \
248 /org/mpris/MediaPlayer2 \
249 org.mpris.MediaPlayer2.Player.PlayPause
250
251 UPnP/DLNA with Rygel
252 --------------------
253
254 Rygel_ is an application that will translate between Mopidy's MPRIS interface
255 and UPnP. Rygel must be run on the same machine as Mopidy, but will make
256 Mopidy controllable by any device on the local network that can control a
257 UPnP/DLNA MediaRenderer.
258
259 .. _Rygel: https://wiki.gnome.org/Projects/Rygel
260
261 The setup process is approximately as follows:
262
263 1. Install Rygel.
264
265 On Debian/Ubuntu/Raspbian::
266
267 sudo apt install rygel
268
269 2. Enable Rygel's MPRIS plugin.
270
271 On Debian/Ubuntu/Raspbian, edit ``/etc/rygel.conf``, find the ``[MPRIS]``
272 section, and change ``enabled=false`` to ``enabled=true``.
273
274 3. Start Rygel.
275
276 To start it as the current user::
277
278 systemctl --user start rygel
279
280 To make Rygel start as the current user on boot::
281
282 systemctl --user enable rygel
283
284 4. Configure your system's firewall to allow the local network to reach
285 Rygel. Exactly how is out of scope for this document.
286
287 5. Start Mopidy with Mopidy-MPRIS enabled.
288
289 6. If you view Rygel's log output with::
290
291 journalctl --user -feu rygel
292
293 You should see a log statement similar to::
294
295 New plugin "org.mpris.MediaPlayer2.mopidy" available
296
297 6. If everything went well, you should now be able to control Mopidy from a
298 device on your local network that can control an UPnP/DLNA MediaRenderer,
299 for example the Android app BubbleUPnP.
300
301 Alternatively, `upmpdcli combined with Mopidy-MPD`_ serves the same purpose as
302 this setup.
303
304 .. _upmpdcli combined with Mopidy-MPD: https://docs.mopidy.com/en/latest/clients/upnp/
305
306
307 Development tips
308 ================
309
310 Mopidy-MPRIS has an extensive test suite, so the first step for all changes
311 or additions is to add a test exercising the new code. However, making the
312 tests pass doesn't ensure that what comes out on the D-Bus bus is correct. To
313 introspect this through the bus, there's a couple of useful tools.
314
315
316 Browsing the MPRIS API with D-Feet
317 ----------------------------------
318
319 D-Feet is a graphical D-Bus browser. On Debian/Ubuntu systems it can be
320 installed by running::
321
322 sudo apt install d-feet
323
324 Then run the ``d-feet`` command. In the D-Feet window, select the tab
325 corresponding to the bus you run Mopidy-MPRIS on, usually the session bus.
326 Then search for "MediaPlayer2" to find all available MPRIS interfaces.
327
328 To get the current value of a property, double-click it. To execute a method,
329 double-click it, provide any required arguments, and click "Execute".
330
331 For more information on D-Feet, see the `GNOME wiki
332 <https://wiki.gnome.org/Apps/DFeet>`_.
333
334
335 Testing the MPRIS API with pydbus
336 ---------------------------------
337
338 To use the MPRIS API directly, start Mopidy, and then run the following in a
339 Python shell to use ``pydbus`` as an MPRIS client::
340
341 >>> import pydbus
342 >>> bus = pydbus.SessionBus()
343 >>> player = bus.get('org.mpris.MediaPlayer2.mopidy', '/org/mpris/MediaPlayer2')
344
345 Now you can control Mopidy through the player object. To get properties from
346 Mopidy, run for example::
347
348 >>> player.PlaybackStatus
349 'Playing'
350 >>> player.Metadata
351 {'mpris:artUrl': 'https://i.scdn.co/image/8eb49b41eeb45c1cf53e1ddfea7973d9ca257777',
352 'mpris:length': 342000000,
353 'mpris:trackid': '/com/mopidy/track/36',
354 'xesam:album': '65/Milo',
355 'xesam:albumArtist': ['Kiasmos'],
356 'xesam:artist': ['Rival Consoles'],
357 'xesam:discNumber': 1,
358 'xesam:title': 'Arp',
359 'xesam:trackNumber': 5,
360 'xesam:url': 'spotify:track:7CoxEEsqo3XdvUsScRV4WD'}
361 >>>
362
363 To pause Mopidy's playback through D-Bus, run::
364
365 >>> player.Pause()
366 >>>
367
368 For details on the API, please refer to the `MPRIS specification
369 <https://specifications.freedesktop.org/mpris-spec/latest/>`__.
370
371
372 Project resources
373 =================
374
375 - `Source code <https://github.com/mopidy/mopidy-mpris>`_
376 - `Issue tracker <https://github.com/mopidy/mopidy-mpris/issues>`_
377 - `Changelog <https://github.com/mopidy/mopidy-mpris/releases>`_
378
379
380 Credits
381 =======
382
383 - Original author: `Stein Magnus Jodal <https://github.com/jodal>`__
384 - Current maintainer: `Stein Magnus Jodal <https://github.com/jodal>`__
385 - `Contributors <https://github.com/mopidy/mopidy-mpris/graphs/contributors>`_
386
387 Platform: UNKNOWN
388 Classifier: Development Status :: 5 - Production/Stable
389 Classifier: Environment :: No Input/Output (Daemon)
390 Classifier: Intended Audience :: End Users/Desktop
391 Classifier: License :: OSI Approved :: Apache Software License
392 Classifier: Operating System :: POSIX :: Linux
393 Classifier: Programming Language :: Python :: 3
394 Classifier: Programming Language :: Python :: 3.7
395 Classifier: Programming Language :: Python :: 3.8
396 Classifier: Programming Language :: Python :: 3.9
397 Classifier: Topic :: Multimedia :: Sound/Audio :: Players
398 Requires-Python: >=3.7
399 Provides-Extra: lint
400 Provides-Extra: release
401 Provides-Extra: test
402 Provides-Extra: dev