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