vimp-engine 0.38.2 → 0.39.0

package/src/client/voice/PttMachine.js

@@ -0,0 +1,369 @@
+import {
+  VOICE_DENY,
+  VOICE_END,
+  VOICE_REQUEST_MIN_INTERVAL_MS,
+  VOICE_REQUEST_TIMEOUT_MS,
+} from '../../config/voiceProtocol.js';
+
+// Разброс автозахвата по освобождению эфира: STOP приходит всем ждущим почти
+// одновременно, и без разброса эфир всегда доставался бы игроку с наименьшим
+// пингом до хоста. Только для повтора по STOP: повтор по кулдауну
+// индивидуален.
+const AUTO_RETRY_JITTER_MS = 60;
+
+/**
+ * Машина клавиши PTT: удержание → запрос эфира → разговор. Чистая логика:
+ * действия и таймеры внедряются. Состояния: idle, acquiring, requesting,
+ * waiting (автозахват при занятом эфире или кулдауне), talking, latched
+ * (эфир оборван или отказан — нужно отпустить клавишу, автопродления нет).
+ */
+export default class PttMachine {
+  /**
+   * @param {Object} deps
+   * @param {Object} deps.config - { maxDurationMs, cooldownMs }.
+   * @param {Object} deps.effects - {
+   *   sendRequest(), sendRelease(talkId), startCapture(talkId),
+   *   stopCapture(), acquireMic() → Promise<boolean>, micState() → string,
+   *   canCapture() → boolean, play(cue), hud(kind, data) }.
+   * @param {Object} deps.timers - { setTimeout, clearTimeout }.
+   * @param {Function} deps.now - мс.
+   * @param {Function} [deps.random] - [0, 1).
+   */
+  constructor({ config, effects, timers, now, random = Math.random }) {
+    this._config = config;
+    this._fx = effects;
+    this._timers = timers;
+    this._now = now;
+    this._random = random;
+
+    this._state = 'idle';
+    // растёт на каждом нажатии: ответ acquireMic прошлого удержания не
+    // трогает новое
+    this._holdId = 0;
+    this._talkId = null;
+    this._cooldownUntil = 0;
+    // сигнал отказа звучит один раз за удержание
+    this._deniedThisHold = false;
+    this._waitReason = null;
+    this._requestTimer = null;
+    this._retryTimer = null;
+    this._talkTimer = null;
+  }
+
+  get state() {
+    return this._state;
+  }
+
+  /** Клавиша вниз. */
+  press() {
+    this._holdId += 1;
+    this._deniedThisHold = false;
+
+    if (this._state !== 'idle') {
+      return;
+    }
+
+    if (!this._fx.canCapture()) {
+      this._fail('unsupported');
+
+      return;
+    }
+
+    // без готового микрофона разрешение спрашивается на каждом нажатии, и
+    // после отказа тоже: закрытый запрос браузер задаст снова, а
+    // заблокированный сайт getUserMedia отвергнет сразу, без окна
+    if (this._fx.micState() !== 'ready') {
+      const hold = this._holdId;
+
+      this._state = 'acquiring';
+      this._fx.acquireMic().then(
+        ok => (ok ? this._micReady(hold) : this._micFailed(hold)),
+        () => this._micFailed(hold),
+      );
+
+      return;
+    }
+
+    this._attempt();
+  }
+
+  /** Клавиша вверх / потеря фокуса. */
+  releaseKey() {
+    switch (this._state) {
+      case 'acquiring':
+        this._state = 'idle';
+        break;
+
+      case 'requesting':
+        this._clearRequestTimer();
+        this._fx.hud('hidden');
+        this._state = 'idle';
+        break;
+
+      case 'waiting':
+        this._clearRetryTimer();
+        this._waitReason = null;
+        this._showCooldown();
+        this._state = 'idle';
+        break;
+
+      case 'talking':
+        this._finishOwn();
+        this._state = 'idle';
+        break;
+
+      case 'latched':
+        this._showCooldown();
+        this._state = 'idle';
+        break;
+
+      default:
+    }
+  }
+
+  onGrant(talkId, maxMs) {
+    if (this._state === 'requesting') {
+      this._clearRequestTimer();
+      this._talkId = talkId;
+      this._state = 'talking';
+      this._fx.startCapture(talkId);
+      this._fx.play('talkStart');
+      this._fx.hud('talking', {
+        endsAt: this._now() + maxMs,
+        totalMs: maxMs,
+      });
+      this._talkTimer = this._timers.setTimeout(() => {
+        this._talkTimer = null;
+        this._finishOwn();
+        this._state = 'latched';
+      }, maxMs);
+
+      return;
+    }
+
+    if (this._state === 'talking' && this._talkId === talkId) {
+      return;
+    }
+
+    // эфир, который клиент уже не держит (поздний ответ, повторный GRANT)
+    this._fx.sendRelease(talkId);
+  }
+
+  onDeny(reason, retryAfterMs) {
+    if (this._state !== 'requesting') {
+      return;
+    }
+
+    this._clearRequestTimer();
+
+    if (reason === VOICE_DENY.BUSY) {
+      this._waitReason = 'busy';
+      this._fx.hud('busy');
+      this._denySignal('busy');
+      this._state = 'waiting';
+    } else if (reason === VOICE_DENY.COOLDOWN) {
+      // не чаще порога хоста: retryAfterMs около 0 дал бы цикл запросов
+      const wait = Math.max(retryAfterMs, VOICE_REQUEST_MIN_INTERVAL_MS);
+
+      this._waitReason = 'cooldown';
+      this._fx.hud('cooldown', { endsAt: this._now() + retryAfterMs });
+      this._denySignal('deny');
+      this._armRetry(wait);
+      this._state = 'waiting';
+    } else {
+      this._fail('unavailable');
+    }
+  }
+
+  onEnd(talkId, reason) {
+    if (this._state !== 'talking' || talkId !== this._talkId) {
+      return;
+    }
+
+    this._clearTalkTimer();
+    this._fx.stopCapture();
+    this._fx.play('talkEnd');
+    this._cooldownUntil = this._now() + this._config.cooldownMs;
+    this._talkId = null;
+
+    if (reason === VOICE_END.REVOKED) {
+      this._fx.hud('error', { textKey: 'unavailable' });
+    } else {
+      this._showCooldown();
+    }
+
+    this._state = 'latched';
+  }
+
+  /** STOP слышимого эфира или страховка, погасившая эфир без STOP. */
+  onChannelFree() {
+    if (
+      this._state === 'waiting' &&
+      this._waitReason === 'busy' &&
+      this._retryTimer === null
+    ) {
+      this._armRetry(Math.floor(this._random() * AUTO_RETRY_JITTER_MS));
+    }
+  }
+
+  /** Чужой START: канал занял другой. */
+  onChannelBusy() {
+    if (
+      this._state === 'waiting' &&
+      this._waitReason === 'busy' &&
+      this._retryTimer !== null
+    ) {
+      // запрос был бы заведомо проигрышным: ждать следующего STOP
+      this._clearRetryTimer();
+    }
+  }
+
+  /** Свой захват умер: энкодер упал, граф снят. */
+  onLocalFailure() {
+    switch (this._state) {
+      case 'requesting':
+        // пришедший позже GRANT отпустит onGrant (состояние уже не requesting)
+        this._clearRequestTimer();
+        this._fail('unavailable');
+        break;
+
+      case 'waiting':
+        this._clearRetryTimer();
+        this._waitReason = null;
+        this._fail('unavailable');
+        break;
+
+      case 'talking':
+        this._finishOwn();
+        this._fx.hud('error', { textKey: 'unavailable' });
+        this._state = 'latched';
+        break;
+
+      default:
+    }
+  }
+
+  /**
+   * Пауза сессии / закрытие: тихо в idle. RELEASE не шлётся: эфир при
+   * паузе снимает хост (заморозка, отсоединение, D15).
+   */
+  reset() {
+    this._clearRequestTimer();
+    this._clearRetryTimer();
+    this._clearTalkTimer();
+
+    if (this._state === 'talking') {
+      this._fx.stopCapture();
+    }
+
+    this._talkId = null;
+    this._waitReason = null;
+    this._state = 'idle';
+    this._fx.hud('hidden');
+  }
+
+  _micReady(hold) {
+    if (this._state === 'acquiring' && hold === this._holdId) {
+      this._attempt();
+    }
+  }
+
+  // micBlocked — только отказ в разрешении; нет устройства, занято,
+  // контекст сменился — unavailable
+  _micFailed(hold) {
+    if (this._state === 'acquiring' && hold === this._holdId) {
+      this._fail(
+        this._fx.micState() === 'denied' ? 'micBlocked' : 'unavailable',
+      );
+    }
+  }
+
+  // ошибка с вспышкой в HUD: до отпускания клавиши ничего не повторяется
+  _fail(textKey) {
+    this._fx.hud('error', { textKey });
+    this._fx.play('deny');
+    this._state = 'latched';
+  }
+
+  _attempt() {
+    const left = this._cooldownUntil - this._now();
+
+    if (left > 0) {
+      this._waitReason = 'cooldown';
+      this._showCooldown();
+      this._denySignal('deny');
+      this._armRetry(left);
+      this._state = 'waiting';
+
+      return;
+    }
+
+    this._fx.sendRequest();
+    this._requestTimer = this._timers.setTimeout(() => {
+      // поздний GRANT отпустит onGrant (состояние уже не requesting)
+      this._requestTimer = null;
+      this._fail('unavailable');
+    }, VOICE_REQUEST_TIMEOUT_MS);
+    this._state = 'requesting';
+  }
+
+  // конец своего эфира: захват, RELEASE, сигнал, кулдаун
+  _finishOwn() {
+    const talkId = this._talkId;
+
+    this._clearTalkTimer();
+    this._fx.stopCapture();
+    this._fx.sendRelease(talkId);
+    this._fx.play('talkEnd');
+    this._cooldownUntil = this._now() + this._config.cooldownMs;
+    this._showCooldown();
+    this._talkId = null;
+  }
+
+  _denySignal(cue) {
+    if (!this._deniedThisHold) {
+      this._fx.play(cue);
+      this._deniedThisHold = true;
+    }
+  }
+
+  _showCooldown() {
+    if (this._now() < this._cooldownUntil) {
+      this._fx.hud('cooldown', { endsAt: this._cooldownUntil });
+    } else {
+      this._fx.hud('hidden');
+    }
+  }
+
+  _armRetry(ms) {
+    this._clearRetryTimer();
+    this._retryTimer = this._timers.setTimeout(() => {
+      this._retryTimer = null;
+
+      if (this._state === 'waiting') {
+        this._attempt();
+      }
+    }, ms);
+  }
+
+  _clearRequestTimer() {
+    if (this._requestTimer !== null) {
+      this._timers.clearTimeout(this._requestTimer);
+      this._requestTimer = null;
+    }
+  }
+
+  _clearRetryTimer() {
+    if (this._retryTimer !== null) {
+      this._timers.clearTimeout(this._retryTimer);
+      this._retryTimer = null;
+    }
+  }
+
+  _clearTalkTimer() {
+    if (this._talkTimer !== null) {
+      this._timers.clearTimeout(this._talkTimer);
+      this._talkTimer = null;
+    }
+  }
+}

