vimp-engine 0.38.3 → 0.40.0

package/src/client/voice/VoicePlayback.js

@@ -0,0 +1,558 @@
+import wsports from '../../config/wsports.js';
+import { readVoiceHeader, voicePayload } from '../../lib/voicePacket.js';
+import JitterBuffer from './JitterBuffer.js';
+import { audioDataToFloat32 } from './audioData.js';
+import { decoderConfig } from './opusConfig.js';
+import { createVoiceOutput } from './voiceOutput.js';
+
+const PUMP_INTERVAL_MS = 10;
+// минимальный запас на джиттер перед первым кадром
+const START_LEAD_S = 0.06;
+// пауза между сигналом и речью
+const CUE_GAP_S = 0.015;
+const MIN_LEAD_S = 0.005;
+// накопленная задержка речи выше этого — кадр выбрасывается
+const MAX_LATENCY_S = 0.35;
+const MAX_SILENT_GAP_FRAMES = 5;
+const FRAME_S = 0.02;
+const FRAME_US = 20000;
+// поток эфира встал: говорящий без DTX шлёт пакет каждые 20 мс
+const SILENCE_TIMEOUT_MS = 1000;
+// первый пакет: START приходит раньше, чем говорящий получит GRANT и
+// запустит захват
+const FIRST_PACKET_GRACE_MS = 2000;
+
+/**
+ * Приём эфиров: декодер, джиттер-буфер, планирование речи, сигналы,
+ * тишина потока. Индикаторы ведёт не он — только звук.
+ */
+export default class VoicePlayback {
+  /**
+   * @param {Object} deps
+   * @param {Function} deps.getOutput - () => { ctx, destination } | null.
+   * @param {import('./VoiceCues.js').default} deps.cues
+   * @param {Function} [deps.voiceFilter] - ClientPlugin.hooks.voiceFilter.
+   * @param {Function|null} deps.createDecoder - init => AudioDecoder; null —
+   *   у браузера нет декодера: приём эфиров выключен, свои сигналы звучат.
+   * @param {Function} deps.createChunk - init => EncodedAudioChunk.
+   * @param {Object} deps.timers - { setInterval, clearInterval }.
+   * @param {Function} deps.now - мс (performance.now).
+   * @param {Object} [deps.diagnostics] - { warn(code, details) }.
+   */
+  constructor({
+    getOutput,
+    cues,
+    voiceFilter,
+    createDecoder,
+    createChunk,
+    timers,
+    now,
+    diagnostics,
+  }) {
+    this._getOutput = getOutput;
+    this._cues = cues;
+    this._voiceFilter = voiceFilter;
+    this._createDecoder = createDecoder;
+    this._createChunk = createChunk;
+    this._timers = timers;
+    this._now = now;
+    this._diagnostics = diagnostics;
+    this._talks = new Map();
+    // { ctx, out } — выход, построенный на контексте Howler
+    this._built = null;
+    // эфиры, под которыми звучит bed
+    this._audible = 0;
+  }
+
+  /** START чужого эфира. */
+  beginTalk({ speakerId, talkId }) {
+    if (!this._createDecoder) {
+      return;
+    }
+
+    const built = this._ensureOutput();
+
+    if (!built) {
+      return;
+    }
+
+    const existing = this._talks.get(speakerId);
+
+    if (existing) {
+      // тот же эфир, живой или спящий, — ничего; закрывающийся (дочитывается
+      // после STOP или засыпает) — слушатель вернулся в канал: приём заново
+      if (
+        existing.talkId === talkId &&
+        !existing.ending &&
+        !existing.finishing
+      ) {
+        return;
+      }
+
+      // устаревший эфир (talkId после смены хоста начинается заново) или
+      // закрывающийся — снимается без сигналов
+      this._drop(existing);
+    }
+
+    this._resume(built.ctx);
+
+    const talk = {
+      speakerId,
+      talkId,
+      startedAt: this._now(),
+      jb: new JitterBuffer(),
+      decoder: null,
+      playhead: null,
+      notBefore: 0,
+      missingRun: 0,
+      ending: false,
+      finishing: false,
+      dormant: false,
+      lastPacketAt: this._now(),
+      gotPacket: false,
+      warned: false,
+      bed: false,
+      sources: new Set(),
+      pump: null,
+    };
+
+    this._talks.set(speakerId, talk);
+    this._safeOpen(talk, built);
+  }
+
+  /** Голосовой пакет (host → client). */
+  push(bytes) {
+    if (!this._createDecoder) {
+      return;
+    }
+
+    const header = readVoiceHeader(bytes);
+
+    if (!header || header.port !== wsports.server.VOICE_AUDIO) {
+      return;
+    }
+
+    const talk = this._talks.get(header.speakerId);
+
+    if (!talk || talk.talkId !== header.talkId || talk.finishing) {
+      return;
+    }
+
+    if (talk.dormant && !this._wake(talk)) {
+      return;
+    }
+
+    talk.lastPacketAt = this._now();
+    talk.gotPacket = true;
+    // копия: буфер может принадлежать ретранслятору
+    talk.jb.push(header.seq, voicePayload(bytes).slice(), this._now());
+  }
+
+  /** STOP: эфир дочитывается из очереди и закрывается сигналом конца. */
+  endTalk({ speakerId, talkId }) {
+    const talk = this._talks.get(speakerId);
+
+    if (!talk || talk.talkId !== talkId) {
+      return;
+    }
+
+    if (talk.dormant) {
+      // сигнал конца уже звучал
+      this._talks.delete(speakerId);
+    } else {
+      talk.ending = true;
+    }
+  }
+
+  /**
+   * Свой сигнал: talkStart | talkEnd | busy | deny.
+   * @returns {number} длительность в секундах.
+   */
+  playCue(cue, speakerId) {
+    const built = this._ensureOutput();
+
+    if (!built) {
+      return 0;
+    }
+
+    this._resume(built.ctx);
+
+    return this._cues.play(cue, {
+      ctx: built.ctx,
+      destination: built.out.cueInput,
+      when: built.ctx.currentTime,
+      speakerId,
+    });
+  }
+
+  /**
+   * Страховка без STOP.
+   * @param {number} maxAgeMs
+   * @returns {Array<number>} speakerId эфиров старше maxAgeMs.
+   */
+  expire(maxAgeMs) {
+    if (!this._createDecoder) {
+      return [];
+    }
+
+    const expired = [];
+
+    for (const talk of [...this._talks.values()]) {
+      if (talk.ending) {
+        continue;
+      }
+
+      if (this._now() - talk.startedAt > maxAgeMs) {
+        expired.push(talk.speakerId);
+
+        if (talk.dormant) {
+          this._talks.delete(talk.speakerId);
+        } else {
+          talk.ending = true;
+        }
+      }
+    }
+
+    return expired;
+  }
+
+  /** Немедленная тишина. */
+  stopAll() {
+    for (const talk of [...this._talks.values()]) {
+      this._drop(talk);
+    }
+
+    this._audible = 0;
+    this._cues.stopBed(this._built?.ctx.currentTime ?? 0);
+  }
+
+  destroy() {
+    this.stopAll();
+    this._built?.out.dispose();
+    this._cues.forgetContext();
+    this._built = null;
+  }
+
+  // выход строится лениво на текущем контексте Howler; контекст сменился —
+  // всё старое разобрано
+  _ensureOutput() {
+    const output = this._getOutput();
+
+    if (!output) {
+      return null;
+    }
+
+    if (this._built && this._built.ctx !== output.ctx) {
+      this.stopAll();
+      this._built.out.dispose();
+      this._cues.forgetContext();
+      this._built = null;
+    }
+
+    if (!this._built) {
+      this._built = {
+        ctx: output.ctx,
+        out: createVoiceOutput(output.ctx, output.destination, {
+          voiceFilter: this._voiceFilter,
+          diagnostics: this._diagnostics,
+        }),
+      };
+      Promise.resolve(this._cues.prepare(output.ctx)).catch(() => {});
+    }
+
+    return this._built;
+  }
+
+  // без жеста браузер resume отклонит — Howler разблокирует контекст сам
+  _resume(ctx) {
+    if (ctx.state === 'suspended') {
+      try {
+        ctx.resume()?.catch?.(() => {});
+      } catch {
+        // игнор
+      }
+    }
+  }
+
+  // сбой открытия (закрывающийся контекст) снимает эфир, а не оставляет
+  // запись без декодера и насоса
+  _safeOpen(talk, built) {
+    try {
+      this._open(talk, built);
+    } catch (error) {
+      this._onDecoderError(talk, error);
+    }
+  }
+
+  // общий шаг beginTalk и wake: сигнал, bed, декодер, насос
+  _open(talk, built) {
+    const { ctx, out } = built;
+    const t0 = ctx.currentTime;
+    const cueSec = this._cues.play('incomingStart', {
+      ctx,
+      destination: out.cueInput,
+      when: t0,
+      speakerId: talk.speakerId,
+    });
+
+    talk.notBefore =
+      t0 + Math.max(START_LEAD_S, cueSec > 0 ? cueSec + CUE_GAP_S : 0);
+
+    if (this._cues.hasBed()) {
+      talk.bed = true;
+      this._audible += 1;
+
+      if (this._audible === 1) {
+        this._cues.startBed({
+          ctx,
+          destination: out.cueInput,
+          when: talk.notBefore,
+        });
+      }
+    }
+
+    try {
+      talk.decoder = this._createDecoder({
+        output: audioData => this._onAudio(talk, audioData),
+        error: error => this._onDecoderError(talk, error),
+      });
+      talk.decoder.configure(decoderConfig());
+    } catch (error) {
+      this._onDecoderError(talk, error);
+
+      return;
+    }
+
+    talk.pump = this._timers.setInterval(
+      () => this._pump(talk),
+      PUMP_INTERVAL_MS,
+    );
+  }
+
+  // новый экземпляр JitterBuffer: очередь и expected прошлого куска не
+  // переживают пробуждение, а опоздавшие пакеты получают 'late'
+  _wake(talk) {
+    const built = this._ensureOutput();
+
+    if (!built) {
+      return false;
+    }
+
+    talk.jb = new JitterBuffer({ after: talk.jb.highestSeq });
+    talk.playhead = null;
+    talk.missingRun = 0;
+    talk.dormant = false;
+    this._resume(built.ctx);
+    this._safeOpen(talk, built);
+
+    return this._talks.get(talk.speakerId) === talk;
+  }
+
+  _pump(talk) {
+    if (talk.finishing) {
+      return;
+    }
+
+    const nowMs = this._now();
+    const silence = talk.gotPacket ? SILENCE_TIMEOUT_MS : FIRST_PACKET_GRACE_MS;
+
+    if (
+      !talk.ending &&
+      talk.jb.size === 0 &&
+      nowMs - talk.lastPacketAt > silence
+    ) {
+      this._finish(talk, true);
+
+      return;
+    }
+
+    for (const item of talk.jb.pull(nowMs, { flush: talk.ending })) {
+      if (item.missing) {
+        // короткий провал не рвёт ритм речи
+        if (talk.playhead !== null && talk.missingRun < MAX_SILENT_GAP_FRAMES) {
+          talk.playhead += FRAME_S;
+          talk.missingRun += 1;
+        }
+
+        continue;
+      }
+
+      talk.missingRun = 0;
+
+      try {
+        talk.decoder.decode(
+          this._createChunk({
+            type: 'key',
+            timestamp: item.seq * FRAME_US,
+            data: item.payload,
+          }),
+        );
+      } catch (error) {
+        this._onDecoderError(talk, error);
+
+        return;
+      }
+    }
+
+    if (talk.ending && talk.jb.size === 0) {
+      this._finish(talk, false);
+    }
+  }
+
+  _onAudio(talk, audioData) {
+    const built = this._built;
+
+    if (!built || this._talks.get(talk.speakerId) !== talk) {
+      audioData.close();
+
+      return;
+    }
+
+    let samples;
+
+    try {
+      samples = audioDataToFloat32(audioData);
+    } catch (error) {
+      audioData.close();
+      this._onDecoderError(talk, error);
+
+      return;
+    }
+
+    const rate = audioData.sampleRate;
+
+    audioData.close();
+
+    const { ctx, out } = built;
+    const now = ctx.currentTime;
+    let start = talk.playhead ?? Math.max(talk.notBefore, now + MIN_LEAD_S);
+
+    // опустошение: догнали «сейчас»
+    if (start < now + MIN_LEAD_S) {
+      start = now + MIN_LEAD_S;
+    }
+
+    // задержка не копится; отсчёт от notBefore: длинный сигнал игры сдвигает
+    // начало речи и не должен резать её кадры
+    if (start - Math.max(now, talk.notBefore) > MAX_LATENCY_S) {
+      return;
+    }
+
+    const buffer = ctx.createBuffer(1, samples.length, rate);
+
+    buffer.copyToChannel(samples, 0);
+
+    const source = ctx.createBufferSource();
+
+    source.buffer = buffer;
+    source.connect(out.speechInput);
+    source.start(start);
+    talk.playhead = start + samples.length / rate;
+    talk.sources.add(source);
+    source.onended = () => talk.sources.delete(source);
+  }
+
+  _onDecoderError(talk, error) {
+    if (!talk.warned) {
+      talk.warned = true;
+      this._diagnostics?.warn('voice.decode', { message: error?.message });
+    }
+
+    this._drop(talk);
+  }
+
+  // Закрывает передачу сигналом конца. sleep — поток встал без STOP: запись
+  // остаётся «спящей», индикатор ведёт хост, а сеть могла лишь «икнуть».
+  async _finish(talk, sleep) {
+    talk.finishing = true;
+    this._timers.clearInterval(talk.pump);
+    talk.pump = null;
+
+    try {
+      await talk.decoder.flush();
+    } catch {
+      // ошибка досыла не мешает закрытию
+    }
+
+    // эфир убрали stopAll/drop/новый beginTalk — звуков уже нет
+    if (this._talks.get(talk.speakerId) !== talk || !this._built) {
+      return;
+    }
+
+    try {
+      const { ctx, out } = this._built;
+      const tailAt = Math.max(talk.playhead ?? 0, ctx.currentTime);
+      const cueSec = this._cues.play('incomingEnd', {
+        ctx,
+        destination: out.cueInput,
+        when: tailAt,
+        speakerId: talk.speakerId,
+      });
+
+      this._releaseBed(talk, tailAt + cueSec);
+    } catch (error) {
+      this._onDecoderError(talk, error);
+
+      return;
+    }
+
+    try {
+      talk.decoder.close();
+    } catch {
+      // уже закрыт
+    }
+
+    talk.decoder = null;
+
+    // STOP пришёл, пока эфир засыпал: спать нечему
+    if (sleep && !talk.ending) {
+      talk.dormant = true;
+      talk.finishing = false;
+    } else {
+      this._talks.delete(talk.speakerId);
+    }
+  }
+
+  // без сигналов
+  _drop(talk) {
+    this._timers.clearInterval(talk.pump);
+    talk.pump = null;
+
+    for (const source of talk.sources) {
+      try {
+        source.stop();
+      } catch {
+        // уже остановлен
+      }
+    }
+
+    talk.sources.clear();
+
+    try {
+      talk.decoder?.close();
+    } catch {
+      // уже закрыт
+    }
+
+    talk.decoder = null;
+    this._releaseBed(talk, this._built?.ctx.currentTime ?? 0);
+
+    if (this._talks.get(talk.speakerId) === talk) {
+      this._talks.delete(talk.speakerId);
+    }
+  }
+
+  _releaseBed(talk, when) {
+    if (!talk.bed) {
+      return;
+    }
+
+    talk.bed = false;
+    this._audible -= 1;
+
+    if (this._audible <= 0) {
+      this._audible = 0;
+      this._cues.stopBed(when);
+    }
+  }
+}

