Commmon Audio Profile

API Reference

group bt_cap

Common Audio Profile (CAP)

[Experimental] Users should note that the APIs can change as a part of ongoing development.

Enums

enum bt_cap_set_type

Type of CAP set

Values:

enumerator BT_CAP_SET_TYPE_AD_HOC

The set is an ad-hoc set

enumerator BT_CAP_SET_TYPE_CSIP

The set is a CSIP Coordinated Set

Functions

int bt_cap_acceptor_register(const struct bt_csip_set_member_register_param *param, struct bt_csip_set_member_svc_inst **svc_inst)

Register the Common Audio Service.

This will register and enable the service and make it discoverable by clients. This will also register a Coordinated Set Identification Service instance.

This shall only be done as a server, and requires BT_CAP_ACCEPTOR_SET_MEMBER . If BT_CAP_ACCEPTOR_SET_MEMBER is not enabled, the Common Audio Service will by statically registered.

Parameters:

  • param – [in] Coordinated Set Identification Service register parameters.

  • svc_inst – [out] Pointer to the registered Coordinated Set Identification Service.

Returns:

0 if success, errno on failure.

int bt_cap_initiator_unicast_discover(struct bt_conn *conn)

Discovers audio support on a remote device.

This will discover the Common Audio Service (CAS) on the remote device, to verify if the remote device supports the Common Audio Profile.

Parameters:

  • conn – Connection to a remote server.

Returns:

0 on success or negative error value on failure.

void bt_cap_stream_ops_register(struct bt_cap_stream *stream, struct bt_bap_stream_ops *ops)

Register Audio operations for a Common Audio Profile stream.

Register Audio operations for a stream.

Parameters:

  • stream – Stream object.

  • ops – Stream operations structure.

int bt_cap_initiator_register_cb(const struct bt_cap_initiator_cb *cb)

Register Common Audio Profile callbacks.

Parameters:

  • cb – The callback structure. Shall remain static.

Returns:

0 on success or negative error value on failure.

int bt_cap_initiator_unicast_audio_start(const struct bt_cap_unicast_audio_start_param *param, struct bt_bap_unicast_group *unicast_group)

Setup and start unicast audio streams for a set of devices.

The result of this operation is that the streams in param will be initialized and will be usable for streaming audio data. The unicast_group value can be used to update and stop the streams.

Note

CONFIG_BT_CAP_INITIATOR and CONFIG_BT_BAP_UNICAST_CLIENT must be enabled for this function to be enabled.

Parameters:

  • param – [in] Parameters to start the audio streams.

  • unicast_group – [out] Pointer to the unicast group.

Returns:

0 on success or negative error value on failure.

int bt_cap_initiator_unicast_audio_update(const struct bt_cap_unicast_audio_update_param params[], size_t count)

Update unicast audio streams.

This will update the metadata of one or more streams.

Note

CONFIG_BT_CAP_INITIATOR and CONFIG_BT_BAP_UNICAST_CLIENT must be enabled for this function to be enabled.

Parameters:

  • params – Array of update parameters.

  • count – The number of entries in params.

Returns:

0 on success or negative error value on failure.

int bt_cap_initiator_unicast_audio_stop(struct bt_bap_unicast_group *unicast_group)

Stop unicast audio streams for a unicast group.

Note

CONFIG_BT_CAP_INITIATOR and CONFIG_BT_BAP_UNICAST_CLIENT must be enabled for this function to be enabled.

Parameters:

  • unicast_group – The group of unicast devices to stop. The audio streams in this will be stopped and reset, and the unicast_group will be invalidated.

Returns:

0 on success or negative error value on failure.

int bt_cap_initiator_broadcast_audio_start(struct bt_cap_initiator_broadcast_create_param *param, struct bt_le_ext_adv *adv, struct bt_cap_broadcast_source **broadcast_source)

Create and start Common Audio Profile Common Audio Profile broadcast source.

Create a new audio broadcast source with one or more audio streams.

The broadcast source will be visible for scanners once this has been called, and the device will advertise audio announcements.

This will allow the streams in the broadcast source to send audio by calling bt_bap_stream_send().

Note

CONFIG_BT_CAP_INITIATOR and CONFIG_BT_BAP_BROADCAST_SOURCE must be enabled for this function to be enabled.

