1PLAYERCTL(1)              BSD General Commands Manual             PLAYERCTL(1)
2

NAME

4     playerctl — control media players via MPRIS
5

SYNOPSIS

7     playerctl [-aFhlV] [-f FORMAT] [-i NAME] [-p NAME] command
8

DESCRIPTION

10     The playerctl utility controls MPRIS-enabled media players.  In addition
11     to offering play, pause and stop control, playerctl also offers previous
12     and next track support, the ability to seek backwards and forwards in a
13     track, and volume control.  playerctl also supports displaying metadata
14     (e.g., artist, title, album) for the current track, and showing the sta‐
15     tus of the player.
16
17     Players that can be controlled using playerctl include audacious(1),
18     cmus(1), mopidy(1), mpd(1), quodlibet(1), rhythmbox(1), vlc(1) and
19     xmms2(1).  However, any player that implements the MPRIS interface speci‐
20     fication can be controlled using playerctl including web browsers.
21
22     Playerctl also comes with a daemon called playerctld which keeps track of
23     media player activity. When playerctld is running, playerctl commands
24     will act on the media player with the most recent activity.  Run the com‐
25     mand playerctld daemon to start the daemon.
26
27     The options are as follows:
28
29     -a, --all-players
30             Apply command to all available players.
31
32     -F, --follow
33             Block and output the updated query when it changes.
34
35     -f FORMAT, --format FORMAT
36             Set the output of the current command to FORMAT.  See Format
37             Strings.
38
39     -h, --help
40             Print this help, then exit.
41
42     -i NAME, --ignore-player NAME
43             Ignore the specific player NAME.  Multiple players can be speci‐
44             fied in a comma-separated list.
45
46     -l, --list-all
47             List the names of running players that can be controlled.
48
49     -p NAME, --player NAME
50             Control the specific player NAME.  Multiple players can be speci‐
51             fied in a comma-separated list.  Defaults to the first available
52             player.  The name "name" matches both "name" and "name.{IN‐
53             STANCE}".  Additionally, the name "%any" matches any player.
54
55     -s, --no-messages
56             Silence some diagnostic and error messages.
57
58     -V, --version
59             Print version number, then exit.
60
61     The commands are as follows:
62
63     status  Get the current status of the player.
64
65     play    Command the player to play.
66
67     pause   Command the player to pause.
68
69     play-pause
70             Command the player to toggle between play and pause.
71
72     stop    Command the player to stop.
73
74     next    Command the player to skip to the next track.
75
76     previous
77             Command the player to skip to the previous track.
78
79     position [OFFSET[+|-]]
80             Print the position of the current track in seconds.  With OFFSET
81             specified, seek to OFFSET seconds from the start of the current
82             track.  With the optional [+|-] appended, seek forward or back‐
83             ward OFFSET seconds from the current position.
84
85     volume [LEVEL[+|-]]
86             Print the player's volume scaled from 0.0 (0%) to 1.0 (100%).
87             With LEVEL specified, set the player's volume to LEVEL.  With the
88             optional [+|-] appended, increase or decrease the player's volume
89             by LEVEL.
90
91     metadata [KEY]
92             Print all metadata properties for the current track set by the
93             current player.  If KEY is specified only the value of KEY is
94             printed.
95
96     open URI
97             Open URI in the player.  URI may be the name of a file or an ex‐
98             ternal URL.
99
100     shuffle [On | Off | Toggle]
101             Print the shuffle status of the player.  With the shuffle status
102             specified, set the shuffle status to either On , Off , or Toggle
103
104     loop [None | Track | Playlist]
105             Print the loop status of the player.  With the loop status speci‐
106             fied, set the loop status to None (disable looping), Track (loop
107             the current track), or Playlist (loop the current playlist).
108
109   Format Strings
110     The output of the position, metadata, status and volume commands can be
111     controlled using a format string.  Variables set by these commands can be
112     included in the format string by enclosing them in curly braces:
113     ‘{{var}}’.  These will then be expanded on output.
114
115     Each command has access to the following variables:
116
117     playerName
118             The name of the current player.
119
120     position
121             The time position of the current track, in microseconds.
122
123     status  The status of the current player.
124
125     volume  The player's volume scaled from 0.0 (0%) to 1.0 (100%).
126
127     Each property listed in the metadata command are also set as variables.
128     It is recommended to check this list for each player, as different play‐
129     ers may not set the same properties.  See the MPRIS v2 metadata
130     guidelines for a list of all properties in the MPRIS specification.  The
131     most common properties are as follows:
132
133     album, xesam:album
134             The album of the current track.
135
136     artist, xesam:artist
137             The artist of the current track.
138
139     title, xesam:title
140             The title of the current track.
141
142     Helper functions are also available to transform expanded variables into
143     other representations.  They are called in the form ‘{{func(var)}}’.  The
144     helper functions are as follows:
145
146     lc(str)
147             Convert string str to lowercase.
148
149     uc(str)
150             Convert string str to uppercase.
151
152     markup_escape(str)
153             Escape XML characters in string str.
154
155     default(str1, str2)
156             Print str1 if set, else print str2.
157
158     duration(time)
159             Reformat the microsecond timestamp time in the form ‘hh:mm:ss’.
160             Can only be called with position or mpris:length.
161
162     emoji(key)
163             Try to convert the value for key to an emoji representation. Cur‐
164             rently implemented for status and volume.
165
166     trunc(str, len)
167             Truncate str to a maximum of len characters, adding an ellipsis
168             (…) if necessary.
169
170     The template language is also able to perform basic math operations.
171
172     References to unknown functions will cause playerctl to exit with an er‐
173     ror.  References to unknown variables will be expanded to empty strings.
174     Text not enclosed in braces will be printed verbatim.
175

EXIT STATUS

177     The playerctl utility exits 0 on success, and >0 if an error occurs.
178

EXAMPLES

180     Print the player name, playback status in lowercase, and position and
181     length in human readable form:
182
183           $ playerctl metadata --format '{{playerName}}: {{lc(status)}} '\
184           '{{duration(position)}}|{{duration(mpris:length)}}'
185

SEE ALSO

187     MPRIS v2 metadata guidelines, freedesktop.org,
188     https://freedesktop.org/wiki/Specifications/mpris-spec/metadata/,
189     September 18, 2013.
190
191     playerctl homepage: https://github.com/altdesktop/playerctl, playerctl
192     API documentation: https://dubstepdish.com/playerctl, GObject
193     introspection language bindings:
194     https://wiki.gnome.org/Projects/GObjectIntrospection/Users
195

AUTHORS

197     The playerctl utility is maintained by Tony Crisci <tony@dubstepdish.com>
198     and is made available under the GNU Lesser General Public License 3.0.
199
200     This reference was written by Nick Morrott <knowledgejunkie@gmail.com>
201     for the Debian GNU/Linux project.  It was later updated and expanded by
202     Stephen Gregoratto <dev@sgregoratto.me>.
203
204BSD                           September 21, 2021                           BSD
Impressum