.Dd September 21, 2021
.Dt PLAYERCTL 1
.Os
.Sh NAME
.Nm playerctl
.Nd control media players via MPRIS
.Sh SYNOPSIS
.Nm
.Op Fl aFhlV
.Op Fl f Ar FORMAT
.Op Fl i Ar NAME
.Op Fl p Ar NAME
.Cm command
.Sh DESCRIPTION
The
.Nm
utility controls MPRIS-enabled media players.
In addition to offering play, pause and stop control,
.Nm
also offers previous and next track support,
the ability to seek backwards and forwards in a track,
and volume control.
.Nm
also supports displaying metadata
.Pq e.g., artist, title, album
for the current track,
and showing the status of the player.
.Pp
Players that can be controlled using
.Nm
include
.Xr audacious 1 ,
.Xr cmus 1 ,
.Xr mopidy 1 ,
.Xr mpd 1 ,
.Xr quodlibet 1 ,
.Xr rhythmbox 1 ,
.Xr vlc 1
and
.Xr xmms2 1 .
However,
any player that implements the MPRIS interface specification
can be controlled using
.Nm
including web browsers.
.Pp
Playerctl also comes with a daemon called
.Nm playerctld
which keeps track of media player activity. When
.Nm playerctld
is running,
.Nm
commands will act on the media player with the most recent activity.
Run the command
.Nm playerctld daemon
to start the daemon.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl a , -all-players
Apply command to all available players.
.It Fl F , -follow
Block and output the updated query when it changes.
.It Fl f Ar FORMAT , Fl -format Ar FORMAT
Set the output of the current command to
.Ar FORMAT .
See
.Sx Format Strings .
.It Fl h , -help
Print this help, then exit.
.It Fl i Ar NAME , Fl -ignore-player Ar NAME
Ignore the specific player
.Ar NAME .
Multiple players can be specified in a comma-separated list.
.It Fl l , -list-all
List the names of running players that can be controlled.
.It Fl p Ar NAME , Fl -player Ar NAME
Control the specific player
.Ar NAME .
Multiple players can be specified in a comma-separated list.
Defaults to the first available player.
The name "name" matches both "name" and "name.{INSTANCE}".
Additionally, the name "%any" matches any player.
.It Fl s, -no-messages
Silence some diagnostic and error messages.
.It Fl V , -version
Print version number, then exit.
.El
.Pp
The commands are as follows:
.Bl -tag -width Ds
.It Cm status
Get the current status of the player.
.It Cm play
Command the player to play.
.It Cm pause
Command the player to pause.
.It Cm play-pause
Command the player to toggle between play and pause.
.It Cm stop
Command the player to stop.
.It Cm next
Command the player to skip to the next track.
.It Cm previous
Command the player to skip to the previous track.
.It Cm position Op Ar OFFSET Ns Op Ar + Ns | Ns Ar -
Print the position of the current track in seconds.
With
.Ar OFFSET
specified, seek to
.Ar OFFSET
seconds from the start of the current track.
With the optional
.Op Ar + Ns | Ns Ar -
appended,
seek forward or backward
.Ar OFFSET
seconds from the current position.
.It Cm volume Op Ar LEVEL Ns Op + Ns | Ns Ar -
Print the player's volume scaled from 0.0
.Pq 0%
to 1.0
.Pq 100% .
With
.Ar LEVEL
specified,
set the player's volume to
.Ar LEVEL .
With the optional
.Op Ar + Ns | Ns Ar -
appended,
increase or decrease the player's volume by
.Ar LEVEL .
.It Cm metadata Op Ar KEY
Print all metadata properties for the current track set by the current
player.
If
.Ar KEY
is specified only the value of
.Ar KEY
is printed.
.It Cm open Ar URI
Open
.Ar URI
in the player.
.Ar URI
may be the name of a file or an external URL.
.It Cm shuffle Op Ic On | Off | Toggle
Print the shuffle status of the player.
With the shuffle status specified,
set the shuffle status to either
.Ic On
,
.Ic Off
, or
.Ic Toggle
.It Cm loop Op Ic None | Track | Playlist
Print the loop status of the player.
With the loop status specified,
set the loop status to
.Ic None
.Pq disable looping ,
.Ic Track
.Pq loop the current track ,
or
.Ic Playlist
.Pq loop the current playlist .
.El
.Ss Format Strings
The output of the
.Cm position ,
.Cm metadata ,
.Cm status
and
.Cm volume
commands can be controlled using a format string.
Variables set by these commands can be included in the format string
by enclosing them in curly braces:
.Ql Brq Brq Va var .
These will then be expanded on output.
.Pp
Each command has access to the following variables:
.Bl -tag -width Ds
.It Va playerName
The name of the current player.
.It Va position
The time position of the current track,
in microseconds.
.It Va status
The status of the current player.
.It Va volume
The player's volume scaled from 0.0
.Pq 0%
to 1.0
.Pq 100% .
.El
.Pp
Each property listed in the
.Cm metadata
command are also set as variables.
It is recommended to check this list for each player,
as different players may not set the same properties.
See the
.%T MPRIS v2 metadata guidelines
for a list of all properties in the MPRIS specification.
The most common properties are as follows:
.Bl -tag -width Ds
.It Va album , xesam:album
The album of the current track.
.It Va artist , xesam:artist
The artist of the current track.
.It Va title , xesam:title
The title of the current track.
.El
.Pp
Helper functions are also available to transform expanded variables into
other representations.
They are called in the form
.Ql Brq Brq Fn func var .
The helper functions are as follows:
.Bl -tag -width Ds
.It Fn lc str
Convert string
.Va str
to lowercase.
.It Fn uc str
Convert string
.Va str
to uppercase.
.It Fn markup_escape str
Escape XML characters in string
.Va str .
.It Fn default str1 str2
Print
.Fa str1
if set, else print
.Fa str2 .
.It Fn duration time
Reformat the microsecond timestamp
.Va time
in the form
.Ql hh:mm:ss .
Can only be called with
.Va position
or
.Va mpris:length .
.It Fn emoji key
Try to convert the value for
.Fa key
to an emoji representation. Currently implemented for
.Fa status
and
.Fa volume .
.It Fn trunc str len
Truncate
.Fa str
to a maximum of
.Fa len
characters, adding an ellipsis (…) if necessary.
.El
.Pp
The template language is also able to perform basic math operations.
.Pp
References to unknown functions will cause
.Nm
to exit with an error.
References to unknown variables will be expanded to empty strings.
Text not enclosed in braces will be printed verbatim.
.Sh EXIT STATUS
.Ex -std
.Sh EXAMPLES
Print the player name,
playback status in lowercase,
and position and length in human readable form:
.Bd -literal -offset indent
$ playerctl metadata --format '{{playerName}}: {{lc(status)}} '\e
\&'{{duration(position)}}|{{duration(mpris:length)}}'
.Ed
.Sh SEE ALSO
.Rs
.%T MPRIS v2 metadata guidelines
.%D September 18, 2013
.%I freedesktop.org
.%U https://freedesktop.org/wiki/Specifications/mpris-spec/metadata/
.Re
.Pp
.Lk https://github.com/altdesktop/playerctl "playerctl homepage" ,
.Lk https://dubstepdish.com/playerctl "playerctl API documentation" ,
.Lk https://wiki.gnome.org/Projects/GObjectIntrospection/Users \
    "GObject introspection language bindings"
.Sh AUTHORS
.An -nosplit
The
.Nm
utility is maintained by
.An Tony Crisci Aq Mt tony@dubstepdish.com
and is made available under the GNU Lesser General Public License 3.0.
.Pp
This reference was written by
.An Nick Morrott Aq Mt knowledgejunkie@gmail.com
for the Debian GNU/Linux project.
It was later updated and expanded by
.An Stephen Gregoratto Aq Mt dev@sgregoratto.me .