mpris

package module
v0.10.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 30, 2026 License: MIT Imports: 6 Imported by: 4

README

GO-MPRIS

GitHub go.mod Go version GitHub Repo stars GitHub License GitHub Tag Git Commit

[!IMPORTANT] 🔥 Found this useful? A quick star goes a long way.

A Go library for DBus-MPRIS.

Features

  1. Full MPRIS 2.2 support for Base and Player interfaces (TrackList and Playlists are incomplete).
  2. Type-safe D-Bus access ensuring reliable data handling across all players.
  3. Native time.Duration usage for playback times instead of raw microseconds.
  4. Simple, high-level API for playback control, metadata, and property management.

Install

go get github.com/Nadim147c/go-mpris

The dependency github.com/godbus/dbus/v5 is going to be installed as well.

Example

Printing the current playback status and then changing it:

import (
	"log"

	"github.com/Nadim147c/go-mpris"
	"github.com/godbus/dbus/v5"
)

func main() {
	conn, err := dbus.SessionBus()
	if err != nil {
		panic(err)
	}
	names, err := mpris.List(conn)
	if err != nil {
		panic(err)
	}
	if len(names) == 0 {
		log.Fatal("No player found")
	}

	name := names[0]
	player := mpris.New(conn, name)

	status, err := player.GetPlaybackStatus()
	if err != nil {
		log.Fatal("Could not get current playback status")
	}

	log.Printf("The player was %s...", status)
	err = player.PlayPause()
	if err != nil {
		log.Fatal("Could not play/pause player")
	}
}

For more examples, see the examples folder.

Go Docs

Read the docs at https://pkg.go.dev/github.com/Nadim147c/go-mpris.

Credits

emersion and Pauloo27 for the original code.

Documentation

Index

Constants

View Source
const (
	// DBusObjectPath is the root object path for MPRIS-compatible media
	// players. All MPRIS interfaces are exposed under this path on the D-Bus.
	DBusObjectPath = "/org/mpris/MediaPlayer2"
	// PropertiesChangedSignal is the D-Bus signal name emitted when a property
	// changes on an MPRIS interface.
	PropertiesChangedSignal = "org.freedesktop.DBus.Properties.PropertiesChanged"
	// BaseInterface is the main MPRIS interface that provides general
	// information and capabilities about the media player instance.
	BaseInterface = "org.mpris.MediaPlayer2"
	// PlayerInterface defines methods and properties for controlling playback,
	// such as play, pause, seek, and retrieving track metadata.
	PlayerInterface = "org.mpris.MediaPlayer2.Player"
	// TrackListInterface provides access to the list of tracks managed by the
	// player, allowing navigation, retrieval, and management of track items.
	TrackListInterface = "org.mpris.MediaPlayer2.TrackList"
	// PlaylistsInterface defines the MPRIS interface for managing and
	// activating playlists exposed by the player.
	PlaylistsInterface = "org.mpris.MediaPlayer2.Playlists"
	// GetPropertyMethod is the standard D-Bus method used to retrieve the value
	// of a property from an interface that implements
	// org.freedesktop.DBus.Properties.
	GetPropertyMethod = "org.freedesktop.DBus.Properties.Get"
	// SetPropertyMethod is the standard D-Bus method used to change the value
	// of a writable property on an interface that implements
	// org.freedesktop.DBus.Properties.
	SetPropertyMethod = "org.freedesktop.DBus.Properties.Set"
)
View Source
const (
	// KeyAlbum is the album name.
	KeyAlbum = "xesam:album"
	// KeyAlbumArtist is the album artist(s).
	KeyAlbumArtist = "xesam:albumArtist"
	// KeyArtist is the track artist(s).
	KeyArtist = "xesam:artist"
	// KeyAsText is the text/lyrics of the track.
	KeyAsText = "xesam:asText"
	// KeyAudioBPM is the speed of the music in beats per minute.
	KeyAudioBPM = "xesam:audioBPM"
	// KeyAutoRating is an automatically generated rating (0.0 to 1.0).
	KeyAutoRating = "xesam:autoRating"
	// KeyComment is a social comment about the track.
	KeyComment = "xesam:comment"
	// KeyComposer is the track composer(s).
	KeyComposer = "xesam:composer"
	// KeyContentCreated is the date/time the content was created.
	KeyContentCreated = "xesam:contentCreated"
	// KeyDiscNumber is the disc number on the album.
	KeyDiscNumber = "xesam:discNumber"
	// KeyFirstUsed is the date/time the track was first played.
	KeyFirstUsed = "xesam:firstUsed"
	// KeyGenre is the genre(s) of the track.
	KeyGenre = "xesam:genre"
	// KeyLastUsed is the date/time the track was last played by any user.
	KeyLastUsed = "xesam:lastUsed"
	// KeyLastUsedByMe is the date/time the track was last played by the current user.
	KeyLastUsedByMe = "xesam:lastUsedByMe"
	// KeyLyricist is the person who wrote the lyrics for the track.
	KeyLyricist = "xesam:lyricist"
	// KeyTitle is the item title.
	KeyTitle = "xesam:title"
	// KeyTrackNumber is the track number on the album.
	KeyTrackNumber = "xesam:trackNumber"
	// KeyURL is the location of the media file.
	KeyURL = "xesam:url"
	// KeyUseCount is the number of times the track has been played.
	KeyUseCount = "xesam:useCount"
	// KeyUserRating is the user's rating of the track (0.0 to 1.0).
	KeyUserRating = "xesam:userRating"
	// KeyTrackID is a unique identity for the track within the context of the playlist.
	KeyTrackID = "mpris:trackid"
	// KeyLength is the duration of the track in microseconds.
	KeyLength = "mpris:length"
	// KeyArtURL is a URI of some album art designed to represent the track/album.
	KeyArtURL = "mpris:artUrl"
)

