Bluetooth Audio

API Reference

group bt_audio

Bluetooth Audio.

Defines

BT_AUDIO_BROADCAST_ID_SIZE
BT_AUDIO_BROADCAST_ID_MAX

Maximum broadcast ID value.

BT_AUDIO_PD_PREF_NONE

Indicates that the server have no preference for the presentation delay.

BT_AUDIO_PD_MAX

Maximum presentation delay in microseconds.

BT_AUDIO_BROADCAST_CODE_SIZE
BT_AUDIO_CONTEXT_TYPE_ANY

Any known context.

BT_AUDIO_METADATA_TYPE_IS_KNOWN(_type)

Helper to check whether metadata type is known by the stack.

BT_AUDIO_UNICAST_ANNOUNCEMENT_GENERAL
BT_AUDIO_UNICAST_ANNOUNCEMENT_TARGETED
BT_AUDIO_CODEC_DATA(_type, _bytes...)

Helper to declare elements of bt_audio_codec_cap arrays.

This macro is mainly for creating an array of struct bt_audio_codec_cap data arrays.

Parameters:

  • _type – Type of advertising data field

  • _bytes – Variable number of single-byte parameters

BT_AUDIO_CODEC_CFG(_id, _cid, _vid, _data, _meta)

Helper to declare Codec config parsing APIs.

Parameters:

  • _id – Codec ID

  • _cid – Company ID

  • _vid – Vendor ID

  • _data – Codec Specific Data in LVT format

  • _meta – Codec Specific Metadata in LVT format

BT_AUDIO_CODEC_CAP(_id, _cid, _vid, _data, _meta)

Helper to declare bt_audio_codec_cap structure.

Parameters:

  • _id – Codec ID

  • _cid – Company ID

  • _vid – Vendor ID

  • _data – Codec Specific Data in LVT format

  • _meta – Codec Specific Metadata in LVT format

BT_AUDIO_LOCATION_ANY

Any known location.

BT_AUDIO_CODEC_QOS(_interval, _framing, _phy, _sdu, _rtn, _latency, _pd)

Helper to declare elements of bt_audio_codec_qos.

Parameters:

  • _interval – SDU interval (usec)

  • _framing – Framing

  • _phy – Target PHY

  • _sdu – Maximum SDU Size

  • _rtn – Retransmission number

  • _latency – Maximum Transport Latency (msec)

  • _pd – Presentation Delay (usec)

BT_AUDIO_CODEC_QOS_UNFRAMED(_interval, _sdu, _rtn, _latency, _pd)

Helper to declare Input Unframed bt_audio_codec_qos.

Parameters:

  • _interval – SDU interval (usec)

  • _sdu – Maximum SDU Size

  • _rtn – Retransmission number

  • _latency – Maximum Transport Latency (msec)

  • _pd – Presentation Delay (usec)

BT_AUDIO_CODEC_QOS_FRAMED(_interval, _sdu, _rtn, _latency, _pd)

Helper to declare Input Framed bt_audio_codec_qos.

Parameters:

  • _interval – SDU interval (usec)

  • _sdu – Maximum SDU Size

  • _rtn – Retransmission number

  • _latency – Maximum Transport Latency (msec)

  • _pd – Presentation Delay (usec)

BT_AUDIO_CODEC_QOS_PREF(_unframed_supported, _phy, _rtn, _latency, _pd_min, _pd_max, _pref_pd_min, _pref_pd_max)

Helper to declare elements of bt_audio_codec_qos_pref.

Parameters:

  • _unframed_supported – Unframed PDUs supported

  • _phy – Preferred Target PHY

  • _rtn – Preferred Retransmission number

  • _latency – Preferred Maximum Transport Latency (msec)

  • _pd_min – Minimum Presentation Delay (usec)

  • _pd_max – Maximum Presentation Delay (usec)

  • _pref_pd_min – Preferred Minimum Presentation Delay (usec)

  • _pref_pd_max – Preferred Maximum Presentation Delay (usec)

Enums

enum bt_audio_context

Audio Context Type for Generic Audio.

These values are defined by the Generic Audio Assigned Numbers, bluetooth.com

Values:

enumerator BT_AUDIO_CONTEXT_TYPE_PROHIBITED = 0
enumerator BT_AUDIO_CONTEXT_TYPE_UNSPECIFIED = BIT(0)
enumerator BT_AUDIO_CONTEXT_TYPE_CONVERSATIONAL = BIT(1)
enumerator BT_AUDIO_CONTEXT_TYPE_MEDIA = BIT(2)
enumerator BT_AUDIO_CONTEXT_TYPE_GAME = BIT(3)
enumerator BT_AUDIO_CONTEXT_TYPE_INSTRUCTIONAL = BIT(4)
enumerator BT_AUDIO_CONTEXT_TYPE_VOICE_ASSISTANTS = BIT(5)
enumerator BT_AUDIO_CONTEXT_TYPE_LIVE = BIT(6)
enumerator BT_AUDIO_CONTEXT_TYPE_SOUND_EFFECTS = BIT(7)
enumerator BT_AUDIO_CONTEXT_TYPE_NOTIFICATIONS = BIT(8)
enumerator BT_AUDIO_CONTEXT_TYPE_RINGTONE = BIT(9)
enumerator BT_AUDIO_CONTEXT_TYPE_ALERTS = BIT(10)
enumerator BT_AUDIO_CONTEXT_TYPE_EMERGENCY_ALARM = BIT(11)
enum bt_audio_parental_rating

Parental rating defined by the Generic Audio assigned numbers (bluetooth.com).

The numbering scheme is aligned with Annex F of EN 300 707 v1.2.1 which defined parental rating for viewing.

Values:

enumerator BT_AUDIO_PARENTAL_RATING_NO_RATING = 0x00
enumerator BT_AUDIO_PARENTAL_RATING_AGE_ANY = 0x01
enumerator BT_AUDIO_PARENTAL_RATING_AGE_5_OR_ABOVE = 0x02
enumerator BT_AUDIO_PARENTAL_RATING_AGE_6_OR_ABOVE = 0x03
enumerator BT_AUDIO_PARENTAL_RATING_AGE_7_OR_ABOVE = 0x04
enumerator BT_AUDIO_PARENTAL_RATING_AGE_8_OR_ABOVE = 0x05
enumerator BT_AUDIO_PARENTAL_RATING_AGE_9_OR_ABOVE = 0x06
enumerator BT_AUDIO_PARENTAL_RATING_AGE_10_OR_ABOVE = 0x07
enumerator BT_AUDIO_PARENTAL_RATING_AGE_11_OR_ABOVE = 0x08
enumerator BT_AUDIO_PARENTAL_RATING_AGE_12_OR_ABOVE = 0x09
enumerator BT_AUDIO_PARENTAL_RATING_AGE_13_OR_ABOVE = 0x0A
enumerator BT_AUDIO_PARENTAL_RATING_AGE_14_OR_ABOVE = 0x0B
enumerator BT_AUDIO_PARENTAL_RATING_AGE_15_OR_ABOVE = 0x0C
enumerator BT_AUDIO_PARENTAL_RATING_AGE_16_OR_ABOVE = 0x0D
enumerator BT_AUDIO_PARENTAL_RATING_AGE_17_OR_ABOVE = 0x0E
enumerator BT_AUDIO_PARENTAL_RATING_AGE_18_OR_ABOVE = 0x0F
enum bt_audio_active_state

Audio Active State defined by the Generic Audio assigned numbers (bluetooth.com).

Values:

enumerator BT_AUDIO_ACTIVE_STATE_DISABLED = 0x00
enumerator BT_AUDIO_ACTIVE_STATE_ENABLED = 0x01
enum bt_audio_metadata_type

Codec metadata type IDs.

Metadata types defined by the Generic Audio assigned numbers (bluetooth.com).

Values:

enumerator BT_AUDIO_METADATA_TYPE_PREF_CONTEXT = 0x01

Preferred audio context. 

   Bitfield of preferred audio contexts.

   If 0, the context type is not a preferred use case for this codec
   configuration.

   See the BT_AUDIO_CONTEXT_* for valid values.
enumerator BT_AUDIO_METADATA_TYPE_STREAM_CONTEXT = 0x02

Streaming audio context. 

   Bitfield of streaming audio contexts.

   If 0, the context type is not a preferred use case for this codec
   configuration.

   See the BT_AUDIO_CONTEXT_* for valid values.
