vimp-engine 0.38.3 → 0.39.0

package/src/client/voice/captureProcessor.worklet.js

@@ -0,0 +1,136 @@
+// AudioWorkletProcessor захвата микрофона. Самодостаточный файл без
+// импортов: грузится audioWorklet.addModule отдельно от бандла (same-origin,
+// CSP не ослабляется).
+//
+// Контекст движка работает на частоте устройства (44.1/48/96 кГц), кодек
+// ждёт 48 кГц — процессор сам приводит поток к outputRate и режет его на
+// кадры frameSamples. Ресемплинг — линейная интерполяция с дробной фазой,
+// непрерывной между квантами и кадрами; при входе выше outputRate перед
+// прореживанием стоит однополюсный ФНЧ против наложения спектра.
+//
+// `{ shutdown: true }` останавливает процессор навсегда: process() возвращает
+// false, и отключённый узел можно собрать (true держал бы его живым вечно).
+
+// срез ФНЧ — доля от outputRate
+const LOWPASS_RATIO = 0.45;
+
+class VoiceCaptureProcessor extends AudioWorkletProcessor {
+  constructor(options) {
+    super();
+
+    const { outputRate, frameSamples } = options.processorOptions;
+
+    this._frameSamples = frameSamples;
+    this._direct = sampleRate === outputRate;
+    // входных сэмплов на один выходной
+    this._step = sampleRate / outputRate;
+    // позиция следующего выходного сэмпла во входе: 0 — первый сэмпл
+    // текущего кванта, -1 — последний сэмпл прошлого
+    this._phase = 0;
+    this._prev = 0;
+    this._lowpass = sampleRate > outputRate;
+    this._alpha =
+      1 - Math.exp((-2 * Math.PI * LOWPASS_RATIO * outputRate) / sampleRate);
+    this._lpState = 0;
+    this._lpReady = false;
+    this._frame = new Float32Array(frameSamples);
+    this._fill = 0;
+    this._active = false;
+    this._alive = true;
+    this._generation = 0;
+    this._scratch = new Float32Array(128);
+
+    // кадры уходят только в эфире: без него главный поток не получает ни
+    // одного сообщения
+    this.port.onmessage = ({ data }) => {
+      if (data.shutdown === true) {
+        this._alive = false;
+        this._active = false;
+
+        return;
+      }
+
+      this._active = data.active === true;
+      this._generation = data.generation;
+      this._fill = 0;
+      this._phase = 0;
+      this._lpReady = false;
+    };
+  }
+
+  _emit(value) {
+    this._frame[this._fill++] = value;
+
+    if (this._fill === this._frameSamples) {
+      const frame = this._frame;
+
+      this._frame = new Float32Array(this._frameSamples);
+      this._fill = 0;
+      this.port.postMessage({ generation: this._generation, samples: frame }, [
+        frame.buffer,
+      ]);
+    }
+  }
+
+  process(inputs) {
+    if (!this._alive) {
+      return false;
+    }
+
+    const input = inputs[0]?.[0];
+
+    if (!this._active || !input) {
+      return true;
+    }
+
+    const count = input.length;
+
+    if (this._direct) {
+      for (let i = 0; i < count; i++) {
+        this._emit(input[i]);
+      }
+
+      return true;
+    }
+
+    let samples = input;
+
+    if (this._lowpass) {
+      if (this._scratch.length !== count) {
+        this._scratch = new Float32Array(count);
+      }
+
+      samples = this._scratch;
+
+      for (let i = 0; i < count; i++) {
+        if (!this._lpReady) {
+          this._lpState = input[i];
+          this._lpReady = true;
+        }
+
+        this._lpState += this._alpha * (input[i] - this._lpState);
+        samples[i] = this._lpState;
+      }
+    }
+
+    let phase = this._phase;
+
+    // выходной сэмпл между samples[i] и samples[i + 1]; пара через стык
+    // квантов (phase в [count - 1, count)) считается в следующем кванте
+    while (phase < count - 1) {
+      const index = Math.floor(phase);
+      const a = index < 0 ? this._prev : samples[index];
+      const b = samples[index + 1];
+
+      this._emit(a + (b - a) * (phase - index));
+      phase += this._step;
+    }
+
+    this._phase = phase - count;
+    this._prev = samples[count - 1];
+
+    return true;
+  }
+}
+
+registerProcessor('vimp-voice-capture', VoiceCaptureProcessor);

