1 /**
2 * @file
3 * @brief Bluetooth Audio handling
4 */
5
6 /*
7 * Copyright (c) 2020 Intel Corporation
8 * Copyright (c) 2020-2024 Nordic Semiconductor ASA
9 *
10 * SPDX-License-Identifier: Apache-2.0
11 */
12 #ifndef ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_AUDIO_H_
13 #define ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_AUDIO_H_
14
15 /**
16 * @brief Bluetooth Audio
17 * @defgroup bt_audio Bluetooth Audio
18 * @ingroup bluetooth
19 * @{
20 */
21
22 #include <stdbool.h>
23 #include <stddef.h>
24 #include <stdint.h>
25
26 #include <zephyr/autoconf.h>
27 #include <zephyr/bluetooth/audio/lc3.h>
28 #include <zephyr/bluetooth/bluetooth.h>
29 #include <zephyr/bluetooth/buf.h>
30 #include <zephyr/bluetooth/conn.h>
31 #include <zephyr/bluetooth/gatt.h>
32 #include <zephyr/bluetooth/hci.h>
33 #include <zephyr/bluetooth/iso.h>
34 #include <zephyr/sys/atomic.h>
35 #include <zephyr/sys/util.h>
36 #include <zephyr/sys/util_macro.h>
37
38 #ifdef __cplusplus
39 extern "C" {
40 #endif
41
42 /** Size of the broadcast ID in octets */
43 #define BT_AUDIO_BROADCAST_ID_SIZE 3
44 /** Maximum broadcast ID value */
45 #define BT_AUDIO_BROADCAST_ID_MAX 0xFFFFFFU
46 /** Indicates that the server have no preference for the presentation delay */
47 #define BT_AUDIO_PD_PREF_NONE 0x000000U
48 /** Maximum presentation delay in microseconds */
49 #define BT_AUDIO_PD_MAX 0xFFFFFFU
50 /** Indicates that the unicast server does not have a preference for any retransmission number */
51 #define BT_AUDIO_RTN_PREF_NONE 0xFFU
52 /** The minimum size of a Broadcast Name as defined by Bluetooth Assigned Numbers */
53 #define BT_AUDIO_BROADCAST_NAME_LEN_MIN 4
54 /** The maximum size of a Broadcast Name as defined by Bluetooth Assigned Numbers */
55 #define BT_AUDIO_BROADCAST_NAME_LEN_MAX 128
56
57 /** Size of the stream language value, e.g. "eng" */
58 #define BT_AUDIO_LANG_SIZE 3
59
60 /**
61 * @brief Codec capability types
62 *
63 * Used to build and parse codec capabilities as specified in the PAC specification.
64 * Source is assigned numbers for Generic Audio, bluetooth.com.
65 */
66 enum bt_audio_codec_cap_type {
67 /** Supported sampling frequencies */
68 BT_AUDIO_CODEC_CAP_TYPE_FREQ = 0x01,
69
70 /** Supported frame durations */
71 BT_AUDIO_CODEC_CAP_TYPE_DURATION = 0x02,
72
73 /** Supported audio channel counts */
74 BT_AUDIO_CODEC_CAP_TYPE_CHAN_COUNT = 0x03,
75
76 /** Supported octets per codec frame */
77 BT_AUDIO_CODEC_CAP_TYPE_FRAME_LEN = 0x04,
78
79 /** Supported maximum codec frames per SDU */
80 BT_AUDIO_CODEC_CAP_TYPE_FRAME_COUNT = 0x05,
81 };
82
83 /** @brief Supported frequencies bitfield */
84 enum bt_audio_codec_cap_freq {
85 /** 8 Khz sampling frequency */
86 BT_AUDIO_CODEC_CAP_FREQ_8KHZ = BIT(0),
87
88 /** 11.025 Khz sampling frequency */
89 BT_AUDIO_CODEC_CAP_FREQ_11KHZ = BIT(1),
90
91 /** 16 Khz sampling frequency */
92 BT_AUDIO_CODEC_CAP_FREQ_16KHZ = BIT(2),
93
94 /** 22.05 Khz sampling frequency */
95 BT_AUDIO_CODEC_CAP_FREQ_22KHZ = BIT(3),
96
97 /** 24 Khz sampling frequency */
98 BT_AUDIO_CODEC_CAP_FREQ_24KHZ = BIT(4),
99
100 /** 32 Khz sampling frequency */
101 BT_AUDIO_CODEC_CAP_FREQ_32KHZ = BIT(5),
102
103 /** 44.1 Khz sampling frequency */
104 BT_AUDIO_CODEC_CAP_FREQ_44KHZ = BIT(6),
105
106 /** 48 Khz sampling frequency */
107 BT_AUDIO_CODEC_CAP_FREQ_48KHZ = BIT(7),
108
109 /** 88.2 Khz sampling frequency */
110 BT_AUDIO_CODEC_CAP_FREQ_88KHZ = BIT(8),
111
112 /** 96 Khz sampling frequency */
113 BT_AUDIO_CODEC_CAP_FREQ_96KHZ = BIT(9),
114
115 /** 176.4 Khz sampling frequency */
116 BT_AUDIO_CODEC_CAP_FREQ_176KHZ = BIT(10),
117
118 /** 192 Khz sampling frequency */
119 BT_AUDIO_CODEC_CAP_FREQ_192KHZ = BIT(11),
120
121 /** 384 Khz sampling frequency */
122 BT_AUDIO_CODEC_CAP_FREQ_384KHZ = BIT(12),
123
124 /** Any frequency capability */
125 BT_AUDIO_CODEC_CAP_FREQ_ANY =
126 (BT_AUDIO_CODEC_CAP_FREQ_8KHZ | BT_AUDIO_CODEC_CAP_FREQ_11KHZ |
127 BT_AUDIO_CODEC_CAP_FREQ_16KHZ | BT_AUDIO_CODEC_CAP_FREQ_22KHZ |
128 BT_AUDIO_CODEC_CAP_FREQ_24KHZ | BT_AUDIO_CODEC_CAP_FREQ_32KHZ |
129 BT_AUDIO_CODEC_CAP_FREQ_44KHZ | BT_AUDIO_CODEC_CAP_FREQ_48KHZ |
130 BT_AUDIO_CODEC_CAP_FREQ_88KHZ | BT_AUDIO_CODEC_CAP_FREQ_96KHZ |
131 BT_AUDIO_CODEC_CAP_FREQ_176KHZ | BT_AUDIO_CODEC_CAP_FREQ_192KHZ |
132 BT_AUDIO_CODEC_CAP_FREQ_384KHZ),
133 };
134
135 /** @brief Supported frame durations bitfield */
136 enum bt_audio_codec_cap_frame_dur {
137 /** 7.5 msec frame duration capability */
138 BT_AUDIO_CODEC_CAP_DURATION_7_5 = BIT(0),
139
140 /** 10 msec frame duration capability */
141 BT_AUDIO_CODEC_CAP_DURATION_10 = BIT(1),
142
143 /** Any frame duration capability */
144 BT_AUDIO_CODEC_CAP_DURATION_ANY =
145 (BT_AUDIO_CODEC_CAP_DURATION_7_5 | BT_AUDIO_CODEC_CAP_DURATION_10),
146
147 /**
148 * @brief 7.5 msec preferred frame duration capability.
149 *
150 * This shall only be set if @ref BT_AUDIO_CODEC_CAP_DURATION_7_5 is also set, and if @ref
151 * BT_AUDIO_CODEC_CAP_DURATION_PREFER_10 is not set.
152 */
153 BT_AUDIO_CODEC_CAP_DURATION_PREFER_7_5 = BIT(4),
154
155 /**
156 * @brief 10 msec preferred frame duration capability
157 *
158 * This shall only be set if @ref BT_AUDIO_CODEC_CAP_DURATION_10 is also set, and if @ref
159 * BT_AUDIO_CODEC_CAP_DURATION_PREFER_7_5 is not set.
160 */
161 BT_AUDIO_CODEC_CAP_DURATION_PREFER_10 = BIT(5),
162 };
163
164 /** Supported audio capabilities channel count bitfield */
165 enum bt_audio_codec_cap_chan_count {
166 /** Supporting 1 channel */
167 BT_AUDIO_CODEC_CAP_CHAN_COUNT_1 = BIT(0),
168
169 /** Supporting 2 channel */
170 BT_AUDIO_CODEC_CAP_CHAN_COUNT_2 = BIT(1),
171
172 /** Supporting 3 channel */
173 BT_AUDIO_CODEC_CAP_CHAN_COUNT_3 = BIT(2),
174
175 /** Supporting 4 channel */
176 BT_AUDIO_CODEC_CAP_CHAN_COUNT_4 = BIT(3),
177
178 /** Supporting 5 channel */
179 BT_AUDIO_CODEC_CAP_CHAN_COUNT_5 = BIT(4),
180
181 /** Supporting 6 channel */
182 BT_AUDIO_CODEC_CAP_CHAN_COUNT_6 = BIT(5),
183
184 /** Supporting 7 channel */
185 BT_AUDIO_CODEC_CAP_CHAN_COUNT_7 = BIT(6),
186
187 /** Supporting 8 channel */
188 BT_AUDIO_CODEC_CAP_CHAN_COUNT_8 = BIT(7),
189
190 /** Supporting all channels */
191 BT_AUDIO_CODEC_CAP_CHAN_COUNT_ANY =
192 (BT_AUDIO_CODEC_CAP_CHAN_COUNT_1 | BT_AUDIO_CODEC_CAP_CHAN_COUNT_2 |
193 BT_AUDIO_CODEC_CAP_CHAN_COUNT_3 | BT_AUDIO_CODEC_CAP_CHAN_COUNT_4 |
194 BT_AUDIO_CODEC_CAP_CHAN_COUNT_5 | BT_AUDIO_CODEC_CAP_CHAN_COUNT_6 |
195 BT_AUDIO_CODEC_CAP_CHAN_COUNT_7 | BT_AUDIO_CODEC_CAP_CHAN_COUNT_8),
196 };
197
198 /** Minimum supported channel counts */
199 #define BT_AUDIO_CODEC_CAP_CHAN_COUNT_MIN 1
200 /** Maximum supported channel counts */
201 #define BT_AUDIO_CODEC_CAP_CHAN_COUNT_MAX 8
202
203 /**
204 * @brief Channel count support capability
205 *
206 * Macro accepts variable number of channel counts.
207 * The allowed channel counts are defined by specification and have to be in range from
208 * @ref BT_AUDIO_CODEC_CAP_CHAN_COUNT_MIN to @ref BT_AUDIO_CODEC_CAP_CHAN_COUNT_MAX inclusive.
209 *
210 * Example to support 1 and 3 channels:
211 * BT_AUDIO_CODEC_CAP_CHAN_COUNT_SUPPORT(1, 3)
212 */
213 #define BT_AUDIO_CODEC_CAP_CHAN_COUNT_SUPPORT(...) \
214 ((enum bt_audio_codec_cap_chan_count)((FOR_EACH(BIT, (|), __VA_ARGS__)) >> 1))
215
216 /** struct to hold minimum and maximum supported codec frame sizes */
217 struct bt_audio_codec_octets_per_codec_frame {
218 /** Minimum number of octets supported per codec frame */
219 uint16_t min;
220 /** Maximum number of octets supported per codec frame */
221 uint16_t max;
222 };
223
224 /**
225 * @brief Codec configuration types
226 *
227 * Used to build and parse codec configurations as specified in the ASCS and BAP specifications.
228 * Source is assigned numbers for Generic Audio, bluetooth.com.
229 */
230 enum bt_audio_codec_cfg_type {
231 /** Sampling frequency */
232 BT_AUDIO_CODEC_CFG_FREQ = 0x01,
233
234 /** Frame duration */
235 BT_AUDIO_CODEC_CFG_DURATION = 0x02,
236
237 /** Audio channel allocation */
238 BT_AUDIO_CODEC_CFG_CHAN_ALLOC = 0x03,
239
240 /** Octets per codec frame */
241 BT_AUDIO_CODEC_CFG_FRAME_LEN = 0x04,
242
243 /** Codec frame blocks per SDU */
244 BT_AUDIO_CODEC_CFG_FRAME_BLKS_PER_SDU = 0x05,
245 };
246
247 /** Codec configuration sampling freqency */
248 enum bt_audio_codec_cfg_freq {
249 /** 8 Khz codec sampling frequency */
250 BT_AUDIO_CODEC_CFG_FREQ_8KHZ = 0x01,
251
252 /** 11.025 Khz codec sampling frequency */
253 BT_AUDIO_CODEC_CFG_FREQ_11KHZ = 0x02,
254
255 /** 16 Khz codec sampling frequency */
256 BT_AUDIO_CODEC_CFG_FREQ_16KHZ = 0x03,
257
258 /** 22.05 Khz codec sampling frequency */
259 BT_AUDIO_CODEC_CFG_FREQ_22KHZ = 0x04,
260
261 /** 24 Khz codec sampling frequency */
262 BT_AUDIO_CODEC_CFG_FREQ_24KHZ = 0x05,
263
264 /** 32 Khz codec sampling frequency */
265 BT_AUDIO_CODEC_CFG_FREQ_32KHZ = 0x06,
266
267 /** 44.1 Khz codec sampling frequency */
268 BT_AUDIO_CODEC_CFG_FREQ_44KHZ = 0x07,
269
270 /** 48 Khz codec sampling frequency */
271 BT_AUDIO_CODEC_CFG_FREQ_48KHZ = 0x08,
272
273 /** 88.2 Khz codec sampling frequency */
274 BT_AUDIO_CODEC_CFG_FREQ_88KHZ = 0x09,
275
276 /** 96 Khz codec sampling frequency */
277 BT_AUDIO_CODEC_CFG_FREQ_96KHZ = 0x0a,
278
279 /** 176.4 Khz codec sampling frequency */
280 BT_AUDIO_CODEC_CFG_FREQ_176KHZ = 0x0b,
281
282 /** 192 Khz codec sampling frequency */
283 BT_AUDIO_CODEC_CFG_FREQ_192KHZ = 0x0c,
284
285 /** 384 Khz codec sampling frequency */
286 BT_AUDIO_CODEC_CFG_FREQ_384KHZ = 0x0d,
287 };
288
289 /** Codec configuration frame duration */
290 enum bt_audio_codec_cfg_frame_dur {
291 /** 7.5 msec Frame Duration configuration */
292 BT_AUDIO_CODEC_CFG_DURATION_7_5 = 0x00,
293
294 /** 10 msec Frame Duration configuration */
295 BT_AUDIO_CODEC_CFG_DURATION_10 = 0x01,
296 };
297
298 /**
299 * @brief Audio Context Type for Generic Audio
300 *
301 * These values are defined by the Generic Audio Assigned Numbers, bluetooth.com
302 */
303 enum bt_audio_context {
304 /** Prohibited */
305 BT_AUDIO_CONTEXT_TYPE_PROHIBITED = 0,
306 /**
307 * Identifies audio where the use case context does not match any other defined value,
308 * or where the context is unknown or cannot be determined.
309 */
310 BT_AUDIO_CONTEXT_TYPE_UNSPECIFIED = BIT(0),
311 /**
312 * Conversation between humans, for example, in telephony or video calls, including
313 * traditional cellular as well as VoIP and Push-to-Talk
314 */
315 BT_AUDIO_CONTEXT_TYPE_CONVERSATIONAL = BIT(1),
316 /** Media, for example, music playback, radio, podcast or movie soundtrack, or tv audio */
317 BT_AUDIO_CONTEXT_TYPE_MEDIA = BIT(2),
318 /**
319 * Audio associated with video gaming, for example gaming media; gaming effects; music
320 * and in-game voice chat between participants; or a mix of all the above
321 */
322 BT_AUDIO_CONTEXT_TYPE_GAME = BIT(3),
323 /** Instructional audio, for example, in navigation, announcements, or user guidance */
324 BT_AUDIO_CONTEXT_TYPE_INSTRUCTIONAL = BIT(4),
325 /** Man-machine communication, for example, with voice recognition or virtual assistants */
326 BT_AUDIO_CONTEXT_TYPE_VOICE_ASSISTANTS = BIT(5),
327 /**
328 * Live audio, for example, from a microphone where audio is perceived both through a
329 * direct acoustic path and through an LE Audio Stream
330 */
331 BT_AUDIO_CONTEXT_TYPE_LIVE = BIT(6),
332 /**
333 * Sound effects including keyboard and touch feedback; menu and user interface sounds;
334 * and other system sounds
335 */
336 BT_AUDIO_CONTEXT_TYPE_SOUND_EFFECTS = BIT(7),
337 /**
338 * Notification and reminder sounds; attention-seeking audio, for example,
339 * in beeps signaling the arrival of a message
340 */
341 BT_AUDIO_CONTEXT_TYPE_NOTIFICATIONS = BIT(8),
342 /**
343 * Alerts the user to an incoming call, for example, an incoming telephony or video call,
344 * including traditional cellular as well as VoIP and Push-to-Talk
345 */
346 BT_AUDIO_CONTEXT_TYPE_RINGTONE = BIT(9),
347 /**
348 * Alarms and timers; immediate alerts, for example, in a critical battery alarm,
349 * timer expiry or alarm clock, toaster, cooker, kettle, microwave, etc.
350 */
351 BT_AUDIO_CONTEXT_TYPE_ALERTS = BIT(10),
352 /** Emergency alarm Emergency sounds, for example, fire alarms or other urgent alerts */
353 BT_AUDIO_CONTEXT_TYPE_EMERGENCY_ALARM = BIT(11),
354 };
355
356 /**
357 * Any known context.
358 */
359 #define BT_AUDIO_CONTEXT_TYPE_ANY (BT_AUDIO_CONTEXT_TYPE_UNSPECIFIED | \
360 BT_AUDIO_CONTEXT_TYPE_CONVERSATIONAL | \
361 BT_AUDIO_CONTEXT_TYPE_MEDIA | \
362 BT_AUDIO_CONTEXT_TYPE_GAME | \
363 BT_AUDIO_CONTEXT_TYPE_INSTRUCTIONAL | \
364 BT_AUDIO_CONTEXT_TYPE_VOICE_ASSISTANTS | \
365 BT_AUDIO_CONTEXT_TYPE_LIVE | \
366 BT_AUDIO_CONTEXT_TYPE_SOUND_EFFECTS | \
367 BT_AUDIO_CONTEXT_TYPE_NOTIFICATIONS | \
368 BT_AUDIO_CONTEXT_TYPE_RINGTONE | \
369 BT_AUDIO_CONTEXT_TYPE_ALERTS | \
370 BT_AUDIO_CONTEXT_TYPE_EMERGENCY_ALARM)
371
372 /**
373 * @brief Parental rating defined by the Generic Audio assigned numbers (bluetooth.com).
374 *
375 * The numbering scheme is aligned with Annex F of EN 300 707 v1.2.1 which
376 * defined parental rating for viewing.
377 */
378 enum bt_audio_parental_rating {
379 /** No rating */
380 BT_AUDIO_PARENTAL_RATING_NO_RATING = 0x00,
381 /** For all ages */
382 BT_AUDIO_PARENTAL_RATING_AGE_ANY = 0x01,
383 /** Recommended for listeners of age 5 and above */
384 BT_AUDIO_PARENTAL_RATING_AGE_5_OR_ABOVE = 0x02,
385 /** Recommended for listeners of age 6 and above */
386 BT_AUDIO_PARENTAL_RATING_AGE_6_OR_ABOVE = 0x03,
387 /** Recommended for listeners of age 7 and above */
388 BT_AUDIO_PARENTAL_RATING_AGE_7_OR_ABOVE = 0x04,
389 /** Recommended for listeners of age 8 and above */
390 BT_AUDIO_PARENTAL_RATING_AGE_8_OR_ABOVE = 0x05,
391 /** Recommended for listeners of age 9 and above */
392 BT_AUDIO_PARENTAL_RATING_AGE_9_OR_ABOVE = 0x06,
393 /** Recommended for listeners of age 10 and above */
394 BT_AUDIO_PARENTAL_RATING_AGE_10_OR_ABOVE = 0x07,
395 /** Recommended for listeners of age 11 and above */
396 BT_AUDIO_PARENTAL_RATING_AGE_11_OR_ABOVE = 0x08,
397 /** Recommended for listeners of age 12 and above */
398 BT_AUDIO_PARENTAL_RATING_AGE_12_OR_ABOVE = 0x09,
399 /** Recommended for listeners of age 13 and above */
400 BT_AUDIO_PARENTAL_RATING_AGE_13_OR_ABOVE = 0x0A,
401 /** Recommended for listeners of age 14 and above */
402 BT_AUDIO_PARENTAL_RATING_AGE_14_OR_ABOVE = 0x0B,
403 /** Recommended for listeners of age 15 and above */
404 BT_AUDIO_PARENTAL_RATING_AGE_15_OR_ABOVE = 0x0C,
405 /** Recommended for listeners of age 16 and above */
406 BT_AUDIO_PARENTAL_RATING_AGE_16_OR_ABOVE = 0x0D,
407 /** Recommended for listeners of age 17 and above */
408 BT_AUDIO_PARENTAL_RATING_AGE_17_OR_ABOVE = 0x0E,
409 /** Recommended for listeners of age 18 and above */
410 BT_AUDIO_PARENTAL_RATING_AGE_18_OR_ABOVE = 0x0F
411 };
412
413 /** @brief Audio Active State defined by the Generic Audio assigned numbers (bluetooth.com). */
414 enum bt_audio_active_state {
415 /** No audio data is being transmitted */
416 BT_AUDIO_ACTIVE_STATE_DISABLED = 0x00,
417 /** Audio data is being transmitted */
418 BT_AUDIO_ACTIVE_STATE_ENABLED = 0x01,
419 };
420
421 /** Assisted Listening Stream defined by the Generic Audio assigned numbers (bluetooth.com). */
422 enum bt_audio_assisted_listening_stream {
423 /** Unspecified audio enhancement */
424 BT_AUDIO_ASSISTED_LISTENING_STREAM_UNSPECIFIED = 0x00,
425 };
426
427 /**
428 * @brief Codec metadata type IDs
429 *
430 * Metadata types defined by the Generic Audio assigned numbers (bluetooth.com).
431 */
432 enum bt_audio_metadata_type {
433 /**
434 * @brief Preferred audio context.
435 *
436 * Bitfield of preferred audio contexts.
437 *
438 * If 0, the context type is not a preferred use case for this codec
439 * configuration.
440 *
441 * See the BT_AUDIO_CONTEXT_* for valid values.
442 */
443 BT_AUDIO_METADATA_TYPE_PREF_CONTEXT = 0x01,
444
445 /**
446 * @brief Streaming audio context.
447 *
448 * Bitfield of streaming audio contexts.
449 *
450 * If 0, the context type is not a preferred use case for this codec
451 * configuration.
452 *
453 * See the BT_AUDIO_CONTEXT_* for valid values.
454 */
455 BT_AUDIO_METADATA_TYPE_STREAM_CONTEXT = 0x02,
456
457 /** UTF-8 encoded title or summary of stream content */
458 BT_AUDIO_METADATA_TYPE_PROGRAM_INFO = 0x03,
459
460 /**
461 * @brief Language
462 *
463 * 3 octet lower case language code defined by ISO 639-3
464 * Possible values can be found at https://iso639-3.sil.org/code_tables/639/data
465 */
466 BT_AUDIO_METADATA_TYPE_LANG = 0x04,
467
468 /** Array of 8-bit CCID values */
469 BT_AUDIO_METADATA_TYPE_CCID_LIST = 0x05,
470
471 /**
472 * @brief Parental rating
473 *
474 * See @ref bt_audio_parental_rating for valid values.
475 */
476 BT_AUDIO_METADATA_TYPE_PARENTAL_RATING = 0x06,
477
478 /** UTF-8 encoded URI for additional Program information */
479 BT_AUDIO_METADATA_TYPE_PROGRAM_INFO_URI = 0x07,
480
481 /**
482 * @brief Audio active state
483 *
484 * See @ref bt_audio_active_state for valid values.
485 */
486 BT_AUDIO_METADATA_TYPE_AUDIO_STATE = 0x08,
487
488 /** Broadcast Audio Immediate Rendering flag */
489 BT_AUDIO_METADATA_TYPE_BROADCAST_IMMEDIATE = 0x09,
490
491 /**
492 * @brief Assisted listening stream
493 *
494 * See @ref bt_audio_assisted_listening_stream for valid values.
495 */
496 BT_AUDIO_METADATA_TYPE_ASSISTED_LISTENING_STREAM = 0x0A,
497
498 /** UTF-8 encoded Broadcast name */
499 BT_AUDIO_METADATA_TYPE_BROADCAST_NAME = 0x0B,
500
501 /** Extended metadata */
502 BT_AUDIO_METADATA_TYPE_EXTENDED = 0xFE,
503
504 /** Vendor specific metadata */
505 BT_AUDIO_METADATA_TYPE_VENDOR = 0xFF,
506 };
507
508 /**
509 * @brief Helper to check whether metadata type is known by the stack.
510 *
511 * @note @p _type is evaluated thrice.
512 */
513 #define BT_AUDIO_METADATA_TYPE_IS_KNOWN(_type) \
514 (IN_RANGE((_type), BT_AUDIO_METADATA_TYPE_PREF_CONTEXT, \
515 BT_AUDIO_METADATA_TYPE_BROADCAST_IMMEDIATE) || \
516 (_type) == BT_AUDIO_METADATA_TYPE_EXTENDED || (_type) == BT_AUDIO_METADATA_TYPE_VENDOR)
517
518 /**
519 * @name Unicast Announcement Type
520 * @{
521 */
522 /** Unicast Server is connectable and is requesting a connection. */
523 #define BT_AUDIO_UNICAST_ANNOUNCEMENT_GENERAL 0x00
524 /** Unicast Server is connectable but is not requesting a connection. */
525 #define BT_AUDIO_UNICAST_ANNOUNCEMENT_TARGETED 0x01
526 /** @} */
527
528 /**
529 * @brief Helper to declare elements of bt_audio_codec_cap arrays
530 *
531 * This macro is mainly for creating an array of struct bt_audio_codec_cap data arrays.
532 *
533 * @param _type Type of advertising data field
534 * @param _bytes Variable number of single-byte parameters
535 */
536 #define BT_AUDIO_CODEC_DATA(_type, _bytes...) \
537 (sizeof((uint8_t)_type) + sizeof((uint8_t[]){_bytes})), (_type), _bytes
538
539 /**
540 * @brief Helper to declare @ref bt_audio_codec_cfg
541 *
542 * @param _id Codec ID
543 * @param _cid Company ID
544 * @param _vid Vendor ID
545 * @param _data Codec Specific Data in LVT format
546 * @param _meta Codec Specific Metadata in LVT format
547 */
548 #define BT_AUDIO_CODEC_CFG(_id, _cid, _vid, _data, _meta) \
549 ((struct bt_audio_codec_cfg){ \
550 /* Use HCI data path as default, can be overwritten by application */ \
551 .path_id = BT_ISO_DATA_PATH_HCI, \
552 .ctlr_transcode = false, \
553 .id = _id, \
554 .cid = _cid, \
555 .vid = _vid, \
556 .data_len = sizeof((uint8_t[])_data), \
557 .data = _data, \
558 .meta_len = sizeof((uint8_t[])_meta), \
559 .meta = _meta, \
560 })
561
562 /**
563 * @brief Helper to declare @ref bt_audio_codec_cap structure
564 *
565 * @param _id Codec ID
566 * @param _cid Company ID
567 * @param _vid Vendor ID
568 * @param _data Codec Specific Data in LVT format
569 * @param _meta Codec Specific Metadata in LVT format
570 */
571 #define BT_AUDIO_CODEC_CAP(_id, _cid, _vid, _data, _meta) \
572 ((struct bt_audio_codec_cap){ \
573 /* Use HCI data path as default, can be overwritten by application */ \
574 .path_id = BT_ISO_DATA_PATH_HCI, \
575 .ctlr_transcode = false, \
576 .id = (_id), \
577 .cid = (_cid), \
578 .vid = (_vid), \
579 .data_len = sizeof((uint8_t[])_data), \
580 .data = _data, \
581 .meta_len = sizeof((uint8_t[])_meta), \
582 .meta = _meta, \
583 })
584
585 /**
586 * @brief Location values for BT Audio.
587 *
588 * These values are defined by the Generic Audio Assigned Numbers, bluetooth.com
589 */
590 enum bt_audio_location {
591 /** Mono Audio (no specified Audio Location) */
592 BT_AUDIO_LOCATION_MONO_AUDIO = 0,
593 /** Front Left */
594 BT_AUDIO_LOCATION_FRONT_LEFT = BIT(0),
595 /** Front Right */
596 BT_AUDIO_LOCATION_FRONT_RIGHT = BIT(1),
597 /** Front Center */
598 BT_AUDIO_LOCATION_FRONT_CENTER = BIT(2),
599 /** Low Frequency Effects 1 */
600 BT_AUDIO_LOCATION_LOW_FREQ_EFFECTS_1 = BIT(3),
601 /** Back Left */
602 BT_AUDIO_LOCATION_BACK_LEFT = BIT(4),
603 /** Back Right */
604 BT_AUDIO_LOCATION_BACK_RIGHT = BIT(5),
605 /** Front Left of Center */
606 BT_AUDIO_LOCATION_FRONT_LEFT_OF_CENTER = BIT(6),
607 /** Front Right of Center */
608 BT_AUDIO_LOCATION_FRONT_RIGHT_OF_CENTER = BIT(7),
609 /** Back Center */
610 BT_AUDIO_LOCATION_BACK_CENTER = BIT(8),
611 /** Low Frequency Effects 2 */
612 BT_AUDIO_LOCATION_LOW_FREQ_EFFECTS_2 = BIT(9),
613 /** Side Left */
614 BT_AUDIO_LOCATION_SIDE_LEFT = BIT(10),
615 /** Side Right */
616 BT_AUDIO_LOCATION_SIDE_RIGHT = BIT(11),
617 /** Top Front Left */
618 BT_AUDIO_LOCATION_TOP_FRONT_LEFT = BIT(12),
619 /** Top Front Right */
620 BT_AUDIO_LOCATION_TOP_FRONT_RIGHT = BIT(13),
621 /** Top Front Center */
622 BT_AUDIO_LOCATION_TOP_FRONT_CENTER = BIT(14),
623 /** Top Center */
624 BT_AUDIO_LOCATION_TOP_CENTER = BIT(15),
625 /** Top Back Left */
626 BT_AUDIO_LOCATION_TOP_BACK_LEFT = BIT(16),
627 /** Top Back Right */
628 BT_AUDIO_LOCATION_TOP_BACK_RIGHT = BIT(17),
629 /** Top Side Left */
630 BT_AUDIO_LOCATION_TOP_SIDE_LEFT = BIT(18),
631 /** Top Side Right */
632 BT_AUDIO_LOCATION_TOP_SIDE_RIGHT = BIT(19),
633 /** Top Back Center */
634 BT_AUDIO_LOCATION_TOP_BACK_CENTER = BIT(20),
635 /** Bottom Front Center */
636 BT_AUDIO_LOCATION_BOTTOM_FRONT_CENTER = BIT(21),
637 /** Bottom Front Left */
638 BT_AUDIO_LOCATION_BOTTOM_FRONT_LEFT = BIT(22),
639 /** Bottom Front Right */
640 BT_AUDIO_LOCATION_BOTTOM_FRONT_RIGHT = BIT(23),
641 /** Front Left Wide */
642 BT_AUDIO_LOCATION_FRONT_LEFT_WIDE = BIT(24),
643 /** Front Right Wide */
644 BT_AUDIO_LOCATION_FRONT_RIGHT_WIDE = BIT(25),
645 /** Left Surround */
646 BT_AUDIO_LOCATION_LEFT_SURROUND = BIT(26),
647 /** Right Surround */
648 BT_AUDIO_LOCATION_RIGHT_SURROUND = BIT(27),
649 };
650
651 /**
652 * Any known location.
653 */
654 #define BT_AUDIO_LOCATION_ANY (BT_AUDIO_LOCATION_FRONT_LEFT | \
655 BT_AUDIO_LOCATION_FRONT_RIGHT | \
656 BT_AUDIO_LOCATION_FRONT_CENTER | \
657 BT_AUDIO_LOCATION_LOW_FREQ_EFFECTS_1 | \
658 BT_AUDIO_LOCATION_BACK_LEFT | \
659 BT_AUDIO_LOCATION_BACK_RIGHT | \
660 BT_AUDIO_LOCATION_FRONT_LEFT_OF_CENTER | \
661 BT_AUDIO_LOCATION_FRONT_RIGHT_OF_CENTER | \
662 BT_AUDIO_LOCATION_BACK_CENTER | \
663 BT_AUDIO_LOCATION_LOW_FREQ_EFFECTS_2 | \
664 BT_AUDIO_LOCATION_SIDE_LEFT | \
665 BT_AUDIO_LOCATION_SIDE_RIGHT | \
666 BT_AUDIO_LOCATION_TOP_FRONT_LEFT | \
667 BT_AUDIO_LOCATION_TOP_FRONT_RIGHT | \
668 BT_AUDIO_LOCATION_TOP_FRONT_CENTER | \
669 BT_AUDIO_LOCATION_TOP_CENTER | \
670 BT_AUDIO_LOCATION_TOP_BACK_LEFT | \
671 BT_AUDIO_LOCATION_TOP_BACK_RIGHT | \
672 BT_AUDIO_LOCATION_TOP_SIDE_LEFT | \
673 BT_AUDIO_LOCATION_TOP_SIDE_RIGHT | \
674 BT_AUDIO_LOCATION_TOP_BACK_CENTER | \
675 BT_AUDIO_LOCATION_BOTTOM_FRONT_CENTER | \
676 BT_AUDIO_LOCATION_BOTTOM_FRONT_LEFT | \
677 BT_AUDIO_LOCATION_BOTTOM_FRONT_RIGHT | \
678 BT_AUDIO_LOCATION_FRONT_LEFT_WIDE | \
679 BT_AUDIO_LOCATION_FRONT_RIGHT_WIDE | \
680 BT_AUDIO_LOCATION_LEFT_SURROUND | \
681 BT_AUDIO_LOCATION_RIGHT_SURROUND)
682
683 /** @brief Codec capability structure. */
684 struct bt_audio_codec_cap {
685 /** Data path ID
686 *
687 * @ref BT_ISO_DATA_PATH_HCI for HCI path, or any other value for
688 * vendor specific ID.
689 */
690 uint8_t path_id;
691 /** Whether or not the local controller should transcode
692 *
693 * This effectively sets the coding format for the ISO data path to @ref
694 * BT_HCI_CODING_FORMAT_TRANSPARENT if false, else uses the @ref bt_audio_codec_cfg.id.
695 */
696 bool ctlr_transcode;
697 /** Codec ID */
698 uint8_t id;
699 /** Codec Company ID */
700 uint16_t cid;
701 /** Codec Company Vendor ID */
702 uint16_t vid;
703 #if CONFIG_BT_AUDIO_CODEC_CAP_MAX_DATA_SIZE > 0 || defined(__DOXYGEN__)
704 /** Codec Specific Capabilities Data count */
705 size_t data_len;
706 /** Codec Specific Capabilities Data */
707 uint8_t data[CONFIG_BT_AUDIO_CODEC_CAP_MAX_DATA_SIZE];
708 #endif /* CONFIG_BT_AUDIO_CODEC_CAP_MAX_DATA_SIZE > 0 */
709 #if defined(CONFIG_BT_AUDIO_CODEC_CAP_MAX_METADATA_SIZE) || defined(__DOXYGEN__)
710 /** Codec Specific Capabilities Metadata count */
711 size_t meta_len;
712 /** Codec Specific Capabilities Metadata */
713 uint8_t meta[CONFIG_BT_AUDIO_CODEC_CAP_MAX_METADATA_SIZE];
714 #endif /* CONFIG_BT_AUDIO_CODEC_CAP_MAX_METADATA_SIZE */
715 };
716
717 /** @brief Codec specific configuration structure. */
718 struct bt_audio_codec_cfg {
719 /** Data path ID
720 *
721 * @ref BT_ISO_DATA_PATH_HCI for HCI path, or any other value for
722 * vendor specific ID.
723 */
724 uint8_t path_id;
725 /** Whether or not the local controller should transcode
726 *
727 * This effectively sets the coding format for the ISO data path to @ref
728 * BT_HCI_CODING_FORMAT_TRANSPARENT if false, else uses the @ref bt_audio_codec_cfg.id.
729 */
730 bool ctlr_transcode;
731 /** Codec ID */
732 uint8_t id;
733 /** Codec Company ID */
734 uint16_t cid;
735 /** Codec Company Vendor ID */
736 uint16_t vid;
737 #if CONFIG_BT_AUDIO_CODEC_CFG_MAX_DATA_SIZE > 0 || defined(__DOXYGEN__)
738 /** Codec Specific Capabilities Data count */
739 size_t data_len;
740 /** Codec Specific Capabilities Data */
741 uint8_t data[CONFIG_BT_AUDIO_CODEC_CFG_MAX_DATA_SIZE];
742 #endif /* CONFIG_BT_AUDIO_CODEC_CFG_MAX_DATA_SIZE > 0 */
743 #if CONFIG_BT_AUDIO_CODEC_CFG_MAX_METADATA_SIZE > 0 || defined(__DOXYGEN__)
744 /** Codec Specific Capabilities Metadata count */
745 size_t meta_len;
746 /** Codec Specific Capabilities Metadata */
747 uint8_t meta[CONFIG_BT_AUDIO_CODEC_CFG_MAX_METADATA_SIZE];
748 #endif /* CONFIG_BT_AUDIO_CODEC_CFG_MAX_METADATA_SIZE > 0 */
749 };
750
751 /**
752 * @brief Helper for parsing length-type-value data.
753 *
754 * @param ltv Length-type-value (LTV) encoded data.
755 * @param size Size of the @p ltv data.
756 * @param func Callback function which will be called for each element
757 * that's found in the data. The callback should return
758 * true to continue parsing, or false to stop parsing.
759 * @param user_data User data to be passed to the callback.
760 *
761 * @retval 0 All entries were parsed.
762 * @retval -EINVAL The data is incorrectly encoded
763 * @retval -ECANCELED Parsing was prematurely cancelled by the callback
764 */
765 int bt_audio_data_parse(const uint8_t ltv[], size_t size,
766 bool (*func)(struct bt_data *data, void *user_data), void *user_data);
767
768 /**
769 * @brief Get the value of a specific data type in an length-type-value data array
770 *
771 * @param[in] ltv_data The array containing the length-type-value tuples
772 * @param[in] size The size of @p ltv_data
773 * @param[in] type The type to get the value for. May be any type, but typically either
774 * @ref bt_audio_codec_cap_type, @ref bt_audio_codec_cfg_type or
775 * @ref bt_audio_metadata_type.
776 * @param[out] data Pointer to the data-pointer to update when item is found.
777 * Any found data will be little endian.
778 *
779 * @retval length The length of found @p data (may be 0).
780 * @retval -EINVAL Arguments are invalid
781 * @retval -ENODATA Data not found
782 */
783 int bt_audio_data_get_val(const uint8_t ltv_data[], size_t size, uint8_t type,
784 const uint8_t **data);
785
786 /**
787 * @brief Function to get the number of channels from the channel allocation
788 *
789 * @param chan_allocation The channel allocation
790 *
791 * @return The number of channels
792 */
793 uint8_t bt_audio_get_chan_count(enum bt_audio_location chan_allocation);
794
795 /** @brief Audio direction from the perspective of the BAP Unicast Server / BAP Broadcast Sink */
796 enum bt_audio_dir {
797 /**
798 * @brief Audio direction sink
799 *
800 * For a BAP Unicast Client or Broadcast Source this is considered outgoing audio (TX).
801 * For a BAP Unicast Server or Broadcast Sink this is considered incoming audio (RX).
802 */
803 BT_AUDIO_DIR_SINK = 0x01,
804 /**
805 * @brief Audio direction source
806 *
807 * For a BAP Unicast Client or Broadcast Source this is considered incoming audio (RX).
808 * For a BAP Unicast Server or Broadcast Sink this is considered outgoing audio (TX).
809 */
810 BT_AUDIO_DIR_SOURCE = 0x02,
811 };
812
813 /**
814 * @brief Audio codec Config APIs
815 * @defgroup bt_audio_codec_cfg Codec config parsing APIs
816 *
817 * Functions to parse codec config data when formatted as LTV wrapped into @ref bt_audio_codec_cfg.
818 *
819 * @{
820 */
821
822 /**
823 * @brief Convert assigned numbers frequency to frequency value.
824 *
825 * @param freq The assigned numbers frequency to convert.
826 *
827 * @retval frequency The converted frequency value in Hz.
828 * @retval -EINVAL Arguments are invalid.
829 */
830 int bt_audio_codec_cfg_freq_to_freq_hz(enum bt_audio_codec_cfg_freq freq);
831
832 /**
833 * @brief Convert frequency value to assigned numbers frequency.
834 *
835 * @param freq_hz The frequency value to convert.
836 *
837 * @retval frequency The assigned numbers frequency (@ref bt_audio_codec_cfg_freq).
838 * @retval -EINVAL Arguments are invalid.
839 */
840 int bt_audio_codec_cfg_freq_hz_to_freq(uint32_t freq_hz);
841
842 /**
843 * @brief Extract the frequency from a codec configuration.
844 *
845 * @param codec_cfg The codec configuration to extract data from.
846 *
847 * @retval frequency A @ref bt_audio_codec_cfg_freq value
848 * @retval -EINVAL Arguments are invalid
849 * @retval -ENODATA Data not found
850 * @retval -EBADMSG The found value has invalid size or value
851 */
852 int bt_audio_codec_cfg_get_freq(const struct bt_audio_codec_cfg *codec_cfg);
853
854 /**
855 * @brief Set the frequency of a codec configuration.
856 *
857 * @param codec_cfg The codec configuration to set data for.
858 * @param freq The assigned numbers frequency to set.
859 *
860 * @retval data_len The @p codec_cfg.data_len on success
861 * @retval -EINVAL Arguments are invalid
862 * @retval -ENOMEM The new value could not be set or added due to lack of memory
863 */
864 int bt_audio_codec_cfg_set_freq(struct bt_audio_codec_cfg *codec_cfg,
865 enum bt_audio_codec_cfg_freq freq);
866
867 /**
868 * @brief Convert assigned numbers frame duration to duration in microseconds.
869 *
870 * @param frame_dur The assigned numbers frame duration to convert.
871 *
872 * @retval duration The converted frame duration value in microseconds.
873 * @retval -EINVAL Arguments are invalid.
874 */
875 int bt_audio_codec_cfg_frame_dur_to_frame_dur_us(enum bt_audio_codec_cfg_frame_dur frame_dur);
876
877 /**
878 * @brief Convert frame duration in microseconds to assigned numbers frame duration.
879 *
880 * @param frame_dur_us The frame duration in microseconds to convert.
881 *
882 * @retval duration The assigned numbers frame duration (@ref bt_audio_codec_cfg_frame_dur).
883 * @retval -EINVAL Arguments are invalid.
884 */
885 int bt_audio_codec_cfg_frame_dur_us_to_frame_dur(uint32_t frame_dur_us);
886
887 /**
888 * @brief Extract frame duration from BT codec config
889 *
890 * @param codec_cfg The codec configuration to extract data from.
891 *
892 * @retval frequency A @ref bt_audio_codec_cfg_frame_dur value
893 * @retval -EINVAL Arguments are invalid
894 * @retval -ENODATA Data not found
895 * @retval -EBADMSG The found value has invalid size or value
896 */
897 int bt_audio_codec_cfg_get_frame_dur(const struct bt_audio_codec_cfg *codec_cfg);
898
899 /**
900 * @brief Set the frame duration of a codec configuration.
901 *
902 * @param codec_cfg The codec configuration to set data for.
903 * @param frame_dur The assigned numbers frame duration to set.
904 *
905 * @retval data_len The @p codec_cfg.data_len on success
906 * @retval -EINVAL Arguments are invalid
907 * @retval -ENOMEM The new value could not be set or added due to lack of memory
908 */
909 int bt_audio_codec_cfg_set_frame_dur(struct bt_audio_codec_cfg *codec_cfg,
910 enum bt_audio_codec_cfg_frame_dur frame_dur);
911
912 /**
913 * @brief Extract channel allocation from BT codec config
914 *
915 * The value returned is a bit field representing one or more audio locations as
916 * specified by @ref bt_audio_location
917 * Shall match one or more of the bits set in BT_PAC_SNK_LOC/BT_PAC_SRC_LOC.
918 *
919 * Up to the configured @ref BT_AUDIO_CODEC_CAP_TYPE_CHAN_COUNT number of channels can be present.
920 *
921 * @param codec_cfg The codec configuration to extract data from.
922 * @param chan_allocation Pointer to the variable to store the extracted value in.
923 * @param fallback_to_default If true this function will provide the default value of
924 * @ref BT_AUDIO_LOCATION_MONO_AUDIO if the type is not found when @p codec_cfg.id is @ref
925 * BT_HCI_CODING_FORMAT_LC3.
926 *
927 * @retval 0 Value is found and stored in the pointer provided
928 * @retval -EINVAL Arguments are invalid
929 * @retval -ENODATA Data not found
930 * @retval -EBADMSG The found value has invalid size or value
931 */
932 int bt_audio_codec_cfg_get_chan_allocation(const struct bt_audio_codec_cfg *codec_cfg,
933 enum bt_audio_location *chan_allocation,
934 bool fallback_to_default);
935
936 /**
937 * @brief Set the channel allocation of a codec configuration.
938 *
939 * @param codec_cfg The codec configuration to set data for.
940 * @param chan_allocation The channel allocation to set.
941 *
942 * @retval data_len The @p codec_cfg.data_len on success
943 * @retval -EINVAL Arguments are invalid
944 * @retval -ENOMEM The new value could not be set or added due to lack of memory
945 */
946 int bt_audio_codec_cfg_set_chan_allocation(struct bt_audio_codec_cfg *codec_cfg,
947 enum bt_audio_location chan_allocation);
948
949 /**
950 * @brief Extract frame size in octets from BT codec config
951 *
952 * The overall SDU size will be octets_per_frame * blocks_per_sdu.
953 *
954 * The Bluetooth specifications are not clear about this value - it does not state that
955 * the codec shall use this SDU size only. A codec like LC3 supports variable bit-rate
956 * (per SDU) hence it might be allowed for an encoder to reduce the frame size below this
957 * value.
958 * Hence it is recommended to use the received SDU size and divide by
959 * blocks_per_sdu rather than relying on this octets_per_sdu value to be fixed.
960 *
961 * @param codec_cfg The codec configuration to extract data from.
962 *
963 * @retval frame_length Frame length in octets
964 * @retval -EINVAL Arguments are invalid
965 * @retval -ENODATA Data not found
966 * @retval -EBADMSG The found value has invalid size or value
967 */
968 int bt_audio_codec_cfg_get_octets_per_frame(const struct bt_audio_codec_cfg *codec_cfg);
969
970 /**
971 * @brief Set the octets per codec frame of a codec configuration.
972 *
973 * @param codec_cfg The codec configuration to set data for.
974 * @param octets_per_frame The octets per codec frame to set.
975 *
976 * @retval data_len The @p codec_cfg.data_len on success
977 * @retval -EINVAL Arguments are invalid
978 * @retval -ENOMEM The new value could not be set or added due to lack of memory
979 */
980 int bt_audio_codec_cfg_set_octets_per_frame(struct bt_audio_codec_cfg *codec_cfg,
981 uint16_t octets_per_frame);
982
983 /**
984 * @brief Extract number of audio frame blocks in each SDU from BT codec config
985 *
986 * The overall SDU size will be octets_per_frame * frame_blocks_per_sdu * number-of-channels.
987 *
988 * If this value is not present a default value of 1 shall be used.
989 *
990 * A frame block is one or more frames that represents data for the same period of time but
991 * for different channels. If the stream have two audio channels and this value is two
992 * there will be four frames in the SDU.
993 *
994 * @param codec_cfg The codec configuration to extract data from.
995 * @param fallback_to_default If true this function will return the default value of 1
996 * if the type is not found when @p codec_cfg.id is @ref BT_HCI_CODING_FORMAT_LC3.
997 *
998 * @retval frame_blocks_per_sdu The count of codec frame blocks in each SDU.
999 * @retval -EINVAL Arguments are invalid
1000 * @retval -ENODATA Data not found
1001 * @retval -EBADMSG The found value has invalid size or value
1002 */
1003 int bt_audio_codec_cfg_get_frame_blocks_per_sdu(const struct bt_audio_codec_cfg *codec_cfg,
1004 bool fallback_to_default);
1005
1006 /**
1007 * @brief Set the frame blocks per SDU of a codec configuration.
1008 *
1009 * @param codec_cfg The codec configuration to set data for.
1010 * @param frame_blocks The frame blocks per SDU to set.
1011 *
1012 * @retval data_len The @p codec_cfg.data_len on success
1013 * @retval -EINVAL Arguments are invalid
1014 * @retval -ENOMEM The new value could not be set or added due to lack of memory
1015 */
1016 int bt_audio_codec_cfg_set_frame_blocks_per_sdu(struct bt_audio_codec_cfg *codec_cfg,
1017 uint8_t frame_blocks);
1018
1019 /**
1020 * @brief Lookup a specific codec configuration value
1021 *
1022 * @param[in] codec_cfg The codec data to search in.
1023 * @param[in] type The type id to look for
1024 * @param[out] data Pointer to the data-pointer to update when item is found
1025 *
1026 * @retval len Length of found @p data (may be 0)
1027 * @retval -EINVAL Arguments are invalid
1028 * @retval -ENODATA Data not found
1029 */
1030 int bt_audio_codec_cfg_get_val(const struct bt_audio_codec_cfg *codec_cfg,
1031 enum bt_audio_codec_cfg_type type, const uint8_t **data);
1032
1033 /**
1034 * @brief Set or add a specific codec configuration value
1035 *
1036 * @param codec_cfg The codec data to set the value in.
1037 * @param type The type id to set
1038 * @param data Pointer to the data-pointer to set
1039 * @param data_len Length of @p data
1040 *
1041 * @retval data_len The @p codec_cfg.data_len on success
1042 * @retval -EINVAL Arguments are invalid
1043 * @retval -ENOMEM The new value could not be set or added due to lack of memory
1044 */
1045 int bt_audio_codec_cfg_set_val(struct bt_audio_codec_cfg *codec_cfg,
1046 enum bt_audio_codec_cfg_type type, const uint8_t *data,
1047 size_t data_len);
1048
1049 /**
1050 * @brief Unset a specific codec configuration value
1051 *
1052 * The type and the value will be removed from the codec configuration.
1053 *
1054 * @param codec_cfg The codec data to set the value in.
1055 * @param type The type id to unset.
1056 *
1057 * @retval data_len The @p codec_cfg.data_len on success
1058 * @retval -EINVAL Arguments are invalid
1059 */
1060 int bt_audio_codec_cfg_unset_val(struct bt_audio_codec_cfg *codec_cfg,
1061 enum bt_audio_codec_cfg_type type);
1062
1063 /**
1064 * @brief Lookup a specific metadata value based on type
1065 *
1066 *
1067 * @param[in] codec_cfg The codec data to search in.
1068 * @param[in] type The type id to look for
1069 * @param[out] data Pointer to the data-pointer to update when item is found
1070 *
1071 * @retval len Length of found @p data (may be 0)
1072 * @retval -EINVAL Arguments are invalid
1073 * @retval -ENODATA Data not found
1074 */
1075 int bt_audio_codec_cfg_meta_get_val(const struct bt_audio_codec_cfg *codec_cfg, uint8_t type,
1076 const uint8_t **data);
1077
1078 /**
1079 * @brief Set or add a specific codec configuration metadata value.
1080 *
1081 * @param codec_cfg The codec configuration to set the value in.
1082 * @param type The type id to set.
1083 * @param data Pointer to the data-pointer to set.
1084 * @param data_len Length of @p data.
1085 *
1086 * @retval meta_len The @p codec_cfg.meta_len on success
1087 * @retval -EINVAL Arguments are invalid
1088 * @retval -ENOMEM The new value could not be set or added due to lack of memory
1089 */
1090 int bt_audio_codec_cfg_meta_set_val(struct bt_audio_codec_cfg *codec_cfg,
1091 enum bt_audio_metadata_type type, const uint8_t *data,
1092 size_t data_len);
1093
1094 /**
1095 * @brief Unset a specific codec configuration metadata value
1096 *
1097 * The type and the value will be removed from the codec configuration metadata.
1098 *
1099 * @param codec_cfg The codec data to set the value in.
1100 * @param type The type id to unset.
1101 *
1102 * @retval meta_len The of @p codec_cfg.meta_len success
1103 * @retval -EINVAL Arguments are invalid
1104 */
1105 int bt_audio_codec_cfg_meta_unset_val(struct bt_audio_codec_cfg *codec_cfg,
1106 enum bt_audio_metadata_type type);
1107 /**
1108 * @brief Extract preferred contexts
1109 *
1110 * See @ref BT_AUDIO_METADATA_TYPE_PREF_CONTEXT for more information about this value.
1111 *
1112 * @param codec_cfg The codec data to search in.
1113 * @param fallback_to_default If true this function will provide the default value of
1114 * @ref BT_AUDIO_CONTEXT_TYPE_UNSPECIFIED if the type is not found when @p codec_cfg.id is
1115 * @ref BT_HCI_CODING_FORMAT_LC3.
1116 *
1117 * @retval context The preferred context type if positive or 0
1118 * @retval -EINVAL Arguments are invalid
1119 * @retval -ENODATA Data not found
1120 * @retval -EBADMSG The found value has invalid size
1121 */
1122 int bt_audio_codec_cfg_meta_get_pref_context(const struct bt_audio_codec_cfg *codec_cfg,
1123 bool fallback_to_default);
1124
1125 /**
1126 * @brief Set the preferred context of a codec configuration metadata.
1127 *
1128 * @param codec_cfg The codec configuration to set data for.
1129 * @param ctx The preferred context to set.
1130 *
1131 * @retval data_len The @p codec_cfg.data_len on success
1132 * @retval -EINVAL Arguments are invalid
1133 * @retval -ENOMEM The new value could not be set or added due to lack of memory
1134 */
1135 int bt_audio_codec_cfg_meta_set_pref_context(struct bt_audio_codec_cfg *codec_cfg,
1136 enum bt_audio_context ctx);
1137
1138 /**
1139 * @brief Extract stream contexts
1140 *
1141 * See @ref BT_AUDIO_METADATA_TYPE_STREAM_CONTEXT for more information about this value.
1142 *
1143 * @param codec_cfg The codec data to search in.
1144 *
1145 * @retval context The stream context type if positive or 0
1146 * @retval -EINVAL Arguments are invalid
1147 * @retval -ENODATA Data not found
1148 * @retval -EBADMSG The found value has invalid size
1149 */
1150 int bt_audio_codec_cfg_meta_get_stream_context(const struct bt_audio_codec_cfg *codec_cfg);
1151
1152 /**
1153 * @brief Set the stream context of a codec configuration metadata.
1154 *
1155 * @param codec_cfg The codec configuration to set data for.
1156 * @param ctx The stream context to set.
1157 *
1158 * @retval data_len The @p codec_cfg.data_len on success
1159 * @retval -EINVAL Arguments are invalid
1160 * @retval -ENOMEM The new value could not be set or added due to lack of memory
1161 */
1162 int bt_audio_codec_cfg_meta_set_stream_context(struct bt_audio_codec_cfg *codec_cfg,
1163 enum bt_audio_context ctx);
1164
1165 /**
1166 * @brief Extract program info
1167 *
1168 * See @ref BT_AUDIO_METADATA_TYPE_PROGRAM_INFO for more information about this value.
1169 *
1170 * @param[in] codec_cfg The codec data to search in.
1171 * @param[out] program_info Pointer to the UTF-8 formatted program info.
1172 *
1173 * @retval len The length of the @p program_info (may be 0)
1174 * @retval -EINVAL Arguments are invalid
1175 * @retval -ENODATA Data not found
1176 */
1177 int bt_audio_codec_cfg_meta_get_program_info(const struct bt_audio_codec_cfg *codec_cfg,
1178 const uint8_t **program_info);
1179
1180 /**
1181 * @brief Set the program info of a codec configuration metadata.
1182 *
1183 * @param codec_cfg The codec configuration to set data for.
1184 * @param program_info The program info to set.
1185 * @param program_info_len The length of @p program_info.
1186 *
1187 * @retval data_len The @p codec_cfg.data_len on success
1188 * @retval -EINVAL Arguments are invalid
1189 * @retval -ENOMEM The new value could not be set or added due to lack of memory
1190 */
1191 int bt_audio_codec_cfg_meta_set_program_info(struct bt_audio_codec_cfg *codec_cfg,
1192 const uint8_t *program_info, size_t program_info_len);
1193
1194 /**
1195 * @brief Extract language
1196 *
1197 * See @ref BT_AUDIO_METADATA_TYPE_LANG for more information about this value.
1198 *
1199 * @param[in] codec_cfg The codec data to search in.
1200 * @param[out] lang Pointer to the language bytes (of length BT_AUDIO_LANG_SIZE)
1201 *
1202 * @retval 0 Success
1203 * @retval -EINVAL Arguments are invalid
1204 * @retval -ENODATA Data not found
1205 * @retval -EBADMSG The found value has invalid size
1206 */
1207 int bt_audio_codec_cfg_meta_get_lang(const struct bt_audio_codec_cfg *codec_cfg,
1208 const uint8_t **lang);
1209
1210 /**
1211 * @brief Set the language of a codec configuration metadata.
1212 *
1213 * @param codec_cfg The codec configuration to set data for.
1214 * @param lang The 24-bit language to set.
1215 *
1216 * @retval data_len The @p codec_cfg.data_len on success
1217 * @retval -EINVAL Arguments are invalid
1218 * @retval -ENOMEM The new value could not be set or added due to lack of memory
1219 */
1220 int bt_audio_codec_cfg_meta_set_lang(struct bt_audio_codec_cfg *codec_cfg,
1221 const uint8_t lang[BT_AUDIO_LANG_SIZE]);
1222
1223 /**
1224 * @brief Extract CCID list
1225 *
1226 * See @ref BT_AUDIO_METADATA_TYPE_CCID_LIST for more information about this value.
1227 *
1228 * @param[in] codec_cfg The codec data to search in.
1229 * @param[out] ccid_list Pointer to the array containing 8-bit CCIDs.
1230 *
1231 * @retval len The length of the @p ccid_list (may be 0)
1232 * @retval -EINVAL Arguments are invalid
1233 * @retval -ENODATA Data not found
1234 */
1235 int bt_audio_codec_cfg_meta_get_ccid_list(const struct bt_audio_codec_cfg *codec_cfg,
1236 const uint8_t **ccid_list);
1237
1238 /**
1239 * @brief Set the CCID list of a codec configuration metadata.
1240 *
1241 * @param codec_cfg The codec configuration to set data for.
1242 * @param ccid_list The program info to set.
1243 * @param ccid_list_len The length of @p ccid_list.
1244 *
1245 * @retval data_len The @p codec_cfg.data_len on success
1246 * @retval -EINVAL Arguments are invalid
1247 * @retval -ENOMEM The new value could not be set or added due to lack of memory
1248 */
1249 int bt_audio_codec_cfg_meta_set_ccid_list(struct bt_audio_codec_cfg *codec_cfg,
1250 const uint8_t *ccid_list, size_t ccid_list_len);
1251
1252 /**
1253 * @brief Extract parental rating
1254 *
1255 * See @ref BT_AUDIO_METADATA_TYPE_PARENTAL_RATING for more information about this value.
1256 *
1257 * @param codec_cfg The codec data to search in.
1258 *
1259 * @retval parental_rating The parental rating if positive or 0
1260 * @retval -EINVAL Arguments are invalid
1261 * @retval -ENODATA Data not found
1262 * @retval -EBADMSG The found value has invalid size
1263 */
1264 int bt_audio_codec_cfg_meta_get_parental_rating(const struct bt_audio_codec_cfg *codec_cfg);
1265
1266 /**
1267 * @brief Set the parental rating of a codec configuration metadata.
1268 *
1269 * @param codec_cfg The codec configuration to set data for.
1270 * @param parental_rating The parental rating to set.
1271 *
1272 * @retval data_len The @p codec_cfg.data_len on success
1273 * @retval -EINVAL Arguments are invalid
1274 * @retval -ENOMEM The new value could not be set or added due to lack of memory
1275 */
1276 int bt_audio_codec_cfg_meta_set_parental_rating(struct bt_audio_codec_cfg *codec_cfg,
1277 enum bt_audio_parental_rating parental_rating);
1278
1279 /**
1280 * @brief Extract program info URI
1281 *
1282 * See @ref BT_AUDIO_METADATA_TYPE_PROGRAM_INFO_URI for more information about this value.
1283 *
1284 * @param[in] codec_cfg The codec data to search in.
1285 * @param[out] program_info_uri Pointer to the UTF-8 formatted program info URI.
1286 *
1287 * @retval len The length of the @p program_info_uri (may be 0)
1288 * @retval -EINVAL Arguments are invalid
1289 * @retval -ENODATA Data not found
1290 */
1291 int bt_audio_codec_cfg_meta_get_program_info_uri(const struct bt_audio_codec_cfg *codec_cfg,
1292 const uint8_t **program_info_uri);
1293
1294 /**
1295 * @brief Set the program info URI of a codec configuration metadata.
1296 *
1297 * @param codec_cfg The codec configuration to set data for.
1298 * @param program_info_uri The program info URI to set.
1299 * @param program_info_uri_len The length of @p program_info_uri.
1300 *
1301 * @retval data_len The @p codec_cfg.data_len on success
1302 * @retval -EINVAL Arguments are invalid
1303 * @retval -ENOMEM The new value could not be set or added due to lack of memory
1304 */
1305 int bt_audio_codec_cfg_meta_set_program_info_uri(struct bt_audio_codec_cfg *codec_cfg,
1306 const uint8_t *program_info_uri,
1307 size_t program_info_uri_len);
1308
1309 /**
1310 * @brief Extract audio active state
1311 *
1312 * See @ref BT_AUDIO_METADATA_TYPE_AUDIO_STATE for more information about this value.
1313 *
1314 * @param codec_cfg The codec data to search in.
1315 *
1316 * @retval context The preferred context type if positive or 0
1317 * @retval -EINVAL Arguments are invalid
1318 * @retval -ENODATA Data not found
1319 * @retval -EBADMSG The found value has invalid size
1320 */
1321 int bt_audio_codec_cfg_meta_get_audio_active_state(const struct bt_audio_codec_cfg *codec_cfg);
1322
1323 /**
1324 * @brief Set the audio active state of a codec configuration metadata.
1325 *
1326 * @param codec_cfg The codec configuration to set data for.
1327 * @param state The audio active state to set.
1328 *
1329 * @retval data_len The @p codec_cfg.data_len on success
1330 * @retval -EINVAL Arguments are invalid
1331 * @retval -ENOMEM The new value could not be set or added due to lack of memory
1332 */
1333 int bt_audio_codec_cfg_meta_set_audio_active_state(struct bt_audio_codec_cfg *codec_cfg,
1334 enum bt_audio_active_state state);
1335
1336 /**
1337 * @brief Extract broadcast audio immediate rendering flag
1338 *
1339 * See @ref BT_AUDIO_METADATA_TYPE_BROADCAST_IMMEDIATE for more information about this value.
1340 *
1341 * @param codec_cfg The codec data to search in.
1342 *
1343 * @retval 0 The flag was found
1344 * @retval -EINVAL Arguments are invalid
1345 * @retval -ENODATA The flag was not found
1346 */
1347 int bt_audio_codec_cfg_meta_get_bcast_audio_immediate_rend_flag(
1348 const struct bt_audio_codec_cfg *codec_cfg);
1349
1350 /**
1351 * @brief Set the broadcast audio immediate rendering flag of a codec configuration metadata.
1352 *
1353 * @param codec_cfg The codec configuration to set data for.
1354 *
1355 * @retval data_len The @p codec_cfg.data_len on success
1356 * @retval -EINVAL Arguments are invalid
1357 * @retval -ENOMEM The new value could not be set or added due to lack of memory
1358 */
1359 int bt_audio_codec_cfg_meta_set_bcast_audio_immediate_rend_flag(
1360 struct bt_audio_codec_cfg *codec_cfg);
1361
1362 /**
1363 * @brief Extract assisted listening stream
1364 *
1365 * See @ref BT_AUDIO_METADATA_TYPE_ASSISTED_LISTENING_STREAM for more information about this value.
1366 *
1367 * @param codec_cfg The codec data to search in.
1368 *
1369 * @retval value The assisted listening stream value if positive or 0
1370 * @retval -EINVAL Arguments are invalid
1371 * @retval -ENODATA Data not found
1372 * @retval -EBADMSG The found value has invalid size
1373 */
1374 int bt_audio_codec_cfg_meta_get_assisted_listening_stream(
1375 const struct bt_audio_codec_cfg *codec_cfg);
1376
1377 /**
1378 * @brief Set the assisted listening stream value of a codec configuration metadata.
1379 *
1380 * @param codec_cfg The codec configuration to set data for.
1381 * @param val The assisted listening stream value to set.
1382 *
1383 * @retval data_len The @p codec_cap.data_len on success
1384 * @retval -EINVAL Arguments are invalid
1385 * @retval -ENOMEM The new value could not be set or added due to lack of memory
1386 */
1387 int bt_audio_codec_cfg_meta_set_assisted_listening_stream(
1388 struct bt_audio_codec_cfg *codec_cfg, enum bt_audio_assisted_listening_stream val);
1389
1390 /**
1391 * @brief Extract broadcast name
1392 *
1393 * See @ref BT_AUDIO_METADATA_TYPE_BROADCAST_NAME for more information about this value.
1394 *
1395 * @param[in] codec_cfg The codec data to search in.
1396 * @param[out] broadcast_name Pointer to the UTF-8 formatted broadcast name.
1397 *
1398 * @retval length The length of the @p broadcast_name (may be 0)
1399 * @retval -EINVAL Arguments are invalid
1400 * @retval -ENODATA Data not found
1401 */
1402 int bt_audio_codec_cfg_meta_get_broadcast_name(const struct bt_audio_codec_cfg *codec_cfg,
1403 const uint8_t **broadcast_name);
1404
1405 /**
1406 * @brief Set the broadcast name of a codec configuration metadata.
1407 *
1408 * @param codec_cfg The codec configuration to set data for.
1409 * @param broadcast_name The broadcast name to set.
1410 * @param broadcast_name_len The length of @p broadcast_name.
1411 *
1412 * @retval data_len The @p codec_cfg.data_len on success
1413 * @retval -EINVAL Arguments are invalid
1414 * @retval -ENOMEM The new value could not be set or added due to lack of memory
1415 */
1416 int bt_audio_codec_cfg_meta_set_broadcast_name(struct bt_audio_codec_cfg *codec_cfg,
1417 const uint8_t *broadcast_name,
1418 size_t broadcast_name_len);
1419
1420 /**
1421 * @brief Extract extended metadata
1422 *
1423 * See @ref BT_AUDIO_METADATA_TYPE_EXTENDED for more information about this value.
1424 *
1425 * @param[in] codec_cfg The codec data to search in.
1426 * @param[out] extended_meta Pointer to the extended metadata.
1427 *
1428 * @retval len The length of the @p extended_meta (may be 0)
1429 * @retval -EINVAL Arguments are invalid
1430 * @retval -ENODATA Data not found
1431 */
1432 int bt_audio_codec_cfg_meta_get_extended(const struct bt_audio_codec_cfg *codec_cfg,
1433 const uint8_t **extended_meta);
1434
1435 /**
1436 * @brief Set the extended metadata of a codec configuration metadata.
1437 *
1438 * @param codec_cfg The codec configuration to set data for.
1439 * @param extended_meta The extended metadata to set.
1440 * @param extended_meta_len The length of @p extended_meta.
1441 *
1442 * @retval data_len The @p codec_cfg.data_len on success
1443 * @retval -EINVAL Arguments are invalid
1444 * @retval -ENOMEM The new value could not be set or added due to lack of memory
1445 */
1446 int bt_audio_codec_cfg_meta_set_extended(struct bt_audio_codec_cfg *codec_cfg,
1447 const uint8_t *extended_meta, size_t extended_meta_len);
1448
1449 /**
1450 * @brief Extract vendor specific metadata
1451 *
1452 * See @ref BT_AUDIO_METADATA_TYPE_VENDOR for more information about this value.
1453 *
1454 * @param[in] codec_cfg The codec data to search in.
1455 * @param[out] vendor_meta Pointer to the vendor specific metadata.
1456 *
1457 * @retval len The length of the @p vendor_meta (may be 0)
1458 * @retval -EINVAL Arguments are invalid
1459 * @retval -ENODATA Data not found
1460 */
1461 int bt_audio_codec_cfg_meta_get_vendor(const struct bt_audio_codec_cfg *codec_cfg,
1462 const uint8_t **vendor_meta);
1463
1464 /**
1465 * @brief Set the vendor specific metadata of a codec configuration metadata.
1466 *
1467 * @param codec_cfg The codec configuration to set data for.
1468 * @param vendor_meta The vendor specific metadata to set.
1469 * @param vendor_meta_len The length of @p vendor_meta.
1470 *
1471 * @retval data_len The @p codec_cfg.data_len on success
1472 * @retval -EINVAL Arguments are invalid
1473 * @retval -ENOMEM The new value could not be set or added due to lack of memory
1474 */
1475 int bt_audio_codec_cfg_meta_set_vendor(struct bt_audio_codec_cfg *codec_cfg,
1476 const uint8_t *vendor_meta, size_t vendor_meta_len);
1477 /** @} */ /* End of bt_audio_codec_cfg */
1478
1479 /**
1480 * @brief Audio codec capabilities APIs
1481 * @defgroup bt_audio_codec_cap Codec capability parsing APIs
1482 *
1483 * Functions to parse codec capability data when formatted as LTV wrapped into @ref
1484 * bt_audio_codec_cap.
1485 *
1486 * @{
1487 */
1488
1489 /**
1490 * @brief Lookup a specific value based on type
1491 *
1492 * @param[in] codec_cap The codec data to search in.
1493 * @param[in] type The type id to look for
1494 * @param[out] data Pointer to the data-pointer to update when item is found
1495 *
1496 * @retval len Length of found @p data (may be 0)
1497 * @retval -EINVAL Arguments are invalid
1498 * @retval -ENODATA Data not found
1499 */
1500 int bt_audio_codec_cap_get_val(const struct bt_audio_codec_cap *codec_cap,
1501 enum bt_audio_codec_cap_type type, const uint8_t **data);
1502
1503 /**
1504 * @brief Set or add a specific codec capability value
1505 *
1506 * @param codec_cap The codec data to set the value in.
1507 * @param type The type id to set
1508 * @param data Pointer to the data-pointer to set
1509 * @param data_len Length of @p data
1510 *
1511 * @retval data_len The @p codec_cap.data_len on success
1512 * @retval -EINVAL Arguments are invalid
1513 * @retval -ENOMEM The new value could not be set or added due to lack of memory
1514 */
1515 int bt_audio_codec_cap_set_val(struct bt_audio_codec_cap *codec_cap,
1516 enum bt_audio_codec_cap_type type, const uint8_t *data,
1517 size_t data_len);
1518
1519 /**
1520 * @brief Unset a specific codec capability value
1521 *
1522 * The type and the value will be removed from the codec capability.
1523 *
1524 * @param codec_cap The codec data to set the value in.
1525 * @param type The type id to unset.
1526 *
1527 * @retval data_len The @p codec_cap.data_len on success
1528 * @retval -EINVAL Arguments are invalid
1529 */
1530 int bt_audio_codec_cap_unset_val(struct bt_audio_codec_cap *codec_cap,
1531 enum bt_audio_codec_cap_type type);
1532
1533 /**
1534 * @brief Extract the frequency from a codec capability.
1535 *
1536 * @param codec_cap The codec capabilities to extract data from.
1537 *
1538 * @retval frequencies Bitfield of supported frequencies (@ref bt_audio_codec_cap_freq) if 0 or
1539 * positive
1540 * @retval -EINVAL Arguments are invalid
1541 * @retval -ENODATA Data not found
1542 * @retval -EBADMSG The found value has invalid size or value
1543 */
1544 int bt_audio_codec_cap_get_freq(const struct bt_audio_codec_cap *codec_cap);
1545
1546 /**
1547 * @brief Set the supported frequencies of a codec capability.
1548 *
1549 * @param codec_cap The codec capabilities to set data for.
1550 * @param freq The supported frequencies to set.
1551 *
1552 * @retval data_len The @p codec_cap.data_len on success
1553 * @retval -EINVAL Arguments are invalid
1554 * @retval -ENOMEM The new value could not be set or added due to lack of memory
1555 */
1556 int bt_audio_codec_cap_set_freq(struct bt_audio_codec_cap *codec_cap,
1557 enum bt_audio_codec_cap_freq freq);
1558
1559 /**
1560 * @brief Extract the frequency from a codec capability.
1561 *
1562 * @param codec_cap The codec capabilities to extract data from.
1563 *
1564 * @retval durations Bitfield of supported frame durations if 0 or positive
1565 * @retval -EINVAL Arguments are invalid
1566 * @retval -ENODATA Data not found
1567 * @retval -EBADMSG The found value has invalid size or value
1568 */
1569 int bt_audio_codec_cap_get_frame_dur(const struct bt_audio_codec_cap *codec_cap);
1570
1571 /**
1572 * @brief Set the frame duration of a codec capability.
1573 *
1574 * @param codec_cap The codec capabilities to set data for.
1575 * @param frame_dur The frame duration to set.
1576 *
1577 * @retval data_len The @p codec_cap.data_len on success
1578 * @retval -EINVAL Arguments are invalid
1579 * @retval -ENOMEM The new value could not be set or added due to lack of memory
1580 */
1581 int bt_audio_codec_cap_set_frame_dur(struct bt_audio_codec_cap *codec_cap,
1582 enum bt_audio_codec_cap_frame_dur frame_dur);
1583
1584 /**
1585 * @brief Extract the frequency from a codec capability.
1586 *
1587 * @param codec_cap The codec capabilities to extract data from.
1588 * @param fallback_to_default If true this function will provide the default value of 1
1589 * if the type is not found when @p codec_cap.id is @ref BT_HCI_CODING_FORMAT_LC3.
1590 *
1591 * @retval channel_counts Number of supported channel counts if 0 or positive
1592 * @retval -EINVAL Arguments are invalid
1593 * @retval -ENODATA Data not found
1594 * @retval -EBADMSG The found value has invalid size or value
1595 */
1596 int bt_audio_codec_cap_get_supported_audio_chan_counts(const struct bt_audio_codec_cap *codec_cap,
1597 bool fallback_to_default);
1598
1599 /**
1600 * @brief Set the channel count of a codec capability.
1601 *
1602 * @param codec_cap The codec capabilities to set data for.
1603 * @param chan_count The channel count frequency to set.
1604 *
1605 * @retval data_len The @p codec_cap.data_len on success
1606 * @retval -EINVAL Arguments are invalid
1607 * @retval -ENOMEM The new value could not be set or added due to lack of memory
1608 */
1609 int bt_audio_codec_cap_set_supported_audio_chan_counts(
1610 struct bt_audio_codec_cap *codec_cap, enum bt_audio_codec_cap_chan_count chan_count);
1611
1612 /**
1613 * @brief Extract the supported octets per codec frame from a codec capability.
1614 *
1615 * @param[in] codec_cap The codec capabilities to extract data from.
1616 * @param[out] codec_frame Struct to place the resulting values in
1617 *
1618 * @retval 0 Success
1619 * @retval -EINVAL Arguments are invalid
1620 * @retval -ENODATA Data not found
1621 * @retval -EBADMSG The found value has invalid size or value
1622 */
1623 int bt_audio_codec_cap_get_octets_per_frame(
1624 const struct bt_audio_codec_cap *codec_cap,
1625 struct bt_audio_codec_octets_per_codec_frame *codec_frame);
1626
1627 /**
1628 * @brief Set the octets per codec frame of a codec capability.
1629 *
1630 * @param codec_cap The codec capabilities to set data for.
1631 * @param codec_frame The octets per codec frame to set.
1632 *
1633 * @retval data_len The @p codec_cap.data_len on success
1634 * @retval -EINVAL Arguments are invalid
1635 * @retval -ENOMEM The new value could not be set or added due to lack of memory
1636 */
1637 int bt_audio_codec_cap_set_octets_per_frame(
1638 struct bt_audio_codec_cap *codec_cap,
1639 const struct bt_audio_codec_octets_per_codec_frame *codec_frame);
1640
1641 /**
1642 * @brief Extract the maximum codec frames per SDU from a codec capability.
1643 *
1644 * @param codec_cap The codec capabilities to extract data from.
1645 * @param fallback_to_default If true this function will provide the default value of 1
1646 * if the type is not found when @p codec_cap.id is @ref BT_HCI_CODING_FORMAT_LC3.
1647 *
1648 * @retval codec_frames_per_sdu Maximum number of codec frames per SDU supported
1649 * @retval -EINVAL Arguments are invalid
1650 * @retval -ENODATA Data not found
1651 * @retval -EBADMSG The found value has invalid size or value
1652 */
1653 int bt_audio_codec_cap_get_max_codec_frames_per_sdu(const struct bt_audio_codec_cap *codec_cap,
1654 bool fallback_to_default);
1655
1656 /**
1657 * @brief Set the maximum codec frames per SDU of a codec capability.
1658 *
1659 * @param codec_cap The codec capabilities to set data for.
1660 * @param codec_frames_per_sdu The maximum codec frames per SDU to set.
1661 *
1662 * @retval data_len The @p codec_cap.data_len on success
1663 * @retval -EINVAL Arguments are invalid
1664 * @retval -ENOMEM The new value could not be set or added due to lack of memory
1665 */
1666 int bt_audio_codec_cap_set_max_codec_frames_per_sdu(struct bt_audio_codec_cap *codec_cap,
1667 uint8_t codec_frames_per_sdu);
1668
1669 /**
1670 * @brief Lookup a specific metadata value based on type
1671 *
1672 * @param[in] codec_cap The codec data to search in.
1673 * @param[in] type The type id to look for
1674 * @param[out] data Pointer to the data-pointer to update when item is found
1675 *
1676 * @retval len Length of found @p data (may be 0)
1677 * @retval -EINVAL Arguments are invalid
1678 * @retval -ENODATA Data not found
1679 */
1680 int bt_audio_codec_cap_meta_get_val(const struct bt_audio_codec_cap *codec_cap, uint8_t type,
1681 const uint8_t **data);
1682
1683 /**
1684 * @brief Set or add a specific codec capability metadata value.
1685 *
1686 * @param codec_cap The codec capability to set the value in.
1687 * @param type The type id to set.
1688 * @param data Pointer to the data-pointer to set.
1689 * @param data_len Length of @p data.
1690 *
1691 * @retval meta_len The @p codec_cap.meta_len on success
1692 * @retval -EINVAL Arguments are invalid
1693 * @retval -ENOMEM The new value could not be set or added due to lack of memory
1694 */
1695 int bt_audio_codec_cap_meta_set_val(struct bt_audio_codec_cap *codec_cap,
1696 enum bt_audio_metadata_type type, const uint8_t *data,
1697 size_t data_len);
1698
1699 /**
1700 * @brief Unset a specific codec capability metadata value
1701 *
1702 * The type and the value will be removed from the codec capability metadata.
1703 *
1704 * @param codec_cap The codec data to set the value in.
1705 * @param type The type id to unset.
1706 *
1707 * @retval meta_len The of @p codec_cap.meta_len on success
1708 * @retval -EINVAL Arguments are invalid
1709 */
1710 int bt_audio_codec_cap_meta_unset_val(struct bt_audio_codec_cap *codec_cap,
1711 enum bt_audio_metadata_type type);
1712
1713 /**
1714 * @brief Extract preferred contexts
1715 *
1716 * See @ref BT_AUDIO_METADATA_TYPE_PREF_CONTEXT for more information about this value.
1717 *
1718 * @param codec_cap The codec data to search in.
1719 *
1720 * @retval The preferred context type if positive or 0
1721 * @retval -EINVAL Arguments are invalid
1722 * @retval -ENODATA Data not found
1723 * @retval -EBADMSG The found value has invalid size
1724 */
1725 int bt_audio_codec_cap_meta_get_pref_context(const struct bt_audio_codec_cap *codec_cap);
1726
1727 /**
1728 * @brief Set the preferred context of a codec capability metadata.
1729 *
1730 * @param codec_cap The codec capability to set data for.
1731 * @param ctx The preferred context to set.
1732 *
1733 * @retval data_len The @p codec_cap.data_len on success
1734 * @retval -EINVAL Arguments are invalid
1735 * @retval -ENOMEM The new value could not be set or added due to lack of memory
1736 */
1737 int bt_audio_codec_cap_meta_set_pref_context(struct bt_audio_codec_cap *codec_cap,
1738 enum bt_audio_context ctx);
1739
1740 /**
1741 * @brief Extract stream contexts
1742 *
1743 * See @ref BT_AUDIO_METADATA_TYPE_STREAM_CONTEXT for more information about this value.
1744 *
1745 * @param codec_cap The codec data to search in.
1746 *
1747 * @retval context The stream context type if positive or 0
1748 * @retval -EINVAL Arguments are invalid
1749 * @retval -ENODATA Data not found
1750 * @retval -EBADMSG The found value has invalid size
1751 */
1752 int bt_audio_codec_cap_meta_get_stream_context(const struct bt_audio_codec_cap *codec_cap);
1753
1754 /**
1755 * @brief Set the stream context of a codec capability metadata.
1756 *
1757 * @param codec_cap The codec capability to set data for.
1758 * @param ctx The stream context to set.
1759 *
1760 * @retval data_len The @p codec_cap.data_len on success
1761 * @retval -EINVAL Arguments are invalid
1762 * @retval -ENOMEM The new value could not be set or added due to lack of memory
1763 */
1764 int bt_audio_codec_cap_meta_set_stream_context(struct bt_audio_codec_cap *codec_cap,
1765 enum bt_audio_context ctx);
1766
1767 /**
1768 * @brief Extract program info
1769 *
1770 * See @ref BT_AUDIO_METADATA_TYPE_PROGRAM_INFO for more information about this value.
1771 *
1772 * @param[in] codec_cap The codec data to search in.
1773 * @param[out] program_info Pointer to the UTF-8 formatted program info.
1774 *
1775 * @retval len The length of the @p program_info (may be 0)
1776 * @retval -EINVAL Arguments are invalid
1777 * @retval -ENODATA Data not found
1778 */
1779 int bt_audio_codec_cap_meta_get_program_info(const struct bt_audio_codec_cap *codec_cap,
1780 const uint8_t **program_info);
1781
1782 /**
1783 * @brief Set the program info of a codec capability metadata.
1784 *
1785 * @param codec_cap The codec capability to set data for.
1786 * @param program_info The program info to set.
1787 * @param program_info_len The length of @p program_info.
1788 *
1789 * @retval data_len The @p codec_cap.data_len on success
1790 * @retval -EINVAL Arguments are invalid
1791 * @retval -ENOMEM The new value could not be set or added due to lack of memory
1792 */
1793 int bt_audio_codec_cap_meta_set_program_info(struct bt_audio_codec_cap *codec_cap,
1794 const uint8_t *program_info, size_t program_info_len);
1795
1796 /**
1797 * @brief Extract language
1798 *
1799 * See @ref BT_AUDIO_METADATA_TYPE_LANG for more information about this value.
1800 *
1801 * @param[in] codec_cap The codec data to search in.
1802 * @param[out] lang Pointer to the language bytes (of length BT_AUDIO_LANG_SIZE)
1803 *
1804 * @retval 0 Success
1805 * @retval -EINVAL Arguments are invalid
1806 * @retval -ENODATA Data not found
1807 * @retval -EBADMSG The found value has invalid size
1808 */
1809 int bt_audio_codec_cap_meta_get_lang(const struct bt_audio_codec_cap *codec_cap,
1810 const uint8_t **lang);
1811
1812 /**
1813 * @brief Set the language of a codec capability metadata.
1814 *
1815 * @param codec_cap The codec capability to set data for.
1816 * @param lang The 24-bit language to set.
1817 *
1818 * @retval data_len The @p codec_cap.data_len on success
1819 * @retval -EINVAL Arguments are invalid
1820 * @retval -ENOMEM The new value could not be set or added due to lack of memory
1821 */
1822 int bt_audio_codec_cap_meta_set_lang(struct bt_audio_codec_cap *codec_cap,
1823 const uint8_t lang[BT_AUDIO_LANG_SIZE]);
1824
1825 /**
1826 * @brief Extract CCID list
1827 *
1828 * See @ref BT_AUDIO_METADATA_TYPE_CCID_LIST for more information about this value.
1829 *
1830 * @param[in] codec_cap The codec data to search in.
1831 * @param[out] ccid_list Pointer to the array containing 8-bit CCIDs.
1832 *
1833 * @retval len The length of the @p ccid_list (may be 0)
1834 * @retval -EINVAL Arguments are invalid
1835 * @retval -ENODATA Data not found
1836 */
1837 int bt_audio_codec_cap_meta_get_ccid_list(const struct bt_audio_codec_cap *codec_cap,
1838 const uint8_t **ccid_list);
1839
1840 /**
1841 * @brief Set the CCID list of a codec capability metadata.
1842 *
1843 * @param codec_cap The codec capability to set data for.
1844 * @param ccid_list The program info to set.
1845 * @param ccid_list_len The length of @p ccid_list.
1846 *
1847 * @retval data_len The @p codec_cap.data_len on success
1848 * @retval -EINVAL Arguments are invalid
1849 * @retval -ENOMEM The new value could not be set or added due to lack of memory
1850 */
1851 int bt_audio_codec_cap_meta_set_ccid_list(struct bt_audio_codec_cap *codec_cap,
1852 const uint8_t *ccid_list, size_t ccid_list_len);
1853
1854 /**
1855 * @brief Extract parental rating
1856 *
1857 * See @ref BT_AUDIO_METADATA_TYPE_PARENTAL_RATING for more information about this value.
1858 *
1859 * @param codec_cap The codec data to search in.
1860 *
1861 * @retval The parental rating if positive or 0
1862 * @retval -EINVAL Arguments are invalid
1863 * @retval -ENODATA Data not found
1864 * @retval -EBADMSG The found value has invalid size
1865 */
1866 int bt_audio_codec_cap_meta_get_parental_rating(const struct bt_audio_codec_cap *codec_cap);
1867
1868 /**
1869 * @brief Set the parental rating of a codec capability metadata.
1870 *
1871 * @param codec_cap The codec capability to set data for.
1872 * @param parental_rating The parental rating to set.
1873 *
1874 * @retval data_len The @p codec_cap.data_len on success
1875 * @retval -EINVAL Arguments are invalid
1876 * @retval -ENOMEM The new value could not be set or added due to lack of memory
1877 */
1878 int bt_audio_codec_cap_meta_set_parental_rating(struct bt_audio_codec_cap *codec_cap,
1879 enum bt_audio_parental_rating parental_rating);
1880
1881 /**
1882 * @brief Extract program info URI
1883 *
1884 * See @ref BT_AUDIO_METADATA_TYPE_PROGRAM_INFO_URI for more information about this value.
1885 *
1886 * @param[in] codec_cap The codec data to search in.
1887 * @param[out] program_info_uri Pointer to the UTF-8 formatted program info URI.
1888 *
1889 * @retval len The length of the @p program_info_uri (may be 0)
1890 * @retval -EINVAL Arguments are invalid
1891 * @retval -ENODATA Data not found
1892 */
1893 int bt_audio_codec_cap_meta_get_program_info_uri(const struct bt_audio_codec_cap *codec_cap,
1894 const uint8_t **program_info_uri);
1895
1896 /**
1897 * @brief Set the program info URI of a codec capability metadata.
1898 *
1899 * @param codec_cap The codec capability to set data for.
1900 * @param program_info_uri The program info URI to set.
1901 * @param program_info_uri_len The length of @p program_info_uri.
1902 *
1903 * @retval data_len The @p codec_cap.data_len on success
1904 * @retval -EINVAL Arguments are invalid
1905 * @retval -ENOMEM The new value could not be set or added due to lack of memory
1906 */
1907 int bt_audio_codec_cap_meta_set_program_info_uri(struct bt_audio_codec_cap *codec_cap,
1908 const uint8_t *program_info_uri,
1909 size_t program_info_uri_len);
1910
1911 /**
1912 * @brief Extract audio active state
1913 *
1914 * See @ref BT_AUDIO_METADATA_TYPE_AUDIO_STATE for more information about this value.
1915 *
1916 * @param codec_cap The codec data to search in.
1917 *
1918 * @retval context The preferred context type if positive or 0
1919 * @retval -EINVAL Arguments are invalid
1920 * @retval -ENODATA Data not found
1921 * @retval -EBADMSG The found value has invalid size
1922 */
1923 int bt_audio_codec_cap_meta_get_audio_active_state(const struct bt_audio_codec_cap *codec_cap);
1924
1925 /**
1926 * @brief Set the audio active state of a codec capability metadata.
1927 *
1928 * @param codec_cap The codec capability to set data for.
1929 * @param state The audio active state to set.
1930 *
1931 * @retval data_len The @p codec_cap.data_len on success
1932 * @retval -EINVAL Arguments are invalid
1933 * @retval -ENOMEM The new value could not be set or added due to lack of memory
1934 */
1935 int bt_audio_codec_cap_meta_set_audio_active_state(struct bt_audio_codec_cap *codec_cap,
1936 enum bt_audio_active_state state);
1937
1938 /**
1939 * @brief Extract broadcast audio immediate rendering flag
1940 *
1941 * See @ref BT_AUDIO_METADATA_TYPE_BROADCAST_IMMEDIATE for more information about this value.
1942 *
1943 * @param codec_cap The codec data to search in.
1944 *
1945 * @retval 0 The flag was found
1946 * @retval -EINVAL Arguments are invalid
1947 * @retval -ENODATA The flag was not found
1948 */
1949 int bt_audio_codec_cap_meta_get_bcast_audio_immediate_rend_flag(
1950 const struct bt_audio_codec_cap *codec_cap);
1951
1952 /**
1953 * @brief Set the broadcast audio immediate rendering flag of a codec capability metadata.
1954 *
1955 * @param codec_cap The codec capability to set data for.
1956 *
1957 * @retval data_len The @p codec_cap.data_len on success
1958 * @retval -EINVAL Arguments are invalid
1959 * @retval -ENOMEM The new value could not be set or added due to lack of memory
1960 */
1961 int bt_audio_codec_cap_meta_set_bcast_audio_immediate_rend_flag(
1962 struct bt_audio_codec_cap *codec_cap);
1963
1964 /**
1965 * @brief Extract assisted listening stream
1966 *
1967 * See @ref BT_AUDIO_METADATA_TYPE_ASSISTED_LISTENING_STREAM for more information about this value.
1968 *
1969 * @param codec_cap The codec data to search in.
1970 *
1971 * @retval value The assisted listening stream value if positive or 0
1972 * @retval -EINVAL Arguments are invalid
1973 * @retval -ENODATA Data not found
1974 * @retval -EBADMSG The found value has invalid size
1975 */
1976 int bt_audio_codec_cap_meta_get_assisted_listening_stream(
1977 const struct bt_audio_codec_cap *codec_cap);
1978
1979 /**
1980 * @brief Set the assisted listening stream value of a codec capability metadata.
1981 *
1982 * @param codec_cap The codec capability to set data for.
1983 * @param val The assisted listening stream value to set.
1984 *
1985 * @retval data_len The @p codec_cap.data_len on success
1986 * @retval -EINVAL Arguments are invalid
1987 * @retval -ENOMEM The new value could not be set or added due to lack of memory
1988 */
1989 int bt_audio_codec_cap_meta_set_assisted_listening_stream(
1990 struct bt_audio_codec_cap *codec_cap, enum bt_audio_assisted_listening_stream val);
1991
1992 /**
1993 * @brief Extract broadcast name
1994 *
1995 * See @ref BT_AUDIO_METADATA_TYPE_BROADCAST_NAME for more information about this value.
1996 *
1997 * @param[in] codec_cap The codec data to search in.
1998 * @param[out] broadcast_name Pointer to the UTF-8 formatted broadcast name.
1999 *
2000 * @retval length The length of the @p broadcast_name (may be 0)
2001 * @retval -EINVAL Arguments are invalid
2002 * @retval -ENODATA Data not found
2003 */
2004 int bt_audio_codec_cap_meta_get_broadcast_name(const struct bt_audio_codec_cap *codec_cap,
2005 const uint8_t **broadcast_name);
2006
2007 /**
2008 * @brief Set the broadcast name of a codec capability metadata.
2009 *
2010 * @param codec_cap The codec capability to set data for.
2011 * @param broadcast_name The broadcast name to set.
2012 * @param broadcast_name_len The length of @p broadcast_name.
2013 *
2014 * @retval data_len The @p codec_cap.data_len on success
2015 * @retval -EINVAL Arguments are invalid
2016 * @retval -ENOMEM The new value could not be set or added due to lack of memory
2017 */
2018 int bt_audio_codec_cap_meta_set_broadcast_name(struct bt_audio_codec_cap *codec_cap,
2019 const uint8_t *broadcast_name,
2020 size_t broadcast_name_len);
2021 /**
2022 * @brief Extract extended metadata
2023 *
2024 * See @ref BT_AUDIO_METADATA_TYPE_EXTENDED for more information about this value.
2025 *
2026 * @param[in] codec_cap The codec data to search in.
2027 * @param[out] extended_meta Pointer to the extended metadata.
2028 *
2029 * @retval len The length of the @p extended_meta (may be 0)
2030 * @retval -EINVAL Arguments are invalid
2031 * @retval -ENODATA Data not found
2032 */
2033 int bt_audio_codec_cap_meta_get_extended(const struct bt_audio_codec_cap *codec_cap,
2034 const uint8_t **extended_meta);
2035
2036 /**
2037 * @brief Set the extended metadata of a codec capability metadata.
2038 *
2039 * @param codec_cap The codec capability to set data for.
2040 * @param extended_meta The extended metadata to set.
2041 * @param extended_meta_len The length of @p extended_meta.
2042 *
2043 * @retval data_len The @p codec_cap.data_len on success
2044 * @retval -EINVAL Arguments are invalid
2045 * @retval -ENOMEM The new value could not be set or added due to lack of memory
2046 */
2047 int bt_audio_codec_cap_meta_set_extended(struct bt_audio_codec_cap *codec_cap,
2048 const uint8_t *extended_meta, size_t extended_meta_len);
2049
2050 /**
2051 * @brief Extract vendor specific metadata
2052 *
2053 * See @ref BT_AUDIO_METADATA_TYPE_VENDOR for more information about this value.
2054 *
2055 * @param[in] codec_cap The codec data to search in.
2056 * @param[out] vendor_meta Pointer to the vendor specific metadata.
2057 *
2058 * @retval len The length of the @p vendor_meta (may be 0)
2059 * @retval -EINVAL Arguments are invalid
2060 * @retval -ENODATA Data not found
2061 */
2062 int bt_audio_codec_cap_meta_get_vendor(const struct bt_audio_codec_cap *codec_cap,
2063 const uint8_t **vendor_meta);
2064
2065 /**
2066 * @brief Set the vendor specific metadata of a codec capability metadata.
2067 *
2068 * @param codec_cap The codec capability to set data for.
2069 * @param vendor_meta The vendor specific metadata to set.
2070 * @param vendor_meta_len The length of @p vendor_meta.
2071 *
2072 * @retval data_len The @p codec_cap.data_len on success
2073 * @retval -EINVAL Arguments are invalid
2074 * @retval -ENOMEM The new value could not be set or added due to lack of memory
2075 */
2076 int bt_audio_codec_cap_meta_set_vendor(struct bt_audio_codec_cap *codec_cap,
2077 const uint8_t *vendor_meta, size_t vendor_meta_len);
2078
2079 /** @} */ /* End of bt_audio_codec_cap */
2080
2081 /**
2082 * @brief Assigned numbers to string API
2083 * @defgroup bt_audio_to_str Assigned numbers to string API
2084 *
2085 * Functions to return string representation of Bluetooth Audio assigned number values.
2086 *
2087 * @{
2088 */
2089
2090 /**
2091 * @brief Returns a string representation of a specific @ref bt_audio_context bit
2092 *
2093 * If @p context contains multiple bits, it will return "Unknown context"
2094 *
2095 * @param context A single context bit
2096 *
2097 * @return String representation of the supplied bit
2098 */
bt_audio_context_bit_to_str(enum bt_audio_context context)2099 static inline char *bt_audio_context_bit_to_str(enum bt_audio_context context)
2100 {
2101 switch (context) {
2102 case BT_AUDIO_CONTEXT_TYPE_PROHIBITED:
2103 return "Prohibited";
2104 case BT_AUDIO_CONTEXT_TYPE_UNSPECIFIED:
2105 return "Unspecified";
2106 case BT_AUDIO_CONTEXT_TYPE_CONVERSATIONAL:
2107 return "Conversational";
2108 case BT_AUDIO_CONTEXT_TYPE_MEDIA:
2109 return "Media";
2110 case BT_AUDIO_CONTEXT_TYPE_GAME:
2111 return "Game";
2112 case BT_AUDIO_CONTEXT_TYPE_INSTRUCTIONAL:
2113 return "Instructional";
2114 case BT_AUDIO_CONTEXT_TYPE_VOICE_ASSISTANTS:
2115 return "Voice assistant";
2116 case BT_AUDIO_CONTEXT_TYPE_LIVE:
2117 return "Live";
2118 case BT_AUDIO_CONTEXT_TYPE_SOUND_EFFECTS:
2119 return "Sound effects";
2120 case BT_AUDIO_CONTEXT_TYPE_NOTIFICATIONS:
2121 return "Notifications";
2122 case BT_AUDIO_CONTEXT_TYPE_RINGTONE:
2123 return "Ringtone";
2124 case BT_AUDIO_CONTEXT_TYPE_ALERTS:
2125 return "Alerts";
2126 case BT_AUDIO_CONTEXT_TYPE_EMERGENCY_ALARM:
2127 return "Emergency alarm";
2128 default:
2129 return "Unknown context";
2130 }
2131 }
2132
2133 /**
2134 * @brief Returns a string representation of a @ref bt_audio_parental_rating value
2135 *
2136 * @param parental_rating The parental rating value
2137 *
2138 * @return String representation of the supplied parental rating value
2139 */
bt_audio_parental_rating_to_str(enum bt_audio_parental_rating parental_rating)2140 static inline char *bt_audio_parental_rating_to_str(enum bt_audio_parental_rating parental_rating)
2141 {
2142 switch (parental_rating) {
2143 case BT_AUDIO_PARENTAL_RATING_NO_RATING:
2144 return "No rating";
2145 case BT_AUDIO_PARENTAL_RATING_AGE_ANY:
2146 return "Any";
2147 case BT_AUDIO_PARENTAL_RATING_AGE_5_OR_ABOVE:
2148 return "Age 5 or above";
2149 case BT_AUDIO_PARENTAL_RATING_AGE_6_OR_ABOVE:
2150 return "Age 6 or above";
2151 case BT_AUDIO_PARENTAL_RATING_AGE_7_OR_ABOVE:
2152 return "Age 7 or above";
2153 case BT_AUDIO_PARENTAL_RATING_AGE_8_OR_ABOVE:
2154 return "Age 8 or above";
2155 case BT_AUDIO_PARENTAL_RATING_AGE_9_OR_ABOVE:
2156 return "Age 9 or above";
2157 case BT_AUDIO_PARENTAL_RATING_AGE_10_OR_ABOVE:
2158 return "Age 10 or above";
2159 case BT_AUDIO_PARENTAL_RATING_AGE_11_OR_ABOVE:
2160 return "Age 11 or above";
2161 case BT_AUDIO_PARENTAL_RATING_AGE_12_OR_ABOVE:
2162 return "Age 12 or above";
2163 case BT_AUDIO_PARENTAL_RATING_AGE_13_OR_ABOVE:
2164 return "Age 13 or above";
2165 case BT_AUDIO_PARENTAL_RATING_AGE_14_OR_ABOVE:
2166 return "Age 14 or above";
2167 case BT_AUDIO_PARENTAL_RATING_AGE_15_OR_ABOVE:
2168 return "Age 15 or above";
2169 case BT_AUDIO_PARENTAL_RATING_AGE_16_OR_ABOVE:
2170 return "Age 16 or above";
2171 case BT_AUDIO_PARENTAL_RATING_AGE_17_OR_ABOVE:
2172 return "Age 17 or above";
2173 case BT_AUDIO_PARENTAL_RATING_AGE_18_OR_ABOVE:
2174 return "Age 18 or above";
2175 default:
2176 return "Unknown rating";
2177 }
2178 }
2179
2180 /**
2181 * @brief Returns a string representation of a @ref bt_audio_active_state value
2182 *
2183 * @param state The active state value
2184 *
2185 * @return String representation of the supplied active state value
2186 */
bt_audio_active_state_to_str(enum bt_audio_active_state state)2187 static inline char *bt_audio_active_state_to_str(enum bt_audio_active_state state)
2188 {
2189 switch (state) {
2190 case BT_AUDIO_ACTIVE_STATE_DISABLED:
2191 return "Disabled";
2192 case BT_AUDIO_ACTIVE_STATE_ENABLED:
2193 return "Enabled";
2194 default:
2195 return "Unknown active state";
2196 }
2197 }
2198
2199 /**
2200 * @brief Returns a string representation of a specific @ref bt_audio_codec_cap_freq bit
2201 *
2202 * If @p freq contains multiple bits, it will return "Unknown supported frequency"
2203 *
2204 * @param freq A single frequency bit
2205 *
2206 * @return String representation of the supplied bit
2207 */
bt_audio_codec_cap_freq_bit_to_str(enum bt_audio_codec_cap_freq freq)2208 static inline char *bt_audio_codec_cap_freq_bit_to_str(enum bt_audio_codec_cap_freq freq)
2209 {
2210 switch (freq) {
2211 case BT_AUDIO_CODEC_CAP_FREQ_8KHZ:
2212 return "8000 Hz";
2213 case BT_AUDIO_CODEC_CAP_FREQ_11KHZ:
2214 return "11025 Hz";
2215 case BT_AUDIO_CODEC_CAP_FREQ_16KHZ:
2216 return "16000 Hz";
2217 case BT_AUDIO_CODEC_CAP_FREQ_22KHZ:
2218 return "22050 Hz";
2219 case BT_AUDIO_CODEC_CAP_FREQ_24KHZ:
2220 return "24000 Hz";
2221 case BT_AUDIO_CODEC_CAP_FREQ_32KHZ:
2222 return "32000 Hz";
2223 case BT_AUDIO_CODEC_CAP_FREQ_44KHZ:
2224 return "44100 Hz";
2225 case BT_AUDIO_CODEC_CAP_FREQ_48KHZ:
2226 return "48000 Hz";
2227 case BT_AUDIO_CODEC_CAP_FREQ_88KHZ:
2228 return "88200 Hz";
2229 case BT_AUDIO_CODEC_CAP_FREQ_96KHZ:
2230 return "96000 Hz";
2231 case BT_AUDIO_CODEC_CAP_FREQ_176KHZ:
2232 return "176400 Hz";
2233 case BT_AUDIO_CODEC_CAP_FREQ_192KHZ:
2234 return "192000 Hz";
2235 case BT_AUDIO_CODEC_CAP_FREQ_384KHZ:
2236 return "384000 Hz";
2237 default:
2238 return "Unknown supported frequency";
2239 }
2240 }
2241
2242 /**
2243 * @brief Returns a string representation of a specific @ref bt_audio_codec_cap_frame_dur bit
2244 *
2245 * If @p frame_dur contains multiple bits, it will return "Unknown frame duration"
2246 *
2247 * @param frame_dur A single frame duration bit
2248 *
2249 * @return String representation of the supplied bit
2250 */
2251 static inline char *
bt_audio_codec_cap_frame_dur_bit_to_str(enum bt_audio_codec_cap_frame_dur frame_dur)2252 bt_audio_codec_cap_frame_dur_bit_to_str(enum bt_audio_codec_cap_frame_dur frame_dur)
2253 {
2254 switch (frame_dur) {
2255 case BT_AUDIO_CODEC_CAP_DURATION_7_5:
2256 return "7.5 ms";
2257 case BT_AUDIO_CODEC_CAP_DURATION_10:
2258 return "10 ms";
2259 case BT_AUDIO_CODEC_CAP_DURATION_PREFER_7_5:
2260 return "7.5 ms preferred";
2261 case BT_AUDIO_CODEC_CAP_DURATION_PREFER_10:
2262 return "10 ms preferred";
2263 default:
2264 return "Unknown frame duration";
2265 }
2266 }
2267
2268 /**
2269 * @brief Returns a string representation of a specific @ref bt_audio_codec_cap_chan_count bit
2270 *
2271 * If @p chan_count contains multiple bits, it will return "Unknown channel count"
2272 *
2273 * @param chan_count A single frame channel count bit
2274 *
2275 * @return String representation of the supplied bit
2276 */
2277 static inline char *
bt_audio_codec_cap_chan_count_bit_to_str(enum bt_audio_codec_cap_chan_count chan_count)2278 bt_audio_codec_cap_chan_count_bit_to_str(enum bt_audio_codec_cap_chan_count chan_count)
2279 {
2280 switch (chan_count) {
2281 case BT_AUDIO_CODEC_CAP_CHAN_COUNT_1:
2282 return "1 channel";
2283 case BT_AUDIO_CODEC_CAP_CHAN_COUNT_2:
2284 return "2 channels";
2285 case BT_AUDIO_CODEC_CAP_CHAN_COUNT_3:
2286 return "3 channels";
2287 case BT_AUDIO_CODEC_CAP_CHAN_COUNT_4:
2288 return "4 channels";
2289 case BT_AUDIO_CODEC_CAP_CHAN_COUNT_5:
2290 return "5 channels";
2291 case BT_AUDIO_CODEC_CAP_CHAN_COUNT_6:
2292 return "6 channels";
2293 case BT_AUDIO_CODEC_CAP_CHAN_COUNT_7:
2294 return "7 channels";
2295 case BT_AUDIO_CODEC_CAP_CHAN_COUNT_8:
2296 return "8 channels";
2297 default:
2298 return "Unknown channel count";
2299 }
2300 }
2301
2302 /**
2303 * @brief Returns a string representation of a specific @ref bt_audio_location bit
2304 *
2305 * If @p location contains multiple bits, it will return "Unknown location"
2306 *
2307 * @param location A single location bit
2308 *
2309 * @return String representation of the supplied bit
2310 */
bt_audio_location_bit_to_str(enum bt_audio_location location)2311 static inline char *bt_audio_location_bit_to_str(enum bt_audio_location location)
2312 {
2313 switch (location) {
2314 case BT_AUDIO_LOCATION_MONO_AUDIO:
2315 return "Mono";
2316 case BT_AUDIO_LOCATION_FRONT_LEFT:
2317 return "Front left";
2318 case BT_AUDIO_LOCATION_FRONT_RIGHT:
2319 return "Front right";
2320 case BT_AUDIO_LOCATION_FRONT_CENTER:
2321 return "Front center";
2322 case BT_AUDIO_LOCATION_LOW_FREQ_EFFECTS_1:
2323 return "Low frequency effects 1";
2324 case BT_AUDIO_LOCATION_BACK_LEFT:
2325 return "Back left";
2326 case BT_AUDIO_LOCATION_BACK_RIGHT:
2327 return "Back right";
2328 case BT_AUDIO_LOCATION_FRONT_LEFT_OF_CENTER:
2329 return "Front left of center";
2330 case BT_AUDIO_LOCATION_FRONT_RIGHT_OF_CENTER:
2331 return "Front right of center";
2332 case BT_AUDIO_LOCATION_BACK_CENTER:
2333 return "Back center";
2334 case BT_AUDIO_LOCATION_LOW_FREQ_EFFECTS_2:
2335 return "Low frequency effects 2";
2336 case BT_AUDIO_LOCATION_SIDE_LEFT:
2337 return "Side left";
2338 case BT_AUDIO_LOCATION_SIDE_RIGHT:
2339 return "Side right";
2340 case BT_AUDIO_LOCATION_TOP_FRONT_LEFT:
2341 return "Top front left";
2342 case BT_AUDIO_LOCATION_TOP_FRONT_RIGHT:
2343 return "Top front right";
2344 case BT_AUDIO_LOCATION_TOP_FRONT_CENTER:
2345 return "Top front center";
2346 case BT_AUDIO_LOCATION_TOP_CENTER:
2347 return "Top center";
2348 case BT_AUDIO_LOCATION_TOP_BACK_LEFT:
2349 return "Top back left";
2350 case BT_AUDIO_LOCATION_TOP_BACK_RIGHT:
2351 return "Top back right";
2352 case BT_AUDIO_LOCATION_TOP_SIDE_LEFT:
2353 return "Top side left";
2354 case BT_AUDIO_LOCATION_TOP_SIDE_RIGHT:
2355 return "Top side right";
2356 case BT_AUDIO_LOCATION_TOP_BACK_CENTER:
2357 return "Top back center";
2358 case BT_AUDIO_LOCATION_BOTTOM_FRONT_CENTER:
2359 return "Bottom front center";
2360 case BT_AUDIO_LOCATION_BOTTOM_FRONT_LEFT:
2361 return "Bottom front left";
2362 case BT_AUDIO_LOCATION_BOTTOM_FRONT_RIGHT:
2363 return "Bottom front right";
2364 case BT_AUDIO_LOCATION_FRONT_LEFT_WIDE:
2365 return "Front left wide";
2366 case BT_AUDIO_LOCATION_FRONT_RIGHT_WIDE:
2367 return "Front right wde";
2368 case BT_AUDIO_LOCATION_LEFT_SURROUND:
2369 return "Left surround";
2370 case BT_AUDIO_LOCATION_RIGHT_SURROUND:
2371 return "Right surround";
2372 default:
2373 return "Unknown location";
2374 }
2375 }
2376
2377 /** @} */ /* End of bt_audio_to_str */
2378 #ifdef __cplusplus
2379 }
2380 #endif
2381
2382 /** @} */ /* end of bt_audio */
2383
2384 #endif /* ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_H_ */
2385
