vimp-engine 0.38.2 → 0.39.0

package/src/client/voice/VoiceCues.js

@@ -0,0 +1,295 @@
+import { VOICE_CUES, synthesizeTone } from './voiceTones.js';
+
+// с большим запасом: два входящих сигнала на каждого из 64 участников плюс
+// свои сигналы и bed — в полной комнате записи не вытесняют друг друга.
+// Потолка байт нет: вытесненный сигнал синтезировался бы заново в момент
+// звука; память держат короткие сигналы игры (plugin-api.md)
+const GAME_CUE_CACHE_MAX = 256;
+// потолок звука игры, секунд: bed — петля, остальные — короткие сигналы
+const MAX_BED_S = 10;
+const MAX_CUE_S = 2;
+const BED_FADE_IN_S = 0.02;
+const BED_FADE_OUT_S = 0.05;
+
+const isPlainObject = value => {
+  if (value === null || typeof value !== 'object') {
+    return false;
+  }
+
+  const proto = Object.getPrototypeOf(value);
+
+  return proto === Object.prototype || proto === null;
+};
+
+/**
+ * Сигналы связи: звук игры из хука `voiceSounds` или нейтральный тон
+ * движка, кэш буферов, петля `bed`.
+ */
+export default class VoiceCues {
+  /**
+   * @param {Object} [deps]
+   * @param {Function} [deps.voiceSounds] - ClientPlugin.hooks.voiceSounds.
+   * @param {Object} [deps.diagnostics] - { warn(code, details) }.
+   */
+  constructor({ voiceSounds, diagnostics } = {}) {
+    this._hook = voiceSounds;
+    this._diagnostics = diagnostics;
+    this._rate = null;
+    this._promise = null;
+    // Map<сигнал, null | функция> — проверенный ответ хука
+    this._set = null;
+    this._warned = new Set();
+    this._cacheCtx = null;
+    this._toneCache = new Map();
+    this._gameCache = new Map();
+    this._bed = null;
+  }
+
+  /**
+   * Вызывает хук игры для частоты контекста (один раз на частоту) и ждёт
+   * набор; без хука — сразу. Пока промис не разрешён, звучат тоны движка.
+   * @param {BaseAudioContext} ctx
+   * @returns {Promise<void>}
+   */
+  prepare(ctx) {
+    const rate = ctx.sampleRate;
+
+    if (this._promise && this._rate === rate) {
+      return this._promise;
+    }
+
+    this._rate = rate;
+    this._set = null;
+
+    if (typeof this._hook !== 'function') {
+      this._promise = Promise.resolve();
+
+      return this._promise;
+    }
+
+    const promise = Promise.resolve()
+      .then(() => this._hook({ sampleRate: rate }))
+      .then(answer => {
+        if (this._promise === promise) {
+          this._set = this._validateSet(answer);
+        }
+      })
+      .catch(error => {
+        if (this._promise === promise) {
+          this._warn('hook', { message: error?.message });
+        }
+      });
+
+    this._promise = promise;
+
+    return promise;
+  }
+
+  /**
+   * Ставит сигнал на destination в момент when.
+   * @param {string} cue - из VOICE_CUES.
+   * @param {Object} target
+   * @param {BaseAudioContext} target.ctx
+   * @param {AudioNode} target.destination
+   * @param {number} target.when - секунды контекста.
+   * @param {number|null} [target.speakerId] - свой id у своих сигналов,
+   *   id говорящего у входящих.
+   * @returns {number} длительность в секундах; 0 — сигнал молчит.
+   */
+  play(cue, { ctx, destination, when, speakerId = null }) {
+    const buffer = this._resolve(cue, ctx, speakerId);
+
+    if (!buffer) {
+      return 0;
+    }
+
+    const source = ctx.createBufferSource();
+
+    source.buffer = buffer;
+    source.connect(destination);
+    source.start(when);
+
+    return buffer.duration;
+  }
+
+  /** @returns {boolean} игра дала петлю bed. */
+  hasBed() {
+    return typeof this._set?.get('bed') === 'function';
+  }
+
+  /** Плавно запускает петлю bed в момент when (без bed — ничего). */
+  startBed({ ctx, destination, when }) {
+    if (this._bed || !this.hasBed()) {
+      return;
+    }
+
+    const buffer = this._resolve('bed', ctx, null);
+
+    if (!buffer) {
+      return;
+    }
+
+    const source = ctx.createBufferSource();
+    const gain = ctx.createGain();
+
+    source.buffer = buffer;
+    source.loop = true;
+    gain.gain.setValueAtTime(0, when);
+    gain.gain.linearRampToValueAtTime(1, when + BED_FADE_IN_S);
+    source.connect(gain);
+    gain.connect(destination);
+    source.start(when);
+    this._bed = { source, gain, ctx };
+  }
+
+  /** Плавно гасит петлю bed в момент when. */
+  stopBed(when) {
+    const bed = this._bed;
+
+    if (!bed) {
+      return;
+    }
+
+    this._bed = null;
+    bed.gain.gain.setValueAtTime(1, when);
+    bed.gain.gain.linearRampToValueAtTime(0, when + BED_FADE_OUT_S);
+    bed.source.stop(when + BED_FADE_OUT_S + 0.01);
+  }
+
+  /** Контекст пересоздан: буферы старого — в мусор. */
+  forgetContext() {
+    this._cacheCtx = null;
+    this._toneCache.clear();
+    this._gameCache.clear();
+    this._bed = null;
+  }
+
+  _validateSet(answer) {
+    if (!isPlainObject(answer)) {
+      this._warn('set', {
+        message: 'voiceSounds must resolve to a plain object',
+      });
+
+      return null;
+    }
+
+    const set = new Map();
+
+    for (const [key, value] of Object.entries(answer)) {
+      if (!VOICE_CUES.includes(key)) {
+        this._warn(`key:${key}`, { key, message: 'unknown voice cue' });
+      } else if (value !== null && typeof value !== 'function') {
+        this._warn(`value:${key}`, {
+          cue: key,
+          message: 'voice cue must be null or a function',
+        });
+      } else {
+        set.set(key, value);
+      }
+    }
+
+    return set;
+  }
+
+  // одно предупреждение на ключ
+  _warn(key, details) {
+    if (this._warned.has(key)) {
+      return;
+    }
+
+    this._warned.add(key);
+    this._diagnostics?.warn('voice.sound', details);
+  }
+
+  _resolve(cue, ctx, speakerId) {
+    if (this._cacheCtx !== ctx) {
+      this._toneCache.clear();
+      this._gameCache.clear();
+      this._bed = null;
+      this._cacheCtx = ctx;
+    }
+
+    if (!this._set?.has(cue)) {
+      return this._tone(cue, ctx);
+    }
+
+    const fn = this._set.get(cue);
+
+    if (fn === null) {
+      return null;
+    }
+
+    const key = `${cue}:${speakerId ?? '-'}`;
+
+    if (this._gameCache.has(key)) {
+      const cached = this._gameCache.get(key);
+
+      // LRU: свежая запись уходит в конец
+      this._gameCache.delete(key);
+      this._gameCache.set(key, cached);
+
+      return cached;
+    }
+
+    let samples;
+
+    try {
+      samples = fn(speakerId);
+    } catch (error) {
+      this._warn(`cue:${cue}`, { cue, message: error?.message });
+
+      return this._tone(cue, ctx);
+    }
+
+    let buffer = null;
+
+    if (samples !== null) {
+      const max = ctx.sampleRate * (cue === 'bed' ? MAX_BED_S : MAX_CUE_S);
+
+      if (
+        !(samples instanceof Float32Array) ||
+        samples.length < 1 ||
+        samples.length > max ||
+        !samples.every(Number.isFinite)
+      ) {
+        this._warn(`cue:${cue}`, {
+          cue,
+          message: 'voice cue must return a finite mono Float32Array or null',
+        });
+
+        return this._tone(cue, ctx);
+      }
+
+      buffer = this._makeBuffer(ctx, samples);
+    }
+
+    this._gameCache.set(key, buffer);
+
+    if (this._gameCache.size > GAME_CUE_CACHE_MAX) {
+      this._gameCache.delete(this._gameCache.keys().next().value);
+    }
+
+    return buffer;
+  }
+
+  _tone(cue, ctx) {
+    if (this._toneCache.has(cue)) {
+      return this._toneCache.get(cue);
+    }
+
+    const samples = synthesizeTone(cue, ctx.sampleRate);
+    const buffer = samples ? this._makeBuffer(ctx, samples) : null;
+
+    this._toneCache.set(cue, buffer);
+
+    return buffer;
+  }
+
+  _makeBuffer(ctx, samples) {
+    const buffer = ctx.createBuffer(1, samples.length, ctx.sampleRate);
+
+    buffer.copyToChannel(samples, 0);
+
+    return buffer;
+  }
+}

