This is the documentation for the latest (main) development branch of Zephyr. If you are looking for the documentation of previous releases, use the drop-down list at the bottom of the left panel and select the desired version.

Bluetooth Media

API Reference

Media Control Service

group bt_mcs

Media Control Service (MCS)

Definitions and types related to the Media Control Service and Media Control Profile specifications.

Since: 3.0
Version: 0.8.0

Playback speeds

The playback speed (s) is calculated by the value of 2 to the power of p divided by 64.

All values from -128 to 127 allowed, only some examples defined.

BT_MCS_PLAYBACK_SPEED_MIN: Minimum playback speed, resulting in 25 % speed.

BT_MCS_PLAYBACK_SPEED_QUARTER: Quarter playback speed, resulting in 25 % speed.

BT_MCS_PLAYBACK_SPEED_HALF: Half playback speed, resulting in 50 % speed.

BT_MCS_PLAYBACK_SPEED_UNITY: Unity playback speed, resulting in 100 % speed.

BT_MCS_PLAYBACK_SPEED_DOUBLE: Double playback speed, resulting in 200 % speed.

BT_MCS_PLAYBACK_SPEED_MAX: Max playback speed, resulting in 395.7 % speed (nearly 400 %)

Seeking speed

The allowed values for seeking speed are the range -64 to -4 (endpoints included), the value 0, and the range 4 to 64 (endpoints included).

BT_MCS_SEEKING_SPEED_FACTOR_MAX: Maximum seeking speed - Can be negated.

BT_MCS_SEEKING_SPEED_FACTOR_MIN: Minimum seeking speed - Can be negated.

BT_MCS_SEEKING_SPEED_FACTOR_ZERO: No seeking.

Playing orders

BT_MCS_PLAYING_ORDER_SINGLE_ONCE: A single track is played once; there is no next track.

BT_MCS_PLAYING_ORDER_SINGLE_REPEAT: A single track is played repeatedly; the next track is the current track.

BT_MCS_PLAYING_ORDER_INORDER_ONCE: The tracks within a group are played once in track order.

BT_MCS_PLAYING_ORDER_INORDER_REPEAT: The tracks within a group are played in track order repeatedly.

BT_MCS_PLAYING_ORDER_OLDEST_ONCE: The tracks within a group are played once only from the oldest first.

BT_MCS_PLAYING_ORDER_OLDEST_REPEAT: The tracks within a group are played from the oldest first repeatedly.

BT_MCS_PLAYING_ORDER_NEWEST_ONCE: The tracks within a group are played once only from the newest first.

BT_MCS_PLAYING_ORDER_NEWEST_REPEAT: The tracks within a group are played from the newest first repeatedly.

BT_MCS_PLAYING_ORDER_SHUFFLE_ONCE: The tracks within a group are played in random order once.

BT_MCS_PLAYING_ORDER_SHUFFLE_REPEAT: The tracks within a group are played in random order repeatedly.

Playing orders supported

A bitmap, in the same order as the playing orders above.

Note that playing order 1 corresponds to bit 0, and so on.

BT_MCS_PLAYING_ORDERS_SUPPORTED_SINGLE_ONCE: A single track is played once; there is no next track.

BT_MCS_PLAYING_ORDERS_SUPPORTED_SINGLE_REPEAT: A single track is played repeatedly; the next track is the current track.

BT_MCS_PLAYING_ORDERS_SUPPORTED_INORDER_ONCE: The tracks within a group are played once in track order.

BT_MCS_PLAYING_ORDERS_SUPPORTED_INORDER_REPEAT: The tracks within a group are played in track order repeatedly.

BT_MCS_PLAYING_ORDERS_SUPPORTED_OLDEST_ONCE: The tracks within a group are played once only from the oldest first.

BT_MCS_PLAYING_ORDERS_SUPPORTED_OLDEST_REPEAT: The tracks within a group are played from the oldest first repeatedly.

BT_MCS_PLAYING_ORDERS_SUPPORTED_NEWEST_ONCE: The tracks within a group are played once only from the newest first.

BT_MCS_PLAYING_ORDERS_SUPPORTED_NEWEST_REPEAT: The tracks within a group are played from the newest first repeatedly.

BT_MCS_PLAYING_ORDERS_SUPPORTED_SHUFFLE_ONCE: The tracks within a group are played in random order once.

BT_MCS_PLAYING_ORDERS_SUPPORTED_SHUFFLE_REPEAT: The tracks within a group are played in random order repeatedly.

Media states

BT_MCS_MEDIA_STATE_INACTIVE: The current track is invalid, and no track has been selected.

BT_MCS_MEDIA_STATE_PLAYING: The media player is playing the current track.

BT_MCS_MEDIA_STATE_PAUSED

The current track is paused.

The media player has a current track, but it is not being played

BT_MCS_MEDIA_STATE_SEEKING: The current track is fast forwarding or fast rewinding.

Media control point opcodes

BT_MCS_OPC_PLAY: Start playing the current track.

BT_MCS_OPC_PAUSE: Pause playing the current track.

BT_MCS_OPC_FAST_REWIND: Fast rewind the current track.

BT_MCS_OPC_FAST_FORWARD: Fast forward the current track.

BT_MCS_OPC_STOP: Stop current activity and return to the paused state and set the current track position to the start of the current track.

