@contractspec/lib.voice 0.2.0

package/dist/node/audio/audio-concatenator.js

@@ -0,0 +1,56 @@
+// src/audio/audio-concatenator.ts
+class AudioConcatenator {
+  concatenate(segments) {
+    if (segments.length === 0) {
+      return {
+        data: new Uint8Array(0),
+        format: "wav",
+        sampleRateHz: 44100,
+        durationMs: 0,
+        channels: 1
+      };
+    }
+    const [firstSegment] = segments;
+    if (!firstSegment) {
+      return {
+        data: new Uint8Array(0),
+        format: "wav",
+        sampleRateHz: 44100,
+        durationMs: 0,
+        channels: 1
+      };
+    }
+    if (segments.length === 1) {
+      return { ...firstSegment };
+    }
+    const referenceFormat = firstSegment.format;
+    const referenceSampleRate = firstSegment.sampleRateHz;
+    const referenceChannels = firstSegment.channels ?? 1;
+    for (const seg of segments) {
+      if (seg.format !== referenceFormat) {
+        throw new Error(`Format mismatch: expected ${referenceFormat}, got ${seg.format}`);
+      }
+      if (seg.sampleRateHz !== referenceSampleRate) {
+        throw new Error(`Sample rate mismatch: expected ${referenceSampleRate}, got ${seg.sampleRateHz}`);
+      }
+    }
+    const totalBytes = segments.reduce((sum, s) => sum + s.data.length, 0);
+    const combined = new Uint8Array(totalBytes);
+    let offset = 0;
+    for (const seg of segments) {
+      combined.set(seg.data, offset);
+      offset += seg.data.length;
+    }
+    const totalDurationMs = segments.reduce((sum, s) => sum + (s.durationMs ?? 0), 0);
+    return {
+      data: combined,
+      format: referenceFormat,
+      sampleRateHz: referenceSampleRate,
+      durationMs: totalDurationMs,
+      channels: referenceChannels
+    };
+  }
+}
+export {
+  AudioConcatenator
+};

package/dist/node/audio/duration-estimator.js

@@ -0,0 +1,21 @@
+// src/audio/duration-estimator.ts
+class DurationEstimator {
+  static DEFAULT_WPM = 150;
+  estimateSeconds(text, wordsPerMinute) {
+    const wpm = wordsPerMinute ?? DurationEstimator.DEFAULT_WPM;
+    const wordCount = text.split(/\s+/).filter(Boolean).length;
+    return Math.ceil(wordCount / wpm * 60);
+  }
+  estimateMs(text, wordsPerMinute) {
+    const wpm = wordsPerMinute ?? DurationEstimator.DEFAULT_WPM;
+    const wordCount = text.split(/\s+/).filter(Boolean).length;
+    return Math.ceil(wordCount / wpm * 60 * 1000);
+  }
+  estimateWordCount(durationSeconds, wordsPerMinute) {
+    const wpm = wordsPerMinute ?? DurationEstimator.DEFAULT_WPM;
+    return Math.round(durationSeconds / 60 * wpm);
+  }
+}
+export {
+  DurationEstimator
+};

package/dist/node/audio/format-converter.js

@@ -0,0 +1,27 @@
+// src/audio/format-converter.ts
+class FormatConverter {
+  convert(audio, targetFormat) {
+    if (audio.format === targetFormat) {
+      return audio;
+    }
+    return {
+      ...audio,
+      format: targetFormat
+    };
+  }
+  isSupported(from, to) {
+    if (from === to)
+      return true;
+    const supportedPaths = {
+      wav: ["mp3", "ogg", "pcm", "opus"],
+      mp3: ["wav"],
+      ogg: ["wav"],
+      pcm: ["wav"],
+      opus: ["wav"]
+    };
+    return supportedPaths[from]?.includes(to) ?? false;
+  }
+}
+export {
+  FormatConverter
+};

package/dist/node/audio/index.js

