PlayerctlPlayer: Playerctl Reference Manual

PlayerctlPlayer

PlayerctlPlayer — A class to control a media player.

Functions

PlayerctlPlayer *	playerctl_player_new ()
PlayerctlPlayer *	playerctl_player_new_for_source ()
PlayerctlPlayer *	playerctl_player_new_from_name ()
GList *	playerctl_list_players ()
void	playerctl_player_on ()
void	playerctl_player_open ()
void	playerctl_player_play_pause ()
void	playerctl_player_play ()
void	playerctl_player_stop ()
void	playerctl_player_seek ()
void	playerctl_player_pause ()
void	playerctl_player_next ()
void	playerctl_player_previous ()
gchar *	playerctl_player_print_metadata_prop ()
gchar *	playerctl_player_get_artist ()
gchar *	playerctl_player_get_title ()
gchar *	playerctl_player_get_album ()
void	playerctl_player_set_volume ()
gint64	playerctl_player_get_position ()
void	playerctl_player_set_position ()
void	playerctl_player_set_loop_status ()
void	playerctl_player_set_shuffle ()

Properties

gboolean	can-control	Read
gboolean	can-go-next	Read
gboolean	can-go-previous	Read
gboolean	can-pause	Read
gboolean	can-play	Read
gboolean	can-seek	Read
PlayerctlLoopStatus	loop-status	Read
GVariant *	metadata	Read
PlayerctlPlaybackStatus	playback-status	Read
char *	player-instance	Read / Write / Construct Only
char *	player-name	Read / Write / Construct Only
gint64	position	Read
gboolean	shuffle	Read
PlayerctlSource	source	Read / Write / Construct Only
char *	status	Read
double	volume	Read / Write

Signals

void	exit	Run First
void	loop-status	Has Details
void	metadata	Run First
void	pause	Run First
void	play	Run First
void	playback-status	Has Details
void	seeked	Run First
void	shuffle	Run First
void	stop	Run First
void	volume	Run First

Types and Values

enum	PlayerctlPlaybackStatus
enum	PlayerctlLoopStatus

Object Hierarchy

    GObject
    ╰── PlayerctlPlayer

Description

The PlayerctlPlayer represents a proxy connection to a media player through an IPC interface that is capable of performing commands and executing queries on the player for properties and metadata.

If you know the name of your player and that it is running, you can use playerctl_player_new() giving the player name to connect to it. The player names given are the same as you can get with the binary playerctl --list-all command. Using this function will get you the first instance of the player it can find, or the exact instance if you pass the instance as the player name.

If you would like to connect to a player dynamically, you can list players to be controlled with playerctl_list_players() or use the PlayerctlPlayerManager class and read the list of player name containers in the “player-names” property or listen to the “name-appeared” event. If you have a PlayerctlPlayerName, you can use the playerctl_player_new_from_name() function to create a PlayerctlPlayer from this name.

Once you have a player, you can give it commands to play, pause, stop, open a file, etc with the provided functions listed below. You can also query for properties such as the playback status, position, and shuffle status. Each of these has an event that will be emitted when these properties change during a main loop.

For examples on how to use the PlayerctlPlayer, see the examples directory in the git repository.

Functions

playerctl_player_new ()

PlayerctlPlayer *
playerctl_player_new (const gchar *player_name,
                      GError **err);

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

Parameters

player_name	The name to use to find the bus name of the player.	[allow-none]
err	The location of a GError or NULL

Returns

A new PlayerctlPlayer connected to an instance of the player or NULL if an error occurred.

[transfer full]

playerctl_player_new_for_source ()

PlayerctlPlayer *
playerctl_player_new_for_source (const gchar *player_name,
                                 PlayerctlSource source,
                                 GError **err);

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

Parameters

player_name	The name to use to find the bus name of the player.	[allow-none]
source	The source where the player name is.
err	The location of a GError or NULL

Returns

