@contractspec/lib.voice 0.2.0

package/dist/browser/sync/index.js

@@ -0,0 +1,165 @@
+// 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/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 {
+  TimingCalculator,
+  SceneAdapter,
+  DurationNegotiator
+};

package/dist/browser/sync/scene-adapter.js

@@ -0,0 +1,52 @@
+// 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/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";
+  }
+}
+export {
+  SceneAdapter
+};

package/dist/browser/sync/timing-calculator.js

@@ -0,0 +1,46 @@
+// 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
+    };
+  }
+}
+export {
+  TimingCalculator
+};

package/dist/browser/tts/audio-assembler.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/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/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);
+  }
+}
+export {
+  AudioAssembler
+};

package/dist/browser/tts/emphasis-planner.js

@@ -0,0 +1,134 @@
+// 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
+    }));
+  }
+}
+export {
+  EmphasisPlanner
+};