react-native-ble-mesh 1.0.1

package/src/service/audio/buffer/JitterBuffer.js

@@ -0,0 +1,190 @@
+'use strict';
+
+/**
+ * @fileoverview Jitter buffer for real-time audio streaming
+ * @module audio/buffer/JitterBuffer
+ */
+
+const EventEmitter = require('../../../utils/EventEmitter');
+const { AUDIO_STREAM_CONFIG } = require('../../../constants/audio');
+
+/**
+ * Jitter buffer for smoothing network jitter in audio streams
+ * @class JitterBuffer
+ * @extends EventEmitter
+ */
+class JitterBuffer extends EventEmitter {
+  /**
+   * Creates a new JitterBuffer
+   * @param {Object} [options] - Buffer options
+   * @param {number} [options.depth=5] - Target buffer depth in frames
+   * @param {number} [options.maxDepth=20] - Maximum buffer depth
+   * @param {number} [options.frameMs=10] - Frame duration in ms
+   */
+  constructor(options = {}) {
+    super();
+
+    /** @private */
+    this._targetDepth = options.depth || AUDIO_STREAM_CONFIG.JITTER_BUFFER_FRAMES;
+    /** @private */
+    this._maxDepth = options.maxDepth || AUDIO_STREAM_CONFIG.MAX_JITTER_BUFFER_FRAMES;
+    /** @private */
+    this._frameMs = options.frameMs || 10;
+    /** @private */
+    this._buffer = new Map(); // sequenceNumber -> { frame, timestamp }
+    /** @private */
+    this._nextPlaySeq = 0;
+    /** @private */
+    this._initialized = false;
+    /** @private */
+    this._stats = {
+      framesReceived: 0,
+      framesPlayed: 0,
+      framesDropped: 0,
+      plcFrames: 0,
+      underruns: 0,
+      overflows: 0
+    };
+  }
+
+  /**
+   * Pushes a frame into the buffer
+   * @param {Uint8Array} frame - Audio frame data
+   * @param {number} sequenceNumber - Frame sequence number
+   * @param {number} [timestamp] - Frame timestamp
+   */
+  push(frame, sequenceNumber, timestamp = Date.now()) {
+    this._stats.framesReceived++;
+
+    // Initialize on first frame
+    if (!this._initialized) {
+      this._nextPlaySeq = sequenceNumber;
+      this._initialized = true;
+    }
+
+    // Drop if too old
+    if (sequenceNumber < this._nextPlaySeq) {
+      this._stats.framesDropped++;
+      return;
+    }
+
+    // Check for overflow
+    if (this._buffer.size >= this._maxDepth) {
+      this._stats.overflows++;
+      this.emit('overflow', { bufferSize: this._buffer.size });
+      // Drop oldest frame
+      const oldestSeq = Math.min(...this._buffer.keys());
+      this._buffer.delete(oldestSeq);
+    }
+
+    this._buffer.set(sequenceNumber, { frame: new Uint8Array(frame), timestamp });
+
+    // Emit ready when we have enough frames
+    if (this._buffer.size >= this._targetDepth) {
+      this.emit('ready', { bufferSize: this._buffer.size });
+    }
+  }
+
+  /**
+   * Pops the next frame from the buffer
+   * @returns {{frame: Uint8Array|null, isPLC: boolean, sequenceNumber: number}}
+   */
+  pop() {
+    const seq = this._nextPlaySeq;
+    this._nextPlaySeq++;
+
+    if (this._buffer.has(seq)) {
+      const { frame } = this._buffer.get(seq);
+      this._buffer.delete(seq);
+      this._stats.framesPlayed++;
+      return { frame, isPLC: false, sequenceNumber: seq };
+    }
+
+    // Frame missing - generate PLC marker
+    this._stats.plcFrames++;
+
+    if (this._buffer.size === 0) {
+      this._stats.underruns++;
+      this.emit('underrun', { sequenceNumber: seq });
+    }
+
+    return { frame: null, isPLC: true, sequenceNumber: seq };
+  }
+
+  /**
+   * Peeks at the next frame without removing it
+   * @returns {{frame: Uint8Array|null, sequenceNumber: number}|null}
+   */
+  peek() {
+    if (this._buffer.has(this._nextPlaySeq)) {
+      const { frame } = this._buffer.get(this._nextPlaySeq);
+      return { frame, sequenceNumber: this._nextPlaySeq };
+    }
+    return null;
+  }
+
+  /**
+   * Returns current buffer level
+   * @returns {number}
+   */
+  getBufferLevel() {
+    return this._buffer.size;
+  }
+
+  /**
+   * Returns buffer level in milliseconds
+   * @returns {number}
+   */
+  getBufferMs() {
+    return this._buffer.size * this._frameMs;
+  }
+
+  /**
+   * Returns whether buffer has enough frames
+   * @returns {boolean}
+   */
+  isReady() {
+    return this._buffer.size >= this._targetDepth;
+  }
+
+  /**
+   * Returns buffer statistics
+   * @returns {Object}
+   */
+  getStats() {
+    return {
+      ...this._stats,
+      currentLevel: this._buffer.size,
+      targetDepth: this._targetDepth,
+      bufferMs: this.getBufferMs(),
+      lossRatio: this._stats.framesReceived > 0
+        ? this._stats.plcFrames / this._stats.framesReceived
+        : 0
+    };
+  }
+
+  /**
+   * Clears the buffer
+   */
+  clear() {
+    this._buffer.clear();
+    this._initialized = false;
+    this._nextPlaySeq = 0;
+  }
+
+  /**
+   * Pauses playback (stops advancing sequence)
+   */
+  pause() {
+    this._paused = true;
+  }
+
+  /**
+   * Resumes playback
+   */
+  resume() {
+    this._paused = false;
+  }
+}
+
+module.exports = JitterBuffer;

