Repository files navigation

For true players only: vlc, mpv, RhythmBox, web browsers, cmus, mpd, spotify and others.

Chat

Playerctl is a command-line utility and library for controlling media players that implement theMPRIS 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.

Playerctl also comes with a daemon that allows it to act on the currently active media player calledplayerctld.

playerctl [--version] [--list-all] [--all-players] [--player=NAME] [--ignore-player=IGNORE] [--format=FORMAT] [--no-messages] COMMAND

Here is a list of available commands:

Without specifying any players to control, Playerctl will act on the first player it can find.

Playerctl comes with a service calledplayerctld that monitors the activity of media players in the background. Ifplayerctld is running, Playerctl will act on players in order of their last activity. To startplayerctld, add the following command to your system startup script:

playerctld daemon

You can list the names of players that are available to control that are running on the system withplayerctl --list-all.

If 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.

Similarly, you can ignore players by passing their names with the--ignore-player flag.

The 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.

Examples:

# Command the first instance of VLC to playplayerctl --player=vlc play# Command all players to stopplayerctl --all-players stop# Command VLC to go to the next track if it's running. If it's not, send the# command to Spotify.playerctl --player=vlc,spotify next# Get the status of the first player that is not Gwenview.playerctl --ignore-player=Gwenview status# Command any player to play, but select Chromium lastplayerctl --player=%any,chromium play# Command any player to play, but select VLC firstplayerctl --player=vlc,%any play

You 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 withplayerctl metadata. You can use this to integrate playerctl into a statusline generator.

For a simple "now playing" banner:

playerctl metadata --format"Now playing: {{ artist }} - {{ album }} - {{ title }}"# prints 'Now playing: Lana Del Rey - Born To Die - Video Games'

Included 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.

# Prints 'Total length: 3:23'playerctl metadata --format"Total length: {{ duration(mpris:length) }}"# Prints 'At position: 1:16'playerctl position --format"At position: {{ duration(position) }}"# Prints 'Artist in lowercase: lana del rey'playerctl metadata --format"Artist in lowercase: {{ lc(artist) }}"# Prints 'STATUS: PLAYING'playerctl status --format"STATUS: {{ uc(status) }}"# Prints the time remaining in the track (e.g, 'Time remaining: 2:07')playerctl metadata --format"Time remaining: {{ duration(mpris:length - position) }}"# Prints volume from 0 - 100playerctl metadata --format"Volume: {{ volume * 100 }}"

You 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:

playerctl metadata --format'{{ playerName }}: {{ artist }} - {{ title }} {{ duration(position) }}|{{ duration(mpris:length) }}' --follow

You can seek to a position in the track or skip forward and back.

# Go back 30 secondsplayerctl position 30-# Go forward 30 secondsplayerctl position 30+# Seek to the position at 30 secondsplayerctl position 30

To enable debug logging, set the environment variableG_MESSAGES_DEBUG=playerctl. It's helpful to include a debug log when you report issues.

Some 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 (likexinit), launch your desktop environment wrapped in adbus-launch command. For example, in your.xinitrc file, use this to start your WM:

exec dbus-launch --autolaunch=$(cat /var/lib/dbus/machine-id) i3

Some players may require installation of a plugin or other configuration.

In Quod Libet open the window File -> Plugins and select the plugin calledMPRIS D-Bus Support.

Ifplayerctld does not autostart and you usexinit and systemd, you might need this fix to enable DBus activation to work correctly:

systemctl --user import-environment DISPLAY XAUTHORITYif which dbus-update-activation-environment >/dev/null 2>&1; then        dbus-update-activation-environment DISPLAY XAUTHORITYfi

First, 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 thereleases page on github.

playerctl is available for Fedora 28 or later:

sudo dnf install playerctl

playerctl is available for Mageia and openSUSE viathis COPR repository. First, install the repository file for your distribution from COPR. Then, installplayerctl with your package manager of choice.

playerctl is available as aGuix package which can be installed on any Linux distribution afterinstalling Guix:

guix install playerctl

Using the cli and library requiresGLib (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 associatedintrospection binding library.

Additionally, you also need the following build dependencies:

gobject-introspection for building introspection data (configurable with theintrospection meson option)

gtk-doc for building documentation (configurable with thegtk-doc meson option)

Fedora users also need to installredhat-rpm-config

To generate and build the project to contribute to development and install playerctl to/:

meson mesonbuildsudo ninja -C mesonbuild install

Note that you needmeson installed. In case your distro only has an older version of meson in its repository you can install the newest version via pip:

pip3 install meson

Also keep in mind that gtk-doc and gobject-introspection are enabled by default, you can disable them with-Dintrospection=false and-Dgtk-doc=false.

If you don't want to install playerctl to/ you can install it elsewhere by exportingDESTDIR before invoking ninja, e.g.:

export PREFIX="/usr/local"meson --prefix="${PREFIX}" --libdir="${PREFIX}/lib" mesonbuildexport DESTDIR="$(pwd)/install"ninja -C mesonbuild install

You can use it later on by exporting the following variables:

export LD_LIBRARY_PATH="$DESTDIR/${PREFIX}/lib/:$LD_LIBRARY_PATH"export GI_TYPELIB_PATH="$DESTDIR/${PREFIX}/lib/:$GI_TYPELIB_PATH"export PATH="$DESTDIR/${PREFIX}/bin:$PATH"

To use a scripting library, find your favorite language fromthis list and install the bindings library. Documentation for the library is hostedhere. For examples on how to use the library, see theexamples folder.

For more advanced users, Playerctl provides anintrospectable 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 thePython bindings.

#!/usr/bin/env python3fromgi.repositoryimportPlayerctl,GLibplayer=Playerctl.Player('vlc')defon_metadata(player,metadata):if'xesam:artist'inmetadata.keys()and'xesam:title'inmetadata.keys():print('Now playing:')print('{artist} - {title}'.format(artist=metadata['xesam:artist'][0],title=metadata['xesam:title']))defon_play(player,status):print('Playing at volume {}'.format(player.props.volume))defon_pause(player,status):print('Paused the song: {}'.format(player.get_title()))player.connect('playback-status::playing',on_play)player.connect('playback-status::paused',on_pause)player.connect('metadata',on_metadata)# start playing some musicplayer.play()ifplayer.get_artist()=='Lana Del Rey':# I meant some good music!player.next()# wait for eventsmain=GLib.MainLoop()main.run()

For a more complete example which is capable of listening to when players start and exit, seeplayer-manager.py from the official examples.

Check out the following articles about Playerctl:

• 2 new apps for music tweakers on Fedora Workstation - Fedora Magazine
• Playerctl at Version 2.0

Related projects from the maker of Playerctl:

• altdesktop/python-dbus-next - The DBus library used in the Playerctl test suite.
• altdesktop/playerbm - A CLI bookmark utility for audiobooks and podcasts.
• dbusjs/mpris-service - MPRIS implementation for JavaScript targeting Electron apps.

This work is available under the GNU Lesser General Public License (See COPYING).

Copyright © 2014, Tony Crisci