Scroll to navigation

PLAYERCTL(1) User Commands PLAYERCTL(1)

NAME

playerctl - utility to control media players via MPRIS

SYNOPSIS

playerctl [OPTION] COMMAND

DESCRIPTION

playerctl is a command line utility to control MPRIS-enabled media players. In addition to offering play/pause/stop control, playerctl also offers previous/next track support, the ability to seek backward/forward in a track, and volume control. playerctl also supports displaying metadata (e.g. artist/title/album) for the current track, and showing the status of the player.

Players that can be controlled using playerctl include audacious, cmus, mopidy, mpd, quod libet, rhythmbox, vlc and xmms2. However, any player that implements the MPRIS interface specification should be able to be controlled using playerctl.

OPTIONS

-p, --player=NAME
The name or comma-separated list of the players to control (default: first available player)
-i, --ignore-player=NAME
The name or comma-separated list of the players to ignore
-f, --format=FORMAT
A format string for printing properties and metadata
-F, --follow=FORMAT
Block and output the updated query when it changes
-l, --list-all
List the names of running players that can be controlled
-a, --all-players
Apply command to all available players
-h, --help
Print this help, then exit
-V, --version
Print version number, then exit

COMMANDS

status
Get the current status of the player
play
Command the player to play
pause
Command the player to pause
play-pause
Command the player to toggle between play/pause
stop
Command the player to stop
next
Command the player to skip to the next track
previous
Command the player to skip to the previous track
position [OFFSET][+|-]
Print the position of the current track in seconds. With OFFSET specified, seek to OFFSET seconds from the start of the current track. With the optional [+|-] appended, seek forward/backward OFFSET seconds from the current position.
volume [LEVEL][+|-]
Print the player's volume scaled from 0.0 (0%) to 1.0 (100%). With LEVEL specified, set the player's volume to LEVEL. With the optional [+|-] appended, increase/decrease the player's volume by LEVEL.
metadata [KEY]
Print available metadata information for the current track. When KEY is specified, print the value of KEY.
open [URI]
Open the given URI in the player. The URI may be the name of a file or an external URL.
shuffle [{On|Off}]
Print the shuffle status of the player. With the shuffle status specified, set shuffle to either On or Off.
loop [{None|Track|Playlist}]
Print the loop status of the player. With the loop status specified, set the loop status to either None to not loop, Track to loop the current track, or Playlist to loop the current playlist.

FORMAT STRINGS

A format string can be given with the --format argument to print properties and metadata in a particular format. Variable names between curly braces in the form of {{ VARIABLE }} will be expanded to their values. The available variables are the names of the commands that print properties or any of the metadata keys that can be viewed with the metadata command. The name of the player is also available with the playerName variable.

Several helper functions are available in the template language to transform expanded values which can be called in the form {{ HELPER(VARIABLE) }}. The available helper functions are:

lc
Convert the value to lowercase
uc
Convert the value to uppercase
duration
When called on a duration such as position or mpris:length, convert the duration to hh:mm:ss form

EXAMPLES

To print the player name, playback status in lowercase, and position and length in human readable form:

playerctl metadata --format '{{playerName}}: {{lc(status)}} {{duration(position)}}|{{duration(mpris:length)}}'

SEE ALSO

Online API documentation: https://dubstepdish.com/playerctl
GObject Introspection language bindings: https://wiki.gnome.org/Projects/GObjectIntrospection/Users

REPORTING BUGS

Please review and report bugs to https://github.com/acrisci/playerctl/issues

AVAILABILITY

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

AUTHOR

This manual page was created by Nick Morrott <knowledgejunkie@gmail.com> for the Debian GNU/Linux system, but may be used by others.

COPYRIGHT

Copyright © 2014, Tony Crisci.
This work is made available under the GNU Lesser General Public License 3.0.
October 2018 playerctl 2.0.1