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 * Low Complexity Communication Codec (LC3) 24 * Bluetooth Specification v1.0 25 * 26 * 27 * The LC3 is an efficient low latency audio codec. 28 * 29 * - Unlike most other codecs, the LC3 codec is focused on audio streaming 30 * in constrained (on packet sizes and interval) tranport layer. 31 * In this way, the LC3 does not handle : 32 * VBR (Variable Bitrate), based on input signal complexity 33 * ABR (Adaptative Bitrate). It does not rely on any bit reservoir, 34 * a frame will be strictly encoded in the bytes budget given by 35 * the user (or transport layer). 36 * 37 * However, the bitrate (bytes budget for encoding a frame) can be 38 * freely changed at any time. But will not rely on signal complexity, 39 * it can follow a temporary bandwidth increase or reduction. 40 * 41 * - Unlike classic codecs, the LC3 codecs does not run on fixed amount 42 * of samples as input. It operates only on fixed frame duration, for 43 * any supported samplerates (8 to 48 KHz). Two frames duration are 44 * available 7.5ms and 10ms. 45 * 46 * 47 * --- About 44.1 KHz samplerate --- 48 * 49 * The Bluetooth specification reference the 44.1 KHz samplerate, although 50 * there is no support in the core algorithm of the codec of 44.1 KHz. 51 * We can summarize the 44.1 KHz support by "you can put any samplerate 52 * around the defined base samplerates". Please mind the following items : 53 * 54 * 1. The frame size will not be 7.5 ms or 10 ms, but is scaled 55 * by 'supported samplerate' / 'input samplerate' 56 * 57 * 2. The bandwidth will be hard limited (to 20 KHz) if you select 48 KHz. 58 * The encoded bandwidth will also be affected by the above inverse 59 * factor of 20 KHz. 60 * 61 * Applied to 44.1 KHz, we get : 62 * 63 * 1. About 8.16 ms frame duration, instead of 7.5 ms 64 * About 10.88 ms frame duration, instead of 10 ms 65 * 66 * 2. The bandwidth becomes limited to 18.375 KHz 67 * 68 * 69 * --- How to encode / decode --- 70 * 71 * An encoder / decoder context needs to be setup. This context keeps states 72 * on the current stream to proceed, and samples that overlapped across 73 * frames. 74 * 75 * You have two ways to setup the encoder / decoder : 76 * 77 * - Using static memory allocation (this module does not rely on 78 * any dynamic memory allocation). The types `lc3_xxcoder_mem_16k_t`, 79 * and `lc3_xxcoder_mem_48k_t` have size of the memory needed for 80 * encoding up to 16 KHz or 48 KHz. 81 * 82 * - Using dynamic memory allocation. The `lc3_xxcoder_size()` procedure 83 * returns the needed memory size, for a given configuration. The memory 84 * space must be aligned to a pointer size. As an example, you can setup 85 * encoder like this : 86 * 87 * | enc = lc3_setup_encoder(frame_us, samplerate, 88 * | malloc(lc3_encoder_size(frame_us, samplerate))); 89 * | ... 90 * | free(enc); 91 * 92 * Note : 93 * - A NULL memory adress as input, will return a NULL encoder context. 94 * - The returned encoder handle is set at the address of the allocated 95 * memory space, you can directly free the handle. 96 * 97 * Next, call the `lc3_encode()` encoding procedure, for each frames. 98 * To handle multichannel streams (Stereo or more), you can proceed with 99 * interleaved channels PCM stream like this : 100 * 101 * | for(int ich = 0; ich < nch: ich++) 102 * | lc3_encode(encoder[ich], pcm + ich, nch, ...); 103 * 104 * with `nch` as the number of channels in the PCM stream 105 * 106 * --- 107 * 108 * Antoine SOULIER, Tempow / Google LLC 109 * 110 */ 111 112 #ifndef __LC3_H 113 #define __LC3_H 114 115 #ifdef __cplusplus 116 extern "C" { 117 #endif 118 119 #include <stdint.h> 120 #include <stdbool.h> 121 122 #include "lc3_private.h" 123 124 125 /** 126 * Limitations 127 * - On the bitrate, in bps, of a stream 128 * - On the size of the frames in bytes 129 * - On the number of samples by frames 130 */ 131 132 #define LC3_MIN_BITRATE 16000 133 #define LC3_MAX_BITRATE 320000 134 135 #define LC3_MIN_FRAME_BYTES 20 136 #define LC3_MAX_FRAME_BYTES 400 137 138 #define LC3_MIN_FRAME_SAMPLES __LC3_NS( 7500, 8000) 139 #define LC3_MAX_FRAME_SAMPLES __LC3_NS(10000, 48000) 140 141 142 /** 143 * Parameters check 144 * LC3_CHECK_DT_US(us) True when frame duration in us is suitable 145 * LC3_CHECK_SR_HZ(sr) True when samplerate in Hz is suitable 146 */ 147 148 #define LC3_CHECK_DT_US(us) \ 149 ( ((us) == 7500) || ((us) == 10000) ) 150 151 #define LC3_CHECK_SR_HZ(sr) \ 152 ( ((sr) == 8000) || ((sr) == 16000) || ((sr) == 24000) || \ 153 ((sr) == 32000) || ((sr) == 48000) ) 154 155 156 /** 157 * PCM Sample Format 158 * S16 Signed 16 bits, in 16 bits words (int16_t) 159 * S24 Signed 24 bits, using low three bytes of 32 bits words (int32_t). 160 * The high byte sign extends (bits 31..24 set to b23). 161 * S24_3LE Signed 24 bits packed in 3 bytes little endian 162 * FLOAT Floating point 32 bits (float type), in range -1 to 1 163 */ 164 165 enum lc3_pcm_format { 166 LC3_PCM_FORMAT_S16, 167 LC3_PCM_FORMAT_S24, 168 LC3_PCM_FORMAT_S24_3LE, 169 LC3_PCM_FORMAT_FLOAT, 170 }; 171 172 173 /** 174 * Handle 175 */ 176 177 typedef struct lc3_encoder *lc3_encoder_t; 178 typedef struct lc3_decoder *lc3_decoder_t; 179 180 181 /** 182 * Static memory of encoder context 183 * 184 * Propose types suitable for static memory allocation, supporting 185 * any frame duration, and maximum samplerates 16k and 48k respectively 186 * You can customize your type using the `LC3_ENCODER_MEM_T` or 187 * `LC3_DECODER_MEM_T` macro. 188 */ 189 190 typedef LC3_ENCODER_MEM_T(10000, 16000) lc3_encoder_mem_16k_t; 191 typedef LC3_ENCODER_MEM_T(10000, 48000) lc3_encoder_mem_48k_t; 192 193 typedef LC3_DECODER_MEM_T(10000, 16000) lc3_decoder_mem_16k_t; 194 typedef LC3_DECODER_MEM_T(10000, 48000) lc3_decoder_mem_48k_t; 195 196 197 /** 198 * Return the number of PCM samples in a frame 199 * dt_us Frame duration in us, 7500 or 10000 200 * sr_hz Samplerate in Hz, 8000, 16000, 24000, 32000 or 48000 201 * return Number of PCM samples, -1 on bad parameters 202 */ 203 int lc3_frame_samples(int dt_us, int sr_hz); 204 205 /** 206 * Return the size of frames, from bitrate 207 * dt_us Frame duration in us, 7500 or 10000 208 * bitrate Target bitrate in bit per second 209 * return The floor size in bytes of the frames, -1 on bad parameters 210 */ 211 int lc3_frame_bytes(int dt_us, int bitrate); 212 213 /** 214 * Resolve the bitrate, from the size of frames 215 * dt_us Frame duration in us, 7500 or 10000 216 * nbytes Size in bytes of the frames 217 * return The according bitrate in bps, -1 on bad parameters 218 */ 219 int lc3_resolve_bitrate(int dt_us, int nbytes); 220 221 /** 222 * Return algorithmic delay, as a number of samples 223 * dt_us Frame duration in us, 7500 or 10000 224 * sr_hz Samplerate in Hz, 8000, 16000, 24000, 32000 or 48000 225 * return Number of algorithmic delay samples, -1 on bad parameters 226 */ 227 int lc3_delay_samples(int dt_us, int sr_hz); 228 229 /** 230 * Return size needed for an encoder 231 * dt_us Frame duration in us, 7500 or 10000 232 * sr_hz Samplerate in Hz, 8000, 16000, 24000, 32000 or 48000 233 * return Size of then encoder in bytes, 0 on bad parameters 234 * 235 * The `sr_hz` parameter is the samplerate of the PCM input stream, 236 * and will match `sr_pcm_hz` of `lc3_setup_encoder()`. 237 */ 238 unsigned lc3_encoder_size(int dt_us, int sr_hz); 239 240 /** 241 * Setup encoder 242 * dt_us Frame duration in us, 7500 or 10000 243 * sr_hz Samplerate in Hz, 8000, 16000, 24000, 32000 or 48000 244 * sr_pcm_hz Input samplerate, downsampling option of input, or 0 245 * mem Encoder memory space, aligned to pointer type 246 * return Encoder as an handle, NULL on bad parameters 247 * 248 * The `sr_pcm_hz` parameter is a downsampling option of PCM input, 249 * the value `0` fallback to the samplerate of the encoded stream `sr_hz`. 250 * When used, `sr_pcm_hz` is intended to be higher or equal to the encoder 251 * samplerate `sr_hz`. The size of the context needed, given by 252 * `lc3_encoder_size()` will be set accordingly to `sr_pcm_hz`. 253 */ 254 lc3_encoder_t lc3_setup_encoder( 255 int dt_us, int sr_hz, int sr_pcm_hz, void *mem); 256 257 /** 258 * Encode a frame 259 * encoder Handle of the encoder 260 * fmt PCM input format 261 * pcm, stride Input PCM samples, and count between two consecutives 262 * nbytes Target size, in bytes, of the frame (20 to 400) 263 * out Output buffer of `nbytes` size 264 * return 0: On success -1: Wrong parameters 265 */ 266 int lc3_encode(lc3_encoder_t encoder, enum lc3_pcm_format fmt, 267 const void *pcm, int stride, int nbytes, void *out); 268 269 /** 270 * Return size needed for an decoder 271 * dt_us Frame duration in us, 7500 or 10000 272 * sr_hz Samplerate in Hz, 8000, 16000, 24000, 32000 or 48000 273 * return Size of then decoder in bytes, 0 on bad parameters 274 * 275 * The `sr_hz` parameter is the samplerate of the PCM output stream, 276 * and will match `sr_pcm_hz` of `lc3_setup_decoder()`. 277 */ 278 unsigned lc3_decoder_size(int dt_us, int sr_hz); 279 280 /** 281 * Setup decoder 282 * dt_us Frame duration in us, 7500 or 10000 283 * sr_hz Samplerate in Hz, 8000, 16000, 24000, 32000 or 48000 284 * sr_pcm_hz Output samplerate, upsampling option of output (or 0) 285 * mem Decoder memory space, aligned to pointer type 286 * return Decoder as an handle, NULL on bad parameters 287 * 288 * The `sr_pcm_hz` parameter is an upsampling option of PCM output, 289 * the value `0` fallback to the samplerate of the decoded stream `sr_hz`. 290 * When used, `sr_pcm_hz` is intended to be higher or equal to the decoder 291 * samplerate `sr_hz`. The size of the context needed, given by 292 * `lc3_decoder_size()` will be set accordingly to `sr_pcm_hz`. 293 */ 294 lc3_decoder_t lc3_setup_decoder( 295 int dt_us, int sr_hz, int sr_pcm_hz, void *mem); 296 297 /** 298 * Decode a frame 299 * decoder Handle of the decoder 300 * in, nbytes Input bitstream, and size in bytes, NULL performs PLC 301 * fmt PCM output format 302 * pcm, stride Output PCM samples, and count between two consecutives 303 * return 0: On success 1: PLC operated -1: Wrong parameters 304 */ 305 int lc3_decode(lc3_decoder_t decoder, const void *in, int nbytes, 306 enum lc3_pcm_format fmt, void *pcm, int stride); 307 308 309 #ifdef __cplusplus 310 } 311 #endif 312 313 #endif /* __LC3_H */ 314
