Control Media Players

MPRIS2 (Media Player Remote Interfacing Specification) is the standard D-Bus interface for media players on Linux. Any application that plays audio or video and follows this spec — Spotify, Firefox, VLC, mpv, Chromium, Rhythmbox, and many others — exposes the same set of methods and properties on the session bus. mcdbus can talk to all of them.

How MPRIS2 works on D-Bus

Every MPRIS2 player registers a well-known service name following the pattern org.mpris.MediaPlayer2.{player}. The player object lives at /org/mpris/MediaPlayer2 and exposes the org.mpris.MediaPlayer2.Player interface with transport controls (Play, Pause, Next, Previous, Stop) and properties like Metadata, PlaybackStatus, and Volume.

Because this is a session bus service, no confirmation prompt is needed — all operations run in your user session.

Quick control with media_player_control

The fastest way to control a player is the dedicated shortcut tool. It auto-discovers MPRIS players if you do not specify one.

“Pause whatever is playing.”

Claude calls:

media_player_control(action="pause")

The tool finds the first MPRIS player on the session bus, sends the Pause command, and reports back the player name, current status, and the track that was playing.

Available actions: play, pause, play-pause, next, previous, stop.

Targeting a specific player

When multiple players are active (say Spotify and Firefox both have audio), specify the full service name:

“Skip to the next track on Spotify.”

media_player_control(action="next", player="org.mpris.MediaPlayer2.spotify")

Discovering active players

If you want to see which players are running before taking action, list session bus services and filter for the MPRIS prefix:

“What media players are running right now?”

list_services(bus="session")

Claude scans the results for service names starting with org.mpris.MediaPlayer2. and reports what it finds. Common names include:

• org.mpris.MediaPlayer2.spotify
• org.mpris.MediaPlayer2.firefox.instance_1_42
• org.mpris.MediaPlayer2.vlc
• org.mpris.MediaPlayer2.mpv

Reading playback metadata

To find out what is currently playing without changing anything, read the properties on the Player interface:

“What song is Spotify playing?”

get_all_properties(
    bus="session",
    service="org.mpris.MediaPlayer2.spotify",
    object_path="/org/mpris/MediaPlayer2",
    interface="org.mpris.MediaPlayer2.Player"
)

The response includes a property table with:

Property	What it contains
PlaybackStatus	”Playing”, “Paused”, or “Stopped”
Metadata	Dict with xesam:title, xesam:artist, xesam:album, mpris:artUrl, mpris:length
Volume	Float from 0.0 to 1.0
Position	Current playback position in microseconds
CanNext	Whether the player supports skipping forward
CanPrevious	Whether the player supports skipping backward

Example workflow

A typical conversation might go:

1. Discover players. Ask Claude to list session bus services. Claude finds org.mpris.MediaPlayer2.spotify and org.mpris.MediaPlayer2.firefox.instance_1_12.

2. Check what is playing. Ask Claude to read the Metadata and PlaybackStatus properties on the Spotify player. Claude reports the current track, artist, album, and that playback is active.

3. Skip to the next track. Ask Claude to send the Next command to Spotify. Claude calls media_player_control(action="next", player="org.mpris.MediaPlayer2.spotify") and confirms the new track.

Tip

The media_player_control tool reads metadata and status automatically after executing the action, so you get confirmation of what is now playing in a single call.

Adjusting volume

Volume is a writable property on the Player interface. To change it, use set_property:

“Set Spotify’s volume to 50%.”

set_property(
    bus="session",
    service="org.mpris.MediaPlayer2.spotify",
    object_path="/org/mpris/MediaPlayer2",
    interface="org.mpris.MediaPlayer2.Player",
    property_name="Volume",
    value="0.5",
    signature="d"
)

Note

Setting a property triggers a confirmation prompt because it mutates state. Claude will ask you to approve before the value is changed.

Going deeper with raw method calls

For actions beyond the shortcut tool — like setting the playback position, opening a specific URI, or reading the top-level org.mpris.MediaPlayer2 interface (which has properties like Identity, DesktopEntry, and SupportedMimeTypes) — use introspect to see what is available, then call_method to invoke it directly.

“Open this Spotify URI in the player.”

call_method(
    bus="session",
    service="org.mpris.MediaPlayer2.spotify",
    object_path="/org/mpris/MediaPlayer2",
    interface="org.mpris.MediaPlayer2.Player",
    method="OpenUri",
    args='["spotify:track:4PTG3Z6ehGkBFwjybzWkR8"]',
    signature="s"
)