Voice library
A persistent voice library for @kucukkanat/tts: voices live in IndexedDB, come with two bundled demo voices, and remember their encodings so a saved voice speaks instantly after a reload.
@kucukkanat/voices · source
- Any recording in, a clean reference clip out: cropped to the best 5–10 s, zero-crossing cuts, peak-normalised.
- Records plug straight into TTS:
tts.speak(text, { voice: record }). - Your metadata, typed: colours, emoji, tags —
createVoiceStore<{ color: string }>(). - Reactive: a stable
snapshot+subscribe(ready foruseSyncExternalStore, or useuseVoicesfrom@kucukkanat/speech-react).
bun add @kucukkanat/voices @kucukkanat/tts
Quick start
import { createTTS } from "@kucukkanat/tts";
import { createVoiceStore } from "@kucukkanat/voices";
const voices = createVoiceStore();
// Encodings are saved with the voices, so they're learned once, not on every page load.
const tts = createTTS({ cache: voices.conditioningCache });
const list = await voices.list(); // the demo voices "Aria" and "Orion", then yours (newest first)
const aria = list.find((v) => v.name === "Aria");
if (aria) await tts.speak("Hello, I'm one of the demo voices.", { voice: aria });
Add a voice
create() takes any recording (URL, File/Blob, bytes or PCM) and turns it into a reference clip:
import { startRecording } from "@kucukkanat/speech-audio";
import { createVoiceStore } from "@kucukkanat/voices";
const voices = createVoiceStore();
// From a file picker…
const file = document.querySelector<HTMLInputElement>("input[type=file]")?.files?.[0];
if (file) await voices.create({ name: "Narrator", audio: file, meta: {} });
// …or from the microphone: read a sentence or two, naturally.
const recording = await startRecording({ maxSeconds: 12 });
setTimeout(() => recording.stop(), 8000);
const me = await voices.create({ name: "Me", audio: await recording.done, meta: {} });
console.log(`${me.name}: ${me.seconds.toFixed(1)} s clip`);
Cropping options: crop: "auto" (default, the most energetic stretch of up to 10 s), crop: false (keep everything up
to maxSeconds), or crop: { start, end } in seconds — for example from your own waveform selector.
Your own metadata
import { createVoiceStore } from "@kucukkanat/voices";
interface Look {
color: string;
emoji?: string;
}
// With custom metadata, say what the demo voices should get — or `demoVoices: false` to skip them.
const voices = createVoiceStore<Look>({
name: "my-app-voices",
demoVoices: (demo) => ({ color: demo.name === "Aria" ? "#ff4f9a" : "#6c5cff" }),
});
const [first] = await voices.list();
if (first) {
console.log(first.meta.color);
await voices.update(first.id, { meta: { color: "#00c2a8", emoji: "🎙️" } });
}
Remove, with undo
import { createVoiceStore } from "@kucukkanat/voices";
const voices = createVoiceStore();
const [, , mine] = await voices.list();
if (mine) {
const removed = await voices.remove(mine.id); // also drops its cached encodings
await voices.restore(removed); // "Undo": back with the same id
}
Demo voices can’t be removed (built-in-read-only).
React to changes
import { createVoiceStore } from "@kucukkanat/voices";
const voices = createVoiceStore();
const unsubscribe = voices.subscribe(({ voices: list, loading, error }) => {
if (error) console.error(error.code, error.message); // e.g. db-blocked, quota-exceeded
else if (!loading) console.log(list.map((v) => v.name));
});
await voices.ready;
unsubscribe();
Clip utilities
The processing behind create() is exported for custom editors:
import { decodeAudio } from "@kucukkanat/speech-audio";
import { bestWindow, CLIP_SECONDS, computePeaks, prepareClip } from "@kucukkanat/voices";
const { pcm, sampleRate } = await decodeAudio("/interview.mp3");
const peaks = computePeaks(pcm, 400); // min/max pairs for drawing a waveform
const suggestion = bestWindow(pcm, sampleRate, CLIP_SECONDS.idealMax); // { start, end } in seconds
const clip = await prepareClip({ pcm, sampleRate }, { crop: suggestion });
console.log(peaks.length, clip.seconds, clip.wav.type); // 800, ≤10, "audio/wav"
Storage notes
- One IndexedDB database per store (
name, default"kucukkanat-voices") with two object stores:voicesandconditioning(encoded voices, keyed by voice, model and encoding version). - Opening a database that another tab keeps open at an older version reports
db-blockedinsnapshot.erroruntil that tab closes. - Databases created by the original Voice Lab app (a
personasstore) are migrated in place: colours and emoji move intometa. - The demo voices are bundled audio files referenced with
new URL(…, import.meta.url); every mainstream bundler serves them automatically. Passdemosto ship your own starter voices instead.