@@ -0,0 +1,120 @@
+// src/audio/audio-concatenator.ts
+class AudioConcatenator {
+  concatenate(segments) {
+    if (segments.length === 0) {
+      return {
+        data: new Uint8Array(0),
+        format: "wav",
+        sampleRateHz: 44100,
+        durationMs: 0,
+        channels: 1
+      };
+    }
+    const [firstSegment] = segments;
+    if (!firstSegment) {
+      return {
+        data: new Uint8Array(0),
+        format: "wav",
+        sampleRateHz: 44100,
+        durationMs: 0,
+        channels: 1
+      };
+    }
+    if (segments.length === 1) {
+      return { ...firstSegment };
+    }
+    const referenceFormat = firstSegment.format;
+    const referenceSampleRate = firstSegment.sampleRateHz;
+    const referenceChannels = firstSegment.channels ?? 1;
+    for (const seg of segments) {
+      if (seg.format !== referenceFormat) {
+        throw new Error(`Format mismatch: expected ${referenceFormat}, got ${seg.format}`);
+      }
+      if (seg.sampleRateHz !== referenceSampleRate) {
+        throw new Error(`Sample rate mismatch: expected ${referenceSampleRate}, got ${seg.sampleRateHz}`);
+      }
+    }
+    const totalBytes = segments.reduce((sum, s) => sum + s.data.length, 0);
+    const combined = new Uint8Array(totalBytes);
+    let offset = 0;
+    for (const seg of segments) {
+      combined.set(seg.data, offset);
+      offset += seg.data.length;
+    }
+    const totalDurationMs = segments.reduce((sum, s) => sum + (s.durationMs ?? 0), 0);
+    return {
+      data: combined,
+      format: referenceFormat,
+      sampleRateHz: referenceSampleRate,
+      durationMs: totalDurationMs,
+      channels: referenceChannels
+    };
+  }
+}
+
+// src/audio/duration-estimator.ts
+class DurationEstimator {
+  static DEFAULT_WPM = 150;
+  estimateSeconds(text, wordsPerMinute) {
+    const wpm = wordsPerMinute ?? DurationEstimator.DEFAULT_WPM;
+    const wordCount = text.split(/\s+/).filter(Boolean).length;
+    return Math.ceil(wordCount / wpm * 60);
+  }
+  estimateMs(text, wordsPerMinute) {
+    const wpm = wordsPerMinute ?? DurationEstimator.DEFAULT_WPM;
+    const wordCount = text.split(/\s+/).filter(Boolean).length;
+    return Math.ceil(wordCount / wpm * 60 * 1000);
+  }
+  estimateWordCount(durationSeconds, wordsPerMinute) {
+    const wpm = wordsPerMinute ?? DurationEstimator.DEFAULT_WPM;
+    return Math.round(durationSeconds / 60 * wpm);
+  }
+}
+
+// src/audio/format-converter.ts
+class FormatConverter {
+  convert(audio, targetFormat) {
+    if (audio.format === targetFormat) {
+      return audio;
+    }
+    return {
+      ...audio,
+      format: targetFormat
+    };
+  }
+  isSupported(from, to) {
+    if (from === to)
+      return true;
+    const supportedPaths = {
+      wav: ["mp3", "ogg", "pcm", "opus"],
+      mp3: ["wav"],
+      ogg: ["wav"],
+      pcm: ["wav"],
+      opus: ["wav"]
+    };
+    return supportedPaths[from]?.includes(to) ?? false;
+  }
+}
+
+// src/audio/silence-generator.ts
+class SilenceGenerator {
+  generate(durationMs, format = "wav", sampleRateHz = 44100, channels = 1) {
+    const totalSamples = Math.ceil(sampleRateHz * durationMs / 1000);
+    const bytesPerSample = 2;
+    const dataSize = totalSamples * bytesPerSample * channels;
+    const data = new Uint8Array(dataSize);
+    return {
+      data,
+      format,
+      sampleRateHz,
+      durationMs,
+      channels
+    };
+  }
+}
+export {
+  SilenceGenerator,
+  FormatConverter,
+  DurationEstimator,
+  AudioConcatenator
+};

package/dist/node/audio/silence-generator.js

@@ -0,0 +1,19 @@
+// src/audio/silence-generator.ts
+class SilenceGenerator {
+  generate(durationMs, format = "wav", sampleRateHz = 44100, channels = 1) {
+    const totalSamples = Math.ceil(sampleRateHz * durationMs / 1000);
+    const bytesPerSample = 2;
+    const dataSize = totalSamples * bytesPerSample * channels;
+    const data = new Uint8Array(dataSize);
+    return {
+      data,
+      format,
+      sampleRateHz,
+      durationMs,
+      channels
+    };
+  }
+}
+export {
+  SilenceGenerator
+};

package/dist/node/conversational/index.js

