• Home
  • History
  • Annotate
Name Date Size #Lines LOC

..03-May-2022-

data/H30-Nov-2020-258234

doc/H30-Nov-2020-392381

examples/H30-Nov-2020-14687

playerctl/H30-Nov-2020-6,9265,063

snap/H30-Nov-2020-4539

test/H30-Nov-2020-1,4991,129

.clang-formatH A D30-Nov-2020336 1211

.dockerignoreH A D30-Nov-202039 43

.flake8H A D30-Nov-2020239 1513

.travis.ymlH A D30-Nov-2020163 119

CHANGELOG.mdH A D30-Nov-20209.1 KiB221153

CONTRIBUTORSH A D30-Nov-2020307 97

COPYINGH A D30-Nov-20207.5 KiB166128

DockerfileH A D30-Nov-2020916 3124

MakefileH A D30-Nov-2020537 2417

README.mdH A D30-Nov-202014.8 KiB302198

fpm-packages.shH A D30-Nov-20202.1 KiB8361

letter-to-spotify-support.mdH A D30-Nov-20201.1 KiB2515

meson.buildH A D30-Nov-20201 KiB5243

pytest.iniH A D30-Nov-202021 32

README.md

1# Playerctl
2
3For true players only: vlc, mpv, RhythmBox, web browsers, cmus, mpd, spotify and others.
4
5[Chat](https://discord.gg/UdbXHVX)
6
7## About
8
9Playerctl is a command-line utility and library for controlling media players that implement the [MPRIS](http://specifications.freedesktop.org/mpris-spec/latest/) D-Bus Interface Specification. Playerctl makes it easy to bind player actions, such as play and pause, to media keys. You can also get metadata about the playing track such as the artist and title for integration into statusline generators or other command-line tools.
10
11Playerctl also comes with a daemon that allows it to act on the currently active media player called `playerctld`.
12
13## Using the CLI
14
15```
16playerctl [--version] [--list-all] [--all-players] [--player=NAME] [--ignore-player=IGNORE] [--format=FORMAT] [--no-messages] COMMAND
17```
18
19Here is a list of available commands:
20
21| Command                      | Description                                                                                            |
22|:----------------------------:| ------------------------------------------------------------------------------------------------------ |
23| **`play`**                   | Command the player to play.                                                                            |
24| **`pause`**                  | Command the player to pause                                                                            |
25| **`play-pause`**             | Command the player to toggle between play/pause.                                                       |
26| **`stop`**                   | Command the player to stop.                                                                            |
27| **`next`**                   | Command the player to skip to the next track.                                                          |
28| **`previous`**               | Command the player to skip to the previous track.                                                      |
29| **`position [OFFSET][+/-]`** | Command the player to go to the position or seek forward or backward OFFSET in seconds.                |
30| **`volume [LEVEL][+/-]`**    | Print or set the volume to LEVEL from 0.0 to 1.0.                                                      |
31| **`status`**                 | Get the play status of the player. Either "Playing", "Paused", or "Stopped".                           |
32| **`metadata [KEY...]`**      | Print the metadata for the current track. If KEY is passed, print only those values from the metadata. |
33| **`open [URI]`**             | Command for the player to open a given URI. Can be either a file path or a remote URL.                 |
34| **`loop [STATUS]`**          | Print or set the loop status. Either "None", "Track", or "Playlist".                                   |
35| **`shuffle [STATUS]`**       | Print or set the shuffle status. Either "On", "Off".                                                   |
36
37### Selecting Players to Control
38
39Without specifying any players to control, Playerctl will act on the first player it can find.
40
41Playerctl comes with a service called `playerctld` that monitors the activity of media players in the background. If `playerctld` is running, Playerctl will act on players in order of their last activity. To start `playerctld`, add the following command to your system startup script:
42
43```
44playerctld daemon
45```
46
47You can list the names of players that are available to control that are running on the system with `playerctl --list-all`.
48
49If you'd only like to control certain players, you can pass the names of those players separated by commas with the `--player` flag. Playerctl will select the first instance of a player in that list that supports the command. To control all players in the list, you can use the `--all-players` flag.
50
51Similarly, you can ignore players by passing their names with the `--ignore-player` flag.
52
53The special player name `%any` can be used in the list of selected players once to match any player not in the list. This can be used to prioritize or deprioritize players.
54
55Examples:
56
57```bash
58# Command the first instance of VLC to play
59playerctl --player=vlc play
60
61# Command all players to stop
62playerctl --all-players stop
63
64# Command VLC to go to the next track if it's running. If it's not, send the
65# command to Spotify.
66playerctl --player=vlc,spotify next
67
68# Get the status of the first player that is not Gwenview.
69playerctl --ignore-player=Gwenview status
70
71# Command any player to play, but select Chromium last
72playerctl --player=%any,chromium play
73
74# Command any player to play, but select VLC first
75playerctl --player=vlc,%any play
76```
77
78### Printing Properties and Metadata
79
80You can pass a format string with the `--format` argument to print properties in a specific format. Pass the variable you want to print in the format string between double braces like `{{ VARIABLE }}`. The variables available are either the name of the query command, or anything in the metadata map which can be viewed with `playerctl metadata`. You can use this to integrate playerctl into a statusline generator.
81
82For a simple "now playing" banner:
83
84```bash
85playerctl metadata --format "Now playing: {{ artist }} - {{ album }} - {{ title }}"
86# prints 'Now playing: Lana Del Rey - Born To Die - Video Games'
87```
88
89Included in the template language are some built-in variables and helper functions for common formatting that you can call on template variables. It can also do basic math operations on numbers.
90
91```bash
92# Prints 'Total length: 3:23'
93playerctl metadata --format "Total length: {{ duration(mpris:length) }}"
94
95# Prints 'At position: 1:16'
96playerctl position --format "At position: {{ duration(position) }}"
97
98# Prints 'Artist in lowercase: lana del rey'
99playerctl metadata --format "Artist in lowercase: {{ lc(artist) }}"
100
101# Prints 'STATUS: PLAYING'
102playerctl status --format "STATUS: {{ uc(status) }}"
103
104# Prints the time remaining in the track (e.g, 'Time remaining: 2:07')
105playerctl metadata --format "Time remaining: {{ duration(mpris:length - position) }}"
106
107# Prints volume from 0 - 100
108playerctl metadata --format "Volume: {{ volume * 100 }}"
109```
110
111| Function        | Argument         | Description                                                        |
112| --------------- | ---------------  | ------------------------------------------------------------------ |
113| `lc`            | string           | Convert the string to lowercase.                                   |
114| `uc`            | string           | Convert the string to uppercase.                                   |
115| `duration`      | int              | Convert the duration to hh:mm:ss format.                           |
116| `markup_escape` | string           | Escape XML markup characters in the string.                        |
117| `default`       | any, any         | Print the first value if it is present, or else print the second.  |
118| `emoji`         | status or volume | Try to convert the variable to an emoji representation.            |
119
120| Variable     | Description                                       |
121| ------------ | ------------------------------------------------- |
122| `playerName` | The name of the current player.                   |
123| `position`   | The position of the current track in microseconds |
124| `status`     | The playback status of the current player         |
125| `volume`     | The volume from 0.0 to 1.0                        |
126| `album`      | The album of the current track.                   |
127| `artist`     | The artist of the current track.                  |
128| `title`      | The title of the current track.                   |
129
130### Following changes
131
132You can pass the `--follow` flag to query commands to block, wait for players to connect, and print the query whenever it changes. If players are passed with `--player`, players earlier in the list will be preferred in the order they appear unless `--all-players` is passed. When no player can support the query, such as when all the players exit, a newline will be printed. For example, to be notified of information about the latest currently playing track for your media players, use:
133
134```bash
135playerctl metadata --format '{{ playerName }}: {{ artist }} - {{ title }} {{ duration(position) }}|{{ duration(mpris:length) }}' --follow
136```
137
138## Troubleshooting
139
140### Debug Logging
141
142To enable debug logging, set the environment variable `G_MESSAGES_DEBUG=playerctl`. It's helpful to include a debug log when you report issues.
143
144### No Players Found
145
146If you are using Quod Libet as your music player you need to install/activate a plugin for it.
147In Quod Libet open the window File -> Plugins and select the plugin called *MPRIS D-Bus Support*.
148
149Some players like Spotify require certain DBus environment variables to be set which are normally set within the session manager. If you're not using a session manager or it does not set these variables automatically (like `xinit`), launch your desktop environment wrapped in a `dbus-launch` command. For example, in your `.xinitrc` file, use this to start your WM:
150
151```
152exec dbus-launch --autolaunch=$(cat /var/lib/dbus/machine-id) i3
153```
154
155### Playerctld Autostart Issues
156
157If `playerctld` does not autostart and you use `xinit` and systemd, you might need this fix to enable DBus activation to work correctly:
158
159```
160systemctl --user import-environment DISPLAY XAUTHORITY
161
162if which dbus-update-activation-environment >/dev/null 2>&1; then
163        dbus-update-activation-environment DISPLAY XAUTHORITY
164fi
165```
166
167## Installing
168
169First, check and see if Playerctl is available from your package manager (if it is not, get someone to host a package for you) and also check the [releases](https://github.com/altdesktop/playerctl/releases) page on github.
170
171### Fedora
172
173`playerctl` is available for Fedora 28 or later:
174
175```
176sudo dnf install playerctl
177```
178
179### Mageia, openSUSE
180
181`playerctl` is available for Mageia and openSUSE via [this COPR repository](https://copr.fedorainfracloud.org/coprs/jflory7/playerctl/). First, install the repository file for your distribution from COPR. Then, install `playerctl` with your package manager of choice.
182
183### Guix
184
185`playerctl` is available as a [Guix](https://guix.gnu.org) package which can be installed on any Linux distribution after [installing Guix](https://guix.gnu.org/manual/en/html_node/Installation.html):
186
187```
188guix install playerctl
189```
190
191### Compile from source
192
193Using the cli and library requires [GLib](https://developer.gnome.org/glib/) (which is a dependency of almost all of these players as well, so you probably already have it). You can use the library in almost any programming language with the associated [introspection binding library](https://wiki.gnome.org/Projects/GObjectIntrospection/Users).
194
195Additionally, you also need the following build dependencies:
196
197[gobject-introspection](https://wiki.gnome.org/action/show/Projects/GObjectIntrospection) for building introspection data (configurable with the `introspection` meson option)
198
199[gtk-doc](http://www.gtk.org/gtk-doc/) for building documentation (configurable with the `gtk-doc` meson option)
200
201Fedora users also need to install `redhat-rpm-config`
202
203To generate and build the project to contribute to development and install playerctl to `/`:
204
205```
206meson mesonbuild
207sudo ninja -C mesonbuild install
208```
209
210Note that you need `meson >= 0.50.0` installed. In case your distro only has an older version of meson in its repository you can install the newest version via pip:
211
212```
213pip3 install meson
214```
215
216Also keep in mind that gtk-doc and gobject-introspection are enabled by default, you can disable them with `-Dintrospection=false` and `-Dgtk-doc=false`.
217
218If you don't want to install playerctl to `/` you can install it elsewhere by exporting `DESTDIR` before invoking ninja, e.g.:
219
220```
221export PREFIX="/usr/local"
222meson --prefix="${PREFIX}" --libdir="${PREFIX}/lib" mesonbuild
223export DESTDIR="$(pwd)/install"
224ninja -C mesonbuild install
225```
226
227You can use it later on by exporting the following variables:
228
229```
230export LD_LIBRARY_PATH="$DESTDIR/${PREFIX}/lib/:$LD_LIBRARY_PATH"
231export GI_TYPELIB_PATH="$DESTDIR/${PREFIX}/lib/:$GI_TYPELIB_PATH"
232export PATH="$DESTDIR/${PREFIX}/bin:$PATH"
233```
234
235## Using the Library
236
237To use a scripting library, find your favorite language from [this list](https://wiki.gnome.org/Projects/GObjectIntrospection/Users) and install the bindings library. Documentation for the library is hosted [here](https://dubstepdish.com/playerctl). For examples on how to use the library, see the [examples](https://github.com/acrisci/playerctl/blob/master/examples) folder.
238
239### Example Python Script
240
241For more advanced users, Playerctl provides an [introspectable](https://wiki.gnome.org/action/show/Projects/GObjectIntrospection) library available in your favorite scripting language that allows more detailed control like the ability to subscribe to media player events or get metadata such as artist and title for the playing track. This example uses the [Python bindings](https://wiki.gnome.org/action/show/Projects/PyGObject).
242
243```python
244#!/usr/bin/env python3
245
246from gi.repository import Playerctl, GLib
247
248player = Playerctl.Player('vlc')
249
250
251def on_metadata(player, metadata):
252    if 'xesam:artist' in metadata.keys() and 'xesam:title' in metadata.keys():
253        print('Now playing:')
254        print('{artist} - {title}'.format(
255            artist=metadata['xesam:artist'][0], title=metadata['xesam:title']))
256
257
258def on_play(player, status):
259    print('Playing at volume {}'.format(player.props.volume))
260
261
262def on_pause(player, status):
263    print('Paused the song: {}'.format(player.get_title()))
264
265
266player.connect('playback-status::playing', on_play)
267player.connect('playback-status::paused', on_pause)
268player.connect('metadata', on_metadata)
269
270# start playing some music
271player.play()
272
273if player.get_artist() == 'Lana Del Rey':
274    # I meant some good music!
275    player.next()
276
277# wait for events
278main = GLib.MainLoop()
279main.run()
280```
281
282For a more complete example which is capable of listening to when players start and exit, see [player-manager.py](https://github.com/acrisci/playerctl/blob/master/examples/player-manager.py) from the official examples.
283
284## Resources
285
286Check out the following articles about Playerctl:
287
288* [2 new apps for music tweakers on Fedora Workstation - Fedora Magazine](https://fedoramagazine.org/2-new-apps-for-music-tweakers-on-fedora-workstation/ "2 new apps for music tweakers on Fedora Workstation")
289* [Playerctl at Version 2.0](https://dubstepdish.com/index.php/2018/10/21/playerctl-at-version-2-0/)
290
291Related projects from the maker of Playerctl:
292
293* [altdesktop/python-dbus-next](https://github.com/altdesktop/python-dbus-next) - The DBus library used in the Playerctl test suite.
294* [altdesktop/playerbm](https://github.com/altdesktop/playerbm) - A CLI bookmark utility for audiobooks and podcasts.
295* [dbusjs/mpris-service](https://github.com/dbusjs/mpris-service) - MPRIS implementation for JavaScript targeting Electron apps.
296
297## License
298
299This work is available under the GNU Lesser General Public License (See COPYING).
300
301Copyright © 2014, Tony Crisci
302