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