package/src/service/audio/buffer/index.js

@@ -0,0 +1,14 @@
+'use strict';
+
+/**
+ * @fileoverview Audio buffer module exports
+ * @module audio/buffer
+ */
+
+const FrameBuffer = require('./FrameBuffer');
+const JitterBuffer = require('./JitterBuffer');
+
+module.exports = {
+  FrameBuffer,
+  JitterBuffer
+};

package/src/service/audio/codec/LC3Codec.js

@@ -0,0 +1,291 @@
+'use strict';
+
+/**
+ * @fileoverview LC3 codec wrapper for React Native
+ * @module audio/codec/LC3Codec
+ */
+
+const EventEmitter = require('../../../utils/EventEmitter');
+const AudioError = require('../../../errors/AudioError');
+const { LC3_CONFIG, AUDIO_QUALITY } = require('../../../constants/audio');
+
+/**
+ * LC3 Codec wrapper that bridges to React Native native modules
+ * @class LC3Codec
+ * @extends EventEmitter
+ */
+class LC3Codec extends EventEmitter {
+  /**
+   * Creates a new LC3Codec instance
+   * @param {Object} [options] - Codec configuration
+   * @param {number} [options.sampleRate=16000] - Sample rate in Hz
+   * @param {number} [options.frameMs=10] - Frame duration in milliseconds
+   * @param {number} [options.bitRate=24000] - Bit rate in bps
+   * @param {number} [options.channels=1] - Number of audio channels
+   */
+  constructor(options = {}) {
+    super();
+
+    const quality = options.quality ? AUDIO_QUALITY[options.quality] : null;
+
+    /** @private */
+    this._sampleRate = quality?.sampleRate || options.sampleRate || LC3_CONFIG.DEFAULT_SAMPLE_RATE;
+    /** @private */
+    this._frameMs = quality?.frameMs || options.frameMs || LC3_CONFIG.DEFAULT_FRAME_DURATION_MS;
+    /** @private */
+    this._bitRate = quality?.bitRate || options.bitRate || LC3_CONFIG.DEFAULT_BIT_RATE;
+    /** @private */
+    this._channels = quality?.channels || options.channels || LC3_CONFIG.DEFAULT_CHANNELS;
+    /** @private */
+    this._initialized = false;
+    /** @private */
+    this._nativeModule = null;
+    /** @private */
+    this._useMock = false;
+
+    this._validateConfig();
+  }
+
+  /**
+   * Validates codec configuration
+   * @private
+   */
+  _validateConfig() {
+    if (!LC3_CONFIG.SAMPLE_RATES.includes(this._sampleRate)) {
+      throw AudioError.invalidConfig(`Invalid sample rate: ${this._sampleRate}`);
+    }
+    if (!LC3_CONFIG.FRAME_DURATIONS.includes(this._frameMs)) {
+      throw AudioError.invalidConfig(`Invalid frame duration: ${this._frameMs}`);
+    }
+  }
+
+  /**
+   * Initializes the codec
+   * @returns {Promise<void>}
+   */
+  async initialize() {
+    if (this._initialized) {
+      return;
+    }
+
+    try {
+      // Try to load native module
+      this._nativeModule = this._loadNativeModule();
+
+      if (this._nativeModule) {
+        await this._nativeModule.initialize({
+          sampleRate: this._sampleRate,
+          frameMs: this._frameMs,
+          bitRate: this._bitRate,
+          channels: this._channels
+        });
+      } else {
+        // Use mock implementation for testing
+        this._useMock = true;
+        console.warn('LC3Codec: Native module not available, using mock implementation');
+      }
+
+      this._initialized = true;
+      this.emit('initialized', this.getConfig());
+    } catch (error) {
+      throw AudioError.codecInitFailed({ reason: error.message });
+    }
+  }
+
+  /**
+   * Attempts to load the native LC3 module
+   * @private
+   * @returns {Object|null}
+   */
+  _loadNativeModule() {
+    try {
+      // Try React Native NativeModules
+      const { NativeModules } = require('react-native');
+      if (NativeModules && NativeModules.RNLc3Codec) {
+        return NativeModules.RNLc3Codec;
+      }
+    } catch {
+      // Not in React Native environment
+    }
+    return null;
+  }
+
+  /**
+   * Returns whether the codec is initialized
+   * @returns {boolean}
+   */
+  isInitialized() {
+    return this._initialized;
+  }
+
+  /**
+   * Returns whether using mock implementation
+   * @returns {boolean}
+   */
+  isMock() {
+    return this._useMock;
+  }
+
+  /**
+   * Encodes PCM samples to LC3 frame
+   * @param {Int16Array} pcmSamples - PCM audio samples
+   * @returns {Promise<Uint8Array>} Encoded LC3 frame
+   */
+  async encode(pcmSamples) {
+    if (!this._initialized) {
+      throw AudioError.codecInitFailed({ reason: 'Codec not initialized' });
+    }
+
+    const expectedSamples = this.getFrameSamples();
+    if (pcmSamples.length !== expectedSamples) {
+      throw AudioError.encodingFailed({
+        reason: `Expected ${expectedSamples} samples, got ${pcmSamples.length}`
+      });
+    }
+
+    if (this._useMock) {
+      return this._mockEncode(pcmSamples);
+    }
+
+    try {
+      const result = await this._nativeModule.encode(Array.from(pcmSamples));
+      return new Uint8Array(result);
+    } catch (error) {
+      throw AudioError.encodingFailed({ reason: error.message });
+    }
+  }
+
+  /**
+   * Decodes LC3 frame to PCM samples
+   * @param {Uint8Array} lc3Frame - Encoded LC3 frame
+   * @returns {Promise<Int16Array>} Decoded PCM samples
+   */
+  async decode(lc3Frame) {
+    if (!this._initialized) {
+      throw AudioError.codecInitFailed({ reason: 'Codec not initialized' });
+    }
+
+    if (this._useMock) {
+      return this._mockDecode(lc3Frame);
+    }
+
+    try {
+      const result = await this._nativeModule.decode(Array.from(lc3Frame));
+      return new Int16Array(result);
+    } catch (error) {
+      throw AudioError.decodingFailed({ reason: error.message });
+    }
+  }
+
+  /**
+   * Generates PLC (Packet Loss Concealment) frame
+   * @returns {Promise<Int16Array>} Concealed PCM samples
+   */
+  async decodePLC() {
+    if (!this._initialized) {
+      throw AudioError.codecInitFailed({ reason: 'Codec not initialized' });
+    }
+
+    if (this._useMock) {
+      return this._mockDecodePLC();
+    }
+
+    try {
+      const result = await this._nativeModule.decodePLC();
+      return new Int16Array(result);
+    } catch (error) {
+      throw AudioError.decodingFailed({ reason: error.message });
+    }
+  }
+
+  /**
+   * Mock encode implementation for testing
+   * @private
+   */
+  _mockEncode(pcmSamples) {
+    // Simple mock: compress by taking every 4th sample and convert to bytes
+    const frameBytes = this.getFrameBytes();
+    const encoded = new Uint8Array(frameBytes);
+
+    for (let i = 0; i < frameBytes && i * 2 < pcmSamples.length; i++) {
+      const sample = pcmSamples[i * 2];
+      encoded[i] = (sample >> 8) & 0xFF;
+    }
+
+    return encoded;
+  }
+
+  /**
+   * Mock decode implementation for testing
+   * @private
+   */
+  _mockDecode(lc3Frame) {
+    const samples = this.getFrameSamples();
+    const decoded = new Int16Array(samples);
+
+    for (let i = 0; i < samples && i < lc3Frame.length; i++) {
+      decoded[i * 2] = (lc3Frame[i] << 8);
+      if (i * 2 + 1 < samples) {
+        decoded[i * 2 + 1] = (lc3Frame[i] << 8);
+      }
+    }
+
+    return decoded;
+  }
+
+  /**
+   * Mock PLC implementation for testing
+   * @private
+   */
+  _mockDecodePLC() {
+    // Return silence for PLC
+    return new Int16Array(this.getFrameSamples());
+  }
+
+  /**
+   * Returns the number of samples per frame
+   * @returns {number}
+   */
+  getFrameSamples() {
+    return Math.floor(this._sampleRate * this._frameMs / 1000);
+  }
+
+  /**
+   * Returns the encoded frame size in bytes
+   * @returns {number}
+   */
+  getFrameBytes() {
+    // LC3 frame size formula: bitRate * frameMs / 8000
+    return Math.ceil(this._bitRate * this._frameMs / 8000);
+  }
+
+  /**
+   * Returns the current codec configuration
+   * @returns {Object}
+   */
+  getConfig() {
+    return {
+      sampleRate: this._sampleRate,
+      frameMs: this._frameMs,
+      bitRate: this._bitRate,
+      channels: this._channels,
+      frameSamples: this.getFrameSamples(),
+      frameBytes: this.getFrameBytes(),
+      isMock: this._useMock
+    };
+  }
+
+  /**
+   * Destroys the codec and releases resources
+   */
+  destroy() {
+    if (this._nativeModule && typeof this._nativeModule.destroy === 'function') {
+      this._nativeModule.destroy();
+    }
+    this._initialized = false;
+    this._nativeModule = null;
+    this.removeAllListeners();
+  }
+}
+
+module.exports = LC3Codec;