enumerator BT_AUDIO_METADATA_TYPE_PROGRAM_INFO = 0x03

UTF-8 encoded title or summary of stream content.

enumerator BT_AUDIO_METADATA_TYPE_STREAM_LANG = 0x04

Stream language. 

   3 octet lower case language code defined by ISO 639-3
enumerator BT_AUDIO_METADATA_TYPE_CCID_LIST = 0x05

Array of 8-bit CCID values.

enumerator BT_AUDIO_METADATA_TYPE_PARENTAL_RATING = 0x06

Parental rating. 

   See @ref bt_audio_parental_rating for valid values.
enumerator BT_AUDIO_METADATA_TYPE_PROGRAM_INFO_URI = 0x07

UTF-8 encoded URI for additional Program information.

enumerator BT_AUDIO_METADATA_TYPE_AUDIO_STATE = 0x08

Audio active state. 

   See @ref bt_audio_active_state for valid values.
enumerator BT_AUDIO_METADATA_TYPE_BROADCAST_IMMEDIATE = 0x09

Broadcast Audio Immediate Rendering flag

enumerator BT_AUDIO_METADATA_TYPE_EXTENDED = 0xFE

Extended metadata.

enumerator BT_AUDIO_METADATA_TYPE_VENDOR = 0xFF

Vendor specific metadata.

enum bt_audio_location

Location values for BT Audio.

These values are defined by the Generic Audio Assigned Numbers, bluetooth.com

Values:

enumerator BT_AUDIO_LOCATION_PROHIBITED = 0
enumerator BT_AUDIO_LOCATION_FRONT_LEFT = BIT(0)
enumerator BT_AUDIO_LOCATION_FRONT_RIGHT = BIT(1)
enumerator BT_AUDIO_LOCATION_FRONT_CENTER = BIT(2)
enumerator BT_AUDIO_LOCATION_LOW_FREQ_EFFECTS_1 = BIT(3)
enumerator BT_AUDIO_LOCATION_BACK_LEFT = BIT(4)
enumerator BT_AUDIO_LOCATION_BACK_RIGHT = BIT(5)
enumerator BT_AUDIO_LOCATION_FRONT_LEFT_OF_CENTER = BIT(6)
enumerator BT_AUDIO_LOCATION_FRONT_RIGHT_OF_CENTER = BIT(7)
enumerator BT_AUDIO_LOCATION_BACK_CENTER = BIT(8)
enumerator BT_AUDIO_LOCATION_LOW_FREQ_EFFECTS_2 = BIT(9)
enumerator BT_AUDIO_LOCATION_SIDE_LEFT = BIT(10)
enumerator BT_AUDIO_LOCATION_SIDE_RIGHT = BIT(11)
enumerator BT_AUDIO_LOCATION_TOP_FRONT_LEFT = BIT(12)
enumerator BT_AUDIO_LOCATION_TOP_FRONT_RIGHT = BIT(13)
enumerator BT_AUDIO_LOCATION_TOP_FRONT_CENTER = BIT(14)
enumerator BT_AUDIO_LOCATION_TOP_CENTER = BIT(15)
enumerator BT_AUDIO_LOCATION_TOP_BACK_LEFT = BIT(16)
enumerator BT_AUDIO_LOCATION_TOP_BACK_RIGHT = BIT(17)
enumerator BT_AUDIO_LOCATION_TOP_SIDE_LEFT = BIT(18)
enumerator BT_AUDIO_LOCATION_TOP_SIDE_RIGHT = BIT(19)
enumerator BT_AUDIO_LOCATION_TOP_BACK_CENTER = BIT(20)
enumerator BT_AUDIO_LOCATION_BOTTOM_FRONT_CENTER = BIT(21)
enumerator BT_AUDIO_LOCATION_BOTTOM_FRONT_LEFT = BIT(22)
enumerator BT_AUDIO_LOCATION_BOTTOM_FRONT_RIGHT = BIT(23)
enumerator BT_AUDIO_LOCATION_FRONT_LEFT_WIDE = BIT(24)
enumerator BT_AUDIO_LOCATION_FRONT_RIGHT_WIDE = BIT(25)
enumerator BT_AUDIO_LOCATION_LEFT_SURROUND = BIT(26)
enumerator BT_AUDIO_LOCATION_RIGHT_SURROUND = BIT(27)
enum bt_audio_dir

