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_CODEC_CAP_CHAN_COUNT_MIN

Minimum supported channel counts.

BT_AUDIO_CODEC_CAP_CHAN_COUNT_MAX

Maximum supported channel counts.

BT_AUDIO_CODEC_CAP_CHAN_COUNT_SUPPORT(...)

Channel count support capability.

Macro accepts variable number of channel counts. The allowed channel counts are defined by specification and have to be in range from BT_AUDIO_CODEC_CAP_CHAN_COUNT_MIN to BT_AUDIO_CODEC_CAP_CHAN_COUNT_MAX inclusive.

Example to support 1 and 3 channels: BT_AUDIO_CODEC_CAP_CHAN_COUNT_SUPPORT(1, 3)

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.

Note

_type is evaluated thrice.

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 Codec capability parsing APIs 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_codec_cap_type

Codec capability types.

Used to build and parse codec capabilities as specified in the PAC specification. Source is assigned numbers for Generic Audio, bluetooth.com.

Values:

enumerator BT_AUDIO_CODEC_CAP_TYPE_FREQ = 0x01

Supported sampling frequencies.

enumerator BT_AUDIO_CODEC_CAP_TYPE_DURATION = 0x02

Supported frame durations.

enumerator BT_AUDIO_CODEC_CAP_TYPE_CHAN_COUNT = 0x03

Supported audio channel counts.

enumerator BT_AUDIO_CODEC_CAP_TYPE_FRAME_LEN = 0x04

Supported octets per codec frame.

enumerator BT_AUDIO_CODEC_CAP_TYPE_FRAME_COUNT = 0x05

Supported maximum codec frames per SDU

enum bt_audio_codec_cap_freq

Supported frequencies bitfield.

Values:

enumerator BT_AUDIO_CODEC_CAP_FREQ_8KHZ = BIT(0)

8 Khz sampling frequency

enumerator BT_AUDIO_CODEC_CAP_FREQ_11KHZ = BIT(1)

11.025 Khz sampling frequency

enumerator BT_AUDIO_CODEC_CAP_FREQ_16KHZ = BIT(2)

16 Khz sampling frequency

enumerator BT_AUDIO_CODEC_CAP_FREQ_22KHZ = BIT(3)

22.05 Khz sampling frequency

enumerator BT_AUDIO_CODEC_CAP_FREQ_24KHZ = BIT(4)

24 Khz sampling frequency

enumerator BT_AUDIO_CODEC_CAP_FREQ_32KHZ = BIT(5)

32 Khz sampling frequency

enumerator BT_AUDIO_CODEC_CAP_FREQ_44KHZ = BIT(6)

44.1 Khz sampling frequency

enumerator BT_AUDIO_CODEC_CAP_FREQ_48KHZ = BIT(7)

48 Khz sampling frequency

enumerator BT_AUDIO_CODEC_CAP_FREQ_88KHZ = BIT(8)

88.2 Khz sampling frequency

enumerator BT_AUDIO_CODEC_CAP_FREQ_96KHZ = BIT(9)

96 Khz sampling frequency

enumerator BT_AUDIO_CODEC_CAP_FREQ_176KHZ = BIT(10)

176.4 Khz sampling frequency

enumerator BT_AUDIO_CODEC_CAP_FREQ_192KHZ = BIT(11)

192 Khz sampling frequency

enumerator BT_AUDIO_CODEC_CAP_FREQ_384KHZ = BIT(12)

384 Khz sampling frequency

enumerator BT_AUDIO_CODEC_CAP_FREQ_ANY = (BT_AUDIO_CODEC_CAP_FREQ_8KHZ | BT_AUDIO_CODEC_CAP_FREQ_11KHZ | BT_AUDIO_CODEC_CAP_FREQ_16KHZ | BT_AUDIO_CODEC_CAP_FREQ_22KHZ | BT_AUDIO_CODEC_CAP_FREQ_24KHZ | BT_AUDIO_CODEC_CAP_FREQ_32KHZ | BT_AUDIO_CODEC_CAP_FREQ_44KHZ | BT_AUDIO_CODEC_CAP_FREQ_48KHZ | BT_AUDIO_CODEC_CAP_FREQ_88KHZ | BT_AUDIO_CODEC_CAP_FREQ_96KHZ | BT_AUDIO_CODEC_CAP_FREQ_176KHZ | BT_AUDIO_CODEC_CAP_FREQ_192KHZ | BT_AUDIO_CODEC_CAP_FREQ_384KHZ)

