API documentation

Translation layer API documentation
LC3 API documentation

Translation layer API documentation 

Header file: lc3/include/sw_codec_lc3.h

Source file: lc3/src/sw_codec_lc3.c

group LC3_translation

Functions

int sw_codec_lc3_enc_run(void const *const pcm_data, uint32_t pcm_data_size, uint32_t enc_bitrate, uint8_t audio_ch, uint16_t lc3_data_buf_size, uint8_t *const lc3_data, uint16_t *const lc3_data_wr_size)

Runs the LC3 encoder.

Note

The return codes from Zephyr and LC3 may overlap.

Parameters

pcm_data – [in] Buffer containing PCM data
pcm_data_size – [in] Number of bytes in pcm_data. Note that pcm_data is uint16_t *.
enc_bitrate – [in] Bitrate of encoded mono stream (bps). If set to LC3_USE_BITRATE_FROM_INIT the bitrate given to sw_codec_lc3_enc_init() will be used. Consult the LC3 doc for legal values.
audio_ch – [in] Index to which channel is being encoded
lc3_data_buf_size – [in] Size of supplied LC3 buffer.
lc3_data – [out] Pointer to LC3 data output buffer.
lc3_data_wr_size – [out] Number of bytes written to lc3_data.

Returns

0 on success. -EPERM Encoder is not initialized. -EINVAL Too few PCM bytes given to encode. Other errors. Refer to LC3 documentation.

int sw_codec_lc3_dec_run(uint8_t const *const lc3_data, uint16_t lc3_data_size, uint16_t pcm_data_buf_size, uint8_t audio_ch, void *const pcm_data, uint16_t *const pcm_data_wr_size, bool bad_frame)

Runs the LC3 decoder.

Note

The return codes from Zephyr and LC3 may overlap.

Parameters

lc3_data – [in] Buffer containing LC3 data.
lc3_data_size – [in] Number of bytes in lc3_data.
pcm_data_buf_size – [in] Size of supplied pcm_data buffer
audio_ch – [in] Index to which channel is being decoded
pcm_data – [out] Pointer to PCM data output buffer.
pcm_data_wr_size – [out] Number of bytes written to pcm_data
bad_frame – [out] Bad frame indicator. Refer to LC3 doc.

Returns

0 on success. -EPERM Decoder is not initialized. Other errors. Refer to LC3 documentation.

int sw_codec_lc3_enc_uninit_all(void)

Closes the LC3 encoder and frees allocated RAM.

Returns: 0 on success. -EALREADY if already un-initialized.

int sw_codec_lc3_dec_uninit_all(void)

Closes the LC3 decoder and frees allocated RAM.

Returns: 0 on success. -EALREADY if already un-initialized.

int sw_codec_lc3_init(uint8_t *sw_codec_lc3_buffer, uint32_t *sw_codec_lc3_buffer_size, uint16_t framesize_us): Initializes the LC3 Codec.

Note

: For documentation, see LC3API.h (/codec/inc/LC3API.h)

int sw_codec_lc3_enc_init(uint16_t pcm_sample_rate, uint8_t pcm_bit_depth, uint16_t framesize_us, uint32_t enc_bitrate, uint8_t num_channels, uint16_t *const pcm_bytes_req)

Initializes the LC3 encoder and allocates required RAM.

Note

The return codes from Zephyr and LC3 may overlap.

Parameters

pcm_sample_rate – [in] Sample rate in Hz (typ. 16000 or 48000)
pcm_bit_depth – [in] Number of bits in sample (typ. 16 or 24)
framesize_us – [in] Frame size in microseconds
enc_bitrate – [in] Bitrate of encoded mono stream (bps) (typ. 24000 - 160000). Consult the LC3 doc for legal values.
num_channels – [in] Number of channels to initialize
pcm_bytes_req – [out] PCM bytes required to encode a frame.

Returns

0 on success. -EALREADY if already initialized. -EPERM 0 bytes required from PCM sample. Other errors. Refer to LC3 documentation.

int sw_codec_lc3_dec_init(uint16_t pcm_sample_rate, uint8_t pcm_bit_depth, uint16_t framesize_us, uint8_t num_channels)

Initializes the LC3 decoder and allocates required RAM.

Note

The return codes from Zephyr and LC3 may overlap.

Parameters

pcm_sample_rate – [in] Sample rate in Hz (typ. 16000 or 48000)
pcm_bit_depth – [in] Output PCM bits per sample.
framesize_us – [in] Frame size in microseconds
num_channels – [in] Number of channels to initialize