package/src/client/voice/VoiceEncoder.js

@@ -0,0 +1,174 @@
+import wsports from '../../config/wsports.js';
+import {
+  VOICE_MAX_PACKET_BYTES,
+  VOICE_SAMPLE_RATE,
+} from '../../config/voiceProtocol.js';
+import { encodeVoicePacket } from '../../lib/voicePacket.js';
+
+// глубже очередь энкодера — CPU не успевает: живость важнее полноты
+const MAX_QUEUE = 4;
+
+/**
+ * Кадры микрофона → голосовые пакеты (Opus через WebCodecs).
+ */
+export default class VoiceEncoder {
+  /**
+   * @param {Object} deps
+   * @param {Object} deps.config - конфиг энкодера из detectVoiceSupport.
+   * @param {Function} deps.createEncoder - init => AudioEncoder.
+   * @param {Function} deps.createAudioData - init => AudioData.
+   * @param {Function} deps.onPacket - (Uint8Array) => void.
+   * @param {Function} [deps.onError] - (Error) => void.
+   */
+  constructor({ config, createEncoder, createAudioData, onPacket, onError }) {
+    this._config = config;
+    this._createEncoder = createEncoder;
+    this._createAudioData = createAudioData;
+    this._onPacket = onPacket;
+    this._onError = onError;
+    this._encoder = null;
+    this._configured = false;
+    this._talkId = null;
+    this._seq = 0;
+  }
+
+  /**
+   * Начинает эфир: seq с нуля, энкодер сконфигурирован.
+   * @param {number} talkId
+   */
+  begin(talkId) {
+    if (!this._encoder) {
+      const encoder = this._createEncoder({
+        // чанки выброшенного энкодера не попадают в поток нового эфира
+        output: chunk => {
+          if (encoder === this._encoder) {
+            this._onChunk(chunk);
+          }
+        },
+        // колбэк уже выброшенного энкодера не трогает новый
+        error: error => this._fail(error, encoder),
+      });
+
+      this._encoder = encoder;
+      this._configured = false;
+    }
+
+    if (!this._configured) {
+      this._encoder.configure(this._config);
+      this._configured = true;
+    }
+
+    this._talkId = talkId;
+    this._seq = 0;
+  }
+
+  /**
+   * @param {Float32Array} samples - кадр 20 мс, 48 кГц, моно.
+   * @param {number} timestampUs
+   */
+  encode(samples, timestampUs) {
+    if (this._talkId === null || !this._encoder) {
+      return;
+    }
+
+    if (this._encoder.encodeQueueSize > MAX_QUEUE) {
+      return;
+    }
+
+    const audioData = this._createAudioData({
+      format: 'f32-planar',
+      sampleRate: VOICE_SAMPLE_RATE,
+      numberOfFrames: samples.length,
+      numberOfChannels: 1,
+      timestamp: timestampUs,
+      data: samples,
+    });
+
+    try {
+      this._encoder.encode(audioData);
+    } catch (error) {
+      // закрытый энкодер бросает синхронно: тот же сбой, что колбэк error
+      this._fail(error, this._encoder);
+    } finally {
+      audioData.close();
+    }
+  }
+
+  /**
+   * Заканчивает эфир. reset(), а не flush(): после RELEASE хост снимает
+   * маршрут, хвостовые пакеты ретранслятор всё равно выбросил бы. Бросок
+   * reset() — сбой энкодера, как в encode().
+   */
+  end() {
+    this._talkId = null;
+
+    if (!this._encoder || !this._configured) {
+      return;
+    }
+
+    const encoder = this._encoder;
+
+    try {
+      encoder.reset();
+      this._configured = false;
+    } catch (error) {
+      // закрытый энкодер бросает синхронно, как в encode()
+      this._fail(error, encoder);
+    }
+  }
+
+  destroy() {
+    this._talkId = null;
+
+    try {
+      this._encoder?.close();
+    } catch {
+      // уже закрыт
+    }
+
+    this._encoder = null;
+    this._configured = false;
+  }
+
+  _onChunk(chunk) {
+    if (this._talkId === null) {
+      return;
+    }
+
+    const payload = new Uint8Array(chunk.byteLength);
+
+    chunk.copyTo(payload);
+
+    const bytes = encodeVoicePacket({
+      port: wsports.client.VOICE_AUDIO,
+      talkId: this._talkId,
+      seq: this._seq,
+      payload,
+    });
+
+    this._seq = (this._seq + 1) & 0xffff;
+
+    if (bytes.length <= VOICE_MAX_PACKET_BYTES) {
+      this._onPacket(bytes);
+    }
+  }
+
+  // сломанный энкодер выбрасывается один раз: следующий begin создаст новый
+  _fail(error, encoder) {
+    if (encoder !== this._encoder) {
+      return;
+    }
+
+    this._talkId = null;
+    this._encoder = null;
+    this._configured = false;
+
+    try {
+      encoder.close();
+    } catch {
+      // уже закрыт
+    }
+
+    this._onError?.(error);
+  }
+}