@mosaicoo/svg-engine 0.1.0

package/types/mosaicoo-svg-engine-ai-nlu-voice-wasm.d.ts

@@ -0,0 +1,175 @@
+import * as i0 from '@angular/core';
+import { InjectionToken, Provider, Signal } from '@angular/core';
+
+/**
+ * **D-046 voz local (Whisper WASM)** — configuração do provider de
+ * reconhecimento de voz **100% offline** baseado em
+ * `@huggingface/transformers` (transformers.js) + onnxruntime-web.
+ *
+ * Todos os caminhos apontam para assets **servidos pela própria
+ * origem** do app (sem CDN / sem `huggingface.co` em runtime). O modelo
+ * vem do submódulo `assets/ml/whisper` (repo `svgengine-ml-assets`); os
+ * binários `.wasm` do onnxruntime são copiados do pacote npm para os
+ * assets do app (ver `angular.json`).
+ */
+interface WhisperVoiceConfig {
+    /**
+     * Base servida onde o transformers.js procura o modelo
+     * (`env.localModelPath`). O modelo é resolvido em
+     * `${modelBasePath}/${modelId}/...`. Default: `/assets/ml/whisper`.
+     */
+    readonly modelBasePath: string;
+    /**
+     * Id/pasta do modelo dentro de `modelBasePath`. Default:
+     * `whisper-base`.
+     */
+    readonly modelId: string;
+    /**
+     * Base servida com os binários `.wasm` do onnxruntime-web
+     * (`env.backends.onnx.wasm.wasmPaths`). Default: `/assets/ml/ort/`.
+     */
+    readonly wasmBasePath: string;
+    /**
+     * dtype do modelo ONNX. `'q8'` mapeia para os arquivos
+     * `*_quantized.onnx` (que vendoramos: encoder/decoder int8). Mantenha
+     * `'q8'` salvo se vendorar outra variante.
+     */
+    readonly dtype: 'q8' | 'fp32' | 'fp16' | 'int8' | 'uint8' | 'q4' | 'q4f16';
+    /**
+     * Nº de threads WASM. **1** (default) evita exigir cross-origin
+     * isolation (COOP/COEP) — funciona em qualquer hospedagem. Aumente
+     * apenas se o app já servir os headers de isolamento.
+     */
+    readonly numThreads: number;
+    /**
+     * Nível de otimização de grafo do onnxruntime (`session_options`).
+     * **`'disabled'`** (default) evita a passada
+     * `TransposeDQWeightsForMatMulNBits` do ORT 1.26, que falha ao carregar
+     * o decoder int8 do Whisper base (`Missing required scale` no
+     * `embed_tokens` merged/transposto). O modelo carrega e roda normal
+     * sem essa fusão — só perde uma otimização de performance irrelevante
+     * para comandos curtos. Suba para `'basic'`/`'all'` apenas se vendorar
+     * um modelo cuja quantização o ORT consiga fundir.
+     */
+    readonly graphOptimizationLevel: 'disabled' | 'basic' | 'extended' | 'all';
+    /**
+     * Idioma BCP-47 padrão quando o chamador não informa. Default
+     * `'pt'`. O Whisper base é multilíngue (PT-BR / ES / EN / …).
+     */
+    readonly defaultLanguage: string;
+    /**
+     * Duração máxima de captura por sessão (ms) antes de parar
+     * automaticamente e transcrever. Funciona como teto de segurança
+     * caso o VAD nunca dispare (ruído constante). Default 15000.
+     */
+    readonly maxRecordMs: number;
+    /**
+     * **VAD (detecção de silêncio)** — após a fala começar, encerra a
+     * captura automaticamente quando o silêncio durar este tempo (ms).
+     * Espelha o auto-stop da Web Speech para manter o comportamento
+     * consistente entre as engines. Default 1000 (1 s).
+     * `0` desliga o VAD (só para via `stop()` ou `maxRecordMs`).
+     */
+    readonly silenceMs: number;
+    /**
+     * Limiar de energia (RMS, 0–1 no domínio do tempo) acima do qual o
+     * áudio é considerado fala pelo VAD. Default 0.015. Aumente se o
+     * ruído de fundo disparar falso-positivo; diminua se a fala não
+     * estiver sendo detectada (mic baixo/distante).
+     */
+    readonly silenceThreshold: number;
+    /**
+     * **Timeout de "nenhuma fala"** — se o VAD **não** detectar fala
+     * dentro deste tempo (ms) após iniciar, encerra a captura mesmo
+     * assim. Evita o microfone ficar "preso" ligado quando o áudio fica
+     * abaixo do limiar. Default 6000. `0` desliga (só `maxRecordMs`).
+     */
+    readonly noSpeechTimeoutMs: number;
+}
+/** Defaults aplicáveis ao layout padrão de assets dos apps SVGEngine. */
+declare const DEFAULT_WHISPER_VOICE_CONFIG: WhisperVoiceConfig;
+/** Token DI para a configuração do provider Whisper. */
+declare const WHISPER_VOICE_CONFIG: InjectionToken<WhisperVoiceConfig>;
+/**
+ * Helper de bootstrap — registra a configuração do provider Whisper.
+ * Passe um patch parcial; os campos ausentes usam
+ * {@link DEFAULT_WHISPER_VOICE_CONFIG}.
+ *
+ * ```ts
+ * providers: [provideWhisperVoice({ modelBasePath: '/custom/assets/whisper' })]
+ * ```
+ */
+declare function provideWhisperVoice(config?: Partial<WhisperVoiceConfig>): Provider;
+
+declare class WhisperVoiceService {
+    private readonly config;
+    /** `false` quando o ambiente não tem mic/WebAssembly (UI esconde o botão). */
+    readonly isSupported: Signal<boolean>;
+    private readonly _listening;
+    /** `true` enquanto está gravando OU transcrevendo. */
+    readonly listening: Signal<boolean>;
+    private readonly _modelLoading;
+    /** `true` durante o (primeiro) carregamento do modelo do disco. */
+    readonly modelLoading: Signal<boolean>;
+    private readonly _lastError;
+    /** Último erro (`'not-allowed'`, `'audio-capture'`, `'load-failed'`, …). */
+    readonly lastError: Signal<string | null>;
+    /** Pipeline ASR carregado uma vez e reutilizado entre capturas. */
+    private transcriber;
+    /** Recorder/stream da captura ativa (para `stop()`). */
+    private activeRecorder;
+    private activeStream;
+    /**
+     * Inicia a captura e resolve com a transcrição final. Grava até
+     * `stop()` ser chamado OU `maxRecordMs` expirar, então transcreve.
+     *
+     * @param lang BCP-47 (default `config.defaultLanguage`)
+     * @param options.timeoutMs duração máxima de captura (default
+     *   `config.maxRecordMs`)
+     */
+    listen(lang?: string, options?: {
+        readonly timeoutMs?: number;
+    }): Promise<string>;
+    /** Encerra a captura ativa (dispara a transcrição do que foi gravado). */
+    stop(): void;
+    /** Decodifica + downmix mono + reamostra para 16 kHz e roda o ASR. */
+    private transcribe;
+    /**
+     * Carrega (uma vez) o pipeline ASR a partir dos assets locais. Lazy
+     * `import()` do transformers.js — só puxa a lib quando a voz Whisper é
+     * realmente usada. Configura o env para **não** acessar a rede externa.
+     */
+    private ensurePipeline;
+    static ɵfac: i0.ɵɵFactoryDeclaration<WhisperVoiceService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<WhisperVoiceService>;
+}
+
+/**
+ * **Bootstrap da voz local (Whisper) como engine selecionável.**
+ *
+ * Registra o {@link WhisperVoiceService} no token opcional
+ * `VOICE_WHISPER_PROVIDER` (de `svg-engine/ai/nlu`), tornando-o
+ * disponível para o `VoiceEngineService` (orquestrador em `nlu-ui`).
+ * A partir daí o usuário pode escolher a engine `'whisper'` ou
+ * `'auto'` no `<svge-nlu-input>`.
+ *
+ * Aceita um patch opcional de {@link WhisperVoiceConfig} (caminhos de
+ * assets, dtype, idioma padrão). Sem o patch, usa os defaults
+ * (`/assets/ml/whisper`, `/assets/ml/ort/`, `whisper-base`, `q8`).
+ *
+ * ```ts
+ * // app.config.ts
+ * providers: [
+ *   ...provideWhisperVoiceEngine(),
+ *   // ou com caminhos custom:
+ *   ...provideWhisperVoiceEngine({ modelBasePath: '/cdn/whisper' }),
+ * ]
+ * ```
+ *
+ * **Pré-requisito**: os assets do modelo + `.wasm` do onnxruntime
+ * precisam estar servidos pela origem do app (ver `angular.json`).
+ */
+declare function provideWhisperVoiceEngine(config?: Partial<WhisperVoiceConfig>): Provider[];
+
+export { DEFAULT_WHISPER_VOICE_CONFIG, WHISPER_VOICE_CONFIG, WhisperVoiceService, provideWhisperVoice, provideWhisperVoiceEngine };
+export type { WhisperVoiceConfig };