Parameters:

  • param – [in] Parameters to start the audio streams.

  • adv – [in] Pointer to an extended advertising set with periodic advertising configured.

  • broadcast_source – [out] Pointer to the broadcast source created.

Returns:

0 on success or negative error value on failure.

int bt_cap_initiator_broadcast_audio_update(struct bt_cap_broadcast_source *broadcast_source, const struct bt_codec_data meta[], size_t meta_count)

Update broadcast audio streams for a Common Audio Profile broadcast source.

Note

CONFIG_BT_CAP_INITIATOR and CONFIG_BT_BAP_BROADCAST_SOURCE must be enabled for this function to be enabled.

Parameters:

  • broadcast_source – The broadcast source to update.

  • meta_count – The number of entries in meta.

  • meta – The new metadata. The metadata shall contain a list of CCIDs as well as a non-0 context bitfield.

Returns:

0 on success or negative error value on failure.

int bt_cap_initiator_broadcast_audio_stop(struct bt_cap_broadcast_source *broadcast_source)

Stop broadcast audio streams for a Common Audio Profile broadcast source.

Note

CONFIG_BT_CAP_INITIATOR and CONFIG_BT_BAP_BROADCAST_SOURCE must be enabled for this function to be enabled.

Parameters:

  • broadcast_source – The broadcast source to stop. The audio streams in this will be stopped and reset.

Returns:

0 on success or negative error value on failure.

int bt_cap_initiator_broadcast_audio_delete(struct bt_cap_broadcast_source *broadcast_source)
int bt_cap_initiator_broadcast_get_id(const struct bt_cap_broadcast_source *source, uint32_t *const broadcast_id)

Get the broadcast ID of a Common Audio Profile broadcast source.

This will return the 3-octet broadcast ID that should be advertised in the extended advertising data with BT_UUID_BROADCAST_AUDIO_VAL as BT_DATA_SVC_DATA16.

See table 3.14 in the Basic Audio Profile v1.0.1 for the structure.

Parameters:

  • source – [in] Pointer to the broadcast source.

  • broadcast_id – [out] Pointer to the 3-octet broadcast ID.

Returns:

int 0 if on success, errno on error.

int bt_cap_initiator_broadcast_get_base(struct bt_cap_broadcast_source *source, struct net_buf_simple *base_buf)

Get the Broadcast Audio Stream Endpoint of a Common Audio Profile broadcast source.

This will encode the BASE of a broadcast source into a buffer, that can be used for advertisement. The encoded BASE will thus be encoded as little-endian. The BASE shall be put into the periodic advertising data (see bt_le_per_adv_set_data()).

See table 3.15 in the Basic Audio Profile v1.0.1 for the structure.

Parameters:

  • source – Pointer to the broadcast source.

  • base_buf – Pointer to a buffer where the BASE will be inserted.

Returns:

int 0 if on success, errno on error.

int bt_cap_initiator_unicast_to_broadcast(const struct bt_cap_unicast_to_broadcast_param *param, struct bt_cap_broadcast_source **source)

Hands over the data streams in a unicast group to a broadcast source.

The streams in the unicast group will be stopped and the unicast group will be deleted. This can only be done for source streams.

Note

CONFIG_BT_CAP_INITIATOR , CONFIG_BT_BAP_UNICAST_CLIENT and CONFIG_BT_BAP_BROADCAST_SOURCE must be enabled for this function to be enabled.

Parameters:

  • param – The parameters for the handover.

  • source – The resulting broadcast source.

Returns:

0 on success or negative error value on failure.

int bt_cap_initiator_broadcast_to_unicast(const struct bt_cap_broadcast_to_unicast_param *param, struct bt_bap_unicast_group **unicast_group)

Hands over the data streams in a broadcast source to a unicast group.

The streams in the broadcast source will be stopped and the broadcast source will be deleted.

Note

CONFIG_BT_CAP_INITIATOR , CONFIG_BT_BAP_UNICAST_CLIENT and CONFIG_BT_BAP_BROADCAST_SOURCE must be enabled for this function to be enabled.

Parameters:

  • param – [in] The parameters for the handover.

  • unicast_group – [out] The resulting broadcast source.

Returns:

0 on success or negative error value on failure.

struct bt_cap_initiator_cb
#include <cap.h>

Callback structure for CAP procedures

union bt_cap_set_member
#include <cap.h>

Represents a Common Audio Set member that are either in a Coordinated or ad-hoc set

Public Members

struct bt_conn *member

