@mentra/bluetooth-sdk 0.1.0

package/ios/Packages/CoreObjC/lc3.h

@@ -0,0 +1,313 @@
+/******************************************************************************
+ *
+ *  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
+ *
+ *
+ * The LC3 is an efficient low latency audio codec.
+ *
+ * - 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 samplerates (8 to 48 KHz). Two frames duration are
+ *   available 7.5ms and 10ms.
+ *
+ *
+ * --- About 44.1 KHz samplerate ---
+ *
+ * The Bluetooth specification reference the 44.1 KHz samplerate, although
+ * there is no support in the core algorithm of the codec of 44.1 KHz.
+ * We can summarize the 44.1 KHz support by "you can put any samplerate
+ * around the defined base samplerates". Please mind the following items :
+ *
+ *   1. The frame size will not be 7.5 ms or 10 ms, but is scaled
+ *      by 'supported samplerate' / 'input samplerate'
+ *
+ *   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, samplerate,
+ *   |      malloc(lc3_encoder_size(frame_us, samplerate)));
+ *   | ...
+ *   | 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, of a stream
+ * - 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_MIN_FRAME_BYTES        20
+#define LC3_MAX_FRAME_BYTES       400
+
+#define LC3_MIN_FRAME_SAMPLES  __LC3_NS( 7500,  8000)
+#define LC3_MAX_FRAME_SAMPLES  __LC3_NS(10000, 48000)
+
+
+/**
+ * Parameters check
+ *   LC3_CHECK_DT_US(us)  True when frame duration in us is suitable
+ *   LC3_CHECK_SR_HZ(sr)  True when samplerate in Hz is suitable
+ */
+
+#define LC3_CHECK_DT_US(us) \
+    ( ((us) == 7500) || ((us) == 10000) )
+
+#define LC3_CHECK_SR_HZ(sr) \
+    ( ((sr) ==  8000) || ((sr) == 16000) || ((sr) == 24000) || \
+      ((sr) == 32000) || ((sr) == 48000)                       )
+
+
+/**
+ * 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 context
+ *
+ * Propose types suitable for static memory allocation, supporting
+ * any frame duration, and maximum samplerates 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
+ * dt_us           Frame duration in us, 7500 or 10000
+ * sr_hz           Samplerate in Hz, 8000, 16000, 24000, 32000 or 48000
+ * return          Number of PCM samples, -1 on bad parameters
+ */
+int lc3_frame_samples(int dt_us, int sr_hz);
+
+/**
+ * Return the size of frames, from bitrate
+ * dt_us           Frame duration in us, 7500 or 10000
+ * bitrate         Target bitrate in bit per second
+ * return          The floor size in bytes of the frames, -1 on bad parameters
+ */
+int lc3_frame_bytes(int dt_us, int bitrate);
+
+/**
+ * Resolve the bitrate, from the size of frames
+ * dt_us           Frame duration in us, 7500 or 10000
+ * nbytes          Size in bytes of the frames
+ * return          The according bitrate in bps, -1 on bad parameters
+ */
+int lc3_resolve_bitrate(int dt_us, int nbytes);
+
+/**
+ * Return algorithmic delay, as a number of samples
+ * dt_us           Frame duration in us, 7500 or 10000
+ * sr_hz           Samplerate in Hz, 8000, 16000, 24000, 32000 or 48000
+ * return          Number of algorithmic delay samples, -1 on bad parameters
+ */
+int lc3_delay_samples(int dt_us, int sr_hz);
+
+/**
+ * Return size needed for an encoder
+ * dt_us           Frame duration in us, 7500 or 10000
+ * sr_hz           Samplerate in Hz, 8000, 16000, 24000, 32000 or 48000
+ * return          Size of then encoder in bytes, 0 on bad parameters
+ *
+ * The `sr_hz` parameter is the samplerate of the PCM input stream,
+ * and will match `sr_pcm_hz` of `lc3_setup_encoder()`.
+ */
+unsigned lc3_encoder_size(int dt_us, int sr_hz);
+
+/**
+ * Setup encoder
+ * dt_us           Frame duration in us, 7500 or 10000
+ * sr_hz           Samplerate in Hz, 8000, 16000, 24000, 32000 or 48000
+ * sr_pcm_hz       Input samplerate, 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 samplerate of the encoded stream `sr_hz`.
+ * When used, `sr_pcm_hz` is intended to be higher or equal to the encoder
+ * samplerate `sr_hz`. The size of the context needed, given by
+ * `lc3_encoder_size()` will be set accordingly to `sr_pcm_hz`.
+ */
+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 (20 to 400)
+ * out             Output buffer of `nbytes` size
+ * return          0: On success  -1: Wrong parameters
+ */
+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
+ * dt_us           Frame duration in us, 7500 or 10000
+ * sr_hz           Samplerate in Hz, 8000, 16000, 24000, 32000 or 48000
+ * return          Size of then decoder in bytes, 0 on bad parameters
+ *
+ * The `sr_hz` parameter is the samplerate of the PCM output stream,
+ * and will match `sr_pcm_hz` of `lc3_setup_decoder()`.
+ */
+unsigned lc3_decoder_size(int dt_us, int sr_hz);
+
+/**
+ * Setup decoder
+ * dt_us           Frame duration in us, 7500 or 10000
+ * sr_hz           Samplerate in Hz, 8000, 16000, 24000, 32000 or 48000
+ * sr_pcm_hz       Output samplerate, 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 samplerate of the decoded stream `sr_hz`.
+ * When used, `sr_pcm_hz` is intended to be higher or equal to the decoder
+ * samplerate `sr_hz`. The size of the context needed, given by
+ * `lc3_decoder_size()` will be set accordingly to `sr_pcm_hz`.
+ */
+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
+ */
+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 */