BT_MCS_OPC_MOVE_RELATIVE: Set a new current track position relative to the current track position.

BT_MCS_OPC_PREV_SEGMENT: Set the current track position to the starting position of the previous segment of the current track.

BT_MCS_OPC_NEXT_SEGMENT: Set the current track position to the starting position of the next segment of the current track.

BT_MCS_OPC_FIRST_SEGMENT: Set the current track position to the starting position of the first segment of the current track.

BT_MCS_OPC_LAST_SEGMENT: Set the current track position to the starting position of the last segment of the current track.

BT_MCS_OPC_GOTO_SEGMENT: Set the current track position to the starting position of the nth segment of the current track.

BT_MCS_OPC_PREV_TRACK: Set the current track to the previous track based on the playing order.

BT_MCS_OPC_NEXT_TRACK: Set the current track to the next track based on the playing order.

BT_MCS_OPC_FIRST_TRACK: Set the current track to the first track based on the playing order.

BT_MCS_OPC_LAST_TRACK: Set the current track to the last track based on the playing order.

BT_MCS_OPC_GOTO_TRACK: Set the current track to the nth track based on the playing order.

BT_MCS_OPC_PREV_GROUP: Set the current group to the previous group in the sequence of groups.

BT_MCS_OPC_NEXT_GROUP: Set the current group to the next group in the sequence of groups.

BT_MCS_OPC_FIRST_GROUP: Set the current group to the first group in the sequence of groups.

BT_MCS_OPC_LAST_GROUP: Set the current group to the last group in the sequence of groups.

BT_MCS_OPC_GOTO_GROUP: Set the current group to the nth group in the sequence of groups.

Media control point supported opcodes values

BT_MCS_OPC_SUP_PLAY: Support the Play opcode.

BT_MCS_OPC_SUP_PAUSE: Support the Pause opcode.

BT_MCS_OPC_SUP_FAST_REWIND: Support the Fast Rewind opcode.

BT_MCS_OPC_SUP_FAST_FORWARD: Support the Fast Forward opcode.

BT_MCS_OPC_SUP_STOP: Support the Stop opcode.

BT_MCS_OPC_SUP_MOVE_RELATIVE: Support the Move Relative opcode.

BT_MCS_OPC_SUP_PREV_SEGMENT: Support the Previous Segment opcode.

BT_MCS_OPC_SUP_NEXT_SEGMENT: Support the Next Segment opcode.

BT_MCS_OPC_SUP_FIRST_SEGMENT: Support the First Segment opcode.

BT_MCS_OPC_SUP_LAST_SEGMENT: Support the Last Segment opcode.

BT_MCS_OPC_SUP_GOTO_SEGMENT: Support the Goto Segment opcode.

BT_MCS_OPC_SUP_PREV_TRACK: Support the Previous Track opcode.

BT_MCS_OPC_SUP_NEXT_TRACK: Support the Next Track opcode.

BT_MCS_OPC_SUP_FIRST_TRACK: Support the First Track opcode.

BT_MCS_OPC_SUP_LAST_TRACK: Support the Last Track opcode.

BT_MCS_OPC_SUP_GOTO_TRACK: Support the Goto Track opcode.

BT_MCS_OPC_SUP_PREV_GROUP: Support the Previous Group opcode.

BT_MCS_OPC_SUP_NEXT_GROUP: Support the Next Group opcode.

BT_MCS_OPC_SUP_FIRST_GROUP: Support the First Group opcode.

BT_MCS_OPC_SUP_LAST_GROUP: Support the Last Group opcode.

BT_MCS_OPC_SUP_GOTO_GROUP: Support the Goto Group opcode.

Media control point notification result codes

BT_MCS_OPC_NTF_SUCCESS: Action requested by the opcode write was completed successfully.

BT_MCS_OPC_NTF_NOT_SUPPORTED: An invalid or unsupported opcode was used for the Media Control Point write.

BT_MCS_OPC_NTF_PLAYER_INACTIVE: The Media Player State characteristic value is Inactive when the opcode is received or the result of the requested action of the opcode results in the Media Player State characteristic being set to Inactive.

BT_MCS_OPC_NTF_CANNOT_BE_COMPLETED: The requested action of any Media Control Point write cannot be completed successfully because of a condition within the player.

Search control point type values

Reference: Media Control Service spec v1.0 section 3.20.2

BT_MCS_SEARCH_TYPE_TRACK_NAME: Search for Track Name.

BT_MCS_SEARCH_TYPE_ARTIST_NAME: Search for Artist Name.

BT_MCS_SEARCH_TYPE_ALBUM_NAME: Search for Album Name.

BT_MCS_SEARCH_TYPE_GROUP_NAME: Search for Group Name.

BT_MCS_SEARCH_TYPE_EARLIEST_YEAR: Search for Earliest Year.

BT_MCS_SEARCH_TYPE_LATEST_YEAR: Search for Latest Year.

BT_MCS_SEARCH_TYPE_GENRE: Search for Genre.

BT_MCS_SEARCH_TYPE_ONLY_TRACKS: Search for Tracks only.

BT_MCS_SEARCH_TYPE_ONLY_GROUPS: Search for Groups only.

Search notification result codes

Reference: Media Control Service spec v1.0 section 3.20.2