Returns

0 on success. -EALREADY if already initialized. Other errors. Refer to LC3 documentation.

LC3 API documentation 

Header file: codec/inc/LC3API.h

group LC3

LC3 Result Codes

LC3_ERROR_OFFSET: Offset for LC3 error values.

LC3_RESULT_NO_ERROR: Success.

LC3_RESULT_INVALID_PARAMETER: Error: invalid parameter detected.

LC3_RESULT_INSUFFICIENT_RESOURCES: Error: not enough memory available.

LC3_RESULT_NOT_INITIALIZED: Error: not initialized before use.

LC3_RESULT_UNKNOWN_ERROR: Error: unknown error detected.

LC3_RESULT_INVALID_BITRATE: Error: invalid bitrate value.

LC3_RESULT_INPUT_BUFFER_TOO_SMALL: Error: passed buffer size too small for input data.

LC3_RESULT_OUTPUT_BUFFER_TOO_SMALL: Error: passed buffer size too small for output data.

LC3_RESULT_INVALID_BITSPERSAMPLE: Error: invalid bits per sample value.

LC3_RESULT_INVALID_SAMPLERATE: Error: invalid sample rate value.

LC3_RESULT_BITERRORCONDITION: Error: bit error condition detected in bit stream data.

LC3_RESULT_FEATURE_NOT_SUPPORTED: Error: feature not supported in this build.

LC3_RESULT_STILL_IN_USE: Error: Sessions not closed, buffer still in use.

LC3_RESULT_ALREADY_INITIALIZED: Error: Codec already initialized, call LC3Deinitialize first.

LC3 Sample Rate Bits

LC3_SAMPLE_RATE_NONE: No sample rate selected.

LC3_SAMPLE_RATE_8_KHZ: 8 kHz sample rate bit.

LC3_SAMPLE_RATE_16_KHZ: 16 kHz sample rate bit.

LC3_SAMPLE_RATE_24_KHZ: 24 kHz sample rate bit.

LC3_SAMPLE_RATE_32_KHZ: 32 kHz sample rate bit.

LC3_SAMPLE_RATE_441_KHZ: 44.1 kHz sample rate bit.

LC3_SAMPLE_RATE_48_KHZ: 48 kHz sample rate bit.

LC3_SAMPLE_RATE_ALL: All sample rates selected.

Typedefs

typedef void *LC3EncoderHandle_t: LC3 encoder handle type.

typedef void *LC3DecoderHandle_t: LC3 decoder handle type.

Enums

enum LC3FrameSizeConfig_t

Frame Size for configuration.

Defines the frame size used for global memory configuration purposes. Select the specific frame size if only one will be used, otherwise select both and the session open call will define which is used for a session.

Values:

enumerator LC3FrameSize10MsConfig: 10 msec frame size.

enumerator LC3FrameSize7_5MsConfig: 7.5 msec frame size.

enumerator LC3FrameSizeBothConfig: 7.5 and 10 msec frame size.

enum LC3FrameSize_t

Session Frame Size.

Defines the valid frame sizes for an LC3 codec session.

Values:

enumerator LC3FrameSize10Ms: 10 msec frame size.

enumerator LC3FrameSize7_5Ms: 7.5 msec frame size.

enum LC3BFI_t

Bad Frame Indicator (BFI).

Identifies a bit stream data frame’s status as known by the device. A frame known to contain bit errors or be otherwise corrupted should be passed with the BadFrame value when passed to the LC3 decoder. The decoder will detect bit errors internally and apply PLC automatically, but if the caller knows that the frame is in error, such as from information indicated by a Bluetooth controller, then this value is used to skip decoding and immediately execute packet loss concealment.

Values:

enumerator GoodFrame

enumerator BadFrame

Functions

int32_t LC3Initialize(uint8_t encoderSampleRates, uint8_t decoderSampleRates, LC3FrameSizeConfig_t frameSizeConfig, uint8_t uniqueSessions, uint8_t *buffer, uint32_t *bufferSize)

Initializes the LC3 Codec.

This function initializes the LC3 codec for the sample rates(s) specified in the encoder/decoder sample rate parameter bit masks. The sample rate bits are defined in LC3SampleRateBits. The user must provide all required encoder/decoder sample rates to this function. If the exact sample rates are unknown, the LC3_SAMPLE_RATE_ALL value should be entered.