Any frequency capability.

enum bt_audio_codec_cap_frame_dur

Supported frame durations bitfield.

Values:

enumerator BT_AUDIO_CODEC_CAP_DURATION_7_5 = BIT(0)

7.5 msec frame duration capability

enumerator BT_AUDIO_CODEC_CAP_DURATION_10 = BIT(1)

10 msec frame duration capability

enumerator BT_AUDIO_CODEC_CAP_DURATION_ANY = (BT_AUDIO_CODEC_CAP_DURATION_7_5 | BT_AUDIO_CODEC_CAP_DURATION_10)

Any frame duration capability.

enumerator BT_AUDIO_CODEC_CAP_DURATION_PREFER_7_5 = BIT(4)

7.5 msec preferred frame duration capability.

This shall only be set if BT_AUDIO_CODEC_CAP_DURATION_7_5 is also set, and if BT_AUDIO_CODEC_CAP_DURATION_PREFER_10 is not set.

enumerator BT_AUDIO_CODEC_CAP_DURATION_PREFER_10 = BIT(5)

10 msec preferred frame duration capability

This shall only be set if BT_AUDIO_CODEC_CAP_DURATION_10 is also set, and if BT_AUDIO_CODEC_CAP_DURATION_PREFER_7_5 is not set.

enum bt_audio_codec_cap_chan_count

Values:

enumerator BT_AUDIO_CODEC_CAP_CHAN_COUNT_1 = BIT(0)

Supporting 1 channel.

enumerator BT_AUDIO_CODEC_CAP_CHAN_COUNT_2 = BIT(1)

Supporting 2 channel.

enumerator BT_AUDIO_CODEC_CAP_CHAN_COUNT_3 = BIT(2)

Supporting 3 channel.

enumerator BT_AUDIO_CODEC_CAP_CHAN_COUNT_4 = BIT(3)

Supporting 4 channel.

enumerator BT_AUDIO_CODEC_CAP_CHAN_COUNT_5 = BIT(4)

Supporting 5 channel.

enumerator BT_AUDIO_CODEC_CAP_CHAN_COUNT_6 = BIT(5)

Supporting 6 channel.

enumerator BT_AUDIO_CODEC_CAP_CHAN_COUNT_7 = BIT(6)

Supporting 7 channel.

enumerator BT_AUDIO_CODEC_CAP_CHAN_COUNT_8 = BIT(7)

Supporting 8 channel.

enumerator BT_AUDIO_CODEC_CAP_CHAN_COUNT_ANY = (BT_AUDIO_CODEC_CAP_CHAN_COUNT_1 | BT_AUDIO_CODEC_CAP_CHAN_COUNT_2 | BT_AUDIO_CODEC_CAP_CHAN_COUNT_3 | BT_AUDIO_CODEC_CAP_CHAN_COUNT_4 | BT_AUDIO_CODEC_CAP_CHAN_COUNT_5 | BT_AUDIO_CODEC_CAP_CHAN_COUNT_6 | BT_AUDIO_CODEC_CAP_CHAN_COUNT_7 | BT_AUDIO_CODEC_CAP_CHAN_COUNT_8)

Supporting all channels.

enum bt_audio_codec_cfg_type

Codec configuration types.

Used to build and parse codec configurations as specified in the ASCS and BAP specifications. Source is assigned numbers for Generic Audio, bluetooth.com.

Values:

enumerator BT_AUDIO_CODEC_CFG_FREQ = 0x01

Sampling frequency.

enumerator BT_AUDIO_CODEC_CFG_DURATION = 0x02

Frame duration.

enumerator BT_AUDIO_CODEC_CFG_CHAN_ALLOC = 0x03

Audio channel allocation.

enumerator BT_AUDIO_CODEC_CFG_FRAME_LEN = 0x04

Octets per codec frame.

enumerator BT_AUDIO_CODEC_CFG_FRAME_BLKS_PER_SDU = 0x05

Codec frame blocks per SDU.

enum bt_audio_codec_cfg_freq

Values:

enumerator BT_AUDIO_CODEC_CFG_FREQ_8KHZ = 0x01

8 Khz codec sampling frequency

enumerator BT_AUDIO_CODEC_CFG_FREQ_11KHZ = 0x02

11.025 Khz codec sampling frequency

enumerator BT_AUDIO_CODEC_CFG_FREQ_16KHZ = 0x03

16 Khz codec sampling frequency

enumerator BT_AUDIO_CODEC_CFG_FREQ_22KHZ = 0x04

22.05 Khz codec sampling frequency

enumerator BT_AUDIO_CODEC_CFG_FREQ_24KHZ = 0x05

24 Khz codec sampling frequency

enumerator BT_AUDIO_CODEC_CFG_FREQ_32KHZ = 0x06

32 Khz codec sampling frequency

enumerator BT_AUDIO_CODEC_CFG_FREQ_44KHZ = 0x07

44.1 Khz codec sampling frequency

enumerator BT_AUDIO_CODEC_CFG_FREQ_48KHZ = 0x08

48 Khz codec sampling frequency

enumerator BT_AUDIO_CODEC_CFG_FREQ_88KHZ = 0x09

88.2 Khz codec sampling frequency

enumerator BT_AUDIO_CODEC_CFG_FREQ_96KHZ = 0x0a

96 Khz codec sampling frequency

enumerator BT_AUDIO_CODEC_CFG_FREQ_176KHZ = 0x0b

176.4 Khz codec sampling frequency

enumerator BT_AUDIO_CODEC_CFG_FREQ_192KHZ = 0x0c

192 Khz codec sampling frequency

enumerator BT_AUDIO_CODEC_CFG_FREQ_384KHZ = 0x0d

384 Khz codec sampling frequency

enum bt_audio_codec_cfg_frame_dur

Values:

enumerator BT_AUDIO_CODEC_CFG_DURATION_7_5 = 0x00

7.5 msec Frame Duration configuration

enumerator BT_AUDIO_CODEC_CFG_DURATION_10 = 0x01

10 msec Frame Duration configuration

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_MONO_AUDIO = 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_octets_per_codec_frame
#include <audio.h>

Public Members

uint16_t min

Minimum number of octets supported per codec frame.

uint16_t max

Maximum number of octets supported per codec frame.

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.

bool ctlr_transcode

Whether or not the local controller should transcode.

This effectively sets the coding format for the ISO data path to BT_HCI_CODING_FORMAT_TRANSPARENT if false, else uses the bt_audio_codec_cfg::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.

bool ctlr_transcode

Whether or not the local controller should transcode.

This effectively sets the coding format for the ISO data path to BT_HCI_CODING_FORMAT_TRANSPARENT if false, else uses the bt_audio_codec_cfg::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.

Functions

int bt_audio_codec_cfg_freq_to_freq_hz(enum bt_audio_codec_cfg_freq freq)

Convert assigned numbers frequency to frequency value.

Parameters:
  • freq – The assigned numbers frequency to convert.

Return values:
  • -EINVAL – if arguments are invalid.

  • The – converted frequency value in Hz.

int bt_audio_codec_cfg_freq_hz_to_freq(uint32_t freq_hz)

Convert frequency value to assigned numbers frequency.

Parameters:
  • freq_hz – The frequency value to convert.

Return values:
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.

Return values:
  • Abt_audio_codec_cfg_freq value

  • -EINVAL – if arguments are invalid

  • -ENODATA – if not found

  • -EBADMSG – if found value has invalid size or value

int bt_audio_codec_cfg_set_freq(struct bt_audio_codec_cfg *codec_cfg, enum bt_audio_codec_cfg_freq freq)

Set the frequency of a codec configuration.

Parameters:
  • codec_cfg – The codec configuration to set data for.

  • freq – The assigned numbers frequency to set.

Return values:
  • The – data_len of codec_cfg on success

  • -EINVAL – if arguments are invalid

  • -ENOMEM – if the new value could not set or added due to memory

int bt_audio_codec_cfg_frame_dur_to_frame_dur_us(enum bt_audio_codec_cfg_frame_dur frame_dur)

Convert assigned numbers frame duration to duration in microseconds.

Parameters:
  • frame_dur – The assigned numbers frame duration to convert.

