Playerctl.Player¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`new` (player_name)
class	`new_for_source` (player_name, source)
class	`new_from_name` (player_name)
	`get_album` ()
	`get_artist` ()
	`get_position` ()
	`get_title` ()
	`next` ()
	`on` (event, callback)
	`open` (uri)
	`pause` ()
	`play` ()
	`play_pause` ()
	`previous` ()
	`print_metadata_prop` (property)
	`seek` (offset)
	`set_loop_status` (status)
	`set_position` (position)
	`set_shuffle` (shuffle)
	`set_volume` (volume)
	`stop` ()

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

Name	Type	Flags	Short Description
`can-control`	`bool`	r	Whether the player can be controlled by playerctl
`can-go-next`	`bool`	r	Whether the player can go to the next track
`can-go-previous`	`bool`	r	Whether the player can go to the previous track
`can-pause`	`bool`	r	Whether the player can pause
`can-play`	`bool`	r	Whether the player can start playing and has a current track.
`can-seek`	`bool`	r	Whether the position of the player can be controlled
`loop-status`	`Playerctl.LoopStatus`	r	The loop status of the player
`metadata`	`GLib.Variant`	r	The metadata of the currently playing track as an array of key-value pairs. The metadata available depends on the track, but may include the artist, title, length, art url, and other metadata.
`playback-status`	`Playerctl.PlaybackStatus`	r	Whether the player is playing, paused, or stopped
`player-instance`	`str`	r/w/co	An instance name that identifies this player on the source
`player-name`	`str`	r/w/co	The name of the type of player this is. The instance is fully qualified with the player-instance and the source.
`position`	`int`	r	The position in the current track of the player in microseconds
`shuffle`	`bool`	r	A value of false indicates that playback is progressing linearly through a playlist, while true means playback is progressing through a playlist in some other order.
`source`	`Playerctl.Source`	r/w/co	The source of this player. Currently supported sources are the DBus session bus and DBus system bus.
`status`	`str`	d/r	The play status of the player (deprecated: use playback-status) `deprecated`
`volume`	`float`	r/w	The volume level of the player. Setting this property directly is deprecated and this property will become read only in a future version. Use `Playerctl.Player.set_volume`() to set the volume.

Signals¶

Inherited:: GObject.Object (1)

Name	Short Description
`exit`	Emitted when the player has disconnected and will no longer respond to queries and commands.
`loop-status`	Emitted when the loop status changes.
`metadata`	Emitted when the metadata for the currently playing track changes.
`pause`	Emitted when the player pauses. `deprecated`
`play`	Emitted when the player begins to play. `deprecated`
`playback-status`	Emitted when the playback status changes.
`seeked`	Emitted when the track changes position unexpectedly or begins in a position other than the beginning.
`shuffle`	Emitted when the shuffle status changes.
`stop`	Emitted when the player stops. `deprecated`
`volume`	Emitted when the volume of the player changes.

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent_instance	`GObject.Object`	r

Class Details¶

class Playerctl.Player(**kwargs)¶

Bases:: GObject.Object
Abstract:: No
Structure:: Playerctl.PlayerClass

classmethod new(player_name)¶

Parameters:: player_name (str or None) – The name to use to find the bus name of the player
Raises:: GLib.Error
Returns:: A new Playerctl.Player connected to an instance of the player or None if an error occurred
Return type:: Playerctl.Player

Allocates a new Playerctl.Player and tries to connect to an instance of the player with the given name.

classmethod new_for_source(player_name, source)¶

Parameters:

player_name (str or None) – The name to use to find the bus name of the player
source (Playerctl.Source) – The source where the player name is.

Raises:

GLib.Error

Returns:

A new Playerctl.Player connected to an instance of the player or None if an error occurred

Return type:

Playerctl.Player

Allocates a new Playerctl.Player and tries to connect to an instance of the player with the given name from the given source.

classmethod new_from_name(player_name)¶

Parameters:: player_name (Playerctl.PlayerName) – The name type to use to find the player
Raises:: GLib.Error
Returns:: A new Playerctl.Player connected to the player or None if an error occurred
Return type:: Playerctl.Player

Allocates a new Playerctl.Player and tries to connect to the player identified by the Playerctl.PlayerName.

get_album()¶

Raises:: GLib.Error
Returns:: The album from the metadata of the current track
Return type:: str

Gets the album from the metadata of the current track, or None if no track is playing.

get_artist()¶