frameSizeConfig defines if the codec will support 7.5 msec frames, 10 msec frames or both. If the frame size isn’t known in advance, setting this to both allows each session to use either 7.5 or 10 msec but will use more memory.

The uniqueSessions value is the number of unique (sample rates * frame sizes) sessions expected to be used simultaneously; the sample rates of 48k and 44.1k are considered a single sample rate for this calculation. If nothing is known of the expected sessions’ sample rates and/or frame sizes, this can be set to the number of simultaneous encode + decode sessions. Setting this to the total number of (unique sample rates * frame sizes) will initialize data tables globally, otherwise they will be initialized as needed when sessions are opened.

When LC3_SAMPLE_RATE_ALL and/or LC3FrameSizeBothConfig are used and the uniqueSessions value is less than the number of (sample rates * frame sizes), the codec allocates the worse case shared memory required based on the uniqueSessions value. The LC3EncodeSessionOpen and/or LC3DecodeSessionOpen call initializes the tables required for each session’s sample rate and frame size. In general, the smallest memory footprint will be achieved by defining the sample rate bit fields and a single frame size.

This function can allocate its own memory or take a user-provided buffer. It can also return the amount of memory needed without initializing. These memory options are performed in the following ways:

bufferSize = NULL: Allocates memory needed. The buffer parameter may be NULL.

*bufferSize < memory required by codec: Sets bufferSize’s referenced value to the total memory required and returns LC3_RESULT_INSUFFICIENT_RESOURCES. The caller can then call this function again with a buffer of at least bufferSize’s referenced value. A size of 0 will always trigger this condition. The buffer parameter may be NULL.

*bufferSize >= memory required by codec: Uses the user-provided buffer. bufferSize’s referenced value is set to the amount of memory used by the codec. The buffer parameter may not be NULL.

Parameters

encoderSampleRates – [in] Bitfield containing all encoder session sample rates required.
decoderSampleRates – [in] Bitfield containing all decoder session sample rates required.
frameSizeConfig – [in] Frame size of 7.5, 10 msec or both.
uniqueSessions – [in] The number of unique simultaneous sample rate * frame size sessions.
buffer – [in] Pointer to a memory buffer.
bufferSize – [inout] Size of the memory buffer passed in, number of bytes used returned.

Returns

Zero on success or one of the defined LC3 result codes on error.

int32_t LC3Deinitialize(void)

Deinitializes the LC3 Codec.

This function deinitializes the LC3 Codec. All encoder and decoder sessions should be closed before calling this function. Memory passed in the LC3Initialize’s buffer parameter can be freed only after this function returns LC3_RESULT_NO_ERROR. If LC3Initialize allocated memory internally, that memory will be freed upon a successful call to this function.

If the result code LC3_RESULT_STILL_IN_USE is returned, there are still open sessions. No related resources are freed until all sessions associated with the handle are closed.

Returns: Zero on success or one of the defined LC3 result codes on error.

LC3EncoderHandle_t LC3EncodeSessionOpen(uint16_t sampleRate, uint8_t bitsPerSample, LC3FrameSize_t frameSize, uint8_t *buffer, uint16_t *bufferSize, int32_t *result)

Opens and initializes an LC3 Encoder session.

This function initializes the LC3 encoder in preparation for encoding one stream of audio. It allocates the memory needed for the session’s processing, including any used for tracking progress from frame to frame, and initializes the allocated memory.

A non-NULL handle to the encoder session is returned when successful. The handle value is passed to future calls of LC3EncodeSessionData() and LC3EncodeSessionClose() for this session.

This function can allocate its own memory or take a user-provided buffer. It can also return the amount of memory needed without initializing. These memory options are performed in the following ways:

bufferSize = NULL: Allocates memory needed. The buffer parameter may be NULL.

*bufferSize < memory required by encoder: Sets bufferSize’s referenced value to the total memory required and returns LC3_RESULT_INSUFFICIENT_RESOURCES. The caller can then call this function again with a buffer of at least bufferSize’s referenced value. A size of 0 will always trigger this condition. The buffer parameter may be NULL.

*bufferSize >= memory required by encoder: Uses the user-provided buffer. bufferSize’s referenced value is set to the amount of memory used by the encoder. The buffer parameter may not be NULL.

Parameters

sampleRate – [in] Input PCM sample rate in Hz.
bitsPerSample – [in] Input PCM bits per sample.
frameSize – [in] Frame size of 7.5 or 10 msec.
buffer – [in] Pointer to a memory buffer.
bufferSize – [inout] Size of the memory buffer passed in, number of bytes used returned.
result – [out] Pointer to an LC3 Return Code integer.