Variables

This section is empty.

Functions

func List

func List(conn *dbus.Conn) ([]string, error)

List lists the available players.

func OnSignal added in v0.9.0

func OnSignal(conn *dbus.Conn, ch chan<- *dbus.Signal) error

OnSignal adds a handler to the player's properties change signal.

Types

type LoopStatus

type LoopStatus string

LoopStatus represents the loop status of the player. It can be "None", "Track" or "Playlist".

const (
	LoopNone     LoopStatus = "None"
	LoopTrack    LoopStatus = "Track"
	LoopPlaylist LoopStatus = "Playlist"
)

type Metadata added in v0.6.0

type Metadata map[string]dbus.Variant

Metadata represents the metadata of the current track.

func (Metadata) Get added in v0.6.0

func (m Metadata) Get(key string) (any, error)

Get returns the value for the given metadata key.

func (Metadata) Has added in v0.10.0

func (m Metadata) Has(key string) bool

Has checks if the metadata key exists.

type PlaybackStatus

type PlaybackStatus string

PlaybackStatus represents the playback status. It can be "Playing", "Paused" or "Stopped".

const (
	PlaybackPlaying PlaybackStatus = "Playing"
	PlaybackPaused  PlaybackStatus = "Paused"
	PlaybackStopped PlaybackStatus = "Stopped"
)

type Player

type Player struct {
	// contains filtered or unexported fields
}

Player represents a mpris player.

func New

func New(conn *dbus.Conn, name string) *Player

New connects the the player with the name in the connection conn.

func (*Player) CanControl added in v0.5.0

func (i *Player) CanControl() (bool, error)

CanControl returns whether the player can be controlled.

func (*Player) CanEditTracks added in v0.5.0

func (i *Player) CanEditTracks() (bool, error)

CanEditTracks returns if player can edit track list

func (*Player) CanGoNext added in v0.5.0

func (i *Player) CanGoNext() (bool, error)

CanGoNext returns whether the player can skip to the next track.

func (*Player) CanGoPrevious added in v0.5.0

func (i *Player) CanGoPrevious() (bool, error)

CanGoPrevious returns whether the player can skip to the previous track.

func (*Player) CanPause added in v0.5.0

func (i *Player) CanPause() (bool, error)

CanPause returns whether the player can pause playback.

func (*Player) CanPlay added in v0.5.0

func (i *Player) CanPlay() (bool, error)

CanPlay returns whether the player can start or resume playback.

func (*Player) CanQuit added in v0.7.0

func (i *Player) CanQuit() (bool, error)

CanQuit returns whether the player can be quit.

func (*Player) CanRaise added in v0.7.0

func (i *Player) CanRaise() (bool, error)

CanRaise returns whether the player can be raised.

