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