A new PlayerctlPlayer connected to an instance of the player or NULL if an error occurred.

[transfer full]

playerctl_player_new_from_name ()

PlayerctlPlayer *
playerctl_player_new_from_name (PlayerctlPlayerName *player_name,
                                GError **err);

Allocates a new PlayerctlPlayer and tries to connect to the player identified by the PlayerctlPlayerName.

Parameters

player_name	The name type to use to find the player
err	The location of a GError or NULL.	[allow-none]

Returns

A new PlayerctlPlayer connected to the player or NULL if an error occurred.

[transfer full]

playerctl_list_players ()

GList *
playerctl_list_players (GError **err);

Lists all the players that can be controlled by Playerctl.

Parameters

err

The location of a GError or NULL

Returns

A list of player names.

[transfer full][element-type PlayerctlPlayerName]

playerctl_player_on ()

void
playerctl_player_on (PlayerctlPlayer *self,
                     const gchar *event,
                     GClosure *callback,
                     GError **err);

playerctl_player_on has been deprecated since version 2.0.0 and should not be used in newly-written code.

Use g_object_connect() to listen to events.

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

Parameters

self	a PlayerctlPlayer
event	the event to subscribe to
callback	the callback to run on the event
err	the location of a GError or NULL.	[allow-none]

playerctl_player_open ()

void
playerctl_player_open (PlayerctlPlayer *self,
                       gchar *uri,
                       GError **err);

Command the player to open given URI

Parameters

self	a PlayerctlPlayer
uri	the URI to open, either a file name or an external URL
err	the location of a GError or NULL.	[allow-none]

playerctl_player_play_pause ()

void
playerctl_player_play_pause (PlayerctlPlayer *self,
                             GError **err);

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

Parameters

self	a PlayerctlPlayer
err	the location of a GError or NULL.	[allow-none]

playerctl_player_play ()

void
playerctl_player_play (PlayerctlPlayer *self,
                       GError **err);

Command the player to play

Parameters

self	a PlayerctlPlayer
err	the location of a GError or NULL.	[allow-none]

playerctl_player_stop ()

void
playerctl_player_stop (PlayerctlPlayer *self,
                       GError **err);

Command the player to stop

Parameters

self	a PlayerctlPlayer
err	the location of a GError or NULL.	[allow-none]

playerctl_player_seek ()

void
playerctl_player_seek (PlayerctlPlayer *self,
                       gint64 offset,
                       GError **err);

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

Parameters

self	a PlayerctlPlayer
offset	the offset to seek forward to in microseconds
err	the location of a GError or NULL.	[allow-none]

playerctl_player_pause ()

void
playerctl_player_pause (PlayerctlPlayer *self,
                        GError **err);

Command the player to pause

Parameters

self	a PlayerctlPlayer
err	the location of a GError or NULL.	[allow-none]

playerctl_player_next ()

void
playerctl_player_next (PlayerctlPlayer *self,
                       GError **err);

Command the player to go to the next track

Parameters

self	a PlayerctlPlayer
err	the location of a GError or NULL.	[allow-none]

playerctl_player_previous ()

void
playerctl_player_previous (PlayerctlPlayer *self,
                           GError **err);

Command the player to go to the previous track

Parameters

self	a PlayerctlPlayer
err	the location of a GError or NULL.	[allow-none]

playerctl_player_print_metadata_prop ()

gchar *
playerctl_player_print_metadata_prop (PlayerctlPlayer *self,
                                      const gchar *property,
                                      GError **err);

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

Parameters

self	a PlayerctlPlayer
property	the property from the metadata to print.	[allow-none]
err	the location of a GError or NULL.	[allow-none]

Returns

The artist from the metadata of the current track.

[transfer full]

playerctl_player_get_artist ()

gchar *
playerctl_player_get_artist (PlayerctlPlayer *self,
                             GError **err);

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

Parameters

