@contractspec/lib.voice 0.2.0

package/dist/index.js

@@ -0,0 +1,1071 @@
+// @bun
+// 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
+    };
+  }
+}
+// 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;
+  }
+}
+// src/tts/pace-analyzer.ts
+var CONTENT_TYPE_PACING = {
+  intro: {
+    rate: 0.95,
+    emphasis: "normal",
+    tone: "authoritative",
+    leadingSilenceMs: 0,
+    trailingSilenceMs: 500
+  },
+  problem: {
+    rate: 0.9,
+    emphasis: "strong",
+    tone: "urgent",
+    leadingSilenceMs: 300,
+    trailingSilenceMs: 500
+  },
+  solution: {
+    rate: 1,
+    emphasis: "normal",
+    tone: "calm",
+    leadingSilenceMs: 300,
+    trailingSilenceMs: 500
+  },
+  metric: {
+    rate: 0.85,
+    emphasis: "strong",
+    tone: "excited",
+    leadingSilenceMs: 300,
+    trailingSilenceMs: 600
+  },
+  cta: {
+    rate: 0.9,
+    emphasis: "strong",
+    tone: "authoritative",
+    leadingSilenceMs: 400,
+    trailingSilenceMs: 0
+  },
+  transition: {
+    rate: 1.1,
+    emphasis: "reduced",
+    tone: "neutral",
+    leadingSilenceMs: 200,
+    trailingSilenceMs: 300
+  }
+};
+
+class PaceAnalyzer {
+  analyze(segments, baseRate = 1) {
+    return segments.map((segment) => {
+      const defaults = CONTENT_TYPE_PACING[segment.contentType];
+      return {
+        sceneId: segment.sceneId,
+        rate: defaults.rate * baseRate,
+        emphasis: defaults.emphasis,
+        tone: defaults.tone,
+        leadingSilenceMs: defaults.leadingSilenceMs,
+        trailingSilenceMs: defaults.trailingSilenceMs
+      };
+    });
+  }
+  getDefaults(contentType) {
+    return { ...CONTENT_TYPE_PACING[contentType] };
+  }
+}
+
+// src/tts/emphasis-planner.ts
+class EmphasisPlanner {
+  llm;
+  model;
+  paceAnalyzer;
+  constructor(options) {
+    this.llm = options?.llm;
+    this.model = options?.model;
+    this.paceAnalyzer = new PaceAnalyzer;
+  }
+  async plan(segments, baseRate = 1) {
+    if (!this.llm) {
+      return this.paceAnalyzer.analyze(segments, baseRate);
+    }
+    try {
+      return await this.planWithLlm(segments, baseRate);
+    } catch {
+      return this.paceAnalyzer.analyze(segments, baseRate);
+    }
+  }
+  async planWithLlm(segments, baseRate) {
+    if (!this.llm) {
+      return this.paceAnalyzer.analyze(segments, baseRate);
+    }
+    const response = await this.llm.chat([
+      {
+        role: "system",
+        content: [
+          {
+            type: "text",
+            text: [
+              "You are a voice director planning emphasis and pacing for TTS narration.",
+              "For each segment, return a JSON array of directives.",
+              "Each directive has: sceneId, rate (0.7-1.3), emphasis (reduced|normal|strong),",
+              "tone (neutral|urgent|excited|calm|authoritative), leadingSilenceMs, trailingSilenceMs.",
+              "Return ONLY a JSON array, no other text."
+            ].join(`
+`)
+          }
+        ]
+      },
+      {
+        role: "user",
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(segments.map((s) => ({
+              sceneId: s.sceneId,
+              text: s.text,
+              contentType: s.contentType
+            })))
+          }
+        ]
+      }
+    ], { model: this.model, temperature: 0.3, responseFormat: "json" });
+    const text = response.message.content.find((p) => p.type === "text");
+    if (!text || text.type !== "text") {
+      return this.paceAnalyzer.analyze(segments, baseRate);
+    }
+    const parsed = JSON.parse(text.text);
+    return parsed.map((d) => ({
+      ...d,
+      rate: d.rate * baseRate
+    }));
+  }
+}
+
+// src/tts/segment-synthesizer.ts
+class SegmentSynthesizer {
+  tts;
+  constructor(tts) {
+    this.tts = tts;
+  }
+  async synthesizeAll(segments, voice, directives) {
+    const directiveMap = new Map(directives.map((d) => [d.sceneId, d]));
+    const results = await Promise.all(segments.map((segment) => this.synthesizeOne(segment, voice, directiveMap.get(segment.sceneId))));
+    return results;
+  }
+  async synthesizeOne(segment, voice, directive) {
+    const result = await this.tts.synthesize({
+      text: segment.text,
+      voiceId: voice.voiceId,
+      language: voice.language,
+      style: voice.style,
+      stability: voice.stability,
+      rate: directive?.rate,
+      emphasis: directive?.emphasis
+    });
+    return {
+      sceneId: segment.sceneId,
+      audio: result.audio,
+      durationMs: result.audio.durationMs ?? 0,
+      wordTimings: result.wordTimings?.map((wt) => ({
+        word: wt.word,
+        startMs: wt.startMs,
+        endMs: wt.endMs
+      }))
+    };
+  }
+}
+
+// src/tts/audio-assembler.ts
+class AudioAssembler {
+  concatenator = new AudioConcatenator;
+  silenceGenerator = new SilenceGenerator;
+  assemble(segments, directives, defaultPauseMs = 500) {
+    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
+      };
+    }
+    const directiveMap = new Map(directives.map((d) => [d.sceneId, d]));
+    const reference = firstSegment.audio;
+    const parts = [];
+    for (let i = 0;i < segments.length; i++) {
+      const segment = segments[i];
+      if (!segment) {
+        continue;
+      }
+      const directive = directiveMap.get(segment.sceneId);
+      const leadingSilenceMs = directive?.leadingSilenceMs ?? 0;
+      if (leadingSilenceMs > 0) {
+        parts.push(this.silenceGenerator.generate(leadingSilenceMs, reference.format, reference.sampleRateHz, reference.channels ?? 1));
+      }
+      parts.push(segment.audio);
+      const trailingSilenceMs = directive?.trailingSilenceMs ?? (i < segments.length - 1 ? defaultPauseMs : 0);
+      if (trailingSilenceMs > 0) {
+        parts.push(this.silenceGenerator.generate(trailingSilenceMs, reference.format, reference.sampleRateHz, reference.channels ?? 1));
+      }
+    }
+    return this.concatenator.concatenate(parts);
+  }
+}
+
+// src/tts/voice-synthesizer.ts
+class VoiceSynthesizer {
+  segmentSynthesizer;
+  emphasisPlanner;
+  audioAssembler = new AudioAssembler;
+  durationEstimator = new DurationEstimator;
+  paceAnalyzer = new PaceAnalyzer;
+  options;
+  constructor(options) {
+    this.options = options;
+    this.segmentSynthesizer = new SegmentSynthesizer(options.tts);
+    this.emphasisPlanner = new EmphasisPlanner({
+      llm: options.llm,
+      model: options.model
+    });
+  }
+  async synthesize(brief) {
+    const script = this.buildScript(brief);
+    return this.executePipeline(script, brief.voice, brief.pacing);
+  }
+  async synthesizeForVideo(brief) {
+    const script = this.buildScriptFromScenePlan(brief);
+    return this.executePipeline(script, brief.voice, brief.pacing, brief.fps);
+  }
+  async executePipeline(script, voice, pacing, fps) {
+    const projectId = generateProjectId();
+    const baseRate = pacing?.baseRate ?? 1;
+    const pacingDirectives = await this.emphasisPlanner.plan(script.segments, baseRate);
+    const synthesized = await this.segmentSynthesizer.synthesizeAll(script.segments, voice, pacingDirectives);
+    const pauseMs = pacing?.segmentPauseMs ?? 500;
+    const assembledAudio = this.audioAssembler.assemble(synthesized, pacingDirectives, pauseMs);
+    const effectiveFps = fps ?? this.options.fps ?? 30;
+    const breathingRoomFactor = pacing?.breathingRoomFactor ?? 1.15;
+    const timingMap = this.buildTimingMap(synthesized, effectiveFps, breathingRoomFactor);
+    return {
+      id: projectId,
+      script,
+      pacingDirectives,
+      segments: synthesized,
+      assembledAudio,
+      timingMap
+    };
+  }
+  buildScript(brief) {
+    const segments = [];
+    const introText = `${brief.content.title}. ${brief.content.summary}`;
+    segments.push({
+      sceneId: "intro",
+      text: introText,
+      estimatedDurationSeconds: this.durationEstimator.estimateSeconds(introText),
+      contentType: "intro"
+    });
+    if (brief.content.problems.length > 0) {
+      const text = brief.content.problems.join(". ");
+      segments.push({
+        sceneId: "problems",
+        text,
+        estimatedDurationSeconds: this.durationEstimator.estimateSeconds(text),
+        contentType: "problem"
+      });
+    }
+    if (brief.content.solutions.length > 0) {
+      const text = brief.content.solutions.join(". ");
+      segments.push({
+        sceneId: "solutions",
+        text,
+        estimatedDurationSeconds: this.durationEstimator.estimateSeconds(text),
+        contentType: "solution"
+      });
+    }
+    if (brief.content.metrics && brief.content.metrics.length > 0) {
+      const text = brief.content.metrics.join(". ");
+      segments.push({
+        sceneId: "metrics",
+        text,
+        estimatedDurationSeconds: this.durationEstimator.estimateSeconds(text),
+        contentType: "metric"
+      });
+    }
+    if (brief.content.callToAction) {
+      segments.push({
+        sceneId: "cta",
+        text: brief.content.callToAction,
+        estimatedDurationSeconds: this.durationEstimator.estimateSeconds(brief.content.callToAction),
+        contentType: "cta"
+      });
+    }
+    const fullText = segments.map((s) => s.text).join(" ");
+    const estimatedDurationSeconds = segments.reduce((sum, s) => sum + s.estimatedDurationSeconds, 0);
+    return { fullText, segments, estimatedDurationSeconds };
+  }
+  buildScriptFromScenePlan(brief) {
+    const segments = brief.scenePlan.scenes.filter((scene) => scene.narrationText).map((scene) => {
+      const text = scene.narrationText ?? "";
+      return {
+        sceneId: scene.id,
+        text,
+        estimatedDurationSeconds: this.durationEstimator.estimateSeconds(text),
+        contentType: "intro"
+      };
+    });
+    const fullText = segments.map((s) => s.text).join(" ");
+    const estimatedDurationSeconds = segments.reduce((sum, s) => sum + s.estimatedDurationSeconds, 0);
+    return { fullText, segments, estimatedDurationSeconds };
+  }
+  buildTimingMap(segments, fps, breathingRoomFactor) {
+    const timingSegments = segments.map((seg) => {
+      const durationInFrames = Math.ceil(seg.durationMs / 1000 * fps);
+      return {
+        sceneId: seg.sceneId,
+        durationMs: seg.durationMs,
+        durationInFrames,
+        recommendedSceneDurationInFrames: Math.ceil(durationInFrames * breathingRoomFactor),
+        wordTimings: seg.wordTimings?.map((wt) => ({
+          word: wt.word,
+          startMs: wt.startMs,
+          endMs: wt.endMs
+        }))
+      };
+    });
+    const totalDurationMs = segments.reduce((sum, s) => sum + s.durationMs, 0);
+    return { totalDurationMs, segments: timingSegments, fps };
+  }
+}
+function generateProjectId() {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).slice(2, 8);
+  return `tts_${timestamp}_${random}`;
+}
+// src/stt/segment-splitter.ts
+class SegmentSplitter {
+  static DEFAULT_MAX_CHUNK_MS = 5 * 60 * 1000;
+  split(audio, maxChunkMs = SegmentSplitter.DEFAULT_MAX_CHUNK_MS) {
+    const totalDurationMs = audio.durationMs ?? this.estimateDurationMs(audio);
+    if (totalDurationMs <= maxChunkMs) {
+      return [audio];
+    }
+    const chunks = [];
+    const bytesPerMs = audio.data.length / Math.max(totalDurationMs, 1);
+    let offsetMs = 0;
+    while (offsetMs < totalDurationMs) {
+      const chunkDurationMs = Math.min(maxChunkMs, totalDurationMs - offsetMs);
+      const startByte = Math.floor(offsetMs * bytesPerMs);
+      const endByte = Math.floor((offsetMs + chunkDurationMs) * bytesPerMs);
+      chunks.push({
+        data: audio.data.slice(startByte, endByte),
+        format: audio.format,
+        sampleRateHz: audio.sampleRateHz,
+        durationMs: chunkDurationMs,
+        channels: audio.channels
+      });
+      offsetMs += chunkDurationMs;
+    }
+    return chunks;
+  }
+  estimateDurationMs(audio) {
+    const bytesPerSample = 2;
+    const channels = audio.channels ?? 1;
+    const totalSamples = audio.data.length / (bytesPerSample * channels);
+    return Math.ceil(totalSamples / audio.sampleRateHz * 1000);
+  }
+}
+
+// src/stt/diarization-mapper.ts
+class DiarizationMapper {
+  map(segments, labelPrefix = "Speaker") {
+    const speakerOrder = [];
+    const speakerStats = new Map;
+    for (const seg of segments) {
+      if (seg.speakerId && !speakerOrder.includes(seg.speakerId)) {
+        speakerOrder.push(seg.speakerId);
+        speakerStats.set(seg.speakerId, {
+          segmentCount: 0,
+          totalSpeakingMs: 0
+        });
+      }
+    }
+    const labeledSegments = segments.map((seg) => {
+      if (!seg.speakerId)
+        return seg;
+      const index = speakerOrder.indexOf(seg.speakerId);
+      const label = `${labelPrefix} ${index + 1}`;
+      const stats = speakerStats.get(seg.speakerId);
+      if (!stats) {
+        return { ...seg, speakerLabel: label };
+      }
+      stats.segmentCount += 1;
+      stats.totalSpeakingMs += seg.endMs - seg.startMs;
+      return { ...seg, speakerLabel: label };
+    });
+    const speakers = speakerOrder.map((id, index) => {
+      const stats = speakerStats.get(id);
+      return {
+        id,
+        label: `${labelPrefix} ${index + 1}`,
+        segmentCount: stats?.segmentCount ?? 0,
+        totalSpeakingMs: stats?.totalSpeakingMs ?? 0
+      };
+    });
+    return { segments: labeledSegments, speakers };
+  }
+}
+
+// src/stt/subtitle-formatter.ts
+class SubtitleFormatter {
+  toSRT(segments) {
+    return segments.map((seg, i) => {
+      const start = this.formatTimeSRT(seg.startMs);
+      const end = this.formatTimeSRT(seg.endMs);
+      const label = seg.speakerLabel ? `[${seg.speakerLabel}] ` : "";
+      return `${i + 1}
+${start} --> ${end}
+${label}${seg.text}`;
+    }).join(`
+
+`);
+  }
+  toVTT(segments) {
+    const header = `WEBVTT
+
+`;
+    const cues = segments.map((seg, i) => {
+      const start = this.formatTimeVTT(seg.startMs);
+      const end = this.formatTimeVTT(seg.endMs);
+      const label = seg.speakerLabel ? `<v ${seg.speakerLabel}>` : "";
+      return `${i + 1}
+${start} --> ${end}
+${label}${seg.text}`;
+    }).join(`
+
+`);
+    return header + cues;
+  }
+  formatTimeSRT(ms) {
+    const hours = Math.floor(ms / 3600000);
+    const minutes = Math.floor(ms % 3600000 / 60000);
+    const seconds = Math.floor(ms % 60000 / 1000);
+    const millis = ms % 1000;
+    return `${this.pad(hours, 2)}:${this.pad(minutes, 2)}:${this.pad(seconds, 2)},${this.pad(millis, 3)}`;
+  }
+  formatTimeVTT(ms) {
+    const hours = Math.floor(ms / 3600000);
+    const minutes = Math.floor(ms % 3600000 / 60000);
+    const seconds = Math.floor(ms % 60000 / 1000);
+    const millis = ms % 1000;
+    return `${this.pad(hours, 2)}:${this.pad(minutes, 2)}:${this.pad(seconds, 2)}.${this.pad(millis, 3)}`;
+  }
+  pad(value, length) {
+    return value.toString().padStart(length, "0");
+  }
+}
+
+// src/stt/transcriber.ts
+class Transcriber {
+  stt;
+  segmentSplitter = new SegmentSplitter;
+  diarizationMapper = new DiarizationMapper;
+  subtitleFormatter = new SubtitleFormatter;
+  constructor(options) {
+    this.stt = options.stt;
+  }
+  async transcribe(brief) {
+    const projectId = generateProjectId2();
+    const chunks = this.segmentSplitter.split(brief.audio);
+    const allSegments = [];
+    let fullText = "";
+    let totalDurationMs = 0;
+    let offsetMs = 0;
+    for (const chunk of chunks) {
+      const result = await this.stt.transcribe({
+        audio: chunk,
+        language: brief.language,
+        diarize: brief.diarize,
+        speakerCount: brief.speakerCount,
+        wordTimestamps: true,
+        vocabularyHints: brief.vocabularyHints
+      });
+      const offsetSegments = result.segments.map((seg) => ({
+        text: seg.text,
+        startMs: seg.startMs + offsetMs,
+        endMs: seg.endMs + offsetMs,
+        speakerId: seg.speakerId,
+        speakerName: seg.speakerName,
+        confidence: seg.confidence
+      }));
+      allSegments.push(...offsetSegments);
+      fullText += (fullText ? " " : "") + result.text;
+      totalDurationMs += result.durationMs;
+      offsetMs += chunk.durationMs ?? 0;
+    }
+    let mappedSegments = allSegments;
+    let speakers;
+    if (brief.diarize) {
+      const mapping = this.diarizationMapper.map(allSegments);
+      mappedSegments = mapping.segments;
+      speakers = mapping.speakers;
+    }
+    const transcript = {
+      text: fullText,
+      segments: mappedSegments,
+      language: brief.language ?? "en",
+      durationMs: totalDurationMs
+    };
+    let subtitles;
+    const format = brief.subtitleFormat ?? "none";
+    if (format === "srt") {
+      subtitles = this.subtitleFormatter.toSRT(mappedSegments);
+    } else if (format === "vtt") {
+      subtitles = this.subtitleFormatter.toVTT(mappedSegments);
+    }
+    return {
+      id: projectId,
+      transcript,
+      subtitles,
+      speakers
+    };
+  }
+  async* transcribeStream(audio, options) {
+    if (!this.stt.transcribeStream) {
+      throw new Error("Streaming transcription not supported by the current STT provider");
+    }
+    const stream = this.stt.transcribeStream(audio, {
+      language: options?.language,
+      diarize: options?.diarize,
+      speakerCount: options?.speakerCount,
+      wordTimestamps: true,
+      vocabularyHints: options?.vocabularyHints
+    });
+    for await (const segment of stream) {
+      yield {
+        text: segment.text,
+        startMs: segment.startMs,
+        endMs: segment.endMs,
+        speakerId: segment.speakerId,
+        speakerLabel: segment.speakerName,
+        confidence: segment.confidence
+      };
+    }
+  }
+}
+function generateProjectId2() {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).slice(2, 8);
+  return `stt_${timestamp}_${random}`;
+}
+// src/sync/timing-calculator.ts
+class TimingCalculator {
+  calculate(segments, fps, breathingRoomFactor = 1.15) {
+    const timingSegments = segments.map((seg) => {
+      const durationInFrames = Math.ceil(seg.durationMs / 1000 * fps);
+      const recommendedSceneDurationInFrames = Math.ceil(durationInFrames * breathingRoomFactor);
+      const wordTimings = seg.wordTimings?.map((wt) => ({
+        word: wt.word,
+        startMs: wt.startMs,
+        endMs: wt.endMs
+      }));
+      return {
+        sceneId: seg.sceneId,
+        durationMs: seg.durationMs,
+        durationInFrames,
+        recommendedSceneDurationInFrames,
+        wordTimings
+      };
+    });
+    const totalDurationMs = segments.reduce((sum, s) => sum + s.durationMs, 0);
+    return {
+      totalDurationMs,
+      segments: timingSegments,
+      fps
+    };
+  }
+  recalculateForFps(timingMap, newFps) {
+    const segments = timingMap.segments.map((seg) => {
+      const durationInFrames = Math.ceil(seg.durationMs / 1000 * newFps);
+      const ratio = seg.recommendedSceneDurationInFrames / Math.max(seg.durationInFrames, 1);
+      return {
+        ...seg,
+        durationInFrames,
+        recommendedSceneDurationInFrames: Math.ceil(durationInFrames * ratio)
+      };
+    });
+    return {
+      ...timingMap,
+      segments,
+      fps: newFps
+    };
+  }
+}
+
+// src/sync/scene-adapter.ts
+class SceneAdapter {
+  durationEstimator = new DurationEstimator;
+  adapt(scenePlan) {
+    const scenesWithNarration = scenePlan.scenes.filter((s) => s.narrationText && s.narrationText.trim().length > 0);
+    const segments = scenesWithNarration.map((scene, index) => {
+      const text = scene.narrationText ?? "";
+      return {
+        sceneId: scene.id,
+        text,
+        estimatedDurationSeconds: this.durationEstimator.estimateSeconds(text),
+        contentType: this.inferContentType(index, scenesWithNarration.length)
+      };
+    });
+    const fullText = segments.map((s) => s.text).join(" ");
+    const estimatedDurationSeconds = segments.reduce((sum, s) => sum + s.estimatedDurationSeconds, 0);
+    return { fullText, segments, estimatedDurationSeconds };
+  }
+  inferContentType(index, total) {
+    if (index === 0)
+      return "intro";
+    if (index === total - 1)
+      return "cta";
+    if (index === 1 && total > 3)
+      return "problem";
+    if (index === total - 2 && total > 3)
+      return "metric";
+    return "solution";
+  }
+}
+
+// src/sync/duration-negotiator.ts
+class DurationNegotiator {
+  static UPPER_THRESHOLD = 1.1;
+  static LOWER_THRESHOLD = 0.7;
+  static MAX_RATE = 1.3;
+  static MIN_RATE = 0.8;
+  negotiate(timingMap, sceneDurations) {
+    const adjustments = [];
+    const updatedSegments = timingMap.segments.map((seg) => {
+      const originalSceneDuration = sceneDurations.get(seg.sceneId);
+      if (originalSceneDuration === undefined) {
+        adjustments.push({
+          sceneId: seg.sceneId,
+          originalSceneDurationInFrames: seg.recommendedSceneDurationInFrames,
+          voiceDurationInFrames: seg.durationInFrames,
+          action: "no_change",
+          finalSceneDurationInFrames: seg.recommendedSceneDurationInFrames
+        });
+        return seg;
+      }
+      const ratio = seg.durationInFrames / originalSceneDuration;
+      if (ratio > DurationNegotiator.UPPER_THRESHOLD) {
+        const suggestedRate = Math.min(ratio, DurationNegotiator.MAX_RATE);
+        adjustments.push({
+          sceneId: seg.sceneId,
+          originalSceneDurationInFrames: originalSceneDuration,
+          voiceDurationInFrames: seg.durationInFrames,
+          action: ratio > DurationNegotiator.MAX_RATE ? "extend_scene" : "suggest_rate_change",
+          suggestedRate,
+          finalSceneDurationInFrames: seg.recommendedSceneDurationInFrames
+        });
+        return seg;
+      }
+      if (ratio < DurationNegotiator.LOWER_THRESHOLD) {
+        const suggestedRate = Math.max(ratio, DurationNegotiator.MIN_RATE);
+        adjustments.push({
+          sceneId: seg.sceneId,
+          originalSceneDurationInFrames: originalSceneDuration,
+          voiceDurationInFrames: seg.durationInFrames,
+          action: "pad_silence",
+          suggestedRate,
+          finalSceneDurationInFrames: originalSceneDuration
+        });
+        return {
+          ...seg,
+          recommendedSceneDurationInFrames: originalSceneDuration
+        };
+      }
+      adjustments.push({
+        sceneId: seg.sceneId,
+        originalSceneDurationInFrames: originalSceneDuration,
+        voiceDurationInFrames: seg.durationInFrames,
+        action: "no_change",
+        finalSceneDurationInFrames: seg.recommendedSceneDurationInFrames
+      });
+      return seg;
+    });
+    return {
+      timingMap: {
+        ...timingMap,
+        segments: updatedSegments
+      },
+      adjustments
+    };
+  }
+}
+export {
+  VoiceSynthesizer,
+  VoiceSessionManager,
+  TurnDetector,
+  TranscriptBuilder,
+  Transcriber,
+  TimingCalculator,
+  SubtitleFormatter,
+  SilenceGenerator,
+  SegmentSynthesizer,
+  SegmentSplitter,
+  SceneAdapter,
+  ResponseOrchestrator,
+  PaceAnalyzer,
+  FormatConverter,
+  EmphasisPlanner,
+  DurationNegotiator,
+  DurationEstimator,
+  DiarizationMapper,
+  AudioConcatenator,
+  AudioAssembler
+};