@@ -0,0 +1,241 @@
+// src/conversational/transcript-builder.ts
+class TranscriptBuilder {
+  turns = [];
+  currentTurn = null;
+  sessionStartMs = Date.now();
+  getTranscript() {
+    return [...this.turns];
+  }
+  toText() {
+    return this.turns.map((t) => `[${t.role}] ${t.text}`).join(`
+`);
+  }
+  getTurnCount() {
+    return this.turns.length;
+  }
+  processEvent(event) {
+    switch (event.type) {
+      case "session_started":
+        this.sessionStartMs = Date.now();
+        break;
+      case "user_speech_started":
+        this.currentTurn = {
+          role: "user",
+          startMs: Date.now() - this.sessionStartMs
+        };
+        break;
+      case "user_speech_ended":
+        if (this.currentTurn && this.currentTurn.role === "user") {
+          this.currentTurn.text = event.transcript;
+          this.currentTurn.endMs = Date.now() - this.sessionStartMs;
+          this.turns.push(this.currentTurn);
+          this.currentTurn = null;
+        }
+        break;
+      case "agent_speech_started":
+        this.currentTurn = {
+          role: "agent",
+          text: event.text,
+          startMs: Date.now() - this.sessionStartMs
+        };
+        break;
+      case "agent_speech_ended":
+        if (this.currentTurn && this.currentTurn.role === "agent") {
+          this.currentTurn.endMs = Date.now() - this.sessionStartMs;
+          this.turns.push(this.currentTurn);
+          this.currentTurn = null;
+        }
+        break;
+      case "transcript":
+        break;
+      default:
+        break;
+    }
+  }
+  reset() {
+    this.turns.length = 0;
+    this.currentTurn = null;
+    this.sessionStartMs = Date.now();
+  }
+}
+
+// src/conversational/voice-session-manager.ts
+class VoiceSessionManager {
+  provider;
+  constructor(options) {
+    this.provider = options.conversational;
+  }
+  async startSession(config) {
+    const transcriptBuilder = new TranscriptBuilder;
+    const session = await this.provider.startSession({
+      voiceId: config.voiceId,
+      language: config.language,
+      systemPrompt: config.systemPrompt,
+      llmModel: config.llmModel,
+      inputFormat: config.inputFormat,
+      outputFormat: config.outputFormat,
+      turnDetection: config.turnDetection,
+      silenceThresholdMs: config.silenceThresholdMs,
+      maxDurationSeconds: config.maxDurationSeconds
+    });
+    const state = {
+      sessionId: "",
+      status: "connecting",
+      currentTurn: "idle",
+      turnCount: 0,
+      durationMs: 0,
+      transcript: []
+    };
+    const wrappedEvents = this.wrapEvents(session.events, state, transcriptBuilder);
+    return {
+      state,
+      sendAudio: (chunk) => session.sendAudio(chunk),
+      sendText: (text) => session.sendText(text),
+      interrupt: () => session.interrupt(),
+      close: async () => {
+        const summary = await session.close();
+        state.status = "ended";
+        return summary;
+      },
+      events: wrappedEvents
+    };
+  }
+  async* wrapEvents(events, state, transcriptBuilder) {
+    for await (const event of events) {
+      transcriptBuilder.processEvent(event);
+      switch (event.type) {
+        case "session_started":
+          state.sessionId = event.sessionId;
+          state.status = "active";
+          break;
+        case "user_speech_started":
+          state.currentTurn = "user";
+          break;
+        case "user_speech_ended":
+          state.currentTurn = "idle";
+          state.turnCount += 1;
+          break;
+        case "agent_speech_started":
+          state.currentTurn = "agent";
+          break;
+        case "agent_speech_ended":
+          state.currentTurn = "idle";
+          state.turnCount += 1;
+          break;
+        case "session_ended":
+          state.status = "ended";
+          state.durationMs = event.durationMs;
+          break;
+      }
+      state.transcript = transcriptBuilder.getTranscript();
+      yield event;
+    }
+  }
+}
+
+// src/conversational/turn-detector.ts
+class TurnDetector {
+  silenceThresholdMs;
+  energyThreshold;
+  silenceStartMs = null;
+  constructor(silenceThresholdMs = 800, energyThreshold = 0.01) {
+    this.silenceThresholdMs = silenceThresholdMs;
+    this.energyThreshold = energyThreshold;
+  }
+  processChunk(chunk, timestampMs) {
+    const energy = this.calculateEnergy(chunk);
+    const isSpeech = energy > this.energyThreshold;
+    if (isSpeech) {
+      this.silenceStartMs = null;
+      return false;
+    }
+    if (this.silenceStartMs === null) {
+      this.silenceStartMs = timestampMs;
+    }
+    const silenceDurationMs = timestampMs - this.silenceStartMs;
+    return silenceDurationMs >= this.silenceThresholdMs;
+  }
+  reset() {
+    this.silenceStartMs = null;
+  }
+  calculateEnergy(chunk) {
+    if (chunk.length < 2)
+      return 0;
+    let sum = 0;
+    const sampleCount = Math.floor(chunk.length / 2);
+    for (let i = 0;i < chunk.length - 1; i += 2) {
+      const low = chunk[i] ?? 0;
+      const high = chunk[i + 1] ?? 0;
+      const sample = (low | high << 8) << 16 >> 16;
+      const normalized = sample / 32768;
+      sum += normalized * normalized;
+    }
+    return Math.sqrt(sum / sampleCount);
+  }
+}
+
+// src/conversational/response-orchestrator.ts
+class ResponseOrchestrator {
+  stt;
+  llm;
+  tts;
+  conversationHistory = [];
+  constructor(stt, llm, tts) {
+    this.stt = stt;
+    this.llm = llm;
+    this.tts = tts;
+  }
+  async* processUserTurn(userAudio, config) {
+    const transcription = await this.stt.transcribe({
+      audio: userAudio,
+      language: config.language,
+      wordTimestamps: false
+    });
+    const userText = transcription.text;
+    yield { type: "user_speech_ended", transcript: userText };
+    yield {
+      type: "transcript",
+      role: "user",
+      text: userText,
+      timestamp: Date.now()
+    };
+    this.conversationHistory.push({ role: "user", content: userText });
+    const llmResponse = await this.llm.chat([
+      {
+        role: "system",
+        content: [{ type: "text", text: config.systemPrompt }]
+      },
+      ...this.conversationHistory.map((msg) => ({
+        role: msg.role,
+        content: [{ type: "text", text: msg.content }]
+      }))
+    ], { model: config.llmModel });
+    const responseText = llmResponse.message.content.find((p) => p.type === "text");
+    const agentText = responseText && responseText.type === "text" ? responseText.text : "I apologize, I could not generate a response.";
+    this.conversationHistory.push({ role: "assistant", content: agentText });
+    yield { type: "agent_speech_started", text: agentText };
+    const synthesis = await this.tts.synthesize({
+      text: agentText,
+      voiceId: config.voiceId,
+      language: config.language,
+      format: config.outputFormat
+    });
+    yield { type: "agent_audio", audio: synthesis.audio.data };
+    yield { type: "agent_speech_ended" };
+    yield {
+      type: "transcript",
+      role: "agent",
+      text: agentText,
+      timestamp: Date.now()
+    };
+  }
+  reset() {
+    this.conversationHistory.length = 0;
+  }
+}
+export {
+  VoiceSessionManager,
+  TurnDetector,
+  TranscriptBuilder,
+  ResponseOrchestrator
+};