BT_MCS_SCP_NTF_SUCCESS: Search request was accepted; search has started.

BT_MCS_SCP_NTF_FAILURE: Search request was invalid; no search started.

Group object object types

Reference: Media Control Service spec v1.0 section 4.4.1

BT_MCS_GROUP_OBJECT_TRACK_TYPE: Group object type is track.

BT_MCS_GROUP_OBJECT_GROUP_TYPE: Group object type is group.

Defines

BT_MCS_ERR_LONG_VAL_CHANGED: A characteristic value has changed while a Read Long Value Characteristic sub-procedure is in progress.

BT_MCS_OPCODES_SUPPORTED_LEN: Media control point supported opcodes length.

SEARCH_LEN_MIN

Search control point minimum length.

At least one search control item (SCI), consisting of the length octet and the type octet. (The * parameter field may be empty.)

SEARCH_LEN_MAX: Search control point maximum length.

SEARCH_SCI_LEN_MIN

Search control point item (SCI) minimum length.

An SCI length can be as little as one byte, for an SCI that has only the type field. (The SCI len is the length of type + param.)

SEARCH_PARAM_MAX: Search parameters maximum length

Media Proxy

group bt_media_proxy

Media proxy module.

The media proxy module is the connection point between media players and media controllers.

Since: 3.0
Version: 0.8.0

A media player has (access to) media content and knows how to navigate and play this content. A media controller reads or gets information from a player and controls the player by setting player parameters and giving the player commands.

The media proxy module allows media player implementations to make themselves available to media controllers. And it allows controllers to access, and get updates from, any player.

The media proxy module allows both local and remote control of local player instances: A media controller may be a local application, or it may be a Media Control Service relaying requests from a remote Media Control Client. There may be either local or remote control, or both, or even multiple instances of each.

Playback speed parameters

All values from -128 to 127 allowed, only some defined

MEDIA_PROXY_PLAYBACK_SPEED_MIN: Minimum playback speed, resulting in 25 % speed.

MEDIA_PROXY_PLAYBACK_SPEED_QUARTER: Quarter playback speed, resulting in 25 % speed.

MEDIA_PROXY_PLAYBACK_SPEED_HALF: Half playback speed, resulting in 50 % speed.

MEDIA_PROXY_PLAYBACK_SPEED_UNITY: Unity playback speed, resulting in 100 % speed.

MEDIA_PROXY_PLAYBACK_SPEED_DOUBLE: Double playback speed, resulting in 200 % speed.

MEDIA_PROXY_PLAYBACK_SPEED_MAX: Max playback speed, resulting in 395.7 % speed (nearly 400 %)

Seeking speed factors

The allowed values for seeking speed are the range -64 to -4 (endpoints included), the value 0, and the range 4 to 64 (endpoints included).

MEDIA_PROXY_SEEKING_SPEED_FACTOR_MAX: Maximum seeking speed - Can be negated.

MEDIA_PROXY_SEEKING_SPEED_FACTOR_MIN: Minimum seeking speed - Can be negated.

MEDIA_PROXY_SEEKING_SPEED_FACTOR_ZERO: No seeking.

Playing orders

MEDIA_PROXY_PLAYING_ORDER_SINGLE_ONCE: A single track is played once; there is no next track.

MEDIA_PROXY_PLAYING_ORDER_SINGLE_REPEAT: A single track is played repeatedly; the next track is the current track.

MEDIA_PROXY_PLAYING_ORDER_INORDER_ONCE: The tracks within a group are played once in track order.

MEDIA_PROXY_PLAYING_ORDER_INORDER_REPEAT: The tracks within a group are played in track order repeatedly.

MEDIA_PROXY_PLAYING_ORDER_OLDEST_ONCE: The tracks within a group are played once only from the oldest first.

MEDIA_PROXY_PLAYING_ORDER_OLDEST_REPEAT: The tracks within a group are played from the oldest first repeatedly.

MEDIA_PROXY_PLAYING_ORDER_NEWEST_ONCE: The tracks within a group are played once only from the newest first.

MEDIA_PROXY_PLAYING_ORDER_NEWEST_REPEAT: The tracks within a group are played from the newest first repeatedly.

MEDIA_PROXY_PLAYING_ORDER_SHUFFLE_ONCE: The tracks within a group are played in random order once.

MEDIA_PROXY_PLAYING_ORDER_SHUFFLE_REPEAT: The tracks within a group are played in random order repeatedly.

Playing orders supported

A bitmap, in the same order as the playing orders above.

Note that playing order 1 corresponds to bit 0, and so on.

MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_SINGLE_ONCE: A single track is played once; there is no next track.

MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_SINGLE_REPEAT: A single track is played repeatedly; the next track is the current track.

MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_INORDER_ONCE: The tracks within a group are played once in track order.

MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_INORDER_REPEAT: The tracks within a group are played in track order repeatedly.

MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_OLDEST_ONCE: The tracks within a group are played once only from the oldest first.

MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_OLDEST_REPEAT: The tracks within a group are played from the oldest first repeatedly.

MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_NEWEST_ONCE: The tracks within a group are played once only from the newest first.

MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_NEWEST_REPEAT: The tracks within a group are played from the newest first repeatedly.

MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_SHUFFLE_ONCE: The tracks within a group are played in random order once.

MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_SHUFFLE_REPEAT: The tracks within a group are played in random order repeatedly.

Media player states

MEDIA_PROXY_STATE_INACTIVE: The current track is invalid, and no track has been selected.

MEDIA_PROXY_STATE_PLAYING: The media player is playing the current track.

MEDIA_PROXY_STATE_PAUSED

The current track is paused.

The media player has a current track, but it is not being played

MEDIA_PROXY_STATE_SEEKING: The current track is fast forwarding or fast rewinding.

MEDIA_PROXY_STATE_LAST: Used internally as the last state value.

Media player command opcodes

MEDIA_PROXY_OP_PLAY: Start playing the current track.

MEDIA_PROXY_OP_PAUSE: Pause playing the current track.

MEDIA_PROXY_OP_FAST_REWIND: Fast rewind the current track.

MEDIA_PROXY_OP_FAST_FORWARD: Fast forward the current track.

MEDIA_PROXY_OP_STOP: Stop current activity and return to the paused state and set the current track position to the start of the current track.

MEDIA_PROXY_OP_MOVE_RELATIVE: Set a new current track position relative to the current track position.

MEDIA_PROXY_OP_PREV_SEGMENT: Set the current track position to the starting position of the previous segment of the current track.

MEDIA_PROXY_OP_NEXT_SEGMENT: Set the current track position to the starting position of the next segment of the current track.

MEDIA_PROXY_OP_FIRST_SEGMENT: Set the current track position to the starting position of the first segment of the current track.

MEDIA_PROXY_OP_LAST_SEGMENT: Set the current track position to the starting position of the last segment of the current track.

MEDIA_PROXY_OP_GOTO_SEGMENT: Set the current track position to the starting position of the nth segment of the current track.

MEDIA_PROXY_OP_PREV_TRACK: Set the current track to the previous track based on the playing order.

MEDIA_PROXY_OP_NEXT_TRACK: Set the current track to the next track based on the playing order.

MEDIA_PROXY_OP_FIRST_TRACK: Set the current track to the first track based on the playing order.

MEDIA_PROXY_OP_LAST_TRACK: Set the current track to the last track based on the playing order.

MEDIA_PROXY_OP_GOTO_TRACK: Set the current track to the nth track based on the playing order.

MEDIA_PROXY_OP_PREV_GROUP: Set the current group to the previous group in the sequence of groups.

MEDIA_PROXY_OP_NEXT_GROUP: Set the current group to the next group in the sequence of groups.

MEDIA_PROXY_OP_FIRST_GROUP: Set the current group to the first group in the sequence of groups.

MEDIA_PROXY_OP_LAST_GROUP: Set the current group to the last group in the sequence of groups.

MEDIA_PROXY_OP_GOTO_GROUP: Set the current group to the nth group in the sequence of groups.

Unnamed Group

MEDIA_PROXY_OP_SUP_PLAY

Media player supported command opcodes.

Support the Play opcode

MEDIA_PROXY_OP_SUP_PAUSE: Support the Pause opcode.

MEDIA_PROXY_OP_SUP_FAST_REWIND: Support the Fast Rewind opcode.

MEDIA_PROXY_OP_SUP_FAST_FORWARD: Support the Fast Forward opcode.

MEDIA_PROXY_OP_SUP_STOP: Support the Stop opcode.

MEDIA_PROXY_OP_SUP_MOVE_RELATIVE: Support the Move Relative opcode.

MEDIA_PROXY_OP_SUP_PREV_SEGMENT: Support the Previous Segment opcode.

MEDIA_PROXY_OP_SUP_NEXT_SEGMENT: Support the Next Segment opcode.

MEDIA_PROXY_OP_SUP_FIRST_SEGMENT: Support the First Segment opcode.

MEDIA_PROXY_OP_SUP_LAST_SEGMENT: Support the Last Segment opcode.

MEDIA_PROXY_OP_SUP_GOTO_SEGMENT: Support the Goto Segment opcode.

MEDIA_PROXY_OP_SUP_PREV_TRACK: Support the Previous Track opcode.

MEDIA_PROXY_OP_SUP_NEXT_TRACK: Support the Next Track opcode.

MEDIA_PROXY_OP_SUP_FIRST_TRACK: Support the First Track opcode.

MEDIA_PROXY_OP_SUP_LAST_TRACK: Support the Last Track opcode.

MEDIA_PROXY_OP_SUP_GOTO_TRACK: Support the Goto Track opcode.

MEDIA_PROXY_OP_SUP_PREV_GROUP: Support the Previous Group opcode.

MEDIA_PROXY_OP_SUP_NEXT_GROUP: Support the Next Group opcode.

MEDIA_PROXY_OP_SUP_FIRST_GROUP: Support the First Group opcode.

MEDIA_PROXY_OP_SUP_LAST_GROUP: Support the Last Group opcode.

MEDIA_PROXY_OP_SUP_GOTO_GROUP: Support the Goto Group opcode.

Media player command result codes

MEDIA_PROXY_CMD_SUCCESS: Action requested by the opcode write was completed successfully.

MEDIA_PROXY_CMD_NOT_SUPPORTED: An invalid or unsupported opcode was used for the Media Control Point write.

MEDIA_PROXY_CMD_PLAYER_INACTIVE: The Media Player State characteristic value is Inactive when the opcode is received or the result of the requested action of the opcode results in the Media Player State characteristic being set to Inactive.