Audio Capability type.

Values:

enumerator BT_AUDIO_DIR_SINK = 0x01
enumerator BT_AUDIO_DIR_SOURCE = 0x02
enum bt_audio_codec_qos_framing

Codec QoS Framing.

Values:

enumerator BT_AUDIO_CODEC_QOS_FRAMING_UNFRAMED = 0x00
enumerator BT_AUDIO_CODEC_QOS_FRAMING_FRAMED = 0x01
enum [anonymous]

Codec QoS Preferred PHY.

Values:

enumerator BT_AUDIO_CODEC_QOS_1M = BIT(0)
enumerator BT_AUDIO_CODEC_QOS_2M = BIT(1)
enumerator BT_AUDIO_CODEC_QOS_CODED = BIT(2)

Functions

int bt_audio_data_parse(const uint8_t ltv[], size_t size, bool (*func)(struct bt_data *data, void *user_data), void *user_data)

Helper for parsing length-type-value data.

Parameters:

  • ltv – Length-type-value (LTV) encoded data.

  • size – Size of the ltv data.

  • func – Callback function which will be called for each element that’s found in the data. The callback should return true to continue parsing, or false to stop parsing.

  • user_data – User data to be passed to the callback.

Return values:

  • 0 – if all entries were parsed.

  • -EINVAL – if the data is incorrectly encoded

  • -ECANCELED – if parsing was prematurely cancelled by the callback

struct bt_audio_codec_cap
#include <audio.h>

Codec capability structure.

Public Members

uint8_t path_id

Data path ID.

BT_ISO_DATA_PATH_HCI for HCI path, or any other value for vendor specific ID.

uint8_t id

Codec ID.

uint16_t cid

Codec Company ID.

uint16_t vid

Codec Company Vendor ID.

struct bt_audio_codec_cfg
#include <audio.h>

Codec specific configuration structure.

Public Members

uint8_t path_id

Data path ID.

BT_ISO_DATA_PATH_HCI for HCI path, or any other value for vendor specific ID.

uint8_t id

Codec ID.

uint16_t cid

Codec Company ID.

uint16_t vid

Codec Company Vendor ID.

struct bt_audio_codec_qos
#include <audio.h>

Codec QoS structure.

Public Members

uint8_t phy

QoS PHY.

enum bt_audio_codec_qos_framing framing

QoS Framing.

uint8_t rtn

QoS Retransmission Number.

uint16_t sdu

QoS SDU.

uint32_t interval

QoS Frame Interval.

uint32_t pd

QoS Presentation Delay in microseconds.

Value range 0 to BT_AUDIO_PD_MAX.

struct bt_audio_codec_qos_pref
#include <audio.h>

Audio Stream Quality of Service Preference structure.

Public Members

bool unframed_supported

Unframed PDUs supported.

Unlike the other fields, this is not a preference but whether the codec supports unframed ISOAL PDUs.

uint8_t phy

Preferred PHY.

uint8_t rtn

Preferred Retransmission Number.

uint16_t latency

Preferred Transport Latency.

uint32_t pd_min

Minimum Presentation Delay in microseconds.

Unlike the other fields, this is not a preference but a minimum requirement.

Value range 0 to BT_AUDIO_PD_MAX, or BT_AUDIO_PD_PREF_NONE to indicate no preference.

uint32_t pd_max

Maximum Presentation Delay.

Unlike the other fields, this is not a preference but a maximum requirement.

Value range 0 to BT_AUDIO_PD_MAX, or BT_AUDIO_PD_PREF_NONE to indicate no preference.

uint32_t pref_pd_min

Preferred minimum Presentation Delay.

Value range 0 to BT_AUDIO_PD_MAX.

uint32_t pref_pd_max

Preferred maximum Presentation Delay.

Value range 0 to BT_AUDIO_PD_MAX.

group bt_audio_codec_cfg

Audio codec Config APIs.

Functions to parse codec config data when formatted as LTV wrapped into Codec config parsing APIs.

Enums

enum bt_audio_codec_cfg_parse_err

Codec parser error codes for Codec config parsing APIs.

Values:

enumerator BT_AUDIO_CODEC_PARSE_ERR_SUCCESS = 0

The requested type is not present in the data set.

enumerator BT_AUDIO_CODEC_PARSE_ERR_TYPE_NOT_FOUND = -1

The requested type is not present in the data set.

enumerator BT_AUDIO_CODEC_PARSE_ERR_INVALID_VALUE_FOUND = -2

The value found is invalid.

enumerator BT_AUDIO_CODEC_PARSE_ERR_INVALID_PARAM = -3

The parameters specified to the function call are not valid.

Functions

int bt_audio_codec_cfg_get_freq(const struct bt_audio_codec_cfg *codec_cfg)

Extract the frequency from a codec configuration.

Parameters:

  • codec_cfg – The codec configuration to extract data from.

Returns:

The frequency in Hz if found else a negative value of type bt_audio_codec_cfg_parse_err.

int bt_audio_codec_cfg_get_frame_duration_us(const struct bt_audio_codec_cfg *codec_cfg)

Extract frame duration from BT codec config.

Parameters:

  • codec_cfg – The codec configuration to extract data from.

Returns:

Frame duration in microseconds if value is found else a negative value of type bt_audio_codec_cfg_parse_err.

int bt_audio_codec_cfg_get_chan_allocation_val(const struct bt_audio_codec_cfg *codec_cfg, enum bt_audio_location *chan_allocation)

Extract channel allocation from BT codec config.

The value returned is a bit field representing one or more audio locations as specified by bt_audio_location Shall match one or more of the bits set in BT_PAC_SNK_LOC/BT_PAC_SRC_LOC.

Up to the configured BT_AUDIO_CODEC_LC3_CHAN_COUNT number of channels can be present.

Parameters:

  • codec_cfg – The codec configuration to extract data from.

  • chan_allocation – Pointer to the variable to store the extracted value in.

Returns:

BT_AUDIO_CODEC_PARSE_SUCCESS if value is found and stored in the pointer provided else a negative value of type bt_audio_codec_cfg_parse_err.

int bt_audio_codec_cfg_get_octets_per_frame(const struct bt_audio_codec_cfg *codec_cfg)

Extract frame size in octets from BT codec config.

The overall SDU size will be octets_per_frame * blocks_per_sdu.

The Bluetooth specificationa are not clear about this value - it does not state that the codec shall use this SDU size only. A codec like LC3 supports variable bit-rate (per SDU) hence it might be allowed for an encoder to reduce the frame size below this value. Hence it is recommended to use the received SDU size and divide by blocks_per_sdu rather than relying on this octets_per_sdu value to be fixed.

Parameters:

  • codec_cfg – The codec configuration to extract data from.

Returns:

Frame length in octets if value is found else a negative value of type bt_audio_codec_cfg_parse_err.

int bt_audio_codec_cfg_get_frame_blocks_per_sdu(const struct bt_audio_codec_cfg *codec_cfg, bool fallback_to_default)

Extract number of audio frame blockss in each SDU from BT codec config.

The overall SDU size will be octets_per_frame * frame_blocks_per_sdu * number-of-channels.

If this value is not present a default value of 1 shall be used.

A frame block is one or more frames that represents data for the same period of time but for different channels. If the stream have two audio channels and this value is two there will be four frames in the SDU.

Parameters:

  • codec_cfg – The codec configuration to extract data from.

  • fallback_to_default – If true this function will return the default value of 1 if the type is not found. In this case the function will only fail if a NULL pointer is provided.

Returns:

The count of codec frames in each SDU if value is found else a negative value of type bt_audio_codec_cfg_parse_err - unless when fallback_to_default is true then the value 1 is returned if frames per sdu is not found.

uint8_t bt_audio_codec_cfg_get_val(const struct bt_audio_codec_cfg *codec_cfg, uint8_t type, const uint8_t **data)

Lookup a specific value based on type.

Depending on context bt_audio_codec_cfg will be either codec capabilities, codec configuration or meta data.

Typically types used are: bt_audio_codec_capability_type bt_audio_codec_config_type bt_audio_metadata_type

Parameters:

  • codec_cfg – [in] The codec data to search in.

  • type – [in] The type id to look for

  • data – [out] Pointer to the data-pointer to update when item is found

Returns:

Length of found data or 0 if not found