ESP-BLE-AUDIO

ESP-BLE-AUDIO provides APIs for Bluetooth LE Audio, enabling time-synchronized audio over BLE using the Bluetooth Core Specification LE Audio architecture. Applications can implement unicast (one-to-one) and broadcast audio scenarios, including hearing aids, headsets, speakers, and broadcast sources/sinks.

The LE Audio stack is built on the Bluetooth Core and the LC3 codec. The generic audio framework includes the Common Audio Profile (CAP), Common Audio Service (CAS), and the profiles and services below. Use case specific profiles (HAP, GMAP, TMAP, PBP) sit on top of the generic framework. LE Audio runs over the LE Isochronous Channels (CIS/BIS) supported by ESP-BLE-ISO.

Warning

This is a preview release. The ESP-BLE-AUDIO APIs, data structures, and configuration parameters are subject to change in future releases. Breaking changes — such as renamed or restructured types, modified function signatures, or removed fields — may be introduced without prior notice.

Generic audio framework

• Common Audio Profile (CAP) — Top-level profile for coordinating audio procedures across single or multiple devices.

• Common Audio Service (CAS) — GATT service companion to CAP; used for coordinated set member announcement.

• Basic Audio Profile (BAP) — Unicast and broadcast stream setup, codec configuration, and stream control.

• Published Audio Capabilities Service (PACS) — Advertising and negotiating audio capabilities.

• Audio Stream Control Service (ASCS) — Exposes sink/source audio endpoints on a BAP Unicast Server; used by the Unicast Client to configure and control streams.

• Broadcast Audio Scan Service (BASS) — Allows a Broadcast Assistant to offload BIS scanning from a low-power Scan Delegator.

• Volume Control Profile (VCP) — Volume control (VCS, VOCS, AICS).

• Volume Offset Control Service (VOCS) — Per-output volume offset.

• Audio Input Control Service (AICS) — Audio input (microphone) state and gain.

• Microphone Control Profile (MICP) — Microphone mute and gain (MICS).

• Coordinated Set Identification Profile (CSIP) — Set member identification for coordinated sets (e.g., left/right earbuds).

• Media Control Profile (MCP) — Media control (MCS).

• Media Control Service (MCS) — Media control service.

• Call Control Profile (CCP) — Call/telephony control (TBS).

• Telephone Bearer Service (TBS) — Telephony bearer and in-call control.

• Media Proxy — Media proxy service (Zephyr implementation component; not a Bluetooth SIG specification).

Use case specific profiles

• Hearing Access Profile (HAP) — Hearing aid presets and presets control.

• Gaming Audio Profile (GMAP) — Gaming audio (e.g. Unicast Game Gateway/Terminal, Broadcast Game Sender/Receiver).

• Telephony and Media Audio Profile (TMAP) — Interoperability configurations for telephony and media audio use cases.

• Public Broadcast Profile (PBP) — Discovery and subscription to public broadcast streams.

Application Examples

• BAP (Basic Audio Profile)

  • bluetooth/esp_ble_audio/bap/broadcast_sink demonstrates how to act as a BAP Broadcast Sink that synchronizes to a broadcast source and receives BIS audio streams.

  • bluetooth/esp_ble_audio/bap/broadcast_source demonstrates how to act as a BAP Broadcast Source that creates a BIG and sends broadcast audio over BIS.

  • bluetooth/esp_ble_audio/bap/unicast_client demonstrates how to discover and connect to a unicast server and establish BAP unicast streams.

  • bluetooth/esp_ble_audio/bap/unicast_server demonstrates how to advertise and accept unicast connections and serve BAP unicast streams.

• CAP (Common Audio Profile)

  • bluetooth/esp_ble_audio/cap/acceptor demonstrates how to act as a CAP Acceptor for unicast and broadcast flows.

  • bluetooth/esp_ble_audio/cap/initiator demonstrates how to act as a CAP Initiator for unicast and broadcast flows.

• TMAP (Telephony and Media Audio Profile)

  • bluetooth/esp_ble_audio/tmap/bmr demonstrates the TMAP Broadcast Media Receiver (BMR) role that receives broadcast audio from a BMS.

  • bluetooth/esp_ble_audio/tmap/bms demonstrates the TMAP Broadcast Media Sender (BMS) role that sends broadcast audio.

  • bluetooth/esp_ble_audio/tmap/central demonstrates the TMAP Call Gateway (CG) and Unicast Media Sender (UMS) roles.

  • bluetooth/esp_ble_audio/tmap/peripheral demonstrates the TMAP Call Terminal (CT) and Unicast Media Receiver (UMR) roles.

API Reference

ESP-BLE-AUDIO APIs are divided into the following parts:

• Definitions

  • General Definitions

  • LC3 Codec Definitions

  • MCS Definitions

  • BAP LC3 Preset Definitions

  • GMAP LC3 Preset Definitions

• API

  • Common API

  • Codec API

  • Common Audio Profile (CAP)

  • Call Control Profile (CCP)

  • Basic Audio Profile (BAP)

  • Published Audio Capabilities (PACS)

  • Gaming Audio Profile (GMAP)

  • Volume Control Profile (VCP)

  • Volume Offset Control Service (VOCS)

  • Audio Input Control Service (AICS)

  • Microphone Control Profile (MICP)

  • Hearing Access Profile (HAP)

  • Coordinated Set Identification Profile (CSIP)

  • Telephone Bearer Service (TBS)

  • Media Control Client (MCC)

  • Media Proxy

  • Telephony and Media Audio Profile (TMAP)

  • Public Broadcast Profile (PBP)

ESP-BLE-AUDIO Definitions

This section contains common definitions, constants, and types used across LE Audio.

General Definitions

Header File

• components/bt/esp_ble_audio/api/include/esp_ble_audio_defs.h

• This header file can be included with:

  #include "esp_ble_audio_defs.h"
  

• This header file is a part of the API provided by the bt component. To declare that your component depends on bt, add the following to your CMakeLists.txt:

  REQUIRES bt
  

  or

  PRIV_REQUIRES bt
  

Macros

ESP_BLE_AUDIO_ATT_MTU_MIN

< Minimum ATT MTU size required by Basic Audio Profile (BAP)

ESP_BLE_AUDIO_DIR_SINK

Audio direction sink.

For a BAP Unicast Client or Broadcast Source this is considered outgoing audio (TX). For a BAP Unicast Server or Broadcast Sink this is considered incoming audio (RX).

ESP_BLE_AUDIO_DIR_SOURCE

Audio direction source.

For a BAP Unicast Client or Broadcast Source this is considered incoming audio (RX). For a BAP Unicast Server or Broadcast Sink this is considered outgoing audio (TX).

ESP_BLE_AUDIO_LANG_SIZE

Size of the broadcast ID in octets

ESP_BLE_AUDIO_BROADCAST_ID_SIZE

Maximum broadcast ID value

ESP_BLE_AUDIO_BROADCAST_ID_MAX

Indicates that the server have no preference for the presentation delay

ESP_BLE_AUDIO_PD_PREF_NONE

Maximum presentation delay in microseconds

ESP_BLE_AUDIO_PD_MAX

Indicates that the unicast server does not have a preference for any retransmission number

ESP_BLE_AUDIO_RTN_PREF_NONE

The minimum size of a Broadcast Name as defined by Bluetooth Assigned Numbers

ESP_BLE_AUDIO_BROADCAST_NAME_LEN_MIN

The maximum size of a Broadcast Name as defined by Bluetooth Assigned Numbers

ESP_BLE_AUDIO_BROADCAST_NAME_LEN_MAX

Unicast Server is connectable and is requesting a connection.

ESP_BLE_AUDIO_UNICAST_ANNOUNCEMENT_GENERAL

Unicast Server is connectable but is not requesting a connection.

ESP_BLE_AUDIO_UNICAST_ANNOUNCEMENT_TARGETED

No context type

ESP_BLE_AUDIO_CONTEXT_TYPE_NONE

ESP_BLE_AUDIO_CONTEXT_TYPE_UNSPECIFIED

Identifies audio where the use case context does not match any other defined value, or where the context is unknown or cannot be determined.

ESP_BLE_AUDIO_CONTEXT_TYPE_CONVERSATIONAL

Conversation between humans, for example, in telephony or video calls, including traditional cellular as well as VoIP and Push-to-Talk Media, for example, music playback, radio, podcast or movie soundtrack, or tv audio

ESP_BLE_AUDIO_CONTEXT_TYPE_MEDIA

ESP_BLE_AUDIO_CONTEXT_TYPE_GAME

Audio associated with video gaming, for example gaming media; gaming effects; music and in-game voice chat between participants; or a mix of all the above Instructional audio, for example, in navigation, announcements, or user guidance

ESP_BLE_AUDIO_CONTEXT_TYPE_INSTRUCTIONAL

Man-machine communication, for example, with voice recognition or virtual assistants

ESP_BLE_AUDIO_CONTEXT_TYPE_VOICE_ASSISTANTS

ESP_BLE_AUDIO_CONTEXT_TYPE_LIVE

Live audio, for example, from a microphone where audio is perceived both through a direct acoustic path and through an LE Audio Stream

ESP_BLE_AUDIO_CONTEXT_TYPE_SOUND_EFFECTS

Sound effects including keyboard and touch feedback; menu and user interface sounds; and other system sounds

ESP_BLE_AUDIO_CONTEXT_TYPE_NOTIFICATIONS

Notification and reminder sounds; attention-seeking audio, for example, in beeps signaling the arrival of a message

ESP_BLE_AUDIO_CONTEXT_TYPE_RINGTONE

Alerts the user to an incoming call, for example, an incoming telephony or video call, including traditional cellular as well as VoIP and Push-to-Talk

ESP_BLE_AUDIO_CONTEXT_TYPE_ALERTS

Alarms and timers; immediate alerts, for example, in a critical battery alarm, timer expiry or alarm clock, toaster, cooker, kettle, microwave, etc. Emergency alarm Emergency sounds, for example, fire alarms or other urgent alerts

ESP_BLE_AUDIO_CONTEXT_TYPE_EMERGENCY_ALARM

Any known context

ESP_BLE_AUDIO_CONTEXT_TYPE_ANY

ESP_BLE_AUDIO_PARENTAL_RATING_NO_RATING

For all ages

ESP_BLE_AUDIO_PARENTAL_RATING_AGE_ANY

Recommended for listeners of age 5 and above

ESP_BLE_AUDIO_PARENTAL_RATING_AGE_5_OR_ABOVE

Recommended for listeners of age 6 and above

ESP_BLE_AUDIO_PARENTAL_RATING_AGE_6_OR_ABOVE

Recommended for listeners of age 7 and above

ESP_BLE_AUDIO_PARENTAL_RATING_AGE_7_OR_ABOVE

Recommended for listeners of age 8 and above

ESP_BLE_AUDIO_PARENTAL_RATING_AGE_8_OR_ABOVE

Recommended for listeners of age 9 and above

ESP_BLE_AUDIO_PARENTAL_RATING_AGE_9_OR_ABOVE

Recommended for listeners of age 10 and above

ESP_BLE_AUDIO_PARENTAL_RATING_AGE_10_OR_ABOVE

Recommended for listeners of age 11 and above

ESP_BLE_AUDIO_PARENTAL_RATING_AGE_11_OR_ABOVE

Recommended for listeners of age 12 and above

ESP_BLE_AUDIO_PARENTAL_RATING_AGE_12_OR_ABOVE

Recommended for listeners of age 13 and above

ESP_BLE_AUDIO_PARENTAL_RATING_AGE_13_OR_ABOVE

Recommended for listeners of age 14 and above

ESP_BLE_AUDIO_PARENTAL_RATING_AGE_14_OR_ABOVE

Recommended for listeners of age 15 and above

ESP_BLE_AUDIO_PARENTAL_RATING_AGE_15_OR_ABOVE

Recommended for listeners of age 16 and above

ESP_BLE_AUDIO_PARENTAL_RATING_AGE_16_OR_ABOVE

Recommended for listeners of age 17 and above

ESP_BLE_AUDIO_PARENTAL_RATING_AGE_17_OR_ABOVE

Recommended for listeners of age 18 and above

ESP_BLE_AUDIO_PARENTAL_RATING_AGE_18_OR_ABOVE

ESP_BLE_AUDIO_ACTIVE_STATE_DISABLED

Audio data is being transmitted

ESP_BLE_AUDIO_ACTIVE_STATE_ENABLED

ESP_BLE_AUDIO_METADATA_TYPE_PREF_CONTEXT

Streaming audio context

ESP_BLE_AUDIO_METADATA_TYPE_STREAM_CONTEXT

UTF-8 encoded title or summary of stream content

ESP_BLE_AUDIO_METADATA_TYPE_PROGRAM_INFO

Language

ESP_BLE_AUDIO_METADATA_TYPE_LANG

Array of 8-bit CCID values

ESP_BLE_AUDIO_METADATA_TYPE_CCID_LIST

Parental rating

ESP_BLE_AUDIO_METADATA_TYPE_PARENTAL_RATING

UTF-8 encoded URI for additional Program information

ESP_BLE_AUDIO_METADATA_TYPE_PROGRAM_INFO_URI

Audio active state

ESP_BLE_AUDIO_METADATA_TYPE_AUDIO_STATE

Broadcast Audio Immediate Rendering flag

ESP_BLE_AUDIO_METADATA_TYPE_BROADCAST_IMMEDIATE

Assisted listening stream

ESP_BLE_AUDIO_METADATA_TYPE_ASSISTED_LISTENING_STREAM

UTF-8 encoded Broadcast name

ESP_BLE_AUDIO_METADATA_TYPE_BROADCAST_NAME

Extended metadata

ESP_BLE_AUDIO_METADATA_TYPE_EXTENDED

Vendor specific metadata

ESP_BLE_AUDIO_METADATA_TYPE_VENDOR

ESP_BLE_AUDIO_METADATA_TYPE_IS_KNOWN(_type)

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

Parameters:

• _type -- Metadata type.

ESP_BLE_AUDIO_LOCATION_MONO_AUDIO

Front Left

ESP_BLE_AUDIO_LOCATION_FRONT_LEFT

Front Right

ESP_BLE_AUDIO_LOCATION_FRONT_RIGHT

Front Center

ESP_BLE_AUDIO_LOCATION_FRONT_CENTER

Low Frequency Effects 1

ESP_BLE_AUDIO_LOCATION_LOW_FREQ_EFFECTS_1

Back Left

ESP_BLE_AUDIO_LOCATION_BACK_LEFT

Back Right

ESP_BLE_AUDIO_LOCATION_BACK_RIGHT

Front Left of Center

ESP_BLE_AUDIO_LOCATION_FRONT_LEFT_OF_CENTER

Front Right of Center

ESP_BLE_AUDIO_LOCATION_FRONT_RIGHT_OF_CENTER

Back Center

ESP_BLE_AUDIO_LOCATION_BACK_CENTER

Low Frequency Effects 2

ESP_BLE_AUDIO_LOCATION_LOW_FREQ_EFFECTS_2

Side Left

ESP_BLE_AUDIO_LOCATION_SIDE_LEFT

Side Right

ESP_BLE_AUDIO_LOCATION_SIDE_RIGHT

Top Front Left

ESP_BLE_AUDIO_LOCATION_TOP_FRONT_LEFT

Top Front Right

ESP_BLE_AUDIO_LOCATION_TOP_FRONT_RIGHT

Top Front Center

ESP_BLE_AUDIO_LOCATION_TOP_FRONT_CENTER

Top Center

ESP_BLE_AUDIO_LOCATION_TOP_CENTER

Top Back Left

ESP_BLE_AUDIO_LOCATION_TOP_BACK_LEFT

Top Back Right

ESP_BLE_AUDIO_LOCATION_TOP_BACK_RIGHT

Top Side Left

ESP_BLE_AUDIO_LOCATION_TOP_SIDE_LEFT

Top Side Right

ESP_BLE_AUDIO_LOCATION_TOP_SIDE_RIGHT

Top Back Center

ESP_BLE_AUDIO_LOCATION_TOP_BACK_CENTER

Bottom Front Center

ESP_BLE_AUDIO_LOCATION_BOTTOM_FRONT_CENTER

Bottom Front Left

ESP_BLE_AUDIO_LOCATION_BOTTOM_FRONT_LEFT

Bottom Front Right

ESP_BLE_AUDIO_LOCATION_BOTTOM_FRONT_RIGHT

Front Left Wide

ESP_BLE_AUDIO_LOCATION_FRONT_LEFT_WIDE

Front Right Wide

ESP_BLE_AUDIO_LOCATION_FRONT_RIGHT_WIDE

Left Surround

ESP_BLE_AUDIO_LOCATION_LEFT_SURROUND

Right Surround

ESP_BLE_AUDIO_LOCATION_RIGHT_SURROUND

Any known location

ESP_BLE_AUDIO_LOCATION_ANY

ESP_BLE_AUDIO_ASSISTED_LISTENING_STREAM_UNSPECIFIED

ESP_BLE_AUDIO_UUID_SIZE_16

Audio Input Control Service UUID value

ESP_BLE_AUDIO_UUID_AICS_VAL

Audio Stream Control Service UUID value

ESP_BLE_AUDIO_UUID_ASCS_VAL

Broadcast Audio Scan Service UUID value

ESP_BLE_AUDIO_UUID_BASS_VAL

Basic Audio Announcement Service UUID value

ESP_BLE_AUDIO_UUID_BASIC_AUDIO_VAL

Broadcast Audio Announcement Service UUID value

ESP_BLE_AUDIO_UUID_BROADCAST_AUDIO_VAL

Common Audio Service UUID value

ESP_BLE_AUDIO_UUID_CAS_VAL

Coordinated Set Identification Service UUID value

ESP_BLE_AUDIO_UUID_CSIS_VAL

Gaming Service UUID value

ESP_BLE_AUDIO_UUID_GMAS_VAL

Generic Media Control Service UUID value

ESP_BLE_AUDIO_UUID_GMCS_VAL

Generic Telephone Bearer Service UUID value

ESP_BLE_AUDIO_UUID_GTBS_VAL

Hearing Access Service UUID value

ESP_BLE_AUDIO_UUID_HAS_VAL

Media Control Service UUID value

ESP_BLE_AUDIO_UUID_MCS_VAL

Microphone Control Service UUID value

ESP_BLE_AUDIO_UUID_MICS_VAL

Published Audio Capabilities Service UUID value

ESP_BLE_AUDIO_UUID_PACS_VAL

Public Broadcast Announcement Service UUID value

ESP_BLE_AUDIO_UUID_PBA_VAL

Telephone Bearer Service UUID value

ESP_BLE_AUDIO_UUID_TBS_VAL

Telephony and Media Audio Service UUID value

ESP_BLE_AUDIO_UUID_TMAS_VAL

Volume Control Service UUID value

ESP_BLE_AUDIO_UUID_VCS_VAL

Volume Offset Control Service UUID value

ESP_BLE_AUDIO_UUID_VOCS_VAL

Object Transfer Service UUID value

ESP_BLE_AUDIO_UUID_OTS_VAL

Audio Input Control Service State value

ESP_BLE_AUDIO_UUID_AICS_STATE_VAL

Audio Input Control Service Gain Settings Properties value

ESP_BLE_AUDIO_UUID_AICS_GAIN_SETTINGS_VAL

Audio Input Control Service Input Type value

ESP_BLE_AUDIO_UUID_AICS_INPUT_TYPE_VAL

Audio Input Control Service Input Status value

ESP_BLE_AUDIO_UUID_AICS_INPUT_STATUS_VAL

Audio Input Control Service Control Point value

ESP_BLE_AUDIO_UUID_AICS_CONTROL_VAL

Audio Input Control Service Input Description value

ESP_BLE_AUDIO_UUID_AICS_DESCRIPTION_VAL

Audio Stream Endpoint Sink Characteristic value

ESP_BLE_AUDIO_UUID_ASCS_ASE_SNK_VAL

Audio Stream Endpoint Source Characteristic value

ESP_BLE_AUDIO_UUID_ASCS_ASE_SRC_VAL

Audio Stream Endpoint Control Point Characteristic value

ESP_BLE_AUDIO_UUID_ASCS_ASE_CP_VAL

Broadcast Audio Scan Service Scan State value

ESP_BLE_AUDIO_UUID_BASS_CONTROL_POINT_VAL

Broadcast Audio Scan Service Receive State value

ESP_BLE_AUDIO_UUID_BASS_RECV_STATE_VAL

Set Identity Resolving Key value

ESP_BLE_AUDIO_UUID_CSIS_SIRK_VAL

Set size value

ESP_BLE_AUDIO_UUID_CSIS_SET_SIZE_VAL

Set lock value

ESP_BLE_AUDIO_UUID_CSIS_SET_LOCK_VAL

Rank value

ESP_BLE_AUDIO_UUID_CSIS_RANK_VAL

Gaming Audio Profile Role UUID value

ESP_BLE_AUDIO_UUID_GMAP_ROLE_VAL

Gaming Audio Profile Unicast Game Gateway Features UUID value

ESP_BLE_AUDIO_UUID_GMAP_UGG_FEAT_VAL

Gaming Audio Profile Unicast Game Terminal Features UUID value

ESP_BLE_AUDIO_UUID_GMAP_UGT_FEAT_VAL

Gaming Audio Profile Broadcast Game Sender Features UUID value

ESP_BLE_AUDIO_UUID_GMAP_BGS_FEAT_VAL

Gaming Audio Profile Broadcast Game Receiver Features UUID value

ESP_BLE_AUDIO_UUID_GMAP_BGR_FEAT_VAL

Hearing Aid Features Characteristic value

ESP_BLE_AUDIO_UUID_HAS_HEARING_AID_FEATURES_VAL

Hearing Aid Preset Control Point Characteristic value

ESP_BLE_AUDIO_UUID_HAS_PRESET_CONTROL_POINT_VAL

Hearing Aid Active Preset Index Characteristic value

ESP_BLE_AUDIO_UUID_HAS_ACTIVE_PRESET_INDEX_VAL

Media player name value

ESP_BLE_AUDIO_UUID_MCS_PLAYER_NAME_VAL

Media Icon Object ID value

ESP_BLE_AUDIO_UUID_MCS_ICON_OBJ_ID_VAL

Media Icon URL value

ESP_BLE_AUDIO_UUID_MCS_ICON_URL_VAL

Track Changed value

ESP_BLE_AUDIO_UUID_MCS_TRACK_CHANGED_VAL

Track Title value

ESP_BLE_AUDIO_UUID_MCS_TRACK_TITLE_VAL

Track Duration value

ESP_BLE_AUDIO_UUID_MCS_TRACK_DURATION_VAL

Track Position value

ESP_BLE_AUDIO_UUID_MCS_TRACK_POSITION_VAL

Playback Speed value

ESP_BLE_AUDIO_UUID_MCS_PLAYBACK_SPEED_VAL

Seeking Speed value

ESP_BLE_AUDIO_UUID_MCS_SEEKING_SPEED_VAL

Track Segments Object ID value

ESP_BLE_AUDIO_UUID_MCS_TRACK_SEGMENTS_OBJ_ID_VAL

Current Track Object ID value

ESP_BLE_AUDIO_UUID_MCS_CURRENT_TRACK_OBJ_ID_VAL

Next Track Object ID value

ESP_BLE_AUDIO_UUID_MCS_NEXT_TRACK_OBJ_ID_VAL

Parent Group Object ID value

ESP_BLE_AUDIO_UUID_MCS_PARENT_GROUP_OBJ_ID_VAL

Group Object ID value

ESP_BLE_AUDIO_UUID_MCS_CURRENT_GROUP_OBJ_ID_VAL

Playing Order value

ESP_BLE_AUDIO_UUID_MCS_PLAYING_ORDER_VAL

Playing Orders supported value

ESP_BLE_AUDIO_UUID_MCS_PLAYING_ORDERS_VAL

Media State value

ESP_BLE_AUDIO_UUID_MCS_MEDIA_STATE_VAL

Media Control Point value

ESP_BLE_AUDIO_UUID_MCS_MEDIA_CONTROL_POINT_VAL

Media control opcodes supported value

ESP_BLE_AUDIO_UUID_MCS_MEDIA_CONTROL_OPCODES_VAL

Search result object ID value

ESP_BLE_AUDIO_UUID_MCS_SEARCH_RESULTS_OBJ_ID_VAL

Search control point value

ESP_BLE_AUDIO_UUID_MCS_SEARCH_CONTROL_POINT_VAL

Microphone Control Service Mute value

ESP_BLE_AUDIO_UUID_MICS_MUTE_VAL

Sink PAC Characteristic value

ESP_BLE_AUDIO_UUID_PACS_SNK_VAL

Sink PAC Locations Characteristic value

ESP_BLE_AUDIO_UUID_PACS_SNK_LOC_VAL

Source PAC Characteristic value

ESP_BLE_AUDIO_UUID_PACS_SRC_VAL

Source PAC Locations Characteristic value

ESP_BLE_AUDIO_UUID_PACS_SRC_LOC_VAL

Available Audio Contexts Characteristic value

ESP_BLE_AUDIO_UUID_PACS_AVAILABLE_CONTEXT_VAL

Supported Audio Context Characteristic value

ESP_BLE_AUDIO_UUID_PACS_SUPPORTED_CONTEXT_VAL

Bearer Provider Name value

ESP_BLE_AUDIO_UUID_TBS_PROVIDER_NAME_VAL

Bearer UCI value

ESP_BLE_AUDIO_UUID_TBS_UCI_VAL

Bearer Technology value

ESP_BLE_AUDIO_UUID_TBS_TECHNOLOGY_VAL

Bearer URI Prefixes Supported List value

ESP_BLE_AUDIO_UUID_TBS_URI_LIST_VAL

Bearer Signal Strength value

ESP_BLE_AUDIO_UUID_TBS_SIGNAL_STRENGTH_VAL

Bearer Signal Strength Reporting Interval value

ESP_BLE_AUDIO_UUID_TBS_SIGNAL_INTERVAL_VAL

Bearer List Current Calls value

ESP_BLE_AUDIO_UUID_TBS_LIST_CURRENT_CALLS_VAL

Status flags value

ESP_BLE_AUDIO_UUID_TBS_STATUS_FLAGS_VAL

Incoming Call Target Caller ID value

ESP_BLE_AUDIO_UUID_TBS_INCOMING_URI_VAL

Call State value

ESP_BLE_AUDIO_UUID_TBS_CALL_STATE_VAL

Call Control Point value

ESP_BLE_AUDIO_UUID_TBS_CALL_CONTROL_POINT_VAL

Optional Opcodes value

ESP_BLE_AUDIO_UUID_TBS_OPTIONAL_OPCODES_VAL

Terminate reason value

ESP_BLE_AUDIO_UUID_TBS_TERMINATE_REASON_VAL

Incoming Call value

ESP_BLE_AUDIO_UUID_TBS_INCOMING_CALL_VAL

Incoming Call Friendly name value

ESP_BLE_AUDIO_UUID_TBS_FRIENDLY_NAME_VAL

Volume Control Setting value

ESP_BLE_AUDIO_UUID_VCS_STATE_VAL

Volume Control Control point value

ESP_BLE_AUDIO_UUID_VCS_CONTROL_VAL

Volume Control Flags value

ESP_BLE_AUDIO_UUID_VCS_FLAGS_VAL

Volume Offset State value

ESP_BLE_AUDIO_UUID_VOCS_STATE_VAL

Audio Location value

ESP_BLE_AUDIO_UUID_VOCS_LOCATION_VAL

Volume Offset Control Point value

ESP_BLE_AUDIO_UUID_VOCS_CONTROL_VAL

Volume Offset Audio Output Description value

ESP_BLE_AUDIO_UUID_VOCS_DESCRIPTION_VAL

Content Control ID value

ESP_BLE_AUDIO_UUID_CCID_VAL

OTS Feature Characteristic UUID value

ESP_BLE_AUDIO_UUID_OTS_FEATURE_VAL

OTS Object Name Characteristic UUID value

ESP_BLE_AUDIO_UUID_OTS_NAME_VAL

OTS Object Type Characteristic UUID value

ESP_BLE_AUDIO_UUID_OTS_TYPE_VAL

OTS Object Size Characteristic UUID value

ESP_BLE_AUDIO_UUID_OTS_SIZE_VAL

OTS Object First-Created Characteristic UUID value

ESP_BLE_AUDIO_UUID_OTS_FIRST_CREATED_VAL

OTS Object Last-Modified Characteristic UUI value

ESP_BLE_AUDIO_UUID_OTS_LAST_MODIFIED_VAL

OTS Object ID Characteristic UUID value

ESP_BLE_AUDIO_UUID_OTS_ID_VAL

OTS Object Properties Characteristic UUID value

ESP_BLE_AUDIO_UUID_OTS_PROPERTIES_VAL

OTS Object Action Control Point Characteristic UUID value

ESP_BLE_AUDIO_UUID_OTS_ACTION_CP_VAL

OTS Object List Control Point Characteristic UUID value

ESP_BLE_AUDIO_UUID_OTS_LIST_CP_VAL

OTS Object List Filter Characteristic UUID value

ESP_BLE_AUDIO_UUID_OTS_LIST_FILTER_VAL

OTS Object Changed Characteristic UUID value

ESP_BLE_AUDIO_UUID_OTS_CHANGED_VAL

OTS Unspecified Object Type UUID value

ESP_BLE_AUDIO_UUID_OTS_TYPE_UNSPECIFIED_VAL

OTS Directory Listing UUID value

ESP_BLE_AUDIO_UUID_OTS_DIRECTORY_LISTING_VAL

OTS Media Player Icon Object Type value

ESP_BLE_AUDIO_UUID_OTS_TYPE_MPL_ICON_VAL

OTS Track Segments Object Type value

ESP_BLE_AUDIO_UUID_OTS_TYPE_TRACK_SEGMENT_VAL

OTS Track Object Type value

ESP_BLE_AUDIO_UUID_OTS_TYPE_TRACK_VAL

OTS Group Object Type value

ESP_BLE_AUDIO_UUID_OTS_TYPE_GROUP_VAL

Generic Audio Sink

ESP_BLE_AUDIO_APPEARANCE_GENERIC_AUDIO_SINK

Standalone Speaker

ESP_BLE_AUDIO_APPEARANCE_AUDIO_SINK_STANDALONE_SPEAKER

Soundbar

ESP_BLE_AUDIO_APPEARANCE_AUDIO_SINK_SOUNDBAR

Bookshelf Speaker

ESP_BLE_AUDIO_APPEARANCE_AUDIO_SINK_BOOKSHELF_SPEAKER

Standmounted Speaker

ESP_BLE_AUDIO_APPEARANCE_AUDIO_SINK_STANDMOUNTED_SPEAKER

Speakerphone

ESP_BLE_AUDIO_APPEARANCE_AUDIO_SINK_SPEAKERPHONE

Generic Audio Source

ESP_BLE_AUDIO_APPEARANCE_GENERIC_AUDIO_SOURCE

Microphone

ESP_BLE_AUDIO_APPEARANCE_AUDIO_SOURCE_MICROPHONE

Alarm

ESP_BLE_AUDIO_APPEARANCE_AUDIO_SOURCE_ALARM

Bell

ESP_BLE_AUDIO_APPEARANCE_AUDIO_SOURCE_BELL

Horn

ESP_BLE_AUDIO_APPEARANCE_AUDIO_SOURCE_HORN

Broadcasting Device

ESP_BLE_AUDIO_APPEARANCE_AUDIO_SOURCE_BROADCASTING_DEVICE

Service Desk

ESP_BLE_AUDIO_APPEARANCE_AUDIO_SOURCE_SERVICE_DESK

Kiosk

ESP_BLE_AUDIO_APPEARANCE_AUDIO_SOURCE_KIOSK

Broadcasting Room

ESP_BLE_AUDIO_APPEARANCE_AUDIO_SOURCE_BROADCASTING_ROOM

Auditorium

ESP_BLE_AUDIO_APPEARANCE_AUDIO_SOURCE_AUDITORIUM

Generic Wearable Audio Device

ESP_BLE_AUDIO_APPEARANCE_GENERIC_WEARABLE_AUDIO_DEVICE

