PLAYERCTL(1)

📦
version 2.4.1 · 2 versions
  • 2.4.1 · alpine 3.24, arch rolling, debian bookworm, debian trixie, epel 9, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, opensuse-leap 16.0, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute (latest)
  • 2.4.1 · ubuntu stonking
, in alpine 3.24, arch rolling, debian bookworm, debian trixie, epel 9, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, opensuse-leap 16.0, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute

💖 PLAYERCTL 💖

okay bestie, welcome to the playerctl(1) manual page, general commands section, and yes this is THE one — the little command-line baddie that runs your music 🎀

✨ NAME ✨

playerctl — control media players via MPRIS. that's it, that's the whole vibe 💅

🌸 SYNOPSIS 🌸

playerctl [-aFhlV] [-f FORMAT] [-i NAME] [-p NAME] command

🦋 DESCRIPTION 🦋

so the playerctl utility controls MPRIS-enabled media players. no cap. and it's not just play/pause/stop — it also does previous and next track, it can seek backwards and forwards inside a track, and yes queen, it does volume control. it can also show you metadata for the current track (like artist, title, album), and print the player's status. it's giving full remote control 🫶

players you can control with playerctl include audacious(1), cmus(1), mopidy(1), mpd(1), quodlibet(1), rhythmbox(1), vlc(1) and xmms2(1). BUT — and this is the iconic part — any player that implements the MPRIS interface specification works too, web browsers included. your browser is a media player now, we don't make the rules 🌈

also, playerctl ships with a daemon called playerctld that keeps track of media player activity. when playerctld is running, playerctl commands act on the media player with the most recent activity. to start the daemon, run the command playerctld daemon. main character energy fr fr 👑

the options are as follows:

  • -a, --all-players — apply the command to all available players. every single one. we're going wide 📢
  • -F, --follow — block and output the updated query when it changes. it just sits there and watches. patient king 🧚
  • -f FORMAT, --format FORMAT — set the output of the current command to FORMAT. go read "Format Strings" below, it's important 💖
  • -h, --help — print this help, then exit. bye 👋
  • -i NAME, --ignore-player NAME — ignore the specific player NAME. you can list multiple players in a comma-separated list. not you, not you, not you 🚫
  • -l, --list-all — list the names of running players that can be controlled. roll call ✨
  • -p NAME, --player NAME — control the specific player NAME. multiple players can go in a comma-separated list. defaults to the first available player. the name "name" matches both "name" and "name.{INSTANCE}". plus, the name "%any" matches any player. choose your fighter 💅
  • -s, --no-messages — silence some diagnostic and error messages. shhh 🤫
  • -V, --version — print version number, then exit.

the commands are as follows:

  • 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 and pause. the indecisive icon 🎀
  • 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 or backward OFFSET seconds from the current position. math but make it music 📐
  • 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 or decrease the player's volume by LEVEL.
  • metadata [KEY] — print all metadata properties for the current track set by the current player. if KEY is specified, only the value of KEY is printed.
  • open URI — open URI in the player. URI may be the name of a file or an external URL.
  • shuffle [On | Off | Toggle] — print the shuffle status of the player. with the shuffle status specified, set the shuffle status to either On , Off , or Toggle
  • loop [None | Track | Playlist] — print the loop status of the player. with the loop status specified, set the loop status to None (disable looping), Track (loop the current track), or Playlist (loop the current playlist). we love a repeat situation 🔁

💜 Format Strings 💜

the output of the position, metadata, status and volume commands can be controlled using a format string. variables set by these commands get included in the format string by wrapping them in curly braces: {{var}}. these then get expanded on output. obsessed ✨

each command has access to the following variables:

  • playerName — the name of the current player.
  • position — the time position of the current track, in microseconds.
  • status — the status of the current player.
  • volume — the player's volume scaled from 0.0 (0%) to 1.0 (100%).

each property listed in the metadata command is also set as a variable. highkey recommended to check this list for each player, because different players may not set the same properties. see the MPRIS v2 metadata guidelines for a list of all properties in the MPRIS specification. the most common properties are as follows:

  • album, xesam:album — the album of the current track.
  • artist, xesam:artist — the artist of the current track.
  • title, xesam:title — the title of the current track.

helper functions are also available to transform expanded variables into other representations. you call them in the form {{func(var)}}. the helper functions are as follows:

  • lc(str) — convert string str to lowercase.
  • uc(str) — convert string str to uppercase.
  • markup_escape(str) — escape XML characters in string str.
  • default(str1, str2) — print str1 if set, else print str2.
  • duration(time) — reformat the microsecond timestamp time in the form hh:mm:ss. can only be called with position or mpris:length.
  • emoji(key) — try to convert the value for key to an emoji representation. currently implemented for status and volume. 🎉
  • trunc(str, len) — truncate str to a maximum of len characters, adding an ellipsis (…) if necessary.

the template language is also able to perform basic math operations.

⚠️ references to unknown functions will cause playerctl to exit with an error. references to unknown variables will be expanded to empty strings. text not enclosed in braces will be printed verbatim. so like, be careful bestie 😭

💀 EXIT STATUS 💀

the playerctl utility exits 0 on success, and >0 if an error occurs. clean exit = slay, non-zero = something went wrong 🙈

🌟 EXAMPLES 🌟

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 👑

🎀 AUTHORS 🎀

the playerctl utility is maintained by Tony Crisci <tony@dubstepdish.com> and is made available under the GNU Lesser General Public License 3.0.

this reference was written by Nick Morrott <knowledgejunkie@gmail.com> for the Debian GNU/Linux project. it was later updated and expanded by Stephen Gregoratto <dev@sgregoratto.me>.

okay that's the whole page, you're a playerctl expert now, no cap 💖

and for the cute sign-off: this lil masterpiece came from the Debian fam, dated September 21, 2021, and it lives under the general commands manual for playerctl(1). go control some media, bestie ✨🦋🌸
📦 where this page comes from