Raises:: GLib.Error
Returns:: The artist from the metadata of the current track
Return type:: str

Gets the artist from the metadata of the current track, or None if no track is playing.

get_position()¶

Raises:: GLib.Error
Return type:: int

Gets the position of the current track in microseconds ignoring the property cache.

get_title()¶

Raises:: GLib.Error
Returns:: The title from the metadata of the current track
Return type:: str

Gets the title from the metadata of the current track, or None if no track is playing.

next()¶

Raises:: GLib.Error

Command the player to go to the next track

on(event, callback)¶

Parameters:

event (str) – the event to subscribe to
callback (GObject.Closure) – the callback to run on the event

Raises:

GLib.Error

A convenience function for bindings to subscribe to an event with a callback

Deprecated since version 2.0.0: Use GObject.Object.connect() to listen to events.

open(uri)¶

Parameters:: uri (str) – the URI to open, either a file name or an external URL
Raises:: GLib.Error

Command the player to open given URI

pause()¶

Raises:: GLib.Error

Command the player to pause

play()¶

Raises:: GLib.Error

Command the player to play

play_pause()¶

Raises:: GLib.Error

Command the player to play if it is paused or pause if it is playing

previous()¶

Raises:: GLib.Error

Command the player to go to the previous track

print_metadata_prop(property)¶

Parameters:: property (str or None) – the property from the metadata to print
Raises:: GLib.Error
Returns:: The artist from the metadata of the current track
Return type:: str

Gets the given property from the metadata of the current track. If property is null, prints all the metadata properties. Returns None if no track is playing.

seek(offset)¶

Parameters:: offset (int) – the offset to seek forward to in microseconds
Raises:: GLib.Error

Command the player to seek forward by offset given in microseconds.

set_loop_status(status)¶

Parameters:: status (Playerctl.LoopStatus) – the requested Playerctl.LoopStatus to set the player to
Raises:: GLib.Error

Set the loop status of the player. Can be set to either None, Track, or Playlist.

set_position(position)¶

Parameters:: position (int) – The absolute position in the track to set as the position
Raises:: GLib.Error

Sets the absolute position of the current track to the given position in microseconds.

set_shuffle(shuffle)¶

Parameters:: shuffle (bool) – whether to enable shuffle
Raises:: GLib.Error

Request to set the shuffle state of the player, either on or off.

set_volume(volume)¶

Parameters:: volume (float) – the volume level from 0.0 to 1.0
Raises:: GLib.Error

Sets the volume level for the player from 0.0 for no volume to 1.0 for maximum volume. Passing negative numbers should set the volume to 0.0.

stop()¶

Raises:: GLib.Error

Command the player to stop

Signal Details¶

Playerctl.Player.signals.exit(player)¶

Signal Name:: exit
Flags:: RUN_FIRST
Parameters:: player (Playerctl.Player) – The object which received the signal

Emitted when the player has disconnected and will no longer respond to queries and commands.

Playerctl.Player.signals.loop_status(player, loop_status)¶

Signal Name:

loop-status

Flags:

RUN_FIRST, DETAILED

Parameters:

player (Playerctl.Player) – The object which received the signal
loop_status (Playerctl.LoopStatus) – the loop status of the player

Emitted when the loop status changes.

Playerctl.Player.signals.metadata(player, metadata)¶

Signal Name:

metadata

Flags:

RUN_FIRST

Parameters:

player (Playerctl.Player) – The object which received the signal
metadata (GLib.Variant) – the metadata for the currently playing track.

Emitted when the metadata for the currently playing track changes.

Playerctl.Player.signals.pause(player)¶

Signal Name:: pause
Flags:: RUN_FIRST, DEPRECATED
Parameters:: player (Playerctl.Player) – The object which received the signal

Emitted when the player pauses.

Deprecated since version 2.0.0: Use the “playback-status::paused” signal instead.

Playerctl.Player.signals.play(player)¶

Signal Name:: play
Flags:: RUN_FIRST, DEPRECATED
Parameters:: player (Playerctl.Player) – The object which received the signal

Emitted when the player begins to play.

Deprecated since version 2.0.0: Use the “playback-status::playing” signal instead.

Playerctl.Player.signals.playback_status(player, playback_status)¶

Signal Name:

playback-status

Flags:

RUN_FIRST, DETAILED

Parameters:

player (Playerctl.Player) – The object which received the signal
playback_status (Playerctl.PlaybackStatus) – the playback status of the player