package/dist/node/conversational/response-orchestrator.js

@@ -0,0 +1,62 @@
+// src/conversational/response-orchestrator.ts
+class ResponseOrchestrator {
+  stt;
+  llm;
+  tts;
+  conversationHistory = [];
+  constructor(stt, llm, tts) {
+    this.stt = stt;
+    this.llm = llm;
+    this.tts = tts;
+  }
+  async* processUserTurn(userAudio, config) {
+    const transcription = await this.stt.transcribe({
+      audio: userAudio,
+      language: config.language,
+      wordTimestamps: false
+    });
+    const userText = transcription.text;
+    yield { type: "user_speech_ended", transcript: userText };
+    yield {
+      type: "transcript",
+      role: "user",
+      text: userText,
+      timestamp: Date.now()
+    };
+    this.conversationHistory.push({ role: "user", content: userText });
+    const llmResponse = await this.llm.chat([
+      {
+        role: "system",
+        content: [{ type: "text", text: config.systemPrompt }]
+      },
+      ...this.conversationHistory.map((msg) => ({
+        role: msg.role,
+        content: [{ type: "text", text: msg.content }]
+      }))
+    ], { model: config.llmModel });
+    const responseText = llmResponse.message.content.find((p) => p.type === "text");
+    const agentText = responseText && responseText.type === "text" ? responseText.text : "I apologize, I could not generate a response.";
+    this.conversationHistory.push({ role: "assistant", content: agentText });
+    yield { type: "agent_speech_started", text: agentText };
+    const synthesis = await this.tts.synthesize({
+      text: agentText,
+      voiceId: config.voiceId,
+      language: config.language,
+      format: config.outputFormat
+    });
+    yield { type: "agent_audio", audio: synthesis.audio.data };
+    yield { type: "agent_speech_ended" };
+    yield {
+      type: "transcript",
+      role: "agent",
+      text: agentText,
+      timestamp: Date.now()
+    };
+  }
+  reset() {
+    this.conversationHistory.length = 0;
+  }
+}
+export {
+  ResponseOrchestrator
+};

