mpris

MPRIS: media players with metadata, controls, TrackList and Playlists.

local player = mantle.mpris:map(function(mpris)
    return mpris.players[1]
end)

rect {
    on_click = function()
        local current = player:get()
        if current then
            mantle.mpris:control(current.id, "play_pause")
        end
    end,
    children = {
        text {
            max_width = 240,
            elide = "end",
            content = player:map(function(current)
                return current and (current.play_state .. ": " .. current.title) or ""
            end, ""),
        },
    },
}

State

mantle.mpris:get() returns MprisState, nil before the first push. A field marked ? may be absent.

Field	Type	Description
`players`	`PlayerState[]`	Every controllable MPRIS player except `playerctld`, longest-running first, so `players[1]` stays put; empty when none runs.

`LoopStatus`

MPRIS LoopStatus, also the set_loop_status argument.

Value	Description
`"none"`	Plays through once.
`"track"`	Repeats the current track.
`"playlist"`	Repeats the playlist.

`PlayState`

MPRIS PlaybackStatus.

One of "playing", "paused", "stopped".

`PlayerState`

Field	Type	Description
`album`	`string`	Album title; empty when unset.
`album_art_path`	`string`	Cover art as an existing local path, or empty when unavailable.
`album_artist`	`string`	Album artists joined with `", "`; empty when unset.
`art_url`	`string`	`mpris:artUrl` as sent, e.g. an `https://` image to fetch and cache; empty when unset.
`artist`	`string`	Artists joined with `", "`; empty when unset.
`can_go_next`	`boolean`	MPRIS `CanGoNext`.
`can_go_previous`	`boolean`	MPRIS `CanGoPrevious`.
`can_pause`	`boolean`	MPRIS `CanPause`.
`can_play`	`boolean`	MPRIS `CanPlay`.
`can_quit`	`boolean`	MPRIS `CanQuit` on the root interface.
`can_raise`	`boolean`	MPRIS `CanRaise` on the root interface.
`can_seek`	`boolean`	MPRIS `CanSeek`.
`desktop_entry`	`string`	The player’s `.desktop` basename, e.g. `"firefox"`, for app matching; empty when unset.
`genre`	`string`	Genres joined with `", "`; empty when unset.
`id`	`string`	Bus-name suffix after `org.mpris.MediaPlayer2.`, e.g. `"spotify"`; every action takes it.
`identity`	`string`	Display name, e.g. `"Spotify"`; empty if unanswered.
`length?`	`integer`	Track length in microseconds, or `nil` when unknown, as for a live stream.
`loop_status?`	`LoopStatus`	MPRIS loop mode; `nil` when the player does not report one.
`maximum_rate`	`number`	MPRIS maximum playback rate, or `0` when unavailable.
`minimum_rate`	`number`	MPRIS minimum playback rate, or `0` when unavailable.
`pid?`	`integer`	Process id of the bus name’s owner, which `mantle.audio.apps[].pid` matches exactly; `nil` when the bus refuses. A sandboxed app’s streams may report a pid from inside its sandbox.
`play_state`	`PlayState`	MPRIS `PlaybackStatus`; keeps the last value when a read fails, `"stopped"` if none.
`playlists`	`PlaylistsState`	One bounded page from the optional MPRIS Playlists interface.
`position?`	`integer`	Playback offset in microseconds as of `position_updated_at`, not polled while playing: add elapsed time. `nil` when unknown.
`position_updated_at`	`integer`	`CLOCK_MONOTONIC` microseconds when `position` was read: the clock of `mantle.clock:now()` in seconds, so `mantle.clock:now() - position_updated_at / 1e6` is the age.
`rate`	`number`	MPRIS playback rate.
`shuffle`	`boolean`	MPRIS shuffle setting.
`title`	`string`	Track title; empty when unset, normal between tracks.
`track_list`	`TrackListState`	Nearby tracks from the optional MPRIS TrackList interface.
`url`	`string`	`xesam:url` as sent, e.g. a `file://` path or an `https://` page; empty when unset.
`volume`	`number`	MPRIS volume in percent, `100` when unreported. The protocol permits amplification above `100`.

`PlaylistSummary`

Field	Type	Description
`icon`	`string`	Icon URI, or empty if absent.
`id`	`string`	Stable playlist object path.
`name`	`string`	User-facing playlist name.

`PlaylistsState`

