@lokutor/sdk 1.1.43 → 1.2.2

package/dist/index.d.mts

@@ -68,12 +68,14 @@ declare const AUDIO_CONFIG: {
 declare const DEFAULT_URLS: {
     VOICE_AGENT: string;
     TTS: string;
+    STT: string;
 };
 /**
  * SDK Configuration interface
  */
 interface LokutorConfig {
     apiKey: string;
+    agentId?: string;
     onTranscription?: (text: string) => void;
     onResponse?: (text: string) => void;
     onAudio?: (data: Uint8Array) => void;
@@ -91,6 +93,59 @@ interface SynthesizeOptions {
     steps?: number;
     visemes?: boolean;
 }
+/**
+ * Options for one-shot batch transcription via STTClient.transcribe()
+ * (POST /stt/transcribe) — pass a complete recording and get a transcript
+ * back. For continuous/live transcription, use SpeechToTextClient instead.
+ */
+interface TranscribeOptions {
+    /** Complete audio to transcribe. A Blob/File (e.g. from a file input or
+     *  MediaRecorder) is sent as multipart/form-data; a raw PCM16 buffer is
+     *  sent as base64 JSON with `format: "pcm16"`. */
+    audio: Blob | ArrayBuffer | Uint8Array;
+    /** Required when `audio` is raw PCM16 (ignored for WAV/Blob input, whose
+     *  rate is read from the file header). */
+    sampleRate?: number;
+    /** Set when passing a raw PCM16 buffer instead of a WAV Blob. */
+    format?: 'wav' | 'pcm16';
+    language?: Language;
+}
+/** One transcribed segment with timing, when the engine provides them. */
+interface TranscribeSegment {
+    text: string;
+    start: number;
+    end: number;
+    duration: number;
+}
+/** Result of STTClient.transcribe() — mirrors POST /stt/transcribe's response body. */
+interface TranscribeResult {
+    text: string;
+    latencyMs: number;
+    engine: string;
+    sampleRate: number;
+    language: string;
+    durationSeconds: number;
+    segments?: TranscribeSegment[];
+}
+/**
+ * Continuous speech-to-text options (WS /ws/stt) — standalone transcription
+ * with server-side VAD, independent of the full voice-agent pipeline (no
+ * LLM turn, no TTS). Use this for live captioning/dictation; use
+ * STTClient.transcribe() for a single pre-recorded clip.
+ */
+interface SpeechToTextOptions {
+    apiKey: string;
+    serverUrl?: string;
+    language?: Language;
+    /** VAD engine: "silero" (default, neural) or "rms" (energy-threshold fallback). */
+    vad?: 'silero' | 'rms';
+    /** Fires repeatedly while the user is mid-utterance, with the best partial guess so far. */
+    onPartialTranscript?: (text: string) => void;
+    /** Fires once VAD detects the utterance ended. */
+    onFinalTranscript?: (text: string) => void;
+    onError?: (error: LokutorError) => void;
+    onStatusChange?: (status: 'connecting' | 'connected' | 'disconnected') => void;
+}
 /**
  * Browser audio configuration options
  */
@@ -245,6 +300,7 @@ interface AudioManager {
 declare class VoiceAgentClient {
     private ws;
     private apiKey;
+    private agentId;
     prompt: string;
     voice: VoiceStyle;
     language: Language;
@@ -433,6 +489,55 @@ declare class TTSClient {
         onError?: (error: any) => void;
     }): Promise<void>;
 }
+/**
+ * Standalone speech-to-text — batch transcription of a single, complete
+ * audio clip (POST /stt/transcribe). No LLM, no TTS, no voice-agent session.
+ * For continuous/live transcription (e.g. dictation, live captions), use
+ * SpeechToTextClient instead.
+ */
+declare class STTClient {
+    private apiKey;
+    private baseUrl;
+    constructor(config: {
+        apiKey: string;
+        serverUrl?: string;
+    });
+    /**
+     * Transcribe a complete audio clip. Pass a Blob/File (e.g. from a file
+     * input or MediaRecorder) for WAV/compressed audio, or a raw PCM16
+     * buffer with `format: "pcm16"` and `sampleRate` set.
+     */
+    transcribe(options: TranscribeOptions): Promise<TranscribeResult>;
+}
+/**
+ * Continuous speech-to-text (WS /ws/stt) — streams microphone audio to the
+ * server and receives partial transcripts while the user is speaking and a
+ * final transcript when the server's VAD detects the utterance ended.
+ * Standalone: no LLM turn, no TTS, no voice-agent session — just
+ * transcription. For a single pre-recorded clip, use STTClient instead.
+ */
+declare class SpeechToTextClient {
+    private apiKey;
+    private serverUrl;
+    private language?;
+    private vad;
+    private onPartialTranscript?;
+    private onFinalTranscript?;
+    private onError?;
+    private onStatusChange?;
+    private ws;
+    private audioManager;
+    private isConnected;
+    constructor(config: SpeechToTextOptions);
+    /**
+     * Connect and start streaming microphone audio.
+     * @param customAudioManager Optional replacement for the default audio hardware handler (e.g. NodeAudioManager for CLI use)
+     */
+    connect(customAudioManager?: AudioManager): Promise<boolean>;
+    /** Force-finalize whatever utterance is currently in progress. */
+    endUtterance(): void;
+    disconnect(): void;
+}
 /**
  * Quick function to start a conversation (requires manual audio piping in JS)
  */
@@ -446,6 +551,13 @@ declare function simpleTTS(options: SynthesizeOptions & {
     apiKey: string;
     onAudio: (buf: Uint8Array) => void;
 }): Promise<void>;
+/**
+ * Quick function for standalone, one-shot transcription of a complete audio clip.
+ */
+declare function simpleTranscribe(options: TranscribeOptions & {
+    apiKey: string;
+    serverUrl?: string;
+}): Promise<TranscribeResult>;
 
 /**
  * Audio utility functions for format conversion, resampling, and PCM processing
@@ -558,6 +670,7 @@ declare class BrowserAudioManager {
     private mediaStreamAudioSourceNode;
     private scriptProcessor;
     private analyserNode;
+    private amplitudeBuffer;
     private mediaStream;
     private resampler;
     private nextPlaybackTime;
@@ -637,14 +750,42 @@ declare class BrowserAudioManager {
     isRecording(): boolean;
 }
 
+/**
+ * Node.js-specific AudioManager implementation.
+ * Note: These require 'speaker' and 'node-record-lpcm16' to be installed by the user.
+ */
+declare class NodeAudioManager implements AudioManager {
+    private speaker;
+    private recorder;
+    private recordingStream;
+    private isMuted;
+    private isListening;
+    constructor();
+    init(): Promise<void>;
+    startMicrophone(onAudioInput: (pcm16Data: Uint8Array) => void): Promise<void>;
+    stopMicrophone(): void;
+    playAudio(pcm16Data: Uint8Array): Promise<void>;
+    stopPlayback(): void;
+    cleanup(): void;
+    isMicMuted(): boolean;
+    setMuted(muted: boolean): void;
+    getAmplitude(): number;
+}
+
 interface ConversationalPanelConfig {
+    /** Container element to mount the panel */
     container: HTMLElement;
-    title: string;
-    description: string;
-    prompt: string;
+    /** Agent name or title shown in the curtain */
+    title?: string;
+    /** Short description below the title */
+    description?: string;
+    /** System prompt for the voice agent */
+    prompt?: string;
+    /** Voice style identifier (default: M1) */
     voice?: string;
+    /** Language code (default: en) */
     language?: string;
-    /** Accent color for the sphere glow and highlights, e.g. '#e74c3c' */
+    /** Accent color for the sphere glow and highlights, e.g. '#e74c3b' */
     accentColor?: string;
     /** Background color, e.g. '#0a0a0a' */
     backgroundColor?: string;
@@ -676,14 +817,16 @@ declare class ConversationalPanel {
     private isRunning;
     private _locked;
     private _lastSpeechTime;
+    private selectedVoice;
     private el;
     private curtain;
     private curtainTitle;
     private curtainDesc;
+    private curtainBg;
+    private curtainOverlay;
     private startBtn;
     private errorEl;
     private errorText;
-    private timerEl;
     private canvas;
     private muteBtn;
     private muteSvg;
@@ -708,6 +851,7 @@ declare class ConversationalPanel {
     setBackgroundColor(color: string): void;
     /** Update title text */
     setTitle(title: string): void;
+    /** Select a voice from the picker */
     /** Update description text */
     setDescription(desc: string): void;
     /** Update prompt (only takes effect on next start()) */
@@ -718,7 +862,6 @@ declare class ConversationalPanel {
     showError(text: string): void;
     /** Destroy the component, removing all DOM and stopping any active session */
     destroy(): void;
-    private fmt;
     private startTimer;
     private toggleMute;
     private playConnectingSound;
@@ -726,4 +869,4 @@ declare class ConversationalPanel {
     private playErrorTone;
 }
 
-export { AUDIO_CONFIG, type AnalyserConfig, type AudioManager, type BrowserAudioConfig, BrowserAudioManager, type BrowserAudioOptions, ConversationalPanel, type ConversationalPanelConfig, DEFAULT_URLS, type ErrorCode, type HealthStatus, Language, type LanguageInfo, type LokutorConfig, LokutorError, type ModelInfo, type ServerConfig, type ServerStatus, StreamResampler, type SynthesizeOptions, TTSClient, type ToolCall, type ToolDefinition, type Viseme, VoiceAgentClient, type VoiceAgentOptions, type VoiceInfo, VoiceStyle, applyLowPassFilter, bytesToPcm16, calculateRMS, float32ToPcm16, isRetryable, normalizeAudio, pcm16ToBytes, pcm16ToFloat32, resample, resampleWithAntiAliasing, simpleConversation, simpleTTS };
+export { AUDIO_CONFIG, type AnalyserConfig, type AudioManager, type BrowserAudioConfig, BrowserAudioManager, type BrowserAudioOptions, ConversationalPanel, type ConversationalPanelConfig, DEFAULT_URLS, type ErrorCode, type HealthStatus, Language, type LanguageInfo, type LokutorConfig, LokutorError, type ModelInfo, NodeAudioManager, STTClient, type ServerConfig, type ServerStatus, SpeechToTextClient, type SpeechToTextOptions, StreamResampler, type SynthesizeOptions, TTSClient, type ToolCall, type ToolDefinition, type TranscribeOptions, type TranscribeResult, type TranscribeSegment, type Viseme, VoiceAgentClient, type VoiceAgentOptions, type VoiceInfo, VoiceStyle, applyLowPassFilter, bytesToPcm16, calculateRMS, float32ToPcm16, isRetryable, normalizeAudio, pcm16ToBytes, pcm16ToFloat32, resample, resampleWithAntiAliasing, simpleConversation, simpleTTS, simpleTranscribe };

package/dist/index.d.ts

@@ -68,12 +68,14 @@ declare const AUDIO_CONFIG: {
 declare const DEFAULT_URLS: {
     VOICE_AGENT: string;
     TTS: string;
+    STT: string;
 };
 /**
  * SDK Configuration interface
  */
 interface LokutorConfig {
     apiKey: string;
+    agentId?: string;
     onTranscription?: (text: string) => void;
     onResponse?: (text: string) => void;
     onAudio?: (data: Uint8Array) => void;
@@ -91,6 +93,59 @@ interface SynthesizeOptions {
     steps?: number;
     visemes?: boolean;
 }
+/**
+ * Options for one-shot batch transcription via STTClient.transcribe()
+ * (POST /stt/transcribe) — pass a complete recording and get a transcript
+ * back. For continuous/live transcription, use SpeechToTextClient instead.
+ */
+interface TranscribeOptions {
+    /** Complete audio to transcribe. A Blob/File (e.g. from a file input or
+     *  MediaRecorder) is sent as multipart/form-data; a raw PCM16 buffer is
+     *  sent as base64 JSON with `format: "pcm16"`. */
+    audio: Blob | ArrayBuffer | Uint8Array;
+    /** Required when `audio` is raw PCM16 (ignored for WAV/Blob input, whose
+     *  rate is read from the file header). */
+    sampleRate?: number;
+    /** Set when passing a raw PCM16 buffer instead of a WAV Blob. */
+    format?: 'wav' | 'pcm16';
+    language?: Language;
+}
+/** One transcribed segment with timing, when the engine provides them. */
+interface TranscribeSegment {
+    text: string;
+    start: number;
+    end: number;
+    duration: number;
+}
+/** Result of STTClient.transcribe() — mirrors POST /stt/transcribe's response body. */
+interface TranscribeResult {
+    text: string;
+    latencyMs: number;
+    engine: string;
+    sampleRate: number;
+    language: string;
+    durationSeconds: number;
+    segments?: TranscribeSegment[];
+}
+/**
+ * Continuous speech-to-text options (WS /ws/stt) — standalone transcription
+ * with server-side VAD, independent of the full voice-agent pipeline (no
+ * LLM turn, no TTS). Use this for live captioning/dictation; use
+ * STTClient.transcribe() for a single pre-recorded clip.
+ */
+interface SpeechToTextOptions {
+    apiKey: string;
+    serverUrl?: string;
+    language?: Language;
+    /** VAD engine: "silero" (default, neural) or "rms" (energy-threshold fallback). */
+    vad?: 'silero' | 'rms';
+    /** Fires repeatedly while the user is mid-utterance, with the best partial guess so far. */
+    onPartialTranscript?: (text: string) => void;
+    /** Fires once VAD detects the utterance ended. */
+    onFinalTranscript?: (text: string) => void;
+    onError?: (error: LokutorError) => void;
+    onStatusChange?: (status: 'connecting' | 'connected' | 'disconnected') => void;
+}
 /**
  * Browser audio configuration options
  */
@@ -245,6 +300,7 @@ interface AudioManager {
 declare class VoiceAgentClient {
     private ws;
     private apiKey;
+    private agentId;
     prompt: string;
     voice: VoiceStyle;
     language: Language;
@@ -433,6 +489,55 @@ declare class TTSClient {
         onError?: (error: any) => void;
     }): Promise<void>;
 }
+/**
+ * Standalone speech-to-text — batch transcription of a single, complete
+ * audio clip (POST /stt/transcribe). No LLM, no TTS, no voice-agent session.
+ * For continuous/live transcription (e.g. dictation, live captions), use
+ * SpeechToTextClient instead.
+ */
+declare class STTClient {
+    private apiKey;
+    private baseUrl;
+    constructor(config: {
+        apiKey: string;
+        serverUrl?: string;
+    });
+    /**
+     * Transcribe a complete audio clip. Pass a Blob/File (e.g. from a file
+     * input or MediaRecorder) for WAV/compressed audio, or a raw PCM16
+     * buffer with `format: "pcm16"` and `sampleRate` set.
+     */
+    transcribe(options: TranscribeOptions): Promise<TranscribeResult>;
+}
+/**
+ * Continuous speech-to-text (WS /ws/stt) — streams microphone audio to the
+ * server and receives partial transcripts while the user is speaking and a
+ * final transcript when the server's VAD detects the utterance ended.
+ * Standalone: no LLM turn, no TTS, no voice-agent session — just
+ * transcription. For a single pre-recorded clip, use STTClient instead.
+ */
+declare class SpeechToTextClient {
+    private apiKey;
+    private serverUrl;
+    private language?;
+    private vad;
+    private onPartialTranscript?;
+    private onFinalTranscript?;
+    private onError?;
+    private onStatusChange?;
+    private ws;
+    private audioManager;
+    private isConnected;
+    constructor(config: SpeechToTextOptions);
+    /**
+     * Connect and start streaming microphone audio.
+     * @param customAudioManager Optional replacement for the default audio hardware handler (e.g. NodeAudioManager for CLI use)
+     */
+    connect(customAudioManager?: AudioManager): Promise<boolean>;
+    /** Force-finalize whatever utterance is currently in progress. */
+    endUtterance(): void;
+    disconnect(): void;
+}
 /**
  * Quick function to start a conversation (requires manual audio piping in JS)
  */
@@ -446,6 +551,13 @@ declare function simpleTTS(options: SynthesizeOptions & {
     apiKey: string;
     onAudio: (buf: Uint8Array) => void;
 }): Promise<void>;
+/**
+ * Quick function for standalone, one-shot transcription of a complete audio clip.
+ */
+declare function simpleTranscribe(options: TranscribeOptions & {
+    apiKey: string;
+    serverUrl?: string;
+}): Promise<TranscribeResult>;
 
 /**
  * Audio utility functions for format conversion, resampling, and PCM processing
@@ -558,6 +670,7 @@ declare class BrowserAudioManager {
     private mediaStreamAudioSourceNode;
     private scriptProcessor;
     private analyserNode;
+    private amplitudeBuffer;
     private mediaStream;
     private resampler;
     private nextPlaybackTime;
@@ -637,14 +750,42 @@ declare class BrowserAudioManager {
     isRecording(): boolean;
 }
 
+/**
+ * Node.js-specific AudioManager implementation.
+ * Note: These require 'speaker' and 'node-record-lpcm16' to be installed by the user.
+ */
+declare class NodeAudioManager implements AudioManager {
+    private speaker;
+    private recorder;
+    private recordingStream;
+    private isMuted;
+    private isListening;
+    constructor();
+    init(): Promise<void>;
+    startMicrophone(onAudioInput: (pcm16Data: Uint8Array) => void): Promise<void>;
+    stopMicrophone(): void;
+    playAudio(pcm16Data: Uint8Array): Promise<void>;
+    stopPlayback(): void;
+    cleanup(): void;
+    isMicMuted(): boolean;
+    setMuted(muted: boolean): void;
+    getAmplitude(): number;
+}
+
 interface ConversationalPanelConfig {
+    /** Container element to mount the panel */
     container: HTMLElement;
-    title: string;
-    description: string;
-    prompt: string;
+    /** Agent name or title shown in the curtain */
+    title?: string;
+    /** Short description below the title */
+    description?: string;
+    /** System prompt for the voice agent */
+    prompt?: string;
+    /** Voice style identifier (default: M1) */
     voice?: string;
+    /** Language code (default: en) */
     language?: string;
-    /** Accent color for the sphere glow and highlights, e.g. '#e74c3c' */
+    /** Accent color for the sphere glow and highlights, e.g. '#e74c3b' */
     accentColor?: string;
     /** Background color, e.g. '#0a0a0a' */
     backgroundColor?: string;
@@ -676,14 +817,16 @@ declare class ConversationalPanel {
     private isRunning;
     private _locked;
     private _lastSpeechTime;
+    private selectedVoice;
     private el;
     private curtain;
     private curtainTitle;
     private curtainDesc;
+    private curtainBg;
+    private curtainOverlay;
     private startBtn;
     private errorEl;
     private errorText;
-    private timerEl;
     private canvas;
     private muteBtn;
     private muteSvg;
@@ -708,6 +851,7 @@ declare class ConversationalPanel {
     setBackgroundColor(color: string): void;
     /** Update title text */
     setTitle(title: string): void;
+    /** Select a voice from the picker */
     /** Update description text */
     setDescription(desc: string): void;
     /** Update prompt (only takes effect on next start()) */
@@ -718,7 +862,6 @@ declare class ConversationalPanel {
     showError(text: string): void;
     /** Destroy the component, removing all DOM and stopping any active session */
     destroy(): void;
-    private fmt;
     private startTimer;
     private toggleMute;
     private playConnectingSound;
@@ -726,4 +869,4 @@ declare class ConversationalPanel {
     private playErrorTone;
 }
 
-export { AUDIO_CONFIG, type AnalyserConfig, type AudioManager, type BrowserAudioConfig, BrowserAudioManager, type BrowserAudioOptions, ConversationalPanel, type ConversationalPanelConfig, DEFAULT_URLS, type ErrorCode, type HealthStatus, Language, type LanguageInfo, type LokutorConfig, LokutorError, type ModelInfo, type ServerConfig, type ServerStatus, StreamResampler, type SynthesizeOptions, TTSClient, type ToolCall, type ToolDefinition, type Viseme, VoiceAgentClient, type VoiceAgentOptions, type VoiceInfo, VoiceStyle, applyLowPassFilter, bytesToPcm16, calculateRMS, float32ToPcm16, isRetryable, normalizeAudio, pcm16ToBytes, pcm16ToFloat32, resample, resampleWithAntiAliasing, simpleConversation, simpleTTS };
+export { AUDIO_CONFIG, type AnalyserConfig, type AudioManager, type BrowserAudioConfig, BrowserAudioManager, type BrowserAudioOptions, ConversationalPanel, type ConversationalPanelConfig, DEFAULT_URLS, type ErrorCode, type HealthStatus, Language, type LanguageInfo, type LokutorConfig, LokutorError, type ModelInfo, NodeAudioManager, STTClient, type ServerConfig, type ServerStatus, SpeechToTextClient, type SpeechToTextOptions, StreamResampler, type SynthesizeOptions, TTSClient, type ToolCall, type ToolDefinition, type TranscribeOptions, type TranscribeResult, type TranscribeSegment, type Viseme, VoiceAgentClient, type VoiceAgentOptions, type VoiceInfo, VoiceStyle, applyLowPassFilter, bytesToPcm16, calculateRMS, float32ToPcm16, isRetryable, normalizeAudio, pcm16ToBytes, pcm16ToFloat32, resample, resampleWithAntiAliasing, simpleConversation, simpleTTS, simpleTranscribe };