playerctl(1)

1PLAYERCTL(1)                     User Commands                    PLAYERCTL(1)
2
3
4

NAME

6       playerctl - utility to control media players via MPRIS
7

SYNOPSIS

9       playerctl [OPTION] COMMAND
10

DESCRIPTION

playerctl is a command line utility to control MPRIS-enabled media players. In

13addition to offering play/pause/stop control,  playerctl  also  offers  previ‐
14ous/next  track  support, the ability to seek backward/forward in a track, and
15volume  control.   playerctl   also   supports   displaying   metadata   (e.g.
16artist/title/album)  for  the  current  track,  and  showing the status of the
17player.
18
19Players that can  be  controlled  using  playerctl  include  audacious,  cmus,
20mopidy,  mpd,  quod  libet, rhythmbox, vlc and xmms2. However, any player that
21implements the MPRIS interface specification should be able to  be  controlled
22using playerctl.
23

OPTIONS

25       -p, --player=NAME
26              The  name  or  comma-separated  list  of  the players to control
27              (default: first available player)
28
29       -i, --ignore-player=NAME
30              The name or comma-separated list of the players to ignore
31
32       -f, --format=FORMAT
33              A format string for printing properties and metadata
34
35       -F, --follow
36              Block and output the updated query when it changes
37
38       -l, --list-all
39              List the names of running players that can be controlled
40
41       -a, --all-players
42              Apply command to all available players
43
44       -h, --help
45              Print this help, then exit
46
47       -V, --version
48              Print version number, then exit
49

COMMANDS

51       status Get the current status of the player
52
53       play   Command the player to play
54
55       pause  Command the player to pause
56
57       play-pause
58              Command the player to toggle between play/pause
59
60       stop   Command the player to stop
61
62       next   Command the player to skip to the next track
63
64       previous
65              Command the player to skip to the previous track
66
67       position [OFFSET][+|-]
68              Print the position of the current track in seconds. With  OFFSET
69              specified,  seek to OFFSET seconds from the start of the current
70              track.  With the optional [+|-] appended, seek  forward/backward
71              OFFSET seconds from the current position.
72
73       volume [LEVEL][+|-]
74              Print  the  player's  volume scaled from 0.0 (0%) to 1.0 (100%).
75              With LEVEL specified, set the player's volume to LEVEL. With the
76              optional  [+|-]  appended, increase/decrease the player's volume
77              by LEVEL.
78
79       metadata [KEY]
80              Print available metadata information for the current track. When
81              KEY is specified, print the value of KEY.
82
83       open [URI]
84              Open  the  given URI in the player. The URI may be the name of a
85              file or an external URL.
86
87       shuffle [{On|Off}]
88              Print the shuffle status of the player. With the shuffle  status
89              specified, set shuffle to either On or Off.
90
91       loop [{None|Track|Playlist}]
92              Print the loop status of the player. With the loop status speci‐
93              fied, set the loop status to either None to not loop,  Track  to
94              loop  the  current  track,  or  Playlist  to  loop  the  current
95              playlist.
96

FORMAT STRINGS

98       A format string can be given with the --format argument to print  prop‐
99       erties  and  metadata  in  a  particular format. Variable names between
100       curly braces in the form of {{ VARIABLE }} will be  expanded  to  their
101       values.  The  available  variables  are  the names of the commands that
102       print properties or any of the metadata keys that can  be  viewed  with
103       the metadata command. The name of the player is also available with the
104       playerName variable.
105
106       Several helper functions are available  in  the  template  language  to
107       transform   expanded  values  which  can  be  called  in  the  form  {{
108       HELPER(VARIABLE) }}. The available helper functions are:
109
110       lc     Convert the value to lowercase
111
112       uc     Convert the value to uppercase
113
114       duration
115              When called on a duration such as position or mpris:length, con‐
116              vert the duration to hh:mm:ss form
117

EXAMPLES

119       To  print  the  player name, playback status in lowercase, and position
120       and length in human readable form:
121
122              playerctl  metadata  --format  '{{playerName}}:   {{lc(status)}}
123              {{duration(position)}}|{{duration(mpris:length)}}'
124

REPORTING BUGS

132       Please  review  and  report  bugs  to  https://github.com/acrisci/play‐
133       erctl/issues
134

AVAILABILITY

136       The     latest     version     of    playerctl    is    available    at
137       https://github.com/acrisci/playerctl
138

AUTHOR

140       This   manual   page  was   created   by   Nick   Morrott   <knowledge‐
141       junkie@gmail.com>  for  the Debian GNU/Linux system, but may be used by
142       others.
143

COPYRIGHT

145       Copyright © 2014, Tony Crisci.
146
147       This work is made available under the GNU Lesser General Public License
148       3.0.
149
150
151
152playerctl 2.0.2                   March 2019                      PLAYERCTL(1)