Field	Type	Description
`active?`	`PlaylistSummary`	Active playlist, if the player reports one.
`count`	`integer`	Total playlists reported by the player.
`index`	`integer`	Index used for the current page.
`order`	`string`	Ordering used for the current page.
`orderings`	`string[]`	Ordering names accepted by `playlists_get`.
`page_size`	`integer`	Number of entries requested for the current page, at most 100.
`playlists`	`PlaylistSummary[]`	At most 100 playlist entries.
`reverse`	`boolean`	Whether the page is reversed.

`TrackListState`

Field	Type	Description
`can_edit`	`boolean`	Whether the player permits add and remove calls.
`current_track`	`string`	Current TrackList object path, or empty if unknown.
`tracks`	`TrackSummary[]`	At most 100 tracks around the current track; the full playlist remains player-owned.

`TrackSummary`

Field	Type	Description
`artist`	`string`	Track artists joined with `", "`.
`id`	`string`	TrackList object path, used by `track_list_go_to` and `track_list_remove_track`.
`length?`	`integer`	Track length in microseconds, or `nil` when unknown.
`title`	`string`	Track title, empty when the player has none.

Actions

Call each as mantle.mpris:<action>(arguments...); ? marks an argument you may omit.

Action	Arguments	Description
`control`	`id: string, cmd: PlayerCommand`	Sends a playback command to `players[].id`.
`seek`	`id: string, position_us: integer`	Seeks to an absolute position in microseconds, clamped to `[0, length]` (only `>= 0` when `length` is `nil`).
`seek_relative`	`id: string, offset_us: integer`	Seeks by a signed offset in microseconds, unclamped; past the end may skip to the next track.
`raise`	`id: string`	Calls Raise; check `players[].can_raise` before calling.
`quit`	`id: string`	Calls Quit; check `players[].can_quit` before calling.
`open_uri`	`id: string, uri: string`	Opens an absolute URI in the player.
`set_volume`	`id: string, value: number`	Sets MPRIS `Volume` in percent; finite values at or above zero are accepted.
`set_loop_status`	`id: string, value: LoopStatus`	Sets MPRIS `LoopStatus`.
`set_shuffle`	`id: string, value: boolean`	Sets MPRIS `Shuffle`.
`set_rate`	`id: string, value: number`	Sets a positive finite MPRIS playback rate.
`track_list_add_track`	`id: string, uri: string, after_track: string, set_as_current: boolean`	Inserts a URI after a track id, or after `/org/mpris/MediaPlayer2/TrackList/NoTrack` to prepend.
`track_list_remove_track`	`id: string, track_id: string`	Removes a track by its TrackList object path.
`track_list_go_to`	`id: string, track_id: string`	Starts the track identified by its TrackList object path.
`playlists_get`	`id: string, index: integer, count: integer, order: string, reverse: boolean`	Reads a bounded playlist page into `players[].playlists`.
`playlists_activate`	`id: string, playlist_id: string`	Activates a playlist by its object path.

`PlayerCommand`

One of "play", "pause", "play_pause", "next", "previous", "stop".

Backend

Contract	Behavior
Discovery	Session bus `ListNames` once, then `NameOwnerChanged` for `org.mpris.MediaPlayer2.*`. Skips `playerctld` and any player reporting `CanControl = false`
Pushes	On playback, metadata, control-property, TrackList or Playlists changes and on `Seeked`. A status change re-reads `Position` 100 ms later. Nothing polls
Seek	`seek` calls `SetPosition` with the cached `mpris:trackid`. A player without one gets a relative `Seek` from a live `Position` read
Controls	Read `can_*` before calling matching methods. Setters accept a finite nonnegative volume percent, positive finite rate within advertised limits, and `"none"`, `"track"`, or `"playlist"` loop status
Artwork	Uses existing local `file://` paths. Remote artwork URLs are unsupported

How do I…

Task	Answer
Show a live progress bar	Compare `position_updated_at / 1e6` with `mantle.clock:now()`, or stamp each new report in `on_change` and add the seconds since: Media player

Gotchas

Trap	Fix
`position` stands still while playing	It is the offset at `position_updated_at`, not polled. Extrapolate, as above
`position_updated_at` compared with `mantle.clock.monotonic` is off by a million	Same clock, different unit: microseconds against seconds. Divide by `1e6`; use `mantle.clock:now()` for a live reading

Keyboard shortcuts

Mantle