Skip to main content

loqui_kokoro/
lib.rs

1//! Kokoro-82M text-to-speech, in process.
2//!
3//! Text goes through [`loqui_g2p`] (misaki's English G2P, GPL-free), is cut
4//! into chunks of at most 510 phonemes exactly as Kokoro's own `KPipeline`
5//! cuts it, and each chunk runs through the ONNX export of Kokoro on ONNX
6//! Runtime. The result is 24 kHz mono `f32`, trimmed of edge silence and
7//! peak-normalised the way open-speech delivers it.
8//!
9//! Weights are not bundled. Point [`KokoroModel::load`] at
10//! `onnx/model.onnx` and [`Kokoro::new`] at the `voices/` directory of
11//! `onnx-community/Kokoro-82M-v1.0-ONNX` (Apache-2.0).
12
13mod blend;
14mod chunk;
15mod model;
16pub mod post;
17mod voice;
18
19use std::path::PathBuf;
20use std::sync::OnceLock;
21
22use loqui_g2p::{Dialect, G2p, OovFallback};
23
24pub use blend::Blend;
25pub use chunk::{chunks, tokens_to_ps};
26pub use model::{Device, KokoroModel, SAMPLE_RATE};
27use voice::VoicePacks;
28pub use voice::{MAX_PHONEMES, STYLE_DIM, Voice};
29
30/// Kokoro's default voice, and what OpenAI's `alloy` maps to.
31pub const DEFAULT_VOICE: &str = "af_heart";
32
33/// Kokoro v1.0's American (`a*`) and British (`b*`) voices: the ones this
34/// crate can phonemize for. `f`/`m` in the second letter is the speaker's
35/// voice type as Kokoro labels it.
36pub const ENGLISH_VOICES: &[&str] = &[
37    "af_alloy",
38    "af_aoede",
39    "af_bella",
40    "af_heart",
41    "af_jessica",
42    "af_kore",
43    "af_nicole",
44    "af_nova",
45    "af_river",
46    "af_sarah",
47    "af_sky",
48    "am_adam",
49    "am_echo",
50    "am_eric",
51    "am_fenrir",
52    "am_liam",
53    "am_michael",
54    "am_onyx",
55    "am_puck",
56    "am_santa",
57    "bf_alice",
58    "bf_emma",
59    "bf_isabella",
60    "bf_lily",
61    "bm_daniel",
62    "bm_fable",
63    "bm_george",
64    "bm_lewis",
65];
66
67/// Non-exhaustive so that a new failure need not be a breaking change.
68#[derive(Debug, thiserror::Error)]
69#[non_exhaustive]
70pub enum Error {
71    #[error("model: {0}")]
72    Model(String),
73    #[error("voice: {0}")]
74    Voice(String),
75    #[error("G2P: {0}")]
76    G2p(#[from] loqui_g2p::Error),
77    #[error("speed {0} is outside 0.25..=4.0")]
78    Speed(f32),
79}
80
81/// OpenAI's voice names, mapped the way open-speech maps them, so a client
82/// written against OpenAI keeps working. [`Blend`] applies this to each
83/// part of a spec.
84pub fn resolve_alias(voice: &str) -> &str {
85    match voice {
86        "alloy" => "af_heart",
87        "echo" => "am_adam",
88        "fable" => "bf_emma",
89        "onyx" => "am_michael",
90        "nova" => "af_nova",
91        "shimmer" => "af_bella",
92        other => other,
93    }
94}
95
96/// Text in, audio out. `Send + Sync`: share one per process.
97pub struct Kokoro {
98    model: KokoroModel,
99    fallback: OovFallback,
100    american: OnceLock<G2p>,
101    british: OnceLock<G2p>,
102    packs: VoicePacks,
103}
104
105impl std::fmt::Debug for Kokoro {
106    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
107        f.debug_struct("Kokoro").field("model", &self.model).field("voices_dir", &self.packs.dir()).finish_non_exhaustive()
108    }
109}
110
111impl Kokoro {
112    pub fn new(model: KokoroModel, voices_dir: PathBuf, fallback: OovFallback) -> Self {
113        Self { model, fallback, american: OnceLock::new(), british: OnceLock::new(), packs: VoicePacks::new(voices_dir) }
114    }
115
116    /// Speaks `text` in `voice` at `speed` (0.25 to 4.0). Returns 24 kHz
117    /// mono samples, edge silence trimmed and peak-normalised to 0.95, as
118    /// open-speech returns them. A voice is any pack in the voices
119    /// directory, or a blend of them: `&"af_bella(2)+af_sky(1)".parse()?`.
120    pub fn speak(&self, text: &str, voice: &Blend, speed: f32) -> Result<Vec<f32>, Error> {
121        let audio = self.speak_raw(text, voice, speed)?;
122        Ok(post::normalize_peak(post::trim_silence(&audio, post::TRIM_THRESHOLD), post::PEAK))
123    }
124
125    /// [`Kokoro::speak`] without trimming or normalisation: the model's
126    /// output, chunks concatenated.
127    pub fn speak_raw(&self, text: &str, voice: &Blend, speed: f32) -> Result<Vec<f32>, Error> {
128        if !(0.25..=4.0).contains(&speed) {
129            return Err(Error::Speed(speed));
130        }
131        let dialect = Dialect::for_kokoro_voice(voice.lead())
132            .ok_or_else(|| Error::Voice("only American (a*) and British (b*) voices are supported".into()))?;
133        let style = self.packs.get(voice)?;
134        let mut audio = Vec::new();
135        for ps in self.phoneme_chunks(text, dialect)? {
136            audio.extend(self.model.synthesize(&ps, &style, speed)?);
137        }
138        Ok(audio)
139    }
140
141    /// The phoneme chunks `text` is spoken as. `KPipeline` splits on
142    /// newlines before phonemizing, then chunks each line.
143    pub fn phoneme_chunks(&self, text: &str, dialect: Dialect) -> Result<Vec<String>, Error> {
144        let g2p = self.g2p(dialect)?;
145        Ok(text.trim().split('\n').filter(|line| !line.trim().is_empty()).flat_map(|line| chunks(g2p.tokens(line))).collect())
146    }
147
148    fn g2p(&self, dialect: Dialect) -> Result<&G2p, Error> {
149        let cell = match dialect {
150            Dialect::American => &self.american,
151            Dialect::British => &self.british,
152        };
153        if let Some(g2p) = cell.get() {
154            return Ok(g2p);
155        }
156        let built = G2p::new(dialect, self.fallback)?;
157        Ok(cell.get_or_init(|| built))
158    }
159}