Skip to main content

loqui_g2p/
lib.rs

1//! English grapheme-to-phoneme conversion for Kokoro, GPL-free.
2//!
3//! Kokoro's voices were trained on phonemes from misaki, hexgrad's G2P, so
4//! this crate reproduces misaki's English pipeline: spaCy's tokenization,
5//! Penn Treebank tags, the misaki gold and silver lexicons, heteronym
6//! selection, stress rules, morphology, and number, currency and year
7//! reading. Each stage is checked against its Python original by the parity
8//! harness in `tools/parity`.
9//!
10//! Where upstream hands unknown words to eSpeak NG (GPL-3.0), this crate
11//! uses a small embedded neural model trained on the same lexicons
12//! ([`OovFallback::Neural`]). It links no GPL code.
13//!
14//! ```
15//! use loqui_g2p::{Dialect, G2p, OovFallback};
16//!
17//! let g2p = G2p::new(Dialect::American, OovFallback::Neural)?;
18//! assert_eq!(g2p.phonemize("Hello world."), "həlˈO wˈɜɹld.");
19//! # Ok::<(), loqui_g2p::Error>(())
20//! ```
21
22mod en;
23mod lexicon;
24mod neural;
25pub mod numbers;
26pub mod tagger;
27pub mod tokenize;
28
29pub use neural::{MAX_WORD_CHARS, NeuralG2p};
30
31use en::{Lexicon, MToken};
32use tagger::Tagger;
33use tokenize::Tokenizer;
34
35/// What misaki writes for a word it could not phonemize at all.
36pub const UNKNOWN: &str = "❓";
37
38/// One spoken word and its phonemes, as Kokoro's chunker consumes them.
39#[derive(Debug, Clone, PartialEq, Eq)]
40pub struct PhonemeToken {
41    /// The source text of the word.
42    pub text: String,
43    /// Its phonemes; empty for silent tokens (currency signs, `#`) and for
44    /// anything nothing could phonemize.
45    pub phonemes: String,
46    /// Whether whitespace followed the word in the source.
47    pub whitespace: bool,
48}
49
50/// Which English the lexicons, rules and fallback model follow.
51///
52/// Kokoro voices encode their dialect in the first letter of the voice id:
53/// `a` (`af_heart`) is American, `b` (`bf_emma`) is British.
54#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
55pub enum Dialect {
56    American,
57    British,
58}
59
60impl Dialect {
61    /// The dialect a Kokoro voice id implies, or `None` for a voice whose
62    /// language this crate does not phonemize (Kokoro's `e`, `f`, `h`, `i`,
63    /// `j`, `p` and `z` voices need other G2P engines).
64    pub fn for_kokoro_voice(voice: &str) -> Option<Self> {
65        match voice.chars().next()? {
66            'a' => Some(Self::American),
67            'b' => Some(Self::British),
68            _ => None,
69        }
70    }
71}
72
73/// What happens to a word that no lexicon entry, morphology rule or number
74/// rule covers: a name, a coinage, a typo.
75#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
76pub enum OovFallback {
77    /// The embedded character-level BART model (Apache-2.0), trained on the
78    /// misaki lexicons. It pronounces unseen words as words, and scores
79    /// slightly better than eSpeak NG against CMUdict on held-out names.
80    #[default]
81    Neural,
82    /// Spell the word letter by letter. Predictable, and right for
83    /// acronyms, but it reads "zorbulate" as nine letter names.
84    SpellOut,
85}
86
87#[derive(Debug, thiserror::Error)]
88pub enum Error {
89    /// Embedded data (model weights, lexicons, tokenizer rules) could not
90    /// be read. This is a build defect, never a runtime condition.
91    #[error("embedded G2P data is malformed: {0}")]
92    Weights(String),
93}
94
95/// A ready-to-use phonemizer. Construction parses the lexicons (tens of
96/// megabytes of JSON), so build one and share it: it is `Send + Sync`.
97pub struct G2p {
98    dialect: Dialect,
99    fallback: OovFallback,
100    tokenizer: Tokenizer,
101    tagger: Tagger,
102    lexicon: Lexicon,
103    neural: Option<NeuralG2p>,
104}
105
106impl std::fmt::Debug for G2p {
107    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
108        f.debug_struct("G2p").field("dialect", &self.dialect).field("fallback", &self.fallback).finish_non_exhaustive()
109    }
110}
111
112impl G2p {
113    pub fn new(dialect: Dialect, fallback: OovFallback) -> Result<Self, Error> {
114        Ok(Self {
115            dialect,
116            fallback,
117            tokenizer: Tokenizer::english()?,
118            tagger: Tagger::english()?,
119            lexicon: lexicon::load(dialect)?,
120            neural: match fallback {
121                OovFallback::Neural => Some(NeuralG2p::load(dialect)?),
122                OovFallback::SpellOut => None,
123            },
124        })
125    }
126
127    pub fn dialect(&self) -> Dialect {
128        self.dialect
129    }
130
131    /// Converts `text` to Kokoro phonemes. Punctuation is kept, because
132    /// Kokoro uses it for prosody. misaki's inline markup is honoured:
133    /// `[word](/phonemes/)` overrides a pronunciation, `[word](+2)` sets
134    /// stress, and `[5](#a#)` passes number-reading flags.
135    pub fn phonemize(&self, text: &str) -> String {
136        self.run(text, UNKNOWN).into_iter().map(|tk| tk.phonemes.unwrap_or_else(|| UNKNOWN.to_owned()) + &tk.whitespace).collect()
137    }
138
139    /// The same conversion, one token per spoken word, with nothing marked
140    /// unknown: a word that cannot be phonemized is simply silent. This is
141    /// what Kokoro's own pipeline feeds its chunker (misaki with `unk=''`).
142    pub fn tokens(&self, text: &str) -> Vec<PhonemeToken> {
143        self.run(text, "")
144            .into_iter()
145            .map(|tk| PhonemeToken { phonemes: tk.phonemes.unwrap_or_default(), whitespace: !tk.whitespace.is_empty(), text: tk.text })
146            .collect()
147    }
148
149    fn run(&self, text: &str, unk: &str) -> Vec<MToken> {
150        let word_fallback = |word: &str| -> Option<String> {
151            // A short word with no vowel letter ("kg", "mph", "SQL" in
152            // lowercase) is an abbreviation; eSpeak spells those out too.
153            let vowelless = !word.chars().any(|c| "aeiouyAEIOUY".contains(c));
154            if vowelless
155                && word.chars().count() <= 5
156                && let Some(spelled) = self.lexicon.spell(word)
157            {
158                return Some(spelled);
159            }
160            match &self.neural {
161                // A word the model cannot encode at all ("日本") is dropped
162                // rather than read as an unknown marker.
163                Some(model) => Some(model.phonemize(word).unwrap_or_default()),
164                None => self.lexicon.spell(word),
165            }
166        };
167        let fallback = |word: &str| self.lexicon.compose_fallback(word, &word_fallback);
168        en::g2p(&self.lexicon, text, |t| self.tag(t), &fallback, unk)
169    }
170
171    fn tag(&self, text: &str) -> Vec<MToken> {
172        let tokens = self.tokenizer.tokenize(text);
173        let words: Vec<&str> = tokens.iter().map(|t| t.text.as_str()).collect();
174        let tags = self.tagger.tag(&words);
175        tokens
176            .into_iter()
177            .zip(tags)
178            // spaCy tags URLs and e-mail addresses ADD, and misaki then reads
179            // their "." as "dot" and "/" as "slash". The pattern decides
180            // that more reliably than the statistical tagger does.
181            .map(|(t, tag)| {
182                let tag = if self.tokenizer.is_url(&t.text) {
183                    "ADD".to_owned()
184                } else if is_numeral(&t.text) {
185                    // A numeral is CD whatever its neighbours say, and misaki
186                    // reads money and plain numbers only from CD tokens.
187                    "CD".to_owned()
188                } else {
189                    tag
190                };
191                (t, tag)
192            })
193            .map(|(t, tag)| MToken {
194                whitespace: if t.space_after { " ".to_owned() } else { String::new() },
195                text: t.text,
196                tag,
197                is_head: true,
198                ..MToken::default()
199            })
200            .collect()
201    }
202}
203
204/// Digits with optional thousands separators, a decimal point and a leading
205/// minus: "12", "1,234,567.89", "-5", "4.7".
206fn is_numeral(text: &str) -> bool {
207    let body = text.strip_prefix('-').unwrap_or(text);
208    body.starts_with(|c: char| c.is_ascii_digit()) && body.chars().all(|c| c.is_ascii_digit() || c == ',' || c == '.')
209}
210
211#[cfg(test)]
212mod tests {
213    use super::*;
214
215    fn assert_send_sync<T: Send + Sync>() {}
216
217    #[test]
218    fn g2p_is_shareable_across_threads() {
219        assert_send_sync::<G2p>();
220    }
221
222    #[test]
223    fn dialect_follows_the_kokoro_voice_prefix() {
224        assert_eq!(Dialect::for_kokoro_voice("af_heart"), Some(Dialect::American));
225        assert_eq!(Dialect::for_kokoro_voice("bm_george"), Some(Dialect::British));
226        assert_eq!(Dialect::for_kokoro_voice("jf_alpha"), None);
227        assert_eq!(Dialect::for_kokoro_voice(""), None);
228    }
229
230    #[test]
231    fn neural_fallback_pronounces_unknown_words_as_words() {
232        let neural = G2p::new(Dialect::American, OovFallback::Neural).unwrap();
233        let spelled = G2p::new(Dialect::American, OovFallback::SpellOut).unwrap();
234        assert_eq!(neural.phonemize("zorbulate"), "zˈɔɹbjəlˌAt");
235        assert_ne!(neural.phonemize("zorbulate"), spelled.phonemize("zorbulate"));
236    }
237
238    #[test]
239    fn tokens_carry_phonemes_and_spacing_per_word() {
240        let g2p = G2p::new(Dialect::American, OovFallback::Neural).unwrap();
241        let tokens = g2p.tokens("It costs $5.");
242        let shown: Vec<(&str, &str, bool)> = tokens.iter().map(|t| (t.text.as_str(), t.phonemes.as_str(), t.whitespace)).collect();
243        assert_eq!(
244            shown,
245            [("It", "ˌɪt", true), ("costs", "kˈɔsts", true), ("$", "", false), ("5", "fˈIv dˈɑləɹz", false), (".", ".", false)]
246        );
247    }
248
249    #[test]
250    fn inline_markup_overrides_pronunciation() {
251        let g2p = G2p::new(Dialect::American, OovFallback::Neural).unwrap();
252        assert_eq!(g2p.phonemize("[Kokoro](/kˈOkəɹO/) speaks."), "kˈOkəɹO spˈiks.");
253    }
254}