MEDIA_PROXY_CMD_CANNOT_BE_COMPLETED: The requested action of any Media Control Point write cannot be completed successfully because of a condition within the player.

Search operation type values

MEDIA_PROXY_SEARCH_TYPE_TRACK_NAME: Search for Track Name.

MEDIA_PROXY_SEARCH_TYPE_ARTIST_NAME: Search for Artist Name.

MEDIA_PROXY_SEARCH_TYPE_ALBUM_NAME: Search for Album Name.

MEDIA_PROXY_SEARCH_TYPE_GROUP_NAME: Search for Group Name.

MEDIA_PROXY_SEARCH_TYPE_EARLIEST_YEAR: Search for Earliest Year.

MEDIA_PROXY_SEARCH_TYPE_LATEST_YEAR: Search for Latest Year.

MEDIA_PROXY_SEARCH_TYPE_GENRE: Search for Genre.

MEDIA_PROXY_SEARCH_TYPE_ONLY_TRACKS: Search for Tracks only.

MEDIA_PROXY_SEARCH_TYPE_ONLY_GROUPS: Search for Groups only.

Search notification result codes

MEDIA_PROXY_SEARCH_SUCCESS: Search request was accepted; search has started.

MEDIA_PROXY_SEARCH_FAILURE: Search request was invalid; no search started.

Group object object types

MEDIA_PROXY_GROUP_OBJECT_TRACK_TYPE: Group object type is track.

MEDIA_PROXY_GROUP_OBJECT_GROUP_TYPE: Group object type is group.

Defines

MEDIA_PROXY_OPCODES_SUPPORTED_LEN: Media player supported opcodes length.

Functions

int media_proxy_ctrl_register(struct media_proxy_ctrl_cbs *ctrl_cbs)

Register a controller with the media_proxy.

Parameters:

ctrl_cbs – Callbacks to the controller

Returns:

0 if success, errno on failure

int media_proxy_ctrl_discover_player(struct bt_conn *conn)

Discover a remote media player.

Discover a remote media player instance. The remote player instance will be discovered, and accessed, using Bluetooth, via the media control client and a remote media control service. This call will start a GATT discovery of the Media Control Service on the peer, and setup handles and subscriptions.

This shall be called once before any other actions can be executed for the remote player. The remote player instance will be returned in the discover_player() callback.

Parameters:

conn – The connection to do discovery for

Returns:

0 if success, errno on failure

int media_proxy_ctrl_get_player_name(struct media_player *player)

Read Media Player Name.

Parameters:

player – Media player instance pointer

Returns:

0 if success, errno on failure.

int media_proxy_ctrl_get_icon_id(struct media_player *player)

Read Icon Object ID.

Get an ID (48 bit) that can be used to retrieve the Icon Object from an Object Transfer Service

See the Media Control Service spec v1.0 sections 3.2 and 4.1 for a description of the Icon Object.

Requires Object Transfer Service

Parameters:

player – Media player instance pointer

Returns:

0 if success, errno on failure.

int media_proxy_ctrl_get_icon_url(struct media_player *player)

Read Icon URL.

Get a URL to the media player’s icon.

Parameters:

player – Media player instance pointer

int media_proxy_ctrl_get_track_title(struct media_player *player)

Read Track Title.

Parameters:

player – Media player instance pointer

Returns:

0 if success, errno on failure.

int media_proxy_ctrl_get_track_duration(struct media_player *player)

Read Track Duration.

The duration of a track is measured in hundredths of a second.

Parameters:

player – Media player instance pointer

Returns:

0 if success, errno on failure.

int media_proxy_ctrl_get_track_position(struct media_player *player)

Read Track Position.

The position of the player (the playing position) is measured in hundredths of a second from the beginning of the track

Parameters:

player – Media player instance pointer

Returns:

0 if success, errno on failure.

int media_proxy_ctrl_set_track_position(struct media_player *player, int32_t position)

Set Track Position.

Set the playing position of the media player in the current track. The position is given in hundredths of a second, from the beginning of the track of the track for positive values, and (backwards) from the end of the track for negative values.

Parameters:

player – Media player instance pointer
position – The track position to set

Returns:

0 if success, errno on failure.

int media_proxy_ctrl_get_playback_speed(struct media_player *player)

Get Playback Speed.

The playback speed parameter is related to the actual playback speed as follows: actual playback speed = 2^(speed_parameter/64)

A speed parameter of 0 corresponds to unity speed playback (i.e. playback at “normal” speed). A speed parameter of -128 corresponds to playback at one fourth of normal speed, 127 corresponds to playback at almost four times the normal speed.

Parameters:

player – Media player instance pointer

Returns:

0 if success, errno on failure.

int media_proxy_ctrl_set_playback_speed(struct media_player *player, int8_t speed)

Set Playback Speed.

See the get_playback_speed() function for an explanation of the playback speed parameter.

Note that the media player may not support all possible values of the playback speed parameter. If the value given is not supported, and is higher than the current value, the player should set the playback speed to the next higher supported value. (And correspondingly to the next lower supported value for given values lower than the current value.)

Parameters:

player – Media player instance pointer
speed – The playback speed parameter to set

Returns:

0 if success, errno on failure.