Return values:
  • -EINVAL – if arguments are invalid.

  • The – converted frame duration value in microseconds.

int bt_audio_codec_cfg_frame_dur_us_to_frame_dur(uint32_t frame_dur_us)

Convert frame duration in microseconds to assigned numbers frame duration.

Parameters:
  • frame_dur_us – The frame duration in microseconds to convert.

Return values:
int bt_audio_codec_cfg_get_frame_dur(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.

Return values:
  • Abt_audio_codec_cfg_frame_dur value

  • -EINVAL – if arguments are invalid

  • -ENODATA – if not found

  • -EBADMSG – if found value has invalid size or value

int bt_audio_codec_cfg_set_frame_dur(struct bt_audio_codec_cfg *codec_cfg, enum bt_audio_codec_cfg_frame_dur frame_dur)

Set the frame duration of a codec configuration.

Parameters:
  • codec_cfg – The codec configuration to set data for.

  • frame_dur – The assigned numbers frame duration to set.

Return values:
  • The – data_len of codec_cfg on success

  • -EINVAL – if arguments are invalid

  • -ENOMEM – if the new value could not set or added due to memory

int bt_audio_codec_cfg_get_chan_allocation(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_CAP_TYPE_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.

Return values:
  • 0 – if value is found and stored in the pointer provided

  • -EINVAL – if arguments are invalid

  • -ENODATA – if not found

  • -EBADMSG – if found value has invalid size or value

int bt_audio_codec_cfg_set_chan_allocation(struct bt_audio_codec_cfg *codec_cfg, enum bt_audio_location chan_allocation)

Set the channel allocation of a codec configuration.

Parameters:
  • codec_cfg – The codec configuration to set data for.

  • chan_allocation – The channel allocation to set.

Return values:
  • The – data_len of codec_cfg on success

  • -EINVAL – if arguments are invalid

  • -ENOMEM – if the new value could not set or added due to memory

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.

Return values:
  • Frame – length in octets

  • -EINVAL – if arguments are invalid

  • -ENODATA – if not found

  • -EBADMSG – if found value has invalid size or value

int bt_audio_codec_cfg_set_octets_per_frame(struct bt_audio_codec_cfg *codec_cfg, uint16_t octets_per_frame)

Set the octets per codec frame of a codec configuration.

Parameters:
  • codec_cfg – The codec configuration to set data for.

  • octets_per_frame – The octets per codec frame to set.

Return values:
  • The – data_len of codec_cfg on success

  • -EINVAL – if arguments are invalid

  • -ENOMEM – if the new value could not set or added due to memory

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.

Return values:
  • The – count of codec frames in each SDU if value is found else of fallback_to_default is true then the value 1 is returned if frames per sdu is not found.

  • -EINVAL – if arguments are invalid

  • -ENODATA – if not found

  • -EBADMSG – if found value has invalid size or value

int bt_audio_codec_cfg_set_frame_blocks_per_sdu(struct bt_audio_codec_cfg *codec_cfg, uint8_t frame_blocks)

Set the frame blocks per SDU of a codec configuration.

Parameters:
  • codec_cfg – The codec configuration to set data for.

  • frame_blocks – The frame blocks per SDU to set.

Return values:
  • The – data_len of codec_cfg on success

  • -EINVAL – if arguments are invalid

  • -ENOMEM – if the new value could not set or added due to memory

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

Lookup a specific codec configuration value.

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

Return values:
  • Length – of found data (may be 0)

  • -EINVAL – if arguments are invalid

  • -ENODATA – if not found

int bt_audio_codec_cfg_set_val(struct bt_audio_codec_cfg *codec_cfg, enum bt_audio_codec_cfg_type type, const uint8_t *data, size_t data_len)

Set or add a specific codec configuration value.

Parameters:
  • codec_cfg – The codec data to set the value in.

  • type – The type id to set

  • data – Pointer to the data-pointer to set

  • data_len – Length of data

Return values:
  • The – data_len of codec_cfg on success

  • -EINVAL – if arguments are invalid

  • -ENOMEM – if the new value could not set or added due to memory

int bt_audio_codec_cfg_unset_val(struct bt_audio_codec_cfg *codec_cfg, enum bt_audio_codec_cfg_type type)

Unset a specific codec configuration value.

The type and the value will be removed from the codec configuration.

Parameters:
  • codec_cfg – The codec data to set the value in.

  • type – The type id to unset.

Return values:
  • The – data_len of codec_cfg on success

  • -EINVAL – if arguments are invalid

int bt_audio_codec_cfg_meta_get_val(const struct bt_audio_codec_cfg *codec_cfg, uint8_t type, const uint8_t **data)

Lookup a specific metadata value based on 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

Return values:
  • Length – of found data (may be 0)

  • -EINVAL – if arguments are invalid

  • -ENODATA – if not found

int bt_audio_codec_cfg_meta_set_val(struct bt_audio_codec_cfg *codec_cfg, enum bt_audio_metadata_type type, const uint8_t *data, size_t data_len)

Set or add a specific codec configuration metadata value.

Parameters:
  • codec_cfg – The codec configuration to set the value in.

  • type – The type id to set.

  • data – Pointer to the data-pointer to set.

  • data_len – Length of data.

Return values:
  • The – meta_len of codec_cfg on success

  • -EINVAL – if arguments are invalid

  • -ENOMEM – if the new value could not set or added due to memory

int bt_audio_codec_cfg_meta_unset_val(struct bt_audio_codec_cfg *codec_cfg, enum bt_audio_metadata_type type)

Unset a specific codec configuration metadata value.

The type and the value will be removed from the codec configuration metadata.

Parameters:
  • codec_cfg – The codec data to set the value in.

  • type – The type id to unset.

Return values:
  • The – meta_len of codec_cfg on success

  • -EINVAL – if arguments are invalid

int bt_audio_codec_cfg_meta_get_pref_context(const struct bt_audio_codec_cfg *codec_cfg)

Extract preferred contexts.

See BT_AUDIO_METADATA_TYPE_PREF_CONTEXT for more information about this value.

Parameters:
  • codec_cfg – The codec data to search in.

Return values:
  • The – preferred context type if positive or 0

  • -EINVAL – if arguments are invalid

  • -ENODATA – if not found

  • -EBADMSG – if found value has invalid size

int bt_audio_codec_cfg_meta_set_pref_context(struct bt_audio_codec_cfg *codec_cfg, enum bt_audio_context ctx)

Set the preferred context of a codec configuration metadata.

Parameters:
  • codec_cfg – The codec configuration to set data for.

  • ctx – The preferred context to set.

Return values:
  • The – data_len of codec_cfg on success

  • -EINVAL – if arguments are invalid

  • -ENOMEM – if the new value could not set or added due to memory

int bt_audio_codec_cfg_meta_get_stream_context(const struct bt_audio_codec_cfg *codec_cfg)

Extract stream contexts.

See BT_AUDIO_METADATA_TYPE_STREAM_CONTEXT for more information about this value.

Parameters:
  • codec_cfg – The codec data to search in.

Return values:
  • The – stream context type if positive or 0

  • -EINVAL – if arguments are invalid

  • -ENODATA – if not found

  • -EBADMSG – if found value has invalid size

int bt_audio_codec_cfg_meta_set_stream_context(struct bt_audio_codec_cfg *codec_cfg, enum bt_audio_context ctx)

Set the stream context of a codec configuration metadata.

Parameters:
  • codec_cfg – The codec configuration to set data for.

  • ctx – The stream context to set.

Return values:
  • The – data_len of codec_cfg on success

  • -EINVAL – if arguments are invalid

  • -ENOMEM – if the new value could not set or added due to memory

int bt_audio_codec_cfg_meta_get_program_info(const struct bt_audio_codec_cfg *codec_cfg, const uint8_t **program_info)

Extract program info.

See BT_AUDIO_METADATA_TYPE_PROGRAM_INFO for more information about this value.

Parameters:
  • codec_cfg[in] The codec data to search in.

  • program_info[out] Pointer to the UTF-8 formatted program info.

Return values:
  • The – length of the program_info (may be 0)

  • -EINVAL – if arguments are invalid

  • -ENODATA – if not found

int bt_audio_codec_cfg_meta_set_program_info(struct bt_audio_codec_cfg *codec_cfg, const uint8_t *program_info, size_t program_info_len)

Set the program info of a codec configuration metadata.

Parameters:
  • codec_cfg – The codec configuration to set data for.

  • program_info – The program info to set.

  • program_info_len – The length of program_info.

Return values:
  • The – data_len of codec_cfg on success

  • -EINVAL – if arguments are invalid

  • -ENOMEM – if the new value could not set or added due to memory

int bt_audio_codec_cfg_meta_get_stream_lang(const struct bt_audio_codec_cfg *codec_cfg)

Extract stream language.

See BT_AUDIO_METADATA_TYPE_STREAM_LANG for more information about this value.

Parameters:
  • codec_cfg – The codec data to search in.

Return values:
  • The – stream language if positive or 0

  • -EINVAL – if arguments are invalid

  • -ENODATA – if not found

  • -EBADMSG – if found value has invalid size

int bt_audio_codec_cfg_meta_set_stream_lang(struct bt_audio_codec_cfg *codec_cfg, uint32_t stream_lang)

Set the stream language of a codec configuration metadata.

Parameters:
  • codec_cfg – The codec configuration to set data for.

  • stream_lang – The 24-bit stream language to set.

Return values:
  • The – data_len of codec_cfg on success

  • -EINVAL – if arguments are invalid

  • -ENOMEM – if the new value could not set or added due to memory

int bt_audio_codec_cfg_meta_get_ccid_list(const struct bt_audio_codec_cfg *codec_cfg, const uint8_t **ccid_list)

Extract CCID list.

See BT_AUDIO_METADATA_TYPE_CCID_LIST for more information about this value.

Parameters:
  • codec_cfg[in] The codec data to search in.

  • ccid_list[out] Pointer to the array containing 8-bit CCIDs.

Return values:
  • The – length of the ccid_list (may be 0)

  • -EINVAL – if arguments are invalid

  • -ENODATA – if not found

int bt_audio_codec_cfg_meta_set_ccid_list(struct bt_audio_codec_cfg *codec_cfg, const uint8_t *ccid_list, size_t ccid_list_len)

Set the CCID list of a codec configuration metadata.

Parameters:
  • codec_cfg – The codec configuration to set data for.

  • ccid_list – The program info to set.

  • ccid_list_len – The length of ccid_list.

Return values:
  • The – data_len of codec_cfg on success

  • -EINVAL – if arguments are invalid

  • -ENOMEM – if the new value could not set or added due to memory

int bt_audio_codec_cfg_meta_get_parental_rating(const struct bt_audio_codec_cfg *codec_cfg)

Extract parental rating.

See BT_AUDIO_METADATA_TYPE_PARENTAL_RATING for more information about this value.

Parameters:
  • codec_cfg – The codec data to search in.

Return values:
  • The – parental rating if positive or 0

  • -EINVAL – if arguments are invalid

  • -ENODATA – if not found

  • -EBADMSG – if found value has invalid size

int bt_audio_codec_cfg_meta_set_parental_rating(struct bt_audio_codec_cfg *codec_cfg, enum bt_audio_parental_rating parental_rating)

Set the parental rating of a codec configuration metadata.

Parameters:
  • codec_cfg – The codec configuration to set data for.

  • parental_rating – The parental rating to set.

Return values:
  • The – data_len of codec_cfg on success

  • -EINVAL – if arguments are invalid

  • -ENOMEM – if the new value could not set or added due to memory

int bt_audio_codec_cfg_meta_get_program_info_uri(const struct bt_audio_codec_cfg *codec_cfg, const uint8_t **program_info_uri)

Extract program info URI.

See BT_AUDIO_METADATA_TYPE_PROGRAM_INFO_URI for more information about this value.

Parameters:
  • codec_cfg[in] The codec data to search in.

  • program_info_uri[out] Pointer to the UTF-8 formatted program info URI.

Return values:
  • The – length of the ccid_list (may be 0)

  • -EINVAL – if arguments are invalid

  • -ENODATA – if not found

int bt_audio_codec_cfg_meta_set_program_info_uri(struct bt_audio_codec_cfg *codec_cfg, const uint8_t *program_info_uri, size_t program_info_uri_len)

Set the program info URI of a codec configuration metadata.

Parameters:
  • codec_cfg – The codec configuration to set data for.

  • program_info_uri – The program info URI to set.

  • program_info_uri_len – The length of program_info_uri.

Return values:
  • The – data_len of codec_cfg on success

  • -EINVAL – if arguments are invalid

  • -ENOMEM – if the new value could not set or added due to memory

int bt_audio_codec_cfg_meta_get_audio_active_state(const struct bt_audio_codec_cfg *codec_cfg)

Extract audio active state.

See BT_AUDIO_METADATA_TYPE_AUDIO_STATE for more information about this value.

Parameters:
  • codec_cfg – The codec data to search in.

Return values:
  • The – preferred context type if positive or 0

  • -EINVAL – if arguments are invalid

  • -ENODATA – if not found

  • -EBADMSG – if found value has invalid size

int bt_audio_codec_cfg_meta_set_audio_active_state(struct bt_audio_codec_cfg *codec_cfg, enum bt_audio_active_state state)

Set the audio active state of a codec configuration metadata.

Parameters:
  • codec_cfg – The codec configuration to set data for.

  • state – The audio active state to set.

Return values:
  • The – data_len of codec_cfg on success

  • -EINVAL – if arguments are invalid

  • -ENOMEM – if the new value could not set or added due to memory

int bt_audio_codec_cfg_meta_get_bcast_audio_immediate_rend_flag(const struct bt_audio_codec_cfg *codec_cfg)

Extract broadcast audio immediate rendering flag.

See BT_AUDIO_METADATA_TYPE_BROADCAST_IMMEDIATE for more information about this value.

Parameters:
  • codec_cfg – The codec data to search in.

Return values:
  • 0 – if the flag was found

  • -EINVAL – if arguments are invalid

  • -ENODATA – if not the flag was not found

int bt_audio_codec_cfg_meta_set_bcast_audio_immediate_rend_flag(struct bt_audio_codec_cfg *codec_cfg)

Set the broadcast audio immediate rendering flag of a codec configuration metadata.

Parameters:
  • codec_cfg – The codec configuration to set data for.

Return values:
  • The – data_len of codec_cfg on success

  • -EINVAL – if arguments are invalid

  • -ENOMEM – if the new value could not set or added due to memory

int bt_audio_codec_cfg_meta_get_extended(const struct bt_audio_codec_cfg *codec_cfg, const uint8_t **extended_meta)

Extract extended metadata.

See BT_AUDIO_METADATA_TYPE_EXTENDED for more information about this value.

Parameters:
  • codec_cfg[in] The codec data to search in.

  • extended_meta[out] Pointer to the extended metadata.

Return values:
  • The – length of the ccid_list (may be 0)

  • -EINVAL – if arguments are invalid

  • -ENODATA – if not found

int bt_audio_codec_cfg_meta_set_extended(struct bt_audio_codec_cfg *codec_cfg, const uint8_t *extended_meta, size_t extended_meta_len)

Set the extended metadata of a codec configuration metadata.

Parameters:
  • codec_cfg – The codec configuration to set data for.

  • extended_meta – The extended metadata to set.

  • extended_meta_len – The length of extended_meta.

Return values:
  • The – data_len of codec_cfg on success

  • -EINVAL – if arguments are invalid

  • -ENOMEM – if the new value could not set or added due to memory

int bt_audio_codec_cfg_meta_get_vendor(const struct bt_audio_codec_cfg *codec_cfg, const uint8_t **vendor_meta)

Extract vendor specific metadata.

See BT_AUDIO_METADATA_TYPE_VENDOR for more information about this value.

Parameters:
  • codec_cfg[in] The codec data to search in.

  • vendor_meta[out] Pointer to the vendor specific metadata.

Return values:
  • The – length of the ccid_list (may be 0)

  • -EINVAL – if arguments are invalid

  • -ENODATA – if not found

int bt_audio_codec_cfg_meta_set_vendor(struct bt_audio_codec_cfg *codec_cfg, const uint8_t *vendor_meta, size_t vendor_meta_len)

Set the vendor specific metadata of a codec configuration metadata.

Parameters:
  • codec_cfg – The codec configuration to set data for.

  • vendor_meta – The vendor specific metadata to set.

  • vendor_meta_len – The length of vendor_meta.

Return values:
  • The – data_len of codec_cfg on success

  • -EINVAL – if arguments are invalid

  • -ENOMEM – if the new value could not set or added due to memory