package/src/client/voice/VoiceClient.js

@@ -0,0 +1,336 @@
+import { VOICE_LISTENER_SAFETY_MS } from '../../config/voiceProtocol.js';
+import {
+  floorReleaseMessage,
+  floorRequestMessage,
+} from '../../lib/voiceMessages.js';
+import { toBytes } from '../../lib/voicePacket.js';
+import MicCapture from './MicCapture.js';
+import PttMachine from './PttMachine.js';
+import VoiceCues from './VoiceCues.js';
+import VoiceEncoder from './VoiceEncoder.js';
+import VoicePlayback from './VoicePlayback.js';
+import { detectVoiceSupport } from './voiceSupport.js';
+
+// страховка индикаторов и автозахвата проверяется раз в секунду
+const SAFETY_TICK_MS = 1000;
+
+/**
+ * Оркестратор голосовой связи клиента: клавиша PTT → машина → запросы эфира
+ * и захват → пакеты; VOICE_DATA → HUD, сигналы, воспроизведение.
+ */
+export default class VoiceClient {
+  /**
+   * @param {Object} deps
+   * @param {Object} deps.config - CONFIG_DATA.voice (нормализованный).
+   * @param {Function} deps.sendFloor - payload => void (порт VOICE_FLOOR).
+   * @param {Function} deps.sendAudio - Uint8Array => void.
+   * @param {Object} deps.soundManager - getAudioOutput().
+   * @param {Object} deps.localPlayer - { id, is(id) }.
+   * @param {Object} deps.hud - контроллер HUD: showOwn, setIncoming.
+   * @param {Object} deps.voiceStore - хранилище lib/voiceState.js.
+   * @param {Function} [deps.voiceSounds] - ClientPlugin.hooks.voiceSounds.
+   * @param {Function} [deps.voiceFilter] - ClientPlugin.hooks.voiceFilter.
+   * @param {Object} [deps.diagnostics] - { warn, capture }.
+   * @param {Object} [deps.platform] - globals, timers, now, random,
+   *   mediaDevices, createWorkletNode, createEncoder, createDecoder,
+   *   createAudioData, createChunk; тесты подставляют фейки. Своего
+   *   AudioContext нет: захват и вывод — на контексте движка.
+   */
+  constructor({
+    config,
+    sendFloor,
+    sendAudio,
+    soundManager,
+    localPlayer,
+    hud,
+    voiceStore,
+    voiceSounds,
+    voiceFilter,
+    diagnostics,
+    platform = {},
+  }) {
+    const globals = platform.globals ?? globalThis;
+
+    this._config = config;
+    this._sendFloor = sendFloor;
+    this._sendAudio = sendAudio;
+    this._soundManager = soundManager;
+    this._localPlayer = localPlayer;
+    this._hud = hud;
+    this._store = voiceStore;
+    this._voiceSounds = voiceSounds;
+    this._voiceFilter = voiceFilter;
+    this._diagnostics = diagnostics;
+    this._globals = globals;
+    this._timers = platform.timers ?? {
+      setTimeout: (...args) => globals.setTimeout(...args),
+      clearTimeout: id => globals.clearTimeout(id),
+      setInterval: (...args) => globals.setInterval(...args),
+      clearInterval: id => globals.clearInterval(id),
+    };
+    this._now = platform.now ?? (() => globals.performance.now());
+    this._random = platform.random;
+    this._mediaDevices =
+      platform.mediaDevices ?? globals.navigator?.mediaDevices;
+    this._createWorkletNode = platform.createWorkletNode;
+    this._createEncoder =
+      platform.createEncoder ?? (init => new globals.AudioEncoder(init));
+    this._createDecoder =
+      platform.createDecoder ?? (init => new globals.AudioDecoder(init));
+    this._createAudioData =
+      platform.createAudioData ?? (init => new globals.AudioData(init));
+    this._createChunk =
+      platform.createChunk ?? (init => new globals.EncodedAudioChunk(init));
+
+    this._machine = null;
+    this._mic = null;
+    this._encoder = null;
+    this._playback = null;
+    this._interval = null;
+    // чужой эфир, показанный в HUD: { speakerId, talkId, at }
+    this._incoming = null;
+    this._destroyed = false;
+  }
+
+  async init() {
+    const getOutput = () => this._soundManager.getAudioOutput();
+    const support = await detectVoiceSupport({
+      globals: this._globals,
+      bitrate: this._config.bitrate,
+      getOutput,
+    });
+
+    if (this._destroyed) {
+      return;
+    }
+
+    const cues = new VoiceCues({
+      voiceSounds: this._voiceSounds,
+      diagnostics: this._diagnostics,
+    });
+    const output = getOutput();
+
+    if (output) {
+      // хук игры зовётся здесь; сбои уходят в предупреждения внутри VoiceCues
+      Promise.resolve(cues.prepare(output.ctx)).catch(() => {});
+    }
+
+    if (support.capture) {
+      this._encoder = new VoiceEncoder({
+        config: support.encoderConfig,
+        createEncoder: this._createEncoder,
+        createAudioData: this._createAudioData,
+        onPacket: bytes => this._sendAudio(bytes),
+        onError: error => {
+          // после destroy() энкодер разбирается вместе с матчем —
+          // предупреждение было бы шумом
+          if (this._destroyed) {
+            return;
+          }
+
+          this._diagnostics?.warn('voice.encode', { message: error?.message });
+          this._failLater();
+        },
+      });
+      this._mic = new MicCapture({
+        mediaDevices: this._mediaDevices,
+        getContext: () => getOutput()?.ctx ?? null,
+        createWorkletNode: this._createWorkletNode,
+        timers: this._timers,
+        onFrame: (samples, timestampUs) =>
+          this._encoder.encode(samples, timestampUs),
+        // контекст закрыт или микрофон выдернут посреди эфира: эфир
+        // отпускается сразу, а не «говорит» тишиной до таймаута
+        onLost: () => this._machine.onLocalFailure(),
+      });
+    }
+
+    if (output) {
+      this._playback = new VoicePlayback({
+        getOutput,
+        cues,
+        voiceFilter: this._voiceFilter,
+        createDecoder: support.playback ? this._createDecoder : null,
+        createChunk: this._createChunk,
+        timers: this._timers,
+        now: this._now,
+        diagnostics: this._diagnostics,
+      });
+    }
+
+    this._machine = new PttMachine({
+      config: this._config,
+      timers: this._timers,
+      now: this._now,
+      random: this._random,
+      effects: {
+        sendRequest: () => this._sendFloor(floorRequestMessage()),
+        sendRelease: talkId => this._sendFloor(floorReleaseMessage(talkId)),
+        startCapture: talkId => {
+          this._encoder.begin(talkId);
+
+          if (!this._mic.start()) {
+            // граф умер между нажатием и выдачей
+            this._failLater();
+          }
+        },
+        stopCapture: () => {
+          this._mic?.stop();
+          this._encoder?.end();
+        },
+        acquireMic: () => this._mic.acquire(),
+        micState: () => this._mic?.state ?? 'idle',
+        canCapture: () => support.capture,
+        play: cue => this._playback?.playCue(cue, this._localPlayer.id ?? 0),
+        hud: (kind, data) => this._hud.showOwn(kind, data),
+      },
+    });
+
+    this._interval = this._timers.setInterval(
+      () => this._expire(),
+      SAFETY_TICK_MS,
+    );
+  }
+
+  /** Клавиша PTT (от Controls). */
+  setPttHeld(held) {
+    if (held) {
+      this._machine?.press();
+    } else {
+      this._machine?.releaseKey();
+    }
+  }
+
+  /** Разобранное parseVoiceMessage. */
+  handleFloorMessage(message) {
+    const machine = this._machine;
+
+    if (!machine) {
+      return;
+    }
+
+    switch (message.type) {
+      case 'grant':
+        machine.onGrant(message.talkId, message.maxDurationMs);
+        break;
+
+      case 'deny':
+        machine.onDeny(message.reason, message.retryAfterMs);
+        break;
+
+      case 'end':
+        machine.onEnd(message.talkId, message.reason);
+        break;
+
+      case 'start':
+        // свой эфир ведёт хранилище индикаторов, не воспроизведение
+        if (!this._localPlayer.is(message.speakerId)) {
+          this._playback?.beginTalk({
+            speakerId: message.speakerId,
+            talkId: message.talkId,
+          });
+          this._hud.setIncoming({
+            name: message.name,
+            teamId: message.teamId,
+            color: message.color,
+          });
+          this._incoming = {
+            speakerId: message.speakerId,
+            talkId: message.talkId,
+            at: this._now(),
+          };
+          machine.onChannelBusy();
+        }
+
+        break;
+
+      case 'stop':
+        if (!this._localPlayer.is(message.speakerId)) {
+          this._playback?.endTalk({
+            speakerId: message.speakerId,
+            talkId: message.talkId,
+          });
+
+          if (
+            this._incoming?.speakerId === message.speakerId &&
+            this._incoming.talkId === message.talkId
+          ) {
+            this._hud.setIncoming(null);
+            this._incoming = null;
+          }
+        }
+
+        machine.onChannelFree();
+        break;
+
+      default:
+    }
+  }
+
+  /** Голосовой пакет от транспорта. */
+  handleAudio(data) {
+    const bytes = toBytes(data);
+
+    if (bytes) {
+      this._playback?.push(bytes);
+    }
+  }
+
+  /** Пауза сессии: тишина, HUD скрыт. */
+  suspend() {
+    this._machine?.reset();
+    this._playback?.stopAll();
+    this._hud.showOwn('hidden');
+    this._hud.setIncoming(null);
+    this._incoming = null;
+  }
+
+  /** Закрытие матча. */
+  destroy() {
+    this._destroyed = true;
+    this.suspend();
+    this._mic?.destroy();
+    this._encoder?.destroy();
+    this._playback?.destroy();
+
+    if (this._interval !== null) {
+      this._timers.clearInterval(this._interval);
+      this._interval = null;
+    }
+  }
+
+  // Сбой эффекта машины (энкодер, граф в startCapture): эффект бросает
+  // посреди перехода, и onLocalFailure вошёл бы в него повторно (двойной
+  // RELEASE и talkEnd) — машина узнаёт о сбое после перехода
+  _failLater() {
+    queueMicrotask(() => {
+      if (!this._destroyed) {
+        this._machine?.onLocalFailure();
+      }
+    });
+  }
+
+  // Страховка без STOP (вкладка хоста пропала, слушатель переподключался):
+  // индикаторы, звук и автозахват не залипают
+  _expire() {
+    const limit = this._config.maxDurationMs + VOICE_LISTENER_SAFETY_MS;
+    const removed = this._store.expire(limit);
+    const expired = this._playback?.expire(limit) ?? [];
+    let freed = removed > 0 || expired.length > 0;
+    const incoming = this._incoming;
+
+    if (
+      incoming &&
+      (expired.includes(incoming.speakerId) ||
+        this._now() - incoming.at > limit)
+    ) {
+      this._hud.setIncoming(null);
+      this._incoming = null;
+      freed = true;
+    }
+
+    if (freed) {
+      this._machine?.onChannelFree();
+    }
+  }
+}