Returns

Non-NULL LC3EncoderHandle_t on success or NULL on failure.

int32_t LC3EncodeSessionData(LC3EncoderHandle_t encodeHandle, LC3EncodeInput_t *encodeInput, LC3EncodeOutput_t *encodeOutput)

Encodes a frame of data using LC3.

This function processes the audio frame data passed in the encodeInput structure. It returns the encoded data in the encodeOutput structure.

Parameters

encodeHandle – [in] Handle to an encoder instance.
encodeInput – [in] Pointer to a structure pointing to the frame’s audio samples to encode.
encodeOutput – [in] Pointer to a structure to receive the frame’s encoded data.

Returns

Zero on success or one of the defined LC3 result codes on error.

void LC3EncodeSessionClose(LC3EncoderHandle_t encodeHandle)

Closes an LC3 Encoder session.

This function closes the encodeHandle’s session and releases allocated session memory. Memory passed in the LC3EncodeSessionOpen’s buffer parameter can be freed after this returns. The encodeHandle is no longer valid and should not be reused.

Parameters

encodeHandle – [in] Handle to the encoder instance to close.

Returns

None.

LC3DecoderHandle_t LC3DecodeSessionOpen(uint16_t sampleRate, uint8_t bitsPerSample, LC3FrameSize_t frameSize, uint8_t *buffer, uint16_t *bufferSize, int32_t *result)

Opens and initializes an LC3 Decoder session.

This function initializes the LC3 decoder in preparation for decoding one stream of audio. It allocates the memory needed for the session’s processing, including any used for tracking progress from frame to frame, and initializes the allocated memory.

A non-NULL handle to the decoder session is returned when successful. The handle value is passed to future calls of LC3DecodeSessionData() and LC3DecodeSessionClose() for this session.

This function can allocate its own memory or take a user-provided buffer. It can also return the amount of memory needed without initializing. These memory options are performed in the following ways:

bufferSize = NULL: Allocates memory needed. The buffer parameter may be NULL.

*bufferSize < memory required by decoder: Sets bufferSize’s referenced value to the total memory required and returns LC3_RESULT_INSUFFICIENT_RESOURCES. The caller can then call this function again with a buffer of at least bufferSize’s referenced value. A size of 0 will always trigger this condition. The buffer parameter may be NULL.

*bufferSize >= memory required by decoder: Uses the user-provided buffer. bufferSize’s referenced value is set to the amount of memory used by the decoder. The buffer parameter may not be NULL.

Parameters

sampleRate – [in] Output PCM sample rate in Hz.
bitsPerSample – [in] Output PCM bits per sample.
frameSize – [in] Frame size of 7.5 or 10 msec.
buffer – [in] Pointer to a memory buffer.
bufferSize – [inout] Size of the memory buffer passed in, number of bytes used returned.
result – [out] Pointer to an LC3 Return Code integer value.

Returns

Non-NULL LC3DecoderHandle_t on success or NULL on failure.

int32_t LC3DecodeSessionData(LC3DecoderHandle_t decodeHandle, LC3DecodeInput_t *decodeInput, LC3DecodeOutput_t *decodeOutput)

Decodes a frame of data using LC3.

Processes the frame of encoded bit stream data passed by the decodeInput structure. Returns the decoded audio PCM data via the decodeOutput structure.

This function will automatically apply packet loss concealment (PLC) to any frame where the decode input’s badFrameIndicator is set to BadFrame or if the bit stream data contains errors. The caller should set badFrameIndicator to BadFrame if the caller knows in advance of bit stream errors; this allows the decoder to skip decoding and directly apply PLC. If the caller is unaware of bit stream errors, but they are present, the decoder will detect them regardless. When PLC is applied successfully, this function still returns LC3_RESULT_NO_ERROR as when a frame is decoded successfully, but the decode output’s PLCCounter parameter is incremented. Upon a successful decode, PLCCounter is reset. Therefore, a non-zero PLCCounter indicates PLC has been applied to the current frame.

Parameters

decodeHandle – [in] Handle to a decoder instance.
decodeInput – [in] Pointer to a structure pointing to the encoded bit stream frame to decode.
decodeOutput – [in] Pointer to a structure to receive the frame’s decoded PCM data.

Returns

Zero on success or one of the defined LC3 result codes on error.

void LC3DecodeSessionClose(LC3DecoderHandle_t decodeHandle)

Closes an LC3 Decoder session.