package/dist/node/conversational/transcript-builder.js

@@ -0,0 +1,63 @@
+// src/conversational/transcript-builder.ts
+class TranscriptBuilder {
+  turns = [];
+  currentTurn = null;
+  sessionStartMs = Date.now();
+  getTranscript() {
+    return [...this.turns];
+  }
+  toText() {
+    return this.turns.map((t) => `[${t.role}] ${t.text}`).join(`
+`);
+  }
+  getTurnCount() {
+    return this.turns.length;
+  }
+  processEvent(event) {
+    switch (event.type) {
+      case "session_started":
+        this.sessionStartMs = Date.now();
+        break;
+      case "user_speech_started":
+        this.currentTurn = {
+          role: "user",
+          startMs: Date.now() - this.sessionStartMs
+        };
+        break;
+      case "user_speech_ended":
+        if (this.currentTurn && this.currentTurn.role === "user") {
+          this.currentTurn.text = event.transcript;
+          this.currentTurn.endMs = Date.now() - this.sessionStartMs;
+          this.turns.push(this.currentTurn);
+          this.currentTurn = null;
+        }
+        break;
+      case "agent_speech_started":
+        this.currentTurn = {
+          role: "agent",
+          text: event.text,
+          startMs: Date.now() - this.sessionStartMs
+        };
+        break;
+      case "agent_speech_ended":
+        if (this.currentTurn && this.currentTurn.role === "agent") {
+          this.currentTurn.endMs = Date.now() - this.sessionStartMs;
+          this.turns.push(this.currentTurn);
+          this.currentTurn = null;
+        }
+        break;
+      case "transcript":
+        break;
+      default:
+        break;
+    }
+  }
+  reset() {
+    this.turns.length = 0;
+    this.currentTurn = null;
+    this.sessionStartMs = Date.now();
+  }
+}
+export {
+  TranscriptBuilder
+};

package/dist/node/conversational/turn-detector.js

@@ -0,0 +1,43 @@
+// src/conversational/turn-detector.ts
+class TurnDetector {
+  silenceThresholdMs;
+  energyThreshold;
+  silenceStartMs = null;
+  constructor(silenceThresholdMs = 800, energyThreshold = 0.01) {
+    this.silenceThresholdMs = silenceThresholdMs;
+    this.energyThreshold = energyThreshold;
+  }
+  processChunk(chunk, timestampMs) {
+    const energy = this.calculateEnergy(chunk);
+    const isSpeech = energy > this.energyThreshold;
+    if (isSpeech) {
+      this.silenceStartMs = null;
+      return false;
+    }
+    if (this.silenceStartMs === null) {
+      this.silenceStartMs = timestampMs;
+    }
+    const silenceDurationMs = timestampMs - this.silenceStartMs;
+    return silenceDurationMs >= this.silenceThresholdMs;
+  }
+  reset() {
+    this.silenceStartMs = null;
+  }
+  calculateEnergy(chunk) {
+    if (chunk.length < 2)
+      return 0;
+    let sum = 0;
+    const sampleCount = Math.floor(chunk.length / 2);
+    for (let i = 0;i < chunk.length - 1; i += 2) {
+      const low = chunk[i] ?? 0;
+      const high = chunk[i + 1] ?? 0;
+      const sample = (low | high << 8) << 16 >> 16;
+      const normalized = sample / 32768;
+      sum += normalized * normalized;
+    }
+    return Math.sqrt(sum / sampleCount);
+  }
+}
+export {
+  TurnDetector
+};