int media_proxy_ctrl_get_seeking_speed(struct media_player *player)

Get Seeking Speed.

The seeking speed gives the speed with which the player is seeking. It is a factor, relative to real-time playback speed - a factor four means seeking happens at four times the real-time playback speed. Positive values are for forward seeking, negative values for backwards seeking.

The seeking speed is not settable - a non-zero seeking speed is the result of “fast rewind” of “fast forward” commands.

Parameters:

player – Media player instance pointer

Returns:

0 if success, errno on failure.

int media_proxy_ctrl_get_track_segments_id(struct media_player *player)

Read Current Track Segments Object ID.

Get an ID (48 bit) that can be used to retrieve the Current Track Segments Object from an Object Transfer Service

See the Media Control Service spec v1.0 sections 3.10 and 4.2 for a description of the Track Segments Object.

Requires Object Transfer Service

Parameters:

player – Media player instance pointer

Returns:

0 if success, errno on failure.

int media_proxy_ctrl_get_current_track_id(struct media_player *player)

Read Current Track Object ID.

Get an ID (48 bit) that can be used to retrieve the Current Track Object from an Object Transfer Service

See the Media Control Service spec v1.0 sections 3.11 and 4.3 for a description of the Current Track Object.

Requires Object Transfer Service

Parameters:

player – Media player instance pointer

Returns:

0 if success, errno on failure.

int media_proxy_ctrl_set_current_track_id(struct media_player *player, uint64_t id)

Set Current Track Object ID.

Change the player’s current track to the track given by the ID. (Behaves similarly to the goto track command.)

Requires Object Transfer Service

Parameters:

player – Media player instance pointer
id – The ID of a track object

Returns:

0 if success, errno on failure.

int media_proxy_ctrl_get_next_track_id(struct media_player *player)

Media Control Client

group bt_gatt_mcc

Bluetooth Media Control Client (MCC) interface.

Updated to the Media Control Profile specification revision 1.0

Since: 3.0
Version: 0.8.0

Typedefs

typedef void (*bt_mcc_discover_mcs_cb)(struct bt_conn *conn, int err)

Callback function for bt_mcc_discover_mcs()

Called when a media control server is discovered

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail

typedef void (*bt_mcc_read_player_name_cb)(struct bt_conn *conn, int err, const char *name)

Callback function for bt_mcc_read_player_name()

Called when the player name is read or notified

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param name:: Player name

typedef void (*bt_mcc_read_icon_obj_id_cb)(struct bt_conn *conn, int err, uint64_t icon_id)

Callback function for bt_mcc_read_icon_obj_id()

Called when the icon object ID is read

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param icon_id:: The ID of the Icon Object. This is a UINT48 in a uint64_t

typedef void (*bt_mcc_read_icon_url_cb)(struct bt_conn *conn, int err, const char *icon_url)

Callback function for bt_mcc_read_icon_url()

Called when the icon URL is read

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param icon_url:: The URL of the Icon

typedef void (*bt_mcc_track_changed_ntf_cb)(struct bt_conn *conn, int err)

Callback function for track changed notifications.

Called when a track change is notified.

The track changed characteristic is a special case. It can not be read or set, it can only be notified.

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail

typedef void (*bt_mcc_read_track_title_cb)(struct bt_conn *conn, int err, const char *title)

Callback function for bt_mcc_read_track_title()

Called when the track title is read or notified

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param title:: The title of the track

typedef void (*bt_mcc_read_track_duration_cb)(struct bt_conn *conn, int err, int32_t dur)

Callback function for bt_mcc_read_track_duration()

Called when the track duration is read or notified

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param dur:: The duration of the track

typedef void (*bt_mcc_read_track_position_cb)(struct bt_conn *conn, int err, int32_t pos)

Callback function for bt_mcc_read_track_position()

Called when the track position is read or notified

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param pos:: The Track Position

typedef void (*bt_mcc_set_track_position_cb)(struct bt_conn *conn, int err, int32_t pos)

Callback function for bt_mcc_set_track_position()

Called when the track position is set

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param pos:: The Track Position set (or attempted to set)

typedef void (*bt_mcc_read_playback_speed_cb)(struct bt_conn *conn, int err, int8_t speed)

Callback function for bt_mcc_read_playback_speed()

Called when the playback speed is read or notified

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param speed:: The Playback Speed

typedef void (*bt_mcc_set_playback_speed_cb)(struct bt_conn *conn, int err, int8_t speed)

Callback function for bt_mcc_set_playback_speed()

Called when the playback speed is set

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param speed:: The Playback Speed set (or attempted to set)

typedef void (*bt_mcc_read_seeking_speed_cb)(struct bt_conn *conn, int err, int8_t speed)

Callback function for bt_mcc_read_seeking_speed()

Called when the seeking speed is read or notified

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param speed:: The Seeking Speed

typedef void (*bt_mcc_read_segments_obj_id_cb)(struct bt_conn *conn, int err, uint64_t id)

Callback function for bt_mcc_read_segments_obj_id()

Called when the track segments object ID is read

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param id:: The Track Segments Object ID (UINT48)

typedef void (*bt_mcc_read_current_track_obj_id_cb)(struct bt_conn *conn, int err, uint64_t id)

Callback function for bt_mcc_read_current_track_obj_id()

