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

EXIT STATUS

162     The playerctl utility exits 0 on success, and >0 if an error occurs.
163

EXAMPLES

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

SEE ALSO

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

AUTHORS

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                             August 8, 2020                             BSD
Impressum