Интеграция Peito Denoise

Peito Denoise — реалтайм ИИ-шумодав для браузера, Electron и Capacitor-WebView. Эта страница проведёт от установки пакета до обработанного аудиотрека в вашем приложении.

Установка

Пакет ставится из npm. onnxruntime-web — peer-зависимость, нужна для нейробэкенда dfn3:

npm i peito-denoise onnxruntime-web

Пакет содержит JS-бандл, типы и AudioWorklet-процессор. Тяжёлые ассеты (модели, wasm) в пакет не входят — их хостите вы (см. ниже).

Ассеты

Скопируйте в свою папку статики (например, public/):

Проще всего скопировать весь каталог onnxruntime-web/dist/ в public/ort/.

// Vite: файл попадёт в assets с хешом, копировать в public/ не нужно
import workletUrl from 'peito-denoise/denoise-processor.js?url';
const node = new DenoiseNode({ backend: 'dfn3', workletUrl });

// Webpack 5 — аналогично:
const workletUrl = new URL('peito-denoise/denoise-processor.js', import.meta.url).href;

Заголовки COOP/COEP

Конвейер использует SharedArrayBuffer (lock-free ring между AudioWorklet и воркером), поэтому странице нужна cross-origin isolation. Сервер должен отдавать:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

Пример для Vite dev-сервера:

// vite.config.ts
export default defineConfig({
  server: {
    headers: {
      'Cross-Origin-Opener-Policy': 'same-origin',
      'Cross-Origin-Embedder-Policy': 'require-corp',
    },
  },
});

if (!crossOriginIsolated) {
  // нет COOP/COEP — SharedArrayBuffer недоступен, конвейер не поднимется
}
import { detectCapabilities } from 'peito-denoise';
console.log(detectCapabilities()); // sharedArrayBuffer, crossOriginIsolated, simd, threads…

Быстрый старт

Минимальная интеграция: микрофон → шумодав → динамики. init() вызывайте после жеста пользователя (клик), иначе браузер не даст запустить AudioContext.

import { DenoiseNode } from 'peito-denoise';

const node = new DenoiseNode({
  backend: 'dfn3',                        // нейромодель; 'spectral' — DSP без ассетов
  workletUrl: '/denoise-processor.js',    // скопированный worklet (это и есть дефолт)
});
await node.init();

// граф: любой источник → шумодав → куда угодно
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const src = node.audioContext.createMediaStreamSource(stream);
node.connectSource(src);
node.connect(node.audioContext.destination);

Бэкенды: dfn3 (DeepFilterNet3, нейросеть, лучшее качество речи), spectral (DSP-гейт, ~24 дБ на стационарном шуме, без ассетов), passthrough (обход, для A/B).

На слабых CPU включите многопоточный wasm-инференс — threads: 2–4 в опциях (см. справочник): время кадра dfn3 падает примерно вдвое.

MediaStreamTrack → чистый трек

Для WebRTC-звонков удобнее получить обработанный MediaStreamTrack и отдать его в PeerConnection:

const rawTrack = stream.getAudioTracks()[0];
const cleanTrack = node.createProcessedTrack(rawTrack);

// дальше как обычно:
pc.addTrack(cleanTrack, new MediaStream([cleanTrack]));

LiveKit

Адаптер под TrackProcessor. createLiveKitProcessor принимает тот же объект опций, что и DenoiseNode — обязательны activation (иначе dfn3 не получит модель) и context (running-контекст). Адаптер сам вызывает start() после инициализации.

import { createLiveKitProcessor } from 'peito-denoise';

// running-контекст создаём в рамках жеста пользователя (клик по «Позвонить»)
const ctx = new AudioContext({ sampleRate: 48000 });
await ctx.resume();

const proc = createLiveKitProcessor({
  backend: 'dfn3',
  suppressionLevel: 70,
  activation: {
    key: 'pk_…',                                  // ключ из личного кабинета
    activateUrl: 'https://peito.ru/api/activate', // или ваш прокси (см. про CORS ниже)
  },
  context: ctx,                                   // без него worklet отдаёт тишину/сырой звук
});

await localAudioTrack.setProcessor(proc);         // адаптер сам вызовет start()

// метрики и ошибки — через proc.denoiser
proc.denoiser?.on('metrics', (m) => updateUi(m));
proc.denoiser?.on('error', (e) => console.warn(e.code, e.where, e.error));

