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 */ 130 131 #define LC3_MIN_BITRATE 16000 132 #define LC3_MAX_BITRATE 320000 133 134 #define LC3_MIN_FRAME_BYTES 20 135 #define LC3_MAX_FRAME_BYTES 400 136 137 138 /** 139 * Parameters check 140 * LC3_CHECK_DT_US(us) True when frame duration in us is suitable 141 * LC3_CHECK_SR_HZ(sr) True when samplerate in Hz is suitable 142 */ 143 144 #define LC3_CHECK_DT_US(us) \ 145 ( ((us) == 7500) || ((us) == 10000) ) 146 147 #define LC3_CHECK_SR_HZ(sr) \ 148 ( ((sr) == 8000) || ((sr) == 16000) || ((sr) == 24000) || \ 149 ((sr) == 32000) || ((sr) == 48000) ) 150 151 152 /** 153 * PCM Sample Format 154 * S16 Signed 16 bits, in 16 bits words (int16_t) 155 * S24 Signed 24 bits, using low three bytes of 32 bits words (int32_t). 156 * The high byte sign extends (bits 31..24 set to b23). 157 * S24_3LE Signed 24 bits packed in 3 bytes little endian 158 * FLOAT Floating point 32 bits (float type), in range -1 to 1 159 */ 160 161 enum lc3_pcm_format { 162 LC3_PCM_FORMAT_S16, 163 LC3_PCM_FORMAT_S24, 164 LC3_PCM_FORMAT_S24_3LE, 165 LC3_PCM_FORMAT_FLOAT, 166 }; 167 168 169 /** 170 * Handle 171 */ 172 173 typedef struct lc3_encoder *lc3_encoder_t; 174 typedef struct lc3_decoder *lc3_decoder_t; 175 176 177 /** 178 * Static memory of encoder context 179 * 180 * Propose types suitable for static memory allocation, supporting 181 * any frame duration, and maximum samplerates 16k and 48k respectively 182 * You can customize your type using the `LC3_ENCODER_MEM_T` or 183 * `LC3_DECODER_MEM_T` macro. 184 */ 185 186 typedef LC3_ENCODER_MEM_T(10000, 16000) lc3_encoder_mem_16k_t; 187 typedef LC3_ENCODER_MEM_T(10000, 48000) lc3_encoder_mem_48k_t; 188 189 typedef LC3_DECODER_MEM_T(10000, 16000) lc3_decoder_mem_16k_t; 190 typedef LC3_DECODER_MEM_T(10000, 48000) lc3_decoder_mem_48k_t; 191 192 193 /** 194 * Return the number of PCM samples in a frame 195 * dt_us Frame duration in us, 7500 or 10000 196 * sr_hz Samplerate in Hz, 8000, 16000, 24000, 32000 or 48000 197 * return Number of PCM samples, -1 on bad parameters 198 */ 199 int lc3_frame_samples(int dt_us, int sr_hz); 200 201 /** 202 * Return the size of frames, from bitrate 203 * dt_us Frame duration in us, 7500 or 10000 204 * bitrate Target bitrate in bit per second 205 * return The floor size in bytes of the frames, -1 on bad parameters 206 */ 207 int lc3_frame_bytes(int dt_us, int bitrate); 208 209 /** 210 * Resolve the bitrate, from the size of frames 211 * dt_us Frame duration in us, 7500 or 10000 212 * nbytes Size in bytes of the frames 213 * return The according bitrate in bps, -1 on bad parameters 214 */ 215 int lc3_resolve_bitrate(int dt_us, int nbytes); 216 217 /** 218 * Return algorithmic delay, as a number of samples 219 * dt_us Frame duration in us, 7500 or 10000 220 * sr_hz Samplerate in Hz, 8000, 16000, 24000, 32000 or 48000 221 * return Number of algorithmic delay samples, -1 on bad parameters 222 */ 223 int lc3_delay_samples(int dt_us, int sr_hz); 224 225 /** 226 * Return size needed for an encoder 227 * dt_us Frame duration in us, 7500 or 10000 228 * sr_hz Samplerate in Hz, 8000, 16000, 24000, 32000 or 48000 229 * return Size of then encoder in bytes, 0 on bad parameters 230 * 231 * The `sr_hz` parameter is the samplerate of the PCM input stream, 232 * and will match `sr_pcm_hz` of `lc3_setup_encoder()`. 233 */ 234 unsigned lc3_encoder_size(int dt_us, int sr_hz); 235 236 /** 237 * Setup encoder 238 * dt_us Frame duration in us, 7500 or 10000 239 * sr_hz Samplerate in Hz, 8000, 16000, 24000, 32000 or 48000 240 * sr_pcm_hz Input samplerate, downsampling option of input, or 0 241 * mem Encoder memory space, aligned to pointer type 242 * return Encoder as an handle, NULL on bad parameters 243 * 244 * The `sr_pcm_hz` parameter is a downsampling option of PCM input, 245 * the value `0` fallback to the samplerate of the encoded stream `sr_hz`. 246 * When used, `sr_pcm_hz` is intended to be higher or equal to the encoder 247 * samplerate `sr_hz`. The size of the context needed, given by 248 * `lc3_encoder_size()` will be set accordingly to `sr_pcm_hz`. 249 */ 250 lc3_encoder_t lc3_setup_encoder( 251 int dt_us, int sr_hz, int sr_pcm_hz, void *mem); 252 253 /** 254 * Encode a frame 255 * encoder Handle of the encoder 256 * fmt PCM input format 257 * pcm, stride Input PCM samples, and count between two consecutives 258 * nbytes Target size, in bytes, of the frame (20 to 400) 259 * out Output buffer of `nbytes` size 260 * return 0: On success -1: Wrong parameters 261 */ 262 int lc3_encode(lc3_encoder_t encoder, enum lc3_pcm_format fmt, 263 const void *pcm, int stride, int nbytes, void *out); 264 265 /** 266 * Return size needed for an decoder 267 * dt_us Frame duration in us, 7500 or 10000 268 * sr_hz Samplerate in Hz, 8000, 16000, 24000, 32000 or 48000 269 * return Size of then decoder in bytes, 0 on bad parameters 270 * 271 * The `sr_hz` parameter is the samplerate of the PCM output stream, 272 * and will match `sr_pcm_hz` of `lc3_setup_decoder()`. 273 */ 274 unsigned lc3_decoder_size(int dt_us, int sr_hz); 275 276 /** 277 * Setup decoder 278 * dt_us Frame duration in us, 7500 or 10000 279 * sr_hz Samplerate in Hz, 8000, 16000, 24000, 32000 or 48000 280 * sr_pcm_hz Output samplerate, upsampling option of output (or 0) 281 * mem Decoder memory space, aligned to pointer type 282 * return Decoder as an handle, NULL on bad parameters 283 * 284 * The `sr_pcm_hz` parameter is an upsampling option of PCM output, 285 * the value `0` fallback to the samplerate of the decoded stream `sr_hz`. 286 * When used, `sr_pcm_hz` is intended to be higher or equal to the decoder 287 * samplerate `sr_hz`. The size of the context needed, given by 288 * `lc3_decoder_size()` will be set accordingly to `sr_pcm_hz`. 289 */ 290 lc3_decoder_t lc3_setup_decoder( 291 int dt_us, int sr_hz, int sr_pcm_hz, void *mem); 292 293 /** 294 * Decode a frame 295 * decoder Handle of the decoder 296 * in, nbytes Input bitstream, and size in bytes, NULL performs PLC 297 * fmt PCM output format 298 * pcm, stride Output PCM samples, and count between two consecutives 299 * return 0: On success 1: PLC operated -1: Wrong parameters 300 */ 301 int lc3_decode(lc3_decoder_t decoder, const void *in, int nbytes, 302 enum lc3_pcm_format fmt, void *pcm, int stride); 303 304 305 #ifdef __cplusplus 306 } 307 #endif 308 309 #endif /* __LC3_H */ 310