package/src/client/voice/opusConfig.js

@@ -0,0 +1,49 @@
+import {
+  VOICE_FRAME_MS,
+  VOICE_SAMPLE_RATE,
+} from '../../config/voiceProtocol.js';
+
+// Конфигурации кодека Opus — единый источник для поддержки, энкодера и
+// декодера. FEC выключен: декодер WebCodecs не восстанавливает кадр из
+// следующего пакета, а битрейт FEC съел бы. DTX выключен: детектор тишины
+// потока (VoicePlayback) опирается на непрерывный поток пакетов.
+
+/**
+ * Кандидаты конфигурации энкодера по убыванию предпочтения: с opus-блоком
+ * и без него (не каждый браузер знает OpusEncoderConfig).
+ * @param {number} bitrate - бит/с.
+ * @returns {Object[]}
+ */
+export function encoderConfigCandidates(bitrate) {
+  const base = {
+    codec: 'opus',
+    sampleRate: VOICE_SAMPLE_RATE,
+    numberOfChannels: 1,
+    bitrate,
+  };
+
+  return [
+    {
+      ...base,
+      opus: {
+        frameDuration: VOICE_FRAME_MS * 1000,
+        complexity: 5,
+        usedtx: false,
+        useinbandfec: false,
+      },
+    },
+    { ...base },
+  ];
+}
+
+/**
+ * Конфигурация декодера.
+ * @returns {Object}
+ */
+export function decoderConfig() {
+  return {
+    codec: 'opus',
+    sampleRate: VOICE_SAMPLE_RATE,
+    numberOfChannels: 1,
+  };
+}

package/src/client/voice/voiceOutput.js

@@ -0,0 +1,72 @@
+const isNode = (node, ctx) =>
+  Boolean(node) && typeof node.connect === 'function' && node.context === ctx;
+
+/**
+ * Выход звука голосовой связи поверх выхода движка: шина речи (через граф
+ * окраски игры) и шина сигналов → master gain Howler (общая громкость и mute
+ * движка действуют и на связь).
+ * @param {BaseAudioContext} ctx
+ * @param {AudioNode} destination - master gain Howler.
+ * @param {Object} [opts]
+ * @param {Function} [opts.voiceFilter] - ClientPlugin.hooks.voiceFilter.
+ * @param {Object} [opts.diagnostics] - { warn(code, details) }.
+ * @returns {{ speechInput: AudioNode, cueInput: AudioNode, dispose(): void }}
+ */
+export function createVoiceOutput(
+  ctx,
+  destination,
+  { voiceFilter, diagnostics } = {},
+) {
+  const speechInput = ctx.createGain();
+  const cueInput = ctx.createGain();
+  let graph = null;
+
+  cueInput.connect(destination);
+
+  if (typeof voiceFilter === 'function') {
+    try {
+      const answer = voiceFilter(ctx);
+
+      // null/undefined — игра окраску не хочет
+      if (answer !== null && answer !== undefined) {
+        if (isNode(answer.input, ctx) && isNode(answer.output, ctx)) {
+          graph = answer;
+        } else {
+          diagnostics?.warn('voice.filter', {
+            message:
+              'voiceFilter must return { input, output } nodes of the ctx',
+          });
+        }
+      }
+    } catch (error) {
+      diagnostics?.warn('voice.filter', { message: error?.message });
+    }
+  }
+
+  if (graph) {
+    speechInput.connect(graph.input);
+    graph.output.connect(destination);
+  } else {
+    speechInput.connect(destination);
+  }
+
+  return {
+    speechInput,
+    cueInput,
+    dispose() {
+      for (const node of [speechInput, cueInput, graph?.output]) {
+        try {
+          node?.disconnect();
+        } catch {
+          // уже отключён
+        }
+      }
+
+      try {
+        graph?.dispose?.();
+      } catch {
+        // сбой окраски при разборе не мешает остальному
+      }
+    },
+  };
+}

