@contractspec/lib.voice 0.2.0

package/dist/audio/audio-concatenator.d.ts

@@ -0,0 +1,15 @@
+import type { AudioData } from '../types';
+/**
+ * Concatenate multiple AudioData segments into a single buffer.
+ *
+ * All segments must share the same format and sample rate.
+ * Use FormatConverter first if segments have mixed formats.
+ */
+export declare class AudioConcatenator {
+    /**
+     * Concatenate audio segments in order.
+     *
+     * @throws If segments have mismatched formats or sample rates
+     */
+    concatenate(segments: AudioData[]): AudioData;
+}

package/dist/audio/audio-concatenator.js

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

package/dist/audio/duration-estimator.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Estimate speech duration from text.
+ *
+ * Uses word count and an assumed speaking rate.
+ * This is a deterministic fallback -- actual duration comes from TTS provider.
+ */
+export declare class DurationEstimator {
+    /** Words per minute at normal speaking rate */
+    private static readonly DEFAULT_WPM;
+    /**
+     * Estimate speaking duration in seconds from text.
+     *
+     * @param text - The text to estimate duration for
+     * @param wordsPerMinute - Speaking rate (default 150 WPM)
+     */
+    estimateSeconds(text: string, wordsPerMinute?: number): number;
+    /**
+     * Estimate speaking duration in milliseconds from text.
+     *
+     * @param text - The text to estimate duration for
+     * @param wordsPerMinute - Speaking rate (default 150 WPM)
+     */
+    estimateMs(text: string, wordsPerMinute?: number): number;
+    /**
+     * Estimate word count from duration.
+     *
+     * @param durationSeconds - Duration in seconds
+     * @param wordsPerMinute - Speaking rate (default 150 WPM)
+     */
+    estimateWordCount(durationSeconds: number, wordsPerMinute?: number): number;
+}

package/dist/audio/duration-estimator.js

@@ -0,0 +1,22 @@
+// @bun
+// 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/audio/format-converter.d.ts

@@ -0,0 +1,17 @@
+import type { AudioData, AudioFormat } from '../types';
+/**
+ * Convert audio data between formats.
+ *
+ * In a real implementation, this would use ffmpeg or a similar tool.
+ * For now, provides passthrough when formats match and throws for
+ * unsupported conversions.
+ */
+export declare class FormatConverter {
+    /**
+     * Convert audio to a target format.
+     * Returns unchanged data if already in the target format.
+     */
+    convert(audio: AudioData, targetFormat: AudioFormat): AudioData;
+    /** Check if a conversion path is supported */
+    isSupported(from: AudioFormat, to: AudioFormat): boolean;
+}

package/dist/audio/format-converter.js

@@ -0,0 +1,28 @@
+// @bun
+// 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/audio/index.d.ts

@@ -0,0 +1,4 @@
+export { FormatConverter } from './format-converter';
+export { SilenceGenerator } from './silence-generator';
+export { AudioConcatenator } from './audio-concatenator';
+export { DurationEstimator } from './duration-estimator';

package/dist/audio/index.js

@@ -0,0 +1,121 @@
+// @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
+    };
+  }
+}
+export {
+  SilenceGenerator,
+  FormatConverter,
+  DurationEstimator,
+  AudioConcatenator
+};

package/dist/audio/silence-generator.d.ts

@@ -0,0 +1,16 @@
+import type { AudioData, AudioFormat } from '../types';
+/**
+ * Generate silence buffers in various audio formats.
+ * Used by AudioAssembler to insert pauses between TTS segments.
+ */
+export declare class SilenceGenerator {
+    /**
+     * Generate a silence buffer of the given duration.
+     *
+     * @param durationMs - Silence duration in milliseconds
+     * @param format - Target audio format
+     * @param sampleRateHz - Sample rate (default 44100)
+     * @param channels - Number of channels (default 1)
+     */
+    generate(durationMs: number, format?: AudioFormat, sampleRateHz?: number, channels?: 1 | 2): AudioData;
+}

package/dist/audio/silence-generator.js

@@ -0,0 +1,20 @@
+// @bun
+// 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/browser/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/browser/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/browser/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/browser/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/browser/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
+};