vimp-engine 0.38.2 → 0.39.0

package/src/client/voice/JitterBuffer.js

@@ -0,0 +1,137 @@
+import { seqDiff } from '../../lib/voicePacket.js';
+
+/**
+ * Упорядочивает пакеты голоса: перестановки, дубли, потери. Чистая логика
+ * без таймеров — время приходит аргументом. Новый поток — новый экземпляр.
+ */
+export default class JitterBuffer {
+  /**
+   * @param {Object} [opts]
+   * @param {number} [opts.maxWaitMs] - сколько ждать пропавший пакет.
+   * @param {number} [opts.maxQueue] - потолок очереди (1 с голоса).
+   * @param {number|null} [opts.after] - номер, после которого идёт поток:
+   *   пакеты не новее него — 'late' (пробуждение эфира).
+   */
+  constructor({ maxWaitMs = 60, maxQueue = 50, after = null } = {}) {
+    this._maxWaitMs = maxWaitMs;
+    this._maxQueue = maxQueue;
+    this._after = after;
+    this._highest = after;
+    this._expected = null;
+    this._queue = new Map();
+  }
+
+  get size() {
+    return this._queue.size;
+  }
+
+  /** Наибольший принятый seq или after, пока ничего не принято. */
+  get highestSeq() {
+    return this._highest;
+  }
+
+  /**
+   * @param {number} seq - u16.
+   * @param {Uint8Array} payload
+   * @param {number} nowMs
+   * @returns {'accepted'|'late'|'duplicate'|'overflow'}
+   */
+  push(seq, payload, nowMs) {
+    if (this._after !== null && seqDiff(seq, this._after) <= 0) {
+      return 'late';
+    }
+
+    if (this._expected !== null && seqDiff(seq, this._expected) < 0) {
+      return 'late';
+    }
+
+    if (this._queue.has(seq)) {
+      return 'duplicate';
+    }
+
+    if (this._queue.size >= this._maxQueue) {
+      return 'overflow';
+    }
+
+    this._queue.set(seq, { payload, at: nowMs });
+
+    if (this._highest === null || seqDiff(seq, this._highest) > 0) {
+      this._highest = seq;
+    }
+
+    return 'accepted';
+  }
+
+  /**
+   * Кадры, готовые к декодированию, по порядку.
+   * @param {number} nowMs
+   * @param {Object} [opts]
+   * @param {boolean} [opts.flush] - выдать всё, не ожидая пропавших.
+   * @returns {Array<{ seq: number, payload: Uint8Array }|
+   *   { seq: number, missing: true }>}
+   */
+  pull(nowMs, { flush = false } = {}) {
+    const out = [];
+
+    if (this._queue.size === 0) {
+      return out;
+    }
+
+    const waited = () => nowMs - this._oldestAt() >= this._maxWaitMs;
+
+    if (this._expected === null) {
+      if (!(flush || this._queue.size >= 3 || waited())) {
+        return out;
+      }
+
+      this._expected = this._lowestSeq();
+    }
+
+    const lowest = this._lowestSeq();
+
+    // скачок seq дальше очереди: пакеты позади него не придут, зазор не
+    // перебираем «потерями» — ждать нечего
+    if (seqDiff(lowest, this._expected) > this._maxQueue) {
+      this._expected = lowest;
+    }
+
+    while (this._queue.size > 0) {
+      const entry = this._queue.get(this._expected);
+
+      if (entry) {
+        this._queue.delete(this._expected);
+        out.push({ seq: this._expected, payload: entry.payload });
+      } else if (flush || waited()) {
+        out.push({ seq: this._expected, missing: true });
+      } else {
+        break;
+      }
+
+      this._expected = (this._expected + 1) & 0xffff;
+    }
+
+    return out;
+  }
+
+  _oldestAt() {
+    let oldest = Infinity;
+
+    for (const { at } of this._queue.values()) {
+      oldest = Math.min(oldest, at);
+    }
+
+    return oldest;
+  }
+
+  _lowestSeq() {
+    let lowest = null;
+
+    for (const seq of this._queue.keys()) {
+      if (lowest === null || seqDiff(seq, lowest) < 0) {
+        lowest = seq;
+      }
+    }
+
+    return lowest;
+  }
+}

package/src/client/voice/MicCapture.js

