@lokutor/sdk 1.1.43 → 1.2.1

package/src/client.ts

@@ -16,6 +16,9 @@ import {
   ServerConfig,
   ServerStatus,
   HealthStatus,
+  TranscribeOptions,
+  TranscribeResult,
+  SpeechToTextOptions,
 } from './types';
 import { BrowserAudioManager } from './browser-audio';
 
@@ -97,6 +100,16 @@ function base64ToUint8Array(base64: string): Uint8Array {
   return bytes;
 }
 
+// Browser-compatible Uint8Array to base64
+function uint8ArrayToBase64(bytes: Uint8Array): string {
+  let binaryString = '';
+  const chunkSize = 0x8000; // avoid call-stack limits on String.fromCharCode(...large array)
+  for (let i = 0; i < bytes.length; i += chunkSize) {
+    binaryString += String.fromCharCode(...bytes.subarray(i, i + chunkSize));
+  }
+  return btoa(binaryString);
+}
+
 function normalizeVisemes(payload: any): Viseme[] {
   if (!Array.isArray(payload)) return [];
   const normalized: Viseme[] = [];
@@ -144,6 +157,7 @@ function extractVisemePayload(msg: any): Viseme[] {
 export class VoiceAgentClient {
   private ws: WebSocket | null = null;
   private apiKey: string;
+  private agentId: string = "";
   public prompt: string;
   public voice: VoiceStyle;
   public language: Language;
@@ -192,6 +206,7 @@ export class VoiceAgentClient {
     serverUrl?: string,
   }) {
     this.apiKey = config.apiKey;
+    this.agentId = config.agentId || "";
     this.prompt = config.prompt;
     this.voice = config.voice || VoiceStyle.F1;
     this.language = config.language || Language.ENGLISH;
@@ -242,6 +257,10 @@ export class VoiceAgentClient {
           const separator = url.includes('?') ? '&' : '?';
           url += `${separator}api_key=${this.apiKey}`;
         }
+        if (this.agentId) {
+          const separator = url.includes('?') ? '&' : '?';
+          url += `${separator}agent_id=${this.agentId}`;
+        }
 
         const redactedUrl = url.replace(/api_key=[^&]+/, 'api_key=***');
         sdkTrace('ws.connect', {
@@ -955,6 +974,198 @@ export class TTSClient {
   }
 }
 
+/**
+ * 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.
+ */
+export class STTClient {
+  private apiKey: string;
+  private baseUrl: string;
+
+  constructor(config: { apiKey: string; serverUrl?: string }) {
+    this.apiKey = config.apiKey;
+    this.baseUrl = wsToHttp(config.serverUrl || DEFAULT_URLS.STT).replace(/\/ws\/stt\/?$/, '');
+  }
+
+  /**
+   * 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.
+   */
+  public async transcribe(options: TranscribeOptions): Promise<TranscribeResult> {
+    const url = `${this.baseUrl}/stt/transcribe`;
+    let res: Response;
+
+    if (typeof Blob !== 'undefined' && options.audio instanceof Blob) {
+      const form = new FormData();
+      form.append('audio', options.audio, 'audio.wav');
+      if (options.language) form.append('lang', options.language);
+      if (options.sampleRate) form.append('sample_rate', String(options.sampleRate));
+      res = await fetch(url, {
+        method: 'POST',
+        headers: { 'X-API-Key': this.apiKey },
+        body: form,
+      });
+    } else {
+      const bytes = options.audio instanceof Uint8Array
+        ? options.audio
+        : new Uint8Array(options.audio as ArrayBuffer);
+      res = await fetch(url, {
+        method: 'POST',
+        headers: { 'X-API-Key': this.apiKey, 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          audio: uint8ArrayToBase64(bytes),
+          format: options.format || 'pcm16',
+          sample_rate: options.sampleRate,
+          lang: options.language,
+        }),
+      });
+    }
+
+    if (!res.ok) {
+      const detail = await res.text().catch(() => '');
+      throw new LokutorError('internal.error', `HTTP ${res.status} from ${url}`, {
+        detail,
+        retryable: res.status >= 500,
+      });
+    }
+
+    const data = await res.json();
+    return {
+      text: data.text ?? '',
+      latencyMs: data.latency_ms ?? 0,
+      engine: data.engine ?? '',
+      sampleRate: data.sample_rate ?? 0,
+      language: data.language ?? '',
+      durationSeconds: data.duration_seconds ?? 0,
+      segments: data.segments,
+    };
+  }
+}
+
+/**
+ * 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.
+ */
+export class SpeechToTextClient {
+  private apiKey: string;
+  private serverUrl: string;
+  private language?: Language;
+  private vad: 'silero' | 'rms';
+  private onPartialTranscript?: (text: string) => void;
+  private onFinalTranscript?: (text: string) => void;
+  private onError?: (error: LokutorError) => void;
+  private onStatusChange?: (status: 'connecting' | 'connected' | 'disconnected') => void;
+
+  private ws: WebSocket | null = null;
+  private audioManager: AudioManager | null = null;
+  private isConnected = false;
+
+  constructor(config: SpeechToTextOptions) {
+    this.apiKey = config.apiKey;
+    this.serverUrl = config.serverUrl || DEFAULT_URLS.STT;
+    this.language = config.language;
+    this.vad = config.vad || 'silero';
+    this.onPartialTranscript = config.onPartialTranscript;
+    this.onFinalTranscript = config.onFinalTranscript;
+    this.onError = config.onError;
+    this.onStatusChange = config.onStatusChange;
+  }
+
+  /**
+   * Connect and start streaming microphone audio.
+   * @param customAudioManager Optional replacement for the default audio hardware handler (e.g. NodeAudioManager for CLI use)
+   */
+  public async connect(customAudioManager?: AudioManager): Promise<boolean> {
+    this.audioManager = customAudioManager
+      || (typeof window !== 'undefined' ? new BrowserAudioManager() : null);
+    if (!this.audioManager) {
+      throw new LokutorError('internal.error', 'No audio manager available — pass one explicitly outside the browser (e.g. NodeAudioManager).');
+    }
+    await this.audioManager.init();
+
+    this.onStatusChange?.('connecting');
+
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const settle = (fn: () => void) => { if (!settled) { settled = true; fn(); } };
+
+      try {
+        let url = this.serverUrl;
+        const separator = url.includes('?') ? '&' : '?';
+        url += `${separator}api_key=${this.apiKey}`;
+
+        this.ws = new WebSocket(url);
+
+        this.ws.onopen = async () => {
+          this.isConnected = true;
+          this.onStatusChange?.('connected');
+          this.ws!.send(JSON.stringify({ lang: this.language || Language.ENGLISH, vad: this.vad }));
+
+          await this.audioManager!.startMicrophone((data) => {
+            if (this.isConnected && this.ws?.readyState === WebSocket.OPEN) {
+              this.ws.send(data);
+            }
+          });
+
+          settle(() => resolve(true));
+        };
+
+        this.ws.onmessage = (event) => {
+          if (typeof event.data !== 'string') return; // this endpoint only ever sends JSON text frames
+          try {
+            const msg = JSON.parse(event.data);
+            if (msg.type === 'transcript') {
+              if (msg.isFinal) {
+                this.onFinalTranscript?.(msg.data ?? '');
+              } else {
+                this.onPartialTranscript?.(msg.data ?? '');
+              }
+            } else if (msg.type === 'error') {
+              this.onError?.(new LokutorError('internal.error', msg.data ?? 'STT error'));
+            }
+          } catch {
+            // ignore malformed frames
+          }
+        };
+
+        this.ws.onerror = (err) => {
+          const lokutorErr = new LokutorError('internal.error', 'WebSocket error', { original: err });
+          this.onError?.(lokutorErr);
+          settle(() => reject(lokutorErr));
+        };
+
+        this.ws.onclose = () => {
+          this.isConnected = false;
+          this.onStatusChange?.('disconnected');
+        };
+      } catch (err) {
+        settle(() => reject(err));
+      }
+    });
+  }
+
+  /** Force-finalize whatever utterance is currently in progress. */
+  public endUtterance(): void {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify({ type: 'end' }));
+    }
+  }
+
+  public disconnect(): void {
+    this.isConnected = false;
+    this.audioManager?.stopMicrophone();
+    this.audioManager?.cleanup();
+    this.ws?.close();
+    this.ws = null;
+  }
+}
+
 /**
  * Quick function to start a conversation (requires manual audio piping in JS)
  */