package/src/service/audio/codec/LC3Decoder.js

@@ -0,0 +1,131 @@
+'use strict';
+
+/**
+ * @fileoverview LC3 decoder with PLC support
+ * @module audio/codec/LC3Decoder
+ */
+
+const EventEmitter = require('../../../utils/EventEmitter');
+const AudioError = require('../../../errors/AudioError');
+
+/**
+ * LC3 Decoder with Packet Loss Concealment
+ * @class LC3Decoder
+ * @extends EventEmitter
+ */
+class LC3Decoder extends EventEmitter {
+  /**
+   * Creates a new LC3Decoder
+   * @param {LC3Codec} codec - Initialized LC3 codec instance
+   */
+  constructor(codec) {
+    super();
+
+    if (!codec || !codec.isInitialized()) {
+      throw AudioError.codecInitFailed({ reason: 'Codec must be initialized' });
+    }
+
+    /** @private */
+    this._codec = codec;
+    /** @private */
+    this._frameSamples = codec.getFrameSamples();
+    /** @private */
+    this._framesDecoded = 0;
+    /** @private */
+    this._plcFrames = 0;
+    /** @private */
+    this._errors = 0;
+    /** @private */
+    this._lastSequence = -1;
+  }
+
+  /**
+   * Decodes an LC3 frame to PCM samples
+   * @param {Uint8Array} lc3Frame - Encoded LC3 frame
+   * @param {number} [sequenceNumber] - Optional sequence number for gap detection
+   * @returns {Promise<Int16Array>} Decoded PCM samples
+   */
+  async decode(lc3Frame, sequenceNumber) {
+    // Check for gaps in sequence
+    if (sequenceNumber !== undefined && this._lastSequence >= 0) {
+      const gap = sequenceNumber - this._lastSequence - 1;
+      if (gap > 0) {
+        this.emit('gap-detected', { missing: gap, lastSeq: this._lastSequence });
+      }
+    }
+
+    if (sequenceNumber !== undefined) {
+      this._lastSequence = sequenceNumber;
+    }
+
+    try {
+      const samples = await this._codec.decode(lc3Frame);
+      this._framesDecoded++;
+      this.emit('samples', { samples, index: this._framesDecoded });
+      return samples;
+    } catch (error) {
+      this._errors++;
+      this.emit('error', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Generates a PLC frame for packet loss concealment
+   * @returns {Promise<Int16Array>} Concealed PCM samples
+   */
+  async decodePLC() {
+    try {
+      const samples = await this._codec.decodePLC();
+      this._plcFrames++;
+      this.emit('plc', { samples, plcCount: this._plcFrames });
+      return samples;
+    } catch (error) {
+      this._errors++;
+      this.emit('error', error);
+      // Return silence on PLC failure
+      return new Int16Array(this._frameSamples);
+    }
+  }
+
+  /**
+   * Decodes a frame or generates PLC if frame is missing
+   * @param {Uint8Array|null} lc3Frame - LC3 frame or null for PLC
+   * @param {number} [sequenceNumber] - Sequence number
+   * @returns {Promise<{samples: Int16Array, isPLC: boolean}>}
+   */
+  async decodeOrPLC(lc3Frame, sequenceNumber) {
+    if (lc3Frame === null || lc3Frame === undefined) {
+      const samples = await this.decodePLC();
+      return { samples, isPLC: true };
+    }
+
+    const samples = await this.decode(lc3Frame, sequenceNumber);
+    return { samples, isPLC: false };
+  }
+
+  /**
+   * Returns decoder statistics
+   * @returns {Object}
+   */
+  getStats() {
+    return {
+      framesDecoded: this._framesDecoded,
+      plcFrames: this._plcFrames,
+      errors: this._errors,
+      plcRatio: this._framesDecoded > 0
+        ? this._plcFrames / (this._framesDecoded + this._plcFrames)
+        : 0,
+      lastSequence: this._lastSequence
+    };
+  }
+
+  /**
+   * Resets the decoder state
+   */
+  reset() {
+    this._lastSequence = -1;
+  }
+}
+
+module.exports = LC3Decoder;