Earbud

ESP_BLE_AUDIO_APPEARANCE_WEARABLE_AUDIO_DEVICE_EARBUD

Headset

ESP_BLE_AUDIO_APPEARANCE_WEARABLE_AUDIO_DEVICE_HEADSET

Headphones

ESP_BLE_AUDIO_APPEARANCE_WEARABLE_AUDIO_DEVICE_HEADPHONES

Neck Band

ESP_BLE_AUDIO_APPEARANCE_WEARABLE_AUDIO_DEVICE_NECK_BAND

Generic Hearing aid

ESP_BLE_AUDIO_APPEARANCE_GENERIC_HEARING_AID

In-ear hearing aid

ESP_BLE_AUDIO_APPEARANCE_HEARING_AID_IN_EAR

Behind-ear hearing aid

ESP_BLE_AUDIO_APPEARANCE_HEARING_AID_BEHIND_EAR

Cochlear Implant

ESP_BLE_AUDIO_APPEARANCE_HEARING_AID_COCHLEAR_IMPLANT

Type Definitions

typedef enum bt_audio_dir esp_ble_audio_dir_t

Audio direction from the perspective of the BAP Unicast Server / BAP Broadcast Sink Size of the stream language value, e.g. "eng"

typedef enum bt_audio_context esp_ble_audio_context_t

Audio Context Type for Generic Audio No rating

typedef enum bt_audio_parental_rating esp_ble_audio_parental_rating_t

Parental rating defined by the Generic Audio assigned numbers No audio data is being transmitted

typedef enum bt_audio_active_state esp_ble_audio_active_state_t

Audio Active State defined by the Generic Audio assigned numbers Preferred audio context

typedef enum bt_audio_metadata_type esp_ble_audio_metadata_type_t

Metadata types defined by the Generic Audio assigned numbers Mono Audio (no specified Audio Location)

typedef enum bt_audio_location esp_ble_audio_location_t

Location values defined by the Generic Audio assigned numbers Unspecified audio enhancement

typedef enum bt_audio_assisted_listening_stream esp_ble_audio_assisted_listening_stream_t

Assisted Listening Stream defined by the Generic Audio assigned numbers Size in octets of a 16-bit UUID

LC3 Codec Definitions

Header File

• components/bt/esp_ble_audio/api/include/esp_ble_audio_lc3_defs.h

• This header file can be included with:

  #include "esp_ble_audio_lc3_defs.h"
  

• This header file is a part of the API provided by the bt component. To declare that your component depends on bt, add the following to your CMakeLists.txt:

  REQUIRES bt
  

  or

  PRIV_REQUIRES bt
  

Macros

ESP_BLE_AUDIO_CODEC_CAP_LC3_DATA(_freq, _duration, _chan_count, _len_min, _len_max, _max_frames_per_sdu)

Helper to declare LC3 codec capability.

Parameters:

• _freq -- Supported Sampling Frequencies bitfield.

• _duration -- Supported Frame Durations bitfield.

• _chan_count -- Supported channels.

• _len_min -- Minimum number of octets supported per codec frame.

• _len_max -- Maximum number of octets supported per codec frame.

• _max_frames_per_sdu -- Supported maximum codec frames per SDU. Optional and will be included only if != 1.

ESP_BLE_AUDIO_CODEC_CAP_LC3_META(_prefer_context)

Helper to declare LC3 codec metadata.

Parameters:

• _prefer_context -- Preferred contexts.

ESP_BLE_AUDIO_CODEC_CAP_LC3(_data, _meta)

Helper to declare LC3 codec capability.

Parameters:

• _data -- LC3 codec capability data.

• _meta -- LC3 codec capability metadata.

ESP_BLE_AUDIO_CODEC_CAP_LC3_LEN(_data, _data_len, _meta, _meta_len)

Variant of ESP_BLE_AUDIO_CODEC_CAP_LC3 with explicit LVT content lengths.

ESP_BLE_AUDIO_CODEC_CFG_LC3_DATA(_freq, _duration, _loc, _len, _frames_per_sdu)

Helper to declare LC3 codec data configuration.

Parameters:

• _freq -- Sampling frequency.

• _duration -- Frame duration.

• _loc -- Audio channel location bitfield.

• _len -- Octets per frame (16-bit integer).

• _frames_per_sdu -- Frames per SDU (8-bit integer). This value is optional and will be included only if != 1.

ESP_BLE_AUDIO_CODEC_CFG_LC3_META(_stream_context)

Helper to declare LC3 codec metadata configuration.

Parameters:

• _stream_context -- Stream context.

ESP_BLE_AUDIO_CODEC_CFG_LC3(_data, _meta)

Helper to declare LC3 codec configuration.

Parameters:

• _data -- LC3 codec configuration data.

• _meta -- LC3 codec configuration metadata.

ESP_BLE_AUDIO_CODEC_CFG_LC3_LEN(_data, _data_len, _meta, _meta_len)

Variant of ESP_BLE_AUDIO_CODEC_CFG_LC3 with explicit LVT content lengths.

MCS Definitions

Header File

• components/bt/esp_ble_audio/api/include/esp_ble_audio_mcs_defs.h

• This header file can be included with:

  #include "esp_ble_audio_mcs_defs.h"
  

• This header file is a part of the API provided by the bt component. To declare that your component depends on bt, add the following to your CMakeLists.txt:

  REQUIRES bt
  

  or

  PRIV_REQUIRES bt
  

Macros

ESP_BLE_AUDIO_MCS_PLAYBACK_SPEED_MIN

< Minimum playback speed, resulting in 25% speed Quarter playback speed, resulting in 25% speed

ESP_BLE_AUDIO_MCS_PLAYBACK_SPEED_QUARTER

Half playback speed, resulting in 50% speed

ESP_BLE_AUDIO_MCS_PLAYBACK_SPEED_HALF

Unity playback speed, resulting in 100% speed

ESP_BLE_AUDIO_MCS_PLAYBACK_SPEED_UNITY

Double playback speed, resulting in 200% speed

ESP_BLE_AUDIO_MCS_PLAYBACK_SPEED_DOUBLE

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

ESP_BLE_AUDIO_MCS_PLAYBACK_SPEED_MAX

Maximum seeking speed - Can be negated

ESP_BLE_AUDIO_MCS_SEEKING_SPEED_FACTOR_MAX

Minimum seeking speed - Can be negated

ESP_BLE_AUDIO_MCS_SEEKING_SPEED_FACTOR_MIN

No seeking

ESP_BLE_AUDIO_MCS_SEEKING_SPEED_FACTOR_ZERO

A single track is played once; there is no next track.

ESP_BLE_AUDIO_MCS_PLAYING_ORDER_SINGLE_ONCE

A single track is played repeatedly; the next track is the current track.

ESP_BLE_AUDIO_MCS_PLAYING_ORDER_SINGLE_REPEAT

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

ESP_BLE_AUDIO_MCS_PLAYING_ORDER_INORDER_ONCE

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

ESP_BLE_AUDIO_MCS_PLAYING_ORDER_INORDER_REPEAT

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

ESP_BLE_AUDIO_MCS_PLAYING_ORDER_OLDEST_ONCE

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

ESP_BLE_AUDIO_MCS_PLAYING_ORDER_OLDEST_REPEAT

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

ESP_BLE_AUDIO_MCS_PLAYING_ORDER_NEWEST_ONCE

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

ESP_BLE_AUDIO_MCS_PLAYING_ORDER_NEWEST_REPEAT

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

ESP_BLE_AUDIO_MCS_PLAYING_ORDER_SHUFFLE_ONCE

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

ESP_BLE_AUDIO_MCS_PLAYING_ORDER_SHUFFLE_REPEAT

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

ESP_BLE_AUDIO_MCS_MEDIA_STATE_INACTIVE

The media player is playing the current track.

ESP_BLE_AUDIO_MCS_MEDIA_STATE_PLAYING

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

ESP_BLE_AUDIO_MCS_MEDIA_STATE_PAUSED

The current track is fast forwarding or fast rewinding.

ESP_BLE_AUDIO_MCS_MEDIA_STATE_SEEKING

Start playing the current track.

ESP_BLE_AUDIO_MCS_OPC_PLAY

Pause playing the current track.

ESP_BLE_AUDIO_MCS_OPC_PAUSE

Fast rewind the current track.

ESP_BLE_AUDIO_MCS_OPC_FAST_REWIND

Fast forward the current track.

ESP_BLE_AUDIO_MCS_OPC_FAST_FORWARD

ESP_BLE_AUDIO_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. Set a new current track position relative to the current track position.

ESP_BLE_AUDIO_MCS_OPC_MOVE_RELATIVE

ESP_BLE_AUDIO_MCS_OPC_PREV_SEGMENT

Set the current track position to the starting position of the previous segment of the current track.

ESP_BLE_AUDIO_MCS_OPC_NEXT_SEGMENT

Set the current track position to the starting position of the next segment of the current track.

ESP_BLE_AUDIO_MCS_OPC_FIRST_SEGMENT

Set the current track position to the starting position of the first segment of the current track.

ESP_BLE_AUDIO_MCS_OPC_LAST_SEGMENT

Set the current track position to the starting position of the last segment of the current track.

ESP_BLE_AUDIO_MCS_OPC_GOTO_SEGMENT

Set the current track position to the starting position of the nth segment of the current track. Set the current track to the previous track based on the playing order.

ESP_BLE_AUDIO_MCS_OPC_PREV_TRACK

Set the current track to the next track based on the playing order.

ESP_BLE_AUDIO_MCS_OPC_NEXT_TRACK

Set the current track to the first track based on the playing order.

ESP_BLE_AUDIO_MCS_OPC_FIRST_TRACK

Set the current track to the last track based on the playing order.

ESP_BLE_AUDIO_MCS_OPC_LAST_TRACK

Set the current track to the nth track based on the playing order.

ESP_BLE_AUDIO_MCS_OPC_GOTO_TRACK

Set the current group to the previous group in the sequence of groups.

ESP_BLE_AUDIO_MCS_OPC_PREV_GROUP

Set the current group to the next group in the sequence of groups.

ESP_BLE_AUDIO_MCS_OPC_NEXT_GROUP

Set the current group to the first group in the sequence of groups.

ESP_BLE_AUDIO_MCS_OPC_FIRST_GROUP

Set the current group to the last group in the sequence of groups.

ESP_BLE_AUDIO_MCS_OPC_LAST_GROUP

Set the current group to the nth group in the sequence of groups.

ESP_BLE_AUDIO_MCS_OPC_GOTO_GROUP

Media control point supported opcodes length

ESP_BLE_AUDIO_MCS_OPCODES_SUPPORTED_LEN

Support the Play opcode

ESP_BLE_AUDIO_MCS_OPC_SUP_PLAY

Support the Pause opcode

ESP_BLE_AUDIO_MCS_OPC_SUP_PAUSE

Support the Fast Rewind opcode

ESP_BLE_AUDIO_MCS_OPC_SUP_FAST_REWIND

Support the Fast Forward opcode

ESP_BLE_AUDIO_MCS_OPC_SUP_FAST_FORWARD

Support the Stop opcode

ESP_BLE_AUDIO_MCS_OPC_SUP_STOP

Support the Move Relative opcode

ESP_BLE_AUDIO_MCS_OPC_SUP_MOVE_RELATIVE

Support the Previous Segment opcode

ESP_BLE_AUDIO_MCS_OPC_SUP_PREV_SEGMENT

Support the Next Segment opcode

ESP_BLE_AUDIO_MCS_OPC_SUP_NEXT_SEGMENT

Support the First Segment opcode

ESP_BLE_AUDIO_MCS_OPC_SUP_FIRST_SEGMENT

Support the Last Segment opcode

ESP_BLE_AUDIO_MCS_OPC_SUP_LAST_SEGMENT

Support the Goto Segment opcode

ESP_BLE_AUDIO_MCS_OPC_SUP_GOTO_SEGMENT

Support the Previous Track opcode

ESP_BLE_AUDIO_MCS_OPC_SUP_PREV_TRACK

Support the Next Track opcode

ESP_BLE_AUDIO_MCS_OPC_SUP_NEXT_TRACK

Support the First Track opcode

ESP_BLE_AUDIO_MCS_OPC_SUP_FIRST_TRACK

Support the Last Track opcode

ESP_BLE_AUDIO_MCS_OPC_SUP_LAST_TRACK

Support the Goto Track opcode

ESP_BLE_AUDIO_MCS_OPC_SUP_GOTO_TRACK

Support the Previous Group opcode

ESP_BLE_AUDIO_MCS_OPC_SUP_PREV_GROUP

Support the Next Group opcode

ESP_BLE_AUDIO_MCS_OPC_SUP_NEXT_GROUP

Support the First Group opcode

ESP_BLE_AUDIO_MCS_OPC_SUP_FIRST_GROUP

Support the Last Group opcode

ESP_BLE_AUDIO_MCS_OPC_SUP_LAST_GROUP

Support the Goto Group opcode

ESP_BLE_AUDIO_MCS_OPC_SUP_GOTO_GROUP

ESP_BLE_AUDIO_MCS_OPC_NTF_SUCCESS

Action requested by the opcode write was completed successfully.

ESP_BLE_AUDIO_MCS_OPC_NTF_NOT_SUPPORTED

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

ESP_BLE_AUDIO_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.

ESP_BLE_AUDIO_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 for Track Name

ESP_BLE_AUDIO_MCS_SEARCH_TYPE_TRACK_NAME

Search for Artist Name

ESP_BLE_AUDIO_MCS_SEARCH_TYPE_ARTIST_NAME

Search for Album Name

ESP_BLE_AUDIO_MCS_SEARCH_TYPE_ALBUM_NAME

Search for Group Name

ESP_BLE_AUDIO_MCS_SEARCH_TYPE_GROUP_NAME

Search for Earliest Year

ESP_BLE_AUDIO_MCS_SEARCH_TYPE_EARLIEST_YEAR

Search for Latest Year

ESP_BLE_AUDIO_MCS_SEARCH_TYPE_LATEST_YEAR

Search for Genre

ESP_BLE_AUDIO_MCS_SEARCH_TYPE_GENRE

Search for Tracks only

ESP_BLE_AUDIO_MCS_SEARCH_TYPE_ONLY_TRACKS

Search for Groups only

ESP_BLE_AUDIO_MCS_SEARCH_TYPE_ONLY_GROUPS

Search control point minimum length

ESP_BLE_AUDIO_SEARCH_LEN_MIN

Search control point maximum length

ESP_BLE_AUDIO_SEARCH_LEN_MAX

Search control point item (SCI) minimum length

ESP_BLE_AUDIO_SEARCH_SCI_LEN_MIN

Search parameters maximum length

ESP_BLE_AUDIO_SEARCH_PARAM_MAX

Search request was accepted; search has started.

ESP_BLE_AUDIO_MCS_SCP_NTF_SUCCESS

Search request was invalid; no search started.

ESP_BLE_AUDIO_MCS_SCP_NTF_FAILURE

Group object type is track

ESP_BLE_AUDIO_MCS_GROUP_OBJECT_TRACK_TYPE

Group object type is group

ESP_BLE_AUDIO_MCS_GROUP_OBJECT_GROUP_TYPE

A single track is played once; there is no next track.

ESP_BLE_AUDIO_MCS_PLAYING_ORDERS_SUPPORTED_SINGLE_ONCE

A single track is played repeatedly; the next track is the current track.

ESP_BLE_AUDIO_MCS_PLAYING_ORDERS_SUPPORTED_SINGLE_REPEAT

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

ESP_BLE_AUDIO_MCS_PLAYING_ORDERS_SUPPORTED_INORDER_ONCE

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

ESP_BLE_AUDIO_MCS_PLAYING_ORDERS_SUPPORTED_INORDER_REPEAT

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

ESP_BLE_AUDIO_MCS_PLAYING_ORDERS_SUPPORTED_OLDEST_ONCE

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

ESP_BLE_AUDIO_MCS_PLAYING_ORDERS_SUPPORTED_OLDEST_REPEAT

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

ESP_BLE_AUDIO_MCS_PLAYING_ORDERS_SUPPORTED_NEWEST_ONCE

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

ESP_BLE_AUDIO_MCS_PLAYING_ORDERS_SUPPORTED_NEWEST_REPEAT

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

ESP_BLE_AUDIO_MCS_PLAYING_ORDERS_SUPPORTED_SHUFFLE_ONCE

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

ESP_BLE_AUDIO_MCS_PLAYING_ORDERS_SUPPORTED_SHUFFLE_REPEAT

ESP_BLE_AUDIO_MCS_VALID_OBJ_ID(id)

Check if an Object ID is valid for MCS. This differs from BT_OTS_VALID_OBJ_ID as MCS does not use the directory list object.

Parameters:

• id -- Object ID to validate.

BAP LC3 Preset Definitions

Header File

• components/bt/esp_ble_audio/api/include/esp_ble_audio_bap_lc3_preset_defs.h

• This header file can be included with:

  #include "esp_ble_audio_bap_lc3_preset_defs.h"
  

• This header file is a part of the API provided by the bt component. To declare that your component depends on bt, add the following to your CMakeLists.txt:

  REQUIRES bt
  

  or

  PRIV_REQUIRES bt
  

Macros

ESP_BLE_AUDIO_BAP_LC3_PRESET(_codec, _qos)

ESP_BLE_AUDIO_BAP_LC3_PRESET_DEFINE(_name, _freq, _duration, _loc, _len, _frames_per_sdu, _stream_context, _interval, _sdu, _rtn, _latency, _pd)

Define an LC3 preset configuration.

Backing buffers are sized to CONFIG_BT_AUDIO_CODEC_CFG_MAX_*_SIZE so the preset is safe to mutate via esp_ble_audio_codec_cfg_*_set_*.

Parameters:

• _name -- Preset configuration name.

• _freq -- Sample frequency (in Hz).

• _duration -- Frame duration (in microseconds).

• _loc -- Audio channel location.

• _len -- Frame length in octets.

• _frames_per_sdu -- Number of frames per SDU.

• _stream_context -- Stream context (e.g., Media, Conversational, etc.).

• _interval -- Audio frame interval (in microseconds).

• _sdu -- SDU size in octets.

• _rtn -- Number of retransmissions.

• _latency -- Maximum transport latency (in milliseconds).

• _pd -- Presentation delay (in microseconds).

ESP_BLE_AUDIO_BAP_LC3_UNICAST_PRESET_8_1_1_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Unicast 8_1_1 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_UNICAST_PRESET_8_2_1_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Unicast 8_2_1 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_UNICAST_PRESET_16_1_1_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Unicast 16_1_1 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_UNICAST_PRESET_16_2_1_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Unicast 16_2_1 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_UNICAST_PRESET_24_1_1_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Unicast 24_1_1 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_UNICAST_PRESET_24_2_1_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Unicast 24_2_1 codec configuration.

Mandatory to support as unicast server.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_UNICAST_PRESET_32_1_1_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Unicast 32_1_1 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_UNICAST_PRESET_32_2_1_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Unicast 32_2_1 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_UNICAST_PRESET_441_1_1_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Unicast 441_1_1 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_UNICAST_PRESET_441_2_1_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Unicast 441_2_1 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_UNICAST_PRESET_48_1_1_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Unicast 48_1_1 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_UNICAST_PRESET_48_2_1_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Unicast 48_2_1 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_UNICAST_PRESET_48_3_1_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Unicast 48_3_1 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_UNICAST_PRESET_48_4_1_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Unicast 48_4_1 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_UNICAST_PRESET_48_5_1_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Unicast 48_5_1 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_UNICAST_PRESET_48_6_1_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Unicast 48_6_1 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_UNICAST_PRESET_8_1_2_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Unicast 8_1_2 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_UNICAST_PRESET_8_2_2_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Unicast 8_2_2 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_UNICAST_PRESET_16_1_2_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Unicast 16_1_2 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_UNICAST_PRESET_16_2_2_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Unicast 16_2_2 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_UNICAST_PRESET_24_1_2_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Unicast 24_1_2 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_UNICAST_PRESET_24_2_2_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Unicast 24_2_2 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_UNICAST_PRESET_32_1_2_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Unicast 32_1_2 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_UNICAST_PRESET_32_2_2_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Unicast 32_2_2 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_UNICAST_PRESET_441_1_2_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Unicast 441_1_2 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_UNICAST_PRESET_441_2_2_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Unicast 441_2_2 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_UNICAST_PRESET_48_1_2_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Unicast 48_1_2 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_UNICAST_PRESET_48_2_2_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Unicast 48_2_2 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_UNICAST_PRESET_48_3_2_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Unicast 48_3_2 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_UNICAST_PRESET_48_4_2_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Unicast 48_4_2 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_UNICAST_PRESET_48_5_2_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Unicast 48_5_2 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_UNICAST_PRESET_48_6_2_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Unicast 48_6_2 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_BROADCAST_PRESET_8_1_1_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Broadcast 8_1_1 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_BROADCAST_PRESET_8_2_1_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Broadcast 8_2_1 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_BROADCAST_PRESET_16_1_1_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Broadcast 16_1_1 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_BROADCAST_PRESET_16_2_1_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Broadcast 16_2_1 codec configuration.

Mandatory to support as both broadcast source and sink.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_BROADCAST_PRESET_24_1_1_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Broadcast 24_1_1 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_BROADCAST_PRESET_24_2_1_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Broadcast 24_2_1 codec configuration.

Mandatory to support as broadcast sink.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_BROADCAST_PRESET_32_1_1_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Broadcast 32_1_1 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_BROADCAST_PRESET_32_2_1_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Broadcast 32_2_1 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_BROADCAST_PRESET_441_1_1_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Broadcast 441_1_1 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_BROADCAST_PRESET_441_2_1_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Broadcast 441_2_1 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_BROADCAST_PRESET_48_1_1_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Broadcast 48_1_1 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_BROADCAST_PRESET_48_2_1_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Broadcast 48_2_1 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_BROADCAST_PRESET_48_3_1_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Broadcast 48_3_1 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_BROADCAST_PRESET_48_4_1_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Broadcast 48_4_1 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_BROADCAST_PRESET_48_5_1_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Broadcast 48_5_1 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_BROADCAST_PRESET_48_6_1_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Broadcast 48_6_1 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_BROADCAST_PRESET_8_1_2_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Broadcast 8_1_2 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_BROADCAST_PRESET_8_2_2_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Broadcast 8_2_2 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_BROADCAST_PRESET_16_1_2_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Broadcast 16_1_2 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_BROADCAST_PRESET_16_2_2_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Broadcast 16_2_2 codec configuration.

Mandatory to support as both broadcast source and sink.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_BROADCAST_PRESET_24_1_2_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Broadcast 24_1_2 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_BROADCAST_PRESET_24_2_2_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Broadcast 24_2_2 codec configuration.

Mandatory to support as broadcast sink.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_BROADCAST_PRESET_32_1_2_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Broadcast 32_1_2 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_BROADCAST_PRESET_32_2_2_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Broadcast 32_2_2 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_BROADCAST_PRESET_441_1_2_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Broadcast 441_1_2 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_BROADCAST_PRESET_441_2_2_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Broadcast 441_2_2 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_BROADCAST_PRESET_48_1_2_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Broadcast 48_1_2 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_BROADCAST_PRESET_48_2_2_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Broadcast 48_2_2 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_BROADCAST_PRESET_48_3_2_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Broadcast 48_3_2 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_BROADCAST_PRESET_48_4_2_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Broadcast 48_4_2 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_BROADCAST_PRESET_48_5_2_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Broadcast 48_5_2 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

ESP_BLE_AUDIO_BAP_LC3_BROADCAST_PRESET_48_6_2_DEFINE(_name, _loc, _stream_context)

Helper to declare LC3 Broadcast 48_6_2 codec configuration.

Parameters:

• _name -- Preset configuration name.

• _loc -- Audio channel location bitfield.

• _stream_context -- Stream context.

Type Definitions

typedef struct bt_bap_lc3_preset esp_ble_audio_bap_lc3_preset_t

Struct to hold a BAP defined LC3 preset Helper to declare an LC3 preset structure

GMAP LC3 Preset Definitions

Header File

• components/bt/esp_ble_audio/api/include/esp_ble_audio_gmap_lc3_preset_defs.h

• This header file can be included with:

  #include "esp_ble_audio_gmap_lc3_preset_defs.h"
  

• This header file is a part of the API provided by the bt component. To declare that your component depends on bt, add the following to your CMakeLists.txt:

  REQUIRES bt
  

  or

  PRIV_REQUIRES bt
  

Macros

ESP_BLE_AUDIO_GMAP_LC3_PRESET_DEFINE(_name, _freq, _duration, _loc, _len, _frames_per_sdu, _stream_context, _interval, _sdu, _rtn, _latency, _pd)

Base macro for defining GMAP LC3 presets.

Backing buffers are sized to CONFIG_BT_AUDIO_CODEC_CFG_MAX_*_SIZE so the preset is safe to mutate via esp_ble_audio_codec_cfg_*_set_*.

Parameters:

• _name -- Preset name.

• _freq -- Sampling frequency (16, 32, or 48 kHz).

• _duration -- Frame duration (7.5 or 10 ms).

• _loc -- Audio channel location.

• _len -- Frame length in bytes.

• _frames_per_sdu -- Number of frames per SDU.

• _stream_context -- Stream context type.

• _interval -- Interval between packets in microseconds.

• _sdu -- SDU size in bytes.

• _rtn -- Maximum number of retransmissions.

• _latency -- Maximum latency in milliseconds.

• _pd -- Presentation delay in microseconds.

ESP_BLE_AUDIO_GMAP_LC3_PRESET_32_1_GR_DEFINE(_name, _loc, _stream_context)

Gaming Reliable (GR) preset at 32kHz, 7.5ms frame duration.

Optimized for reliable gaming audio with low latency (15ms) and standard presentation delay (10ms).

Parameters:

• _name -- Preset name.

• _loc -- Audio channel location.

• _stream_context -- Stream context type.

ESP_BLE_AUDIO_GMAP_LC3_PRESET_32_2_GR_DEFINE(_name, _loc, _stream_context)

Gaming Reliable (GR) preset at 32kHz, 10ms frame duration.

Higher quality variant with increased frame duration for better audio quality.

Parameters:

• _name -- Preset name.

• _loc -- Audio channel location.

• _stream_context -- Stream context type.

ESP_BLE_AUDIO_GMAP_LC3_PRESET_48_1_GR_DEFINE(_name, _loc, _stream_context)

Gaming Reliable (GR) preset at 48kHz, 7.5ms frame duration.

High-quality gaming audio with minimal latency.

Parameters:

• _name -- Preset name.

• _loc -- Audio channel location.

• _stream_context -- Stream context type.

ESP_BLE_AUDIO_GMAP_LC3_PRESET_48_2_GR_DEFINE(_name, _loc, _stream_context)

Gaming Reliable (GR) preset at 48kHz, 10ms frame duration.

High-quality gaming audio with balanced latency and quality.

Parameters:

• _name -- Preset name.

• _loc -- Audio channel location.

• _stream_context -- Stream context type.

ESP_BLE_AUDIO_GMAP_LC3_PRESET_48_3_GR_DEFINE(_name, _loc, _stream_context)

Gaming Reliable (GR) preset at 48kHz, 7.5ms frame duration, higher bitrate.

Enhanced quality gaming audio with minimal latency.

Parameters:

• _name -- Preset name.

• _loc -- Audio channel location.

• _stream_context -- Stream context type.

ESP_BLE_AUDIO_GMAP_LC3_PRESET_48_4_GR_DEFINE(_name, _loc, _stream_context)

Gaming Reliable (GR) preset at 48kHz, 10ms frame duration, higher bitrate.

Premium quality gaming audio with balanced latency.

Parameters:

• _name -- Preset name.

• _loc -- Audio channel location.

• _stream_context -- Stream context type.

ESP_BLE_AUDIO_GMAP_LC3_PRESET_16_1_GS_DEFINE(_name, _loc, _stream_context)

Gaming Standard (GS) preset at 16kHz, 7.5ms frame duration.

Basic gaming audio with longer presentation delay (60ms).

Parameters:

• _name -- Preset name.

• _loc -- Audio channel location.

• _stream_context -- Stream context type.

ESP_BLE_AUDIO_GMAP_LC3_PRESET_16_2_GS_DEFINE(_name, _loc, _stream_context)

Gaming Standard (GS) preset at 16kHz, 10ms frame duration.

Basic gaming audio with better quality and longer presentation delay.

Parameters:

• _name -- Preset name.

• _loc -- Audio channel location.

• _stream_context -- Stream context type.

ESP_BLE_AUDIO_GMAP_LC3_PRESET_32_1_GS_DEFINE(_name, _loc, _stream_context)

Gaming Standard (GS) preset at 32kHz, 7.5ms frame duration.

Medium quality gaming audio with standard latency.

Parameters:

• _name -- Preset name.

• _loc -- Audio channel location.

• _stream_context -- Stream context type.

ESP_BLE_AUDIO_GMAP_LC3_PRESET_32_2_GS_DEFINE(_name, _loc, _stream_context)

Gaming Standard (GS) preset at 32kHz, 10ms frame duration.

Enhanced medium quality gaming audio.

Parameters:

• _name -- Preset name.

• _loc -- Audio channel location.

• _stream_context -- Stream context type.

ESP_BLE_AUDIO_GMAP_LC3_PRESET_48_1_GS_DEFINE(_name, _loc, _stream_context)

Gaming Standard (GS) preset at 48kHz, 7.5ms frame duration.

High quality gaming audio with standard latency.

Parameters:

• _name -- Preset name.

• _loc -- Audio channel location.

• _stream_context -- Stream context type.

ESP_BLE_AUDIO_GMAP_LC3_PRESET_48_2_GS_DEFINE(_name, _loc, _stream_context)

Gaming Standard (GS) preset at 48kHz, 10ms frame duration.

Premium quality gaming audio with standard latency.

Parameters:

• _name -- Preset name.

• _loc -- Audio channel location.

• _stream_context -- Stream context type.

ESP_BLE_AUDIO_GMAP_LC3_PRESET_48_1_G_DEFINE(_name, _loc, _stream_context)

Generic Gaming (G) preset at 48kHz, 7.5ms frame duration.

High quality gaming audio with ultra-low latency (8ms).

Parameters:

• _name -- Preset name.

• _loc -- Audio channel location.

• _stream_context -- Stream context type.

ESP_BLE_AUDIO_GMAP_LC3_PRESET_48_2_G_DEFINE(_name, _loc, _stream_context)

Generic Gaming (G) preset at 48kHz, 10ms frame duration.

High quality gaming audio with very low latency (10ms).

Parameters:

• _name -- Preset name.

• _loc -- Audio channel location.

• _stream_context -- Stream context type.

ESP_BLE_AUDIO_GMAP_LC3_PRESET_48_3_G_DEFINE(_name, _loc, _stream_context)

Generic Gaming (G) preset at 48kHz, 7.5ms frame duration, higher bitrate.

Premium quality gaming audio with ultra-low latency.

Parameters:

• _name -- Preset name.

• _loc -- Audio channel location.

• _stream_context -- Stream context type.

ESP_BLE_AUDIO_GMAP_LC3_PRESET_48_4_G_DEFINE(_name, _loc, _stream_context)

Generic Gaming (G) preset at 48kHz, 10ms frame duration, higher bitrate.

Highest quality gaming audio with very low latency.

Parameters:

• _name -- Preset name.

• _loc -- Audio channel location.

• _stream_context -- Stream context type.

ESP-BLE-AUDIO API

This section contains LE Audio APIs: common helpers, codec, Common Audio Profile (CAP), Call Control Profile (CCP), and all profile/service APIs.

Common API

Header File

• components/bt/esp_ble_audio/api/include/esp_ble_audio_common_api.h

• This header file can be included with:

  #include "esp_ble_audio_common_api.h"
  

• This header file is a part of the API provided by the bt component. To declare that your component depends on bt, add the following to your CMakeLists.txt:

  REQUIRES bt
  

  or

  PRIV_REQUIRES bt
  

Functions