package/ios/Packages/CoreObjC/lc3_cpp.h

@@ -0,0 +1,283 @@
+/******************************************************************************
+ *
+ *  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) - C++ interface
+ */
+
+#ifndef __LC3_CPP_H
+#define __LC3_CPP_H
+
+#include <cassert>
+#include <memory>
+#include <vector>
+#include <stdlib.h>
+
+#include "lc3.h"
+
+namespace lc3 {
+
+// PCM Sample Format
+// - Signed 16 bits, in 16 bits words (int16_t)
+// - Signed 24 bits, using low three bytes of 32 bits words (int32_t)
+//   The high byte sign extends (bits 31..24 set to b23)
+// - Signed 24 bits packed in 3 bytes little endian
+// - Floating point 32 bits (float type), in range -1 to 1
+
+enum class PcmFormat {
+  kS16 = LC3_PCM_FORMAT_S16,
+  kS24 = LC3_PCM_FORMAT_S24,
+  kS24In3Le = LC3_PCM_FORMAT_S24_3LE,
+  kF32 = LC3_PCM_FORMAT_FLOAT
+};
+
+// Base Encoder/Decoder Class
+template <typename T>
+class Base {
+ protected:
+  Base(int dt_us, int sr_hz, int sr_pcm_hz, size_t nchannels)
+      : dt_us_(dt_us),
+        sr_hz_(sr_hz),
+        sr_pcm_hz_(sr_pcm_hz == 0 ? sr_hz : sr_pcm_hz),
+        nchannels_(nchannels) {
+    states.reserve(nchannels_);
+  }
+
+  virtual ~Base() = default;
+
+  int dt_us_, sr_hz_;
+  int sr_pcm_hz_;
+  size_t nchannels_;
+
+  using state_ptr = std::unique_ptr<T, decltype(&free)>;
+  std::vector<state_ptr> states;
+
+ public:
+  // Return the number of PCM samples in a frame
+  int GetFrameSamples() { return lc3_frame_samples(dt_us_, sr_pcm_hz_); }
+
+  // Return the size of frames, from bitrate
+  int GetFrameBytes(int bitrate) { return lc3_frame_bytes(dt_us_, bitrate); }
+
+  // Resolve the bitrate, from the size of frames
+  int ResolveBitrate(int nbytes) { return lc3_resolve_bitrate(dt_us_, nbytes); }
+
+  // Return algorithmic delay, as a number of samples
+  int GetDelaySamples() { return lc3_delay_samples(dt_us_, sr_pcm_hz_); }
+
+};  // class Base
+
+// Encoder Class
+class Encoder : public Base<struct lc3_encoder> {
+  template <typename T>
+  int EncodeImpl(PcmFormat fmt, const T *pcm, int frame_size, uint8_t *out) {
+    if (states.size() != nchannels_) return -1;
+
+    enum lc3_pcm_format cfmt = static_cast<lc3_pcm_format>(fmt);
+    int ret = 0;
+
+    for (size_t ich = 0; ich < nchannels_; ich++)
+      ret |= lc3_encode(states[ich].get(), cfmt, pcm + ich, nchannels_,
+                        frame_size, out + ich * frame_size);
+
+    return ret;
+  }
+
+ public:
+  // Encoder construction / destruction
+  //
+  // The frame duration `dt_us` is 7500 or 10000 us.
+  // The samplerate `sr_hz` is 8000, 16000, 24000, 32000 or 48000 Hz.
+  //
+  // The `sr_pcm_hz` parameter is a downsampling option of PCM input,
+  // the value 0 fallback to the samplerate of the encoded stream `sr_hz`.
+  // When used, `sr_pcm_hz` is intended to be higher or equal to the encoder
+  // samplerate `sr_hz`.
+
+  Encoder(int dt_us, int sr_hz, int sr_pcm_hz = 0, size_t nchannels = 1)
+      : Base(dt_us, sr_hz, sr_pcm_hz, nchannels) {
+    for (size_t ich = 0; ich < nchannels_; ich++) {
+      auto s = state_ptr(
+          (lc3_encoder_t)malloc(lc3_encoder_size(dt_us_, sr_pcm_hz_)), free);
+
+      if (lc3_setup_encoder(dt_us_, sr_hz_, sr_pcm_hz_, s.get()))
+        states.push_back(std::move(s));
+    }
+  }
+
+  ~Encoder() override = default;
+
+  // Reset encoder state
+
+  void Reset() {
+    for (auto &s : states)
+      lc3_setup_encoder(dt_us_, sr_hz_, sr_pcm_hz_, s.get());
+  }
+
+  // Encode
+  //
+  // The input PCM samples are given in signed 16 bits, 24 bits, float,
+  // according the type of `pcm` input buffer, or by selecting a format.
+  //
+  // The PCM samples are read in interleaved way, and consecutive
+  // `nchannels` frames of size `frame_size` are output in `out` buffer.
+  //
+  // The value returned is 0 on successs, -1 otherwise.
+
+  int Encode(const int16_t *pcm, int frame_size, uint8_t *out) {
+    return EncodeImpl(PcmFormat::kS16, pcm, frame_size, out);
+  }
+
+  int Encode(const int32_t *pcm, int frame_size, uint8_t *out) {
+    return EncodeImpl(PcmFormat::kS24, pcm, frame_size, out);
+  }
+
+  int Encode(const float *pcm, int frame_size, uint8_t *out) {
+    return EncodeImpl(PcmFormat::kF32, pcm, frame_size, out);
+  }
+
+  int Encode(PcmFormat fmt, const void *pcm, int frame_size, uint8_t *out) {
+    uintptr_t pcm_ptr = reinterpret_cast<uintptr_t>(pcm);
+
+    switch (fmt) {
+      case PcmFormat::kS16:
+        assert(pcm_ptr % alignof(int16_t) == 0);
+        return EncodeImpl(fmt, reinterpret_cast<const int16_t *>(pcm),
+                          frame_size, out);
+
+      case PcmFormat::kS24:
+        assert(pcm_ptr % alignof(int32_t) == 0);
+        return EncodeImpl(fmt, reinterpret_cast<const int32_t *>(pcm),
+                          frame_size, out);
+
+      case PcmFormat::kS24In3Le:
+        return EncodeImpl(fmt, reinterpret_cast<const int8_t(*)[3]>(pcm),
+                          frame_size, out);
+
+      case PcmFormat::kF32:
+        assert(pcm_ptr % alignof(float) == 0);
+        return EncodeImpl(fmt, reinterpret_cast<const float *>(pcm), frame_size,
+                          out);
+    }
+
+    return -1;
+  }
+
+};  // class Encoder
+
+// Decoder Class
+class Decoder : public Base<struct lc3_decoder> {
+  template <typename T>
+  int DecodeImpl(const uint8_t *in, int frame_size, PcmFormat fmt, T *pcm) {
+    if (states.size() != nchannels_) return -1;
+
+    enum lc3_pcm_format cfmt = static_cast<enum lc3_pcm_format>(fmt);
+    int ret = 0;
+
+    for (size_t ich = 0; ich < nchannels_; ich++)
+      ret |= lc3_decode(states[ich].get(), in + ich * frame_size, frame_size,
+                        cfmt, pcm + ich, nchannels_);
+
+    return ret;
+  }
+
+ public:
+  // Decoder construction / destruction
+  //
+  // The frame duration `dt_us` is 7500 or 10000 us.
+  // The samplerate `sr_hz` is 8000, 16000, 24000, 32000 or 48000 Hz.
+  //
+  // The `sr_pcm_hz` parameter is an downsampling option of PCM output,
+  // the value 0 fallback to the samplerate of the decoded stream `sr_hz`.
+  // When used, `sr_pcm_hz` is intended to be higher or equal to the decoder
+  // samplerate `sr_hz`.
+
+  Decoder(int dt_us, int sr_hz, int sr_pcm_hz = 0, size_t nchannels = 1)
+      : Base(dt_us, sr_hz, sr_pcm_hz, nchannels) {
+    for (size_t i = 0; i < nchannels_; i++) {
+      auto s = state_ptr(
+          (lc3_decoder_t)malloc(lc3_decoder_size(dt_us_, sr_pcm_hz_)), free);
+
+      if (lc3_setup_decoder(dt_us_, sr_hz_, sr_pcm_hz_, s.get()))
+        states.push_back(std::move(s));
+    }
+  }
+
+  ~Decoder() override = default;
+
+  // Reset decoder state
+
+  void Reset() {
+    for (auto &s : states)
+      lc3_setup_decoder(dt_us_, sr_hz_, sr_pcm_hz_, s.get());
+  }
+
+  // Decode
+  //
+  // Consecutive `nchannels` frames of size `frame_size` are decoded
+  // in the `pcm` buffer in interleaved way.
+  //
+  // The PCM samples are output in signed 16 bits, 24 bits, float,
+  // according the type of `pcm` output buffer, or by selecting a format.
+  //
+  // The value returned is 0 on successs, 1 when PLC has been performed,
+  // and -1 otherwise.
+
+  int Decode(const uint8_t *in, int frame_size, int16_t *pcm) {
+    return DecodeImpl(in, frame_size, PcmFormat::kS16, pcm);
+  }
+
+  int Decode(const uint8_t *in, int frame_size, int32_t *pcm) {
+    return DecodeImpl(in, frame_size, PcmFormat::kS24In3Le, pcm);
+  }
+
+  int Decode(const uint8_t *in, int frame_size, float *pcm) {
+    return DecodeImpl(in, frame_size, PcmFormat::kF32, pcm);
+  }
+
+  int Decode(const uint8_t *in, int frame_size, PcmFormat fmt, void *pcm) {
+    uintptr_t pcm_ptr = reinterpret_cast<uintptr_t>(pcm);
+
+    switch (fmt) {
+      case PcmFormat::kS16:
+        assert(pcm_ptr % alignof(int16_t) == 0);
+        return DecodeImpl(in, frame_size, fmt,
+                          reinterpret_cast<int16_t *>(pcm));
+
+      case PcmFormat::kS24:
+        assert(pcm_ptr % alignof(int32_t) == 0);
+        return DecodeImpl(in, frame_size, fmt,
+                          reinterpret_cast<int32_t *>(pcm));
+
+      case PcmFormat::kS24In3Le:
+        return DecodeImpl(in, frame_size, fmt,
+                          reinterpret_cast<int8_t(*)[3]>(pcm));
+
+      case PcmFormat::kF32:
+        assert(pcm_ptr % alignof(float) == 0);
+        return DecodeImpl(in, frame_size, fmt, reinterpret_cast<float *>(pcm));
+    }
+
+    return -1;
+  }
+
+};  // class Decoder
+
+}  // namespace lc3
+
+#endif /* __LC3_CPP_H */