1mod 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
35pub const UNKNOWN: &str = "❓";
37
38#[derive(Debug, Clone, PartialEq, Eq)]
40pub struct PhonemeToken {
41 pub text: String,
43 pub phonemes: String,
46 pub whitespace: bool,
48}
49
50#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
55pub enum Dialect {
56 American,
57 British,
58}
59
60impl Dialect {
61 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#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
76pub enum OovFallback {
77 #[default]
81 Neural,
82 SpellOut,
85}
86
87#[derive(Debug, thiserror::Error)]
88pub enum Error {
89 #[error("embedded G2P data is malformed: {0}")]
92 Weights(String),
93}
94
95pub 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 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 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 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 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 .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 "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
204fn 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}