mirror of
https://github.com/bluekitchen/btstack.git
synced 2025-01-01 00:28:18 +00:00
424 lines
16 KiB
C
424 lines
16 KiB
C
/******************************************************************************
|
|
*
|
|
* Copyright 2022 Google LLC
|
|
*
|
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
* you may not use this file except in compliance with the License.
|
|
* You may obtain a copy of the License at:
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*
|
|
******************************************************************************/
|
|
|
|
/**
|
|
* Low Complexity Communication Codec (LC3)
|
|
*
|
|
* This implementation conforms to :
|
|
*
|
|
* - Low Complexity Communication Codec (LC3)
|
|
* Bluetooth Specification v1.0
|
|
*
|
|
* - ETSI TS 103 634 v1.4.1
|
|
* Digital Enhanced Cordless Telecommunications (DECT)
|
|
* Low Complexity Communication Codec plus (LC3plus)
|
|
*
|
|
* LC3 and LC3 Plus are audio codecs designed for low-latency audio transport.
|
|
*
|
|
* - Unlike most other codecs, the LC3 codec is focused on audio streaming
|
|
* in constrained (on packet sizes and interval) tranport layer.
|
|
* In this way, the LC3 does not handle :
|
|
* VBR (Variable Bitrate), based on input signal complexity
|
|
* ABR (Adaptative Bitrate). It does not rely on any bit reservoir,
|
|
* a frame will be strictly encoded in the bytes budget given by
|
|
* the user (or transport layer).
|
|
*
|
|
* However, the bitrate (bytes budget for encoding a frame) can be
|
|
* freely changed at any time. But will not rely on signal complexity,
|
|
* it can follow a temporary bandwidth increase or reduction.
|
|
*
|
|
* - Unlike classic codecs, the LC3 codecs does not run on fixed amount
|
|
* of samples as input. It operates only on fixed frame duration, for
|
|
* any supported sample rates (8 to 48 KHz). Two frames duration are
|
|
* available 7.5ms and 10ms.
|
|
*
|
|
*
|
|
* --- LC3 Plus features ---
|
|
*
|
|
* In addition to LC3, following features of LC3 Plus are proposed:
|
|
* - Frame duration of 2.5 and 5ms.
|
|
* - High-Resolution mode, 48 KHz, and 96 kHz sampling rates.
|
|
*
|
|
* The distinction between LC3 and LC3 plus is made according to :
|
|
*
|
|
* Frame Duration | 2.5ms | 5ms | 7.5ms | 10 ms |
|
|
* ---------------- | ----- | ----- | ----- | ----- |
|
|
* LC3 | | | X | X |
|
|
* LC3 Plus | X | X | | X |
|
|
*
|
|
* The 10 ms frame duration is available in LC3 and LC3 plus standard.
|
|
* In this mode, the produced bitstream can be referenced either
|
|
* as LC3 or LC3 plus.
|
|
*
|
|
* The LC3 Plus high-resolution mode should be preferred at high bitrates
|
|
* and larger audio bandwidth. In this mode, the audio bandwidth is always
|
|
* up to the Nyquist frequency, compared to LC3 at 48 KHz, which limits
|
|
* the bandwidth to 20 KHz.
|
|
*
|
|
*
|
|
* --- Bit rate ---
|
|
*
|
|
* The proposed implementation accepts any frame sizes between 20 and 400 Bytes
|
|
* for non-high-resolution mode. Mind that the LC3 Plus standard defines
|
|
* smaller sizes for frame durations shorter than 10 ms and/or sampling rates
|
|
* less than 48 kHz.
|
|
*
|
|
* In High-Resolution mode, the frame sizes (and bitrates) are restricted
|
|
* as follows:
|
|
*
|
|
* HR Configuration | Frame sizes | Bitrate (kbps) |
|
|
* ------------------ | ------------- | -------------- |
|
|
* 10 ms - 48 KHz | 156 to 625 | 124.8 - 500 |
|
|
* 10 ms - 96 KHz | 187 to 625 | 149.6 - 500 |
|
|
* ------------------ | ------------- | -------------- |
|
|
* 5 ms - 48 KHz | 93 to 375 | 148.8 - 600 |
|
|
* 5 ms - 96 KHz | 109 to 375 | 174.4 - 600 |
|
|
* ------------------ | ------------- | -------------- |
|
|
* 2.5 ms - 48 KHz | 54 to 210 | 172.8 - 672 |
|
|
* 2.5 ms - 96 KHz | 62 to 210 | 198.4 - 672 |
|
|
*
|
|
*
|
|
* --- About 44.1 KHz sample rate ---
|
|
*
|
|
* The Bluetooth specification and the ETSI TS 103 634 standard references
|
|
* the 44.1 KHz sample rate, although there is no support in the core algorithm
|
|
* of the codec.
|
|
* We can summarize the 44.1 KHz support by "You can put any sample rate around
|
|
* the defined base sample rates." Please mind the following items :
|
|
*
|
|
* 1. The frame size will not be 2.5ms, 5ms, 7.5 ms or 10 ms, but is scaled
|
|
* by 'supported sample rate' / 'input sample rate'
|
|
*
|
|
* 2. The bandwidth will be hard limited (to 20 KHz) if you select 48 KHz.
|
|
* The encoded bandwidth will also be affected by the above inverse
|
|
* factor of 20 KHz.
|
|
*
|
|
* Applied to 44.1 KHz, we get :
|
|
*
|
|
* 1. About 8.16 ms frame duration, instead of 7.5 ms
|
|
* About 10.88 ms frame duration, instead of 10 ms
|
|
*
|
|
* 2. The bandwidth becomes limited to 18.375 KHz
|
|
*
|
|
*
|
|
* --- How to encode / decode ---
|
|
*
|
|
* An encoder / decoder context needs to be setup. This context keeps states
|
|
* on the current stream to proceed, and samples that overlapped across
|
|
* frames.
|
|
*
|
|
* You have two ways to setup the encoder / decoder :
|
|
*
|
|
* - Using static memory allocation (this module does not rely on
|
|
* any dynamic memory allocation). The types `lc3_xxcoder_mem_16k_t`,
|
|
* and `lc3_xxcoder_mem_48k_t` have size of the memory needed for
|
|
* encoding up to 16 KHz or 48 KHz.
|
|
*
|
|
* - Using dynamic memory allocation. The `lc3_xxcoder_size()` procedure
|
|
* returns the needed memory size, for a given configuration. The memory
|
|
* space must be aligned to a pointer size. As an example, you can setup
|
|
* encoder like this :
|
|
*
|
|
* | enc = lc3_setup_encoder(frame_us, sample rate,
|
|
* | malloc(lc3_encoder_size(frame_us, sample rate)));
|
|
* | ...
|
|
* | free(enc);
|
|
*
|
|
* Note :
|
|
* - A NULL memory adress as input, will return a NULL encoder context.
|
|
* - The returned encoder handle is set at the address of the allocated
|
|
* memory space, you can directly free the handle.
|
|
*
|
|
* Next, call the `lc3_encode()` encoding procedure, for each frames.
|
|
* To handle multichannel streams (Stereo or more), you can proceed with
|
|
* interleaved channels PCM stream like this :
|
|
*
|
|
* | for(int ich = 0; ich < nch: ich++)
|
|
* | lc3_encode(encoder[ich], pcm + ich, nch, ...);
|
|
*
|
|
* with `nch` as the number of channels in the PCM stream
|
|
*
|
|
* ---
|
|
*
|
|
* Antoine SOULIER, Tempow / Google LLC
|
|
*
|
|
*/
|
|
|
|
#ifndef __LC3_H
|
|
#define __LC3_H
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
#include <stdint.h>
|
|
#include <stdbool.h>
|
|
|
|
#include "lc3_private.h"
|
|
|
|
|
|
/**
|
|
* Limitations
|
|
* - On the bitrate, in bps
|
|
* - On the size of the frames in bytes
|
|
* - On the number of samples by frames
|
|
*/
|
|
|
|
#define LC3_MIN_BITRATE 16000
|
|
#define LC3_MAX_BITRATE 320000
|
|
#define LC3_HR_MAX_BITRATE 672000
|
|
|
|
#define LC3_MIN_FRAME_BYTES 20
|
|
#define LC3_MAX_FRAME_BYTES 400
|
|
#define LC3_HR_MAX_FRAME_BYTES 625
|
|
|
|
#define LC3_MIN_FRAME_SAMPLES LC3_NS( 2500, 8000)
|
|
#define LC3_MAX_FRAME_SAMPLES LC3_NS(10000, 48000)
|
|
#define LC3_HR_MAX_FRAME_SAMPLES LC3_NS(10000, 96000)
|
|
|
|
|
|
/**
|
|
* Parameters check
|
|
* LC3_CHECK_DT_US(us) True when frame duration in us is suitable
|
|
* LC3_CHECK_SR_HZ(sr) True when sample rate in Hz is suitable
|
|
*
|
|
* LC3_HR_CHECK_SR_HZ(hrmode, sr)
|
|
* True when sample rate in Hz is suitable, according to the
|
|
* selection of the high-resolution mode `hrmode`.
|
|
*/
|
|
|
|
#define LC3_CHECK_DT_US(us) \
|
|
( ((us) == 2500) || ((us) == 5000) || \
|
|
((us) == 7500) || ((us) == 10000) )
|
|
|
|
#define LC3_CHECK_SR_HZ(sr) \
|
|
( ((sr) == 8000) || ((sr) == 16000) || ((sr) == 24000) || \
|
|
((sr) == 32000) || ((sr) == 48000) )
|
|
|
|
#define LC3_HR_CHECK_SR_HZ(hrmode, sr) \
|
|
( (hrmode) ? ((sr) == 48000) || ((sr) == 96000) : LC3_CHECK_SR_HZ(sr) )
|
|
|
|
|
|
/**
|
|
* PCM Sample Format
|
|
* S16 Signed 16 bits, in 16 bits words (int16_t)
|
|
* S24 Signed 24 bits, using low three bytes of 32 bits words (int32_t).
|
|
* The high byte sign extends (bits 31..24 set to b23).
|
|
* S24_3LE Signed 24 bits packed in 3 bytes little endian
|
|
* FLOAT Floating point 32 bits (float type), in range -1 to 1
|
|
*/
|
|
|
|
enum lc3_pcm_format {
|
|
LC3_PCM_FORMAT_S16,
|
|
LC3_PCM_FORMAT_S24,
|
|
LC3_PCM_FORMAT_S24_3LE,
|
|
LC3_PCM_FORMAT_FLOAT,
|
|
};
|
|
|
|
|
|
/**
|
|
* Handle
|
|
*/
|
|
|
|
typedef struct lc3_encoder *lc3_encoder_t;
|
|
typedef struct lc3_decoder *lc3_decoder_t;
|
|
|
|
|
|
/**
|
|
* Static memory of encoder/decoder contexts
|
|
*
|
|
* Propose types suitable for static memory allocation, supporting
|
|
* any frame duration, and maximum sample rates 16k and 48k respectively
|
|
* You can customize your type using the `LC3_ENCODER_MEM_T` or
|
|
* `LC3_DECODER_MEM_T` macro.
|
|
*/
|
|
|
|
typedef LC3_ENCODER_MEM_T(10000, 16000) lc3_encoder_mem_16k_t;
|
|
typedef LC3_ENCODER_MEM_T(10000, 48000) lc3_encoder_mem_48k_t;
|
|
|
|
typedef LC3_DECODER_MEM_T(10000, 16000) lc3_decoder_mem_16k_t;
|
|
typedef LC3_DECODER_MEM_T(10000, 48000) lc3_decoder_mem_48k_t;
|
|
|
|
|
|
/**
|
|
* Return the number of PCM samples in a frame
|
|
* hrmode Enable High-Resolution mode (48000 and 96000 sample rates)
|
|
* dt_us Frame duration in us, 2500, 5000, 7500 or 10000
|
|
* sr_hz Sample rate in Hz, 8000, 16000, 24000, 32000, 48000 or 96000
|
|
* return Number of PCM samples, -1 on bad parameters
|
|
*/
|
|
LC3_EXPORT int lc3_hr_frame_samples(bool hrmode, int dt_us, int sr_hz);
|
|
|
|
LC3_EXPORT int lc3_frame_samples(int dt_us, int sr_hz);
|
|
|
|
/**
|
|
* Return the size of frames, from bitrate
|
|
* hrmode Enable High-Resolution mode (48000 and 96000 sample rates)
|
|
* dt_us Frame duration in us, 2500, 5000, 7500 or 10000
|
|
* sr_hz Sample rate in Hz, 8000, 16000, 24000, 32000, 48000 or 96000
|
|
* bitrate Target bitrate in bit per second, 0 or `INT_MAX` returns
|
|
* respectively the minimum and maximum allowed size.
|
|
* return The floor size in bytes of the frames, -1 on bad parameters
|
|
*/
|
|
LC3_EXPORT int lc3_hr_frame_bytes(
|
|
bool hrmode, int dt_us, int sr_hz, int bitrate);
|
|
|
|
LC3_EXPORT int lc3_frame_bytes(int dt_us, int bitrate);
|
|
|
|
/**
|
|
* Return the size of frame blocks, from bitrate
|
|
* A frame block contains the frame data from all channels.
|
|
* hrmode Enable High-Resolution mode (48000 and 96000 sample rates)
|
|
* dt_us Frame duration in us, 2500, 5000, 7500 or 10000
|
|
* sr_hz Sample rate in Hz, 8000, 16000, 24000, 32000, 48000 or 96000
|
|
* nchannels The number of channels (or frames) in the block (<= 8)
|
|
* bitrate Target bitrate in bit per second, 0 or `INT_MAX` returns
|
|
* respectively the minimum and maximum allowed size.
|
|
* return The floor size in bytes of the frames, -1 on bad parameters
|
|
*/
|
|
LC3_EXPORT int lc3_hr_frame_block_bytes(
|
|
bool hrmode, int dt_us, int sr_hz, int nchannels, int bitrate);
|
|
|
|
LC3_EXPORT int lc3_frame_block_bytes(int dt_us, int nframes, int bitrate);
|
|
|
|
/**
|
|
* Resolve the bitrate, from the size of frames
|
|
* hrmode Enable High-Resolution mode (48000 and 96000 sample rates)
|
|
* dt_us Frame duration in us, 2500, 5000, 7500 or 10000
|
|
* sr_hz Sample rate in Hz, 8000, 16000, 24000, 32000, 48000 or 96000
|
|
* nbytes Size in bytes of the frames or frame blocks
|
|
* return The ceiled bitrate in bps, -1 on bad parameters
|
|
*/
|
|
LC3_EXPORT int lc3_hr_resolve_bitrate(
|
|
bool hrmode, int dt_us, int sr_hz, int nbytes);
|
|
|
|
LC3_EXPORT int lc3_resolve_bitrate(int dt_us, int nbytes);
|
|
|
|
/**
|
|
* Return algorithmic delay, as a number of samples
|
|
* hrmode Enable High-Resolution mode (48000 and 96000 sample rates)
|
|
* dt_us Frame duration in us, 2500, 5000, 7500 or 10000
|
|
* sr_hz Sample rate in Hz, 8000, 16000, 24000, 32000, 48000 or 96000
|
|
* return Number of algorithmic delay samples, -1 on bad parameters
|
|
*/
|
|
LC3_EXPORT int lc3_hr_delay_samples(bool hrmode, int dt_us, int sr_hz);
|
|
|
|
LC3_EXPORT int lc3_delay_samples(int dt_us, int sr_hz);
|
|
|
|
/**
|
|
* Return size needed for an encoder
|
|
* hrmode Enable High-Resolution mode (48000 and 96000 sample rates)
|
|
* dt_us Frame duration in us, 2500, 5000, 7500 or 10000
|
|
* sr_hz Sample rate in Hz, 8000, 16000, 24000, 32000, 48000 or 96000
|
|
* return Size of then encoder in bytes, 0 on bad parameters
|
|
*
|
|
* The `sr_hz` parameter is the sample rate of the PCM input stream,
|
|
* and will match `sr_pcm_hz` of `lc3_hr_setup_encoder()`.
|
|
*/
|
|
LC3_EXPORT unsigned lc3_hr_encoder_size(bool hrmode, int dt_us, int sr_hz);
|
|
|
|
LC3_EXPORT unsigned lc3_encoder_size(int dt_us, int sr_hz);
|
|
|
|
/**
|
|
* Setup encoder
|
|
* hrmode Enable High-Resolution mode (48000 and 96000 sample rates)
|
|
* dt_us Frame duration in us, 2500, 5000, 7500 or 10000
|
|
* sr_hz Sample rate in Hz, 8000, 16000, 24000, 32000, 48000 or 96000
|
|
* sr_pcm_hz Input sample rate, downsampling option of input, or 0
|
|
* mem Encoder memory space, aligned to pointer type
|
|
* return Encoder as an handle, NULL on bad parameters
|
|
*
|
|
* The `sr_pcm_hz` parameter is a downsampling option of PCM input,
|
|
* the value `0` fallback to the sample rate of the encoded stream `sr_hz`.
|
|
* When used, `sr_pcm_hz` is intended to be higher or equal to the encoder
|
|
* sample rate `sr_hz`. The size of the context needed, given by
|
|
* `lc3_hr_encoder_size()` will be set accordingly to `sr_pcm_hz`.
|
|
*/
|
|
LC3_EXPORT lc3_encoder_t lc3_hr_setup_encoder(
|
|
bool hrmode, int dt_us, int sr_hz, int sr_pcm_hz, void *mem);
|
|
|
|
LC3_EXPORT lc3_encoder_t lc3_setup_encoder(
|
|
int dt_us, int sr_hz, int sr_pcm_hz, void *mem);
|
|
|
|
/**
|
|
* Encode a frame
|
|
* encoder Handle of the encoder
|
|
* fmt PCM input format
|
|
* pcm, stride Input PCM samples, and count between two consecutives
|
|
* nbytes Target size, in bytes, of the frame
|
|
* out Output buffer of `nbytes` size
|
|
* return 0: On success -1: Wrong parameters
|
|
*/
|
|
LC3_EXPORT int lc3_encode(
|
|
lc3_encoder_t encoder, enum lc3_pcm_format fmt,
|
|
const void *pcm, int stride, int nbytes, void *out);
|
|
|
|
/**
|
|
* Return size needed for an decoder
|
|
* hrmode Enable High-Resolution mode (48000 and 96000 sample rates)
|
|
* dt_us Frame duration in us, 2500, 5000, 7500 or 10000
|
|
* sr_hz Sample rate in Hz, 8000, 16000, 24000, 32000, 48000 or 96000
|
|
* return Size of then decoder in bytes, 0 on bad parameters
|
|
*
|
|
* The `sr_hz` parameter is the sample rate of the PCM output stream,
|
|
* and will match `sr_pcm_hz` of `lc3_hr_setup_decoder()`.
|
|
*/
|
|
LC3_EXPORT unsigned lc3_hr_decoder_size(bool hrmode, int dt_us, int sr_hz);
|
|
|
|
LC3_EXPORT unsigned lc3_decoder_size(int dt_us, int sr_hz);
|
|
|
|
/**
|
|
* Setup decoder
|
|
* hrmode Enable High-Resolution mode (48000 and 96000 sample rates)
|
|
* dt_us Frame duration in us, 2500, 5000, 7500 or 10000
|
|
* sr_hz Sample rate in Hz, 8000, 16000, 24000, 32000, 48000 or 96000
|
|
* sr_pcm_hz Output sample rate, upsampling option of output (or 0)
|
|
* mem Decoder memory space, aligned to pointer type
|
|
* return Decoder as an handle, NULL on bad parameters
|
|
*
|
|
* The `sr_pcm_hz` parameter is an upsampling option of PCM output,
|
|
* the value `0` fallback to the sample rate of the decoded stream `sr_hz`.
|
|
* When used, `sr_pcm_hz` is intended to be higher or equal to the decoder
|
|
* sample rate `sr_hz`. The size of the context needed, given by
|
|
* `lc3_hr_decoder_size()` will be set accordingly to `sr_pcm_hz`.
|
|
*/
|
|
LC3_EXPORT lc3_decoder_t lc3_hr_setup_decoder(
|
|
bool hrmode, int dt_us, int sr_hz, int sr_pcm_hz, void *mem);
|
|
|
|
LC3_EXPORT lc3_decoder_t lc3_setup_decoder(
|
|
int dt_us, int sr_hz, int sr_pcm_hz, void *mem);
|
|
|
|
/**
|
|
* Decode a frame
|
|
* decoder Handle of the decoder
|
|
* in, nbytes Input bitstream, and size in bytes, NULL performs PLC
|
|
* fmt PCM output format
|
|
* pcm, stride Output PCM samples, and count between two consecutives
|
|
* return 0: On success 1: PLC operated -1: Wrong parameters
|
|
*/
|
|
LC3_EXPORT int lc3_decode(
|
|
lc3_decoder_t decoder, const void *in, int nbytes,
|
|
enum lc3_pcm_format fmt, void *pcm, int stride);
|
|
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* __LC3_H */
|