playerctl

Toggle play

$ playerctl play-pause

$ playerctl next

$ playerctl previous

$ playerctl --list-all

$ playerctl --player [player_name] [play-pause|next|previous|...]

$ playerctl --all-players [play-pause|next|previous|...]

$ playerctl metadata --format "[Now playing: \{\{artist\}\} - \{\{album\}\} - \{\{title\}\]}"

playerctl [OPTIONS] [COMMAND] [ARGUMENTS]

Examples:
playerctl play
playerctl -p spotify next
playerctl metadata --format '{{artist}} - {{title}}'

--player=<player>, -p <player>
    Selects a specific media player instance by its name (e.g., 'spotify', 'vlc').

--all-players, -a
    Applies the specified command to all currently detected and running media players.

--list-all, -l
    Lists the names of all currently available and MPRIS-compliant media players.

--follow, -s
    For commands like status or metadata, keeps printing updates as changes occur.

--format <format>, -f <format>
    Specifies a Go-like template string for formatting output from metadata or status commands.

play
    Starts or resumes playback of the current media. If already playing, it does nothing.

pause
    Pauses the playback of the current media. If already paused, it does nothing.

play-pause
    Toggles the playback state between playing and paused.

stop
    Completely stops playback. This may reset the playback position.

next
    Skips to the next track or item in the current playlist.

previous
    Skips to the previous track or item in the current playlist.

status
    Prints the current playback status (e.g., 'Playing', 'Paused', 'Stopped').

metadata
    Prints detailed metadata for the current track, such as artist, title, album, and duration.

volume [level]
    Gets the current volume level, or sets it if a value (0.0 to 1.0) is provided.

position [seconds]
    Gets the current playback position in seconds, or sets it if a value is provided.

loop [status]
    Gets the current loop status, or sets it ('None', 'Track', 'Playlist').

shuffle [status]
    Gets the current shuffle status, or sets it ('On', 'Off').

playerctl is a command-line utility for controlling media players that support the Media Player Remote Interfacing Specification (MPRIS) over D-Bus. This makes it a universal tool for managing playback, volume, and track information for most modern Linux media applications like Spotify, VLC, Rhythmbox, and many others. It allows users to pause, play, skip tracks, query metadata, and adjust volume directly from the terminal or via custom keybindings and scripts.

By abstracting away the specifics of each media player, playerctl provides a consistent interface, making it invaluable for automation, desktop environment integration, and building custom media control solutions. Its reliance on D-Bus ensures seamless communication within the Linux desktop environment, providing a robust and flexible way to interact with your audio and video playback. Whether for simple one-off commands or complex scripting, playerctl empowers users with comprehensive control over their media experience.

playerctl relies entirely on the MPRIS D-Bus interface. If a media player does not implement this standard, or if the D-Bus service is not running correctly, playerctl will not be able to control it.

Furthermore, playerctl can only control players that are currently running and broadcasting their MPRIS interface. It does not launch players or manage their lifecycle beyond what the MPRIS specification allows. Ensure your player is compatible and active for playerctl to function as expected.

playerctl is ideal for custom keyboard shortcuts (e.g., assigning media keys) or integrating media control into shell scripts, status bars (like polybar, i3status), or desktop widgets.

The command's functionality is entirely dependent on the media player's MPRIS implementation. While most major players support it, some niche or older players might not.

The --format option, especially with metadata, allows for powerful customization of output using Go-like template syntax (e.g., {{artist}} - {{title}} ({{album}})), enabling precise data extraction for display or logging.

playerctl emerged to address the need for a standardized, command-line interface to control media players on Linux, bridging the gap left by more ad-hoc or player-specific control mechanisms. Leveraging the MPRIS (Media Player Remote Interfacing Specification), which became a de-facto standard for media player integration into desktop environments, playerctl provides a robust and universal solution. Its development reflects the growing desire for seamless media control in scripting, keyboard shortcuts, and custom desktop widgets, becoming an essential utility for many Linux users and developers seeking consistent media playback management.

dbus-send(1), qdbus(1), mpv(1), vlc(1)