self	a PlayerctlPlayer
err	the location of a GError or NULL.	[allow-none]

Returns

The artist from the metadata of the current track.

[transfer full]

playerctl_player_get_title ()

gchar *
playerctl_player_get_title (PlayerctlPlayer *self,
                            GError **err);

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

Parameters

self	a PlayerctlPlayer
err	the location of a GError or NULL.	[allow-none]

Returns

The title from the metadata of the current track.

[transfer full]

playerctl_player_get_album ()

gchar *
playerctl_player_get_album (PlayerctlPlayer *self,
                            GError **err);

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

Parameters

self	a PlayerctlPlayer
err	the location of a GError or NULL.	[allow-none]

Returns

The album from the metadata of the current track.

[transfer full]

playerctl_player_set_volume ()

void
playerctl_player_set_volume (PlayerctlPlayer *self,
                             gdouble volume,
                             GError **err);

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.

Parameters

self	a PlayerctlPlayer
volume	the volume level from 0.0 to 1.0
err	the location of a GError or NULL.	[allow-none]

playerctl_player_get_position ()

gint64
playerctl_player_get_position (PlayerctlPlayer *self,
                               GError **err);

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

Parameters

self	a PlayerctlPlayer
err	the location of a GError or NULL.	[allow-none]

playerctl_player_set_position ()

void
playerctl_player_set_position (PlayerctlPlayer *self,
                               gint64 position,
                               GError **err);

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

Parameters

self	a PlayerctlPlayer
position	The absolute position in the track to set as the position
err	the location of a GError or NULL.	[allow-none]

playerctl_player_set_loop_status ()

void
playerctl_player_set_loop_status (PlayerctlPlayer *self,
                                  PlayerctlLoopStatus status,
                                  GError **err);

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

Parameters

self	a PlayerctlPlayer
status	the requested PlayerctlLoopStatus to set the player to
err	the location of a GError or NULL.	[allow-none]

playerctl_player_set_shuffle ()

void
playerctl_player_set_shuffle (PlayerctlPlayer *self,
                              gboolean shuffle,
                              GError **err);

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

Parameters

self	a PlayerctlPlayer
shuffle	whether to enable shuffle
err	the location of a GError or NULL.	[allow-none]

Types and Values

enum PlayerctlPlaybackStatus

Playback status enumeration for a PlayerctlPlayer

Members

PLAYERCTL_PLAYBACK_STATUS_PLAYING	A track is currently playing.
PLAYERCTL_PLAYBACK_STATUS_PAUSED	A track is currently paused.
PLAYERCTL_PLAYBACK_STATUS_STOPPED	There is no track currently playing.

enum PlayerctlLoopStatus

Loop status enumeration for a PlayerctlPlayer

Members

PLAYERCTL_LOOP_STATUS_NONE	The playback will stop when there are no more tracks to play.
PLAYERCTL_LOOP_STATUS_TRACK	The current track will start again from the beginning once it has finished playing.
PLAYERCTL_LOOP_STATUS_PLAYLIST	The playback loops through a list of tracks.

Property Details

The `“can-control”` property

  “can-control”              gboolean

Whether the player can be controlled by playerctl.

Owner: PlayerctlPlayer

Flags: Read

Default value: FALSE

The `“can-go-next”` property

  “can-go-next”              gboolean

Whether the player can go to the next track.

Owner: PlayerctlPlayer

Flags: Read

Default value: FALSE

The `“can-go-previous”` property

  “can-go-previous”          gboolean

Whether the player can go to the previous track.

Owner: PlayerctlPlayer

Flags: Read

Default value: FALSE

The `“can-pause”` property

  “can-pause”                gboolean

Whether the player can pause.

Owner: PlayerctlPlayer

Flags: Read

Default value: FALSE

The `“can-play”` property

  “can-play”                 gboolean

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

Owner: PlayerctlPlayer

Flags: Read

Default value: FALSE