@@ -0,0 +1,307 @@
+import {
+  VOICE_FRAME_MS,
+  VOICE_MIC_IDLE_RELEASE_MS,
+  VOICE_SAMPLE_RATE,
+} from '../../config/voiceProtocol.js';
+
+const PROCESSOR_NAME = 'vimp-voice-capture';
+
+/**
+ * Микрофон: разрешение, граф захвата, «тёплое» удержание. Своего
+ * AudioContext у захвата нет — он сидит на контексте движка (Howler): свой
+ * контекст на 48 кГц ломается в Firefox при другой частоте микрофона и
+ * ненадёжен в Safari/iOS. Частоту выравнивает worklet. Howler контекст
+ * пересоздаёт, поэтому он берётся лениво и сверяется по идентичности.
+ */
+export default class MicCapture {
+  /**
+   * @param {Object} deps
+   * @param {MediaDevices} deps.mediaDevices
+   * @param {Function} deps.getContext - () => AudioContext | null.
+   * @param {Function} [deps.createWorkletNode] - (ctx, name, opts) => node.
+   * @param {URL|string} [deps.workletUrl]
+   * @param {Object} [deps.timers] - { setTimeout, clearTimeout }.
+   * @param {number} [deps.idleReleaseMs]
+   * @param {Function} deps.onFrame - (Float32Array, timestampUs) => void.
+   * @param {Function} [deps.onLost] - готовый граф умер (контекст закрыт,
+   *   микрофон выдернут): эфир надо завершить.
+   */
+  constructor({
+    mediaDevices,
+    getContext,
+    createWorkletNode = (ctx, name, opts) =>
+      new globalThis.AudioWorkletNode(ctx, name, opts),
+    workletUrl = new URL('./captureProcessor.worklet.js', import.meta.url),
+    timers = {
+      setTimeout: (...args) => globalThis.setTimeout(...args),
+      clearTimeout: id => globalThis.clearTimeout(id),
+    },
+    idleReleaseMs = VOICE_MIC_IDLE_RELEASE_MS,
+    onFrame,
+    onLost,
+  }) {
+    this._mediaDevices = mediaDevices;
+    this._getContext = getContext;
+    this._createWorkletNode = createWorkletNode;
+    this._workletUrl = workletUrl;
+    this._timers = timers;
+    this._idleReleaseMs = idleReleaseMs;
+    this._onFrame = onFrame;
+    this._onLost = onLost;
+    this._state = 'idle';
+    this._graph = null;
+    this._acquiring = null;
+    this._timer = null;
+    this._running = false;
+    this._frameIndex = 0;
+    this._generation = 0;
+    this._destroyed = false;
+    // контексты, в которые модуль worklet уже загружен
+    this._modules = new WeakSet();
+  }
+
+  /** 'idle' | 'acquiring' | 'ready' | 'denied' | 'failed' */
+  get state() {
+    return this._state === 'ready' && !this._isAlive() ? 'idle' : this._state;
+  }
+
+  /** @returns {Promise<boolean>} граф готов. */
+  acquire() {
+    if (this._acquiring) {
+      return this._acquiring;
+    }
+
+    if (this._state === 'ready' && this._isAlive()) {
+      return Promise.resolve(true);
+    }
+
+    // граф устарел (контекст пересоздан): разобрать и построить заново
+    this.release();
+    this._state = 'acquiring';
+    this._acquiring = this._open().finally(() => {
+      this._acquiring = null;
+    });
+
+    return this._acquiring;
+  }
+
+  /** @returns {boolean} false — графа нет или он устарел. */
+  start() {
+    if (!this._graph || !this._isAlive()) {
+      return false;
+    }
+
+    this._clearTimer();
+
+    const { ctx, node } = this._graph;
+
+    if (ctx.state === 'suspended') {
+      // нажатие V — жест пользователя
+      ctx.resume()?.catch?.(() => {});
+    }
+
+    this._frameIndex = 0;
+    this._running = true;
+    // поколение: кадры прошлого эфира, ещё стоящие в очереди порта, не
+    // попадают в новый
+    this._generation += 1;
+    node.port.postMessage({ active: true, generation: this._generation });
+
+    return true;
+  }
+
+  stop() {
+    if (!this._graph) {
+      return;
+    }
+
+    this._running = false;
+    this._graph.node.port.postMessage({ active: false });
+    this._armTimer();
+  }
+
+  /** Останавливает треки и отключает узлы; контекст чужой, не закрывается. */
+  release() {
+    this._clearTimer();
+    this._running = false;
+
+    const graph = this._graph;
+
+    if (!graph) {
+      return;
+    }
+
+    this._graph = null;
+    this._state = 'idle';
+    graph.ctx.removeEventListener('statechange', graph.onStateChange);
+
+    for (const track of graph.stream.getTracks()) {
+      track.onended = null;
+      track.stop();
+    }
+
+    // процессор с process() → true жил бы вечно: отключённый узел не собрать
+    try {
+      graph.node.port.postMessage({ shutdown: true });
+    } catch {
+      // порт уже закрыт
+    }
+
+    graph.node.port.onmessage = null;
+
+    for (const node of [graph.source, graph.node, graph.silence]) {
+      try {
+        node.disconnect();
+      } catch {
+        // уже отключён
+      }
+    }
+  }
+
+  destroy() {
+    this._destroyed = true;
+    this.release();
+  }
+
+  _isAlive() {
+    return Boolean(this._graph && this._isCurrent(this._graph.ctx));
+  }
+
+  // контекст жив и всё ещё контекст движка (Howler пересоздаёт его)
+  _isCurrent(ctx) {
+    return ctx.state !== 'closed' && this._getContext() === ctx;
+  }
+
+  async _open() {
+    const ctx = this._getContext();
+
+    if (!ctx) {
+      this._state = 'failed';
+
+      return false;
+    }
+
+    let stream;
+
+    try {
+      stream = await this._mediaDevices.getUserMedia({
+        audio: {
+          echoCancellation: true,
+          noiseSuppression: true,
+          autoGainControl: true,
+          channelCount: 1,
+        },
+      });
+    } catch (error) {
+      this._state =
+        error?.name === 'NotAllowedError' || error?.name === 'SecurityError'
+          ? 'denied'
+          : 'failed';
+
+      return false;
+    }
+
+    // захват закрыт или контекст сменился, пока ждали разрешения или модуль:
+    // граф после destroy() держал бы микрофон открытым до таймера «тёплого»
+    // удержания
+    const usable = () => !this._destroyed && this._isCurrent(ctx);
+    let graph = null;
+
+    try {
+      if (usable() && !this._modules.has(ctx)) {
+        await ctx.audioWorklet.addModule(this._workletUrl);
+        this._modules.add(ctx);
+      }
+
+      if (usable()) {
+        graph = this._buildGraph(ctx, stream);
+      }
+    } catch {
+      // модуль не загрузился или граф не собрался — как устаревший контекст
+    }
+
+    if (!graph) {
+      for (const track of stream.getTracks()) {
+        track.stop();
+      }
+
+      this._state = 'failed';
+
+      return false;
+    }
+
+    this._graph = graph;
+    this._state = 'ready';
+    this._armTimer();
+
+    return true;
+  }
+
+  _buildGraph(ctx, stream) {
+    const source = ctx.createMediaStreamSource(stream);
+    const node = this._createWorkletNode(ctx, PROCESSOR_NAME, {
+      numberOfInputs: 1,
+      numberOfOutputs: 1,
+      processorOptions: {
+        outputRate: VOICE_SAMPLE_RATE,
+        frameSamples: (VOICE_SAMPLE_RATE * VOICE_FRAME_MS) / 1000,
+      },
+    });
+    // нулевой выход держит узел в обработке; ctx.destination, а не master
+    // gain Howler: mute движка захват не трогает
+    const silence = ctx.createGain();
+
+    silence.gain.value = 0;
+    source.connect(node);
+    node.connect(silence);
+    silence.connect(ctx.destination);
+
+    const onStateChange = () => {
+      if (ctx.state === 'closed' && this._graph?.ctx === ctx) {
+        this.release();
+        this._onLost?.();
+      }
+    };
+    const graph = { ctx, stream, source, node, silence, onStateChange };
+
+    // addEventListener, не onstatechange: свойство может занимать Howler
+    ctx.addEventListener('statechange', onStateChange);
+
+    node.port.onmessage = ({ data }) => {
+      if (
+        this._running &&
+        this._graph === graph &&
+        data.generation === this._generation
+      ) {
+        this._onFrame(data.samples, this._frameIndex++ * VOICE_FRAME_MS * 1000);
+      }
+    };
+
+    for (const track of stream.getAudioTracks()) {
+      track.onended = () => {
+        if (this._graph === graph) {
+          this.release();
+          this._state = 'failed';
+          this._onLost?.();
+        }
+      };
+    }
+
+    return graph;
+  }
+
+  _armTimer() {
+    this._clearTimer();
+    this._timer = this._timers.setTimeout(
+      () => this.release(),
+      this._idleReleaseMs,
+    );
+  }
+
+  _clearTimer() {
+    if (this._timer !== null) {
+      this._timers.clearTimeout(this._timer);
+      this._timer = null;
+    }
+  }
+}