package/src/client/voice/voiceSupport.js

@@ -0,0 +1,71 @@
+import { decoderConfig, encoderConfigCandidates } from './opusConfig.js';
+
+// isConfigSupported бросает на неизвестных полях конфигурации — это «нет»
+async function isSupported(Codec, config) {
+  try {
+    const result = await Codec.isConfigSupported(config);
+
+    return result?.supported === true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Что умеет браузер. Захват требует защищённого контекста, getUserMedia,
+ * Web Audio движка (контекст Howler: на нём же сидит захват) с
+ * `audioWorklet` и AudioEncoder с поддержанной конфигурацией Opus;
+ * воспроизведение — Web Audio движка и AudioDecoder с поддержанной
+ * конфигурацией.
+ * @param {Object} env
+ * @param {Object} [env.globals] - globalThis.
+ * @param {number} env.bitrate - бит/с энкодера.
+ * @param {Function} env.getOutput - soundManager.getAudioOutput.
+ * @returns {Promise<{ capture: boolean, playback: boolean,
+ *   encoderConfig: Object|null, reason: string|null }>}
+ *   reason — первая причина отказа захвата: 'insecure' | 'noMediaDevices' |
+ *   'noWebAudio' | 'noWorklet' | 'noEncoder' | 'codec'.
+ */
+export async function detectVoiceSupport({
+  globals = globalThis,
+  bitrate,
+  getOutput,
+}) {
+  const output = getOutput();
+  const hasDecoder =
+    typeof globals.AudioDecoder?.isConfigSupported === 'function';
+  const playback =
+    Boolean(output) &&
+    hasDecoder &&
+    (await isSupported(globals.AudioDecoder, decoderConfig()));
+
+  let reason = null;
+  let encoderConfig = null;
+
+  if (!globals.isSecureContext) {
+    reason = 'insecure';
+  } else if (
+    typeof globals.navigator?.mediaDevices?.getUserMedia !== 'function'
+  ) {
+    reason = 'noMediaDevices';
+  } else if (!output) {
+    reason = 'noWebAudio';
+  } else if (!output.ctx.audioWorklet) {
+    reason = 'noWorklet';
+  } else if (typeof globals.AudioEncoder?.isConfigSupported !== 'function') {
+    reason = 'noEncoder';
+  } else {
+    for (const candidate of encoderConfigCandidates(bitrate)) {
+      if (await isSupported(globals.AudioEncoder, candidate)) {
+        encoderConfig = candidate;
+        break;
+      }
+    }
+
+    if (!encoderConfig) {
+      reason = 'codec';
+    }
+  }
+
+  return { capture: reason === null, playback, encoderConfig, reason };
+}

package/src/client/voice/voiceTones.js

@@ -0,0 +1,90 @@
+// Сигналы связи (D11) и нейтральные тоны движка. Чистые функции синтеза:
+// без файлов и случайности. Стиль игре даёт хук hooks.voiceSounds.
+
+// ключи набора hooks.voiceSounds; порядок — порядок таблицы в доках
+export const VOICE_CUES = Object.freeze([
+  'talkStart',
+  'talkEnd',
+  'busy',
+  'deny',
+  'incomingStart',
+  'incomingEnd',
+  'bed',
+]);
+
+// нейтральные сигналы движка: синусы с огибающей. У bed тона нет (тишина)
+export const TONE_SPECS = Object.freeze({
+  talkStart: [{ hz: 660, ms: 50 }, { gapMs: 15 }, { hz: 990, ms: 70 }],
+  talkEnd: [{ hz: 990, ms: 50 }, { gapMs: 15 }, { hz: 660, ms: 70 }],
+  busy: [{ hz: 330, ms: 120 }, { gapMs: 80 }, { hz: 330, ms: 120 }],
+  deny: [{ hz: 330, ms: 120 }],
+  incomingStart: [{ hz: 784, ms: 90 }],
+  incomingEnd: [{ hz: 523, ms: 70 }],
+});
+
+// пиковая амплитуда тона; края — косинусные фронты по TONE_EDGE_MS
+export const TONE_AMPLITUDE = 0.25;
+export const TONE_EDGE_MS = 5;
+
+/**
+ * Длительность тона сигнала в мс (сумма сегментов).
+ * @param {string} cue
+ * @returns {number} 0 — у сигнала нет тона.
+ */
+export function toneDurationMs(cue) {
+  const spec = Object.hasOwn(TONE_SPECS, cue) ? TONE_SPECS[cue] : null;
+
+  return spec
+    ? spec.reduce((sum, segment) => sum + (segment.ms ?? segment.gapMs), 0)
+    : 0;
+}
+
+/**
+ * Тон сигнала в частоте контекста. Каждый тональный сегмент — синус с
+ * фронтами TONE_EDGE_MS на обоих краях (щелчков нет), паузы — нули.
+ * @param {string} cue
+ * @param {number} sampleRate
+ * @returns {Float32Array|null} null — bed и неизвестное имя.
+ */
+export function synthesizeTone(cue, sampleRate) {
+  if (!Object.hasOwn(TONE_SPECS, cue)) {
+    return null;
+  }
+
+  const lengths = TONE_SPECS[cue].map(segment =>
+    Math.round(((segment.ms ?? segment.gapMs) * sampleRate) / 1000),
+  );
+  const out = new Float32Array(
+    lengths.reduce((sum, length) => sum + length, 0),
+  );
+  let offset = 0;
+
+  TONE_SPECS[cue].forEach((segment, index) => {
+    const length = lengths[index];
+
+    if (segment.hz) {
+      const edge = Math.min(
+        Math.floor((TONE_EDGE_MS * sampleRate) / 1000),
+        Math.floor(length / 2),
+      );
+
+      for (let i = 0; i < length; i++) {
+        const fromEnd = length - 1 - i;
+        const edgeDist = Math.min(i, fromEnd);
+        const envelope =
+          edgeDist >= edge
+            ? 1
+            : 0.5 * (1 - Math.cos((Math.PI * edgeDist) / edge));
+
+        out[offset + i] =
+          TONE_AMPLITUDE *
+          envelope *
+          Math.sin((2 * Math.PI * segment.hz * i) / sampleRate);
+      }
+    }
+
+    offset += length;
+  });
+
+  return out;
+}

package/src/config/clientServices.js

@@ -21,6 +21,8 @@ export const clientServices = createRegistry('clientServices', [
   { value: 'accolades', since: 4 },
   // журнал клиентских ошибок (lib/diagnostics.js): warn/capture партов
   { value: 'diagnostics', since: 4 },
+  // голосовая связь: кто сейчас в эфире (client/lib/voiceState.js)
+  { value: 'voice', since: 4 },
 ]);
 
 // плоский список имён — то, чем правило C4 проверяет componentDependencies

package/src/config/voiceDefaults.js

@@ -0,0 +1,44 @@
+// Дефолты и допустимые значения gameConfig.voice. Единственный источник для
+// lib/voiceConfig.js (рантайм), правила контракта B11 (статическая проверка)
+// и документации.
+export const VOICE_DEFAULTS = Object.freeze({
+  enabled: false,
+  scope: 'team',
+  hotkey: 86, // V
+  maxDurationMs: 5000,
+  cooldownMs: 1500,
+  bitrate: 16000,
+  texts: Object.freeze({
+    busy: 'Channel busy',
+    cooldown: 'Stand by',
+    unavailable: 'Voice unavailable',
+    micBlocked: 'Microphone blocked',
+    unsupported: 'Voice not supported',
+  }),
+});
+
+// 'team' — канал на команду, 'global' — один на комнату
+export const VOICE_SCOPES = Object.freeze(['team', 'global']);
+
+// закрытые диапазоны [min, max]; значение вне — зажимается с предупреждением
+export const VOICE_RANGES = Object.freeze({
+  maxDurationMs: [5000, 15000],
+  cooldownMs: [0, 10000],
+  bitrate: [6000, 32000],
+});
+
+// keyCode — целое 1..255
+export const VOICE_HOTKEY_RANGE = Object.freeze([1, 255]);
+
+// потолок длины подписи HUD
+export const VOICE_TEXT_MAX_LENGTH = 60;
+
+export const VOICE_KEYS = Object.freeze(Object.keys(VOICE_DEFAULTS));
+export const VOICE_TEXT_KEYS = Object.freeze(Object.keys(VOICE_DEFAULTS.texts));
+
+// все пути, которые игра может написать: раздел gameConfigFields снимка
+// поверхности (lib/gameConfigView.js → KNOWN_GAME_CONFIG_PATHS)
+export const VOICE_CONFIG_PATHS = Object.freeze([
+  ...VOICE_KEYS.filter(key => key !== 'texts').map(key => `voice.${key}`),
+  ...VOICE_TEXT_KEYS.map(key => `voice.texts.${key}`),
+]);

package/src/config/voiceProtocol.js

@@ -0,0 +1,80 @@
+// Протокол голосовой связи: коды сообщений и константы,
+// общие для хоста, ретранслятора и клиента.
+//
+// VOICE_DATA (server → client), кортежи — собирает и разбирает
+// lib/voiceMessages.js:
+//   GRANT [0, talkId, maxDurationMs]            запросившему
+//   DENY  [1, reason, retryAfterMs]             запросившему
+//   END   [2, talkId, reason]                   говорящему
+//   START [3, speakerId, talkId, name, teamId, chatColor]
+//                                               слушателям канала + говорящему
+//   STOP  [4, speakerId, talkId]                тем, кому ушёл START
+//
+// Голосовой пакет (lib/voicePacket.js):
+//   байт 0     порт (client → host 13 / host → client 22)
+//   байт 1     версия формата
+//   байт 2     id говорящего (клиент пишет 0, ретранслятор ставит авторитетный)
+//   байт 3     talkId (из GRANT)
+//   байты 4–5  seq, u16 big-endian, от 0 в каждом эфире
+//   байты 6…   Opus-пакет
+
+export const VOICE_MSG = Object.freeze({
+  GRANT: 0,
+  DENY: 1,
+  END: 2,
+  START: 3,
+  STOP: 4,
+});
+
+// операции VOICE_FLOOR (client → server): [1] запрос, [0, talkId] отпускание
+export const VOICE_FLOOR_OP = Object.freeze({ RELEASE: 0, REQUEST: 1 });
+
+export const VOICE_DENY = Object.freeze({
+  BUSY: 0,
+  COOLDOWN: 1,
+  FORBIDDEN: 2,
+  UNAVAILABLE: 3,
+});
+
+export const VOICE_END = Object.freeze({ RELEASED: 0, TIMEOUT: 1, REVOKED: 2 });
+
+// байт 1 пакета
+export const VOICE_PACKET_VERSION = 1;
+// длина заголовка пакета
+export const VOICE_HEADER_BYTES = 6;
+// потолок пакета (32 кбит/с × 20 мс = 80 Б, запас кратный)
+export const VOICE_MAX_PACKET_BYTES = 512;
+// id говорящего на проводе — u8
+export const VOICE_MAX_SPEAKER_ID = 255;
+// talkId на проводе — u8 без нуля: 1..VOICE_MAX_TALK_ID
+export const VOICE_MAX_TALK_ID = 255;
+// ник в START обрезается до этой длины (ник ≤ 15 + суффикс #N)
+export const VOICE_NAME_MAX_LENGTH = 32;
+// частота захвата и кодека
+export const VOICE_SAMPLE_RATE = 48000;
+// длительность кадра Opus
+export const VOICE_FRAME_MS = 20;
+// хост обрывает эфир на maxDurationMs + запас (клиент — ровно на maxDurationMs)
+export const VOICE_HOST_GRACE_MS = 300;
+// запросы эфира чаще этого интервала получают отказ cooldown
+export const VOICE_REQUEST_MIN_INTERVAL_MS = 150;
+// ведро токенов ретранслятора на говорящего
+export const VOICE_RELAY_RATE = Object.freeze({
+  packetsPerSecond: 60,
+  burst: 20,
+});
+// байтовое ведро ретранслятора на говорящего: около двух честных потоков на
+// потолке битрейта (32 кбит/с ≈ 4300 Б/с с заголовками); без него пакетное
+// ведро пропускало бы по 512 Б × 60 пакетов/с каждому слушателю
+export const VOICE_RELAY_BYTE_RATE = Object.freeze({
+  bytesPerSecond: 8192,
+  burst: 4096,
+});
+// порог bufferedAmount, выше которого пакет не шлётся
+export const VOICE_BACKPRESSURE_BYTES = 65536;
+// индикатор и звук гаснут сами через maxDurationMs + это время без STOP
+export const VOICE_LISTENER_SAFETY_MS = 2000;
+// «тёплый» микрофон: после последнего эфира закрывается через это время
+export const VOICE_MIC_IDLE_RELEASE_MS = 30000;
+// нет ответа на запрос эфира — запрос считается проваленным
+export const VOICE_REQUEST_TIMEOUT_MS = 2000;

package/src/config/voteKeys.js

@@ -0,0 +1,4 @@
+// keyCode цифр 0..9: клавиши ответа в окне голосования. Общий источник для
+// Vote (читает ответ) и правила контракта C12 (клавиша связи не должна их
+// занимать)
+export const VOTE_ANSWER_KEYS = Object.freeze([48, 57]);

package/src/config/wsports.js

@@ -34,6 +34,12 @@ export default {
     // { resumeKey, gameId } и ответ на RESUME_REQUEST
     SESSION_DATA: 19,
     RESUME_RESULT: 20,
+    // голосовая связь: управление эфиром —
+    // GRANT/DENY/END/START/STOP (lib/voiceMessages.js)
+    VOICE_DATA: 21,
+    // голосовая связь: первый байт бинарного голосового пакета хост → клиент
+    // (lib/voicePacket.js); JSON по нему не ходит
+    VOICE_AUDIO: 22,
   },
   // порты получения данных от клиента
   client: {
@@ -54,5 +60,11 @@ export default {
     // rank/state его токеном — без порта долгий матч писал бы истёкшим.
     // Прежний хост порт игнорирует
     TOKEN_REFRESH: 11,
+    // голосовая связь: [1] — запрос эфира, [0, talkId] — отпускание
+    VOICE_FLOOR: 12,
+    // голосовая связь: первый байт бинарного голосового пакета клиент → хост.
+    // Порт-машина его не разбирает никогда — пакет перехватывает транспорт и
+    // отдаёт ретранслятору (lib/VoiceRelay.js)
+    VOICE_AUDIO: 13,
   },
 };

package/src/devtools/contract/rules/b11-voice-config.js

@@ -0,0 +1,34 @@
+import { inspectVoiceConfig } from '../../../lib/voiceConfig.js';
+import { WARN, skip, verdict } from '../result.js';
+
+// Блок voice необязателен: без него связь выключена. Но объявленный блок с
+// опечаткой — тихий откат на дефолт (или зажим числа). Разбор берётся из
+// lib/voiceConfig.js — того же модуля, что читает рантайм, иначе правило и
+// движок разошлись бы. Хуки voiceSounds/voiceFilter статически не
+// проверяются: их ответ виден только в браузере, и его проверяет рантайм.
+export default {
+  id: 'B11',
+  name: 'voiceConfig',
+  level: WARN,
+  title: 'the voice block is well-formed',
+
+  check(ctx) {
+    if (!ctx.gameConfig) {
+      return skip('no gameConfig');
+    }
+
+    if (ctx.gameConfig.voice === undefined || ctx.gameConfig.voice === null) {
+      return skip('no voice block — voice is off');
+    }
+
+    const { problems } = inspectVoiceConfig(ctx.gameConfig.voice);
+
+    // забытый enabled: блок есть, связи нет, и ни одно правило не скажет.
+    // enabled: false — осознанное выключение, не нарушение
+    if (ctx.gameConfig.voice.enabled === undefined) {
+      problems.push('voice block is declared but voice.enabled is not set');
+    }
+
+    return verdict(problems);
+  },
+};