Emitted when the playback status changes. Detail will be “playing”, “paused”, or “stopped” which you can listen to by connecting to the “playback-status::[STATUS]” signal.

Playerctl.Player.signals.seeked(player, position)¶

Signal Name:

seeked

Flags:

RUN_FIRST

Parameters:

player (Playerctl.Player) – The object which received the signal
position (int) – the new position in the track in microseconds.

Emitted when the track changes position unexpectedly or begins in a position other than the beginning. Otherwise, position is assumed to progress normally.

Playerctl.Player.signals.shuffle(player, shuffle_status)¶

Signal Name:

shuffle

Flags:

RUN_FIRST

Parameters:

player (Playerctl.Player) – The object which received the signal
shuffle_status (bool) – the shuffle status of the player

Emitted when the shuffle status changes.

Playerctl.Player.signals.stop(player)¶

Signal Name:: stop
Flags:: RUN_FIRST, DEPRECATED
Parameters:: player (Playerctl.Player) – The object which received the signal

Emitted when the player stops.

Deprecated since version 2.0.0: Use the “playback-status::stopped” signal instead.

Playerctl.Player.signals.volume(player, volume)¶

Signal Name:

volume

Flags:

RUN_FIRST

Parameters:

player (Playerctl.Player) – The object which received the signal
volume (float) – the volume of the player from 0 to 100.

Emitted when the volume of the player changes.

Property Details¶

Playerctl.Player.props.can_control¶

Name:: can-control
Type:: bool
Default Value:: False
Flags:: READABLE

Whether the player can be controlled by playerctl

Playerctl.Player.props.can_go_next¶

Name:: can-go-next
Type:: bool
Default Value:: False
Flags:: READABLE

Whether the player can go to the next track

Playerctl.Player.props.can_go_previous¶

Name:: can-go-previous
Type:: bool
Default Value:: False
Flags:: READABLE

Whether the player can go to the previous track

Playerctl.Player.props.can_pause¶

Name:: can-pause
Type:: bool
Default Value:: False
Flags:: READABLE

Whether the player can pause

Playerctl.Player.props.can_play¶

Name:: can-play
Type:: bool
Default Value:: False
Flags:: READABLE

Whether the player can start playing and has a current track.

Playerctl.Player.props.can_seek¶

Name:: can-seek
Type:: bool
Default Value:: False
Flags:: READABLE

Whether the position of the player can be controlled

Playerctl.Player.props.loop_status¶

Name:: loop-status
Type:: Playerctl.LoopStatus
Default Value:: Playerctl.LoopStatus.NONE
Flags:: READABLE

The loop status of the player

Playerctl.Player.props.metadata¶

Name:: metadata
Type:: GLib.Variant
Default Value:: None
Flags:: READABLE

The metadata of the currently playing track as an array of key-value pairs. The metadata available depends on the track, but may include the artist, title, length, art url, and other metadata.

Playerctl.Player.props.playback_status¶

Name:: playback-status
Type:: Playerctl.PlaybackStatus
Default Value:: Playerctl.PlaybackStatus.STOPPED
Flags:: READABLE

Whether the player is playing, paused, or stopped

Playerctl.Player.props.player_instance¶

Name:: player-instance
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

An instance name that identifies this player on the source

Playerctl.Player.props.player_name¶

Name:: player-name
Type:: str
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The name of the type of player this is. The instance is fully qualified with the player-instance and the source.

Playerctl.Player.props.position¶

Name:: position
Type:: int
Default Value:: 0
Flags:: READABLE

The position in the current track of the player in microseconds

Playerctl.Player.props.shuffle¶

Name:: shuffle
Type:: bool
Default Value:: False
Flags:: READABLE

A value of false indicates that playback is progressing linearly through a playlist, while true means playback is progressing through a playlist in some other order.

Playerctl.Player.props.source¶

Name:: source
Type:: Playerctl.Source
Default Value:: Playerctl.Source.NONE
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

The source of this player. Currently supported sources are the DBus session bus and DBus system bus.

Playerctl.Player.props.status¶

Name:: status
Type:: str
Default Value:: None
Flags:: DEPRECATED, READABLE

The playback status of the player as a string

Deprecated since version 2.0.0: Use the “playback-status” signal instead.

Playerctl.Player.props.volume¶

Name:: volume
Type:: float
Default Value:: 0.0
Flags:: READABLE, WRITABLE

The volume level of the player. Setting this property directly is deprecated and this property will become read only in a future version. Use Playerctl.Player.set_volume() to set the volume.