This function closes the decodeHandle’s session and and releases allocated session memory. Memory passed in the LC3DecodeSessionOpen’s buffer parameter can be freed after this returns. The decodeHandle is no longer valid and should not be reused.

Parameters

decodeHandle – [in] Handle to the decoder instance to close.

Returns

None.

uint16_t LC3BitstreamBuffersize(uint16_t sampleRate, uint32_t maxBitRate, LC3FrameSize_t frameSize, int32_t *result)

Calculates the buffer size required for bit stream data.

Returns the minimum buffer size in bytes needed to hold a frame of bit stream data for the specified sample rate and bit rate.

The maxBitRate parameter is the maximum bitrate value that will be passed to LC3EncodeSessionData() at any point during the session’s encoding.

Parameters

sampleRate – [in] Sample rate.
maxBitRate – [in] Session’s maximum encoding bit rate.
frameSize – [in] Frame size of 7.5 or 10 msec.
result – [out] Pointer to an LC3 Return Code integer.

Returns

Bit stream buffer size on success or 0 on error.

uint16_t LC3PCMBuffersize(uint16_t sampleRate, uint8_t bitDepth, LC3FrameSize_t frameSize, int32_t *result)

Calculates the buffer size required for PCM data.

Returns the minimum buffer size in bytes needed to hold a frame of PCM data for the specified sample rate and bit depth. A bitDepth value in the range (16,24] uses a 3 byte/sample PCM output while (24,32] uses 4 bytes/sample.

Parameters

sampleRate – [in] Sample rate.
bitDepth – [in] Bit depth of generated PCM data.
frameSize – [in] Frame size of 7.5 or 10 msec.
result – [out] Pointer to an LC3 Return Code integer.

Returns

PCM buffer size on success or 0 on error.

struct LC3EncodeInput_t

#include <LC3API.h>

LC3 encoder input PCM data structure.

Structure used to pass an audio frame to the encoder. Incoming PCM samples must be linear with a bit depth rounded to the nearest byte. A bit depth of 16 uses 2 bytes per sample, bit depths of 17-24 use 3 bytes per sample, and bit depths of 25-32 use 4 bytes per sample. The number of PCM bytes needed per frame can be calculated using LC3PCMBuffersize().

Public Members

const void *PCMData: Pointer to the PCM data to encode.

uint16_t PCMDataLength: Length of PCM data in bytes.

uint32_t encodeBitrate: Bit rate, in bits per second, at which to encode frame.

uint16_t bytesRead: Number of PCM data bytes read.

struct LC3EncodeOutput_t

#include <LC3API.h>

LC3 encoder output data structure.

Structure that holds the LC3 encoder output. The output buffer is externally allocated and its pointer and available byte length are passed into the LC3 Encoder. The number of output bit stream data bytes can be calculated with LC3BitstreamBuffersize().

Public Members

uint8_t *outputData: Output buffer pointer.

uint16_t outputDataLength: Output buffer size in bytes.

uint16_t bytesWritten: Number of bit stream bytes written.

struct LC3DecodeInput_t

#include <LC3API.h>

LC3 decoder input bit stream structure.

Structure used to pass a frame of incoming bit stream data to the LC3 decoder. If there is a known problem with the frame, such as an error condition indicated by a Bluetooth controller, then badFrameIndicator should be set to BadFrame. inputDataLength must represent the number of bytes exactly in the frame to be decoded.

Public Members

const uint8_t *inputData: Pointer to the input LC3 data to decode.

uint16_t inputDataLength: Number of data bytes in the encoded frame.

LC3BFI_t badFrameIndicator: Frame condition as detected by device.

struct LC3DecodeOutput_t

#include <LC3API.h>

LC3 decoder output PCM structure.

This structure is used to hold the decoded PCM audio samples of an audio stream. The buffer is externally allocated and its pointer and size are passed to the LC3 decoder. bytesWritten contains the number of bytes written to the buffer. The number of PCM bytes needed per frame can be calculated with LC3PCMBuffersize(). If PLC has been applied to the frame, PLCCounter will increment by one. A frame decoded without any bit errors resets PLCCounter to zero.

Public Members

void *PCMData: Output buffer pointer.

uint16_t PCMDataLength: Output buffer size in bytes.

uint16_t bytesWritten: Number of bytes written to the output buffer.

uint16_t PLCCounter: Number of successive frames to which PLC has been applied.

API documentation

Translation layer API documentation

LC3 API documentation

Translation layer API documentation 

LC3 API documentation 