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