The `“can-seek”` property

  “can-seek”                 gboolean

Whether the position of the player can be controlled.

Owner: PlayerctlPlayer

Flags: Read

Default value: FALSE

The `“loop-status”` property

  “loop-status”              PlayerctlLoopStatus

The loop status of the player.

Owner: PlayerctlPlayer

Flags: Read

Default value: PLAYERCTL_LOOP_STATUS_NONE

The `“metadata”` property

  “metadata”                 GVariant *

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.

Owner: PlayerctlPlayer

Flags: Read

Allowed values: GVariant<a{sv}>

Default value: NULL

The `“playback-status”` property

  “playback-status”          PlayerctlPlaybackStatus

Whether the player is playing, paused, or stopped.

Owner: PlayerctlPlayer

Flags: Read

Default value: PLAYERCTL_PLAYBACK_STATUS_STOPPED

The `“player-instance”` property

  “player-instance”          char *

An instance name that identifies this player on the source.

Owner: PlayerctlPlayer

Flags: Read / Write / Construct Only

Default value: NULL

The `“player-name”` property

  “player-name”              char *

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

Owner: PlayerctlPlayer

Flags: Read / Write / Construct Only

Default value: NULL

The `“position”` property

  “position”                 gint64

The position in the current track of the player in microseconds.

Owner: PlayerctlPlayer

Flags: Read

Allowed values: >= 0

Default value: 0

The `“shuffle”` property

  “shuffle”                  gboolean

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.

Owner: PlayerctlPlayer

Flags: Read

Default value: FALSE

The `“source”` property

  “source”                   PlayerctlSource

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

Owner: PlayerctlPlayer

Flags: Read / Write / Construct Only

Default value: PLAYERCTL_SOURCE_NONE

The `“status”` property

  “status”                   char *

The playback status of the player as a string

PlayerctlPlayer:status has been deprecated since version 2.0.0 and should not be used in newly-written code.

Use the "playback-status" signal instead.

Owner: PlayerctlPlayer

Flags: Read

Default value: NULL

The `“volume”` property

  “volume”                   double

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.

Owner: PlayerctlPlayer

Flags: Read / Write

Allowed values: [0,100]

Default value: 0

Signal Details

The `“exit”` signal

void
user_function (PlayerctlPlayer *player,
               gpointer         user_data)

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

Parameters

player	the player this event was emitted on.
user_data	user data set when the signal handler was connected.

Flags: Run First

The `“loop-status”` signal

void
user_function (PlayerctlPlayer    *player,
               PlayerctlLoopStatus loop_status,
               gpointer            user_data)

Emitted when the loop status changes.

Parameters

player	the player this event was emitted on
loop_status	the loop status of the player
user_data	user data set when the signal handler was connected.

Flags: Has Details

The `“metadata”` signal

void
user_function (PlayerctlPlayer *player,
               GVariant        *metadata,
               gpointer         user_data)

Emitted when the metadata for the currently playing track changes.

Parameters

player	the player this event was emitted on
metadata	the metadata for the currently playing track.
user_data	user data set when the signal handler was connected.

Flags: Run First

The `“pause”` signal

void
user_function (PlayerctlPlayer *player,
               gpointer         user_data)

Emitted when the player pauses.

PlayerctlPlayer::pause has been deprecated since version 2.0.0 and should not be used in newly-written code.

Use the "playback-status::paused" signal instead.

Parameters

player	the player this event was emitted on
user_data	user data set when the signal handler was connected.

Flags: Run First

The `“play”` signal

void
user_function (PlayerctlPlayer *player,
               gpointer         user_data)

Emitted when the player begins to play.

PlayerctlPlayer::play has been deprecated since version 2.0.0 and should not be used in newly-written code.

Use the "playback-status::playing" signal instead.

Parameters

player	the player this event was emitted on
user_data	user data set when the signal handler was connected.

Flags: Run First

The `“playback-status”` signal