Connection pointer if the type is BT_CAP_SET_TYPE_AD_HOC.

struct bt_csip_set_coordinator_csis_inst *csip

CSIP Coordinated Set struct used if type is BT_CAP_SET_TYPE_CSIP.

struct bt_cap_stream
#include <cap.h>
struct bt_cap_unicast_audio_start_stream_param
#include <cap.h>

Public Members

union bt_cap_set_member member

Coordinated or ad-hoc set member.

struct bt_cap_stream *stream

Stream for the member.

struct bt_bap_ep *ep

Endpoint reference for the stream

struct bt_codec *codec

Codec configuration.

The codec.meta shall include a list of CCIDs (BT_AUDIO_METADATA_TYPE_CCID_LIST) as well as a non-0 stream context (BT_AUDIO_METADATA_TYPE_STREAM_CONTEXT) bitfield.

struct bt_codec_qos *qos

Quality of Service configuration.

struct bt_cap_unicast_audio_start_param
#include <cap.h>

Public Members

enum bt_cap_set_type type

The type of the set.

size_t count

The number of parameters in stream_params

struct bt_cap_unicast_audio_start_stream_param *stream_params

Array of stream parameters

uint8_t packing

Unicast Group packing mode.

BT_ISO_PACKING_SEQUENTIAL or BT_ISO_PACKING_INTERLEAVED.

Note

This is a recommendation to the controller, which the controller may ignore.

struct bt_cap_unicast_audio_update_param
#include <cap.h>

Public Members

struct bt_cap_stream *stream

Stream for the member.

size_t meta_count

The number of entries in meta.

struct bt_codec_data *meta

The new metadata.

The metadata shall a list of CCIDs as well as a non-0 context bitfield.

struct bt_cap_initiator_broadcast_stream_param
#include <cap.h>

Public Members

struct bt_cap_stream *stream

Audio stream

size_t data_count

The number of elements in the p data array.

The BIS specific data may be omitted and this set to 0.

struct bt_codec_data *data

BIS Codec Specific Configuration

struct bt_cap_initiator_broadcast_subgroup_param
#include <cap.h>

Public Members

size_t stream_count

The number of parameters in stream_params

struct bt_cap_initiator_broadcast_stream_param *stream_params

Array of stream parameters

struct bt_codec *codec

Subgroup Codec configuration.

struct bt_cap_initiator_broadcast_create_param
#include <cap.h>

Public Members

size_t subgroup_count

The number of parameters in subgroup_params

struct bt_cap_initiator_broadcast_subgroup_param *subgroup_params

Array of stream parameters

struct bt_codec_qos *qos

Quality of Service configuration.

uint8_t packing

Broadcast Source packing mode.

BT_ISO_PACKING_SEQUENTIAL or BT_ISO_PACKING_INTERLEAVED.

Note

This is a recommendation to the controller, which the controller may ignore.

bool encryption

Whether or not to encrypt the streams.

uint8_t broadcast_code[BT_AUDIO_BROADCAST_CODE_SIZE]

16-octet broadcast code.

Only valid if encrypt is true.

If the value is a string or a the value is less than 16 octets, the remaining octets shall be 0.

Example: The string “Broadcast Code” shall be [42 72 6F 61 64 63 61 73 74 20 43 6F 64 65 00 00]

struct bt_cap_unicast_to_broadcast_param
#include <cap.h>

Public Members

struct bt_bap_unicast_group *unicast_group

The source unicast group with the streams.

bool encrypt

Whether or not to encrypt the streams.

If set to true, then the broadcast code in broadcast_code will be used to encrypt the streams.

uint8_t broadcast_code[BT_ISO_BROADCAST_CODE_SIZE]

16-octet broadcast code.

Only valid if encrypt is true.

If the value is a string or a the value is less than 16 octets, the remaining octets shall be 0.

Example: The string “Broadcast Code” shall be [42 72 6F 61 64 63 61 73 74 20 43 6F 64 65 00 00]

struct bt_cap_broadcast_to_unicast_param
#include <cap.h>

Public Members

struct bt_cap_broadcast_source *broadcast_source

The source broadcast source with the streams.

The broadcast source will be stopped and deleted.

enum bt_cap_set_type type

The type of the set.

size_t count

The number of set members in members.

This value shall match the number of streams in the broadcast_source.

union bt_cap_set_member **members

Coordinated or ad-hoc set members.