dsh-live-voice 0.0.1-developing → 0.1.0

package/src/engines/recognition/browser.ts

@@ -0,0 +1,314 @@
+// @ts-nocheck
+const abortError = () =>
+  Object.assign(new Error('Speech recognition was cancelled.'), { name: 'AbortError' });
+const localReason =
+  'Local browser speech recognition is unavailable for this language. Install the local language pack, or explicitly turn off local-only processing in Settings if you permit the browser recognition service to process audio.';
+const notify = (callback, value) => {
+  try {
+    callback?.(value);
+  } catch {
+    /* Consumer errors must not retain microphone ownership. */
+  }
+};
+
+/** Web Speech recognition with explicit user-selected local-only or browser-service processing.
+ * When local-only plus auto-install is selected, the browser's native language-pack install API is used.
+ * All browser globals (including optional setTimeout/clearTimeout) are injectable.
+ * capability({lang}?) asynchronously returns {supported, local:true, reason?} without starting capture.
+ * start({lang,signal,onResult,onActivity,onError}?) resolves when native start() is accepted,
+ * not when permission is granted. Native asynchronous errors go to onError(Error).
+ * onResult({interim,final}) contains the current interim string and NEW final text only.
+ * onActivity(boolean) reports speech activity, not microphone permission/readiness.
+ * reset() replaces active native capture so its cumulative result list starts empty.
+ * stop() aborts capture, discards pending results, removes handlers and cancels restarts.
+ * Consecutive no-progress restarts are bounded; speech or nonempty results reset the budget.
+ * Native start acceptance alone is not progress. Restart delay backs off up to 30 seconds.
+ */
+export class BrowserRecognitionEngine {
+  constructor({
+    globals = globalThis,
+    lang = 'pt-BR',
+    processLocally = true,
+    autoInstallLocalPack = true,
+    onResult,
+    onActivity,
+    onError,
+    maxRestarts = 3,
+    restartDelayMs = 100,
+  } = {}) {
+    if (!Number.isInteger(maxRestarts) || maxRestarts < 0 || maxRestarts > 100)
+      throw new RangeError('maxRestarts must be an integer between 0 and 100.');
+    if (!Number.isFinite(restartDelayMs) || restartDelayMs < 0)
+      throw new RangeError('restartDelayMs must be nonnegative.');
+    Object.assign(this, {
+      globals,
+      lang,
+      processLocally,
+      autoInstallLocalPack,
+      onResult,
+      onActivity,
+      onError,
+      maxRestarts,
+      restartDelayMs,
+    });
+    this.session = null;
+  }
+
+  get active() {
+    return this.session !== null;
+  }
+  get Recognition() {
+    try {
+      const standard = this.globals?.SpeechRecognition;
+      return typeof standard === 'function' ? standard : this.globals?.webkitSpeechRecognition;
+    } catch {
+      return undefined;
+    }
+  }
+
+  async capability({ lang = this.lang, processLocally = this.processLocally } = {}) {
+    try {
+      const Recognition = this.Recognition;
+      if (typeof Recognition !== 'function') throw new Error();
+      const probe = new Recognition();
+      if (typeof probe.start !== 'function' || typeof probe.abort !== 'function') throw new Error();
+      if (!processLocally)
+        return {
+          supported: true,
+          local: false,
+          reason: 'Browser recognition service may process audio remotely.',
+        };
+      if (typeof Recognition.available !== 'function' || !('processLocally' in probe))
+        throw new Error();
+      probe.processLocally = true;
+      if (probe.processLocally !== true) throw new Error();
+      let availability = await Recognition.available({ langs: [lang], processLocally: true });
+      if (availability === 'downloadable' && this.autoInstallLocalPack) {
+        const installed = await Recognition.install?.({ langs: [lang], processLocally: true });
+        if (installed === true)
+          availability = await Recognition.available({ langs: [lang], processLocally: true });
+        else
+          return {
+            supported: false,
+            local: true,
+            availability,
+            reason: `The browser could not install the local ${lang} language pack. Disable local processing to use the browser recognition service, or try again later.`,
+          };
+      }
+      if (availability !== 'available')
+        return {
+          supported: false,
+          local: true,
+          availability,
+          reason: `Local recognition for ${lang}: ${availability}. ${availability === 'downloadable' ? 'The language pack is not installed; enable automatic installation or browser-service recognition.' : availability === 'downloading' ? 'The browser is still installing the language pack.' : 'The browser cannot currently provide on-device recognition for this language.'}`,
+        };
+      return { supported: true, local: true };
+    } catch {
+      return {
+        supported: false,
+        local: processLocally,
+        reason: processLocally
+          ? localReason
+          : 'Browser speech recognition is unavailable in this browser.',
+      };
+    }
+  }
+  async installLocalPack({ lang = this.lang } = {}) {
+    const Recognition = this.Recognition;
+    if (typeof Recognition?.install !== 'function')
+      throw new Error('This browser cannot install local speech-recognition language packs.');
+    const result = await Recognition.install({ langs: [lang], processLocally: true });
+    if (result !== true) throw new Error(`Local recognition for ${lang} could not be installed.`);
+    return this.capability({ lang, processLocally: true });
+  }
+
+  async start({
+    lang = this.lang,
+    signal,
+    onResult = this.onResult,
+    onActivity = this.onActivity,
+    onError = this.onError,
+  } = {}) {
+    this.stop();
+    if (signal?.aborted) throw abortError();
+    const session = {
+      lang,
+      signal,
+      onResult,
+      onActivity,
+      onError,
+      restarts: 0,
+      timer: null,
+      recognition: null,
+      speaking: false,
+    };
+    this.session = session;
+    const cancelled = new Promise((resolve, reject) => {
+      session.rejectCancelled = reject;
+    });
+    session.cancel = () => {
+      if (this.session === session) this.stop();
+    };
+    signal?.addEventListener('abort', session.cancel, { once: true });
+    const capability = await Promise.race([
+      this.capability({ lang, processLocally: this.processLocally }),
+      cancelled,
+    ]);
+    if (this.session !== session || signal?.aborted) {
+      session.cancel();
+      throw abortError();
+    }
+    if (!capability.supported) {
+      this.stop();
+      throw new Error(capability.reason);
+    }
+    try {
+      this._begin(session);
+      if (this.session !== session) throw abortError();
+    } catch (error) {
+      if (this.session === session) this.stop();
+      throw error;
+    }
+  }
+
+  _activity(session, active) {
+    if (session.speaking === active) return;
+    session.speaking = active;
+    notify(session.onActivity, active);
+  }
+
+  _detach(recognition) {
+    if (!recognition) return;
+    for (const name of ['onresult', 'onerror', 'onend', 'onspeechstart', 'onspeechend'])
+      recognition[name] = null;
+  }
+
+  _fail(session, error) {
+    if (this.session !== session) return;
+    this.stop();
+    notify(session.onError, error);
+  }
+
+  _begin(session) {
+    if (this.session !== session) return;
+    const recognition = new this.Recognition();
+    if (this.processLocally) {
+      if (!('processLocally' in recognition)) throw new Error(localReason);
+      recognition.processLocally = true;
+      if (recognition.processLocally !== true) throw new Error(localReason);
+    } else if ('processLocally' in recognition) recognition.processLocally = false;
+    recognition.lang = session.lang;
+    recognition.continuous = true;
+    recognition.interimResults = true;
+    session.recognition = recognition;
+    const finals = new Set();
+    const valid = () => this.session === session && session.recognition === recognition;
+    recognition.onspeechstart = () => {
+      if (!valid()) return;
+      session.restarts = 0;
+      this._activity(session, true);
+    };
+    recognition.onspeechend = () => {
+      if (valid()) this._activity(session, false);
+    };
+    recognition.onresult = (event) => {
+      if (!valid()) return;
+      const interim = [],
+        final = [];
+      for (let i = 0; i < event.results.length; i++) {
+        const result = event.results[i];
+        const text = result[0]?.transcript ?? '';
+        if (text.trim()) session.restarts = 0;
+        if (result.isFinal) {
+          if (!finals.has(i)) {
+            finals.add(i);
+            final.push(text);
+          }
+        } else interim.push(text);
+      }
+      notify(session.onResult, { interim: interim.join(' '), final: final.join(' ') });
+    };
+    recognition.onerror = (event) => {
+      if (!valid()) return;
+      const error = Object.assign(
+        new Error('Local browser recognition failed: ' + (event.error || 'unknown error')),
+        { code: event.error },
+      );
+      // no-speech is recoverable only when the browser subsequently ends this session.
+      if (event.error === 'no-speech') return;
+      else this._fail(session, error);
+    };
+    recognition.onend = () => {
+      if (!valid()) return;
+      this._detach(recognition);
+      session.recognition = null;
+      this._activity(session, false);
+      if (this.session !== session) return;
+      if (session.restarts >= this.maxRestarts) {
+        this._fail(
+          session,
+          Object.assign(
+            new Error(
+              'Local browser recognition stopped repeatedly. Restart listening manually or choose another local engine.',
+            ),
+            { code: 'restart-limit' },
+          ),
+        );
+        return;
+      }
+      session.restarts++;
+      session.timer = (this.globals.setTimeout ?? globalThis.setTimeout)(
+        () => {
+          session.timer = null;
+          if (this.session !== session) return;
+          try {
+            this._begin(session);
+          } catch (error) {
+            this._fail(session, error);
+          }
+        },
+        Math.min(30_000, this.restartDelayMs * 2 ** Math.min(session.restarts - 1, 20)),
+      );
+    };
+    recognition.start();
+  }
+
+  reset() {
+    const session = this.session;
+    const recognition = session?.recognition;
+    if (!session || !recognition) return false;
+    this._detach(recognition);
+    session.recognition = null;
+    try {
+      recognition.abort();
+    } catch {
+      /* Browser already ended capture. */
+    }
+    this._activity(session, false);
+    if (this.session !== session || session.signal?.aborted) return false;
+    try {
+      this._begin(session);
+      return true;
+    } catch (error) {
+      this._fail(session, error);
+      return false;
+    }
+  }
+
+  async stop() {
+    const session = this.session;
+    if (!session) return;
+    this.session = null;
+    session.rejectCancelled(abortError());
+    session.signal?.removeEventListener('abort', session.cancel);
+    if (session.timer !== null)
+      (this.globals.clearTimeout ?? globalThis.clearTimeout)(session.timer);
+    this._detach(session.recognition);
+    try {
+      session.recognition?.abort();
+    } catch {
+      /* Browser already ended capture. */
+    }
+    this._activity(session, false);
+  }
+}