package/src/client/voice/audioData.js

@@ -0,0 +1,35 @@
+/**
+ * AudioData → Float32Array (моно, первый канал). Форматы 'f32', 'f32-planar',
+ * 's16', 's16-planar'; интерливные многоканальные читаются через шаг в
+ * numberOfChannels сэмплов.
+ * @param {AudioData} audioData
+ * @returns {Float32Array}
+ * @throws {RangeError} другой формат сэмплов.
+ */
+export function audioDataToFloat32(audioData) {
+  const { format, numberOfFrames: frames } = audioData;
+  const channels = Math.max(1, audioData.numberOfChannels || 1);
+  const planar = typeof format === 'string' && format.endsWith('-planar');
+  const base = typeof format === 'string' ? format.replace('-planar', '') : '';
+
+  if (base !== 'f32' && base !== 's16') {
+    throw new RangeError(`voice: unsupported audio format ${format}`);
+  }
+
+  const Typed = base === 'f32' ? Float32Array : Int16Array;
+  const raw = new Typed(
+    audioData.allocationSize({ planeIndex: 0 }) / Typed.BYTES_PER_ELEMENT,
+  );
+
+  audioData.copyTo(raw, { planeIndex: 0 });
+
+  const stride = planar ? 1 : channels;
+  const scale = base === 's16' ? 1 / 32768 : 1;
+  const out = new Float32Array(frames);
+
+  for (let i = 0; i < frames; i++) {
+    out[i] = raw[i * stride] * scale;
+  }
+
+  return out;
+}