CORS и прокси. В 0.2.0 activateUrl по умолчанию абсолютный (https://peito.ru/api/activate) — сервер Peito отдаёт CORS-заголовки, так что с браузера он доступен напрямую. Если хотите проксировать активацию через свой бэкенд — переопределите activation.activateUrl и activation.refreshUrl. Расшифрованные модели активация отдаёт по /api/assets?…; они кэшируются после первой загрузки (см. Предзагрузка и кеш).

Управление в рантайме

Все параметры меняются на лету, без пересоздания графа:

node.setSuppression(80);            // сила подавления 0..100
node.setMix(0.5);                   // 0 = dry (сырой), 1 = wet (обработанный)
node.setBypass(true);               // мгновенный обход для A/B-сравнения
node.switchBackend('spectral');     // хот-свап бэкенда внутри воркера

node.setParam('highpassHz', 0);     // выключить входной high-pass (по умолчанию 80 Гц)

node.pause();                       // воркер простаивает — экономия CPU
await node.start();                 // возобновление (+ поднимает AudioContext)
node.destroy();                     // полная очистка ресурсов

AutoGain

Дотягивает тихую речь до целевого уровня: VAD-гейт (не усиливает шум в паузах), посэмпловое сглаживание и lookahead-лимитер — без щелчков и клиппинга.

node.setAutoGain({
  enabled: true,
  targetDb: -18,     // целевой уровень речи
  maxGainDb: 24,     // потолок буста
});

Входной high-pass (ветер, гул, DC)

Перед моделью стоит high-pass фильтр (Butterworth 2-го порядка, по умолчанию 80 Гц): он срезает то, что живёт ниже речи и плохо даётся нейросети — ветер в капсюль, хендлинг-шум, гул сети, DC-смещение. На 40 Гц затухание −12 дБ, на 20 Гц −24 дБ; от 300 Гц фильтр прозрачен, речь не задевается.

new DenoiseNode({ backend: 'dfn3', highpassHz: 100 }); // своя частота среза
node.setParam('highpassHz', 0);                        // выключить на лету

Предзагрузка и кеш

Ассеты кешируются в CacheStorage, поэтому загрузка происходит максимум один раз, а повторный запуск шумодава — почти мгновенный.

• Модели через активацию. Зашифрованные блоба моделей (~8.5 МБ) кешируются по стабильному ключу при первой активации. Повторная активация и перезагрузка страницы берут их из кеша — без повторной загрузки; заново только быстрая дешифровка в памяти. (Ключ расшифровки эфемерный, plaintext-модели не хранятся.)
• Модели через self-host (assets.modelUrl) и ORT wasm кешируются по URL тем же CacheStorage.

preloadDenoise() прогревает кеш заранее (wasm + ORT + self-host-модели), чтобы первый init() стартовал уже из кеша и работал офлайн:

import { preloadDenoise, clearDenoiseCache } from 'peito-denoise';

await preloadDenoise({
  onProgress: (p) => console.log(`${p.loaded} / ${p.total}`),
});

// сбросить оба кеша (ассеты + модели), напр. при обновлении моделей
await clearDenoiseCache();

Наблюдаемость

Шина событий даёт живые метрики и детекторы искажений — проблемы видно в телеметрии, а не «на слух»:

node.on('metrics', (e) => {
  // reductionDb, inferMs p50/p95, латентность, VAD, under/overruns…
  console.log('подавление:', e.data.reductionDb, 'дБ');
});
node.on('artifact', (e) => console.warn('искажение:', e.kind, e.frame));
node.on('error', (e) => console.error(e));
node.on('backendSwitch', (e) => console.log('fail-open/восстановление', e));

// последние N секунд raw/processed — готовые WAV-блобы для офлайн-репро
const { raw, processed } = await node.dumpWav(); // { raw: Blob, processed: Blob }

Детекторы: clip, click (разрыв), musical (музыкальный шум), oversuppress (модель ест речь), nan/inf, dead (тишина).

Дебаг-панель

Отдельный вход — не попадает в прод-бандл, если не импортирован:

import { createDebugPanel } from 'peito-denoise/panel';

const panel = createDebugPanel(node, document.getElementById('debug'));
// метрики с зонами, лампы детекторов, журнал, start/pause/bypass
panel.destroy(); // снять панель

Лицензирование

Основной путь для всех планов (Trial = Pro по фичам, отличается сроком и доменами) — онлайн-активация: клиент обменивает короткий публичный ключ (pk_… из личного кабинета) на session-токен, сервер проверяет домен, срок и отзыв и выдаёт зашифрованные модели по короткоживущим ссылкам. Без успешной активации нейробэкенд не получает веса — «пропустить проверку» на клиенте нельзя.

const node = new DenoiseNode({
  backend: 'dfn3',
  activation: { key: 'pk_…' },  // по умолчанию → https://peito.ru/api/activate
});
await node.init();              // активация отклонена → init() бросает
node.session;                   // текущий session-токен

Дальше библиотека сама продлевает session в фоне (refresh на ~60% TTL, по умолчанию TTL 15 минут). Если продлить не удалось — она реактивируется ключом (модели не перекачиваются). Если и это не прошло (ключ отозван, срок истёк, сервер недоступен) — шумодав отключается в fail-open: звук продолжает идти, но без обработки; попытки реактивации идут раз в минуту, при успехе обработка включается обратно. Оба перехода видны в событии backendSwitch.

Дополнительно ключ можно проверять и офлайн — по подписи ECDSA P-256 (WebCrypto): домены (включая wildcard), срок, набор фич. Работает без сети, но не видит отзыв ключа до истечения срока — используйте как дополнение к активации или для окружений без сети.

const node = new DenoiseNode({
  backend: 'dfn3',
  license: {
    key: MY_LICENSE_KEY,
    mode: 'enforce',   // блокирует init() без валидного ключа; 'warn' — только событие error
  },
});
await node.init();
await node.hasFeature('dfn3'); // проверка фичи из лицензии

Ошибки и коды

Все ошибки конвейера — кодовые: у каждой стабильный код E_*. Ошибки видны тремя способами, и по умолчанию их не нужно специально ловить, чтобы увидеть:

• Консоль по умолчанию. Библиотека сама логирует ошибки в консоль (console.error для фатальных, console.warn для остальных). Уровень задаётся debug.verbosity ('error' по умолчанию; 'silent' отключает вывод, 'info'/'debug' добавляют переключения бэкенда и селфтест).
• Фатальные — через исключение. На путях, где шумодав не может запуститься, init() отклоняется экземпляром PeitoError с полем .code. Раньше такие сбои могли пройти молча — теперь await init() бросает.
• Событие error. Для наблюдаемости все ошибки идут и событием с полями { code, where, error, fatal }.

import { DenoiseNode, PeitoError, PeitoErrorCode } from 'peito-denoise';

const node = new DenoiseNode({
  backend: 'dfn3',
  activation: { key: 'pk_…' },
  debug: { verbosity: 'error' },   // 'silent' | 'error' | 'info' | 'debug'
});

// рантайм-ошибки (fail-open, watchdog, refresh лицензии, artefact-детекторы)
node.on('error', (e) => {
  console.warn(e.code, e.where, e.error, e.fatal);
  if (e.code === PeitoErrorCode.LICENSE_REFRESH) notifyUser('лицензия истекла');
});

try {
  await node.init();               // фатальные пути бросают PeitoError
} catch (e) {
  if (e instanceof PeitoError && e.code === PeitoErrorCode.COOP_COEP) {
    // нет cross-origin isolation — проверьте заголовки COOP/COEP
  }
  throw e;
}

Полный список кодов:

Свой бэкенд (своя модель)

RNNoise, DTLN, GTCRN или произвольный ONNX подключаются плагином — конвейер трогать не нужно. Реализуйте интерфейс DenoiseBackend и зарегистрируйте:

import { registerBackend } from 'peito-denoise';
import type { DenoiseBackend } from 'peito-denoise';

class MyOnnxBackend implements DenoiseBackend {
  // init, processFrame(input, out), setParam, reset, destroy,
  // опционально lastDebug() — маска/VAD для спектрограммы и детекторов
}

registerBackend('onnx', () => new MyOnnxBackend()); // имя — из BackendName ('rnnoise', 'dtln', 'gtcrn', 'onnx')
const node = new DenoiseNode({ backend: 'onnx' });

Справочник опций DenoiseNode

Остались вопросы? Посмотрите живое демо — там весь конвейер с метриками и спектрограммами, или начните с Trial-лицензии.