package/src/engines/recognition/qwen-http.ts

@@ -0,0 +1,36 @@
+// @ts-nocheck
+import { WhisperHttpRecognitionEngine } from './whisper-http.ts';
+
+/** Qwen shares the plugin-owned microphone/VAD pipeline with Whisper, but uses
+ * its own authenticated DSH route and capability probe. */
+export class QwenHttpRecognitionEngine extends WhisperHttpRecognitionEngine {
+  constructor(options = {}) {
+    super(options);
+    this.route = '/api/dsh-live-voice/qwen';
+  }
+  async capability() {
+    const capture = await this.meter?.capability?.();
+    if (capture?.supported === false) return capture;
+    try {
+      const response = await this.g.fetch(this.route + '/capabilities?kind=asr', {
+          credentials: 'same-origin',
+        }),
+        json = await response.json();
+      return response.ok && json?.ok
+        ? json.value
+        : {
+            supported: false,
+            local: true,
+            location: 'host',
+            reason: json?.error?.message || 'Qwen capability check failed.',
+          };
+    } catch (error) {
+      return {
+        supported: false,
+        local: true,
+        location: 'host',
+        reason: 'Qwen speech server check failed: ' + (error?.message || error),
+      };
+    }
+  }
+}

package/src/engines/recognition/whisper-http-host.ts

