@segnavia/voice 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 modstudio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+import { Word } from "@segnavia/format";
+//#region src/index.d.ts
+export interface Speech {
+  words: Word[];
+  durationMs: number;
+  audio: {
+    bytes: Uint8Array;
+    extension: string;
+  } | null;
+}
+export interface VoiceProvider {
+  id: string;
+  synthesize(text: string, voice?: string): Promise<Speech>;
+}
+export declare function splitWords(text: string): string[];
+export declare function wordsFromCharacters(characters: string[], startsSec: number[], endsSec: number[]): Word[];
+export declare function pacedProvider(options?: {
+  wordsPerMinute?: number;
+}): VoiceProvider;
+export declare function elevenLabsProvider(options: {
+  apiKey: () => string;
+  voice: string;
+  model?: string;
+}): VoiceProvider;
+export declare function alignedProvider(options: {
+  id: string;
+  speak: (text: string, voice?: string) => Promise<{
+    bytes: Uint8Array;
+    extension: string;
+    durationMs: number;
+  }>;
+  align: (audio: Uint8Array, text: string) => Promise<Word[]>;
+}): VoiceProvider;
+export interface Narrated {
+  words: Word[];
+  durationMs: number;
+  audio: string | null;
+}
+export declare function narrate(provider: VoiceProvider, text: string, options: {
+  cacheDirectory: string;
+  voice?: string;
+}): Promise<Narrated>;
+//#endregion

package/dist/index.js

@@ -0,0 +1,128 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+//#region src/index.ts
+function splitWords(text) {
+	return text.split(/\s+/).filter(Boolean);
+}
+function wordsFromCharacters(characters, startsSec, endsSec) {
+	const words = [];
+	let current = null;
+	characters.forEach((character, index) => {
+		const start = Math.round((startsSec[index] ?? 0) * 1e3);
+		const end = Math.round((endsSec[index] ?? 0) * 1e3);
+		if (/\s/.test(character)) {
+			if (current) words.push(current);
+			current = null;
+			return;
+		}
+		if (current) {
+			current.text += character;
+			current.endMs = end;
+		} else current = {
+			text: character,
+			startMs: start,
+			endMs: end
+		};
+	});
+	if (current) words.push(current);
+	return words;
+}
+const SENTENCE_END = /[.!?\u05C3\u061F\u06D4\u0964]["'\u05F4\u201D)]*$/u;
+const CLAUSE_END = /[,;:\u060C\u061B\u05C0]["'\u05F4\u201D)]*$/u;
+function pacedProvider(options = {}) {
+	const msPerChar = 6e4 / ((options.wordsPerMinute ?? 160) * 5.5);
+	return {
+		id: `paced-${options.wordsPerMinute ?? 160}`,
+		async synthesize(text) {
+			let clock = 0;
+			return {
+				words: splitWords(text).map((word) => {
+					const startMs = clock;
+					const endMs = startMs + Math.max(140, word.length * msPerChar);
+					clock = endMs + (SENTENCE_END.test(word) ? 350 : CLAUSE_END.test(word) ? 150 : 60);
+					return {
+						text: word,
+						startMs: Math.round(startMs),
+						endMs: Math.round(endMs)
+					};
+				}),
+				durationMs: Math.round(clock + 400),
+				audio: null
+			};
+		}
+	};
+}
+function elevenLabsProvider(options) {
+	return {
+		id: `elevenlabs-${options.model ?? "eleven_multilingual_v2"}-${options.voice}`,
+		async synthesize(text, voice = options.voice) {
+			const response = await fetch(`https://api.elevenlabs.io/v1/text-to-speech/${voice}/with-timestamps`, {
+				method: "POST",
+				headers: {
+					"xi-api-key": options.apiKey(),
+					"content-type": "application/json"
+				},
+				body: JSON.stringify({
+					text,
+					model_id: options.model ?? "eleven_multilingual_v2"
+				})
+			});
+			if (!response.ok) throw new Error(`ElevenLabs refused the synthesis: ${response.status} ${await response.text()}`);
+			const body = await response.json();
+			const { characters, character_start_times_seconds: starts, character_end_times_seconds: ends } = body.alignment;
+			return {
+				words: wordsFromCharacters(characters, starts, ends),
+				durationMs: Math.round((ends.at(-1) ?? 0) * 1e3) + 300,
+				audio: {
+					bytes: Buffer.from(body.audio_base64, "base64"),
+					extension: "mp3"
+				}
+			};
+		}
+	};
+}
+function alignedProvider(options) {
+	return {
+		id: options.id,
+		async synthesize(text, voice) {
+			const audio = await options.speak(text, voice);
+			const words = await options.align(audio.bytes, text);
+			const expected = splitWords(text).length;
+			if (words.length !== expected) throw new Error(`The aligner placed ${words.length} words; the narration has ${expected}.`);
+			return {
+				words,
+				durationMs: audio.durationMs,
+				audio: {
+					bytes: audio.bytes,
+					extension: audio.extension
+				}
+			};
+		}
+	};
+}
+async function narrate(provider, text, options) {
+	const hash = createHash("sha256").update(JSON.stringify([
+		provider.id,
+		options.voice ?? null,
+		text
+	])).digest("hex").slice(0, 16);
+	mkdirSync(options.cacheDirectory, { recursive: true });
+	const timings = path.join(options.cacheDirectory, `${hash}.json`);
+	if (existsSync(timings)) return JSON.parse(readFileSync(timings, "utf8"));
+	const speech = await provider.synthesize(text, options.voice);
+	let audio = null;
+	if (speech.audio) {
+		audio = `${hash}.${speech.audio.extension}`;
+		writeFileSync(path.join(options.cacheDirectory, audio), speech.audio.bytes);
+	}
+	const narrated = {
+		words: speech.words,
+		durationMs: speech.durationMs,
+		audio
+	};
+	writeFileSync(timings, JSON.stringify(narrated));
+	return narrated;
+}
+//#endregion
+export { alignedProvider, elevenLabsProvider, narrate, pacedProvider, splitWords, wordsFromCharacters };

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@segnavia/voice",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/modstudio/segnavia.git",
+    "directory": "packages/voice"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "@segnavia/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@segnavia/format": "0.2.0"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.