func (*Player) CanSeek added in v0.5.0

func (i *Player) CanSeek() (bool, error)

CanSeek returns whether the player can seek within the current track.

func (*Player) CanSetFullscreen added in v0.7.0

func (i *Player) CanSetFullscreen() (bool, error)

CanSetFullscreen returns whether the player allows changing fullscreen state.

func (*Player) GetAlbum added in v0.2.0

func (i *Player) GetAlbum() (string, error)

GetAlbum returns the current track album.

func (*Player) GetArtURL added in v0.10.0

func (i *Player) GetArtURL() (string, error)

GetArtURL returns the cover art URL of the current track.

func (*Player) GetArtist added in v0.2.0

func (i *Player) GetArtist() ([]string, error)

GetArtist returns the current track artist(s).

func (*Player) GetBaseProperty added in v0.6.0

func (i *Player) GetBaseProperty(property string) (dbus.Variant, error)

GetBaseProperty returns the prop from the base interface.

func (*Player) GetCoverURL deprecated added in v0.2.0

func (i *Player) GetCoverURL() (string, error)

GetCoverURL returns the cover art URL of the current track.

Deprecated: Use mpris.OnSignal

func (*Player) GetDesktopEntry added in v0.7.0

func (i *Player) GetDesktopEntry() (string, error)

GetDesktopEntry returns the desktop entry name of the player.

func (*Player) GetFullscreen added in v0.7.0

func (i *Player) GetFullscreen() (bool, error)

GetFullscreen returns whether the player is in fullscreen mode.

func (*Player) GetIdentity

func (i *Player) GetIdentity() (string, error)

GetIdentity returns the player identity.

func (*Player) GetLength

func (i *Player) GetLength() (time.Duration, error)

GetLength returns the current track length.

func (*Player) GetLoopStatus

func (i *Player) GetLoopStatus() (LoopStatus, error)

GetLoopStatus returns the current loop status.

func (*Player) GetMaximumRate added in v0.7.0

func (i *Player) GetMaximumRate() (float64, error)

GetMaximumRate returns the maximum playback rate.

func (*Player) GetMetadata

func (i *Player) GetMetadata() (Metadata, error)

GetMetadata returns the current track metadata.

func (*Player) GetMinimumRate added in v0.7.0

func (i *Player) GetMinimumRate() (float64, error)

GetMinimumRate returns the minimum playback rate.

func (*Player) GetName

func (i *Player) GetName() string

GetName gets the player full name.

func (*Player) GetPlaybackStatus

func (i *Player) GetPlaybackStatus() (PlaybackStatus, error)

GetPlaybackStatus returns the current playback status.

func (*Player) GetPlayerProperty

func (i *Player) GetPlayerProperty(property string) (dbus.Variant, error)

GetPlayerProperty returns the prop from the player interface.

func (*Player) GetPlaylistsProperty added in v0.6.0

func (i *Player) GetPlaylistsProperty(property string) (dbus.Variant, error)

GetPlaylistsProperty returns the prop from the playlists interface.

func (*Player) GetPosition

func (i *Player) GetPosition() (time.Duration, error)

GetPosition returns the current playback position.

func (*Player) GetProperty

func (i *Player) GetProperty(iface, property string) (dbus.Variant, error)

GetProperty returns the prop in the iface.

func (*Player) GetRate

func (i *Player) GetRate() (float64, error)

GetRate returns the current playback rate.

func (*Player) GetShuffle

func (i *Player) GetShuffle() (bool, error)

GetShuffle returns true if shuffle mode is enabled, false if playing linearly through a playlist.

func (*Player) GetSupportedUriSchemes added in v0.7.0

func (i *Player) GetSupportedUriSchemes() ([]string, error)

GetSupportedUriSchemes returns the supported URI schemes of the player.

func (*Player) GetTitle added in v0.2.0

func (i *Player) GetTitle() (string, error)

GetTitle returns the current track title.

func (*Player) GetTrackID added in v0.5.0

func (i *Player) GetTrackID() (dbus.ObjectPath, error)

GetTrackID returns track id for player as dbus.ObjectPath

func (*Player) GetTrackListProperty added in v0.6.0

func (i *Player) GetTrackListProperty(property string) (dbus.Variant, error)

GetTrackListProperty returns the prop from the tracklist interface.

