1 /****************************************************************************** 2 * 3 * Copyright 2022 Google LLC 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at: 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 ******************************************************************************/ 18 19 /** 20 * Low Complexity Communication Codec (LC3) 21 * 22 * This implementation conforms to : 23 * 24 * - Low Complexity Communication Codec (LC3) 25 * Bluetooth Specification v1.0 26 * 27 * - ETSI TS 103 634 v1.4.1 28 * Digital Enhanced Cordless Telecommunications (DECT) 29 * Low Complexity Communication Codec plus (LC3plus) 30 * 31 * LC3 and LC3 Plus are audio codecs designed for low-latency audio transport. 32 * 33 * - Unlike most other codecs, the LC3 codec is focused on audio streaming 34 * in constrained (on packet sizes and interval) tranport layer. 35 * In this way, the LC3 does not handle : 36 * VBR (Variable Bitrate), based on input signal complexity 37 * ABR (Adaptative Bitrate). It does not rely on any bit reservoir, 38 * a frame will be strictly encoded in the bytes budget given by 39 * the user (or transport layer). 40 * 41 * However, the bitrate (bytes budget for encoding a frame) can be 42 * freely changed at any time. But will not rely on signal complexity, 43 * it can follow a temporary bandwidth increase or reduction. 44 * 45 * - Unlike classic codecs, the LC3 codecs does not run on fixed amount 46 * of samples as input. It operates only on fixed frame duration, for 47 * any supported sample rates (8 to 48 KHz). Two frames duration are 48 * available 7.5ms and 10ms. 49 * 50 * 51 * --- LC3 Plus features --- 52 * 53 * In addition to LC3, following features of LC3 Plus are proposed: 54 * - Frame duration of 2.5 and 5ms. 55 * - High-Resolution mode, 48 KHz, and 96 kHz sampling rates. 56 * 57 * The distinction between LC3 and LC3 plus is made according to : 58 * 59 * Frame Duration | 2.5ms | 5ms | 7.5ms | 10 ms | 60 * ---------------- | ----- | ----- | ----- | ----- | 61 * LC3 | | | X | X | 62 * LC3 Plus | X | X | | X | 63 * 64 * The 10 ms frame duration is available in LC3 and LC3 plus standard. 65 * In this mode, the produced bitstream can be referenced either 66 * as LC3 or LC3 plus. 67 * 68 * The LC3 Plus high-resolution mode should be preferred at high bitrates 69 * and larger audio bandwidth. In this mode, the audio bandwidth is always 70 * up to the Nyquist frequency, compared to LC3 at 48 KHz, which limits 71 * the bandwidth to 20 KHz. 72 * 73 * 74 * --- Bit rate --- 75 * 76 * The proposed implementation accepts any frame sizes between 20 and 400 Bytes 77 * for non-high-resolution mode. Mind that the LC3 Plus standard defines 78 * smaller sizes for frame durations shorter than 10 ms and/or sampling rates 79 * less than 48 kHz. 80 * 81 * In High-Resolution mode, the frame sizes (and bitrates) are restricted 82 * as follows: 83 * 84 * HR Configuration | Frame sizes | Bitrate (kbps) | 85 * ------------------ | ------------- | -------------- | 86 * 10 ms - 48 KHz | 156 to 625 | 124.8 - 500 | 87 * 10 ms - 96 KHz | 187 to 625 | 149.6 - 500 | 88 * ------------------ | ------------- | -------------- | 89 * 5 ms - 48 KHz | 93 to 375 | 148.8 - 600 | 90 * 5 ms - 96 KHz | 109 to 375 | 174.4 - 600 | 91 * ------------------ | ------------- | -------------- | 92 * 2.5 ms - 48 KHz | 54 to 210 | 172.8 - 672 | 93 * 2.5 ms - 96 KHz | 62 to 210 | 198.4 - 672 | 94 * 95 * 96 * --- About 44.1 KHz sample rate --- 97 * 98 * The Bluetooth specification and the ETSI TS 103 634 standard references 99 * the 44.1 KHz sample rate, although there is no support in the core algorithm 100 * of the codec. 101 * We can summarize the 44.1 KHz support by "You can put any sample rate around 102 * the defined base sample rates." Please mind the following items : 103 * 104 * 1. The frame size will not be 2.5ms, 5ms, 7.5 ms or 10 ms, but is scaled 105 * by 'supported sample rate' / 'input sample rate' 106 * 107 * 2. The bandwidth will be hard limited (to 20 KHz) if you select 48 KHz. 108 * The encoded bandwidth will also be affected by the above inverse 109 * factor of 20 KHz. 110 * 111 * Applied to 44.1 KHz, we get : 112 * 113 * 1. About 8.16 ms frame duration, instead of 7.5 ms 114 * About 10.88 ms frame duration, instead of 10 ms 115 * 116 * 2. The bandwidth becomes limited to 18.375 KHz 117 * 118 * 119 * --- How to encode / decode --- 120 * 121 * An encoder / decoder context needs to be setup. This context keeps states 122 * on the current stream to proceed, and samples that overlapped across 123 * frames. 124 * 125 * You have two ways to setup the encoder / decoder : 126 * 127 * - Using static memory allocation (this module does not rely on 128 * any dynamic memory allocation). The types `lc3_xxcoder_mem_16k_t`, 129 * and `lc3_xxcoder_mem_48k_t` have size of the memory needed for 130 * encoding up to 16 KHz or 48 KHz. 131 * 132 * - Using dynamic memory allocation. The `lc3_xxcoder_size()` procedure 133 * returns the needed memory size, for a given configuration. The memory 134 * space must be aligned to a pointer size. As an example, you can setup 135 * encoder like this : 136 * 137 * | enc = lc3_setup_encoder(frame_us, sample rate, 138 * | malloc(lc3_encoder_size(frame_us, sample rate))); 139 * | ... 140 * | free(enc); 141 * 142 * Note : 143 * - A NULL memory adress as input, will return a NULL encoder context. 144 * - The returned encoder handle is set at the address of the allocated 145 * memory space, you can directly free the handle. 146 * 147 * Next, call the `lc3_encode()` encoding procedure, for each frames. 148 * To handle multichannel streams (Stereo or more), you can proceed with 149 * interleaved channels PCM stream like this : 150 * 151 * | for(int ich = 0; ich < nch: ich++) 152 * | lc3_encode(encoder[ich], pcm + ich, nch, ...); 153 * 154 * with `nch` as the number of channels in the PCM stream 155 * 156 * --- 157 * 158 * Antoine SOULIER, Tempow / Google LLC 159 * 160 */ 161 162 #ifndef __LC3_H 163 #define __LC3_H 164 165 #ifdef __cplusplus 166 extern "C" { 167 #endif 168 169 #include <stdint.h> 170 #include <stdbool.h> 171 172 #include "lc3_private.h" 173 174 175 /** 176 * Limitations 177 * - On the bitrate, in bps 178 * - On the size of the frames in bytes 179 * - On the number of samples by frames 180 */ 181 182 #define LC3_MIN_BITRATE 16000 183 #define LC3_MAX_BITRATE 320000 184 #define LC3_HR_MAX_BITRATE 672000 185 186 #define LC3_MIN_FRAME_BYTES 20 187 #define LC3_MAX_FRAME_BYTES 400 188 #define LC3_HR_MAX_FRAME_BYTES 625 189 190 #define LC3_MIN_FRAME_SAMPLES LC3_NS( 2500, 8000) 191 #define LC3_MAX_FRAME_SAMPLES LC3_NS(10000, 48000) 192 #define LC3_HR_MAX_FRAME_SAMPLES LC3_NS(10000, 96000) 193 194 195 /** 196 * Parameters check 197 * LC3_CHECK_DT_US(us) True when frame duration in us is suitable 198 * LC3_CHECK_SR_HZ(sr) True when sample rate in Hz is suitable 199 * 200 * LC3_HR_CHECK_SR_HZ(hrmode, sr) 201 * True when sample rate in Hz is suitable, according to the 202 * selection of the high-resolution mode `hrmode`. 203 */ 204 205 #define LC3_CHECK_DT_US(us) \ 206 ( ((us) == 2500) || ((us) == 5000) || \ 207 ((us) == 7500) || ((us) == 10000) ) 208 209 #define LC3_CHECK_SR_HZ(sr) \ 210 ( ((sr) == 8000) || ((sr) == 16000) || ((sr) == 24000) || \ 211 ((sr) == 32000) || ((sr) == 48000) ) 212 213 #define LC3_HR_CHECK_SR_HZ(hrmode, sr) \ 214 ( (hrmode) ? ((sr) == 48000) || ((sr) == 96000) : LC3_CHECK_SR_HZ(sr) ) 215 216 217 /** 218 * PCM Sample Format 219 * S16 Signed 16 bits, in 16 bits words (int16_t) 220 * S24 Signed 24 bits, using low three bytes of 32 bits words (int32_t). 221 * The high byte sign extends (bits 31..24 set to b23). 222 * S24_3LE Signed 24 bits packed in 3 bytes little endian 223 * FLOAT Floating point 32 bits (float type), in range -1 to 1 224 */ 225 226 enum lc3_pcm_format { 227 LC3_PCM_FORMAT_S16, 228 LC3_PCM_FORMAT_S24, 229 LC3_PCM_FORMAT_S24_3LE, 230 LC3_PCM_FORMAT_FLOAT, 231 }; 232 233 234 /** 235 * Handle 236 */ 237 238 typedef struct lc3_encoder *lc3_encoder_t; 239 typedef struct lc3_decoder *lc3_decoder_t; 240 241 242 /** 243 * Static memory of encoder/decoder contexts 244 * 245 * Propose types suitable for static memory allocation, supporting 246 * any frame duration, and maximum sample rates 16k and 48k respectively 247 * You can customize your type using the `LC3_ENCODER_MEM_T` or 248 * `LC3_DECODER_MEM_T` macro. 249 */ 250 251 typedef LC3_ENCODER_MEM_T(10000, 16000) lc3_encoder_mem_16k_t; 252 typedef LC3_ENCODER_MEM_T(10000, 48000) lc3_encoder_mem_48k_t; 253 254 typedef LC3_DECODER_MEM_T(10000, 16000) lc3_decoder_mem_16k_t; 255 typedef LC3_DECODER_MEM_T(10000, 48000) lc3_decoder_mem_48k_t; 256 257 258 /** 259 * Return the number of PCM samples in a frame 260 * hrmode Enable High-Resolution mode (48000 and 96000 sample rates) 261 * dt_us Frame duration in us, 2500, 5000, 7500 or 10000 262 * sr_hz Sample rate in Hz, 8000, 16000, 24000, 32000, 48000 or 96000 263 * return Number of PCM samples, -1 on bad parameters 264 */ 265 LC3_EXPORT int lc3_hr_frame_samples(bool hrmode, int dt_us, int sr_hz); 266 267 LC3_EXPORT int lc3_frame_samples(int dt_us, int sr_hz); 268 269 /** 270 * Return the size of frames, from bitrate 271 * hrmode Enable High-Resolution mode (48000 and 96000 sample rates) 272 * dt_us Frame duration in us, 2500, 5000, 7500 or 10000 273 * sr_hz Sample rate in Hz, 8000, 16000, 24000, 32000, 48000 or 96000 274 * bitrate Target bitrate in bit per second, 0 or `INT_MAX` returns 275 * respectively the minimum and maximum allowed size. 276 * return The floor size in bytes of the frames, -1 on bad parameters 277 */ 278 LC3_EXPORT int lc3_hr_frame_bytes( 279 bool hrmode, int dt_us, int sr_hz, int bitrate); 280 281 LC3_EXPORT int lc3_frame_bytes(int dt_us, int bitrate); 282 283 /** 284 * Return the size of frame blocks, from bitrate 285 * A frame block contains the frame data from all channels. 286 * hrmode Enable High-Resolution mode (48000 and 96000 sample rates) 287 * dt_us Frame duration in us, 2500, 5000, 7500 or 10000 288 * sr_hz Sample rate in Hz, 8000, 16000, 24000, 32000, 48000 or 96000 289 * nchannels The number of channels (or frames) in the block (<= 8) 290 * bitrate Target bitrate in bit per second, 0 or `INT_MAX` returns 291 * respectively the minimum and maximum allowed size. 292 * return The floor size in bytes of the frames, -1 on bad parameters 293 */ 294 LC3_EXPORT int lc3_hr_frame_block_bytes( 295 bool hrmode, int dt_us, int sr_hz, int nchannels, int bitrate); 296 297 LC3_EXPORT int lc3_frame_block_bytes(int dt_us, int nframes, int bitrate); 298 299 /** 300 * Resolve the bitrate, from the size of frames 301 * hrmode Enable High-Resolution mode (48000 and 96000 sample rates) 302 * dt_us Frame duration in us, 2500, 5000, 7500 or 10000 303 * sr_hz Sample rate in Hz, 8000, 16000, 24000, 32000, 48000 or 96000 304 * nbytes Size in bytes of the frames or frame blocks 305 * return The ceiled bitrate in bps, -1 on bad parameters 306 */ 307 LC3_EXPORT int lc3_hr_resolve_bitrate( 308 bool hrmode, int dt_us, int sr_hz, int nbytes); 309 310 LC3_EXPORT int lc3_resolve_bitrate(int dt_us, int nbytes); 311 312 /** 313 * Return algorithmic delay, as a number of samples 314 * hrmode Enable High-Resolution mode (48000 and 96000 sample rates) 315 * dt_us Frame duration in us, 2500, 5000, 7500 or 10000 316 * sr_hz Sample rate in Hz, 8000, 16000, 24000, 32000, 48000 or 96000 317 * return Number of algorithmic delay samples, -1 on bad parameters 318 */ 319 LC3_EXPORT int lc3_hr_delay_samples(bool hrmode, int dt_us, int sr_hz); 320 321 LC3_EXPORT int lc3_delay_samples(int dt_us, int sr_hz); 322 323 /** 324 * Return size needed for an encoder 325 * hrmode Enable High-Resolution mode (48000 and 96000 sample rates) 326 * dt_us Frame duration in us, 2500, 5000, 7500 or 10000 327 * sr_hz Sample rate in Hz, 8000, 16000, 24000, 32000, 48000 or 96000 328 * return Size of then encoder in bytes, 0 on bad parameters 329 * 330 * The `sr_hz` parameter is the sample rate of the PCM input stream, 331 * and will match `sr_pcm_hz` of `lc3_hr_setup_encoder()`. 332 */ 333 LC3_EXPORT unsigned lc3_hr_encoder_size(bool hrmode, int dt_us, int sr_hz); 334 335 LC3_EXPORT unsigned lc3_encoder_size(int dt_us, int sr_hz); 336 337 /** 338 * Setup encoder 339 * hrmode Enable High-Resolution mode (48000 and 96000 sample rates) 340 * dt_us Frame duration in us, 2500, 5000, 7500 or 10000 341 * sr_hz Sample rate in Hz, 8000, 16000, 24000, 32000, 48000 or 96000 342 * sr_pcm_hz Input sample rate, downsampling option of input, or 0 343 * mem Encoder memory space, aligned to pointer type 344 * return Encoder as an handle, NULL on bad parameters 345 * 346 * The `sr_pcm_hz` parameter is a downsampling option of PCM input, 347 * the value `0` fallback to the sample rate of the encoded stream `sr_hz`. 348 * When used, `sr_pcm_hz` is intended to be higher or equal to the encoder 349 * sample rate `sr_hz`. The size of the context needed, given by 350 * `lc3_hr_encoder_size()` will be set accordingly to `sr_pcm_hz`. 351 */ 352 LC3_EXPORT lc3_encoder_t lc3_hr_setup_encoder( 353 bool hrmode, int dt_us, int sr_hz, int sr_pcm_hz, void *mem); 354 355 LC3_EXPORT lc3_encoder_t lc3_setup_encoder( 356 int dt_us, int sr_hz, int sr_pcm_hz, void *mem); 357 358 /** 359 * Encode a frame 360 * encoder Handle of the encoder 361 * fmt PCM input format 362 * pcm, stride Input PCM samples, and count between two consecutives 363 * nbytes Target size, in bytes, of the frame 364 * out Output buffer of `nbytes` size 365 * return 0: On success -1: Wrong parameters 366 */ 367 LC3_EXPORT int lc3_encode( 368 lc3_encoder_t encoder, enum lc3_pcm_format fmt, 369 const void *pcm, int stride, int nbytes, void *out); 370 371 /** 372 * Return size needed for an decoder 373 * hrmode Enable High-Resolution mode (48000 and 96000 sample rates) 374 * dt_us Frame duration in us, 2500, 5000, 7500 or 10000 375 * sr_hz Sample rate in Hz, 8000, 16000, 24000, 32000, 48000 or 96000 376 * return Size of then decoder in bytes, 0 on bad parameters 377 * 378 * The `sr_hz` parameter is the sample rate of the PCM output stream, 379 * and will match `sr_pcm_hz` of `lc3_hr_setup_decoder()`. 380 */ 381 LC3_EXPORT unsigned lc3_hr_decoder_size(bool hrmode, int dt_us, int sr_hz); 382 383 LC3_EXPORT unsigned lc3_decoder_size(int dt_us, int sr_hz); 384 385 /** 386 * Setup decoder 387 * hrmode Enable High-Resolution mode (48000 and 96000 sample rates) 388 * dt_us Frame duration in us, 2500, 5000, 7500 or 10000 389 * sr_hz Sample rate in Hz, 8000, 16000, 24000, 32000, 48000 or 96000 390 * sr_pcm_hz Output sample rate, upsampling option of output (or 0) 391 * mem Decoder memory space, aligned to pointer type 392 * return Decoder as an handle, NULL on bad parameters 393 * 394 * The `sr_pcm_hz` parameter is an upsampling option of PCM output, 395 * the value `0` fallback to the sample rate of the decoded stream `sr_hz`. 396 * When used, `sr_pcm_hz` is intended to be higher or equal to the decoder 397 * sample rate `sr_hz`. The size of the context needed, given by 398 * `lc3_hr_decoder_size()` will be set accordingly to `sr_pcm_hz`. 399 */ 400 LC3_EXPORT lc3_decoder_t lc3_hr_setup_decoder( 401 bool hrmode, int dt_us, int sr_hz, int sr_pcm_hz, void *mem); 402 403 LC3_EXPORT lc3_decoder_t lc3_setup_decoder( 404 int dt_us, int sr_hz, int sr_pcm_hz, void *mem); 405 406 /** 407 * Decode a frame 408 * decoder Handle of the decoder 409 * in, nbytes Input bitstream, and size in bytes, NULL performs PLC 410 * fmt PCM output format 411 * pcm, stride Output PCM samples, and count between two consecutives 412 * return 0: On success 1: PLC operated -1: Wrong parameters 413 */ 414 LC3_EXPORT int lc3_decode( 415 lc3_decoder_t decoder, const void *in, int nbytes, 416 enum lc3_pcm_format fmt, void *pcm, int stride); 417 418 419 #ifdef __cplusplus 420 } 421 #endif 422 423 #endif /* __LC3_H */ 424
