Docs
Type Reference
Quickshell.Services.Mpris
MprisPlayer

MprisPlayer: QtObject [uncreatable]

import Quickshell.Services.Mpris

A media player exposed over MPRIS. More

Properties

Functions

Detailed Description

A media player exposed over MPRIS.

⚠️
Support for various functionality and general compliance to the MPRIS specification varies wildly by player. Always check the associated canXyz and xyzSupported properties if available.
ℹ️
The TrackList and Playlist interfaces were not implemented as we could not find any media players using them to test against.

Property Details

[readonly]

canControl: bool

No details provided.

[readonly]

canGoNext: bool

No details provided.

[readonly]

canGoPrevious: bool

No details provided.

[readonly]

canPause: bool

No details provided.

[readonly]

canPlay: bool

No details provided.

[readonly]

canQuit: bool

No details provided.

[readonly]

canRaise: bool

No details provided.

[readonly]

canSeek: bool

No details provided.

[readonly]

canSetFullscreen: bool

No details provided.

[readonly]

canTogglePlaying: bool

No details provided.

[readonly]

desktopEntry: string

The name of the desktop entry for the media player, or an empty string if not provided.

fullscreen: bool

If the player is currently shown in fullscreen.

May only be written to if canSetFullscreen is true.

[readonly]

identity: string

The human readable name of the media player.

[readonly]

length: real

The length of the playing track, as seconds, with millisecond precision, or the value of position if lengthSupported is false.

[readonly]

lengthSupported: bool

No details provided.

loopState: MprisLoopState

The loop state of the media player, or None if loopSupported is false.

May only be written to if canControl and loopSupported are true.

[readonly]

loopSupported: bool

No details provided.

[readonly]

maxRate: real

No details provided.

[readonly]

metadata: unknown

Metadata of the current track.

A map of common properties is available here. Do not count on any of them actually being present.

Note that the trackTitle, trackAlbum, trackAlbumArtist, trackArtists and trackArtUrl properties have extra logic to guard against bad players sending weird metadata, and should be used over grabbing the properties directly from the metadata.

[readonly]

minRate: real

No details provided.

playbackState: MprisPlaybackState

The playback state of the media player.

  • If canPlay is false, you cannot assign the Playing state.
  • If canPause is false, you cannot assign the Paused state.
  • If canControl is false, you cannot assign the Stopped state. (or any of the others, though their repsective properties will also be false)

position: real

The current position in the playing track, as seconds, with millisecond precision, or 0 if positionSupported is false.

May only be written to if canSeek and positionSupported are true.

⚠️

To avoid excessive property updates wasting CPU while position is not actively monitored, position usually will not update reactively, unless a nonlinear change in position occurs, however reading it will always return the current position.

If you want to actively monitor the position, the simplest way it to emit the [signal] positionChanged() signal manually for the duration you are monitoring it, Using a FrameAnimation if you need the value to update smoothly, such as on a slider, or a Timer if not, as shown below.

Using a FrameAnimation
FrameAnimation {
  // only emit the signal when the position is actually changing.
  running: player.playbackState == MprisPlaybackState.Playing
  // emit the positionChanged signal every frame.
  onTriggered: player.positionChanged()
}
Using a Timer
Timer {
  // only emit the signal when the position is actually changing.
  running: player.playbackState == MprisPlaybackState.Playing
  // Make sure the position updates at least once per second.
  interval: 1000
  repeat: true
  // emit the positionChanged signal every second.
  onTriggered: player.positionChanged()
}
[readonly]

positionSupported: bool

No details provided.

rate: real

The speed the song is playing at, as a multiplier.

Only values between minRate and maxRate (inclusive) may be written to the property. Additionally, It is recommended that you only write common values such as 0.25, 0.5, 1.0, 2.0 to the property, as media players are free to ignore the value, and are more likely to accept common ones.

shuffle: bool

If the play queue is currently being shuffled, or false if shuffleSupported is false.

May only be written if canControl and shuffleSupported are true.

[readonly]

shuffleSupported: bool

No details provided.

[readonly]

supportedMimeTypes: list<string>

Mime types supported by openUri().

[readonly]

supportedUriSchemes: list<string>

Uri schemes supported by openUri().

[readonly]

trackAlbum: string

The current track’s album, or “Unknown Album” if none was provided.

[readonly]

trackAlbumArtist: string

The current track’s album artist, or “Unknown Artist” if none was provided.

[readonly]

trackArtUrl: string

The current track’s art url, or "" if none was provided.

[readonly]

trackArtists: list<string>

The current track’s artists, or an empty list if none were provided.

[readonly]

trackTitle: string

The title of the current track, or “Unknown Track” if none was provided.

[readonly]

uniqueId: int

An opaque identifier for the current track unique within the current player.

⚠️
This is NOT mpris:trackid as that is sometimes missing or nonunique in some players.

volume: real

The volume of the playing track from 0.0 to 1.0, or 1.0 if volumeSupported is false.

May only be written to if canControl and volumeSupported are true.

[readonly]

volumeSupported: bool

No details provided.

Function Details

void next()

Play the next song.

May only be called if canGoNext is true.

void openUri(uri: string)

Open the given URI in the media player.

Many players will silently ignore this, especially if the uri does not match supportedUriSchemes and supportedMimeTypes.

void pause()

Equivalent to setting playbackState to Paused.

void play()

Equivalent to setting playbackState to Playing.

void previous()

Play the previous song, or go back to the beginning of the current one.

May only be called if canGoPrevious is true.

void quit()

Quit the media player.

May only be called if canQuit is true.

void raise()

Bring the media player to the front of the window stack.

May only be called if canRaise is true.

void seek(offset: real)

Change position by an offset.

Even if positionSupported is false and you cannot set position, this function may work.

May only be called if canSeek is true.

void stop()

Equivalent to setting playbackState to Stopped.

void togglePlaying()

Equivalent to calling play() if not playing or pause() if playing.

May only be called if canTogglePlaying is true, which is equivalent to canPlay or canPause() depending on the current playback state.

MprisPlaybackState