Called when the current track object ID is read or notified

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param id:: The Current Track Object ID (UINT48)

typedef void (*bt_mcc_set_current_track_obj_id_cb)(struct bt_conn *conn, int err, uint64_t id)

Callback function for bt_mcc_set_current_track_obj_id()

Called when the current track object ID is set

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param id:: The Object ID (UINT48) set (or attempted to set)

typedef void (*bt_mcc_read_next_track_obj_id_cb)(struct bt_conn *conn, int err, uint64_t id)

Callback function for bt_mcc_read_next_track_obj_id_obj()

Called when the next track object ID is read or notified

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param id:: The Next Track Object ID (UINT48)

typedef void (*bt_mcc_set_next_track_obj_id_cb)(struct bt_conn *conn, int err, uint64_t id)

Callback function for bt_mcc_set_next_track_obj_id()

Called when the next track object ID is set

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param id:: The Object ID (UINT48) set (or attempted to set)

typedef void (*bt_mcc_read_parent_group_obj_id_cb)(struct bt_conn *conn, int err, uint64_t id)

Callback function for bt_mcc_read_parent_group_obj_id()

Called when the parent group object ID is read or notified

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param id:: The Parent Group Object ID (UINT48)

typedef void (*bt_mcc_read_current_group_obj_id_cb)(struct bt_conn *conn, int err, uint64_t id)

Callback function for bt_mcc_read_current_group_obj_id()

Called when the current group object ID is read or notified

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param id:: The Current Group Object ID (UINT48)

typedef void (*bt_mcc_set_current_group_obj_id_cb)(struct bt_conn *conn, int err, uint64_t obj_id)

Callback function for bt_mcc_set_current_group_obj_id()

Called when the current group object ID is set

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param obj_id:: The Object ID (UINT48) set (or attempted to set)

typedef void (*bt_mcc_read_playing_order_cb)(struct bt_conn *conn, int err, uint8_t order)

Callback function for bt_mcc_read_playing_order()

Called when the playing order is read or notified

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param order:: The playback order

typedef void (*bt_mcc_set_playing_order_cb)(struct bt_conn *conn, int err, uint8_t order)

Callback function for bt_mcc_set_playing_order()

Called when the playing order is set

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param order:: The Playing Order set (or attempted to set)

typedef void (*bt_mcc_read_playing_orders_supported_cb)(struct bt_conn *conn, int err, uint16_t orders)

Callback function for bt_mcc_read_playing_orders_supported()

Called when the supported playing orders are read or notified

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param orders:: The playing orders supported (bitmap)

typedef void (*bt_mcc_read_media_state_cb)(struct bt_conn *conn, int err, uint8_t state)

Callback function for bt_mcc_read_media_state()

Called when the media state is read or notified

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param state:: The Media State

typedef void (*bt_mcc_send_cmd_cb)(struct bt_conn *conn, int err, const struct mpl_cmd *cmd)

Callback function for bt_mcc_send_cmd()

Called when a command is sent, i.e. when the media control point is set

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param cmd:: The command sent

typedef void (*bt_mcc_cmd_ntf_cb)(struct bt_conn *conn, int err, const struct mpl_cmd_ntf *ntf)

Callback function for command notifications.

Called when the media control point is notified

Notifications for commands (i.e. for writes to the media control point) use a different parameter structure than what is used for sending commands (writing to the media control point)

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param ntf:: The command notification

typedef void (*bt_mcc_read_opcodes_supported_cb)(struct bt_conn *conn, int err, uint32_t opcodes)

Callback function for bt_mcc_read_opcodes_supported()

Called when the supported opcodes (commands) are read or notified

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param opcodes:: The supported opcodes

typedef void (*bt_mcc_send_search_cb)(struct bt_conn *conn, int err, const struct mpl_search *search)

Callback function for bt_mcc_send_search()

Called when a search is sent, i.e. when the search control point is set

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param search:: The search set (or attempted to set)

typedef void (*bt_mcc_search_ntf_cb)(struct bt_conn *conn, int err, uint8_t result_code)

Callback function for search notifications.

Called when the search control point is notified

Notifications for searches (i.e. for writes to the search control point) use a different parameter structure than what is used for sending searches (writing to the search control point)

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param result_code:: The search notification

typedef void (*bt_mcc_read_search_results_obj_id_cb)(struct bt_conn *conn, int err, uint64_t id)

Callback function for bt_mcc_read_search_results_obj_id()

Called when the search results object ID is read or notified

Note that the Search Results Object ID value may be zero, in case the characteristic does not exist on the server. (This will be the case if there has not been a successful search.)

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param id:: The Search Results Object ID (UINT48)

typedef void (*bt_mcc_read_content_control_id_cb)(struct bt_conn *conn, int err, uint8_t ccid)

Callback function for bt_mcc_read_content_control_id()

Called when the content control ID is read

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param ccid:: The Content Control ID

typedef void (*bt_mcc_otc_obj_selected_cb)(struct bt_conn *conn, int err)

Callback function for object selected.

Called when an object is selected

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail

typedef void (*bt_mcc_otc_obj_metadata_cb)(struct bt_conn *conn, int err)

Callback function for bt_mcc_otc_read_object_metadata()

Called when object metadata is read

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail

typedef void (*bt_mcc_otc_read_icon_object_cb)(struct bt_conn *conn, int err, struct net_buf_simple *buf)

Callback function for bt_mcc_otc_read_icon_object()

Called when the icon object is read

If err is EMSGSIZE, the object contents have been truncated.

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param buf:: Buffer containing the object contents

typedef void (*bt_mcc_otc_read_track_segments_object_cb)(struct bt_conn *conn, int err, struct net_buf_simple *buf)

Callback function for bt_mcc_otc_read_track_segments_object()

Called when the track segments object is read

If err is EMSGSIZE, the object contents have been truncated.

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param buf:: Buffer containing the object contents

typedef void (*bt_mcc_otc_read_current_track_object_cb)(struct bt_conn *conn, int err, struct net_buf_simple *buf)

Callback function for bt_mcc_otc_read_current_track_object()

Called when the current track object is read

If err is EMSGSIZE, the object contents have been truncated.

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param buf:: Buffer containing the object contents

typedef void (*bt_mcc_otc_read_next_track_object_cb)(struct bt_conn *conn, int err, struct net_buf_simple *buf)

Callback function for bt_mcc_otc_read_next_track_object()

Called when the next track object is read

If err is EMSGSIZE, the object contents have been truncated.

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param buf:: Buffer containing the object contents

typedef void (*bt_mcc_otc_read_parent_group_object_cb)(struct bt_conn *conn, int err, struct net_buf_simple *buf)

Callback function for bt_mcc_otc_read_parent_group_object()

Called when the parent group object is read

If err is EMSGSIZE, the object contents have been truncated.

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param buf:: Buffer containing the object contents

typedef void (*bt_mcc_otc_read_current_group_object_cb)(struct bt_conn *conn, int err, struct net_buf_simple *buf)

Callback function for bt_mcc_otc_read_current_group_object()

Called when the current group object is read

If err is EMSGSIZE, the object contents have been truncated.

Param conn:: The connection that was used to initialise the media control client
Param err:: Error value. 0 on success, GATT error or errno on fail
Param buf:: Buffer containing the object contents

Functions

int bt_mcc_init(struct bt_mcc_cb *cb)

Initialize Media Control Client.

Parameters:

cb – Callbacks to be used

Returns:

0 if success, errno on failure.

int bt_mcc_discover_mcs(struct bt_conn *conn, bool subscribe)

Discover Media Control Service.

Discover Media Control Service (MCS) on the server given by the connection Optionally subscribe to notifications.

Shall be called once, after media control client initialization and before using other media control client functionality.

Parameters:

conn – Connection to the peer device
subscribe – Whether to subscribe to notifications

Returns:

0 if success, errno on failure.

int bt_mcc_read_player_name(struct bt_conn *conn)

Read Media Player Name.

Parameters:

conn – Connection to the peer device

Returns:

0 if success, errno on failure.

int bt_mcc_read_icon_obj_id(struct bt_conn *conn)

Read Icon Object ID.

Parameters:

conn – Connection to the peer device

Returns:

0 if success, errno on failure.

int bt_mcc_read_icon_url(struct bt_conn *conn)

Read Icon Object URL.

Parameters:

conn – Connection to the peer device

Returns:

0 if success, errno on failure.

int bt_mcc_read_track_title(struct bt_conn *conn)

Read Track Title.

Parameters:

conn – Connection to the peer device

Returns:

0 if success, errno on failure.

int bt_mcc_read_track_duration(struct bt_conn *conn)

Read Track Duration.

Parameters:

conn – Connection to the peer device

Returns:

0 if success, errno on failure.

int bt_mcc_read_track_position(struct bt_conn *conn)

Read Track Position.

Parameters:

conn – Connection to the peer device

Returns:

0 if success, errno on failure.

int bt_mcc_set_track_position(struct bt_conn *conn, int32_t pos)

Set Track position.

Parameters:

conn – Connection to the peer device
pos – Track position

Returns:

0 if success, errno on failure.

int bt_mcc_read_playback_speed(struct bt_conn *conn)

Read Playback speed.

Parameters:

conn – Connection to the peer device

Returns:

0 if success, errno on failure.

int bt_mcc_set_playback_speed(struct bt_conn *conn, int8_t speed)

Set Playback Speed.

Parameters:

conn – Connection to the peer device
speed – Playback speed

Returns:

0 if success, errno on failure.

int bt_mcc_read_seeking_speed(struct bt_conn *conn)

Read Seeking speed.

Parameters:

conn – Connection to the peer device

Returns:

0 if success, errno on failure.

int bt_mcc_read_segments_obj_id(struct bt_conn *conn)

Read Track Segments Object ID.

Parameters:

conn – Connection to the peer device

Returns:

0 if success, errno on failure.

int bt_mcc_read_current_track_obj_id(struct bt_conn *conn)

Read Current Track Object ID.

Parameters:

conn – Connection to the peer device

Returns:

0 if success, errno on failure.

int bt_mcc_set_current_track_obj_id(struct bt_conn *conn, uint64_t id)

Set Current Track Object ID.

Set the Current Track to the track given by the id parameter

Parameters:

conn – Connection to the peer device
id – Object Transfer Service ID (UINT48) of the track to set as the current track

Returns:

0 if success, errno on failure.

int bt_mcc_read_next_track_obj_id(struct bt_conn *conn)