func (*Player) GetURL added in v0.3.0

func (i *Player) GetURL() (string, error)

GetURL returns the URL of the current track.

func (*Player) GetVolume

func (i *Player) GetVolume() (float64, error)

GetVolume returns the current volume.

func (*Player) HasTrackList added in v0.7.0

func (i *Player) HasTrackList() (bool, error)

HasTrackList returns whether the player has a track list.

func (*Player) Next

func (i *Player) Next() error

Next skips to the next track in the tracklist.

func (*Player) OnSeeked added in v0.7.0

func (i *Player) OnSeeked(ctx context.Context, position chan<- time.Duration) error

OnSeeked listens for "Seeked" signal and sends the new position as time.Duration to position until ctx is canceled.

func (*Player) OnSignal deprecated

func (i *Player) OnSignal(ch chan<- *dbus.Signal) error

OnSignal adds a handler to the player's properties change signal.

Deprecated: Use mpris.OnSignal

func (*Player) OpenURI added in v0.5.0

func (i *Player) OpenURI(uri string) error

OpenURI opens and plays the given URI if supported.

func (*Player) OpenUri deprecated

func (i *Player) OpenUri(uri string) error

OpenUri opens and plays the given URI if supported.

Deprecated: Use OpenURI instead.

func (*Player) Pause

func (i *Player) Pause() error

Pause pauses the current track.

func (*Player) Play

func (i *Player) Play() error

Play starts or resumes playback of the current track.

func (*Player) PlayPause

func (i *Player) PlayPause() error

PlayPause resumes the current track if it's paused and pauses it if it's playing.

func (*Player) Previous

func (i *Player) Previous() error

Previous skips to the previous track in the tracklist.

func (*Player) Quit

func (i *Player) Quit() error

Quit closes the player.

func (*Player) Raise

func (i *Player) Raise() error

Raise raises player priority.

func (*Player) Seek

func (i *Player) Seek(offset time.Duration) error

Seek changes the current track position by the given offset. If the offset is negative, the playback position moves backward.

func (*Player) SetBaseProperty added in v0.6.0

func (i *Player) SetBaseProperty(property string, value any) error

SetBaseProperty sets the propertyName from the base interface.

func (*Player) SetFullscreen added in v0.7.0

func (i *Player) SetFullscreen(fullscreen bool) error

SetFullscreen sets the fullscreen state of the player.

func (*Player) SetLoopStatus

func (i *Player) SetLoopStatus(loopStatus LoopStatus) error

SetLoopStatus sets the loop status.

func (*Player) SetPlayerProperty

func (i *Player) SetPlayerProperty(property string, value any) error

SetPlayerProperty sets the propertyName from the player interface.

func (*Player) SetPlaylistsProperty added in v0.6.0

func (i *Player) SetPlaylistsProperty(property string, value any) error

SetPlaylistsProperty sets the propertyName from the playlists interface.

func (*Player) SetPosition

func (i *Player) SetPosition(position time.Duration) error

SetPosition sets the playback position of the current track.

func (*Player) SetProperty

func (i *Player) SetProperty(iface, property string, value any) error

SetProperty sets the value of a property in the interface.

func (*Player) SetRate added in v0.7.0

func (i *Player) SetRate(rate float64) error

SetRate sets the playback rate.

func (*Player) SetShuffle

func (i *Player) SetShuffle(value bool) error

SetShuffle sets the shuffle mode.

func (*Player) SetTrackListProperty added in v0.6.0

func (i *Player) SetTrackListProperty(property string, value any) error

SetTrackListProperty sets the propertyName from the tracklist interface.

func (*Player) SetTrackPosition

func (i *Player) SetTrackPosition(
	trackID *dbus.ObjectPath,
	position time.Duration,
) error

SetTrackPosition sets the playback position of a specific track.

func (*Player) SetVolume

func (i *Player) SetVolume(volume float64) error

SetVolume sets the current volume.

func (*Player) Stop

func (i *Player) Stop() error

Stop stops the current track.

func (*Player) SupportedMimeTypes added in v0.7.0

func (i *Player) SupportedMimeTypes() ([]string, error)

SupportedMimeTypes returns the supported MIME types of the player.

Directories

Path Synopsis
examples
playpause command
raise command
seeked command
signal command
volume command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL