304 lines
7.1 KiB
Groff
304 lines
7.1 KiB
Groff
.Dd @PLAYERCTL_RELEASE_DATE@
|
|
.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 .
|