1 /** @file 2 * @brief Bluetooth Audio handling 3 */ 4 5 /* 6 * Copyright (c) 2020 Intel Corporation 7 * Copyright (c) 2020-2023 Nordic Semiconductor ASA 8 * 9 * SPDX-License-Identifier: Apache-2.0 10 */ 11 #ifndef ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_AUDIO_H_ 12 #define ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_AUDIO_H_ 13 14 /** 15 * @brief Bluetooth Audio 16 * @defgroup bt_audio Bluetooth Audio 17 * @ingroup bluetooth 18 * @{ 19 */ 20 21 #include <zephyr/sys/atomic.h> 22 #include <zephyr/bluetooth/buf.h> 23 #include <zephyr/bluetooth/conn.h> 24 #include <zephyr/bluetooth/hci.h> 25 #include <zephyr/bluetooth/iso.h> 26 #include <zephyr/bluetooth/gatt.h> 27 #include <zephyr/bluetooth/audio/lc3.h> 28 29 30 #ifdef __cplusplus 31 extern "C" { 32 #endif 33 34 #define BT_AUDIO_BROADCAST_ID_SIZE 3 /* octets */ 35 /** Maximum broadcast ID value */ 36 #define BT_AUDIO_BROADCAST_ID_MAX 0xFFFFFFU 37 /** Indicates that the server have no preference for the presentation delay */ 38 #define BT_AUDIO_PD_PREF_NONE 0x000000U 39 /** Maximum presentation delay in microseconds */ 40 #define BT_AUDIO_PD_MAX 0xFFFFFFU 41 42 #define BT_AUDIO_BROADCAST_CODE_SIZE 16 43 44 /** @brief Audio Context Type for Generic Audio 45 * 46 * These values are defined by the Generic Audio Assigned Numbers, bluetooth.com 47 */ 48 enum bt_audio_context { 49 BT_AUDIO_CONTEXT_TYPE_PROHIBITED = 0, 50 BT_AUDIO_CONTEXT_TYPE_UNSPECIFIED = BIT(0), 51 BT_AUDIO_CONTEXT_TYPE_CONVERSATIONAL = BIT(1), 52 BT_AUDIO_CONTEXT_TYPE_MEDIA = BIT(2), 53 BT_AUDIO_CONTEXT_TYPE_GAME = BIT(3), 54 BT_AUDIO_CONTEXT_TYPE_INSTRUCTIONAL = BIT(4), 55 BT_AUDIO_CONTEXT_TYPE_VOICE_ASSISTANTS = BIT(5), 56 BT_AUDIO_CONTEXT_TYPE_LIVE = BIT(6), 57 BT_AUDIO_CONTEXT_TYPE_SOUND_EFFECTS = BIT(7), 58 BT_AUDIO_CONTEXT_TYPE_NOTIFICATIONS = BIT(8), 59 BT_AUDIO_CONTEXT_TYPE_RINGTONE = BIT(9), 60 BT_AUDIO_CONTEXT_TYPE_ALERTS = BIT(10), 61 BT_AUDIO_CONTEXT_TYPE_EMERGENCY_ALARM = BIT(11), 62 }; 63 64 /** 65 * Any known context. 66 */ 67 #define BT_AUDIO_CONTEXT_TYPE_ANY (BT_AUDIO_CONTEXT_TYPE_UNSPECIFIED | \ 68 BT_AUDIO_CONTEXT_TYPE_CONVERSATIONAL | \ 69 BT_AUDIO_CONTEXT_TYPE_MEDIA | \ 70 BT_AUDIO_CONTEXT_TYPE_GAME | \ 71 BT_AUDIO_CONTEXT_TYPE_INSTRUCTIONAL | \ 72 BT_AUDIO_CONTEXT_TYPE_VOICE_ASSISTANTS | \ 73 BT_AUDIO_CONTEXT_TYPE_LIVE | \ 74 BT_AUDIO_CONTEXT_TYPE_SOUND_EFFECTS | \ 75 BT_AUDIO_CONTEXT_TYPE_NOTIFICATIONS | \ 76 BT_AUDIO_CONTEXT_TYPE_RINGTONE | \ 77 BT_AUDIO_CONTEXT_TYPE_ALERTS | \ 78 BT_AUDIO_CONTEXT_TYPE_EMERGENCY_ALARM) 79 80 /** 81 * @brief Parental rating defined by the Generic Audio assigned numbers (bluetooth.com). 82 * 83 * The numbering scheme is aligned with Annex F of EN 300 707 v1.2.1 which 84 * defined parental rating for viewing. 85 */ 86 enum bt_audio_parental_rating { 87 BT_AUDIO_PARENTAL_RATING_NO_RATING = 0x00, 88 BT_AUDIO_PARENTAL_RATING_AGE_ANY = 0x01, 89 BT_AUDIO_PARENTAL_RATING_AGE_5_OR_ABOVE = 0x02, 90 BT_AUDIO_PARENTAL_RATING_AGE_6_OR_ABOVE = 0x03, 91 BT_AUDIO_PARENTAL_RATING_AGE_7_OR_ABOVE = 0x04, 92 BT_AUDIO_PARENTAL_RATING_AGE_8_OR_ABOVE = 0x05, 93 BT_AUDIO_PARENTAL_RATING_AGE_9_OR_ABOVE = 0x06, 94 BT_AUDIO_PARENTAL_RATING_AGE_10_OR_ABOVE = 0x07, 95 BT_AUDIO_PARENTAL_RATING_AGE_11_OR_ABOVE = 0x08, 96 BT_AUDIO_PARENTAL_RATING_AGE_12_OR_ABOVE = 0x09, 97 BT_AUDIO_PARENTAL_RATING_AGE_13_OR_ABOVE = 0x0A, 98 BT_AUDIO_PARENTAL_RATING_AGE_14_OR_ABOVE = 0x0B, 99 BT_AUDIO_PARENTAL_RATING_AGE_15_OR_ABOVE = 0x0C, 100 BT_AUDIO_PARENTAL_RATING_AGE_16_OR_ABOVE = 0x0D, 101 BT_AUDIO_PARENTAL_RATING_AGE_17_OR_ABOVE = 0x0E, 102 BT_AUDIO_PARENTAL_RATING_AGE_18_OR_ABOVE = 0x0F 103 }; 104 105 /** @brief Audio Active State defined by the Generic Audio assigned numbers (bluetooth.com). */ 106 enum bt_audio_active_state { 107 BT_AUDIO_ACTIVE_STATE_DISABLED = 0x00, 108 BT_AUDIO_ACTIVE_STATE_ENABLED = 0x01, 109 }; 110 111 /** 112 * @brief Codec metadata type IDs 113 * 114 * Metadata types defined by the Generic Audio assigned numbers (bluetooth.com). 115 */ 116 enum bt_audio_metadata_type { 117 /** @brief Preferred audio context. 118 * 119 * Bitfield of preferred audio contexts. 120 * 121 * If 0, the context type is not a preferred use case for this codec 122 * configuration. 123 * 124 * See the BT_AUDIO_CONTEXT_* for valid values. 125 */ 126 BT_AUDIO_METADATA_TYPE_PREF_CONTEXT = 0x01, 127 128 /** @brief Streaming audio context. 129 * 130 * Bitfield of streaming audio contexts. 131 * 132 * If 0, the context type is not a preferred use case for this codec 133 * configuration. 134 * 135 * See the BT_AUDIO_CONTEXT_* for valid values. 136 */ 137 BT_AUDIO_METADATA_TYPE_STREAM_CONTEXT = 0x02, 138 139 /** UTF-8 encoded title or summary of stream content */ 140 BT_AUDIO_METADATA_TYPE_PROGRAM_INFO = 0x03, 141 142 /** @brief Stream language 143 * 144 * 3 octet lower case language code defined by ISO 639-3 145 */ 146 BT_AUDIO_METADATA_TYPE_STREAM_LANG = 0x04, 147 148 /** Array of 8-bit CCID values */ 149 BT_AUDIO_METADATA_TYPE_CCID_LIST = 0x05, 150 151 /** @brief Parental rating 152 * 153 * See @ref bt_audio_parental_rating for valid values. 154 */ 155 BT_AUDIO_METADATA_TYPE_PARENTAL_RATING = 0x06, 156 157 /** UTF-8 encoded URI for additional Program information */ 158 BT_AUDIO_METADATA_TYPE_PROGRAM_INFO_URI = 0x07, 159 160 /** @brief Audio active state 161 * 162 * See @ref bt_audio_active_state for valid values. 163 */ 164 BT_AUDIO_METADATA_TYPE_AUDIO_STATE = 0x08, 165 166 /** Broadcast Audio Immediate Rendering flag */ 167 BT_AUDIO_METADATA_TYPE_BROADCAST_IMMEDIATE = 0x09, 168 169 /** Extended metadata */ 170 BT_AUDIO_METADATA_TYPE_EXTENDED = 0xFE, 171 172 /** Vendor specific metadata */ 173 BT_AUDIO_METADATA_TYPE_VENDOR = 0xFF, 174 }; 175 176 /* Unicast Announcement Type, Generic Audio */ 177 #define BT_AUDIO_UNICAST_ANNOUNCEMENT_GENERAL 0x00 178 #define BT_AUDIO_UNICAST_ANNOUNCEMENT_TARGETED 0x01 179 180 /** @brief Codec configuration structure */ 181 struct bt_codec_data { 182 struct bt_data data; 183 uint8_t value[CONFIG_BT_CODEC_MAX_DATA_LEN]; 184 }; 185 186 /** 187 * @brief Helper to declare elements of bt_codec_data arrays 188 * 189 * This macro is mainly for creating an array of struct bt_codec_data 190 * elements inside bt_codec which is then passed to the likes of 191 * bt_bap_stream_config or bt_bap_stream_reconfig. 192 * 193 * @param _type Type of advertising data field 194 * @param _bytes Variable number of single-byte parameters 195 */ 196 #define BT_CODEC_DATA(_type, _bytes...) \ 197 { \ 198 .data = BT_DATA(_type, ((uint8_t []) { _bytes }), \ 199 sizeof((uint8_t []) { _bytes })) \ 200 } 201 202 /** 203 * @brief Helper to declare bt_codec structure 204 * 205 * @param _id Codec ID 206 * @param _cid Company ID 207 * @param _vid Vendor ID 208 * @param _data Codec Specific Data in LVT format 209 * @param _meta Codec Specific Metadata in LVT format 210 */ 211 #define BT_CODEC(_id, _cid, _vid, _data, _meta) \ 212 { \ 213 /* Use HCI data path as default, can be overwritten by application */ \ 214 .path_id = BT_ISO_DATA_PATH_HCI, \ 215 .id = _id, \ 216 .cid = _cid, \ 217 .vid = _vid, \ 218 .data_count = ARRAY_SIZE(((struct bt_codec_data[]) _data)), \ 219 .data = _data, \ 220 .meta_count = ARRAY_SIZE(((struct bt_codec_data[]) _meta)), \ 221 .meta = _meta, \ 222 } 223 224 /** @brief Location values for BT Audio. 225 * 226 * These values are defined by the Generic Audio Assigned Numbers, bluetooth.com 227 */ 228 enum bt_audio_location { 229 BT_AUDIO_LOCATION_PROHIBITED = 0, 230 BT_AUDIO_LOCATION_FRONT_LEFT = BIT(0), 231 BT_AUDIO_LOCATION_FRONT_RIGHT = BIT(1), 232 BT_AUDIO_LOCATION_FRONT_CENTER = BIT(2), 233 BT_AUDIO_LOCATION_LOW_FREQ_EFFECTS_1 = BIT(3), 234 BT_AUDIO_LOCATION_BACK_LEFT = BIT(4), 235 BT_AUDIO_LOCATION_BACK_RIGHT = BIT(5), 236 BT_AUDIO_LOCATION_FRONT_LEFT_OF_CENTER = BIT(6), 237 BT_AUDIO_LOCATION_FRONT_RIGHT_OF_CENTER = BIT(7), 238 BT_AUDIO_LOCATION_BACK_CENTER = BIT(8), 239 BT_AUDIO_LOCATION_LOW_FREQ_EFFECTS_2 = BIT(9), 240 BT_AUDIO_LOCATION_SIDE_LEFT = BIT(10), 241 BT_AUDIO_LOCATION_SIDE_RIGHT = BIT(11), 242 BT_AUDIO_LOCATION_TOP_FRONT_LEFT = BIT(12), 243 BT_AUDIO_LOCATION_TOP_FRONT_RIGHT = BIT(13), 244 BT_AUDIO_LOCATION_TOP_FRONT_CENTER = BIT(14), 245 BT_AUDIO_LOCATION_TOP_CENTER = BIT(15), 246 BT_AUDIO_LOCATION_TOP_BACK_LEFT = BIT(16), 247 BT_AUDIO_LOCATION_TOP_BACK_RIGHT = BIT(17), 248 BT_AUDIO_LOCATION_TOP_SIDE_LEFT = BIT(18), 249 BT_AUDIO_LOCATION_TOP_SIDE_RIGHT = BIT(19), 250 BT_AUDIO_LOCATION_TOP_BACK_CENTER = BIT(20), 251 BT_AUDIO_LOCATION_BOTTOM_FRONT_CENTER = BIT(21), 252 BT_AUDIO_LOCATION_BOTTOM_FRONT_LEFT = BIT(22), 253 BT_AUDIO_LOCATION_BOTTOM_FRONT_RIGHT = BIT(23), 254 BT_AUDIO_LOCATION_FRONT_LEFT_WIDE = BIT(24), 255 BT_AUDIO_LOCATION_FRONT_RIGHT_WIDE = BIT(25), 256 BT_AUDIO_LOCATION_LEFT_SURROUND = BIT(26), 257 BT_AUDIO_LOCATION_RIGHT_SURROUND = BIT(27), 258 }; 259 260 /** 261 * Any known location. 262 */ 263 #define BT_AUDIO_LOCATION_ANY (BT_AUDIO_LOCATION_FRONT_LEFT | \ 264 BT_AUDIO_LOCATION_FRONT_RIGHT | \ 265 BT_AUDIO_LOCATION_FRONT_CENTER | \ 266 BT_AUDIO_LOCATION_LOW_FREQ_EFFECTS_1 | \ 267 BT_AUDIO_LOCATION_BACK_LEFT | \ 268 BT_AUDIO_LOCATION_BACK_RIGHT | \ 269 BT_AUDIO_LOCATION_FRONT_LEFT_OF_CENTER | \ 270 BT_AUDIO_LOCATION_FRONT_RIGHT_OF_CENTER | \ 271 BT_AUDIO_LOCATION_BACK_CENTER | \ 272 BT_AUDIO_LOCATION_LOW_FREQ_EFFECTS_2 | \ 273 BT_AUDIO_LOCATION_SIDE_LEFT | \ 274 BT_AUDIO_LOCATION_SIDE_RIGHT | \ 275 BT_AUDIO_LOCATION_TOP_FRONT_LEFT | \ 276 BT_AUDIO_LOCATION_TOP_FRONT_RIGHT | \ 277 BT_AUDIO_LOCATION_TOP_FRONT_CENTER | \ 278 BT_AUDIO_LOCATION_TOP_CENTER | \ 279 BT_AUDIO_LOCATION_TOP_BACK_LEFT | \ 280 BT_AUDIO_LOCATION_TOP_BACK_RIGHT | \ 281 BT_AUDIO_LOCATION_TOP_SIDE_LEFT | \ 282 BT_AUDIO_LOCATION_TOP_SIDE_RIGHT | \ 283 BT_AUDIO_LOCATION_TOP_BACK_CENTER | \ 284 BT_AUDIO_LOCATION_BOTTOM_FRONT_CENTER | \ 285 BT_AUDIO_LOCATION_BOTTOM_FRONT_LEFT | \ 286 BT_AUDIO_LOCATION_BOTTOM_FRONT_RIGHT | \ 287 BT_AUDIO_LOCATION_FRONT_LEFT_WIDE | \ 288 BT_AUDIO_LOCATION_FRONT_RIGHT_WIDE | \ 289 BT_AUDIO_LOCATION_LEFT_SURROUND | \ 290 BT_AUDIO_LOCATION_RIGHT_SURROUND) 291 292 /** @brief Codec structure. */ 293 struct bt_codec { 294 /** Data path ID 295 * 296 * @ref BT_ISO_DATA_PATH_HCI for HCI path, or any other value for 297 * vendor specific ID. 298 */ 299 uint8_t path_id; 300 /** Codec ID */ 301 uint8_t id; 302 /** Codec Company ID */ 303 uint16_t cid; 304 /** Codec Company Vendor ID */ 305 uint16_t vid; 306 #if defined(CONFIG_BT_CODEC_MAX_DATA_COUNT) 307 /** Codec Specific Data count */ 308 size_t data_count; 309 /** Codec Specific Data */ 310 struct bt_codec_data data[CONFIG_BT_CODEC_MAX_DATA_COUNT]; 311 #endif /* CONFIG_BT_CODEC_MAX_DATA_COUNT */ 312 #if defined(CONFIG_BT_CODEC_MAX_METADATA_COUNT) 313 /** Codec Specific Metadata count */ 314 size_t meta_count; 315 /** Codec Specific Metadata */ 316 struct bt_codec_data meta[CONFIG_BT_CODEC_MAX_METADATA_COUNT]; 317 #endif /* CONFIG_BT_CODEC_MAX_METADATA_COUNT */ 318 }; 319 320 /** @brief Audio Capability type */ 321 enum bt_audio_dir { 322 BT_AUDIO_DIR_SINK = 0x01, 323 BT_AUDIO_DIR_SOURCE = 0x02, 324 }; 325 326 /** 327 * @brief Helper to declare elements of bt_codec_qos 328 * 329 * @param _interval SDU interval (usec) 330 * @param _framing Framing 331 * @param _phy Target PHY 332 * @param _sdu Maximum SDU Size 333 * @param _rtn Retransmission number 334 * @param _latency Maximum Transport Latency (msec) 335 * @param _pd Presentation Delay (usec) 336 */ 337 #define BT_CODEC_QOS(_interval, _framing, _phy, _sdu, _rtn, _latency, \ 338 _pd) \ 339 { \ 340 .interval = _interval, \ 341 .framing = _framing, \ 342 .phy = _phy, \ 343 .sdu = _sdu, \ 344 .rtn = _rtn, \ 345 .latency = _latency, \ 346 .pd = _pd, \ 347 } 348 349 /** @brief Codec QoS Framing */ 350 enum { 351 BT_CODEC_QOS_UNFRAMED = 0x00, 352 BT_CODEC_QOS_FRAMED = 0x01, 353 }; 354 355 /** @brief Codec QoS Preferred PHY */ 356 enum { 357 BT_CODEC_QOS_1M = BIT(0), 358 BT_CODEC_QOS_2M = BIT(1), 359 BT_CODEC_QOS_CODED = BIT(2), 360 }; 361 362 /** 363 * @brief Helper to declare Input Unframed bt_codec_qos 364 * 365 * @param _interval SDU interval (usec) 366 * @param _sdu Maximum SDU Size 367 * @param _rtn Retransmission number 368 * @param _latency Maximum Transport Latency (msec) 369 * @param _pd Presentation Delay (usec) 370 */ 371 #define BT_CODEC_QOS_UNFRAMED(_interval, _sdu, _rtn, _latency, _pd) \ 372 BT_CODEC_QOS(_interval, BT_CODEC_QOS_UNFRAMED, BT_CODEC_QOS_2M, _sdu, \ 373 _rtn, _latency, _pd) 374 375 /** 376 * @brief Helper to declare Input Framed bt_codec_qos 377 * 378 * @param _interval SDU interval (usec) 379 * @param _sdu Maximum SDU Size 380 * @param _rtn Retransmission number 381 * @param _latency Maximum Transport Latency (msec) 382 * @param _pd Presentation Delay (usec) 383 */ 384 #define BT_CODEC_QOS_FRAMED(_interval, _sdu, _rtn, _latency, _pd) \ 385 BT_CODEC_QOS(_interval, BT_CODEC_QOS_FRAMED, BT_CODEC_QOS_2M, _sdu, \ 386 _rtn, _latency, _pd) 387 388 /** @brief Codec QoS structure. */ 389 struct bt_codec_qos { 390 /** QoS PHY */ 391 uint8_t phy; 392 393 /** QoS Framing */ 394 uint8_t framing; 395 396 /** QoS Retransmission Number */ 397 uint8_t rtn; 398 399 /** QoS SDU */ 400 uint16_t sdu; 401 402 #if defined(CONFIG_BT_BAP_BROADCAST_SOURCE) || defined(CONFIG_BT_BAP_UNICAST) 403 /** 404 * @brief QoS Transport Latency 405 * 406 * Not used for the @kconfig{CONFIG_BT_BAP_BROADCAST_SINK} role. 407 */ 408 uint16_t latency; 409 #endif /* CONFIG_BT_BAP_BROADCAST_SOURCE || CONFIG_BT_BAP_UNICAST */ 410 411 /** QoS Frame Interval */ 412 uint32_t interval; 413 414 /** @brief QoS Presentation Delay in microseconds 415 * 416 * Value range 0 to @ref BT_AUDIO_PD_MAX. 417 */ 418 uint32_t pd; 419 }; 420 421 /** 422 * @brief Helper to declare elements of @ref bt_codec_qos_pref 423 * 424 * @param _unframed_supported Unframed PDUs supported 425 * @param _phy Preferred Target PHY 426 * @param _rtn Preferred Retransmission number 427 * @param _latency Preferred Maximum Transport Latency (msec) 428 * @param _pd_min Minimum Presentation Delay (usec) 429 * @param _pd_max Maximum Presentation Delay (usec) 430 * @param _pref_pd_min Preferred Minimum Presentation Delay (usec) 431 * @param _pref_pd_max Preferred Maximum Presentation Delay (usec) 432 */ 433 #define BT_CODEC_QOS_PREF(_unframed_supported, _phy, _rtn, _latency, _pd_min, \ 434 _pd_max, _pref_pd_min, _pref_pd_max) \ 435 { \ 436 .unframed_supported = _unframed_supported, \ 437 .phy = _phy, \ 438 .rtn = _rtn, \ 439 .latency = _latency, \ 440 .pd_min = _pd_min, \ 441 .pd_max = _pd_max, \ 442 .pref_pd_min = _pref_pd_min, \ 443 .pref_pd_max = _pref_pd_max, \ 444 } 445 446 /** @brief Audio Stream Quality of Service Preference structure. */ 447 struct bt_codec_qos_pref { 448 /** @brief Unframed PDUs supported 449 * 450 * Unlike the other fields, this is not a preference but whether 451 * the codec supports unframed ISOAL PDUs. 452 */ 453 bool unframed_supported; 454 455 /** Preferred PHY */ 456 uint8_t phy; 457 458 /** Preferred Retransmission Number */ 459 uint8_t rtn; 460 461 /** Preferred Transport Latency */ 462 uint16_t latency; 463 464 /** @brief Minimum Presentation Delay in microseconds 465 * 466 * Unlike the other fields, this is not a preference but a minimum 467 * requirement. 468 * 469 * Value range 0 to @ref BT_AUDIO_PD_MAX, or @ref BT_AUDIO_PD_PREF_NONE 470 * to indicate no preference. 471 */ 472 uint32_t pd_min; 473 474 /** @brief Maximum Presentation Delay 475 * 476 * Unlike the other fields, this is not a preference but a maximum 477 * requirement. 478 * 479 * Value range 0 to @ref BT_AUDIO_PD_MAX, or @ref BT_AUDIO_PD_PREF_NONE 480 * to indicate no preference. 481 */ 482 uint32_t pd_max; 483 484 /** @brief Preferred minimum Presentation Delay 485 * 486 * Value range 0 to @ref BT_AUDIO_PD_MAX. 487 */ 488 uint32_t pref_pd_min; 489 490 /** @brief Preferred maximum Presentation Delay 491 * 492 * Value range 0 to @ref BT_AUDIO_PD_MAX. 493 */ 494 uint32_t pref_pd_max; 495 }; 496 497 /** @brief Turns an array of bt_codec_data to a flat LTV encoded uint8_t array 498 * 499 * The resulting @p buf array can then be used to send over air. 500 * 501 * @param codec_data The codec data. Can either be codec configuration data, 502 * or codec metadata. 503 * @param count The number of elements in the @p codec_data array 504 * @param buf The resulting buffer to put the LTV encoded data. 505 * @param buf_size The size of @p buf. 506 * 507 * @retval The length of the encoded data if successful. 508 * @retval -ENOMEM if the @p codec_data did not fit into the @p buf. 509 */ 510 ssize_t bt_audio_codec_data_to_buf(const struct bt_codec_data *codec_data, size_t count, 511 uint8_t *buf, size_t buf_size); 512 513 /** 514 * @brief Audio codec Config APIs 515 * @defgroup bt_audio_codec_cfg Codec config parsing APIs 516 * 517 * Functions to parse codec config data when formatted as LTV wrapped into @ref bt_codec. 518 * 519 * @{ 520 */ 521 522 /** 523 * @brief Codec parser error codes for @ref bt_audio_codec_cfg. 524 */ 525 enum bt_audio_codec_parse_err { 526 527 /** @brief The requested type is not present in the data set. */ 528 BT_AUDIO_CODEC_PARSE_ERR_SUCCESS = 0, 529 530 /** @brief The requested type is not present in the data set. */ 531 BT_AUDIO_CODEC_PARSE_ERR_TYPE_NOT_FOUND = -1, 532 533 /** @brief The value found is invalid. */ 534 BT_AUDIO_CODEC_PARSE_ERR_INVALID_VALUE_FOUND = -2, 535 536 /** @brief The parameters specified to the function call are not valid. */ 537 BT_AUDIO_CODEC_PARSE_ERR_INVALID_PARAM = -3, 538 }; 539 540 /**@brief Extract the frequency from a codec configuration. 541 * 542 * @param codec The codec configuration to extract data from. 543 * 544 * @return The frequency in Hz if found else a negative value of type 545 * @ref bt_audio_codec_parse_err. 546 */ 547 int bt_codec_cfg_get_freq(const struct bt_codec *codec); 548 549 /** @brief Extract frame duration from BT codec config 550 * 551 * @param codec The codec configuration to extract data from. 552 * 553 * @return Frame duration in microseconds if value is found else a negative value 554 * of type @ref bt_audio_codec_parse_err. 555 */ 556 int bt_codec_cfg_get_frame_duration_us(const struct bt_codec *codec); 557 558 /** @brief Extract channel allocation from BT codec config 559 * 560 * The value returned is a bit field representing one or more audio locations as 561 * specified by @ref bt_audio_location 562 * Shall match one or more of the bits set in BT_PAC_SNK_LOC/BT_PAC_SRC_LOC. 563 * 564 * Up to the configured @ref BT_CODEC_LC3_CHAN_COUNT number of channels can be present. 565 * 566 * @param codec The codec configuration to extract data from. 567 * @param chan_allocation Pointer to the variable to store the extracted value in. 568 * 569 * @return BT_AUDIO_CODEC_PARSE_SUCCESS if value is found and stored in the pointer provided 570 * else a negative value of type @ref bt_audio_codec_parse_err. 571 */ 572 int bt_codec_cfg_get_chan_allocation_val(const struct bt_codec *codec, 573 enum bt_audio_location *chan_allocation); 574 575 /** @brief Extract frame size in octets from BT codec config 576 * 577 * The overall SDU size will be octets_per_frame * blocks_per_sdu. 578 * 579 * The Bluetooth specificationa are not clear about this value - it does not state that 580 * the codec shall use this SDU size only. A codec like LC3 supports variable bit-rate 581 * (per SDU) hence it might be allowed for an encoder to reduce the frame size below this 582 * value. 583 * Hence it is recommended to use the received SDU size and divide by 584 * blocks_per_sdu rather than relying on this octets_per_sdu value to be fixed. 585 * 586 * @param codec The codec configuration to extract data from. 587 * 588 * @return Frame length in octets if value is found else a negative value 589 * of type @ref bt_audio_codec_parse_err. 590 */ 591 int bt_codec_cfg_get_octets_per_frame(const struct bt_codec *codec); 592 593 /** @brief Extract number of audio frame blockss in each SDU from BT codec config 594 * 595 * The overall SDU size will be octets_per_frame * frame_blocks_per_sdu * number-of-channels. 596 * 597 * If this value is not present a default value of 1 shall be used. 598 * 599 * A frame block is one or more frames that represents data for the same period of time but 600 * for different channels. If the stream have two audio channels and this value is two 601 * there will be four frames in the SDU. 602 * 603 * @param codec The codec configuration to extract data from. 604 * @param fallback_to_default If true this function will return the default value of 1 605 * if the type is not found. In this case the function will only fail if a NULL 606 * pointer is provided. 607 * 608 * @return The count of codec frames in each SDU if value is found else a negative value 609 * of type @ref bt_audio_codec_parse_err - unless when \p fallback_to_default is true 610 * then the value 1 is returned if frames per sdu is not found. 611 */ 612 int bt_codec_cfg_get_frame_blocks_per_sdu(const struct bt_codec *codec, bool fallback_to_default); 613 614 /** @brief Lookup a specific value based on type 615 * 616 * Depending on context bt_codec will be either codec capabilities, codec configuration or 617 * meta data. 618 * 619 * Typically types used are: 620 * @ref bt_codec_capability_type 621 * @ref bt_codec_config_type 622 * @ref bt_audio_metadata_type 623 * 624 * @param codec The codec data to search in. 625 * @param type The type id to look for 626 * @param data Pointer to the data-pointer to update when item is found 627 * @return True if the type is found, false otherwise. 628 */ 629 bool bt_codec_get_val(const struct bt_codec *codec, 630 uint8_t type, 631 const struct bt_codec_data **data); 632 633 /** @} */ /* End of bt_audio_codec_cfg */ 634 635 #ifdef __cplusplus 636 } 637 #endif 638 639 /** @} */ /* end of bt_audio */ 640 641 #endif /* ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_H_ */ 642