void
user_function (PlayerctlPlayer        *player,
               PlayerctlPlaybackStatus playback_status,
               gpointer                user_data)

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.

Parameters

player	the player this event was emitted on
playback_status	the playback status of the player
user_data	user data set when the signal handler was connected.

Flags: Has Details

The `“seeked”` signal

void
user_function (PlayerctlPlayer *player,
               gint64           position,
               gpointer         user_data)

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

Parameters

player	the player this event was emitted on.
position	the new position in the track in microseconds.
user_data	user data set when the signal handler was connected.

Flags: Run First

The `“shuffle”` signal

void
user_function (PlayerctlPlayer *player,
               gboolean         shuffle_status,
               gpointer         user_data)

Emitted when the shuffle status changes.

Parameters

player	the player this event was emitted on
shuffle_status	the shuffle status of the player
user_data	user data set when the signal handler was connected.

Flags: Run First

The `“stop”` signal

void
user_function (PlayerctlPlayer *player,
               gpointer         user_data)

Emitted when the player stops.

PlayerctlPlayer::stop has been deprecated since version 2.0.0 and should not be used in newly-written code.

Use the "playback-status::stopped" signal instead.

Parameters

player	the player this event was emitted on
user_data	user data set when the signal handler was connected.

Flags: Run First

The `“volume”` signal

void
user_function (PlayerctlPlayer *player,
               double           volume,
               gpointer         user_data)

Emitted when the volume of the player changes.

Parameters

player	the player this event was emitted on
volume	the volume of the player from 0 to 100.
user_data	user data set when the signal handler was connected.

Flags: Run First

PlayerctlPlayer

Functions

Properties

Signals

Types and Values

Object Hierarchy

Description

Functions

playerctl_player_new ()

Parameters

Returns

playerctl_player_new_for_source ()

Parameters

Returns

playerctl_player_new_from_name ()

Parameters

Returns

playerctl_list_players ()

Parameters

Returns

playerctl_player_on ()

Parameters

playerctl_player_open ()

Parameters

playerctl_player_play_pause ()

Parameters

playerctl_player_play ()

Parameters

playerctl_player_stop ()

Parameters

playerctl_player_seek ()

Parameters

playerctl_player_pause ()

Parameters

playerctl_player_next ()

Parameters

playerctl_player_previous ()

Parameters

playerctl_player_print_metadata_prop ()

Parameters

Returns

playerctl_player_get_artist ()

Parameters

Returns

playerctl_player_get_title ()

Parameters

Returns

playerctl_player_get_album ()

Parameters

Returns

playerctl_player_set_volume ()

Parameters

playerctl_player_get_position ()

Parameters

playerctl_player_set_position ()

Parameters

playerctl_player_set_loop_status ()

Parameters

playerctl_player_set_shuffle ()

Parameters

Types and Values

enum PlayerctlPlaybackStatus

Members

enum PlayerctlLoopStatus

Members

Property Details

The “can-control” property

The “can-go-next” property

The “can-go-previous” property

The “can-pause” property

The “can-play” property

The “can-seek” property

The “loop-status” property

The “metadata” property

The “playback-status” property

The “player-instance” property

The “player-name” property

The “position” property

The “shuffle” property

The “source” property

The `“can-control”` property

The `“can-go-next”` property

The `“can-go-previous”` property

The `“can-pause”` property

The `“can-play”` property

The `“can-seek”` property

The `“loop-status”` property

The `“metadata”` property

The `“playback-status”` property

The `“player-instance”` property

The `“player-name”` property

The `“position”` property

The `“shuffle”` property

The `“source”` property

The `“status”` property

The `“volume”` property

The `“exit”` signal

The `“loop-status”` signal

The `“metadata”` signal

The `“pause”` signal

The `“play”` signal

The `“playback-status”` signal

The `“seeked”` signal

The `“shuffle”` signal

The `“stop”` signal

The `“volume”` signal