@@ -971,3 +1182,11 @@ export async function simpleTTS(options: SynthesizeOptions & { apiKey: string, o
   const client = new TTSClient({ apiKey: options.apiKey });
   return client.synthesize(options);
 }
+
+/**
+ * Quick function for standalone, one-shot transcription of a complete audio clip.
+ */
+export async function simpleTranscribe(options: TranscribeOptions & { apiKey: string; serverUrl?: string }): Promise<TranscribeResult> {
+  const client = new STTClient({ apiKey: options.apiKey, serverUrl: options.serverUrl });
+  return client.transcribe(options);
+}

package/src/conversational-panel.ts

@@ -89,7 +89,7 @@ const PANEL_CSS = /*css*/ `
   }
   .cv-curtain-btn svg { transition: transform 0.3s ease; }
   .cv-curtain-btn:hover svg { transform: translateX(4px); }
-  .cv-header {
+  .cv-error {
     display: flex;
     flex-direction: column;
     align-items: center;
@@ -215,12 +215,47 @@ const PANEL_CSS = /*css*/ `
   }
   .cv-error.is-visible { display: flex; }
   .cv-error-icon { color: var(--cv-accent); flex-shrink: 0; }
+  .cv-voice-picker {
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: center;
+    gap: 0.35rem;
+    z-index: 2;
+  }
+  .cv-voice-btn {
+    padding: 0.25rem 0.5rem;
+    border-radius: 100px;
+    border: 1px solid rgba(255,255,255,0.15);
+    background: rgba(255,255,255,0.05);
+    color: rgba(255,255,255,0.6);
+    font-size: 0.65rem;
+    font-weight: 600;
+    cursor: pointer;
+    transition: all 0.2s ease;
+  }
+  .cv-voice-btn:hover {
+    background: rgba(255,255,255,0.12);
+    color: #fff;
+  }
+  .cv-voice-btn.is-selected {
+    background: #fff;
+    color: #000;
+    border-color: #fff;
+  }
+  .cv-voice-label {
+    font-size: 0.55rem;
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    color: rgba(255,255,255,0.35);
+    z-index: 2;
+  }
   
   /* === COMPACT MODE: < 300px width === */
   @container (max-width: 299px) {
     .cv-curtain-content { padding: 0.5rem; gap: 0.3rem; }
     .cv-curtain-title { font-size: 0.8rem; }
     .cv-curtain-desc { display: none; }
+    .cv-voice-picker { display: none; }
     .cv-curtain-btn { padding: 0.3rem 0.6rem; font-size: 0.6rem; gap: 0.3rem; }
     .cv-curtain-btn svg { display: none; }
     .cv-visualizer-wrap { width: 60px; height: 60px; }
@@ -297,13 +332,19 @@ function injectStyles() {
 }
 
 export 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;
@@ -336,12 +377,13 @@ export class ConversationalPanel {
   private isRunning = false;
   private _locked = false;
   private _lastSpeechTime = 0;
-
-  // Cached DOM refs
+  private selectedVoice = 'M1';
   private el!: HTMLElement;
   private curtain!: HTMLElement;
   private curtainTitle!: HTMLElement;
   private curtainDesc!: HTMLElement;
+  private curtainBg!: HTMLElement;
+  private curtainOverlay!: HTMLElement;
   private startBtn!: HTMLButtonElement;
   private errorEl!: HTMLElement;
   private errorText!: HTMLElement;
@@ -363,6 +405,7 @@ export class ConversationalPanel {
   constructor(cfg: ConversationalPanelConfig) {
     this.cfg = cfg;
     this.container = cfg.container;
+    this.selectedVoice = cfg.voice || 'M1';
     injectStyles();
     this.buildDOM();
   }
@@ -381,9 +424,9 @@ export class ConversationalPanel {
         <div class="cv-curtain-bg"></div>
         <div class="cv-curtain-overlay"></div>
         <div class="cv-curtain-content">
-          <h3 class="cv-curtain-title">${this.esc(this.cfg.title)}</h3>
-          <p class="cv-curtain-desc">${this.esc(this.cfg.description)}</p>
-          <button class="cv-curtain-btn">
+          <h3 class="cv-curtain-title">${this.esc(this.cfg.title || "Voice Chat")}</h3>
+          <p class="cv-curtain-desc">${this.esc(this.cfg.description || "")}</p>
+           <button class="cv-curtain-btn">
             <span>Start Conversation</span>
             <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" width="20" height="20">
               <path d="M5 12h14M12 5l7 7-7 7"/>
@@ -401,7 +444,7 @@ export class ConversationalPanel {
         </div>
       </div>
       <div class="cv-header">
-        <h2 class="cv-title">${this.esc(this.cfg.title)} <span class="cv-timer">00:00</span></h2>
+        <h2 class="cv-title">${this.esc(this.cfg.title || "Voice Chat")} <span class="cv-timer">00:00</span></h2>
       </div>
       <div class="cv-visualizer-wrap">
         <canvas class="cv-canvas"></canvas>
@@ -493,7 +536,7 @@ export class ConversationalPanel {
         apiKey: this.cfg.apiKey,
         tools: this.cfg.tools,
         prompt: this.cfg.prompt,
-        voice: this.cfg.voice || 'M1',
+        voice: this.selectedVoice,
         language: this.cfg.language || 'en',
         onStatusChange: (status: string) => {
           this.el.classList.remove('cv-is-speaking', 'cv-is-thinking');
@@ -633,6 +676,7 @@ export class ConversationalPanel {
     if (h2) h2.innerHTML = `${this.esc(title)} <span class="cv-timer">${this.timerEl?.textContent || '00:00'}</span>`;
   }
 
+  /** Select a voice from the picker */
   /** Update description text */
   setDescription(desc: string) {
     this.cfg.description = desc;

package/src/index.ts

@@ -2,8 +2,18 @@ export * from './types';
 export * from './client';
 export * from './audio-utils';
 export * from './browser-audio';
-export { VoiceAgentClient, TTSClient, simpleConversation, simpleTTS } from './client';
+export * from './node-audio';
+export {
+  VoiceAgentClient,
+  TTSClient,
+  STTClient,
+  SpeechToTextClient,
+  simpleConversation,
+  simpleTTS,
+  simpleTranscribe,
+} from './client';
 export { BrowserAudioManager } from './browser-audio';
+export { NodeAudioManager } from './node-audio';
 export { ConversationalPanel } from './conversational-panel';
 export type { ConversationalPanelConfig } from './conversational-panel';
 export {
@@ -24,4 +34,8 @@ export type {
   ServerConfig,
   ServerStatus,
   HealthStatus,
+  TranscribeOptions,
+  TranscribeResult,
+  TranscribeSegment,
+  SpeechToTextOptions,
 } from './types';

package/src/node-audio.ts

@@ -3,6 +3,18 @@
 import { AudioManager } from './client';
 import { AUDIO_CONFIG } from './types';
 
+// 'speaker' and 'node-record-lpcm16' are optional peer dependencies — Node.js
+// users who want managed microphone/speaker I/O install them themselves (see
+// the warnings below); they are not bundled or required by this package, and
+// aren't installed while building the SDK itself. Importing by a non-literal
+// string (rather than `import('speaker')` directly) keeps TypeScript from
+// trying to resolve either module's types at the SDK's own build time —
+// this always resolves to `any`, and at runtime falls through to the
+// .catch(() => null) handling below if the consumer hasn't installed it.
+function optionalImport(moduleName: string): Promise<any> {
+  return import(moduleName);
+}
+
 /**
  * Node.js-specific AudioManager implementation.
  * Note: These require 'speaker' and 'node-record-lpcm16' to be installed by the user.
@@ -20,7 +32,7 @@ export class NodeAudioManager implements AudioManager {
     try {
       // Dynamic imports to avoid crashing if dependencies are missing at build time
       // The user must install these manually for managed Node.js audio
-      const Speaker = await import('speaker').catch(() => null);
+      const Speaker = await optionalImport('speaker').catch(() => null);
       if (!Speaker) {
         console.warn('⚠️  Package "speaker" is missing. Hardware output will be disabled.');
         console.warn('👉 Run: npm install speaker');
@@ -34,7 +46,7 @@ export class NodeAudioManager implements AudioManager {
     if (this.isListening) return;
 
     try {
-      const recorder = await import('node-record-lpcm16').catch(() => null);
+      const recorder = await optionalImport('node-record-lpcm16').catch(() => null);
       if (!recorder) {
         throw new Error('Package "node-record-lpcm16" is missing. Microphone input failed.\n👉 Run: npm install node-record-lpcm16');
       }
@@ -72,7 +84,7 @@ export class NodeAudioManager implements AudioManager {
   async playAudio(pcm16Data: Uint8Array): Promise<void> {
     try {
       if (!this.speaker) {
-        const Speaker = (await import('speaker')).default;
+        const Speaker = (await optionalImport('speaker')).default;
         this.speaker = new Speaker({
           channels: AUDIO_CONFIG.CHANNELS,
           bitDepth: 16,

package/src/types.ts

@@ -76,6 +76,7 @@ export const AUDIO_CONFIG = {
 export const DEFAULT_URLS = {
   VOICE_AGENT: "wss://api.lokutor.com/ws/agent",
   TTS: "wss://api.lokutor.com/ws/tts",
+  STT: "wss://api.lokutor.com/ws/stt",
 };
 
 /**
@@ -83,6 +84,7 @@ export const DEFAULT_URLS = {
  */
 export interface LokutorConfig {
   apiKey: string;
+  agentId?: string;
   onTranscription?: (text: string) => void;
   onResponse?: (text: string) => void;
   onAudio?: (data: Uint8Array) => void;
@@ -102,6 +104,63 @@ export interface SynthesizeOptions {
   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.
+ */
+export 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. */
+export interface TranscribeSegment {
+  text: string;
+  start: number;
+  end: number;
+  duration: number;
+}
+
+/** Result of STTClient.transcribe() — mirrors POST /stt/transcribe's response body. */
+export 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.
+ */
+export 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
  */