{"id":13421850,"url":"https://github.com/altdesktop/playerctl","last_synced_at":"2025-05-14T22:09:13.571Z","repository":{"id":16044867,"uuid":"18788804","full_name":"altdesktop/playerctl","owner":"altdesktop","description":"🎧 mpris media player command-line controller for vlc, mpv, RhythmBox, web browsers, cmus, mpd, spotify and others.","archived":false,"fork":false,"pushed_at":"2024-06-13T16:40:00.000Z","size":683,"stargazers_count":2596,"open_issues_count":82,"forks_count":84,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-04-11T10:13:53.158Z","etag":null,"topics":["audacious","c","cli","cmus","mediaplayer","mopidy","mpd","mpris","rhythmbox","vlc"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/altdesktop.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-04-15T05:40:48.000Z","updated_at":"2025-04-10T12:47:43.000Z","dependencies_parsed_at":"2023-12-02T02:06:23.487Z","dependency_job_id":"0f3d47ab-e148-46a3-9499-3a670d858204","html_url":"https://github.com/altdesktop/playerctl","commit_stats":{"total_commits":410,"total_committers":36,"mean_commits":11.38888888888889,"dds":0.3365853658536585,"last_synced_commit":"b19a71cb9dba635df68d271bd2b3f6a99336a223"},"previous_names":["acrisci/playerctl"],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/altdesktop%2Fplayerctl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/altdesktop%2Fplayerctl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/altdesktop%2Fplayerctl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/altdesktop%2Fplayerctl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/altdesktop","download_url":"https://codeload.github.com/altdesktop/playerctl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254235701,"owners_count":22036964,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audacious","c","cli","cmus","mediaplayer","mopidy","mpd","mpris","rhythmbox","vlc"],"created_at":"2024-07-30T23:00:32.572Z","updated_at":"2025-05-14T22:09:08.559Z","avatar_url":"https://github.com/altdesktop.png","language":"C","readme":"# Playerctl\n\nFor true players only: vlc, mpv, RhythmBox, web browsers, cmus, mpd, spotify and others.\n\n[Chat](https://discord.gg/UdbXHVX)\n\n## About\n\nPlayerctl is a command-line utility and library for controlling media players that implement the [MPRIS](http://specifications.freedesktop.org/mpris-spec/latest/) D-Bus Interface Specification. Playerctl makes it easy to bind player actions, such as play and pause, to media keys. You can also get metadata about the playing track such as the artist and title for integration into statusline generators or other command-line tools.\n\nPlayerctl also comes with a daemon that allows it to act on the currently active media player called `playerctld`.\n\n## Using the CLI\n\n```\nplayerctl [--version] [--list-all] [--all-players] [--player=NAME] [--ignore-player=IGNORE] [--format=FORMAT] [--no-messages] COMMAND\n```\n\nHere is a list of available commands:\n\n| Command                      | Description                                                                                            |\n|:----------------------------:| ------------------------------------------------------------------------------------------------------ |\n| **`play`**                   | Command the player to play.                                                                            |\n| **`pause`**                  | Command the player to pause                                                                            |\n| **`play-pause`**             | Command the player to toggle between play/pause.                                                       |\n| **`stop`**                   | Command the player to stop.                                                                            |\n| **`next`**                   | Command the player to skip to the next track.                                                          |\n| **`previous`**               | Command the player to skip to the previous track.                                                      |\n| **`position [OFFSET][+/-]`** | Command the player to go to the position or seek forward or backward OFFSET in seconds.                |\n| **`volume [LEVEL][+/-]`**    | Print or set the volume to LEVEL from 0.0 to 1.0.                                                      |\n| **`status`**                 | Get the play status of the player. Either \"Playing\", \"Paused\", or \"Stopped\".                           |\n| **`metadata [KEY...]`**      | Print the metadata for the current track. If KEY is passed, print only those values from the metadata. |\n| **`open [URI]`**             | Command for the player to open a given URI. Can be either a file path or a remote URL.                 |\n| **`loop [STATUS]`**          | Print or set the loop status. Either \"None\", \"Track\", or \"Playlist\".                                   |\n| **`shuffle [STATUS]`**       | Print or set the shuffle status. Either \"On\", \"Off\".                                                   |\n\n### Selecting Players to Control\n\nWithout specifying any players to control, Playerctl will act on the first player it can find.\n\nPlayerctl comes with a service called `playerctld` that monitors the activity of media players in the background. If `playerctld` is running, Playerctl will act on players in order of their last activity. To start `playerctld`, add the following command to your system startup script:\n\n```\nplayerctld daemon\n```\n\nYou can list the names of players that are available to control that are running on the system with `playerctl --list-all`.\n\nIf you'd only like to control certain players, you can pass the names of those players separated by commas with the `--player` flag. Playerctl will select the first instance of a player in that list that supports the command. To control all players in the list, you can use the `--all-players` flag.\n\nSimilarly, you can ignore players by passing their names with the `--ignore-player` flag.\n\nThe special player name `%any` can be used in the list of selected players once to match any player not in the list. This can be used to prioritize or deprioritize players.\n\nExamples:\n\n```bash\n# Command the first instance of VLC to play\nplayerctl --player=vlc play\n\n# Command all players to stop\nplayerctl --all-players stop\n\n# Command VLC to go to the next track if it's running. If it's not, send the\n# command to Spotify.\nplayerctl --player=vlc,spotify next\n\n# Get the status of the first player that is not Gwenview.\nplayerctl --ignore-player=Gwenview status\n\n# Command any player to play, but select Chromium last\nplayerctl --player=%any,chromium play\n\n# Command any player to play, but select VLC first\nplayerctl --player=vlc,%any play\n```\n\n### Printing Properties and Metadata\n\nYou can pass a format string with the `--format` argument to print properties in a specific format. Pass the variable you want to print in the format string between double braces like `{{ VARIABLE }}`. The variables available are either the name of the query command, or anything in the metadata map which can be viewed with `playerctl metadata`. You can use this to integrate playerctl into a statusline generator.\n\nFor a simple \"now playing\" banner:\n\n```bash\nplayerctl metadata --format \"Now playing: {{ artist }} - {{ album }} - {{ title }}\"\n# prints 'Now playing: Lana Del Rey - Born To Die - Video Games'\n```\n\nIncluded in the template language are some built-in variables and helper functions for common formatting that you can call on template variables. It can also do basic math operations on numbers.\n\n```bash\n# Prints 'Total length: 3:23'\nplayerctl metadata --format \"Total length: {{ duration(mpris:length) }}\"\n\n# Prints 'At position: 1:16'\nplayerctl position --format \"At position: {{ duration(position) }}\"\n\n# Prints 'Artist in lowercase: lana del rey'\nplayerctl metadata --format \"Artist in lowercase: {{ lc(artist) }}\"\n\n# Prints 'STATUS: PLAYING'\nplayerctl status --format \"STATUS: {{ uc(status) }}\"\n\n# Prints the time remaining in the track (e.g, 'Time remaining: 2:07')\nplayerctl metadata --format \"Time remaining: {{ duration(mpris:length - position) }}\"\n\n# Prints volume from 0 - 100\nplayerctl metadata --format \"Volume: {{ volume * 100 }}\"\n```\n\n| Function        | Argument         | Description                                                        |\n| --------------- | ---------------  | ------------------------------------------------------------------ |\n| `lc`            | string           | Convert the string to lowercase.                                   |\n| `uc`            | string           | Convert the string to uppercase.                                   |\n| `duration`      | int              | Convert the duration to hh:mm:ss format.                           |\n| `markup_escape` | string           | Escape XML markup characters in the string.                        |\n| `default`       | any, any         | Print the first value if it is present, or else print the second.  |\n| `emoji`         | status or volume | Try to convert the variable to an emoji representation.            |\n| `trunc`         | string, int      | Truncate string to a maximum length.                               |\n\n| Variable     | Description                                       |\n| ------------ | ------------------------------------------------- |\n| `playerName` | The name of the current player.                   |\n| `position`   | The position of the current track in microseconds |\n| `status`     | The playback status of the current player         |\n| `volume`     | The volume from 0.0 to 1.0                        |\n| `album`      | The album of the current track.                   |\n| `artist`     | The artist of the current track.                  |\n| `title`      | The title of the current track.                   |\n\n### Following changes\n\nYou can pass the `--follow` flag to query commands to block, wait for players to connect, and print the query whenever it changes. If players are passed with `--player`, players earlier in the list will be preferred in the order they appear unless `--all-players` is passed. When no player can support the query, such as when all the players exit, a newline will be printed. For example, to be notified of information about the latest currently playing track for your media players, use:\n\n```bash\nplayerctl metadata --format '{{ playerName }}: {{ artist }} - {{ title }} {{ duration(position) }}|{{ duration(mpris:length) }}' --follow\n```\n\n### Changing the position of the track\n\nYou can seek to a position in the track or skip forward and back.\n\n```bash\n# Go back 30 seconds\nplayerctl position 30-\n\n# Go forward 30 seconds\nplayerctl position 30+\n\n# Seek to the position at 30 seconds\nplayerctl position 30\n```\n\n## Troubleshooting\n\n### Debug Logging\n\nTo enable debug logging, set the environment variable `G_MESSAGES_DEBUG=playerctl`. It's helpful to include a debug log when you report issues.\n\n### No Players Found\n\nSome players like Spotify require certain DBus environment variables to be set which are normally set within the session manager. If you're not using a session manager or it does not set these variables automatically (like `xinit`), launch your desktop environment wrapped in a `dbus-launch` command. For example, in your `.xinitrc` file, use this to start your WM:\n\n```\nexec dbus-launch --autolaunch=$(cat /var/lib/dbus/machine-id) i3\n```\n\nSome players may require installation of a plugin or other configuration.\n\nIn Quod Libet open the window File -\u003e Plugins and select the plugin called *MPRIS D-Bus Support*.\n\n### Playerctld Autostart Issues\n\nIf `playerctld` does not autostart and you use `xinit` and systemd, you might need this fix to enable DBus activation to work correctly:\n\n```\nsystemctl --user import-environment DISPLAY XAUTHORITY\n\nif which dbus-update-activation-environment \u003e/dev/null 2\u003e\u00261; then\n        dbus-update-activation-environment DISPLAY XAUTHORITY\nfi\n```\n\n## Installing\n\nFirst, check and see if Playerctl is available from your package manager (if it is not, get someone to host a package for you) and also check the [releases](https://github.com/altdesktop/playerctl/releases) page on github.\n\n### Fedora\n\n`playerctl` is available for Fedora 28 or later:\n\n```\nsudo dnf install playerctl\n```\n\n### Mageia, openSUSE\n\n`playerctl` is available for Mageia and openSUSE via [this COPR repository](https://copr.fedorainfracloud.org/coprs/jflory7/playerctl/). First, install the repository file for your distribution from COPR. Then, install `playerctl` with your package manager of choice.\n\n### Guix\n\n`playerctl` is available as a [Guix](https://guix.gnu.org) package which can be installed on any Linux distribution after [installing Guix](https://guix.gnu.org/manual/en/html_node/Installation.html):\n\n```\nguix install playerctl\n```\n\n### Compile from source\n\nUsing the cli and library requires [GLib](https://developer.gnome.org/glib/) (which is a dependency of almost all of these players as well, so you probably already have it). You can use the library in almost any programming language with the associated [introspection binding library](https://wiki.gnome.org/Projects/GObjectIntrospection/Users).\n\nAdditionally, you also need the following build dependencies:\n\n[gobject-introspection](https://wiki.gnome.org/action/show/Projects/GObjectIntrospection) for building introspection data (configurable with the `introspection` meson option)\n\n[gtk-doc](http://www.gtk.org/gtk-doc/) for building documentation (configurable with the `gtk-doc` meson option)\n\nFedora users also need to install `redhat-rpm-config`\n\nTo generate and build the project to contribute to development and install playerctl to `/`:\n\n```\nmeson mesonbuild\nsudo ninja -C mesonbuild install\n```\n\nNote that you need `meson` installed. In case your distro only has an older version of meson in its repository you can install the newest version via pip:\n\n```\npip3 install meson\n```\n\nAlso keep in mind that gtk-doc and gobject-introspection are enabled by default, you can disable them with `-Dintrospection=false` and `-Dgtk-doc=false`.\n\nIf you don't want to install playerctl to `/` you can install it elsewhere by exporting `DESTDIR` before invoking ninja, e.g.:\n\n```\nexport PREFIX=\"/usr/local\"\nmeson --prefix=\"${PREFIX}\" --libdir=\"${PREFIX}/lib\" mesonbuild\nexport DESTDIR=\"$(pwd)/install\"\nninja -C mesonbuild install\n```\n\nYou can use it later on by exporting the following variables:\n\n```\nexport LD_LIBRARY_PATH=\"$DESTDIR/${PREFIX}/lib/:$LD_LIBRARY_PATH\"\nexport GI_TYPELIB_PATH=\"$DESTDIR/${PREFIX}/lib/:$GI_TYPELIB_PATH\"\nexport PATH=\"$DESTDIR/${PREFIX}/bin:$PATH\"\n```\n\n## Using the Library\n\nTo use a scripting library, find your favorite language from [this list](https://wiki.gnome.org/Projects/GObjectIntrospection/Users) and install the bindings library. Documentation for the library is hosted [here](https://dubstepdish.com/playerctl). For examples on how to use the library, see the [examples](https://github.com/acrisci/playerctl/blob/master/examples) folder.\n\n### Example Python Script\n\nFor more advanced users, Playerctl provides an [introspectable](https://wiki.gnome.org/action/show/Projects/GObjectIntrospection) library available in your favorite scripting language that allows more detailed control like the ability to subscribe to media player events or get metadata such as artist and title for the playing track. This example uses the [Python bindings](https://wiki.gnome.org/action/show/Projects/PyGObject).\n\n```python\n#!/usr/bin/env python3\n\nfrom gi.repository import Playerctl, GLib\n\nplayer = Playerctl.Player('vlc')\n\n\ndef on_metadata(player, metadata):\n    if 'xesam:artist' in metadata.keys() and 'xesam:title' in metadata.keys():\n        print('Now playing:')\n        print('{artist} - {title}'.format(\n            artist=metadata['xesam:artist'][0], title=metadata['xesam:title']))\n\n\ndef on_play(player, status):\n    print('Playing at volume {}'.format(player.props.volume))\n\n\ndef on_pause(player, status):\n    print('Paused the song: {}'.format(player.get_title()))\n\n\nplayer.connect('playback-status::playing', on_play)\nplayer.connect('playback-status::paused', on_pause)\nplayer.connect('metadata', on_metadata)\n\n# start playing some music\nplayer.play()\n\nif player.get_artist() == 'Lana Del Rey':\n    # I meant some good music!\n    player.next()\n\n# wait for events\nmain = GLib.MainLoop()\nmain.run()\n```\n\nFor a more complete example which is capable of listening to when players start and exit, see [player-manager.py](https://github.com/acrisci/playerctl/blob/master/examples/player-manager.py) from the official examples.\n\n## Resources\n\nCheck out the following articles about Playerctl:\n\n* [2 new apps for music tweakers on Fedora Workstation - Fedora Magazine](https://fedoramagazine.org/2-new-apps-for-music-tweakers-on-fedora-workstation/ \"2 new apps for music tweakers on Fedora Workstation\")\n* [Playerctl at Version 2.0](https://dubstepdish.com/index.php/2018/10/21/playerctl-at-version-2-0/)\n\nRelated projects from the maker of Playerctl:\n\n* [altdesktop/python-dbus-next](https://github.com/altdesktop/python-dbus-next) - The DBus library used in the Playerctl test suite.\n* [altdesktop/playerbm](https://github.com/altdesktop/playerbm) - A CLI bookmark utility for audiobooks and podcasts.\n* [dbusjs/mpris-service](https://github.com/dbusjs/mpris-service) - MPRIS implementation for JavaScript targeting Electron apps.\n\n## License\n\nThis work is available under the GNU Lesser General Public License (See COPYING).\n\nCopyright © 2014, Tony Crisci\n","funding_links":[],"categories":["Dependencies","C","Installation"],"sub_categories":["Program List"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faltdesktop%2Fplayerctl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faltdesktop%2Fplayerctl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faltdesktop%2Fplayerctl/lists"}