@@ -0,0 +1,210 @@
+// @ts-nocheck
+import { readFile, mkdir, writeFile, rename, rm } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
+export function validateWhisperConfig(value) {
+  if (!value || typeof value.url !== 'string' || typeof value.healthUrl !== 'string')
+    throw new Error('Endpoint URL and health URL/path are required.');
+  const url = resolveWhisperUrl(value.url.trim());
+  const health = value.healthUrl.trim();
+  if (!health) throw new Error('Health URL/path is required.');
+  resolveWhisperUrl(new URL(health, url).href);
+  if (!Number.isInteger(value.timeoutMs) || value.timeoutMs < 100 || value.timeoutMs > 300000)
+    throw new Error('Request timeout must be an integer between 100 and 300000 ms.');
+  return { url: url.href, healthUrl: health, timeoutMs: value.timeoutMs };
+}
+export function createWhisperConfigStore(
+  path = join(homedir(), '.dsh', 'dsh-live-voice-whisper.json'),
+) {
+  return {
+    async load() {
+      try {
+        return JSON.parse(await readFile(path, 'utf8'));
+      } catch (error) {
+        if (error.code === 'ENOENT') return null;
+        throw new Error('Cannot read persisted Whisper settings: ' + error.message);
+      }
+    },
+    async save(config) {
+      await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+      const temporary = path + '.' + randomUUID() + '.tmp';
+      try {
+        await writeFile(temporary, JSON.stringify(config, null, 2) + '\n', {
+          mode: 0o600,
+          flag: 'wx',
+        });
+        await rename(temporary, path);
+      } finally {
+        await rm(temporary, { force: true });
+      }
+    },
+  };
+}
+const clean = (value) => String(value ?? '').trim();
+export function resolveWhisperUrl(
+  value = process.env.DSH_LIVE_VOICE_WHISPER_URL || 'http://127.0.0.1:8080/inference',
+) {
+  const url = new URL(value);
+  if (
+    url.protocol !== 'http:' ||
+    !LOOPBACK.has(url.hostname) ||
+    url.username ||
+    url.password ||
+    url.hash
+  )
+    throw new Error('Whisper HTTP URL must be an unauthenticated loopback http URL.');
+  return url;
+}
+export function validateMonoPcm16Wav(input, { maxBytes = 2_000_000 } = {}) {
+  const bytes = input instanceof Uint8Array ? input : new Uint8Array(input);
+  if (bytes.byteLength < 44 || bytes.byteLength > maxBytes)
+    throw new Error('Invalid or oversized WAV recording.');
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength),
+    ascii = (at, n) => String.fromCharCode(...bytes.subarray(at, at + n));
+  if (
+    ascii(0, 4) !== 'RIFF' ||
+    ascii(8, 4) !== 'WAVE' ||
+    view.getUint32(4, true) + 8 !== bytes.byteLength
+  )
+    throw new Error('Invalid WAV container.');
+  let at = 12,
+    fmt = null,
+    data = null;
+  while (at + 8 <= bytes.byteLength) {
+    const id = ascii(at, 4),
+      size = view.getUint32(at + 4, true),
+      start = at + 8,
+      end = start + size;
+    if (end > bytes.byteLength) throw new Error('Invalid WAV chunk.');
+    if (id === 'fmt ') fmt = { start, size };
+    if (id === 'data') {
+      if (data) throw new Error('Multiple WAV data chunks are unsupported.');
+      data = { start, size };
+    }
+    at = end + (size & 1);
+  }
+  if (!fmt || fmt.size < 16 || !data || at !== bytes.byteLength)
+    throw new Error('Incomplete WAV recording.');
+  const f = fmt.start;
+  if (
+    view.getUint16(f, true) !== 1 ||
+    view.getUint16(f + 2, true) !== 1 ||
+    view.getUint32(f + 4, true) !== 16000 ||
+    view.getUint32(f + 8, true) !== 32000 ||
+    view.getUint16(f + 12, true) !== 2 ||
+    view.getUint16(f + 14, true) !== 16 ||
+    data.size < 2 ||
+    data.size % 2
+  )
+    throw new Error('WAV must be mono 16 kHz PCM16.');
+  return bytes;
+}
+export class WhisperHttpHost {
+  constructor({
+    url,
+    healthUrl = '/health',
+    timeoutMs = 30000,
+    fetchImpl = globalThis.fetch,
+    maxBytes = 2_000_000,
+    store,
+  } = {}) {
+    this.config = validateWhisperConfig({ url: resolveWhisperUrl(url).href, healthUrl, timeoutMs });
+    this.fetch = fetchImpl;
+    this.maxBytes = maxBytes;
+    this.store = store;
+    this.active = new AbortController();
+    this.queue = Promise.resolve();
+    this.ready = Promise.resolve()
+      .then(async () => {
+        const saved = await store?.load();
+        if (saved) this.config = validateWhisperConfig(saved);
+      })
+      .catch((error) => {
+        this.loadError = error;
+      });
+  }
+  get url() {
+    return new URL(this.config.url);
+  }
+  async getConfig() {
+    await this.ready;
+    if (this.loadError) throw this.loadError;
+    return { ...this.config };
+  }
+  replaceConfig(value) {
+    const next = validateWhisperConfig(value);
+    const operation = this.queue.then(async () => {
+      await this.ready;
+      await this.store?.save(next);
+      this.active.abort();
+      this.active = new AbortController();
+      this.config = next;
+      this.loadError = null;
+      return { ...next };
+    });
+    this.queue = operation.catch(() => {});
+    return operation;
+  }
+  dispose() {
+    this.active.abort();
+  }
+  async request(url, options, config, consume = (response) => response) {
+    const timeout = AbortSignal.timeout(config.timeoutMs);
+    const signal = AbortSignal.any([
+      timeout,
+      this.active.signal,
+      ...(options.signal ? [options.signal] : []),
+    ]);
+    const response = await this.fetch(url, { ...options, signal, redirect: 'error' });
+    const value = await consume(response);
+    signal.throwIfAborted();
+    return value;
+  }
+  async capability(signal, configuration) {
+    try {
+      const config = configuration ? validateWhisperConfig(configuration) : await this.getConfig();
+      const response = await this.request(
+        new URL(config.healthUrl, config.url),
+        { signal },
+        config,
+      );
+      return response.ok
+        ? { supported: true, local: true, streaming: false, maxBytes: this.maxBytes }
+        : {
+            supported: false,
+            local: true,
+            streaming: false,
+            reason: 'Whisper HTTP health check failed (' + response.status + ').',
+          };
+    } catch (error) {
+      return {
+        supported: false,
+        local: true,
+        streaming: false,
+        reason: 'Whisper HTTP server is unreachable: ' + (error?.message || error),
+      };
+    }
+  }
+  async transcribe(input, { lang = 'auto', signal } = {}) {
+    const bytes = validateMonoPcm16Wav(input, { maxBytes: this.maxBytes }),
+      form = new FormData();
+    form.append('file', new Blob([bytes], { type: 'audio/wav' }), 'utterance.wav');
+    form.append('response_format', 'json');
+    form.append('language', lang.startsWith('pt') ? 'pt' : lang.startsWith('en') ? 'en' : 'auto');
+    const config = await this.getConfig();
+    return this.request(
+      new URL(config.url),
+      { method: 'POST', body: form, signal },
+      config,
+      async (response) => {
+        if (!response.ok)
+          throw new Error('Whisper HTTP transcription failed (' + response.status + ').');
+        const json = await response.json();
+        return { text: clean(json?.text) };
+      },
+    );
+  }
+}