esp_err_t esp_ble_audio_data_parse(const uint8_t ltv[], size_t size, bool (*func)(uint8_t type, const uint8_t *data, uint8_t data_len, 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.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_data_get_val(const uint8_t ltv_data[], size_t size, uint8_t type, const uint8_t **data, uint8_t *data_len)

Get the value of a specific data type in an length-type-value data array.

Parameters:

• ltv_data -- The array containing the length-type-value tuples.

• size -- The size of ltv_data.

• type -- The type to get the value for.

• data -- Pointer to the data-pointer to update when item is found. Any found data will be little endian.

• data_len -- Length The length of found data (may be 0).

Returns:

ESP_OK on success, or an error code on failure.

uint8_t esp_ble_audio_get_chan_count(esp_ble_audio_location_t chan_allocation)

Function to get the number of channels from the channel allocation.

Parameters:

chan_allocation -- The channel allocation.

Returns:

The number of channels.

esp_err_t esp_ble_audio_gattc_disc_start(uint16_t conn_handle)

Start GATT service discovery.

Note

This function is only needed while using NimBLE Host.

Parameters:

conn_handle -- Connection Handle.

Returns:

ESP_OK on success, or an error code on failure. Audio GAP Extended Scan Recv event

void esp_ble_audio_gap_app_post_event(uint8_t type, void *param)

Post an application-layer GAP event for audio internal usage.

Note

This function is only needed while using NimBLE Host.

Parameters:

• type -- Event type.

• param -- Event parameters.

void esp_ble_audio_gatt_app_post_event(uint8_t type, void *param)

Post an application-layer GATT event for audio internal usage.

Note

This function is only needed while using NimBLE Host.

Parameters:

• type -- Event type.

• param -- Event parameters.

esp_err_t esp_ble_audio_common_init(esp_ble_audio_init_info_t *info)

Initialize BLE Audio common functionality.

Parameters:

info -- Initialization parameters.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_common_start(esp_ble_audio_start_info_t *info)

Start BLE Audio services.

Parameters:

info -- Service instances to start.

Returns:

ESP_OK on success, or an error code on failure.

Structures

struct esp_ble_audio_init_info_t

Contains callback functions for GAP and GATT events

Public Members

bt_le_gap_app_cb gap_cb

GAP event callbacks

bt_le_gatt_app_cb gatt_cb

GATT event callbacks

struct esp_ble_audio_start_info_t

Contains service instances for audio profiles

Public Members

uint8_t dummy

Dummy field to avoid empty struct

Macros

ESP_BLE_AUDIO_GAP_EVENT_EXT_SCAN_RECV

Audio GAP Periodic Sync Established event

ESP_BLE_AUDIO_GAP_EVENT_PA_SYNC

Audio GAP Periodic Sync Transfer Received event

ESP_BLE_AUDIO_GAP_EVENT_PA_SYNC_PAST

Audio GAP Periodic Sync Lost event

ESP_BLE_AUDIO_GAP_EVENT_PA_SYNC_LOST

Audio GAP Connection Complete event

ESP_BLE_AUDIO_GAP_EVENT_ACL_CONNECT

Audio GAP Disconnection Complete event

ESP_BLE_AUDIO_GAP_EVENT_ACL_DISCONNECT

Audio GAP Security Change event

ESP_BLE_AUDIO_GAP_EVENT_SECURITY_CHANGE

ESP_BLE_AUDIO_GATT_EVENT_GATT_MTU_CHANGE

Audio GATT client discovery complete event

ESP_BLE_AUDIO_GATT_EVENT_GATTC_DISC_CMPL

Type Definitions

typedef struct bt_le_gap_app_event esp_ble_audio_gap_app_event_t

Audio GAP application event structure Audio GATT MTU exchange complete event

typedef struct bt_le_gatt_app_event esp_ble_audio_gatt_app_event_t

Audio GATT application event structure

Codec API

Header File

• components/bt/esp_ble_audio/api/include/esp_ble_audio_codec_api.h

• This header file can be included with:

  #include "esp_ble_audio_codec_api.h"
  

• This header file is a part of the API provided by the bt component. To declare that your component depends on bt, add the following to your CMakeLists.txt:

  REQUIRES bt
  

  or

  PRIV_REQUIRES bt
  

Functions

esp_err_t esp_ble_audio_codec_cfg_freq_to_freq_hz(esp_ble_audio_codec_cfg_freq_t freq, uint32_t *freq_hz)

Convert assigned numbers frequency to frequency value.

Parameters:

• freq -- The assigned numbers frequency to convert.

• freq_hz -- The converted frequency value in Hz on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_freq_hz_to_freq(uint32_t freq_hz, esp_ble_audio_codec_cfg_freq_t *freq)

Convert frequency value to assigned numbers frequency.

Parameters:

• freq_hz -- Frequency in Hz.

• freq -- The assigned numbers frequency on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_get_freq(const esp_ble_audio_codec_cfg_t *codec_cfg, esp_ble_audio_codec_cfg_freq_t *freq)

Extract the frequency from a codec configuration.

Parameters:

• codec_cfg -- The codec configuration to extract data from.

• freq -- The assigned numbers frequency on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_set_freq(esp_ble_audio_codec_cfg_t *codec_cfg, esp_ble_audio_codec_cfg_freq_t 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.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_frame_dur_to_frame_dur_us(esp_ble_audio_codec_cfg_frame_dur_t frame_dur, uint32_t *frame_dur_us)

Convert assigned numbers frame duration to duration in microseconds.

Parameters:

• frame_dur -- The assigned numbers frame duration to convert.

• frame_dur_us -- The converted frame duration value in microseconds on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_frame_dur_us_to_frame_dur(uint32_t frame_dur_us, esp_ble_audio_codec_cfg_frame_dur_t *frame_dur)

Convert frame duration in microseconds to assigned numbers frame duration.

Parameters:

• frame_dur_us -- The frame duration in microseconds to convert.

• frame_dur -- The assigned numbers frame duration on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_get_frame_dur(const esp_ble_audio_codec_cfg_t *codec_cfg, esp_ble_audio_codec_cfg_frame_dur_t *frame_dur)

Extract frame duration from codec config.

Parameters:

• codec_cfg -- The codec configuration to extract data from.

• frame_dur -- The assigned numbers frame duration on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_set_frame_dur(esp_ble_audio_codec_cfg_t *codec_cfg, esp_ble_audio_codec_cfg_frame_dur_t 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.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_get_chan_allocation(const esp_ble_audio_codec_cfg_t *codec_cfg, esp_ble_audio_location_t *chan_allocation, bool fallback_to_default)

Extract channel allocation from codec config.

The value returned is a bit field representing one or more audio locations as specified by esp_ble_audio_location_t. Shall match one or more of the bits set in ESP_BLE_AUDIO_PAC_SNK_LOC or ESP_BLE_AUDIO_PAC_SRC_LOC.

Up to the configured ESP_BLE_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.

• fallback_to_default -- If true this function will provide the default value of ESP_BLE_AUDIO_LOCATION_MONO_AUDIO if the type is not found when codec_cfg.id is BT_HCI_CODING_FORMAT_LC3.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_set_chan_allocation(esp_ble_audio_codec_cfg_t *codec_cfg, esp_ble_audio_location_t 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.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_get_octets_per_frame(const esp_ble_audio_codec_cfg_t *codec_cfg, uint16_t *octets_per_frame)

Extract frame size in octets from codec config.

The overall SDU size will be octets_per_frame * blocks_per_sdu.

The Bluetooth specifications 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.

• octets_per_frame -- The frame length in octets on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_set_octets_per_frame(esp_ble_audio_codec_cfg_t *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.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_get_frame_blocks_per_sdu(const esp_ble_audio_codec_cfg_t *codec_cfg, uint8_t *frame_blocks, bool fallback_to_default)

Extract number of audio frame blocks in each SDU from 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.

• frame_blocks -- The count of codec frame blocks in each SDU on success.

• fallback_to_default -- If true this function will return the default value of 1 if the type is not found when codec_cfg.id is BT_HCI_CODING_FORMAT_LC3.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_set_frame_blocks_per_sdu(esp_ble_audio_codec_cfg_t *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.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_get_val(const esp_ble_audio_codec_cfg_t *codec_cfg, esp_ble_audio_codec_cfg_type_t type, const uint8_t **data, size_t *data_len)

Lookup a specific codec configuration value.

Parameters:

• codec_cfg -- The codec data to search in.

• type -- The type id to look for.

• data -- Pointer to the data-pointer to update when item is found.

• data_len -- Length of found data (may be 0) on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_set_val(esp_ble_audio_codec_cfg_t *codec_cfg, esp_ble_audio_codec_cfg_type_t 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.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_unset_val(esp_ble_audio_codec_cfg_t *codec_cfg, esp_ble_audio_codec_cfg_type_t 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.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_meta_get_val(const esp_ble_audio_codec_cfg_t *codec_cfg, esp_ble_audio_metadata_type_t type, const uint8_t **data, size_t *data_len)

Lookup a specific metadata value based on type.

Parameters:

• codec_cfg -- The codec data to search in.

• type -- The type id to look for

• data -- Pointer to the data-pointer to update when item is found.

• data_len -- Length of found data (may be 0) on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_meta_set_val(esp_ble_audio_codec_cfg_t *codec_cfg, esp_ble_audio_metadata_type_t 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.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_meta_unset_val(esp_ble_audio_codec_cfg_t *codec_cfg, esp_ble_audio_metadata_type_t 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.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_meta_get_pref_context(const esp_ble_audio_codec_cfg_t *codec_cfg, esp_ble_audio_context_t *ctx, bool fallback_to_default)

Extract preferred contexts.

Parameters:

• codec_cfg -- The codec data to search in.

• ctx -- The preferred context type on success.

• fallback_to_default -- If true this function will provide the default value of ESP_BLE_AUDIO_CONTEXT_TYPE_UNSPECIFIED if the type is not found when codec_cfg.id is BT_HCI_CODING_FORMAT_LC3.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_meta_set_pref_context(esp_ble_audio_codec_cfg_t *codec_cfg, esp_ble_audio_context_t 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.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_meta_get_stream_context(const esp_ble_audio_codec_cfg_t *codec_cfg, esp_ble_audio_context_t *ctx)

Extract stream contexts.

Parameters:

• codec_cfg -- The codec data to search in.

• ctx -- The stream context type on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_meta_set_stream_context(esp_ble_audio_codec_cfg_t *codec_cfg, esp_ble_audio_context_t 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.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_meta_get_program_info(const esp_ble_audio_codec_cfg_t *codec_cfg, const uint8_t **program_info, size_t *program_info_len)

Extract program info.

Parameters:

• codec_cfg -- The codec data to search in.

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

• program_info_len -- The length of the program_info (may be 0) on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_meta_set_program_info(esp_ble_audio_codec_cfg_t *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.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_meta_get_language(const esp_ble_audio_codec_cfg_t *codec_cfg, const uint8_t **language)

Extract language.

Parameters:

• codec_cfg -- The codec data to search in.

• language -- Pointer to the language bytes (of length ESP_BLE_AUDIO_LANG_SIZE).

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_meta_set_language(esp_ble_audio_codec_cfg_t *codec_cfg, const uint8_t language[ESP_BLE_AUDIO_LANG_SIZE])

Set the language of a codec configuration metadata.

Parameters:

• codec_cfg -- The codec configuration to set data for.

• language -- The 24-bit language to set.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_meta_get_ccid_list(const esp_ble_audio_codec_cfg_t *codec_cfg, const uint8_t **ccid_list, size_t *ccid_list_len)

Extract CCID list.

Parameters:

• codec_cfg -- The codec data to search in.

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

• ccid_list_len -- The length of the ccid_list (may be 0) on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_meta_set_ccid_list(esp_ble_audio_codec_cfg_t *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.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_meta_get_parental_rating(const esp_ble_audio_codec_cfg_t *codec_cfg, esp_ble_audio_parental_rating_t *parental_rating)

Extract parental rating.

Parameters:

• codec_cfg -- The codec data to search in.

• parental_rating -- The parental rating on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_meta_set_parental_rating(esp_ble_audio_codec_cfg_t *codec_cfg, esp_ble_audio_parental_rating_t 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.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_meta_get_program_info_uri(const esp_ble_audio_codec_cfg_t *codec_cfg, const uint8_t **program_info_uri, size_t *program_info_uri_len)

Extract program info URI.

Parameters:

• codec_cfg -- The codec data to search in.

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

• program_info_uri_len -- The length of the program_info_uri (may be 0) on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_meta_set_program_info_uri(esp_ble_audio_codec_cfg_t *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.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_meta_get_audio_active_state(const esp_ble_audio_codec_cfg_t *codec_cfg, esp_ble_audio_active_state_t *state)

Extract audio active state.

Parameters:

• codec_cfg -- The codec data to search in.

• state -- The preferred context type on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_meta_set_audio_active_state(esp_ble_audio_codec_cfg_t *codec_cfg, esp_ble_audio_active_state_t 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.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_meta_get_broadcast_audio_immediate_rend_flag(const esp_ble_audio_codec_cfg_t *codec_cfg, bool *found)

Extract broadcast audio immediate rendering flag.

Parameters:

• codec_cfg -- The codec data to search in.

• found -- Indicate if the flag is found on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_meta_set_broadcast_audio_immediate_rend_flag(esp_ble_audio_codec_cfg_t *codec_cfg)

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

Parameters:

codec_cfg -- The codec configuration to set data for.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_meta_get_assisted_listening_stream(const esp_ble_audio_codec_cfg_t *codec_cfg, esp_ble_audio_assisted_listening_stream_t *val)

Extract assisted listening stream.

Parameters:

• codec_cfg -- The codec data to search in.

• val -- The assisted listening stream value on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_meta_set_assisted_listening_stream(esp_ble_audio_codec_cfg_t *codec_cfg, esp_ble_audio_assisted_listening_stream_t val)

Set the assisted listening stream value of a codec configuration metadata.

Parameters:

• codec_cfg -- The codec configuration to set data for.

• val -- The assisted listening stream value to set.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_meta_get_broadcast_name(const esp_ble_audio_codec_cfg_t *codec_cfg, const uint8_t **broadcast_name, size_t *broadcast_name_len)

Extract broadcast name.

Parameters:

• codec_cfg -- The codec data to search in.

• broadcast_name -- Pointer to the UTF-8 formatted broadcast name.

• broadcast_name_len -- The length of the broadcast_name (may be 0) on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_meta_set_broadcast_name(esp_ble_audio_codec_cfg_t *codec_cfg, const uint8_t *broadcast_name, size_t broadcast_name_len)

Set the broadcast name of a codec configuration metadata.

Parameters:

• codec_cfg -- The codec configuration to set data for.

• broadcast_name -- The broadcast name to set.

• broadcast_name_len -- The length of broadcast_name.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_meta_get_extended(const esp_ble_audio_codec_cfg_t *codec_cfg, const uint8_t **extended_meta, size_t *extended_meta_len)

Extract extended metadata.

Parameters:

• codec_cfg -- The codec data to search in.

• extended_meta -- Pointer to the extended metadata.

• extended_meta_len -- The length of the extended_meta (may be 0) on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_meta_set_extended(esp_ble_audio_codec_cfg_t *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.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_meta_get_vendor(const esp_ble_audio_codec_cfg_t *codec_cfg, const uint8_t **vendor_meta, size_t *vendor_meta_len)

Extract vendor specific metadata.

Parameters:

• codec_cfg -- The codec data to search in.

• vendor_meta -- Pointer to the vendor specific metadata.

• vendor_meta_len -- The length of the vendor_meta (may be 0) on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cfg_meta_set_vendor(esp_ble_audio_codec_cfg_t *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.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_get_val(const esp_ble_audio_codec_cap_t *codec_cap, esp_ble_audio_codec_cap_type_t type, const uint8_t **data, size_t *data_len)

Lookup a specific value based on type.

Parameters:

• codec_cap -- The codec data to search in.

• type -- The type id to look for.

• data -- Pointer to the data-pointer to update when item is found.

• data_len -- Length of found data (may be 0) on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_set_val(esp_ble_audio_codec_cap_t *codec_cap, esp_ble_audio_codec_cap_type_t type, const uint8_t *data, size_t data_len)

Set or add a specific codec capability value.

Parameters:

• codec_cap -- 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.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_unset_val(esp_ble_audio_codec_cap_t *codec_cap, esp_ble_audio_codec_cap_type_t type)

Unset a specific codec capability value.

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

Parameters:

• codec_cap -- The codec data to set the value in.

• type -- The type id to unset.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_get_freq(const esp_ble_audio_codec_cap_t *codec_cap, esp_ble_audio_codec_cap_freq_t *freq)

Extract the frequency from a codec capability.

Parameters:

• codec_cap -- The codec capabilities to extract data from.

• freq -- Bitfield of supported frequencies on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_set_freq(esp_ble_audio_codec_cap_t *codec_cap, esp_ble_audio_codec_cap_freq_t freq)

Set the supported frequencies of a codec capability.

Parameters:

• codec_cap -- The codec capabilities to set data for.

• freq -- The supported frequencies to set.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_get_frame_dur(const esp_ble_audio_codec_cap_t *codec_cap, esp_ble_audio_codec_cap_frame_dur_t *frame_dur)

Extract the frequency from a codec capability.

Parameters:

• codec_cap -- The codec capabilities to extract data from.

• frame_dur -- Bitfield of supported frame durations on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_set_frame_dur(esp_ble_audio_codec_cap_t *codec_cap, esp_ble_audio_codec_cap_frame_dur_t frame_dur)

Set the frame duration of a codec capability.

Parameters:

• codec_cap -- The codec capabilities to set data for.

• frame_dur -- The frame duration to set.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_get_supported_audio_chan_counts(const esp_ble_audio_codec_cap_t *codec_cap, esp_ble_audio_codec_cap_chan_count_t *chan_count, bool fallback_to_default)

Extract the frequency from a codec capability.

Parameters:

• codec_cap -- The codec capabilities to extract data from.

• chan_count -- Number of supported channel counts on success.

• fallback_to_default -- If true this function will provide the default value of 1 if the type is not found when codec_cap.id is BT_HCI_CODING_FORMAT_LC3.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_set_supported_audio_chan_counts(esp_ble_audio_codec_cap_t *codec_cap, esp_ble_audio_codec_cap_chan_count_t chan_count)

Set the channel count of a codec capability.

Parameters:

• codec_cap -- The codec capabilities to set data for.

• chan_count -- The channel count frequency to set.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_get_octets_per_frame(const esp_ble_audio_codec_cap_t *codec_cap, esp_ble_audio_codec_octets_per_codec_frame_t *codec_frame)

Extract the supported octets per codec frame from a codec capability.

Parameters:

• codec_cap -- The codec capabilities to extract data from.

• codec_frame -- Struct to place the resulting values in.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_set_octets_per_frame(esp_ble_audio_codec_cap_t *codec_cap, const esp_ble_audio_codec_octets_per_codec_frame_t *codec_frame)

Set the octets per codec frame of a codec capability.

Parameters:

• codec_cap -- The codec capabilities to set data for.

• codec_frame -- The octets per codec frame to set.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_get_max_codec_frames_per_sdu(const esp_ble_audio_codec_cap_t *codec_cap, uint8_t *codec_frames_per_sdu, bool fallback_to_default)

Extract the maximum codec frames per SDU from a codec capability.

Parameters:

• codec_cap -- The codec capabilities to extract data from.

• codec_frames_per_sdu -- Maximum number of codec frames per SDU supported on success.

• fallback_to_default -- If true this function will provide the default value of 1 if the type is not found when codec_cap.id is BT_HCI_CODING_FORMAT_LC3.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_set_max_codec_frames_per_sdu(esp_ble_audio_codec_cap_t *codec_cap, uint8_t codec_frames_per_sdu)

Set the maximum codec frames per SDU of a codec capability.

Parameters:

• codec_cap -- The codec capabilities to set data for.

• codec_frames_per_sdu -- The maximum codec frames per SDU to set.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_meta_get_val(const esp_ble_audio_codec_cap_t *codec_cap, esp_ble_audio_metadata_type_t type, const uint8_t **data, size_t *data_len)

Lookup a specific metadata value based on type.

Parameters:

• codec_cap -- The codec data to search in.

• type -- The type id to look for.

• data -- Pointer to the data-pointer to update when item is found.

• data_len -- Length of found data (may be 0) on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_meta_set_val(esp_ble_audio_codec_cap_t *codec_cap, esp_ble_audio_metadata_type_t type, const uint8_t *data, size_t data_len)

Set or add a specific codec capability metadata value.

Parameters:

• codec_cap -- The codec capability to set the value in.

• type -- The type id to set.

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

• data_len -- Length of data.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_meta_unset_val(esp_ble_audio_codec_cap_t *codec_cap, esp_ble_audio_metadata_type_t type)

Unset a specific codec capability metadata value.

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

Parameters:

• codec_cap -- The codec data to set the value in.

• type -- The type id to unset.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_meta_get_pref_context(const esp_ble_audio_codec_cap_t *codec_cap, esp_ble_audio_context_t *ctx)

Extract preferred contexts.

Parameters:

• codec_cap -- The codec data to search in.

• ctx -- The preferred context type on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_meta_set_pref_context(esp_ble_audio_codec_cap_t *codec_cap, esp_ble_audio_context_t ctx)

Set the preferred context of a codec capability metadata.

Parameters:

• codec_cap -- The codec capability to set data for.

• ctx -- The preferred context to set.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_meta_get_stream_context(const esp_ble_audio_codec_cap_t *codec_cap, esp_ble_audio_context_t *ctx)

Extract stream contexts.

Parameters:

• codec_cap -- The codec data to search in.

• ctx -- The stream context type on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_meta_set_stream_context(esp_ble_audio_codec_cap_t *codec_cap, esp_ble_audio_context_t ctx)

Set the stream context of a codec capability metadata.

Parameters:

• codec_cap -- The codec capability to set data for.

• ctx -- The stream context to set.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_meta_get_program_info(const esp_ble_audio_codec_cap_t *codec_cap, const uint8_t **program_info, size_t *program_info_len)

Extract program info.

Parameters:

• codec_cap -- The codec data to search in.

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

• program_info_len -- The length of the program_info (may be 0) on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_meta_set_program_info(esp_ble_audio_codec_cap_t *codec_cap, const uint8_t *program_info, size_t program_info_len)

Set the program info of a codec capability metadata.

Parameters:

• codec_cap -- The codec capability to set data for.

• program_info -- The program info to set.

• program_info_len -- The length of program_info.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_meta_get_language(const esp_ble_audio_codec_cap_t *codec_cap, const uint8_t **language)

Extract language.

Parameters:

• codec_cap -- The codec data to search in.

• language -- Pointer to the language bytes (of length ESP_BLE_AUDIO_LANG_SIZE).

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_meta_set_language(esp_ble_audio_codec_cap_t *codec_cap, const uint8_t language[ESP_BLE_AUDIO_LANG_SIZE])

Set the language of a codec capability metadata.

Parameters:

• codec_cap -- The codec capability to set data for.

• language -- The 24-bit language to set.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_meta_get_ccid_list(const esp_ble_audio_codec_cap_t *codec_cap, const uint8_t **ccid_list, size_t *ccid_list_len)

Extract CCID list.

Parameters:

• codec_cap -- The codec data to search in.

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

• ccid_list_len -- The length of the ccid_list (may be 0) on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_meta_set_ccid_list(esp_ble_audio_codec_cap_t *codec_cap, const uint8_t *ccid_list, size_t ccid_list_len)

Set the CCID list of a codec capability metadata.

Parameters:

• codec_cap -- The codec capability to set data for.

• ccid_list -- The program info to set.

• ccid_list_len -- The length of ccid_list.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_meta_get_parental_rating(const esp_ble_audio_codec_cap_t *codec_cap, esp_ble_audio_parental_rating_t *parental_rating)

Extract parental rating.

Parameters:

• codec_cap -- The codec data to search in.

• parental_rating -- The parental rating on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_meta_set_parental_rating(esp_ble_audio_codec_cap_t *codec_cap, esp_ble_audio_parental_rating_t parental_rating)

Set the parental rating of a codec capability metadata.

Parameters:

• codec_cap -- The codec capability to set data for.

• parental_rating -- The parental rating to set.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_meta_get_program_info_uri(const esp_ble_audio_codec_cap_t *codec_cap, const uint8_t **program_info_uri, size_t *program_info_uri_len)

Extract program info URI.

Parameters:

• codec_cap -- The codec data to search in.

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

• program_info_uri_len -- The length of the program_info_uri (may be 0) on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_meta_set_program_info_uri(esp_ble_audio_codec_cap_t *codec_cap, const uint8_t *program_info_uri, size_t program_info_uri_len)

Set the program info URI of a codec capability metadata.

Parameters:

• codec_cap -- The codec capability to set data for.

• program_info_uri -- The program info URI to set.

• program_info_uri_len -- The length of program_info_uri.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_meta_get_audio_active_state(const esp_ble_audio_codec_cap_t *codec_cap, esp_ble_audio_active_state_t *state)

Extract audio active state.

Parameters:

• codec_cap -- The codec data to search in.

• state -- The preferred context type on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_meta_set_audio_active_state(esp_ble_audio_codec_cap_t *codec_cap, esp_ble_audio_active_state_t state)

Set the audio active state of a codec capability metadata.

Parameters:

• codec_cap -- The codec capability to set data for.

• state -- The audio active state to set.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_meta_get_broadcast_audio_immediate_rend_flag(const esp_ble_audio_codec_cap_t *codec_cap, bool *found)

Extract broadcast audio immediate rendering flag.

Parameters:

• codec_cap -- The codec data to search in.

• found -- Indicate if the flag is found on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_meta_set_broadcast_audio_immediate_rend_flag(esp_ble_audio_codec_cap_t *codec_cap)

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

Parameters:

codec_cap -- The codec capability to set data for.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_meta_get_assisted_listening_stream(const esp_ble_audio_codec_cap_t *codec_cap, esp_ble_audio_assisted_listening_stream_t *val)

Extract assisted listening stream.

Parameters:

• codec_cap -- The codec data to search in.

• val -- The assisted listening stream value on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_meta_set_assisted_listening_stream(esp_ble_audio_codec_cap_t *codec_cap, esp_ble_audio_assisted_listening_stream_t val)

Set the assisted listening stream value of a codec capability metadata.

Parameters:

• codec_cap -- The codec capability to set data for.

• val -- The assisted listening stream value to set.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_meta_get_broadcast_name(const esp_ble_audio_codec_cap_t *codec_cap, const uint8_t **broadcast_name, size_t *broadcast_name_len)

Extract broadcast name.

Parameters:

• codec_cap -- The codec data to search in.

• broadcast_name -- Pointer to the UTF-8 formatted broadcast name.

• broadcast_name_len -- The length of the broadcast_name (may be 0) on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_meta_set_broadcast_name(esp_ble_audio_codec_cap_t *codec_cap, const uint8_t *broadcast_name, size_t broadcast_name_len)

Set the broadcast name of a codec capability metadata.

Parameters:

• codec_cap -- The codec capability to set data for.

• broadcast_name -- The broadcast name to set.

• broadcast_name_len -- The length of broadcast_name.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_meta_get_extended(const esp_ble_audio_codec_cap_t *codec_cap, const uint8_t **extended_meta, size_t *extended_meta_len)

Extract extended metadata.

Parameters:

• codec_cap -- The codec data to search in.

• extended_meta -- Pointer to the extended metadata.

• extended_meta_len -- The length of the extended_meta (may be 0) on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_meta_set_extended(esp_ble_audio_codec_cap_t *codec_cap, const uint8_t *extended_meta, size_t extended_meta_len)

Set the extended metadata of a codec capability metadata.

Parameters:

• codec_cap -- The codec capability to set data for.

• extended_meta -- The extended metadata to set.

• extended_meta_len -- The length of extended_meta.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_meta_get_vendor(const esp_ble_audio_codec_cap_t *codec_cap, const uint8_t **vendor_meta, size_t *vendor_meta_len)

Extract vendor specific metadata.

Parameters:

• codec_cap -- The codec data to search in.

• vendor_meta -- Pointer to the vendor specific metadata.

• vendor_meta_len -- The length of the vendor_meta (may be 0) on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_codec_cap_meta_set_vendor(esp_ble_audio_codec_cap_t *codec_cap, const uint8_t *vendor_meta, size_t vendor_meta_len)

Set the vendor specific metadata of a codec capability metadata.

Parameters:

• codec_cap -- The codec capability to set data for.

• vendor_meta -- The vendor specific metadata to set.

• vendor_meta_len -- The length of vendor_meta.

Returns:

ESP_OK on success, or an error code on failure.

Macros

ESP_BLE_AUDIO_CODEC_DATA

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. Target low latency

ESP_BLE_AUDIO_CODEC_CFG_TARGET_LATENCY_LOW

Target balanced latency

ESP_BLE_AUDIO_CODEC_CFG_TARGET_LATENCY_BALANCED

Target high latency

ESP_BLE_AUDIO_CODEC_CFG_TARGET_LATENCY_HIGH

ESP_BLE_AUDIO_CODEC_CFG_TARGET_PHY_1M

LE 2M PHY

ESP_BLE_AUDIO_CODEC_CFG_TARGET_PHY_2M

LE Coded PHY

ESP_BLE_AUDIO_CODEC_CFG_TARGET_PHY_CODED

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

Helper to declare esp_ble_audio_codec_cfg_t.

Parameters:

• _id -- Codec ID.

• _cid -- Company ID.

• _vid -- Vendor ID.

• _data -- Codec Specific Data in LVT format.

• _meta -- Codec Specific Metadata in LVT format.

ESP_BLE_AUDIO_CODEC_CFG_LEN(_id, _cid, _vid, _data, _data_len, _meta, _meta_len)

Variant of ESP_BLE_AUDIO_CODEC_CFG with explicit LVT content lengths.

Parameters:

• _id -- Codec ID.

• _cid -- Company ID.

• _vid -- Vendor ID.

• _data -- Codec Specific Data buffer in LVT format.

• _data_len -- Current LVT content length in _data.

• _meta -- Codec Specific Metadata buffer in LVT format.

• _meta_len -- Current LVT content length in _meta.

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

Helper to declare esp_ble_audio_codec_cap_t.

Parameters:

• _id -- Codec ID.

• _cid -- Company ID.

• _vid -- Vendor-specific codec ID.

• _data -- Codec-specific capability data.

• _meta -- Metadata capabilities.

ESP_BLE_AUDIO_CODEC_CAP_LEN(_id, _cid, _vid, _data, _data_len, _meta, _meta_len)

Variant of ESP_BLE_AUDIO_CODEC_CAP with explicit LVT content lengths.

ESP_BLE_AUDIO_CODEC_CAP_TYPE_FREQ

< Supported sampling frequencies Supported frame durations

ESP_BLE_AUDIO_CODEC_CAP_TYPE_DURATION

Supported audio channel counts

ESP_BLE_AUDIO_CODEC_CAP_TYPE_CHAN_COUNT

Supported octets per codec frame

ESP_BLE_AUDIO_CODEC_CAP_TYPE_FRAME_LEN

Supported maximum codec frames per SDU

ESP_BLE_AUDIO_CODEC_CAP_TYPE_FRAME_COUNT

ESP_BLE_AUDIO_CODEC_CAP_FREQ_8KHZ

11.025 Khz sampling frequency

ESP_BLE_AUDIO_CODEC_CAP_FREQ_11KHZ

16 Khz sampling frequency

ESP_BLE_AUDIO_CODEC_CAP_FREQ_16KHZ

22.05 Khz sampling frequency

ESP_BLE_AUDIO_CODEC_CAP_FREQ_22KHZ

24 Khz sampling frequency

ESP_BLE_AUDIO_CODEC_CAP_FREQ_24KHZ

32 Khz sampling frequency

ESP_BLE_AUDIO_CODEC_CAP_FREQ_32KHZ

44.1 Khz sampling frequency

ESP_BLE_AUDIO_CODEC_CAP_FREQ_44KHZ

48 Khz sampling frequency

ESP_BLE_AUDIO_CODEC_CAP_FREQ_48KHZ

88.2 Khz sampling frequency

ESP_BLE_AUDIO_CODEC_CAP_FREQ_88KHZ

96 Khz sampling frequency

ESP_BLE_AUDIO_CODEC_CAP_FREQ_96KHZ

176.4 Khz sampling frequency

ESP_BLE_AUDIO_CODEC_CAP_FREQ_176KHZ

192 Khz sampling frequency

ESP_BLE_AUDIO_CODEC_CAP_FREQ_192KHZ

384 Khz sampling frequency

ESP_BLE_AUDIO_CODEC_CAP_FREQ_384KHZ

Any frequency capability

ESP_BLE_AUDIO_CODEC_CAP_FREQ_ANY

ESP_BLE_AUDIO_CODEC_CAP_DURATION_7_5

10 msec frame duration capability

ESP_BLE_AUDIO_CODEC_CAP_DURATION_10

Any frame duration capability

ESP_BLE_AUDIO_CODEC_CAP_DURATION_ANY

7.5 msec preferred frame duration capability

ESP_BLE_AUDIO_CODEC_CAP_DURATION_PREFER_7_5

10 msec preferred frame duration capability

ESP_BLE_AUDIO_CODEC_CAP_DURATION_PREFER_10

ESP_BLE_AUDIO_CODEC_CAP_CHAN_COUNT_1

Supporting 2 channel

ESP_BLE_AUDIO_CODEC_CAP_CHAN_COUNT_2

Supporting 3 channel

ESP_BLE_AUDIO_CODEC_CAP_CHAN_COUNT_3

Supporting 4 channel

ESP_BLE_AUDIO_CODEC_CAP_CHAN_COUNT_4

Supporting 5 channel

ESP_BLE_AUDIO_CODEC_CAP_CHAN_COUNT_5

Supporting 6 channel

ESP_BLE_AUDIO_CODEC_CAP_CHAN_COUNT_6

Supporting 7 channel

ESP_BLE_AUDIO_CODEC_CAP_CHAN_COUNT_7

Supporting 8 channel

ESP_BLE_AUDIO_CODEC_CAP_CHAN_COUNT_8

Supporting all channels

ESP_BLE_AUDIO_CODEC_CAP_CHAN_COUNT_ANY

Minimum supported channel counts

ESP_BLE_AUDIO_CODEC_CAP_CHAN_COUNT_MIN

Maximum supported channel counts

ESP_BLE_AUDIO_CODEC_CAP_CHAN_COUNT_MAX

ESP_BLE_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 ESP_BLE_AUDIO_CODEC_CAP_CHAN_COUNT_MIN to ESP_BLE_AUDIO_CODEC_CAP_CHAN_COUNT_MAX inclusive.

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

ESP_BLE_AUDIO_CODEC_CFG_FREQ

Frame duration

ESP_BLE_AUDIO_CODEC_CFG_DURATION

Audio channel allocation

ESP_BLE_AUDIO_CODEC_CFG_CHAN_ALLOC

Octets per codec frame

ESP_BLE_AUDIO_CODEC_CFG_FRAME_LEN

Codec frame blocks per SDU

ESP_BLE_AUDIO_CODEC_CFG_FRAME_BLKS_PER_SDU

ESP_BLE_AUDIO_CODEC_CFG_FREQ_8KHZ

11.025 Khz codec sampling frequency

ESP_BLE_AUDIO_CODEC_CFG_FREQ_11KHZ

16 Khz codec sampling frequency

ESP_BLE_AUDIO_CODEC_CFG_FREQ_16KHZ

22.05 Khz codec sampling frequency

ESP_BLE_AUDIO_CODEC_CFG_FREQ_22KHZ

24 Khz codec sampling frequency

ESP_BLE_AUDIO_CODEC_CFG_FREQ_24KHZ

32 Khz codec sampling frequency

ESP_BLE_AUDIO_CODEC_CFG_FREQ_32KHZ

44.1 Khz codec sampling frequency

ESP_BLE_AUDIO_CODEC_CFG_FREQ_44KHZ

48 Khz codec sampling frequency

ESP_BLE_AUDIO_CODEC_CFG_FREQ_48KHZ

88.2 Khz codec sampling frequency

ESP_BLE_AUDIO_CODEC_CFG_FREQ_88KHZ

96 Khz codec sampling frequency

ESP_BLE_AUDIO_CODEC_CFG_FREQ_96KHZ

176.4 Khz codec sampling frequency

ESP_BLE_AUDIO_CODEC_CFG_FREQ_176KHZ

192 Khz codec sampling frequency

ESP_BLE_AUDIO_CODEC_CFG_FREQ_192KHZ

384 Khz codec sampling frequency

ESP_BLE_AUDIO_CODEC_CFG_FREQ_384KHZ

ESP_BLE_AUDIO_CODEC_CFG_DURATION_7_5

10 msec Frame Duration configuration

ESP_BLE_AUDIO_CODEC_CFG_DURATION_10

Type Definitions

typedef enum bt_audio_codec_cfg_target_latency esp_ble_audio_codec_cfg_target_latency_t

Codec configuration target latency LE 1M PHY

typedef enum bt_audio_codec_cfg_target_phy esp_ble_audio_codec_cfg_target_phy_t

Codec configuration target PHY

typedef enum bt_audio_codec_cap_type esp_ble_audio_codec_cap_type_t

Codec capability types 8 Khz sampling frequency

typedef enum bt_audio_codec_cap_freq esp_ble_audio_codec_cap_freq_t

Supported frequencies bitfield 7.5 msec frame duration capability

typedef enum bt_audio_codec_cap_frame_dur esp_ble_audio_codec_cap_frame_dur_t

Supported frame durations bitfield Supporting 1 channel

typedef enum bt_audio_codec_cap_chan_count esp_ble_audio_codec_cap_chan_count_t

Supported audio capabilities channel count bitfield Sampling frequency

typedef enum bt_audio_codec_cfg_type esp_ble_audio_codec_cfg_type_t

Codec configuration types 8 Khz codec sampling frequency

typedef enum bt_audio_codec_cfg_freq esp_ble_audio_codec_cfg_freq_t

Codec configuration sampling frequency 7.5 msec Frame Duration configuration

typedef enum bt_audio_codec_cfg_frame_dur esp_ble_audio_codec_cfg_frame_dur_t

Codec configuration frame duration

typedef struct bt_audio_codec_cfg esp_ble_audio_codec_cfg_t

Codec specific configuration structure

typedef struct bt_audio_codec_cap esp_ble_audio_codec_cap_t

Codec capability structure

typedef struct bt_audio_codec_octets_per_codec_frame esp_ble_audio_codec_octets_per_codec_frame_t

Struct to hold minimum and maximum supported codec frame sizes

Common Audio Profile (CAP)

Header File

• components/bt/esp_ble_audio/api/include/esp_ble_audio_cap_api.h

• This header file can be included with:

  #include "esp_ble_audio_cap_api.h"
  

• This header file is a part of the API provided by the bt component. To declare that your component depends on bt, add the following to your CMakeLists.txt:

  REQUIRES bt
  

  or

  PRIV_REQUIRES bt
  

Functions

esp_err_t esp_ble_audio_cap_acceptor_register(const esp_ble_audio_csip_set_member_register_param_t *param, esp_ble_audio_csip_set_member_svc_inst_t **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.

Parameters:

• param -- Coordinated Set Identification Service register parameters.

• svc_inst -- Pointer to the registered Coordinated Set Identification Service.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_initiator_unicast_discover(uint16_t conn_handle)

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_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_stream_ops_register(esp_ble_audio_cap_stream_t *stream, esp_ble_audio_bap_stream_ops_t *ops)

Register Audio operations for a Common Audio Profile stream.

Register Audio operations for a stream.

Parameters:

• stream -- Stream object.

• ops -- Stream operations structure.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_stream_send(esp_ble_audio_cap_stream_t *stream, const uint8_t *sdu, uint16_t sdu_len, uint16_t seq_num)

Send data to Common Audio Profile stream without timestamp.

Sends data over the specified CAP audio stream with a sequence number.

Parameters:

• stream -- Stream object.

• sdu -- Buffer containing data to be sent.

• sdu_len -- Length of data to be sent.

• seq_num -- Packet Sequence number. This value shall be incremented for each call to this function and at least once per SDU interval for a specific channel.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_stream_send_ts(esp_ble_audio_cap_stream_t *stream, const uint8_t *sdu, uint16_t sdu_len, uint16_t seq_num, uint32_t ts)

Send data to Common Audio Profile stream with timestamp.

Sends data over the specified CAP audio stream with a sequence number.

Parameters:

• stream -- Stream object.

• sdu -- Buffer containing data to be sent.

• sdu_len -- Length of data to be sent.

• seq_num -- Packet Sequence number. This value shall be incremented for each call to this function and at least once per SDU interval for a specific channel.

• ts -- Timestamp of the SDU in microseconds (us). This value can be used to transmit multiple SDUs in the same SDU interval in a CIG or BIG.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_stream_get_tx_sync(esp_ble_audio_cap_stream_t *stream, esp_ble_iso_tx_info_t *info)

Get ISO transmission timing info for a Common Audio Profile stream.

Parameters:

• stream -- Stream object.

• info -- Transmit info object.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_unicast_group_create(const esp_ble_audio_cap_unicast_group_param_t *param, esp_ble_audio_cap_unicast_group_t **unicast_group)

Create unicast group.

Create a new audio unicast group with one or more audio streams as a unicast client. All streams shall share the same framing. All streams in the same direction shall share the same interval and latency (see esp_ble_audio_bap_qos_cfg_t).

Parameters:

• param -- The unicast group create parameters.

• unicast_group -- Pointer to the unicast group created.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_unicast_group_reconfig(esp_ble_audio_cap_unicast_group_t *unicast_group, const esp_ble_audio_cap_unicast_group_param_t *param)

Reconfigure unicast group.

Reconfigure a unicast group with one or more audio streams as a unicast client. All streams shall share the same framing. All streams in the same direction shall share the same interval and latency (see esp_ble_audio_bap_qos_cfg_t). All streams in param shall already belong to unicast_group. Use esp_ble_audio_cap_unicast_group_add_streams() to add additional streams.

Parameters:

• unicast_group -- Pointer to the unicast group created.

• param -- The unicast group reconfigure parameters.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_unicast_group_add_streams(esp_ble_audio_cap_unicast_group_t *unicast_group, const esp_ble_audio_cap_unicast_group_stream_pair_param_t params[], size_t num_param)

Add streams to a unicast group as a unicast client.

This function can be used to add additional streams to a esp_ble_audio_cap_unicast_group_t.

This can be called at any time before any of the streams in the group has been started (see esp_ble_audio_bap_stream_ops_t.started()). This can also be called after the streams have been stopped (see esp_ble_audio_bap_stream_ops_t.stopped()).

Once a stream has been added to a unicast group, it cannot be removed. To remove a stream from a group, the group must be deleted with esp_ble_audio_cap_unicast_group_delete(), but this will require all streams in the group to be released first.

Parameters:

• unicast_group -- Pointer to the unicast group

• params -- Array of stream parameters with streams being added to the group.

• num_param -- Number of parameters in params.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_unicast_group_delete(esp_ble_audio_cap_unicast_group_t *unicast_group)

Delete audio unicast group.

Delete a audio unicast group as a client. All streams in the group shall be in the idle or configured state.

Parameters:

unicast_group -- Pointer to the unicast group to delete.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_initiator_register_cb(const esp_ble_audio_cap_initiator_cb_t *cb)

Register Common Audio Profile Initiator callbacks.

Parameters:

cb -- The callback structure. Shall remain static.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_initiator_unregister_cb(const esp_ble_audio_cap_initiator_cb_t *cb)

Unregister Common Audio Profile Initiator callbacks.

Parameters:

cb -- The callback structure that was previously registered.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_initiator_unicast_audio_start(const esp_ble_audio_cap_unicast_audio_start_param_t *param)

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

Parameters:

param -- Parameters to start the audio streams.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_initiator_unicast_audio_update(const esp_ble_audio_cap_unicast_audio_update_param_t *param)

Update unicast audio streams.

This will update the metadata of one or more streams.

Parameters:

param -- Update parameters.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_initiator_unicast_audio_stop(const esp_ble_audio_cap_unicast_audio_stop_param_t *param)

Stop unicast audio streams.

This will stop one or more streams.

Parameters:

param -- Stop parameters.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_initiator_unicast_audio_cancel(void)

Cancel any current Common Audio Profile procedure.

This will stop the current procedure from continuing and making it possible to run a new Common Audio Profile procedure.

It is recommended to do this if any existing procedure takes longer time than expected, which could indicate a missing response from the Common Audio Profile Acceptor.

This does not send any requests to any Common Audio Profile Acceptors involved with the current procedure, and thus notifications from the Common Audio Profile Acceptors may arrive after this has been called. It is thus recommended to either only use this if a procedure has stalled, or wait a short while before starting any new Common Audio Profile procedure after this has been called to avoid getting notifications from the cancelled procedure. The wait time depends on the connection interval, the number of devices in the previous procedure and the behavior of the Common Audio Profile Acceptors.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_initiator_broadcast_audio_create(const esp_ble_audio_cap_initiator_broadcast_create_param_t *param, esp_ble_audio_cap_broadcast_source_t **broadcast_source)

Create a Common Audio Profile broadcast source.

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

Parameters:

• param -- Parameters to start the audio streams.

• broadcast_source -- Pointer to the broadcast source created.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_initiator_broadcast_audio_start(esp_ble_audio_cap_broadcast_source_t *broadcast_source, uint8_t adv_handle)

Start Common Audio Profile broadcast source.

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

Parameters:

• broadcast_source -- Pointer to the broadcast source.

• adv_handle -- Handle of an extended advertising set with periodic advertising configured.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_initiator_broadcast_audio_update(esp_ble_audio_cap_broadcast_source_t *broadcast_source, const uint8_t meta[], size_t meta_len)

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

Parameters:

• broadcast_source -- The broadcast source to update.

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

• meta_len -- The length of meta.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_initiator_broadcast_audio_stop(esp_ble_audio_cap_broadcast_source_t *broadcast_source)

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

Parameters:

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

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_initiator_broadcast_audio_delete(esp_ble_audio_cap_broadcast_source_t *broadcast_source)

Delete Common Audio Profile broadcast source.

Parameters:

broadcast_source -- The broadcast source to delete.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_initiator_broadcast_get_base(esp_ble_audio_cap_broadcast_source_t *broadcast_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 table 3.15 in the Basic Audio Profile v1.0.1 for the structure.

Parameters:

• broadcast_source -- Pointer to the broadcast source.

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

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_handover_register_cb(const esp_ble_audio_cap_handover_cb_t *cb)

Register Common Audio Profile Handover callbacks.

Parameters:

cb -- The callback structure. Shall remain static.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_handover_unregister_cb(const esp_ble_audio_cap_handover_cb_t *cb)

Unregister Common Audio Profile Handover callbacks.

Parameters:

cb -- The callback structure that was previously registered.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_handover_unicast_to_broadcast(const esp_ble_audio_cap_handover_unicast_to_broadcast_param_t *param)

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

All streams in the provided unicast group will be stopped and released. The sink streams will be transferred to a broadcast source, and the broadcast source information will be shared with all accepters that are currently receiving audio. Any stream that is not in the streaming state will only be released.

esp_ble_audio_bap_broadcast_assistant_discover() must have been successfully perform for all members in param before starting this procedure.

Parameters:

param -- The parameters for the handover.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_handover_broadcast_to_unicast(const esp_ble_audio_cap_handover_broadcast_to_unicast_param_t *param)

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.

Parameters:

param -- The parameters for the handover.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_commander_register_cb(const esp_ble_audio_cap_commander_cb_t *cb)

Register Common Audio Profile Commander callbacks.

Parameters:

cb -- The callback structure. Shall remain static.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_commander_unregister_cb(const esp_ble_audio_cap_commander_cb_t *cb)

Unregister Common Audio Profile Commander callbacks.

Parameters:

cb -- The callback structure that was previously registered.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_commander_discover(uint16_t conn_handle)

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_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_commander_cancel(void)

Cancel any current Common Audio Profile commander procedure.

This will stop the current procedure from continuing and making it possible to run a new Common Audio Profile procedure.

It is recommended to do this if any existing procedure takes longer time than expected, which could indicate a missing response from the Common Audio Profile Acceptor.

This does not send any requests to any Common Audio Profile Acceptors involved with the current procedure, and thus notifications from the Common Audio Profile Acceptors may arrive after this has been called. It is thus recommended to either only use this if a procedure has stalled, or wait a short while before starting any new Common Audio Profile procedure after this has been called to avoid getting notifications from the cancelled procedure. The wait time depends on the connection interval, the number of devices in the previous procedure and the behavior of the Common Audio Profile Acceptors.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_commander_broadcast_reception_start(const esp_ble_audio_cap_commander_broadcast_reception_start_param_t *param)

Starts the reception of broadcast audio on one or more remote Common Audio Profile Acceptors.

Parameters:

param -- The parameters to start the broadcast audio

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_commander_broadcast_reception_stop(const esp_ble_audio_cap_commander_broadcast_reception_stop_param_t *param)

Stops the reception of broadcast audio on one or more remote Common Audio Profile Acceptors.

Parameters:

param -- The parameters to stop the broadcast audio

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_commander_distribute_broadcast_code(const esp_ble_audio_cap_commander_distribute_broadcast_code_param_t *param)

Distributes the broadcast code on one or more remote Common Audio Profile Acceptors.

Parameters:

param -- The parameters for distributing the broadcast code.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_commander_change_volume(const esp_ble_audio_cap_commander_change_volume_param_t *param)

Change the volume on one or more Common Audio Profile Acceptors.

Parameters:

param -- The parameters for the volume change.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_commander_change_volume_offset(const esp_ble_audio_cap_commander_change_volume_offset_param_t *param)

Change the volume offset on one or more Common Audio Profile Acceptors.

Parameters:

param -- The parameters for the volume offset change.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_commander_change_volume_mute_state(const esp_ble_audio_cap_commander_change_volume_mute_state_param_t *param)

Change the volume mute state on one or more Common Audio Profile Acceptors.

Parameters:

param -- The parameters for the volume mute state change.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_commander_change_microphone_mute_state(const esp_ble_audio_cap_commander_change_microphone_mute_state_param_t *param)

Change the microphone mute state on one or more Common Audio Profile Acceptors.

Parameters:

param -- The parameters for the microphone mute state change.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_cap_commander_change_microphone_gain_setting(const esp_ble_audio_cap_commander_change_microphone_gain_setting_param_t *param)

Change the microphone gain setting on one or more Common Audio Profile Acceptors.

Parameters:

param -- The parameters for the microphone gain setting change.

Returns:

ESP_OK on success, or an error code on failure.

Macros

ESP_BLE_AUDIO_CAP_SET_TYPE_AD_HOC

< The set is an ad-hoc set The set is a CSIP Coordinated Set

ESP_BLE_AUDIO_CAP_SET_TYPE_CSIP

Type Definitions

typedef enum bt_cap_set_type esp_ble_audio_cap_set_type_t

Type of CAP set

typedef struct bt_cap_stream esp_ble_audio_cap_stream_t

Common Audio Profile stream structure

typedef struct bt_cap_broadcast_source esp_ble_audio_cap_broadcast_source_t

Common Audio Broadcast Source structure

typedef struct bt_cap_unicast_group esp_ble_audio_cap_unicast_group_t

Common Audio Unicast Group structure

typedef struct bt_cap_initiator_cb esp_ble_audio_cap_initiator_cb_t

Callback structure for CAP procedures

typedef union bt_cap_set_member esp_ble_audio_cap_set_member_t

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

typedef struct bt_cap_unicast_group_stream_param esp_ble_audio_cap_unicast_group_stream_param_t

Parameter structure for each stream in the unicast group

typedef struct bt_cap_unicast_group_stream_pair_param esp_ble_audio_cap_unicast_group_stream_pair_param_t

typedef struct bt_cap_unicast_group_param esp_ble_audio_cap_unicast_group_param_t

Parameters for the creating unicast groups

typedef struct bt_cap_unicast_audio_start_stream_param esp_ble_audio_cap_unicast_audio_start_stream_param_t

CAP unicast audio stream specific parameters for starting audio

typedef struct bt_cap_unicast_audio_start_param esp_ble_audio_cap_unicast_audio_start_param_t

CAP unicast audio specific parameters for starting audio

typedef struct bt_cap_unicast_audio_update_stream_param esp_ble_audio_cap_unicast_audio_update_stream_param_t

CAP unicast audio stream specific parameters for updating audio

typedef struct bt_cap_unicast_audio_update_param esp_ble_audio_cap_unicast_audio_update_param_t

CAP unicast audio specific parameters for updating audio

typedef struct bt_cap_unicast_audio_stop_param esp_ble_audio_cap_unicast_audio_stop_param_t

CAP unicast audio specific parameters for stopping audio

typedef struct bt_cap_initiator_broadcast_stream_param esp_ble_audio_cap_initiator_broadcast_stream_param_t

CAP Initiator broadcast audio stream specific parameters

typedef struct bt_cap_initiator_broadcast_subgroup_param esp_ble_audio_cap_initiator_broadcast_subgroup_param_t

CAP Initiator broadcast audio subgroup specific parameters

typedef struct bt_cap_initiator_broadcast_create_param esp_ble_audio_cap_initiator_broadcast_create_param_t

CAP Initiator broadcast audio specific parameters for creating audio

typedef struct bt_cap_handover_cb esp_ble_audio_cap_handover_cb_t

Callback structure for CAP Handover procedures

typedef struct bt_cap_handover_unicast_to_broadcast_param esp_ble_audio_cap_handover_unicast_to_broadcast_param_t

CAP Handover unicast audio to broadcast audio specific parameters

typedef struct bt_cap_handover_broadcast_to_unicast_param esp_ble_audio_cap_handover_broadcast_to_unicast_param_t

CAP Handover broadcast audio to unicast audio specific parameters

typedef struct bt_cap_commander_cb esp_ble_audio_cap_commander_cb_t

Callback structure for CAP Commander procedures

typedef struct bt_cap_commander_broadcast_reception_start_member_param esp_ble_audio_cap_commander_broadcast_reception_start_member_param_t

CAP Commander broadcast audio member specific parameters for starting audio reception

typedef struct bt_cap_commander_broadcast_reception_start_param esp_ble_audio_cap_commander_broadcast_reception_start_param_t

CAP Commander broadcast audio specific parameters for starting audio reception

typedef struct bt_cap_commander_broadcast_reception_stop_member_param esp_ble_audio_cap_commander_broadcast_reception_stop_member_param_t

CAP Commander broadcast audio member specific parameters for stopping audio reception

typedef struct bt_cap_commander_broadcast_reception_stop_param esp_ble_audio_cap_commander_broadcast_reception_stop_param_t

CAP Commander broadcast audio specific parameters for stopping audio reception

typedef struct bt_cap_commander_distribute_broadcast_code_member_param esp_ble_audio_cap_commander_distribute_broadcast_code_member_param_t

CAP Commander member parameters for distributing broadcast code

typedef struct bt_cap_commander_distribute_broadcast_code_param esp_ble_audio_cap_commander_distribute_broadcast_code_param_t

Parameters for distributing broadcast code

typedef struct bt_cap_commander_change_volume_param esp_ble_audio_cap_commander_change_volume_param_t

Parameters for changing absolute volume

typedef struct bt_cap_commander_change_volume_offset_member_param esp_ble_audio_cap_commander_change_volume_offset_member_param_t

Parameters for changing volume offset for a member

typedef struct bt_cap_commander_change_volume_offset_param esp_ble_audio_cap_commander_change_volume_offset_param_t

Parameters for changing volume offset

typedef struct bt_cap_commander_change_volume_mute_state_param esp_ble_audio_cap_commander_change_volume_mute_state_param_t

Parameters for changing volume mute state

typedef struct bt_cap_commander_change_microphone_mute_state_param esp_ble_audio_cap_commander_change_microphone_mute_state_param_t

Parameters for changing microphone mute state

typedef struct bt_cap_commander_change_microphone_gain_setting_member_param esp_ble_audio_cap_commander_change_microphone_gain_setting_member_param_t

Parameters for changing microphone gain setting for a member

typedef struct bt_cap_commander_change_microphone_gain_setting_param esp_ble_audio_cap_commander_change_microphone_gain_setting_param_t

Parameters for changing microphone gain setting

Call Control Profile (CCP)

Header File

• components/bt/esp_ble_audio/api/include/esp_ble_audio_ccp_api.h

• This header file can be included with:

  #include "esp_ble_audio_ccp_api.h"
  

• This header file is a part of the API provided by the bt component. To declare that your component depends on bt, add the following to your CMakeLists.txt:

  REQUIRES bt
  

  or

  PRIV_REQUIRES bt
  

Functions

esp_err_t esp_ble_audio_ccp_call_control_server_register_bearer(const esp_ble_audio_tbs_register_param_t *param, esp_ble_audio_ccp_call_control_server_bearer_t **bearer)

Register a Telephone Bearer.

This will register a Telephone Bearer Service (TBS) (or a Generic Telephone Bearer service (GTBS)) with the provided parameters.

As per the TBS specification, the GTBS shall be instantiated for the feature, and as such a GTBS shall always be registered before any TBS can be registered. Similarly, all TBS shall be unregistered before the GTBS can be unregistered with esp_ble_audio_ccp_call_control_server_unregister_bearer().

Parameters:

• param -- The parameters to initialize the bearer.

• bearer -- Pointer to the initialized bearer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_ccp_call_control_server_unregister_bearer(esp_ble_audio_ccp_call_control_server_bearer_t *bearer)

Unregister a Telephone Bearer.

This will unregister a Telephone Bearer Service (TBS) (or a Generic Telephone Bearer service (GTBS)) with the provided parameters. The bearer shall be registered first by esp_ble_audio_ccp_call_control_server_register_bearer() before it can be unregistered.

All TBS shall be unregistered before the GTBS can be unregistered with.

Parameters:

bearer -- The bearer to unregister.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_ccp_call_control_server_set_bearer_provider_name(esp_ble_audio_ccp_call_control_server_bearer_t *bearer, const char *name)

Set a new bearer provider name.

Parameters:

• bearer -- The bearer to set the name for.

• name -- The new bearer provider name.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_ccp_call_control_server_get_bearer_provider_name(esp_ble_audio_ccp_call_control_server_bearer_t *bearer, const char **name)

Get the bearer provider name.

Parameters:

• bearer -- The bearer to get the name for.

• name -- Pointer that will be updated to be the bearer provider name.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_ccp_call_control_client_discover(esp_ble_conn_t *conn, esp_ble_audio_ccp_call_control_client_t **out_client)

Discovers the Telephone Bearer Service (TBS) support on a remote device.

This will discover the Telephone Bearer Service (TBS) and Generic Telephone Bearer Service (GTBS) on the remote device.

Parameters:

• conn -- Connection to a remote server.

• out_client -- Pointer to client instance on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_ccp_call_control_client_register_cb(esp_ble_audio_ccp_call_control_client_cb_t *cb)

Register callbacks for the Call Control Client.

Parameters:

cb -- The callback struct.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_ccp_call_control_client_unregister_cb(esp_ble_audio_ccp_call_control_client_cb_t *cb)

Unregister callbacks for the Call Control Client.

Parameters:

cb -- The callback struct.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_ccp_call_control_client_get_bearers(esp_ble_audio_ccp_call_control_client_t *client, esp_ble_audio_ccp_call_control_client_bearers_t *bearers)

Get the bearers of a client instance.

Parameters:

• client -- The client to get the bearers of.

• bearers -- The bearers struct that will be populated with the bearers of client.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_ccp_call_control_client_read_bearer_provider_name(esp_ble_audio_ccp_call_control_client_bearer_t *bearer)

Read the bearer provider name of a remote TBS bearer.

Parameters:

bearer -- The bearer to read the name from.

Returns:

ESP_OK on success, or an error code on failure.

Type Definitions

typedef struct bt_ccp_call_control_server_bearer esp_ble_audio_ccp_call_control_server_bearer_t

Abstract Call Control Server Telephone Bearer structure

typedef struct bt_ccp_call_control_client esp_ble_audio_ccp_call_control_client_t

Abstract Call Control Client structure.

typedef struct bt_ccp_call_control_client_bearer esp_ble_audio_ccp_call_control_client_bearer_t

Abstract Call Control Client bearer structure.

typedef struct bt_ccp_call_control_client_bearers esp_ble_audio_ccp_call_control_client_bearers_t

Struct with information about bearers of a client

typedef struct bt_ccp_call_control_client_cb esp_ble_audio_ccp_call_control_client_cb_t

Struct to hold the Telephone Bearer Service client callbacks

Basic Audio Profile (BAP)

Header File

• components/bt/esp_ble_audio/api/include/esp_ble_audio_bap_api.h

• This header file can be included with:

  #include "esp_ble_audio_bap_api.h"
  

• This header file is a part of the API provided by the bt component. To declare that your component depends on bt, add the following to your CMakeLists.txt:

  REQUIRES bt
  

  or

  PRIV_REQUIRES bt
  

Functions

esp_err_t esp_ble_audio_bap_unicast_server_register(const esp_ble_audio_bap_unicast_server_register_param_t *param)

Register the Unicast Server.

Register the Unicast Server. Only a single Unicast Server can be registered at any one time. This will register ASCS in the GATT database.

Parameters:

param -- Registration parameters for ascs.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_unicast_server_unregister(void)

Unregister the Unicast Server.

Unregister the Unicast Server. This will unregister ASCS in the GATT database. Before calling this function, any callbacks registered through esp_ble_audio_bap_unicast_server_register_cb() needs to be unregistered with esp_ble_audio_bap_unicast_server_unregister_cb().

Calling this function will issue an release operation on any ASE in a non-idle state.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_unicast_server_register_cb(const esp_ble_audio_bap_unicast_server_cb_t *cb)

Register unicast server callbacks.

Only one callback structure can be registered, and attempting to registering more than one will result in an error. Prior to calling this function the Unicast Server needs to be registered with esp_ble_audio_bap_unicast_server_register().

Parameters:

cb -- Unicast server callback structure.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_unicast_server_unregister_cb(const esp_ble_audio_bap_unicast_server_cb_t *cb)

Unregister unicast server callbacks.

May only unregister a callback structure that has previously been registered by esp_ble_audio_bap_unicast_server_register_cb().

Calling this function will issue an release operation on any ASE in a non-idle state.

Parameters:

cb -- Unicast server callback structure.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_unicast_server_config_ase(uint16_t conn_handle, esp_ble_audio_bap_stream_t *stream, esp_ble_audio_codec_cfg_t *codec_cfg, const esp_ble_audio_bap_qos_cfg_pref_t *qos_pref)

Initialize and configure a new ASE.

Parameters:

• conn_handle -- Connection handle.

• stream -- Configured stream object to be attached to the ASE.

• codec_cfg -- Codec configuration.

• qos_pref -- Audio Stream Quality of Service Preference.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_unicast_group_create(esp_ble_audio_bap_unicast_group_param_t *param, esp_ble_audio_bap_unicast_group_t **unicast_group)

Create unicast group.

Create a new audio unicast group with one or more audio streams as a unicast client. All streams shall share the same framing. All streams in the same direction shall share the same interval and latency.

Parameters:

• param -- The unicast group create parameters.

• unicast_group -- Pointer to the unicast group created.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_unicast_group_reconfig(esp_ble_audio_bap_unicast_group_t *unicast_group, const esp_ble_audio_bap_unicast_group_param_t *param)

Reconfigure unicast group.

Reconfigure a unicast group with one or more audio streams as a unicast client. All streams shall share the same framing. All streams in the same direction shall share the same interval and latency. All streams in param shall already belong to unicast_group. Use esp_ble_audio_bap_unicast_group_add_streams() to add additional streams.

Parameters:

• unicast_group -- Pointer to the unicast group created.

• param -- The unicast group reconfigure parameters.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_unicast_group_add_streams(esp_ble_audio_bap_unicast_group_t *unicast_group, esp_ble_audio_bap_unicast_group_stream_pair_param_t params[], size_t num_param)

Add streams to a unicast group as a unicast client.

This function can be used to add additional streams to a BAP unicast group.

This can be called at any time before any of the streams in the group has been started. This can also be called after the streams have been stopped.

Once a stream has been added to a unicast group, it cannot be removed. To remove a stream from a group, the group must be deleted with esp_ble_audio_bap_unicast_group_delete(), but this will require all streams in the group to be released first.

Parameters:

• unicast_group -- Pointer to the unicast group.

• params -- Array of stream parameters with streams being added to the group.

• num_param -- Number of parameters in params.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_unicast_group_delete(esp_ble_audio_bap_unicast_group_t *unicast_group)

Delete audio unicast group.

Delete an audio unicast group as a client. All streams in the group shall be in the idle or configured state.

Parameters:

unicast_group -- Pointer to the unicast group to delete.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_unicast_client_register_cb(esp_ble_audio_bap_unicast_client_cb_t *cb)

Register unicast client callbacks.

Only one callback structure can be registered, and attempting to registering more than one will result in an error.

Parameters:

cb -- Unicast client callback structure.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_unicast_client_unregister_cb(esp_ble_audio_bap_unicast_client_cb_t *cb)

Unregister unicast client callbacks.

Parameters:

cb -- Unicast client callback structure to unregister.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_unicast_client_discover(uint16_t conn_handle, esp_ble_audio_dir_t dir)

Discover remote capabilities and endpoints.

This procedure is used by a client to discover remote capabilities and endpoints and notifies via params callback.

Parameters:

• conn_handle -- Connection handle.

• dir -- The type of remote endpoints and capabilities to discover.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_stream_config(uint16_t conn_handle, esp_ble_audio_bap_stream_t *stream, esp_ble_audio_bap_ep_t *ep, esp_ble_audio_codec_cfg_t *codec_cfg)

Configure Audio Stream.

This procedure is used by a client to configure a new stream using the remote endpoint, local capability and codec configuration.

Parameters:

• conn_handle -- Connection handle.

• stream -- Stream object being configured.

• ep -- Remote Audio Endpoint being configured.

• codec_cfg -- Codec configuration.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_stream_qos(uint16_t conn_handle, esp_ble_audio_bap_unicast_group_t *group)

Configure Audio Stream QoS.

This procedure is used by a client to configure the Quality of Service of streams in a unicast group. All streams in the group for the specified conn_handle will have the Quality of Service configured. This shall only be used to configure unicast streams.

Parameters:

• conn_handle -- Connection handle.

• group -- Unicast group object.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_stream_enable(esp_ble_audio_bap_stream_t *stream, const uint8_t meta[], size_t meta_len)

Enable Audio Stream.

This procedure is used by a client to enable a stream.

This shall only be called for unicast streams, as broadcast streams will always be enabled once created.

Parameters:

• stream -- Stream object.

• meta -- Metadata.

• meta_len -- Metadata length.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_stream_connect(esp_ble_audio_bap_stream_t *stream)

Connect unicast audio stream.

This procedure is used by a unicast client to connect the connected isochronous stream (CIS) associated with the audio stream. If two audio streams share a CIS, then this only needs to be done once for those streams. This can only be done for streams in the QoS configured or enabled states.

Parameters:

stream -- Stream object.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_stream_stop(esp_ble_audio_bap_stream_t *stream)

Stop Audio Stream.

This procedure is used by a client to make a stream stop streaming.

This shall only be called for unicast streams. Broadcast sinks cannot be stopped.

Parameters:

stream -- Stream object.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_stream_reconfig(esp_ble_audio_bap_stream_t *stream, esp_ble_audio_codec_cfg_t *codec_cfg)

Reconfigure Audio Stream.

This procedure is used by a unicast client or unicast server to reconfigure a stream to use a different local codec configuration.

This can only be done for unicast streams.

Parameters:

• stream -- Stream object being reconfigured.

• codec_cfg -- Codec configuration.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_stream_metadata(esp_ble_audio_bap_stream_t *stream, const uint8_t meta[], size_t meta_len)

Change Audio Stream Metadata.

This procedure is used by a unicast client or unicast server to change the metadata of a stream.

Parameters:

• stream -- Stream object.

• meta -- Metadata.

• meta_len -- Metadata length.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_stream_disable(esp_ble_audio_bap_stream_t *stream)

Disable Audio Stream.

This procedure is used by a unicast client or unicast server to disable a stream.

This shall only be called for unicast streams, as broadcast streams will always be enabled once created.

Parameters:

stream -- Stream object.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_stream_start(esp_ble_audio_bap_stream_t *stream)

Start Audio Stream.

This procedure is used by a unicast client or unicast server to make a stream start streaming.

For the unicast client, this will send the receiver start ready command to the unicast server for ESP_BLE_AUDIO_DIR_SOURCE ASEs. The CIS is required to be connected first by esp_ble_audio_bap_stream_connect() before the command can be sent.

For the unicast server, this will execute the receiver start ready command on the unicast server for ESP_BLE_AUDIO_DIR_SINK ASEs. If the CIS is not connected yet, the stream will go into the streaming state as soon as the CIS is connected.

This shall only be called for unicast streams.

Broadcast sinks will always be started once synchronized, and broadcast source streams shall be started with esp_ble_audio_bap_broadcast_source_start().

Parameters:

stream -- Stream object.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_stream_release(esp_ble_audio_bap_stream_t *stream)

Release Audio Stream.

This procedure is used by a unicast client or unicast server to release a unicast stream.

Broadcast sink streams cannot be released, but can be deleted by esp_ble_audio_bap_broadcast_sink_delete(). Broadcast source streams cannot be released, but can be deleted by esp_ble_audio_bap_broadcast_source_delete().

Parameters:

stream -- Stream object.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_broadcast_source_register_cb(esp_ble_audio_bap_broadcast_source_cb_t *cb)

Registers callbacks for Broadcast Sources.

Parameters:

cb -- Pointer to the callback structure.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_broadcast_source_unregister_cb(esp_ble_audio_bap_broadcast_source_cb_t *cb)

Unregisters callbacks for Broadcast Sources.

Parameters:

cb -- Pointer to the callback structure.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_broadcast_source_create(esp_ble_audio_bap_broadcast_source_param_t *param, esp_ble_audio_bap_broadcast_source_t **source)

Create audio 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.

No audio data can be sent until esp_ble_audio_bap_broadcast_source_start() has been called and no audio information (BIGInfo) will be visible to scanners.

Parameters:

• param -- Pointer to parameters used to create the broadcast source.

• source -- Pointer to the broadcast source created.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_broadcast_source_reconfig(esp_ble_audio_bap_broadcast_source_t *source, esp_ble_audio_bap_broadcast_source_param_t *param)

Reconfigure audio broadcast source.

Reconfigure an audio broadcast source with a new codec and codec quality of service parameters. This can only be done when the source is stopped.

Since this may modify the Broadcast Audio Source Endpoint (BASE), esp_ble_audio_bap_broadcast_source_get_base() should be called after this to get the new BASE information.

If the param.params_count is smaller than the number of subgroups that have been created in the Broadcast Source, only the first param.params_count subgroups are updated. If a stream exist in a subgroup not part of param, then that stream is left as is (i.e. it is not removed; the only way to remove a stream from a Broadcast Source is to recreate the Broadcast Source).

Parameters:

• source -- Pointer to the broadcast source.

• param -- Pointer to parameters used to reconfigure the broadcast source.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_broadcast_source_update_metadata(esp_ble_audio_bap_broadcast_source_t *source, const uint8_t meta[], size_t meta_len)

Modify the metadata of an audio broadcast source.

Modify the metadata an audio broadcast source. This can only be done when the source is started. To update the metadata in the stopped state, use esp_ble_audio_bap_broadcast_source_reconfig().

Parameters:

• source -- Pointer to the broadcast source.

• meta -- Metadata.

• meta_len -- Length of metadata.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_broadcast_adv_add(esp_ble_audio_bap_broadcast_adv_info_t *info)

Add extended advertising for an audio broadcast source.

Parameters:

info -- Extended advertising information.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_broadcast_adv_delete(esp_ble_audio_bap_broadcast_adv_info_t *info)

Delete extended advertising for an audio broadcast source.

Parameters:

info -- Extended advertising information.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_broadcast_source_start(esp_ble_audio_bap_broadcast_source_t *source, uint8_t adv_handle)

Start audio broadcast source.

Start an audio broadcast source with one or more audio streams. The broadcast source will start advertising BIGInfo, and audio data can be streamed.

Parameters:

• source -- Pointer to the broadcast source.

• adv_handle -- Handle of an extended advertising set with periodic advertising configured.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_broadcast_source_stop(esp_ble_audio_bap_broadcast_source_t *source)

Stop audio broadcast source.

Stop an audio broadcast source. The broadcast source will stop advertising BIGInfo, and audio data can no longer be streamed.

Parameters:

source -- Pointer to the broadcast source.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_broadcast_source_delete(esp_ble_audio_bap_broadcast_source_t *source)

Delete audio broadcast source.

Delete an audio broadcast source. The broadcast source will stop advertising entirely, and the source can no longer be used.

Parameters:

source -- Pointer to the broadcast source.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_broadcast_source_get_base(esp_ble_audio_bap_broadcast_source_t *source, struct net_buf_simple *base_buf)

Get the Broadcast Audio Stream Endpoint of a 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 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:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_broadcast_sink_register_cb(esp_ble_audio_bap_broadcast_sink_cb_t *cb)

Register Broadcast sink callbacks.

It is possible to register multiple struct of callbacks, but a single struct can only be registered once. Registering the same callback multiple times is undefined behavior and may break the stack.

Parameters:

cb -- Broadcast sink callback structure.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_broadcast_sink_create(uint16_t sync_handle, uint32_t broadcast_id, esp_ble_audio_bap_broadcast_sink_t **sink)

Create a Broadcast Sink from a periodic advertising sync.

This should only be done after verifying that the periodic advertising sync is from a Broadcast Source.

The created Broadcast Sink will need to be supplied to esp_ble_audio_bap_broadcast_sink_sync() in order to synchronize to the broadcast audio.

Parameters:

• sync_handle -- Sync handle.

• broadcast_id -- 24-bit broadcast ID.

• sink -- Pointer to the Broadcast Sink created.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_broadcast_sink_sync(esp_ble_audio_bap_broadcast_sink_t *sink, uint32_t indexes_bitfield, esp_ble_audio_bap_stream_t *streams[], const uint8_t broadcast_code[ESP_BLE_ISO_BROADCAST_CODE_SIZE])

Sync to a broadcaster's audio.

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

Parameters:

• sink -- Pointer to the sink object from the base_recv callback.

• indexes_bitfield -- Bitfield of the BIS index to sync to. To sync to e.g. BIS index 1 and 2, this should have the value of BIT(1) | BIT(2).

• streams -- Stream object pointers to be used for the receiver. If multiple BIS indexes shall be synchronized, multiple streams shall be provided.

• broadcast_code -- The 16-octet broadcast code. Shall be supplied if the broadcast is encrypted. If the value is a string or a the value is less than 16 octets, the remaining octets shall be 0.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_broadcast_sink_stop(esp_ble_audio_bap_broadcast_sink_t *sink)

Stop audio broadcast sink.

Stop an audio broadcast sink. The broadcast sink will stop receiving BIGInfo, and audio data can no longer be streamed.

Parameters:

sink -- Pointer to the broadcast sink.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_broadcast_sink_delete(esp_ble_audio_bap_broadcast_sink_t *sink)

Release a broadcast sink.

Once a broadcast sink has been allocated, it can be deleted using this function. If the sink has synchronized to any broadcast audio streams, these must first be stopped using esp_ble_audio_bap_stream_stop.

Parameters:

sink -- Pointer to the sink object to delete.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_scan_delegator_register(esp_ble_audio_bap_scan_delegator_cb_t *cb)

Register the Basic Audio Profile Scan Delegator and BASS.

Register the scan delegator and Broadcast Audio Scan Service (BASS) dynamically at runtime.

Only one set of callbacks can be registered at any one time, and calling this function multiple times will override any previously registered callbacks.

Parameters:

cb -- Pointer to the callback struct.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_scan_delegator_unregister(void)

Unregister the Basic Audio Profile Scan Delegator and BASS.

Unregister the scan delegator and Broadcast Audio Scan Service (BASS) dynamically at runtime.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_scan_delegator_set_pa_state(uint8_t src_id, esp_ble_audio_bap_pa_state_t pa_state)

Set the periodic advertising sync state to syncing.

Set the periodic advertising sync state for a receive state to syncing, notifying Broadcast Assistants.

Parameters:

• src_id -- The source id used to identify the receive state.

• pa_state -- The Periodic Advertising sync state to set. ESP_BLE_AUDIO_BAP_PA_STATE_NOT_SYNCED and ESP_BLE_AUDIO_BAP_PA_STATE_SYNCED is not necessary to provide, as they are handled internally.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_scan_delegator_set_bis_sync_state(uint8_t src_id, uint32_t bis_synced[CONFIG_BT_BAP_BASS_MAX_SUBGROUPS])

Set the sync state of a receive state in the server.

Parameters:

• src_id -- The source id used to identify the receive state.

• bis_synced -- Array of bitfields to set the BIS sync state for each subgroup.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_scan_delegator_add_src(const esp_ble_audio_bap_scan_delegator_add_src_param_t *param, uint8_t *src_id)

Add a receive state source locally.

This will notify any connected clients about the new source. This allows them to modify and even remove it.

Parameters:

• param -- The parameters for adding the new source.

• src_id -- Source ID on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_scan_delegator_mod_src(const esp_ble_audio_bap_scan_delegator_mod_src_param_t *param)

Modify a receive state source.

This will modify the receive state.

Parameters:

param -- The parameters for modifying the source.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_scan_delegator_rem_src(uint8_t src_id)

Remove a receive state source.

This will remove the receive state.

Parameters:

src_id -- The source ID to remove.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_broadcast_assistant_discover(uint16_t conn_handle)

Discover Broadcast Audio Scan Service on the server.

Warning: Only one connection can be active at any time; discovering for a new connection, will delete all previous data.

Parameters:

conn_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_broadcast_assistant_scan_start(uint16_t conn_handle, bool start_scan)

Scan start for BISes for a remote server.

This will let the Broadcast Audio Scan Service server know that this device is actively scanning for broadcast sources. The function can optionally also start scanning, if the caller does not want to start scanning itself.

Parameters:

• conn_handle -- Connection handle.

• start_scan -- Start scanning if true. If false, the application should enable scan itself.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_broadcast_assistant_scan_stop(uint16_t conn_handle)

Stop remote scanning for BISes for a server.

Parameters:

conn_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_broadcast_assistant_register_cb(esp_ble_audio_bap_broadcast_assistant_cb_t *cb)

Registers the callbacks used by Broadcast Audio Scan Service client.

Parameters:

cb -- The callback structure.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_broadcast_assistant_unregister_cb(esp_ble_audio_bap_broadcast_assistant_cb_t *cb)

Unregisters the callbacks used by the Broadcast Audio Scan Service client.

Parameters:

cb -- The callback structure.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_broadcast_assistant_add_src(uint16_t conn_handle, const esp_ble_audio_bap_broadcast_assistant_add_src_param_t *param)

Add a source on the server.

Parameters:

• conn_handle -- Connection handle.

• param -- Parameter struct.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_broadcast_assistant_mod_src(uint16_t conn_handle, const esp_ble_audio_bap_broadcast_assistant_mod_src_param_t *param)

Modify a source on the server.

Parameters:

• conn_handle -- Connection handle.

• param -- Parameter struct.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_broadcast_assistant_set_broadcast_code(uint16_t conn_handle, uint8_t src_id, const uint8_t broadcast_code[ESP_BLE_ISO_BROADCAST_CODE_SIZE])

Set a broadcast code to the specified receive state.

Parameters:

• conn_handle -- Connection handle.

• src_id -- Source ID of the receive state.

• broadcast_code -- The broadcast code.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_broadcast_assistant_rem_src(uint16_t conn_handle, uint8_t src_id)

Remove a source from the server.

Parameters:

• conn_handle -- Connection handle.

• src_id -- Source ID of the receive state.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_broadcast_assistant_read_recv_state(uint16_t conn_handle, uint8_t idx)

Read the specified receive state from the server.

Parameters:

• conn_handle -- Connection handle.

• idx -- The index of the receive start.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_ep_get_info(const esp_ble_audio_bap_ep_t *ep, esp_ble_audio_bap_ep_info_t *info)

Return structure holding information of audio stream endpoint.

Parameters:

• ep -- The audio stream endpoint object.

• info -- The structure object to be filled with the info.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_stream_cb_register(esp_ble_audio_bap_stream_t *stream, esp_ble_audio_bap_stream_ops_t *ops)

Register Audio callbacks for a stream.

Register Audio callbacks for a stream.

Parameters:

• stream -- Stream object.

• ops -- Stream operations structure.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_stream_send(esp_ble_audio_bap_stream_t *stream, const uint8_t *sdu, uint16_t sdu_len, uint16_t seq_num)

Send data to Audio stream without timestamp.

Send data from buffer to the stream.

Parameters:

• stream -- Stream object.

• sdu -- Buffer containing data to be sent.

• sdu_len -- length of data to be sent.

• seq_num -- Packet Sequence number. This value shall be incremented for each call to this function and at least once per SDU interval for a specific channel.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_stream_send_ts(esp_ble_audio_bap_stream_t *stream, const uint8_t *sdu, uint16_t sdu_len, uint16_t seq_num, uint32_t ts)

Send data to Audio stream with timestamp.

Parameters:

• stream -- Stream object.

• sdu -- Buffer containing data to be sent.

• sdu_len -- length of data to be sent.

• seq_num -- Packet Sequence number. This value shall be incremented for each call to this function and at least once per SDU interval for a specific channel.

• ts -- Timestamp of the SDU in microseconds (us). This value can be used to transmit multiple SDUs in the same SDU interval in a CIG or BIG.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_stream_get_tx_sync(esp_ble_audio_bap_stream_t *stream, esp_ble_iso_tx_info_t *info)

Get ISO transmission timing info for a Basic Audio Profile stream.

Reads timing information for transmitted ISO packet on an ISO channel. The HCI_LE_Read_ISO_TX_Sync HCI command is used to retrieve this information from the controller.

Note

An SDU must have already been successfully transmitted on the ISO channel for this function to return successfully.

Parameters:

• stream -- Stream object.

• info -- Transmit info object.

Returns:

ESP_OK on success, or an error code on failure.

const esp_ble_audio_bap_base_t *esp_ble_audio_bap_base_get_base_from_ad(uint8_t data_type, const uint8_t *data, uint8_t data_len)

Generate a pointer to a BASE from periodic advertising data.

Parameters:

• data_type -- Type of the periodic advertising data.

• data -- Pointer of the periodic advertising data.

• data_len -- Length of the periodic advertising data.

Returns:

NULL if the data does not contain a BASE. Pointer to an esp_ble_audio_bap_base_t structure.

esp_err_t esp_ble_audio_bap_base_get_size(const esp_ble_audio_bap_base_t *base, size_t *base_size)

Get the size of a BASE.

Parameters:

• base -- The BASE pointer.

• base_size -- The size of the BASE on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_base_get_pres_delay(const esp_ble_audio_bap_base_t *base, uint32_t *pres_delay)

Get the presentation delay value of a BASE.

Parameters:

• base -- The BASE pointer.

• pres_delay -- The 24-bit presentation delay value on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_base_get_subgroup_count(const esp_ble_audio_bap_base_t *base, uint8_t *subgroup_count)

Get the subgroup count of a BASE.

Parameters:

• base -- The BASE pointer.

• subgroup_count -- The 8-bit subgroup count value on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_base_get_bis_indexes(const esp_ble_audio_bap_base_t *base, uint32_t *bis_indexes)

Get all BIS indexes of a BASE.

Parameters:

• base -- The BASE pointer.

• bis_indexes -- 32-bit BIS index bitfield that will be populated.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_base_foreach_subgroup(const esp_ble_audio_bap_base_t *base, bool (*func)(const esp_ble_audio_bap_base_subgroup_t *subgroup, void *user_data), void *user_data)

Iterate on all subgroups in the BASE.

Parameters:

• base -- The BASE pointer.

• func -- Callback function. Return true to continue iterating, or false to stop.

• user_data -- User data supplied to func.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_base_get_subgroup_codec_id(const esp_ble_audio_bap_base_subgroup_t *subgroup, esp_ble_audio_bap_base_codec_id_t *codec_id)

Get the codec ID of a subgroup.

Parameters:

• subgroup -- The subgroup pointer.

• codec_id -- Pointer to the struct where the results are placed.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_base_get_subgroup_codec_data(const esp_ble_audio_bap_base_subgroup_t *subgroup, uint8_t **data)

Get the codec configuration data of a subgroup.

Parameters:

• subgroup -- The subgroup pointer.

• data -- Pointer that will point to the resulting codec configuration data.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_base_get_subgroup_codec_meta(const esp_ble_audio_bap_base_subgroup_t *subgroup, uint8_t **meta)

Get the codec metadata of a subgroup.

Parameters:

• subgroup -- The subgroup pointer.

• meta -- Pointer that will point to the resulting codec metadata.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_base_subgroup_codec_to_codec_cfg(const esp_ble_audio_bap_base_subgroup_t *subgroup, esp_ble_audio_codec_cfg_t *codec_cfg)

Store subgroup codec data in a esp_ble_audio_codec_cfg_t.

Parameters:

• subgroup -- The subgroup pointer.

• codec_cfg -- Pointer to the struct where the results are placed.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_base_get_subgroup_bis_count(const esp_ble_audio_bap_base_subgroup_t *subgroup, uint8_t *bis_count)

Get the BIS count of a subgroup.

Parameters:

• subgroup -- The subgroup pointer.

• bis_count -- The 8-bit BIS count value on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_base_subgroup_get_bis_indexes(const esp_ble_audio_bap_base_subgroup_t *subgroup, uint32_t *bis_indexes)

Get all BIS indexes of a subgroup.

Parameters:

• subgroup -- The subgroup pointer.

• bis_indexes -- 32-bit BIS index bitfield that will be populated.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_base_subgroup_foreach_bis(const esp_ble_audio_bap_base_subgroup_t *subgroup, bool (*func)(const esp_ble_audio_bap_base_subgroup_bis_t *bis, void *user_data), void *user_data)

Iterate on all BIS in the subgroup.

Parameters:

• subgroup -- The subgroup pointer.

• func -- Callback function. Return true to continue iterating, or false to stop.

• user_data -- User data supplied to func.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_bap_base_subgroup_bis_codec_to_codec_cfg(const esp_ble_audio_bap_base_subgroup_bis_t *bis, esp_ble_audio_codec_cfg_t *codec_cfg)

Store BIS codec configuration data in a esp_ble_audio_codec_cfg_t.

This only sets the esp_ble_audio_codec_cfg_t data and esp_ble_audio_codec_cfg_t data_len, but is useful to use the BIS codec configuration data with the esp_ble_audio_codec_cfg_* functions.

Parameters:

• bis -- The BIS pointer.

• codec_cfg -- Pointer to the struct where the results are placed.

Returns:

ESP_OK on success, or an error code on failure.

Macros

ESP_BLE_AUDIO_BAP_BASS_VALID_BIT_BITFIELD(_bis_bitfield)

Check if a BAP BASS BIS_Sync bitfield is valid.

Valid options are either a bitmask of valid BIS indices, including none (0x00000000) or no ref (0xFFFFFFFF).

Parameters:

• _bis_bitfield -- BIS_Sync bitfield (uint32).

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

Helper to declare elements of BAP QoS Configuration.

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).

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

Helper to declare Input Unframed BAP QoS Configuration.

Parameters:

• _interval -- SDU interval (usec).

• _sdu -- Maximum SDU Size.

• _rtn -- Retransmission number.

• _latency -- Maximum Transport Latency (msec).

• _pd -- Presentation Delay (usec).

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

Helper to declare Input Framed BAP QoS Configuration.

Parameters:

• _interval -- SDU interval (usec).

• _sdu -- Maximum SDU Size.

• _rtn -- Retransmission number.

• _latency -- Maximum Transport Latency (msec).

• _pd -- Presentation Delay (usec).

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

Helper to declare elements of BAP QoS Configuration Preference.

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).

ESP_BLE_AUDIO_BAP_ASCS_RSP(c, r)

Macro used to initialise the object storing values of ASE Control Point notification.

Parameters:

• c -- Response Code field.

• r -- Reason field. LE 1M PHY

ESP_BLE_AUDIO_BAP_QOS_CFG_1M

LE 2M PHY

ESP_BLE_AUDIO_BAP_QOS_CFG_2M

LE Coded PHY

ESP_BLE_AUDIO_BAP_QOS_CFG_CODED

An invalid Broadcast ID

ESP_BLE_AUDIO_BAP_INVALID_BROADCAST_ID

Value indicating that the periodic advertising interval is unknown

ESP_BLE_AUDIO_BAP_PA_INTERVAL_UNKNOWN

Indicate that the Broadcast Assistant has no preference to which BIS the Scan Delegator syncs to

ESP_BLE_AUDIO_BAP_BIS_SYNC_NO_PREF

BIS sync value indicating that the BIG sync has failed for any reason

ESP_BLE_AUDIO_BAP_BIS_SYNC_FAILED

Packets may be framed or unframed

ESP_BLE_AUDIO_BAP_QOS_CFG_FRAMING_UNFRAMED

Packets are always framed

ESP_BLE_AUDIO_BAP_QOS_CFG_FRAMING_FRAMED

ESP_BLE_AUDIO_BAP_PA_STATE_NOT_SYNCED

Waiting for SyncInfo from Broadcast Assistant

ESP_BLE_AUDIO_BAP_PA_STATE_INFO_REQ

Synchronized to periodic advertising

ESP_BLE_AUDIO_BAP_PA_STATE_SYNCED

Failed to synchronized to periodic advertising

ESP_BLE_AUDIO_BAP_PA_STATE_FAILED

No periodic advertising sync transfer receiver from Broadcast Assistant

ESP_BLE_AUDIO_BAP_PA_STATE_NO_PAST

ESP_BLE_AUDIO_BAP_BIG_ENC_STATE_NO_ENC

The Broadcast Isochronous Group broadcast code requested

ESP_BLE_AUDIO_BAP_BIG_ENC_STATE_BCODE_REQ

The Broadcast Isochronous Group decrypted

ESP_BLE_AUDIO_BAP_BIG_ENC_STATE_DEC

The Broadcast Isochronous Group bad broadcast code

ESP_BLE_AUDIO_BAP_BIG_ENC_STATE_BAD_CODE

ESP_BLE_AUDIO_BAP_EP_STATE_IDLE

Audio Stream Endpoint Codec Configured state

ESP_BLE_AUDIO_BAP_EP_STATE_CODEC_CONFIGURED

Audio Stream Endpoint QoS Configured state

ESP_BLE_AUDIO_BAP_EP_STATE_QOS_CONFIGURED

Audio Stream Endpoint Enabling state

ESP_BLE_AUDIO_BAP_EP_STATE_ENABLING

Audio Stream Endpoint Streaming state

ESP_BLE_AUDIO_BAP_EP_STATE_STREAMING

Audio Stream Endpoint Disabling state

ESP_BLE_AUDIO_BAP_EP_STATE_DISABLING

Audio Stream Endpoint Releasing state

ESP_BLE_AUDIO_BAP_EP_STATE_RELEASING

ESP_BLE_AUDIO_BAP_ASCS_REASON_NONE

Codec ID

ESP_BLE_AUDIO_BAP_ASCS_REASON_CODEC

Codec configuration

ESP_BLE_AUDIO_BAP_ASCS_REASON_CODEC_DATA

SDU interval

ESP_BLE_AUDIO_BAP_ASCS_REASON_INTERVAL

Framing

ESP_BLE_AUDIO_BAP_ASCS_REASON_FRAMING

PHY

ESP_BLE_AUDIO_BAP_ASCS_REASON_PHY

Maximum SDU size

ESP_BLE_AUDIO_BAP_ASCS_REASON_SDU

RTN

ESP_BLE_AUDIO_BAP_ASCS_REASON_RTN

Max transport latency

ESP_BLE_AUDIO_BAP_ASCS_REASON_LATENCY

Presentation delay

ESP_BLE_AUDIO_BAP_ASCS_REASON_PD

Invalid CIS mapping

ESP_BLE_AUDIO_BAP_ASCS_REASON_CIS

ESP_BLE_AUDIO_BAP_ASCS_RSP_CODE_SUCCESS

Server did not support operation by client

ESP_BLE_AUDIO_BAP_ASCS_RSP_CODE_NOT_SUPPORTED

Server rejected due to invalid operation length

ESP_BLE_AUDIO_BAP_ASCS_RSP_CODE_INVALID_LENGTH

Invalid ASE ID

ESP_BLE_AUDIO_BAP_ASCS_RSP_CODE_INVALID_ASE

Invalid ASE state

ESP_BLE_AUDIO_BAP_ASCS_RSP_CODE_INVALID_ASE_STATE

Invalid operation for direction

ESP_BLE_AUDIO_BAP_ASCS_RSP_CODE_INVALID_DIR

Capabilities not supported by server

ESP_BLE_AUDIO_BAP_ASCS_RSP_CODE_CAP_UNSUPPORTED

Configuration parameters not supported by server

ESP_BLE_AUDIO_BAP_ASCS_RSP_CODE_CONF_UNSUPPORTED

Configuration parameters rejected by server

ESP_BLE_AUDIO_BAP_ASCS_RSP_CODE_CONF_REJECTED

Invalid Configuration parameters

ESP_BLE_AUDIO_BAP_ASCS_RSP_CODE_CONF_INVALID

Unsupported metadata

ESP_BLE_AUDIO_BAP_ASCS_RSP_CODE_METADATA_UNSUPPORTED

Metadata rejected by server

ESP_BLE_AUDIO_BAP_ASCS_RSP_CODE_METADATA_REJECTED

Invalid metadata

ESP_BLE_AUDIO_BAP_ASCS_RSP_CODE_METADATA_INVALID

Server has insufficient resources

ESP_BLE_AUDIO_BAP_ASCS_RSP_CODE_NO_MEM

Unspecified error

ESP_BLE_AUDIO_BAP_ASCS_RSP_CODE_UNSPECIFIED

Type Definitions

typedef enum bt_bap_qos_cfg_framing esp_ble_audio_bap_qos_cfg_framing_t

QoS Framing The periodic advertising has not been synchronized

typedef enum bt_bap_pa_state esp_ble_audio_bap_pa_state_t

Periodic advertising state reported by the Scan Delegator The Broadcast Isochronous Group not encrypted

typedef enum bt_bap_big_enc_state esp_ble_audio_bap_big_enc_state_t

Broadcast Isochronous Group encryption state reported by the Scan Delegator Audio Stream Endpoint Idle state

typedef enum bt_bap_ep_state esp_ble_audio_bap_ep_state_t

Endpoint states No reason

typedef enum bt_bap_ascs_reason esp_ble_audio_bap_ascs_reason_t

Response Reasons Server completed operation successfully

typedef enum bt_bap_ascs_rsp_code esp_ble_audio_bap_ascs_rsp_code_t

Response Status Code

typedef struct bt_bap_base esp_ble_audio_bap_base_t

Broadcast Audio Source Endpoint (BASE) structure

typedef struct bt_bap_base_subgroup esp_ble_audio_bap_base_subgroup_t

Broadcast Audio Source Endpoint (BASE) subgroup structure

typedef struct bt_bap_base_codec_id esp_ble_audio_bap_base_codec_id_t

Codec ID structure for a Broadcast Audio Source Endpoint (BASE)

typedef struct bt_bap_base_subgroup_bis esp_ble_audio_bap_base_subgroup_bis_t

BIS structure for each BIS in a Broadcast Audio Source Endpoint (BASE) subgroup

typedef struct bt_bap_qos_cfg esp_ble_audio_bap_qos_cfg_t

QoS configuration structure

typedef struct bt_bap_qos_cfg_pref esp_ble_audio_bap_qos_cfg_pref_t

Audio Stream Quality of Service Preference structure

typedef struct bt_bap_ep esp_ble_audio_bap_ep_t

Audio Endpoint structure

typedef struct bt_bap_ep_info esp_ble_audio_bap_ep_info_t

Structure holding information of audio stream endpoint

typedef struct bt_bap_stream esp_ble_audio_bap_stream_t

Basic Audio Profile stream structure

typedef struct bt_bap_stream_ops esp_ble_audio_bap_stream_ops_t

Stream operation

typedef struct bt_bap_ascs_rsp esp_ble_audio_bap_ascs_rsp_t

Structure storing values of fields of ASE Control Point notification

typedef struct bt_bap_bass_subgroup esp_ble_audio_bap_bass_subgroup_t

Struct to hold subgroup specific information for the receive state

typedef struct bt_bap_unicast_group esp_ble_audio_bap_unicast_group_t

Audio Unicast Group structure

typedef struct bt_bap_unicast_group_stream_param esp_ble_audio_bap_unicast_group_stream_param_t

Parameter struct for each stream in the unicast group

typedef struct bt_bap_unicast_group_stream_pair_param esp_ble_audio_bap_unicast_group_stream_pair_param_t

Parameter struct for the unicast group functions

typedef struct bt_bap_unicast_group_param esp_ble_audio_bap_unicast_group_param_t

Parameters for creating unicast groups

typedef struct bt_bap_unicast_server_register_param esp_ble_audio_bap_unicast_server_register_param_t

Structure for registering Unicast Server

typedef struct bt_bap_unicast_server_cb esp_ble_audio_bap_unicast_server_cb_t

Unicast Server callback structure

typedef struct bt_bap_unicast_client_cb esp_ble_audio_bap_unicast_client_cb_t

Unicast Client callback structure

typedef esp_ble_iso_ext_adv_info_t esp_ble_audio_bap_broadcast_adv_info_t

Broadcast Source advertising information

typedef struct bt_bap_broadcast_source_cb esp_ble_audio_bap_broadcast_source_cb_t

Broadcast Source callback structure

typedef struct bt_bap_broadcast_source esp_ble_audio_bap_broadcast_source_t

Broadcast Source structure

typedef struct bt_bap_broadcast_source_stream_param esp_ble_audio_bap_broadcast_source_stream_param_t

Broadcast Source stream parameters

typedef struct bt_bap_broadcast_source_subgroup_param esp_ble_audio_bap_broadcast_source_subgroup_param_t

Broadcast Source subgroup parameters

typedef struct bt_bap_broadcast_source_param esp_ble_audio_bap_broadcast_source_param_t

Broadcast Source create parameters

typedef struct bt_bap_broadcast_sink esp_ble_audio_bap_broadcast_sink_t

Broadcast Sink handle

typedef struct bt_bap_broadcast_sink_cb esp_ble_audio_bap_broadcast_sink_cb_t

Broadcast Audio Sink callback structure

typedef struct bt_bap_broadcast_assistant_cb esp_ble_audio_bap_broadcast_assistant_cb_t

Struct to hold the Basic Audio Profile Broadcast Assistant callbacks

typedef struct bt_bap_broadcast_assistant_add_src_param esp_ble_audio_bap_broadcast_assistant_add_src_param_t

Parameters for adding a source to a Broadcast Audio Scan Service server

typedef struct bt_bap_broadcast_assistant_mod_src_param esp_ble_audio_bap_broadcast_assistant_mod_src_param_t

Parameters for modifying a source

typedef struct bt_bap_scan_delegator_cb esp_ble_audio_bap_scan_delegator_cb_t

Struct to hold the Basic Audio Profile Scan Delegator callbacks

typedef struct bt_bap_scan_delegator_recv_state esp_ble_audio_bap_scan_delegator_recv_state_t

Represents the Broadcast Audio Scan Service receive state

typedef struct bt_bap_scan_delegator_add_src_param esp_ble_audio_bap_scan_delegator_add_src_param_t

Parameters for adding a source by Scan Delegator

typedef struct bt_bap_scan_delegator_mod_src_param esp_ble_audio_bap_scan_delegator_mod_src_param_t

Parameters for modifying a source by Scan Delegator

Published Audio Capabilities (PACS)

Header File

• components/bt/esp_ble_audio/api/include/esp_ble_audio_pacs_api.h

• This header file can be included with:

  #include "esp_ble_audio_pacs_api.h"
  

• This header file is a part of the API provided by the bt component. To declare that your component depends on bt, add the following to your CMakeLists.txt:

  REQUIRES bt
  

  or

  PRIV_REQUIRES bt
  

Functions

esp_err_t esp_ble_audio_pacs_register(const esp_ble_audio_pacs_register_param_t *param)

Register the Published Audio Capability Service instance.

Parameters:

param -- PACS register parameters.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_pacs_unregister(void)

Unregister the Published Audio Capability Service instance.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_pacs_cap_register(esp_ble_audio_dir_t dir, esp_ble_audio_pacs_cap_t *cap)

Register Published Audio Capability.

Register Audio Local Capability.

Parameters:

• dir -- Direction of the endpoint to register capability for.

• cap -- Capability structure.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_pacs_cap_unregister(esp_ble_audio_dir_t dir, esp_ble_audio_pacs_cap_t *cap)

Unregister Published Audio Capability.

Unregister Audio Local Capability.

Parameters:

• dir -- Direction of the endpoint to unregister capability for.

• cap -- Capability structure.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_pacs_set_location(esp_ble_audio_dir_t dir, esp_ble_audio_location_t location)

Set the location for an endpoint type.

Parameters:

• dir -- Direction of the endpoints to change location for.

• location -- The location to be set.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_pacs_set_available_contexts(esp_ble_audio_dir_t dir, esp_ble_audio_context_t contexts)

Set the available contexts for an endpoint type.

Parameters:

• dir -- Direction of the endpoints to change available contexts for.

• contexts -- The contexts to be set.

Returns:

ESP_OK on success, or an error code on failure.

esp_ble_audio_context_t esp_ble_audio_pacs_get_available_contexts(esp_ble_audio_dir_t dir)

Get the available contexts for an endpoint type.

Parameters:

dir -- Direction of the endpoints to get contexts for.

Returns:

Bitmask of available contexts.

esp_err_t esp_ble_audio_pacs_conn_set_available_contexts_for_conn(uint16_t conn_handle, esp_ble_audio_dir_t dir, esp_ble_audio_context_t *contexts)

Set the available contexts for a given connection.

This function sets the available contexts value for a given connection. The Available Context Value is reset to default on ACL disconnection.

Parameters:

• conn_handle -- Connection handle.

• dir -- Direction of the endpoints to change available contexts for.

• contexts -- The contexts to be set or NULL to reset to default.

Returns:

ESP_OK on success, or an error code on failure.

esp_ble_audio_context_t esp_ble_audio_pacs_get_available_contexts_for_conn(uint16_t conn_handle, esp_ble_audio_dir_t dir)

Get the available contexts for a given connection.

This server function returns the available contexts value for a given connection.

Parameters:

• conn_handle -- Connection handle.

• dir -- Direction of the endpoints to get contexts for.

Returns:

Bitmask of available contexts.

esp_err_t esp_ble_audio_pacs_set_supported_contexts(esp_ble_audio_dir_t dir, esp_ble_audio_context_t contexts)

Set the supported contexts for an endpoint type.

Parameters:

• dir -- Direction of the endpoints to change available contexts for.

• contexts -- The contexts to be set.

Returns:

ESP_OK on success, or an error code on failure.

Type Definitions

typedef struct bt_pacs_register_param esp_ble_audio_pacs_register_param_t

Structure for registering PACS

typedef struct bt_pacs_cap esp_ble_audio_pacs_cap_t

Published Audio Capability structure.

Gaming Audio Profile (GMAP)

Header File

• components/bt/esp_ble_audio/api/include/esp_ble_audio_gmap_api.h

• This header file can be included with:

  #include "esp_ble_audio_gmap_api.h"
  

• This header file is a part of the API provided by the bt component. To declare that your component depends on bt, add the following to your CMakeLists.txt:

  REQUIRES bt
  

  or

  PRIV_REQUIRES bt
  

Functions

esp_err_t esp_ble_audio_gmap_cb_register(const esp_ble_audio_gmap_cb_t *cb)

Registers the callbacks used by the Gaming Audio Profile.

Parameters:

cb -- The callback structure.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_gmap_discover(uint16_t conn_handle)

Discover Gaming Service on a remote device.

Procedure to find a Gaming Service on a server identified by conn_handle.

Parameters:

conn_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_gmap_register(esp_ble_audio_gmap_role_t role, esp_ble_audio_gmap_feat_t features)

Adds GMAS instance to database and sets the received Gaming Audio Profile role(s).

Parameters:

• role -- Gaming Audio Profile role(s) of the device (one or multiple).

• features -- Features of the roles. If a role is not in the role parameter, then the feature value for that role is simply ignored.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_gmap_set_role(esp_ble_audio_gmap_role_t role, esp_ble_audio_gmap_feat_t features)

Set one or multiple Gaming Audio Profile roles and features dynamically.

Previously registered value will be overwritten. If there is a role change, this will trigger a Gaming Audio Service (GMAS) service change. If there is only a feature change, no service change will happen.

Parameters:

• role -- Gaming Audio Profile role(s).

• features -- Features of the roles. If a role is not in the role parameter, then the feature value for that role is simply ignored.

Returns:

ESP_OK on success, or an error code on failure.

Macros

ESP_BLE_AUDIO_GMAP_ROLE_UGG

< Gaming Role Unicast Game Gateway Gaming Role Unicast Game Terminal

ESP_BLE_AUDIO_GMAP_ROLE_UGT

Gaming Role Broadcast Game Sender

ESP_BLE_AUDIO_GMAP_ROLE_BGS

Gaming Role Broadcast Game Receiver

ESP_BLE_AUDIO_GMAP_ROLE_BGR

ESP_BLE_AUDIO_GMAP_UGG_FEAT_MULTIPLEX

96 kbps source support

ESP_BLE_AUDIO_GMAP_UGG_FEAT_96KBPS_SOURCE

Support for receiving at least two channels of audio, each in a separate CIS

ESP_BLE_AUDIO_GMAP_UGG_FEAT_MULTISINK

ESP_BLE_AUDIO_GMAP_UGT_FEAT_SOURCE

80 kbps source support

ESP_BLE_AUDIO_GMAP_UGT_FEAT_80KBPS_SOURCE

Sink support

ESP_BLE_AUDIO_GMAP_UGT_FEAT_SINK

64 kbps sink support

ESP_BLE_AUDIO_GMAP_UGT_FEAT_64KBPS_SINK

Support for receiving multiple LC3 codec frames per block in an SDU

ESP_BLE_AUDIO_GMAP_UGT_FEAT_MULTIPLEX

Support for receiving at least two audio channels, each in a separate CIS

ESP_BLE_AUDIO_GMAP_UGT_FEAT_MULTISINK

Support for sending at least two audio channels, each in a separate CIS

ESP_BLE_AUDIO_GMAP_UGT_FEAT_MULTISOURCE

ESP_BLE_AUDIO_GMAP_BGS_FEAT_96KBPS

ESP_BLE_AUDIO_GMAP_BGR_FEAT_MULTISINK

Support for receiving multiple LC3 codec frames per block in an SDU

ESP_BLE_AUDIO_GMAP_BGR_FEAT_MULTIPLEX

Type Definitions

typedef enum bt_gmap_role esp_ble_audio_gmap_role_t

Gaming Role bitfield Support transmitting multiple LC3 codec frames per block in an SDU

typedef enum bt_gmap_ugg_feat esp_ble_audio_gmap_ugg_feat_t

Unicast Game Gateway Feature bitfield Source support

typedef enum bt_gmap_ugt_feat esp_ble_audio_gmap_ugt_feat_t

Unicast Game Terminal Feature bitfield 96 kbps support

typedef enum bt_gmap_bgs_feat esp_ble_audio_gmap_bgs_feat_t

Broadcast Game Receiver Feature bitfield Support for receiving at least two audio channels, each in a separate BIS

typedef enum bt_gmap_bgr_feat esp_ble_audio_gmap_bgr_feat_t

Broadcast Game Receiver Feature bitfield

typedef struct bt_gmap_cb esp_ble_audio_gmap_cb_t

Hearing Access Service Client callback structure

typedef struct bt_gmap_feat esp_ble_audio_gmap_feat_t

Broadcast Game Receiver Feature bitfield

Volume Control Profile (VCP)

Header File

• components/bt/esp_ble_audio/api/include/esp_ble_audio_vcp_api.h

• This header file can be included with:

  #include "esp_ble_audio_vcp_api.h"
  

• This header file is a part of the API provided by the bt component. To declare that your component depends on bt, add the following to your CMakeLists.txt:

  REQUIRES bt
  

  or

  PRIV_REQUIRES bt
  

Functions

esp_err_t esp_ble_audio_vcp_vol_rend_included_get(esp_ble_audio_vcp_included_t *included)

Get Volume Control Service included services.

Returns a pointer to a struct that contains information about the Volume Control Service included service instances, such as pointers to the Volume Offset Control Service (Volume Offset Control Service) or Audio Input Control Service (AICS) instances.

Parameters:

included -- Pointer to store the result in.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_vcp_vol_rend_register(esp_ble_audio_vcp_vol_rend_register_param_t *param)

Register the Volume Control Service.

This will register and enable the service and make it discoverable by clients.

Parameters:

param -- Volume Control Service register parameters.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_vcp_vol_rend_set_step(uint8_t volume_step)

Set the Volume Control Service volume step size.

This can only be done as the server.

Parameters:

volume_step -- The volume step size (1-255).

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_vcp_vol_rend_get_state(void)

Get the Volume Control Service volume state.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_vcp_vol_rend_get_flags(void)

Get the Volume Control Service flags.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_vcp_vol_rend_vol_down(void)

Turn the volume down by one step on the server.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_vcp_vol_rend_vol_up(void)

Turn the volume up by one step on the server.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_vcp_vol_rend_unmute_vol_down(void)

Turn the volume down and unmute the server.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_vcp_vol_rend_unmute_vol_up(void)

Turn the volume up and unmute the server.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_vcp_vol_rend_set_vol(uint8_t volume)

Set the volume on the server.

Parameters:

volume -- The absolute volume to set.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_vcp_vol_rend_unmute(void)

Unmute the server.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_vcp_vol_rend_mute(void)

Mute the server.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_vcp_vol_ctlr_cb_register(esp_ble_audio_vcp_vol_ctlr_cb_t *cb)

Registers the callbacks used by the Volume Controller.

Parameters:

cb -- The callback structure.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_vcp_vol_ctlr_cb_unregister(esp_ble_audio_vcp_vol_ctlr_cb_t *cb)

Unregisters the callbacks used by the Volume Controller.

Parameters:

cb -- The callback structure.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_vcp_vol_ctlr_discover(uint16_t conn_handle, esp_ble_audio_vcp_vol_ctlr_t **vol_ctlr)

Discover Volume Control Service and included services.

This will start a GATT discovery and setup handles and subscriptions. This shall be called once before any other actions can be executed for the peer device.

This shall only be done as the client,

Parameters:

• conn_handle -- Connection handle.

• vol_ctlr -- Valid remote instance object on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_ble_audio_vcp_vol_ctlr_t *esp_ble_audio_vcp_vol_ctlr_get_by_conn(uint16_t conn_handle)

Get the volume controller from a connection pointer.

Get the Volume Control Profile Volume Controller pointer from a connection. Only volume controllers that have been initiated can be retrieved.

Parameters:

conn_handle -- Connection handle.

Returns:

Pointer to a Volume Control Profile Volume Controller instance. NULL if the connection has not been found has not done discovery yet.

esp_err_t esp_ble_audio_vcp_vol_ctlr_included_get(esp_ble_audio_vcp_vol_ctlr_t *vol_ctlr, esp_ble_audio_vcp_included_t *included)

Get Volume Control Service included services.

Returns a pointer to a struct that contains information about the Volume Control Service included service instances, such as pointers to the Volume Offset Control Service (Volume Offset Control Service) or Audio Input Control Service (AICS) instances.

Parameters:

• vol_ctlr -- Volume Controller instance pointer.

• included -- Pointer to store the result in.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_vcp_vol_ctlr_read_state(esp_ble_audio_vcp_vol_ctlr_t *vol_ctlr)

Read the volume state of a remote Volume Renderer.

Parameters:

vol_ctlr -- Volume Controller instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_vcp_vol_ctlr_read_flags(esp_ble_audio_vcp_vol_ctlr_t *vol_ctlr)

Read the volume flags of a remote Volume Renderer.

Parameters:

vol_ctlr -- Volume Controller instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_vcp_vol_ctlr_vol_down(esp_ble_audio_vcp_vol_ctlr_t *vol_ctlr)

Turn the volume down one step on a remote Volume Renderer.

Parameters:

vol_ctlr -- Volume Controller instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_vcp_vol_ctlr_vol_up(esp_ble_audio_vcp_vol_ctlr_t *vol_ctlr)

Turn the volume up one step on a remote Volume Renderer.

Parameters:

vol_ctlr -- Volume Controller instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_vcp_vol_ctlr_unmute_vol_down(esp_ble_audio_vcp_vol_ctlr_t *vol_ctlr)

Turn the volume down one step and unmute on a remote Volume Renderer.

Parameters:

vol_ctlr -- Volume Controller instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_vcp_vol_ctlr_unmute_vol_up(esp_ble_audio_vcp_vol_ctlr_t *vol_ctlr)

Turn the volume up one step and unmute on a remote Volume Renderer.

Parameters:

vol_ctlr -- Volume Controller instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_vcp_vol_ctlr_set_vol(esp_ble_audio_vcp_vol_ctlr_t *vol_ctlr, uint8_t volume)

Set the absolute volume on a remote Volume Renderer.

Parameters:

• vol_ctlr -- Volume Controller instance pointer.

• volume -- The absolute volume to set.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_vcp_vol_ctlr_unmute(esp_ble_audio_vcp_vol_ctlr_t *vol_ctlr)

Unmute a remote Volume Renderer.

Parameters:

vol_ctlr -- Volume Controller instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_vcp_vol_ctlr_mute(esp_ble_audio_vcp_vol_ctlr_t *vol_ctlr)

Mute a remote Volume Renderer.

Parameters:

vol_ctlr -- Volume Controller instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

Macros

ESP_BLE_AUDIO_VCP_STATE_UNMUTED

< The volume state is unmuted The volume state is muted

ESP_BLE_AUDIO_VCP_STATE_MUTED

Type Definitions

typedef struct bt_vcp_included esp_ble_audio_vcp_included_t

Volume Control Service included services

typedef struct bt_vcp_vol_ctlr esp_ble_audio_vcp_vol_ctlr_t

Volume Control Service instance

typedef struct bt_vcp_vol_ctlr_cb esp_ble_audio_vcp_vol_ctlr_cb_t

Struct to hold the Volume Controller callbacks

typedef struct bt_vcp_vol_rend_cb esp_ble_audio_vcp_vol_rend_cb_t

Struct to hold the Volume Renderer callbacks

typedef struct bt_vcp_vol_rend_register_param esp_ble_audio_vcp_vol_rend_register_param_t

Register structure for Volume Control Service

Volume Offset Control Service (VOCS)

Header File

• components/bt/esp_ble_audio/api/include/esp_ble_audio_vocs_api.h

• This header file can be included with:

  #include "esp_ble_audio_vocs_api.h"
  

• This header file is a part of the API provided by the bt component. To declare that your component depends on bt, add the following to your CMakeLists.txt:

  REQUIRES bt
  

  or

  PRIV_REQUIRES bt
  

Functions

esp_ble_audio_vocs_t *esp_ble_audio_vocs_free_instance_get(void)

Get a free service instance of Volume Offset Control Service from the pool.

Returns:

Volume Offset Control Service instance in case of success or NULL in case of error.

void *esp_ble_audio_vocs_svc_decl_get(esp_ble_audio_vocs_t *vocs)

Get the service declaration attribute.

The first service attribute returned can be included in any other GATT service.

Parameters:

vocs -- Volume Offset Control Service instance.

Returns:

Pointer to the attributes of the service.

esp_err_t esp_ble_audio_vocs_register(esp_ble_audio_vocs_t *vocs, const esp_ble_audio_vocs_register_param_t *param)

Register the Volume Offset Control Service instance.

Parameters:

• vocs -- Volume Offset Control Service instance.

• param -- Volume Offset Control Service register parameters.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_vocs_state_get(esp_ble_audio_vocs_t *inst)

Read the Volume Offset Control Service offset state.

Parameters:

inst -- Pointer to the Volume Offset Control Service instance.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_vocs_state_set(esp_ble_audio_vocs_t *inst, int16_t offset)

Set the Volume Offset Control Service offset state.

Parameters:

• inst -- Pointer to the Volume Offset Control Service instance.

• offset -- The offset to set (-255 to 255).

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_vocs_location_get(esp_ble_audio_vocs_t *inst)

Read the Volume Offset Control Service location.

Parameters:

inst -- Pointer to the Volume Offset Control Service instance.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_vocs_location_set(esp_ble_audio_vocs_t *inst, uint32_t location)

Set the Volume Offset Control Service location.

Parameters:

• inst -- Pointer to the Volume Offset Control Service instance.

• location -- The location to set.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_vocs_description_get(esp_ble_audio_vocs_t *inst)

Read the Volume Offset Control Service output description.

Parameters:

inst -- Pointer to the Volume Offset Control Service instance.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_vocs_description_set(esp_ble_audio_vocs_t *inst, const char *description)

Set the Volume Offset Control Service description.

Parameters:

• inst -- Pointer to the Volume Offset Control Service instance.

• description -- The UTF-8 encoded string description to set.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_vocs_client_cb_register(esp_ble_audio_vocs_t *inst, esp_ble_audio_vocs_cb_t *cb)

Registers the callbacks for the Volume Offset Control Service client.

Parameters:

• inst -- Pointer to the Volume Offset Control Service client instance.

• cb -- Pointer to the callback structure.

Returns:

ESP_OK on success, or an error code on failure.

esp_ble_audio_vocs_t *esp_ble_audio_vocs_client_free_instance_get(void)

Returns a pointer to a Volume Offset Control Service client instance.

Returns:

Pointer to the instance, or NULL if no free instances are left.

esp_err_t esp_ble_audio_vocs_discover(uint16_t conn_handle, esp_ble_audio_vocs_t *inst, const esp_ble_audio_vocs_discover_param_t *param)

Discover a Volume Offset Control Service.

Attempts to discover a Volume Offset Control Service on a server given the param.

Parameters:

• conn_handle -- Connection handle.

• inst -- Pointer to the Volume Offset Control Service client instance.

• param -- Pointer to the parameters.

Returns:

ESP_OK on success, or an error code on failure.

Macros

ESP_BLE_AUDIO_VOCS_MIN_OFFSET

< Minimum offset value Maximum offset value

ESP_BLE_AUDIO_VOCS_MAX_OFFSET

Type Definitions

typedef struct bt_vocs esp_ble_audio_vocs_t

Volume Offset Control Service instance

typedef struct bt_vocs_cb esp_ble_audio_vocs_cb_t

Struct to hold the Volume Offset Control Service callbacks

typedef struct bt_vocs_register_param esp_ble_audio_vocs_register_param_t

Structure for registering a Volume Offset Control Service instance

typedef struct bt_vocs_discover_param esp_ble_audio_vocs_discover_param_t

Structure for discovering a Volume Offset Control Service instance

Audio Input Control Service (AICS)

Header File

• components/bt/esp_ble_audio/api/include/esp_ble_audio_aics_api.h

• This header file can be included with:

  #include "esp_ble_audio_aics_api.h"
  

• This header file is a part of the API provided by the bt component. To declare that your component depends on bt, add the following to your CMakeLists.txt:

  REQUIRES bt
  

  or

  PRIV_REQUIRES bt
  

Functions

esp_ble_audio_aics_t *esp_ble_audio_aics_free_instance_get(void)

Get a free instance of Audio Input Control Service from the pool.

Returns:

Audio Input Control Service instance in case of success or NULL in case of error.

void *esp_ble_audio_aics_svc_decl_get(esp_ble_audio_aics_t *aics)

Get the service declaration attribute.

The first service attribute returned can be included in any other GATT service.

Parameters:

aics -- Audio Input Control Service instance.

Returns:

Pointer to the attributes of the service.

esp_err_t esp_ble_audio_aics_register(esp_ble_audio_aics_t *aics, esp_ble_audio_aics_register_param_t *param)

Initialize the Audio Input Control Service instance.

Parameters:

• aics -- Audio Input Control Service instance.

• param -- Audio Input Control Service register parameters.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_aics_activate(esp_ble_audio_aics_t *inst)

Activates an Audio Input Control Service instance.

Audio Input Control Services are activated by default, but this will allow the server reactivate an Audio Input Control Service instance after it has been deactivated.

Parameters:

inst -- The instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_aics_deactivate(esp_ble_audio_aics_t *inst)

Deactivates an Audio Input Control Service instance.

Audio Input Control Services are activated by default, but this will allow the server to deactivate an Audio Input Control Service.

Parameters:

inst -- The instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_aics_state_get(esp_ble_audio_aics_t *inst)

Read the Audio Input Control Service input state.

Parameters:

inst -- The instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_aics_gain_setting_get(esp_ble_audio_aics_t *inst)

Read the Audio Input Control Service gain settings.

Parameters:

inst -- The instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_aics_type_get(esp_ble_audio_aics_t *inst)

Read the Audio Input Control Service input type.

Parameters:

inst -- The instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_aics_status_get(esp_ble_audio_aics_t *inst)

Read the Audio Input Control Service input status.

Parameters:

inst -- The instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_aics_disable_mute(esp_ble_audio_aics_t *inst)

Disable mute in the Audio Input Control Service.

Parameters:

inst -- The instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_aics_unmute(esp_ble_audio_aics_t *inst)

Unmute the Audio Input Control Service input.

Parameters:

inst -- The instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_aics_mute(esp_ble_audio_aics_t *inst)

Mute the Audio Input Control Service input.

Parameters:

inst -- The instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_aics_gain_set_manual_only(esp_ble_audio_aics_t *inst)

Set manual only gain mode in Audio Input Control Service.

Parameters:

inst -- The instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_aics_gain_set_auto_only(esp_ble_audio_aics_t *inst)

Set automatic only gain mode in Audio Input Control Service.

Parameters:

inst -- The instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_aics_manual_gain_set(esp_ble_audio_aics_t *inst)

Set input gain to manual.

Parameters:

inst -- The instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_aics_automatic_gain_set(esp_ble_audio_aics_t *inst)

Set the input gain to automatic.

Parameters:

inst -- The instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_aics_gain_set(esp_ble_audio_aics_t *inst, int8_t gain)

Set the input gain.

Parameters:

• inst -- The instance pointer.

• gain -- The gain to set (-128 to 127) in gain setting units.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_aics_description_get(esp_ble_audio_aics_t *inst)

Read the Audio Input Control Service description.

Parameters:

inst -- The instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_aics_description_set(esp_ble_audio_aics_t *inst, const char *description)

Set the Audio Input Control Service description.

Parameters:

• inst -- The instance pointer.

• description -- The description as an UTF-8 encoded string.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_aics_discover(uint16_t conn_handle, esp_ble_audio_aics_t *inst, const esp_ble_audio_aics_discover_param_t *param)

Discover an Audio Input Control Service.

Attempts to discover an Audio Input Control Service on a server given the param.

Parameters:

• conn_handle -- Connection handle.

• inst -- The instance pointer.

• param -- Pointer to the parameters.

Returns:

ESP_OK on success, or an error code on failure.

esp_ble_audio_aics_t *esp_ble_audio_aics_client_free_instance_get(void)

Get a new Audio Input Control Service client instance.

Returns:

Pointer to the instance, or NULL if no free instances are left.

esp_err_t esp_ble_audio_aics_client_cb_register(esp_ble_audio_aics_t *inst, esp_ble_audio_aics_cb_t *cb)

Registers the callbacks for the Audio Input Control Service client.

Parameters:

• inst -- The instance pointer.

• cb -- Pointer to the callback structure.

Returns:

ESP_OK on success, or an error code on failure.

Macros

ESP_BLE_AUDIO_AICS_STATE_UNMUTED

< The mute state is unmuted The mute state is muted

ESP_BLE_AUDIO_AICS_STATE_MUTED

The mute state is disabled

ESP_BLE_AUDIO_AICS_STATE_MUTE_DISABLED

The gain mode is manual only and cannot be changed to automatic

ESP_BLE_AUDIO_AICS_MODE_MANUAL_ONLY

The gain mode is automatic only and cannot be changed to manual

ESP_BLE_AUDIO_AICS_MODE_AUTO_ONLY

The gain mode is manual

ESP_BLE_AUDIO_AICS_MODE_MANUAL

The gain mode is automatic

ESP_BLE_AUDIO_AICS_MODE_AUTO

The input is unspecified

ESP_BLE_AUDIO_AICS_INPUT_TYPE_UNSPECIFIED

The input is a Bluetooth Audio Stream

ESP_BLE_AUDIO_AICS_INPUT_TYPE_BLUETOOTH

The input is a microphone

ESP_BLE_AUDIO_AICS_INPUT_TYPE_MICROPHONE

The input is analog

ESP_BLE_AUDIO_AICS_INPUT_TYPE_ANALOG

The input is digital

ESP_BLE_AUDIO_AICS_INPUT_TYPE_DIGITAL

The input is a radio (AM/FM/XM/etc.)

ESP_BLE_AUDIO_AICS_INPUT_TYPE_RADIO

The input is a Streaming Audio Source

ESP_BLE_AUDIO_AICS_INPUT_TYPE_STREAMING

The input is transparent / pass-through

ESP_BLE_AUDIO_AICS_INPUT_TYPE_AMBIENT

Type Definitions

typedef struct bt_aics esp_ble_audio_aics_t

Audio Input Control Service instance.

typedef struct bt_aics_cb esp_ble_audio_aics_cb_t

Structure to hold callbacks for Audio Input Control Service.

typedef struct bt_aics_register_param esp_ble_audio_aics_register_param_t

Structure for initializing an Audio Input Control Service instance.

typedef struct bt_aics_discover_param esp_ble_audio_aics_discover_param_t

Structure for discovering an Audio Input Control Service instance.

Microphone Control Profile (MICP)

Header File

• components/bt/esp_ble_audio/api/include/esp_ble_audio_micp_api.h

• This header file can be included with:

  #include "esp_ble_audio_micp_api.h"
  

• This header file is a part of the API provided by the bt component. To declare that your component depends on bt, add the following to your CMakeLists.txt:

  REQUIRES bt
  

  or

  PRIV_REQUIRES bt
  

Functions

esp_err_t esp_ble_audio_micp_mic_dev_register(esp_ble_audio_micp_mic_dev_register_param_t *param)

Initialize the Microphone Control Profile Microphone Device.

This will enable the Microphone Control Service instance and make it discoverable by Microphone Controllers.

Parameters:

param -- Pointer to an initialization structure.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_micp_mic_dev_included_get(esp_ble_audio_micp_included_t *included)

Get Microphone Device included services.

Returns a pointer to a struct that contains information about the Microphone Device included Audio Input Control Service instances.

Parameters:

included -- Pointer to store the result in.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_micp_mic_dev_unmute(void)

Unmute the Microphone Device.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_micp_mic_dev_mute(void)

Mute the Microphone Device.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_micp_mic_dev_mute_disable(void)

Disable the mute functionality on the Microphone Device.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_micp_mic_dev_mute_get(void)

Read the mute state on the Microphone Device.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_micp_mic_ctlr_included_get(esp_ble_audio_micp_mic_ctlr_t *mic_ctlr, esp_ble_audio_micp_included_t *included)

Get Microphone Control Profile included services.

Returns a pointer to a struct that contains information about the Microphone Control Profile included services instances, such as pointers to the Audio Input Control Service instances.

Parameters:

• mic_ctlr -- Microphone Controller instance pointer.

• included -- Pointer to store the result in.

Returns:

ESP_OK on success, or an error code on failure.

esp_ble_audio_micp_mic_ctlr_t *esp_ble_audio_micp_mic_ctlr_get_by_conn(uint16_t conn_handle)

Get the Microphone controller from a connection pointer.

Only Microphone controllers that have been initiated can be retrieved.

Parameters:

conn_handle -- Connection handle.

Returns:

Pointer to a Microphone controller instance or NULL if not found.

esp_err_t esp_ble_audio_micp_mic_ctlr_discover(uint16_t conn_handle, esp_ble_audio_micp_mic_ctlr_t **mic_ctlr)

Discover Microphone Control Service.

This will start a GATT discovery and setup handles and subscriptions. This shall be called once before any other actions can be executed for the peer device.

Parameters:

• conn_handle -- Connection handle.

• mic_ctlr -- Valid remote instance object on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_micp_mic_ctlr_unmute(esp_ble_audio_micp_mic_ctlr_t *mic_ctlr)

Unmute a remote Microphone Device.

Parameters:

mic_ctlr -- Microphone Controller instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_micp_mic_ctlr_mute(esp_ble_audio_micp_mic_ctlr_t *mic_ctlr)

Mute a remote Microphone Device.

Parameters:

mic_ctlr -- Microphone Controller instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_micp_mic_ctlr_mute_get(esp_ble_audio_micp_mic_ctlr_t *mic_ctlr)

Read the mute state of a remote Microphone Device.

Parameters:

mic_ctlr -- Microphone Controller instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_micp_mic_ctlr_cb_register(esp_ble_audio_micp_mic_ctlr_cb_t *cb)

Registers the callbacks used by Microphone Controller.

This can only be done as the client.

Parameters:

cb -- The callback structure.

Returns:

ESP_OK on success, or an error code on failure.

Macros

ESP_BLE_AUDIO_MICP_MUTE_UNMUTED

< The microphone state is unmuted The microphone state is muted

ESP_BLE_AUDIO_MICP_MUTE_MUTED

The microphone state is disabled and cannot be muted or unmuted

ESP_BLE_AUDIO_MICP_MUTE_DISABLED

Type Definitions

typedef struct bt_micp_mic_ctlr esp_ble_audio_micp_mic_ctlr_t

Microphone Controller instance

typedef struct bt_micp_mic_ctlr_cb esp_ble_audio_micp_mic_ctlr_cb_t

Struct to hold the Microphone Controller callbacks

typedef struct bt_micp_mic_dev_cb esp_ble_audio_micp_mic_dev_cb_t

Struct to hold the Microphone Device callbacks

typedef struct bt_micp_mic_dev_register_param esp_ble_audio_micp_mic_dev_register_param_t

Register parameters structure for Microphone Control Service

typedef struct bt_micp_included esp_ble_audio_micp_included_t

Microphone Control Profile included services

Hearing Access Profile (HAP)

Header File

• components/bt/esp_ble_audio/api/include/esp_ble_audio_has_api.h

• This header file can be included with:

  #include "esp_ble_audio_has_api.h"
  

• This header file is a part of the API provided by the bt component. To declare that your component depends on bt, add the following to your CMakeLists.txt:

  REQUIRES bt
  

  or

  PRIV_REQUIRES bt
  

Functions

esp_err_t esp_ble_audio_has_client_cb_register(const esp_ble_audio_has_client_cb_t *cb)

Registers the callbacks used by the Hearing Access Service client.

Parameters:

cb -- The callback structure.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_has_client_discover(uint16_t conn_handle)

Discover Hearing Access Service on a remote device.

Client method to find a Hearing Access Service on a server identified by conn_handle.

Parameters:

conn_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_has_client_presets_read(esp_ble_audio_has_t *has, uint8_t index, uint8_t max_count)

Read Preset Records.

Client method to read up to max_count presets starting from given index.

Parameters:

• has -- Pointer to the Hearing Access Service object.

• index -- The index to start with.

• max_count -- Maximum number of presets to read.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_has_client_preset_set(esp_ble_audio_has_t *has, uint8_t index, bool sync)

Set Active Preset.

Client procedure to set preset identified by index as active.

Parameters:

• has -- Pointer to the Hearing Access Service object.

• index -- Preset index to activate.

• sync -- Request active preset synchronization in set.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_has_client_preset_next(esp_ble_audio_has_t *has, bool sync)

Activate Next Preset.

Client procedure to set next available preset as active.

Parameters:

• has -- Pointer to the Hearing Access Service object.

• sync -- Request active preset synchronization in set.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_has_client_preset_prev(esp_ble_audio_has_t *has, bool sync)

Activate Previous Preset.

Client procedure to set previous available preset as active.

Parameters:

• has -- Pointer to the Hearing Access Service object.

• sync -- Request active preset synchronization in set.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_has_register(const esp_ble_audio_has_features_param_t *features)

Register the Hearing Access Service instance.

Parameters:

features -- Hearing Access Service register parameters.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_has_preset_register(const esp_ble_audio_has_preset_register_param_t *param)

Register preset.

Register preset. The preset will be added to the list of exposed preset records.

Parameters:

param -- Preset registration parameter.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_has_preset_unregister(uint8_t index)

Unregister Preset.

Unregister preset. The preset will be removed from the list of preset records.

Parameters:

index -- The index of preset that's being requested to unregister.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_has_preset_available(uint8_t index)

Set the preset as available.

This will notify preset availability to peer devices. Only available preset can be selected as active preset.

Parameters:

index -- The index of preset that's became available.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_has_preset_unavailable(uint8_t index)

Set the preset as unavailable.

This will notify preset availability to peer devices. Unavailable preset cannot be selected as active preset.

Parameters:

index -- The index of preset that's became unavailable.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_has_preset_active_set(uint8_t index)

Set active preset.

Function used to set the preset identified by the index as the active preset. The preset index will be notified to peer devices.

Parameters:

index -- Preset index.

Returns:

ESP_OK on success, or an error code on failure.

uint8_t esp_ble_audio_has_preset_active_get(void)

Get active preset.

Function used to get the currently active preset index.

Returns:

Active preset index.

esp_err_t esp_ble_audio_has_preset_name_change(uint8_t index, const char *name)

Change the Preset Name.

Change the name of the preset identified by index.

Parameters:

• index -- The index of the preset to change the name of.

• name -- Name to write.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_has_features_set(const esp_ble_audio_has_features_param_t *features)

Change the Hearing Aid Features.

Change the hearing aid features.

Parameters:

features -- The features to be set.

Returns:

ESP_OK on success, or an error code on failure.

Macros

ESP_BLE_AUDIO_HAS_PRESET_INDEX_NONE

< No index First preset index

ESP_BLE_AUDIO_HAS_PRESET_INDEX_FIRST

Last preset index

ESP_BLE_AUDIO_HAS_PRESET_INDEX_LAST

Preset name minimum length

ESP_BLE_AUDIO_HAS_PRESET_NAME_MIN

Preset name maximum length

ESP_BLE_AUDIO_HAS_PRESET_NAME_MAX

No properties set

ESP_BLE_AUDIO_HAS_PROP_NONE

Preset name can be written by the client

ESP_BLE_AUDIO_HAS_PROP_WRITABLE

Preset availability

ESP_BLE_AUDIO_HAS_PROP_AVAILABLE

ESP_BLE_AUDIO_HAS_PRESET_SUPPORT

ESP_BLE_AUDIO_HAS_HEARING_AID_TYPE_BINAURAL

Two hearing aids that form a Coordinated Set, one for the right ear and one for the left ear of the user. Typically used by a user with bilateral hearing loss.

ESP_BLE_AUDIO_HAS_HEARING_AID_TYPE_MONAURAL

A single hearing aid for the left or the right ear. Typically used by a user with unilateral hearing loss.

ESP_BLE_AUDIO_HAS_HEARING_AID_TYPE_BANDED

Two hearing aids with a connection to one another that expose a single Bluetooth radio interface.

Type Definitions

typedef enum bt_has_properties esp_ble_audio_has_properties_t

Preset Properties values Indicate support for presets

typedef enum bt_has_capabilities esp_ble_audio_has_capabilities_t

Hearing Aid device capabilities

typedef enum bt_has_hearing_aid_type esp_ble_audio_has_hearing_aid_type_t

Hearing Aid device type

typedef struct bt_has esp_ble_audio_has_t

Hearing Access Service object

typedef struct bt_has_client_cb esp_ble_audio_has_client_cb_t

Hearing Access Service Client callback structure

typedef struct bt_has_features_param esp_ble_audio_has_features_param_t

Structure for registering features of a Hearing Access Service instance

typedef struct bt_has_preset_ops esp_ble_audio_has_preset_ops_t

Preset operations structure

typedef struct bt_has_preset_record esp_ble_audio_has_preset_record_t

Preset record definition

typedef struct bt_has_preset_register_param esp_ble_audio_has_preset_register_param_t

Register structure for preset

Coordinated Set Identification Profile (CSIP)

Header File

• components/bt/esp_ble_audio/api/include/esp_ble_audio_csip_api.h

• This header file can be included with:

  #include "esp_ble_audio_csip_api.h"
  

• This header file is a part of the API provided by the bt component. To declare that your component depends on bt, add the following to your CMakeLists.txt:

  REQUIRES bt
  

  or

  PRIV_REQUIRES bt
  

Functions

void *esp_ble_audio_csip_set_member_svc_decl_get(const esp_ble_audio_csip_set_member_svc_inst_t *svc_inst)

Get the service declaration attribute.

The first service attribute can be included in any other GATT service.

Parameters:

svc_inst -- Pointer to the Coordinated Set Identification Service.

Returns:

The first CSIS attribute instance.

esp_err_t esp_ble_audio_csip_set_member_register(const esp_ble_audio_csip_set_member_register_param_t *param, esp_ble_audio_csip_set_member_svc_inst_t **svc_inst)

Register a Coordinated Set Identification Service instance.

This will register and enable the service and make it discoverable by clients.

This shall only be done as a server.

Parameters:

• param -- Coordinated Set Identification Service register parameters.

• svc_inst -- Pointer to the registered Coordinated Set Identification Service.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_csip_set_member_unregister(esp_ble_audio_csip_set_member_svc_inst_t *svc_inst)

Unregister a Coordinated Set Identification Service instance.

This will unregister and disable the service instance.

Parameters:

svc_inst -- Pointer to the registered Coordinated Set Identification Service.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_csip_set_member_sirk(esp_ble_audio_csip_set_member_svc_inst_t *svc_inst, const uint8_t sirk[ESP_BLE_AUDIO_CSIP_SIRK_SIZE])

Set the SIRK of a service instance.

Parameters:

• svc_inst -- Pointer to the registered Coordinated Set Identification Service.

• sirk -- The new SIRK.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_csip_set_member_set_size_and_rank(esp_ble_audio_csip_set_member_svc_inst_t *svc_inst, uint8_t size, uint8_t rank)

Set a new size and rank for a service instance.

This function can be used to dynamically change the size and rank of a service instance. It is important to note that a set cannot have multiple devices with the same rank in a set, and it is up to the caller of this function to ensure that. Similarly, it is important that the size is updated on all devices in the set at the same time.

If CONFIG_BT_CSIP_SET_MEMBER_SIZE_NOTIFIABLE is enabled, this will also send a notification to all connected or bonded clients.

Parameters:

• svc_inst -- The service instance.

• size -- The new set size.

• rank -- The new rank. Ignored if the svc_inst is not lockable.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_csip_set_member_get_info(const esp_ble_audio_csip_set_member_svc_inst_t *svc_inst, esp_ble_audio_csip_set_member_set_info_t *info)

Get information about a service instances.

Parameters:

• svc_inst -- The service instance.

• info -- Pointer to a struct to store the information in.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_csip_set_member_generate_rsi(const esp_ble_audio_csip_set_member_svc_inst_t *svc_inst, uint8_t rsi[ESP_BLE_AUDIO_CSIP_RSI_SIZE])

Generate the Resolvable Set Identifier (RSI) value.

This will generate RSI for given svc_inst instance.

Parameters:

• svc_inst -- Pointer to the Coordinated Set Identification Service.

• rsi -- Pointer to the 6-octet newly generated RSI data in little-endian.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_csip_set_member_lock(esp_ble_audio_csip_set_member_svc_inst_t *svc_inst, bool lock, bool force)

Locks a specific Coordinated Set Identification Service instance on the server.

Parameters:

• svc_inst -- Pointer to the Coordinated Set Identification Service.

• lock -- If true lock the set, if false release the set.

• force -- This argument only have meaning when lock is false (release) and will force release the lock, regardless of who took the lock.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_csip_set_coordinator_discover(uint16_t conn_handle)

Initialise the csip_set_coordinator instance for a connection. This will do a discovery on the device and prepare the instance for following commands.

Parameters:

conn_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

esp_ble_audio_csip_set_coordinator_set_member_t *esp_ble_audio_csip_set_coordinator_set_member_by_conn(uint16_t conn_handle)

Get the set member from a connection pointer.

Get the Coordinated Set Identification Profile Set Coordinator pointer from connection handle. Only Set Coordinators that have been initiated can be retrieved.

Parameters:

conn_handle -- Connection handle.

Returns:

Pointer to a Coordinated Set Identification Profile Set Coordinator instance. NULL if the connection has not been found or has not done discovery yet.

bool esp_ble_audio_csip_set_coordinator_is_set_member(const uint8_t sirk[ESP_BLE_AUDIO_CSIP_SIRK_SIZE], uint8_t data_type, const uint8_t *data, uint8_t data_len)

Check if advertising data indicates a set member.

Parameters:

• sirk -- The SIRK of the set to check against.

• data_type -- Type of the advertising data.

• data -- Pointer of the advertising data.

• data_len -- Length of the advertising data.

Returns:

True if the advertising data indicates a set member, false otherwise.

esp_err_t esp_ble_audio_csip_set_coordinator_register_cb(esp_ble_audio_csip_set_coordinator_cb_t *cb)

Registers callbacks for csip_set_coordinator.

Parameters:

cb -- Pointer to the callback structure.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_csip_set_coordinator_ordered_access(const esp_ble_audio_csip_set_coordinator_set_member_t *members[], uint8_t count, const esp_ble_audio_csip_set_coordinator_set_info_t *set_info, bt_csip_set_coordinator_ordered_access_t cb)

Access Coordinated Set devices in an ordered manner as a client.

This function will read the lock state of all devices and if all devices are in the unlocked state, then cb will be called with the same members as provided by members, but where the members are ordered by rank (if present).

This procedure only works if all the members have the lock characteristic, and all either has rank = 0 or unique ranks.

If any of the members are in the locked state, the procedure will be cancelled.

This can only be done on members that are bonded.

Parameters:

• members -- Array of set members to access.

• count -- Number of set members in members.

• set_info -- Pointer to the a specific set_info struct, as a member may be part of multiple sets.

• cb -- The callback function to be called for each member.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_csip_set_coordinator_lock(const esp_ble_audio_csip_set_coordinator_set_member_t **members, uint8_t count, const esp_ble_audio_csip_set_coordinator_set_info_t *set_info)

Lock an array of set members.

The members will be locked starting from lowest rank going up.

Parameters:

• members -- Array of set members to lock.

• count -- Number of set members in members.

• set_info -- Pointer to the a specific set_info struct, as a member may be part of multiple sets.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_csip_set_coordinator_release(const esp_ble_audio_csip_set_coordinator_set_member_t **members, uint8_t count, const esp_ble_audio_csip_set_coordinator_set_info_t *set_info)

Release an array of set members.

The members will be released starting from highest rank going down.

Parameters:

• members -- Array of set members to lock.

• count -- Number of set members in members.

• set_info -- Pointer to the a specific set_info struct, as a member may be part of multiple sets.

Returns:

ESP_OK on success, or an error code on failure.

Macros

ESP_BLE_AUDIO_CSIP_SIRK_SIZE

< Size of the Set Identification Resolving Key (SIRK) Size of the Resolvable Set Identifier (RSI)

ESP_BLE_AUDIO_CSIP_RSI_SIZE

Accept the request to read the SIRK as plaintext

ESP_BLE_AUDIO_CSIP_READ_SIRK_REQ_RSP_ACCEPT

Accept the request to read the SIRK, but return encrypted SIRK

ESP_BLE_AUDIO_CSIP_READ_SIRK_REQ_RSP_ACCEPT_ENC

Reject the request to read the SIRK

ESP_BLE_AUDIO_CSIP_READ_SIRK_REQ_RSP_REJECT

SIRK is available only via an OOB procedure

ESP_BLE_AUDIO_CSIP_READ_SIRK_REQ_RSP_OOB_ONLY

ESP_BLE_AUDIO_CSIP_DATA_RSI(_rsi)

Helper to declare bt_data array including RSI.

This macro is mainly for creating an array of struct bt_data elements.

Parameters:

• _rsi -- Pointer to the RSI value.

Type Definitions

typedef struct bt_csip_set_member_cb esp_ble_audio_csip_set_member_cb_t

Callback structure for the Coordinated Set Identification Service

typedef struct bt_csip_set_member_svc_inst esp_ble_audio_csip_set_member_svc_inst_t

Coordinated Set Identification Service instance

typedef struct bt_csip_set_member_register_param esp_ble_audio_csip_set_member_register_param_t

Register structure for Coordinated Set Identification Service

typedef struct bt_csip_set_member_set_info esp_ble_audio_csip_set_member_set_info_t

Struct to hold information about a service instance

typedef struct bt_csip_set_coordinator_cb esp_ble_audio_csip_set_coordinator_cb_t

Struct to hold the Coordinated Set Identification Profile Set Coordinator callbacks

typedef struct bt_csip_set_coordinator_set_info esp_ble_audio_csip_set_coordinator_set_info_t

Information about a specific set

typedef struct bt_csip_set_coordinator_csis_inst esp_ble_audio_csip_set_coordinator_csis_inst_t

Struct representing a coordinated set instance on a remote device

typedef struct bt_csip_set_coordinator_set_member esp_ble_audio_csip_set_coordinator_set_member_t

Struct representing a remote device as a set member

Telephone Bearer Service (TBS)

Header File

• components/bt/esp_ble_audio/api/include/esp_ble_audio_tbs_api.h

• This header file can be included with:

  #include "esp_ble_audio_tbs_api.h"
  

• This header file is a part of the API provided by the bt component. To declare that your component depends on bt, add the following to your CMakeLists.txt:

  REQUIRES bt
  

  or

  PRIV_REQUIRES bt
  

Functions

esp_err_t esp_ble_audio_tbs_accept(uint8_t call_index)

Accept an alerting call.

Parameters:

call_index -- The index of the call that will be accepted.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_hold(uint8_t call_index)

Hold a call.

Parameters:

call_index -- The index of the call that will be held.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_retrieve(uint8_t call_index)

Retrieve a call.

Parameters:

call_index -- The index of the call that will be retrieved.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_terminate(uint8_t call_index)

Terminate a call.

Parameters:

call_index -- The index of the call that will be terminated.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_originate(uint8_t bearer_index, char *uri, uint8_t *call_index)

Originate a call.

Parameters:

• bearer_index -- The index of the Telephone Bearer.

• uri -- The remote URI.

• call_index -- Pointer to a value where the new call_index will be stored.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_join(uint8_t call_index_cnt, uint8_t *call_indexes)

Join calls.

Parameters:

• call_index_cnt -- The number of call indexes to join.

• call_indexes -- Array of call indexes to join.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_remote_answer(uint8_t call_index)

Notify the server that the remote party answered the call.

Parameters:

call_index -- The index of the call that was answered.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_remote_hold(uint8_t call_index)

Notify the server that the remote party held the call.

Parameters:

call_index -- The index of the call that was held.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_remote_retrieve(uint8_t call_index)

Notify the server that the remote party retrieved the call.

Parameters:

call_index -- The index of the call that was retrieved.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_remote_terminate(uint8_t call_index)

Notify the server that the remote party terminated the call.

Parameters:

call_index -- The index of the call that was terminated.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_remote_incoming(uint8_t bearer_index, const char *to, const char *from, const char *friendly_name, uint8_t *call_index)

Notify the server of an incoming call.

Parameters:

• bearer_index -- The index of the Telephone Bearer.

• to -- The URI that is receiving the call.

• from -- The URI of the remote caller.

• friendly_name -- The friendly name of the remote caller.

• call_index -- The call index on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_set_bearer_provider_name(uint8_t bearer_index, const char *name)

Set a new bearer provider.

Parameters:

• bearer_index -- The index of the Telephone Bearer or ESP_BLE_AUDIO_TBS_GTBS_INDEX for GTBS.

• name -- The new bearer provider name.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_set_bearer_technology(uint8_t bearer_index, uint8_t new_technology)

Set a new bearer technology.

Parameters:

• bearer_index -- The index of the Telephone Bearer or ESP_BLE_AUDIO_TBS_GTBS_INDEX for GTBS.

• new_technology -- The new bearer technology.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_set_signal_strength(uint8_t bearer_index, uint8_t new_signal_strength)

Update the signal strength reported by the server.

Parameters:

• bearer_index -- The index of the Telephone Bearer or ESP_BLE_AUDIO_TBS_GTBS_INDEX for GTBS.

• new_signal_strength -- The new signal strength.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_set_status_flags(uint8_t bearer_index, uint16_t status_flags)

Sets the feature and status value.

Parameters:

• bearer_index -- The index of the Telephone Bearer or ESP_BLE_AUDIO_TBS_GTBS_INDEX for GTBS.

• status_flags -- The new feature and status value.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_set_uri_scheme_list(uint8_t bearer_index, const char **uri_list, uint8_t uri_count)

Sets the URI scheme list of a bearer.

Parameters:

• bearer_index -- The index of the Telephone Bearer.

• uri_list -- List of URI prefixes (e.g. {"skype", "tel"}).

• uri_count -- Number of URI prefixes in uri_list.

Returns:

ESP_OK on success, or an error code on failure.

void esp_ble_audio_tbs_register_cb(esp_ble_audio_tbs_cb_t *cbs)

Register the callbacks for TBS.

Parameters:

cbs -- Pointer to the callback structure.

esp_err_t esp_ble_audio_tbs_register_bearer(const esp_ble_audio_tbs_register_param_t *param, uint8_t *bearer_index)

Register a Telephone Bearer.

This will register a Telephone Bearer Service (TBS) (or a Generic Telephone Bearer service (GTBS)) with the provided parameters.

As per the TBS specification, the GTBS shall be instantiated for the feature, and as such a GTBS shall always be registered before any TBS can be registered.

Parameters:

• param -- The parameters to initialize the bearer.

• bearer_index -- The registered bearer index on success.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_unregister_bearer(uint8_t bearer_index)

Unregister a Telephone Bearer.

This will unregister a Telephone Bearer Service (TBS) (or a Generic Telephone Bearer service (GTBS)) with the provided parameters.

Similarly, all TBS shall be unregistered before the GTBS can be unregistered with.

Parameters:

bearer_index -- The index of the bearer to unregister.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_client_discover(uint16_t conn_handle)

Discover TBS for a connection. This will start a GATT discover and setup handles and subscriptions.

Parameters:

conn_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_client_set_signal_strength_interval(uint16_t conn_handle, uint8_t inst_index, uint8_t interval)

Set the signal strength reporting interval for a TBS instance.

Parameters:

• conn_handle -- Connection handle.

• inst_index -- The index of the TBS instance.

• interval -- The interval to write (0-255 seconds).

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_client_originate_call(uint16_t conn_handle, uint8_t inst_index, const char *uri)

Request to originate a call.

Parameters:

• conn_handle -- Connection handle.

• inst_index -- The index of the TBS instance.

• uri -- The URI of the callee.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_client_terminate_call(uint16_t conn_handle, uint8_t inst_index, uint8_t call_index)

Request to terminate a call.

Parameters:

• conn_handle -- Connection handle.

• inst_index -- The index of the TBS instance.

• call_index -- The call index to terminate.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_client_hold_call(uint16_t conn_handle, uint8_t inst_index, uint8_t call_index)

Request to hold a call.

Parameters:

• conn_handle -- Connection handle.

• inst_index -- The index of the TBS instance.

• call_index -- The call index to place on hold.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_client_accept_call(uint16_t conn_handle, uint8_t inst_index, uint8_t call_index)

Accept an incoming call.

Parameters:

• conn_handle -- Connection handle.

• inst_index -- The index of the TBS instance.

• call_index -- The call index to accept.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_client_retrieve_call(uint16_t conn_handle, uint8_t inst_index, uint8_t call_index)

Retrieve call from (local) hold.

Parameters:

• conn_handle -- Connection handle.

• inst_index -- The index of the TBS instance.

• call_index -- The call index to retrieve.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_client_join_calls(uint16_t conn_handle, uint8_t inst_index, const uint8_t *call_indexes, uint8_t count)

Join multiple calls.

Parameters:

• conn_handle -- Connection handle.

• inst_index -- The index of the TBS instance.

• call_indexes -- Array of call indexes.

• count -- Number of call indexes in the call_indexes array.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_client_read_bearer_provider_name(uint16_t conn_handle, uint8_t inst_index)

Read the bearer provider name of a TBS instance.

Parameters:

• conn_handle -- Connection handle.

• inst_index -- The index of the TBS instance.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_client_read_bearer_uci(uint16_t conn_handle, uint8_t inst_index)

Read the UCI of a TBS instance.

Parameters:

• conn_handle -- Connection handle.

• inst_index -- The index of the TBS instance.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_client_read_technology(uint16_t conn_handle, uint8_t inst_index)

Read the technology of a TBS instance.

Parameters:

• conn_handle -- Connection handle.

• inst_index -- The index of the TBS instance.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_client_read_uri_list(uint16_t conn_handle, uint8_t inst_index)

Read the URI schemes list of a TBS instance.

Parameters:

• conn_handle -- Connection handle.

• inst_index -- The index of the TBS instance.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_client_read_signal_strength(uint16_t conn_handle, uint8_t inst_index)

Read the current signal strength of a TBS instance.

Parameters:

• conn_handle -- Connection handle.

• inst_index -- The index of the TBS instance.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_client_read_signal_interval(uint16_t conn_handle, uint8_t inst_index)

Read the signal strength reporting interval of a TBS instance.

Parameters:

• conn_handle -- Connection handle.

• inst_index -- The index of the TBS instance.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_client_read_current_calls(uint16_t conn_handle, uint8_t inst_index)

Read the list of current calls of a TBS instance.

Parameters:

• conn_handle -- Connection handle.

• inst_index -- The index of the TBS instance.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_client_read_ccid(uint16_t conn_handle, uint8_t inst_index)

Read the content ID of a TBS instance.

Parameters:

• conn_handle -- Connection handle.

• inst_index -- The index of the TBS instance.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_client_read_call_uri(uint16_t conn_handle, uint8_t inst_index)

Read the call target URI of a TBS instance.

Parameters:

• conn_handle -- Connection handle.

• inst_index -- The index of the TBS instance.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_client_read_status_flags(uint16_t conn_handle, uint8_t inst_index)

Read the feature and status value of a TBS instance.

Parameters:

• conn_handle -- Connection handle.

• inst_index -- The index of the TBS instance.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_client_read_call_state(uint16_t conn_handle, uint8_t inst_index)

Read the states of the current calls of a TBS instance.

Parameters:

• conn_handle -- Connection handle.

• inst_index -- The index of the TBS instance.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_client_read_remote_uri(uint16_t conn_handle, uint8_t inst_index)

Read the remote URI of a TBS instance.

Parameters:

• conn_handle -- Connection handle.

• inst_index -- The index of the TBS instance.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_client_read_friendly_name(uint16_t conn_handle, uint8_t inst_index)

Read the friendly name of a call for a TBS instance.

Parameters:

• conn_handle -- Connection handle.

• inst_index -- The index of the TBS instance.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_client_read_optional_opcodes(uint16_t conn_handle, uint8_t inst_index)

Read the supported opcode of a TBS instance.

Parameters:

• conn_handle -- Connection handle.

• inst_index -- The index of the TBS instance.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tbs_client_register_cb(esp_ble_audio_tbs_client_cb_t *cbs)

Register the callbacks for CCP.

Parameters:

cbs -- Pointer to the callback structure.

Returns:

ESP_OK on success, or an error code on failure.

esp_ble_audio_tbs_instance_t *esp_ble_audio_tbs_client_get_by_ccid(uint16_t conn_handle, uint8_t ccid)

Look up Telephone Bearer Service instance by CCID.

Parameters:

• conn_handle -- Connection handle.

• ccid -- The CCID to lookup a service instance for.

Returns:

Pointer to TBS instance if found, NULL otherwise.

Macros

ESP_BLE_AUDIO_TBS_GTBS_INDEX

The GTBS index denotes whenever a callback is from a Generic Telephone Bearer Service (GTBS) instance, or whenever the client should perform on action on the GTBS instance of the server, rather than any of the specific Telephone Bearer Service instances. A remote party is calling (incoming call).

ESP_BLE_AUDIO_TBS_CALL_STATE_INCOMING

ESP_BLE_AUDIO_TBS_CALL_STATE_DIALING

The process to call the remote party has started on the server, but the remote party is not being alerted (outgoing call). A remote party is being alerted (outgoing call).

ESP_BLE_AUDIO_TBS_CALL_STATE_ALERTING

The call is in an active conversation.

ESP_BLE_AUDIO_TBS_CALL_STATE_ACTIVE

ESP_BLE_AUDIO_TBS_CALL_STATE_LOCALLY_HELD

The call is connected but held locally. Locally Held implies that either the server or the client can affect the state.

ESP_BLE_AUDIO_TBS_CALL_STATE_REMOTELY_HELD

The call is connected but held remotely. Remotely Held means that the state is controlled by the remote party of a call. The call is connected but held both locally and remotely.

ESP_BLE_AUDIO_TBS_CALL_STATE_LOCALLY_AND_REMOTELY_HELD

The URI value used to originate a call was formed improperly.

ESP_BLE_AUDIO_TBS_REASON_BAD_REMOTE_URI

The call failed.

ESP_BLE_AUDIO_TBS_REASON_CALL_FAILED

The remote party ended the call.

ESP_BLE_AUDIO_TBS_REASON_REMOTE_ENDED_CALL

The call ended from the server.

ESP_BLE_AUDIO_TBS_REASON_SERVER_ENDED_CALL

The line was busy.

ESP_BLE_AUDIO_TBS_REASON_LINE_BUSY

Network congestion.

ESP_BLE_AUDIO_TBS_REASON_NETWORK_CONGESTED

The client terminated the call.

ESP_BLE_AUDIO_TBS_REASON_CLIENT_TERMINATED

No service.

ESP_BLE_AUDIO_TBS_REASON_NO_SERVICE

No answer.

ESP_BLE_AUDIO_TBS_REASON_NO_ANSWER

Unspecified.

ESP_BLE_AUDIO_TBS_REASON_UNSPECIFIED

The opcode write was successful.

ESP_BLE_AUDIO_TBS_RESULT_CODE_SUCCESS

An invalid opcode was used for the Call Control Point write.

ESP_BLE_AUDIO_TBS_RESULT_CODE_OPCODE_NOT_SUPPORTED

The requested operation cannot be completed.

ESP_BLE_AUDIO_TBS_RESULT_CODE_OPERATION_NOT_POSSIBLE

The Call Index used for the Call Control Point write is invalid.

ESP_BLE_AUDIO_TBS_RESULT_CODE_INVALID_CALL_INDEX

ESP_BLE_AUDIO_TBS_RESULT_CODE_STATE_MISMATCH

The opcode written to the Call Control Point was received when the current Call State for the Call Index was not in the expected state. Lack of internal resources to complete the requested action.

ESP_BLE_AUDIO_TBS_RESULT_CODE_OUT_OF_RESOURCES

The Outgoing URI is incorrect or invalid when an Originate opcode is sent.

ESP_BLE_AUDIO_TBS_RESULT_CODE_INVALID_URI

Local Hold and Local Retrieve Call Control Point Opcodes supported

ESP_BLE_AUDIO_TBS_FEATURE_HOLD

Join Call Control Point Opcode supported

ESP_BLE_AUDIO_TBS_FEATURE_JOIN

All Control Point Opcodes supported

ESP_BLE_AUDIO_TBS_FEATURE_ALL

No service

ESP_BLE_AUDIO_TBS_SIGNAL_STRENGTH_NO_SERVICE

Maximum signal strength

ESP_BLE_AUDIO_TBS_SIGNAL_STRENGTH_MAX

Signal strength is unknown

ESP_BLE_AUDIO_TBS_SIGNAL_STRENGTH_UNKNOWN

3G

ESP_BLE_AUDIO_TBS_TECHNOLOGY_3G

4G

ESP_BLE_AUDIO_TBS_TECHNOLOGY_4G

Long-term evolution (LTE)

ESP_BLE_AUDIO_TBS_TECHNOLOGY_LTE

Wifi

ESP_BLE_AUDIO_TBS_TECHNOLOGY_WIFI

5G

ESP_BLE_AUDIO_TBS_TECHNOLOGY_5G

Global System for Mobile Communications (GSM)

ESP_BLE_AUDIO_TBS_TECHNOLOGY_GSM

Code-Division Multiple Access (CDMA)

ESP_BLE_AUDIO_TBS_TECHNOLOGY_CDMA

2G

ESP_BLE_AUDIO_TBS_TECHNOLOGY_2G

Wideband Code-Division Multiple Access (WCDMA)

ESP_BLE_AUDIO_TBS_TECHNOLOGY_WCDMA

Inband ringtone enabled

ESP_BLE_AUDIO_TBS_STATUS_FLAG_INBAND_RINGTONE

Server is in silent mod

ESP_BLE_AUDIO_TBS_STATUS_FLAG_SILENT_MOD

If set, call is outgoing else incoming

ESP_BLE_AUDIO_TBS_CALL_FLAG_OUTGOING

If set call is withheld, else not withheld

ESP_BLE_AUDIO_TBS_CALL_FLAG_WITHHELD

If set call is withheld by network, else provided by network

ESP_BLE_AUDIO_TBS_CALL_FLAG_WITHHELD_BY_NETWORK

Type Definitions

typedef struct bt_tbs_cb esp_ble_audio_tbs_cb_t

Struct to hold the Telephone Bearer Service callbacks

typedef struct bt_tbs_instance esp_ble_audio_tbs_instance_t

Telephone Bearer Service instance

typedef struct bt_tbs_register_param esp_ble_audio_tbs_register_param_t

Struct to hold the parameters to initialize the bearer

typedef struct bt_tbs_client_cb esp_ble_audio_tbs_client_cb_t

Struct to hold the Telephone Bearer Service client callbacks

typedef struct bt_tbs_client_call esp_ble_audio_tbs_client_call_t

Struct to hold a call as the Telephone Bearer Service client

typedef struct bt_tbs_client_call_state esp_ble_audio_tbs_client_call_state_t

Struct to hold a call state

Media Control Client (MCC)

Header File

• components/bt/esp_ble_audio/api/include/esp_ble_audio_mcc_api.h

• This header file can be included with:

  #include "esp_ble_audio_mcc_api.h"
  

• This header file is a part of the API provided by the bt component. To declare that your component depends on bt, add the following to your CMakeLists.txt:

  REQUIRES bt
  

  or

  PRIV_REQUIRES bt
  

Functions

esp_err_t esp_ble_audio_mcc_init(esp_ble_audio_mcc_cb_t *cb)

Initialize Media Control Client.

Parameters:

cb -- Callbacks to be used.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_discover_mcs(uint16_t conn_handle, 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_handle -- Connection handle.

• subscribe -- Whether to subscribe to notifications.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_read_player_name(uint16_t conn_handle)

Read Media Player Name.

Parameters:

conn_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_read_icon_obj_id(uint16_t conn_handle)

Read Icon Object ID.

Parameters:

conn_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_read_icon_url(uint16_t conn_handle)

Read Icon Object URL.

Parameters:

conn_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_read_track_title(uint16_t conn_handle)

Read Track Title.

Parameters:

conn_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_read_track_duration(uint16_t conn_handle)

Read Track Duration.

Parameters:

conn_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_read_track_position(uint16_t conn_handle)

Read Track Position.

Parameters:

conn_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_set_track_position(uint16_t conn_handle, int32_t pos)

Set Track position.

Parameters:

• conn_handle -- Connection handle.

• pos -- Track position.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_read_playback_speed(uint16_t conn_handle)

Read Playback speed.

Parameters:

conn_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_set_playback_speed(uint16_t conn_handle, int8_t speed)

Set Playback Speed.

Parameters:

• conn_handle -- Connection handle.

• speed -- Playback speed.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_read_seeking_speed(uint16_t conn_handle)

Read Seeking speed.

Parameters:

conn_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_read_segments_obj_id(uint16_t conn_handle)

Read Track Segments Object ID.

Parameters:

conn_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_read_current_track_obj_id(uint16_t conn_handle)

Read Current Track Object ID.

Parameters:

conn_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_set_current_track_obj_id(uint16_t conn_handle, uint64_t id)

Set Current Track Object ID.

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

Parameters:

• conn_handle -- Connection handle.

• id -- Object Transfer Service ID (UINT48) of the track to set as the current track.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_read_next_track_obj_id(uint16_t conn_handle)

Read Next Track Object ID.

Parameters:

conn_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_set_next_track_obj_id(uint16_t conn_handle, uint64_t id)

Set Next Track Object ID.

Parameters:

• conn_handle -- Connection handle.

• id -- Object Transfer Service ID (UINT48) of the track to set as the next track.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_read_current_group_obj_id(uint16_t conn_handle)

Read Current Group Object ID.

Parameters:

conn_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_set_current_group_obj_id(uint16_t conn_handle, uint64_t id)

Set Current Group Object ID.

Parameters:

• conn_handle -- Connection handle.

• id -- Object Transfer Service ID (UINT48) of the group to set as the current group.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_read_parent_group_obj_id(uint16_t conn_handle)

Read Parent Group Object ID.

Parameters:

conn_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_read_playing_order(uint16_t conn_handle)

Read Playing Order.

Parameters:

conn_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_set_playing_order(uint16_t conn_handle, uint8_t order)

Set Playing Order.

Parameters:

• conn_handle -- Connection handle.

• order -- Playing order.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_read_playing_orders_supported(uint16_t conn_handle)

Read Playing Orders Supported.

Parameters:

conn_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_read_media_state(uint16_t conn_handle)

Read Media State.

Parameters:

conn_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_send_cmd(uint16_t conn_handle, const esp_ble_audio_mpl_cmd_t *cmd)

Send a command.

Write a command (e.g. "play", "pause") to the server's media control point.

Parameters:

• conn_handle -- Connection handle.

• cmd -- The command to send.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_read_opcodes_supported(uint16_t conn_handle)

Read Opcodes Supported.

Parameters:

conn_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_send_search(uint16_t conn_handle, const esp_ble_audio_mpl_search_t *search)

Send a Search command.

Write a search to the server's search control point.

Parameters:

• conn_handle -- Connection handle.

• search -- The search.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_read_search_results_obj_id(uint16_t conn_handle)

Search Results Group Object ID.

Parameters:

conn_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_read_content_control_id(uint16_t conn_handle)

Read Content Control ID.

Parameters:

conn_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_otc_read_object_metadata(uint16_t conn_handle)

Read the current object metadata.

Parameters:

conn_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_otc_read_icon_object(uint16_t conn_handle)

Read the Icon Object.

Parameters:

conn_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_otc_read_track_segments_object(uint16_t conn_handle)

Read the Track Segments Object.

Parameters:

conn_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_otc_read_current_track_object(uint16_t conn_handle)

Read the Current Track Object.

Parameters:

conn_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_otc_read_next_track_object(uint16_t conn_handle)

Read the Next Track Object.

Parameters:

conn_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_otc_read_current_group_object(uint16_t conn_handle)

Read the Current Group Object.

Parameters:

conn_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_mcc_otc_read_parent_group_object(uint16_t conn_handle)

Read the Parent Group Object.

Parameters:

conn_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

struct bt_ots_client *esp_ble_audio_mcc_otc_inst(uint16_t conn_handle)

Look up MCC OTC instance.

Parameters:

conn_handle -- Connection handle.

Returns:

Pointer to a MCC OTC instance if found else NULL.

Type Definitions

typedef struct bt_mcc_cb esp_ble_audio_mcc_cb_t

Media control client callbacks

Media Proxy

Header File

• components/bt/esp_ble_audio/api/include/esp_ble_audio_media_proxy_api.h

• This header file can be included with:

  #include "esp_ble_audio_media_proxy_api.h"
  

• This header file is a part of the API provided by the bt component. To declare that your component depends on bt, add the following to your CMakeLists.txt:

  REQUIRES bt
  

  or

  PRIV_REQUIRES bt
  

Functions

esp_err_t esp_ble_audio_media_proxy_ctrl_register(esp_ble_audio_media_proxy_ctrl_cbs_t *ctrl_cbs)

Register a controller with the media_proxy.

Parameters:

ctrl_cbs -- Callbacks to the controller.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_media_proxy_ctrl_discover_player(uint16_t conn_handle)

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_handle -- Connection handle.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_media_proxy_ctrl_get_player_name(esp_ble_audio_media_player_t *player)

Read Media Player Name.

Parameters:

player -- Media player instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_media_proxy_ctrl_get_icon_id(esp_ble_audio_media_player_t *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:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_media_proxy_ctrl_get_icon_url(esp_ble_audio_media_player_t *player)

Read Icon URL.

Get a URL to the media player's icon.

Parameters:

player -- Media player instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_media_proxy_ctrl_get_track_title(esp_ble_audio_media_player_t *player)

Read Track Title.

Parameters:

player -- Media player instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_media_proxy_ctrl_get_track_duration(esp_ble_audio_media_player_t *player)

Read Track Duration.

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

Parameters:

player -- Media player instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_media_proxy_ctrl_get_track_position(esp_ble_audio_media_player_t *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:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_media_proxy_ctrl_set_track_position(esp_ble_audio_media_player_t *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:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_media_proxy_ctrl_get_playback_speed(esp_ble_audio_media_player_t *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:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_media_proxy_ctrl_set_playback_speed(esp_ble_audio_media_player_t *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:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_media_proxy_ctrl_get_seeking_speed(esp_ble_audio_media_player_t *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:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_media_proxy_ctrl_get_track_segments_id(esp_ble_audio_media_player_t *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:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_media_proxy_ctrl_get_current_track_id(esp_ble_audio_media_player_t *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:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_media_proxy_ctrl_set_current_track_id(esp_ble_audio_media_player_t *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:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_media_proxy_ctrl_get_next_track_id(esp_ble_audio_media_player_t *player)

Read Next Track Object ID.

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

Requires Object Transfer Service.

Parameters:

player -- Media player instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_media_proxy_ctrl_set_next_track_id(esp_ble_audio_media_player_t *player, uint64_t id)

Set Next Track Object ID.

Change the player's next track to the track given by the ID.

Requires Object Transfer Service.

Parameters:

• player -- Media player instance pointer.

• id -- The ID of a track object.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_media_proxy_ctrl_get_parent_group_id(esp_ble_audio_media_player_t *player)

Read Parent Group Object ID.

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

The parent group is the parent of the current group.

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

Requires Object Transfer Service.

Parameters:

player -- Media player instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_media_proxy_ctrl_get_current_group_id(esp_ble_audio_media_player_t *player)

Read Current Group 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.14 and 4.4 for a description of the Current Group Object.

Requires Object Transfer Service.

Parameters:

player -- Media player instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_media_proxy_ctrl_set_current_group_id(esp_ble_audio_media_player_t *player, uint64_t id)

Set Current Group Object ID.

Change the player's current group to the group given by the ID, and the current track to the first track in that group.

Requires Object Transfer Service.

Parameters:

• player -- Media player instance pointer.

• id -- The ID of a group object.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_media_proxy_ctrl_get_playing_order(esp_ble_audio_media_player_t *player)

Read Playing Order.

Parameters:

player -- Media player instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_media_proxy_ctrl_set_playing_order(esp_ble_audio_media_player_t *player, uint8_t order)

Set Playing Order.

Set the media player's playing order.

Parameters:

• player -- Media player instance pointer.

• order -- The playing order to set.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_media_proxy_ctrl_get_playing_orders_supported(esp_ble_audio_media_player_t *player)

Read Playing Orders Supported.

Read a bitmap containing the media player's supported playing orders.

Parameters:

player -- Media player instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_media_proxy_ctrl_get_media_state(esp_ble_audio_media_player_t *player)

Read Media State.

Read the media player's state.

Parameters:

player -- Media player instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_media_proxy_ctrl_send_command(esp_ble_audio_media_player_t *player, const esp_ble_audio_mpl_cmd_t *command)

Send Command.

Send a command to the media player. Commands may cause the media player to change its state. May result in two callbacks - one for the actual sending of the command to the player, one for the result of the command from the player.

Parameters:

• player -- Media player instance pointer.

• command -- The command to send.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_media_proxy_ctrl_get_commands_supported(esp_ble_audio_media_player_t *player)

Read Commands Supported.

Read a bitmap containing the media player's supported command opcodes.

Parameters:

player -- Media player instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_media_proxy_ctrl_send_search(esp_ble_audio_media_player_t *player, const esp_ble_audio_mpl_search_t *search)

Set Search.

Write a search to the media player. If the search is successful, the search results will be available as a group object in the Object Transfer Service (OTS).

May result in up to three callbacks:

• one for the actual sending of the search to the player;

• one for the result code for the search from the player;

• if the search is successful, one for the search results object ID in the OTs.

Requires Object Transfer Service.

Parameters:

• player -- Media player instance pointer.

• search -- The search to write.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_media_proxy_ctrl_get_search_results_id(esp_ble_audio_media_player_t *player)

Read Search Results Object ID.

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

The search results object is a group object. The search results object only exists if a successful search operation has been done.

Requires Object Transfer Service.

Parameters:

player -- Media player instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_media_proxy_ctrl_get_content_ctrl_id(esp_ble_audio_media_player_t *player)

Read Content Control ID.

The content control ID identifies a content control service on a device, and links it to the corresponding audio stream.

Parameters:

player -- Media player instance pointer.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_media_proxy_pl_register(esp_ble_audio_media_proxy_pl_calls_t *pl_calls)

Register a player with the media proxy.

Register a player with the media proxy module, for use by media controllers.

The media proxy may call any non-NULL function pointers in the supplied media_proxy_pl_calls structure.

Parameters:

pl_calls -- Function pointers to the media player's calls.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_media_proxy_pl_init(void)

Initialize player.

Returns:

ESP_OK on success, or an error code on failure.

struct bt_ots *esp_ble_audio_mcs_get_ots(void)

Get the pointer of the Object Transfer Service used by the Media Control Service.

Returns:

Pointer to an OTS instance if found else NULL.

Macros

ESP_BLE_AUDIO_MEDIA_PROXY_PLAYBACK_SPEED_MIN

< Minimum playback speed, resulting in 25% speed Quarter playback speed, resulting in 25% speed

ESP_BLE_AUDIO_MEDIA_PROXY_PLAYBACK_SPEED_QUARTER

Half playback speed, resulting in 50% speed

ESP_BLE_AUDIO_MEDIA_PROXY_PLAYBACK_SPEED_HALF

Unity playback speed, resulting in 100% speed

ESP_BLE_AUDIO_MEDIA_PROXY_PLAYBACK_SPEED_UNITY

Double playback speed, resulting in 200% speed

ESP_BLE_AUDIO_MEDIA_PROXY_PLAYBACK_SPEED_DOUBLE

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

ESP_BLE_AUDIO_MEDIA_PROXY_PLAYBACK_SPEED_MAX

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

ESP_BLE_AUDIO_MEDIA_PROXY_STATE_INACTIVE

The media player is playing the current track.

ESP_BLE_AUDIO_MEDIA_PROXY_STATE_PLAYING

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

ESP_BLE_AUDIO_MEDIA_PROXY_STATE_PAUSED

The current track is fast forwarding or fast rewinding.

ESP_BLE_AUDIO_MEDIA_PROXY_STATE_SEEKING

Used internally as the last state value

ESP_BLE_AUDIO_MEDIA_PROXY_STATE_LAST

Start playing the current track.

ESP_BLE_AUDIO_MEDIA_PROXY_OP_PLAY

Pause playing the current track.

ESP_BLE_AUDIO_MEDIA_PROXY_OP_PAUSE

Fast rewind the current track.

ESP_BLE_AUDIO_MEDIA_PROXY_OP_FAST_REWIND

Fast forward the current track.

ESP_BLE_AUDIO_MEDIA_PROXY_OP_FAST_FORWARD

ESP_BLE_AUDIO_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. Set a new current track position relative to the current track position.

ESP_BLE_AUDIO_MEDIA_PROXY_OP_MOVE_RELATIVE

ESP_BLE_AUDIO_MEDIA_PROXY_OP_PREV_SEGMENT

Set the current track position to the starting position of the previous segment of the current track.

ESP_BLE_AUDIO_MEDIA_PROXY_OP_NEXT_SEGMENT

Set the current track position to the starting position of the next segment of the current track.

ESP_BLE_AUDIO_MEDIA_PROXY_OP_FIRST_SEGMENT

Set the current track position to the starting position of the first segment of the current track.

ESP_BLE_AUDIO_MEDIA_PROXY_OP_LAST_SEGMENT

Set the current track position to the starting position of the last segment of the current track.

ESP_BLE_AUDIO_MEDIA_PROXY_OP_GOTO_SEGMENT

Set the current track position to the starting position of the nth segment of the current track. Set the current track to the previous track based on the playing order.

ESP_BLE_AUDIO_MEDIA_PROXY_OP_PREV_TRACK

Set the current track to the next track based on the playing order.

ESP_BLE_AUDIO_MEDIA_PROXY_OP_NEXT_TRACK

Set the current track to the first track based on the playing order.

ESP_BLE_AUDIO_MEDIA_PROXY_OP_FIRST_TRACK

Set the current track to the last track based on the playing order.

ESP_BLE_AUDIO_MEDIA_PROXY_OP_LAST_TRACK

Set the current track to the nth track based on the playing order.

ESP_BLE_AUDIO_MEDIA_PROXY_OP_GOTO_TRACK

Set the current group to the previous group in the sequence of groups.

ESP_BLE_AUDIO_MEDIA_PROXY_OP_PREV_GROUP

Set the current group to the next group in the sequence of groups.

ESP_BLE_AUDIO_MEDIA_PROXY_OP_NEXT_GROUP

Set the current group to the first group in the sequence of groups.

ESP_BLE_AUDIO_MEDIA_PROXY_OP_FIRST_GROUP

Set the current group to the last group in the sequence of groups.

ESP_BLE_AUDIO_MEDIA_PROXY_OP_LAST_GROUP

Set the current group to the nth group in the sequence of groups.

ESP_BLE_AUDIO_MEDIA_PROXY_OP_GOTO_GROUP

Media player supported opcodes length

ESP_BLE_AUDIO_MEDIA_PROXY_OPCODES_SUPPORTED_LEN

Support the Play opcode

ESP_BLE_AUDIO_MEDIA_PROXY_OP_SUP_PLAY

Support the Pause opcode

ESP_BLE_AUDIO_MEDIA_PROXY_OP_SUP_PAUSE

Support the Fast Rewind opcode

ESP_BLE_AUDIO_MEDIA_PROXY_OP_SUP_FAST_REWIND

Support the Fast Forward opcode

ESP_BLE_AUDIO_MEDIA_PROXY_OP_SUP_FAST_FORWARD

Support the Stop opcode

ESP_BLE_AUDIO_MEDIA_PROXY_OP_SUP_STOP

Support the Move Relative opcode

ESP_BLE_AUDIO_MEDIA_PROXY_OP_SUP_MOVE_RELATIVE

Support the Previous Segment opcode

ESP_BLE_AUDIO_MEDIA_PROXY_OP_SUP_PREV_SEGMENT

Support the Next Segment opcode

ESP_BLE_AUDIO_MEDIA_PROXY_OP_SUP_NEXT_SEGMENT

Support the First Segment opcode

ESP_BLE_AUDIO_MEDIA_PROXY_OP_SUP_FIRST_SEGMENT

Support the Last Segment opcode

ESP_BLE_AUDIO_MEDIA_PROXY_OP_SUP_LAST_SEGMENT

Support the Goto Segment opcode

ESP_BLE_AUDIO_MEDIA_PROXY_OP_SUP_GOTO_SEGMENT

Support the Previous Track opcode

ESP_BLE_AUDIO_MEDIA_PROXY_OP_SUP_PREV_TRACK

Support the Next Track opcode

ESP_BLE_AUDIO_MEDIA_PROXY_OP_SUP_NEXT_TRACK

Support the First Track opcode

ESP_BLE_AUDIO_MEDIA_PROXY_OP_SUP_FIRST_TRACK

Support the Last Track opcode

ESP_BLE_AUDIO_MEDIA_PROXY_OP_SUP_LAST_TRACK

Support the Goto Track opcode

ESP_BLE_AUDIO_MEDIA_PROXY_OP_SUP_GOTO_TRACK

Support the Previous Group opcode

ESP_BLE_AUDIO_MEDIA_PROXY_OP_SUP_PREV_GROUP

Support the Next Group opcode

ESP_BLE_AUDIO_MEDIA_PROXY_OP_SUP_NEXT_GROUP

Support the First Group opcode

ESP_BLE_AUDIO_MEDIA_PROXY_OP_SUP_FIRST_GROUP

Support the Last Group opcode

ESP_BLE_AUDIO_MEDIA_PROXY_OP_SUP_LAST_GROUP

Support the Goto Group opcode

ESP_BLE_AUDIO_MEDIA_PROXY_OP_SUP_GOTO_GROUP

Action requested by the opcode write was completed successfully.

ESP_BLE_AUDIO_MEDIA_PROXY_CMD_SUCCESS

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

ESP_BLE_AUDIO_MEDIA_PROXY_CMD_NOT_SUPPORTED

ESP_BLE_AUDIO_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.

ESP_BLE_AUDIO_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 for Track Name

ESP_BLE_AUDIO_MEDIA_PROXY_SEARCH_TYPE_TRACK_NAME

Search for Artist Name

ESP_BLE_AUDIO_MEDIA_PROXY_SEARCH_TYPE_ARTIST_NAME

Search for Album Name

ESP_BLE_AUDIO_MEDIA_PROXY_SEARCH_TYPE_ALBUM_NAME

Search for Group Name

ESP_BLE_AUDIO_MEDIA_PROXY_SEARCH_TYPE_GROUP_NAME

Search for Earliest Year

ESP_BLE_AUDIO_MEDIA_PROXY_SEARCH_TYPE_EARLIEST_YEAR

Search for Latest Year

ESP_BLE_AUDIO_MEDIA_PROXY_SEARCH_TYPE_LATEST_YEAR

Search for Genre

ESP_BLE_AUDIO_MEDIA_PROXY_SEARCH_TYPE_GENRE

Search for Tracks only

ESP_BLE_AUDIO_MEDIA_PROXY_SEARCH_TYPE_ONLY_TRACKS

Search for Groups only

ESP_BLE_AUDIO_MEDIA_PROXY_SEARCH_TYPE_ONLY_GROUPS

Search request was accepted; search has started.

ESP_BLE_AUDIO_MEDIA_PROXY_SEARCH_SUCCESS

Search request was invalid; no search started.

ESP_BLE_AUDIO_MEDIA_PROXY_SEARCH_FAILURE

Group object type is track

ESP_BLE_AUDIO_MEDIA_PROXY_GROUP_OBJECT_TRACK_TYPE

Group object type is group

ESP_BLE_AUDIO_MEDIA_PROXY_GROUP_OBJECT_GROUP_TYPE

Maximum seeking speed - Can be negated

ESP_BLE_AUDIO_MEDIA_PROXY_SEEKING_SPEED_FACTOR_MAX

Minimum seeking speed - Can be negated

ESP_BLE_AUDIO_MEDIA_PROXY_SEEKING_SPEED_FACTOR_MIN

No seeking

ESP_BLE_AUDIO_MEDIA_PROXY_SEEKING_SPEED_FACTOR_ZERO

A single track is played once; there is no next track.

ESP_BLE_AUDIO_MEDIA_PROXY_PLAYING_ORDER_SINGLE_ONCE

A single track is played repeatedly; the next track is the current track.

ESP_BLE_AUDIO_MEDIA_PROXY_PLAYING_ORDER_SINGLE_REPEAT

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

ESP_BLE_AUDIO_MEDIA_PROXY_PLAYING_ORDER_INORDER_ONCE

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

ESP_BLE_AUDIO_MEDIA_PROXY_PLAYING_ORDER_INORDER_REPEAT

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

ESP_BLE_AUDIO_MEDIA_PROXY_PLAYING_ORDER_OLDEST_ONCE

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

ESP_BLE_AUDIO_MEDIA_PROXY_PLAYING_ORDER_OLDEST_REPEAT

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

ESP_BLE_AUDIO_MEDIA_PROXY_PLAYING_ORDER_NEWEST_ONCE

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

ESP_BLE_AUDIO_MEDIA_PROXY_PLAYING_ORDER_NEWEST_REPEAT

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

ESP_BLE_AUDIO_MEDIA_PROXY_PLAYING_ORDER_SHUFFLE_ONCE

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

ESP_BLE_AUDIO_MEDIA_PROXY_PLAYING_ORDER_SHUFFLE_REPEAT

A single track is played once; there is no next track.

ESP_BLE_AUDIO_MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_SINGLE_ONCE

A single track is played repeatedly; the next track is the current track.

ESP_BLE_AUDIO_MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_SINGLE_REPEAT

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

ESP_BLE_AUDIO_MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_INORDER_ONCE

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

ESP_BLE_AUDIO_MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_INORDER_REPEAT

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

ESP_BLE_AUDIO_MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_OLDEST_ONCE

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

ESP_BLE_AUDIO_MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_OLDEST_REPEAT

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

ESP_BLE_AUDIO_MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_NEWEST_ONCE

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

ESP_BLE_AUDIO_MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_NEWEST_REPEAT

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

ESP_BLE_AUDIO_MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_SHUFFLE_ONCE

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

ESP_BLE_AUDIO_MEDIA_PROXY_PLAYING_ORDERS_SUPPORTED_SHUFFLE_REPEAT

Type Definitions

typedef struct mpl_cmd esp_ble_audio_mpl_cmd_t

Media player command

typedef struct mpl_cmd_ntf esp_ble_audio_mpl_cmd_ntf_t

Media command notification

typedef struct mpl_sci esp_ble_audio_mpl_sci_t

Search control item

typedef struct mpl_search esp_ble_audio_mpl_search_t

Search

typedef struct media_player esp_ble_audio_media_player_t

Media player instance

typedef struct media_proxy_ctrl_cbs esp_ble_audio_media_proxy_ctrl_cbs_t

Callbacks to a controller, from the media proxy

typedef struct media_proxy_pl_calls esp_ble_audio_media_proxy_pl_calls_t

Available calls in a player, that the media proxy can call

Telephony and Media Audio Profile (TMAP)

Header File

• components/bt/esp_ble_audio/api/include/esp_ble_audio_tmap_api.h

• This header file can be included with:

  #include "esp_ble_audio_tmap_api.h"
  

• This header file is a part of the API provided by the bt component. To declare that your component depends on bt, add the following to your CMakeLists.txt:

  REQUIRES bt
  

  or

  PRIV_REQUIRES bt
  

Functions

esp_err_t esp_ble_audio_tmap_register(esp_ble_audio_tmap_role_t role)

Adds TMAS instance to database and sets the received TMAP role(s).

Parameters:

role -- TMAP role(s) of the device (one or multiple).

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_tmap_discover(uint16_t conn_handle, const esp_ble_audio_tmap_cb_t *tmap_cb)

Perform service discovery as TMAP Client.

Parameters:

• conn_handle -- Connection handle.

• tmap_cb -- Pointer to struct of TMAP callbacks.

Returns:

ESP_OK on success, or an error code on failure.

void esp_ble_audio_tmap_set_role(esp_ble_audio_tmap_role_t role)

Set one or multiple TMAP roles dynamically. Previously registered value will be overwritten.

Parameters:

role -- TMAP role(s).

Macros

ESP_BLE_AUDIO_TMAP_ROLE_CG

< TMAP Call Gateway role TMAP Call Terminal role

ESP_BLE_AUDIO_TMAP_ROLE_CT

TMAP Unicast Media Sender role

ESP_BLE_AUDIO_TMAP_ROLE_UMS

TMAP Unicast Media Receiver role

ESP_BLE_AUDIO_TMAP_ROLE_UMR

TMAP Broadcast Media Sender role

ESP_BLE_AUDIO_TMAP_ROLE_BMS

TMAP Broadcast Media Receiver role

ESP_BLE_AUDIO_TMAP_ROLE_BMR

Type Definitions

typedef enum bt_tmap_role esp_ble_audio_tmap_role_t

TMAP Role characteristic

typedef struct bt_tmap_cb esp_ble_audio_tmap_cb_t

TMAP callback structure

Public Broadcast Profile (PBP)

Header File

• components/bt/esp_ble_audio/api/include/esp_ble_audio_pbp_api.h

• This header file can be included with:

  #include "esp_ble_audio_pbp_api.h"
  

• This header file is a part of the API provided by the bt component. To declare that your component depends on bt, add the following to your CMakeLists.txt:

  REQUIRES bt
  

  or

  PRIV_REQUIRES bt
  

Functions

esp_err_t esp_ble_audio_pbp_get_announcement(const uint8_t meta[], size_t meta_len, esp_ble_audio_pbp_announcement_feature_t features, struct net_buf_simple *pba_data_buf)

Creates a Public Broadcast Announcement based on the information received in the features parameter.

Parameters:

• meta -- Metadata to be included in the advertising data.

• meta_len -- Size of the metadata fields to be included in the advertising data.

• features -- Public Broadcast Announcement features.

• pba_data_buf -- Pointer to store the PBA advertising data. Buffer size needs to be meta_len + ESP_BLE_AUDIO_PBP_MIN_PBA_SIZE.

Returns:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_audio_pbp_parse_announcement(uint8_t data_type, const uint8_t *data, uint8_t data_len, esp_ble_audio_pbp_announcement_feature_t *features, uint8_t **meta, uint8_t *meta_len)

Parses the received advertising data corresponding to a Public Broadcast Announcement. Returns the advertised Public Broadcast Announcement features and metadata.

Parameters:

• data_type -- Type of advertising data to be checked.

• data -- Pointer of advertising data to be checked.

• data_len -- Length of advertising data to be checked.

• features -- Pointer to public broadcast source features to store the parsed features in.

• meta -- Pointer to the metadata present in the advertising data.

• meta_len -- Size of the metadata fields to be included in the advertising data.

Returns:

ESP_OK on success, or an error code on failure.

Macros

ESP_BLE_AUDIO_PBP_MIN_PBA_SIZE

Minimum size of the Public Broadcast Announcement Broadcast Streams encryption status

ESP_BLE_AUDIO_PBP_ANNOUNCEMENT_FEATURE_ENCRYPTION

Standard Quality Public Broadcast Audio configuration

ESP_BLE_AUDIO_PBP_ANNOUNCEMENT_FEATURE_STANDARD_QUALITY

High Quality Public Broadcast Audio configuration

ESP_BLE_AUDIO_PBP_ANNOUNCEMENT_FEATURE_HIGH_QUALITY

Type Definitions

typedef enum bt_pbp_announcement_feature esp_ble_audio_pbp_announcement_feature_t

Public Broadcast Announcement features

---

Was this page helpful?

• Thank you! We received your feedback.
• If you have any comments, fill in Espressif Documentation Feedback Form.

• We value your feedback.
• Let us know how we can improve this page by filling in Espressif Documentation Feedback Form.