1PLAYERCTL(1) BSD General Commands Manual PLAYERCTL(1)
2
4 playerctl — control media players via MPRIS
5
7 playerctl [-aFhlV] [-f FORMAT] [-i NAME] [-p NAME] command
8
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 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 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 The options are as follows:
28 -a, --all-players
30 Apply command to all available players.
31 -F, --follow
33 Block and output the updated query when it changes.
34 -f FORMAT, --format FORMAT
36 Set the output of the current command to FORMAT. See Format
37 Strings.
38 -h, --help
40 Print this help, then exit.
41 -i NAME, --ignore-player NAME
43 Ignore the specific player NAME. Multiple players can be speci‐
44 fied in a comma-separated list.
45 -l, --list-all
47 List the names of running players that can be controlled.
48 -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 -s, --no-messages
56 Silence some diagnostic and error messages.
57 -V, --version
59 Print version number, then exit.
60 The commands are as follows:
62 status Get the current status of the player.
64 play Command the player to play.
66 pause Command the player to pause.
68 play-pause
70 Command the player to toggle between play and pause.
71 stop Command the player to stop.
73 next Command the player to skip to the next track.
75 previous
77 Command the player to skip to the previous track.
78 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 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 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 open URI
97 Open URI in the player. URI may be the name of a file or an ex‐
98 ternal URL.
99 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 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 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 Each command has access to the following variables:
116 playerName
118 The name of the current player.
119 position
121 The time position of the current track, in microseconds.
122 status The status of the current player.
124 volume The player's volume scaled from 0.0 (0%) to 1.0 (100%).
126 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 album, xesam:album
134 The album of the current track.
135 artist, xesam:artist
137 The artist of the current track.
138 title, xesam:title
140 The title of the current track.
141 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 lc(str)
147 Convert string str to lowercase.
148 uc(str)
150 Convert string str to uppercase.
151 markup_escape(str)
153 Escape XML characters in string str.
154 default(str1, str2)
156 Print str1 if set, else print str2.
157 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 emoji(key)
163 Try to convert the value for key to an emoji representation. Cur‐
164 rently implemented for status and volume.
165 trunc(str, len)
167 Truncate str to a maximum of len characters, adding an ellipsis
168 (…) if necessary.
169 The template language is also able to perform basic math operations.
171 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
177 The playerctl utility exits 0 on success, and >0 if an error occurs.
178
180 Print the player name, playback status in lowercase, and position and
181 length in human readable form:
182 $ playerctl metadata --format '{{playerName}}: {{lc(status)}} '\
184 '{{duration(position)}}|{{duration(mpris:length)}}'
185
187 MPRIS v2 metadata guidelines, freedesktop.org,
188 https://freedesktop.org/wiki/Specifications/mpris-spec/metadata/,
189 September 18, 2013.
190 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
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 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>.
203BSD September 21, 2021 BSD