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
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.
21
22 The options are as follows:
23
24 -a, --all-players
25 Apply command to all available players.
26
27 -F, --follow
28 Block and output the updated query when it changes.
29
30 -f FORMAT, --format FORMAT
31 Set the output of the current command to FORMAT. See Format
32 Strings.
33
34 -h, --help
35 Print this help, then exit.
36
37 -i NAME, --ignore-player NAME
38 Ignore the specific player NAME. Multiple players can be speci‐
39 fied in a comma-separated list.
40
41 -l, --list-all
42 List the names of running players that can be controlled.
43
44 -p NAME, --player NAME
45 Control the specific player NAME. Multiple players can be speci‐
46 fied in a comma-separated list. Defaults to the first available
47 player.
48
49 -V, --version
50 Print version number, then exit.
51
52 The commands are as follows:
53
54 status Get the current status of the player.
55
56 play Command the player to play.
57
58 pause Command the player to pause.
59
60 play-pause
61 Command the player to toggle between play and pause.
62
63 stop Command the player to stop.
64
65 next Command the player to skip to the next track.
66
67 previous
68 Command the player to skip to the previous track.
69
70 position [OFFSET[+|-]]
71 Print the position of the current track in seconds. With OFFSET
72 specified, seek to OFFSET seconds from the start of the current
73 track. With the optional [+|-] appended, seek forward or back‐
74 ward OFFSET seconds from the current position.
75
76 volume [LEVEL[+|-]]
77 Print the player's volume scaled from 0.0 (0%) to 1.0 (100%).
78 With LEVEL specified, set the player's volume to LEVEL. With the
79 optional [+|-] appended, increase or decrease the player's volume
80 by LEVEL.
81
82 metadata [KEY]
83 Print all metadata properties for the current track set by the
84 current player. If KEY is specified only the value of KEY is
85 printed.
86
87 open URI
88 Open URI in the player. URI may be the name of a file or an
89 external URL.
90
91 shuffle [On | Off]
92 Print the shuffle status of the player. With the shuffle status
93 specified, set the shuffle status to either On or Off.
94
95 loop [None | Track | Playlist]
96 Print the loop status of the player. With the loop status speci‐
97 fied, set the loop status to None (disable looping), Track (loop
98 the current track), or Playlist (loop the current playlist).
99
100 Format Strings
101 The output of the position, metadata, status and volume commands can be
102 controlled using a format string. Variables set by these commands can be
103 included in the format string by enclosing them in curly braces:
104 ‘{{var}}’. These will then be expanded on output.
105
106 Each command has access to the following variables:
107
108 playerName
109 The name of the current player.
110
111 position
112 The time position of the current track, in microseconds.
113
114 status The status of the current player.
115
116 volume The player's volume scaled from 0.0 (0%) to 1.0 (100%).
117
118 Each property listed in the metadata command are also set as variables.
119 It is recommended to check this list for each player, as different play‐
120 ers may not set the same properties. See the MPRIS v2 metadata
121 guidelines for a list of all properties in the MPRIS specification. The
122 most common properties are as follows:
123
124 album, xesam:album
125 The album of the current track.
126
127 artist, xesam:artist
128 The artist of the current track.
129
130 title, xesam:title
131 The title of the current track.
132
133 Helper functions are also available to transform expanded variables into
134 other representations. They are called in the form ‘{{func(var)}}’. The
135 helper functions are as follows:
136
137 lc(str)
138 Convert string str to lowercase.
139
140 uc(str)
141 Convert string str to uppercase.
142
143 markup_escape(str)
144 Escape XML characters in string str.
145
146 default(str1, str2)
147 Print str1 if set, else print str2.
148
149 duration(time)
150 Reformat the microsecond timestamp time in the form ‘hh:mm:ss’.
151 Can only be called with position or mpris:length.
152
153 emoji(key)
154 Try to convert the value for key to an emoji representation. Cur‐
155 rently implemented for status and volume.
156
157 References to unknown functions will cause playerctl to exit with an
158 error. References to unknown variables will be expanded to empty
159 strings. Text not enclosed in braces will be printed verbatim.
160
162 The playerctl utility exits 0 on success, and >0 if an error occurs.
163
165 Print the player name, playback status in lowercase, and position and
166 length in human readable form:
167
168 $ playerctl metadata --format '{{playerName}}: {{lc(status)}} '\
169 '{{duration(position)}}|{{duration(mpris:length)}}'
170
172 MPRIS v2 metadata guidelines, freedesktop.org,
173 https://freedesktop.org/wiki/Specifications/mpris-spec/metadata/,
174 September 18, 2013.
175
176 playerctl homepage:
177 https://github.com/altdesktop/playerctl,
178 playerctl API documentation:
179 https://dubstepdish.com/playerctl,
180 GObject introspection language bindings:
181 https://wiki.gnome.org/Projects/GObjectIntrospection/Users
182
184 The playerctl utility is maintained by Tony Crisci <tony@dubstepdish.com>
185 and is made available under the GNU Lesser General Public License 3.0.
186
187 This reference was written by Nick Morrott <knowledgejunkie@gmail.com>
188 for the Debian GNU/Linux project. It was later updated and expanded by
189 Stephen Gregoratto <dev@sgregoratto.me>.
190
191BSD January 31, 2020 BSD