@lokutor/sdk 1.1.43 → 1.2.1

package/dist/index.js

@@ -26,6 +26,9 @@ __export(index_exports, {
   DEFAULT_URLS: () => DEFAULT_URLS,
   Language: () => Language,
   LokutorError: () => LokutorError,
+  NodeAudioManager: () => NodeAudioManager,
+  STTClient: () => STTClient,
+  SpeechToTextClient: () => SpeechToTextClient,
   StreamResampler: () => StreamResampler,
   TTSClient: () => TTSClient,
   VoiceAgentClient: () => VoiceAgentClient,
@@ -41,7 +44,8 @@ __export(index_exports, {
   resample: () => resample,
   resampleWithAntiAliasing: () => resampleWithAntiAliasing,
   simpleConversation: () => simpleConversation,
-  simpleTTS: () => simpleTTS
+  simpleTTS: () => simpleTTS,
+  simpleTranscribe: () => simpleTranscribe
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -107,7 +111,8 @@ var AUDIO_CONFIG = {
 };
 var DEFAULT_URLS = {
   VOICE_AGENT: "wss://api.lokutor.com/ws/agent",
-  TTS: "wss://api.lokutor.com/ws/tts"
+  TTS: "wss://api.lokutor.com/ws/tts",
+  STT: "wss://api.lokutor.com/ws/stt"
 };
 var LokutorError = class extends Error {
   code;
@@ -287,6 +292,10 @@ var BrowserAudioManager = class {
   mediaStreamAudioSourceNode = null;
   scriptProcessor = null;
   analyserNode = null;
+  // Reused across getAmplitude() calls instead of allocating a new
+  // Uint8Array on every call — this runs once per animation frame (~60/sec)
+  // from the visualizer, on the same main thread as audio capture.
+  amplitudeBuffer = null;
   mediaStream = null;
   resampler = null;
   // Playback scheduling
@@ -353,7 +362,7 @@ var BrowserAudioManager = class {
         }
       });
       this.mediaStreamAudioSourceNode = this.audioContext.createMediaStreamSource(this.mediaStream);
-      const bufferSize = 4096;
+      const bufferSize = 1024;
       this.scriptProcessor = this.audioContext.createScriptProcessor(
         bufferSize,
         1,
@@ -387,7 +396,6 @@ var BrowserAudioManager = class {
    */
   _processAudioInput(event) {
     if (!this.onAudioInput || !this.audioContext || !this.isListening) return;
-    if (this.isMuted) return;
     const inputBuffer = event.inputBuffer;
     const inputData = inputBuffer.getChannelData(0);
     const outputBuffer = event.outputBuffer;
@@ -399,6 +407,9 @@ var BrowserAudioManager = class {
       processedData = this.resampler.process(processedData);
     }
     if (processedData.length === 0) return;
+    if (this.isMuted) {
+      processedData = new Float32Array(processedData.length);
+    }
     const int16Data = float32ToPcm16(processedData);
     const uint8Data = new Uint8Array(
       int16Data.buffer,
@@ -522,9 +533,11 @@ var BrowserAudioManager = class {
    */
   getAmplitude() {
     if (!this.analyserNode) return 0;
-    const dataArray = new Uint8Array(this.analyserNode.frequencyBinCount);
-    this.analyserNode.getByteTimeDomainData(dataArray);
-    const rms = calculateRMS(dataArray);
+    if (!this.amplitudeBuffer || this.amplitudeBuffer.length !== this.analyserNode.frequencyBinCount) {
+      this.amplitudeBuffer = new Uint8Array(this.analyserNode.frequencyBinCount);
+    }
+    this.analyserNode.getByteTimeDomainData(this.amplitudeBuffer);
+    const rms = calculateRMS(this.amplitudeBuffer);
     return Math.min(rms * 10, 1);
   }
   /**
@@ -631,6 +644,14 @@ function base64ToUint8Array(base64) {
   }
   return bytes;
 }
+function uint8ArrayToBase64(bytes) {
+  let binaryString = "";
+  const chunkSize = 32768;
+  for (let i = 0; i < bytes.length; i += chunkSize) {
+    binaryString += String.fromCharCode(...bytes.subarray(i, i + chunkSize));
+  }
+  return btoa(binaryString);
+}
 function normalizeVisemes(payload) {
   if (!Array.isArray(payload)) return [];
   const normalized = [];
@@ -667,6 +688,7 @@ function extractVisemePayload(msg) {
 var VoiceAgentClient = class {
   ws = null;
   apiKey;
+  agentId = "";
   prompt;
   voice;
   language;
@@ -699,6 +721,7 @@ var VoiceAgentClient = class {
   serverUrl;
   constructor(config) {
     this.apiKey = config.apiKey;
+    this.agentId = config.agentId || "";
     this.prompt = config.prompt;
     this.voice = config.voice || "F1" /* F1 */;
     this.language = config.language || "en" /* ENGLISH */;
@@ -743,6 +766,10 @@ var VoiceAgentClient = class {
           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", {
           endpoint: this.serverUrl,
@@ -1362,6 +1389,164 @@ var TTSClient = class {
     });
   }
 };
+var STTClient = class {
+  apiKey;
+  baseUrl;
+  constructor(config) {
+    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.
+   */
+  async transcribe(options) {
+    const url = `${this.baseUrl}/stt/transcribe`;
+    let res;
+    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);
+      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
+    };
+  }
+};
+var SpeechToTextClient = class {
+  apiKey;
+  serverUrl;
+  language;
+  vad;
+  onPartialTranscript;
+  onFinalTranscript;
+  onError;
+  onStatusChange;
+  ws = null;
+  audioManager = null;
+  isConnected = false;
+  constructor(config) {
+    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)
+   */
+  async connect(customAudioManager) {
+    this.audioManager = customAudioManager || (typeof window !== "undefined" ? new BrowserAudioManager() : null);
+    if (!this.audioManager) {
+      throw new LokutorError("internal.error", "No audio manager available \u2014 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) => {
+        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 || "en" /* 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;
+          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 {
+          }
+        };
+        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. */
+  endUtterance() {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify({ type: "end" }));
+    }
+  }
+  disconnect() {
+    this.isConnected = false;
+    this.audioManager?.stopMicrophone();
+    this.audioManager?.cleanup();
+    this.ws?.close();
+    this.ws = null;
+  }
+};
 async function simpleConversation(config) {
   const client = new VoiceAgentClient(config);
   await client.connect();
@@ -1371,6 +1556,102 @@ async function simpleTTS(options) {
   const client = new TTSClient({ apiKey: options.apiKey });
   return client.synthesize(options);
 }
+async function simpleTranscribe(options) {
+  const client = new STTClient({ apiKey: options.apiKey, serverUrl: options.serverUrl });
+  return client.transcribe(options);
+}
+
+// src/node-audio.ts
+function optionalImport(moduleName) {
+  return import(moduleName);
+}
+var NodeAudioManager = class {
+  speaker = null;
+  recorder = null;
+  recordingStream = null;
+  isMuted = false;
+  isListening = false;
+  constructor() {
+  }
+  async init() {
+    try {
+      const Speaker = await optionalImport("speaker").catch(() => null);
+      if (!Speaker) {
+        console.warn('\u26A0\uFE0F  Package "speaker" is missing. Hardware output will be disabled.');
+        console.warn("\u{1F449} Run: npm install speaker");
+      }
+    } catch (e) {
+      console.error("Error initializing Node audio:", e);
+    }
+  }
+  async startMicrophone(onAudioInput) {
+    if (this.isListening) return;
+    try {
+      const recorder = await optionalImport("node-record-lpcm16").catch(() => null);
+      if (!recorder) {
+        throw new Error('Package "node-record-lpcm16" is missing. Microphone input failed.\n\u{1F449} Run: npm install node-record-lpcm16');
+      }
+      console.log("\u{1F3A4} Starting microphone (Node.js)...");
+      this.recordingStream = recorder.record({
+        sampleRate: AUDIO_CONFIG.SAMPLE_RATE,
+        threshold: 0,
+        verbose: false,
+        recordProgram: "sox"
+        // default
+      });
+      this.recordingStream.stream().on("data", (chunk) => {
+        if (!this.isMuted && onAudioInput) {
+          onAudioInput(new Uint8Array(chunk));
+        }
+      });
+      this.isListening = true;
+    } catch (e) {
+      console.error("Failed to start microphone:", e.message);
+      throw e;
+    }
+  }
+  stopMicrophone() {
+    if (this.recordingStream) {
+      this.recordingStream.stop();
+      this.recordingStream = null;
+    }
+    this.isListening = false;
+  }
+  async playAudio(pcm16Data) {
+    try {
+      if (!this.speaker) {
+        const Speaker = (await optionalImport("speaker")).default;
+        this.speaker = new Speaker({
+          channels: AUDIO_CONFIG.CHANNELS,
+          bitDepth: 16,
+          sampleRate: AUDIO_CONFIG.SPEAKER_SAMPLE_RATE
+        });
+      }
+      this.speaker.write(Buffer.from(pcm16Data));
+    } catch (e) {
+      console.error("NodeAudioManager: speaker playback failed:", e);
+    }
+  }
+  stopPlayback() {
+    if (this.speaker) {
+      this.speaker.end();
+      this.speaker = null;
+    }
+  }
+  cleanup() {
+    this.stopMicrophone();
+    this.stopPlayback();
+  }
+  isMicMuted() {
+    return this.isMuted;
+  }
+  setMuted(muted) {
+    this.isMuted = muted;
+  }
+  getAmplitude() {
+    return 0;
+  }
+};
 
 // src/conversational-panel.ts
 var PANEL_CSS = (
@@ -1466,7 +1747,7 @@ var PANEL_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;
@@ -1592,12 +1873,47 @@ var PANEL_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; }
@@ -1682,11 +1998,13 @@ var ConversationalPanel = class {
   isRunning = false;
   _locked = false;
   _lastSpeechTime = 0;
-  // Cached DOM refs
+  selectedVoice = "M1";
   el;
   curtain;
   curtainTitle;
   curtainDesc;
+  curtainBg;
+  curtainOverlay;
   startBtn;
   errorEl;
   errorText;
@@ -1706,6 +2024,7 @@ var ConversationalPanel = class {
   constructor(cfg) {
     this.cfg = cfg;
     this.container = cfg.container;
+    this.selectedVoice = cfg.voice || "M1";
     injectStyles();
     this.buildDOM();
   }
@@ -1721,9 +2040,9 @@ var ConversationalPanel = class {
         <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"/>
@@ -1741,7 +2060,7 @@ var ConversationalPanel = class {
         </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>
@@ -1819,7 +2138,7 @@ var ConversationalPanel = class {
         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) => {
           this.el.classList.remove("cv-is-speaking", "cv-is-thinking");
@@ -1952,6 +2271,7 @@ var ConversationalPanel = class {
     const h2 = this.el.querySelector(".cv-title");
     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) {
     this.cfg.description = desc;
@@ -2082,6 +2402,9 @@ var ConversationalPanel = class {
   DEFAULT_URLS,
   Language,
   LokutorError,
+  NodeAudioManager,
+  STTClient,
+  SpeechToTextClient,
   StreamResampler,
   TTSClient,
   VoiceAgentClient,
@@ -2097,5 +2420,6 @@ var ConversationalPanel = class {
   resample,
   resampleWithAntiAliasing,
   simpleConversation,
-  simpleTTS
+  simpleTTS,
+  simpleTranscribe
 });