mod blend_match;
mod models;
mod slot;
mod speaker;
use std::collections::{BTreeMap, BTreeSet};
use std::path::PathBuf;
use std::sync::{Arc, Weak};
use std::time::Duration;
pub use blend_match::{Accent, BlendMatch, MAX_EVALUATIONS, MAX_VOICES, MIN_MATCH_SECS, MatchProgress, MatchRequest};
pub use loqui_audio::{Error as AudioError, Format};
pub use loqui_g2p::OovFallback;
pub use loqui_kokoro::{Blend, Error as TtsError};
pub use models::{Downloads, KokoroVariant, WHISPER_MODELS, WhisperModel, default_cache_dir, whisper_model};
pub use speaker::{MIN_EMBED_SECS, SpeakerEmbedding};
use loqui_kokoro::{Kokoro, KokoroModel};
use slot::Slot;
pub const TTS_MODEL_ID: &str = "kokoro";
pub const SPEAKER_MODEL_ID: &str = "wespeaker-resnet34-lm";
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum Error {
#[error("{0}")]
Invalid(String),
#[error("input is {chars} characters; the limit is {limit}")]
InputTooLong { chars: usize, limit: usize },
#[error("{0} is not enabled in this engine")]
Disabled(&'static str),
#[error("configuration: {0}")]
Config(String),
#[error("model unavailable: {0}")]
Unavailable(String),
#[error("weights missing: {0}")]
Missing(String),
#[error("download failed: {0}")]
Download(String),
#[error("integrity check failed: {0}")]
Integrity(String),
#[error("{0}")]
Io(String),
#[error("audio: {0}")]
Audio(#[from] loqui_audio::Error),
#[error("speech synthesis: {0}")]
Tts(#[from] loqui_kokoro::Error),
#[error("speaker embedding: {0}")]
Speaker(#[from] loqui_speaker::Error),
#[error("cancelled")]
Cancelled,
#[cfg(feature = "whisper")]
#[error("transcription: {0}")]
Stt(#[from] loqui_whisper::Error),
}
impl Error {
pub fn is_client_error(&self) -> bool {
matches!(self, Self::Invalid(_) | Self::InputTooLong { .. } | Self::Disabled(_) | Self::Cancelled)
|| matches!(self, Self::Speaker(loqui_speaker::Error::TooShort { .. }))
|| matches!(
self,
Self::Audio(
loqui_audio::Error::Decode(_) | loqui_audio::Error::TooLong { .. } | loqui_audio::Error::UnsupportedFormat { .. }
)
)
|| matches!(self, Self::Tts(loqui_kokoro::Error::Voice(_) | loqui_kokoro::Error::Speed(_)))
|| self.is_unsupported_language()
}
#[cfg(feature = "whisper")]
fn is_unsupported_language(&self) -> bool {
matches!(self, Self::Stt(loqui_whisper::Error::Language(_)))
}
#[cfg(not(feature = "whisper"))]
fn is_unsupported_language(&self) -> bool {
false
}
}
pub use loqui_kokoro::Device as TtsDevice;
#[derive(Debug, Clone)]
pub struct TtsConfig {
pub variant: KokoroVariant,
pub device: TtsDevice,
pub threads: Option<usize>,
pub fallback: OovFallback,
pub idle_ttl: Option<Duration>,
}
impl Default for TtsConfig {
fn default() -> Self {
Self { variant: KokoroVariant::Fp32, device: TtsDevice::Cpu, threads: None, fallback: OovFallback::Neural, idle_ttl: None }
}
}
#[derive(Debug, Clone, Default)]
pub struct SpeakerConfig {
pub threads: Option<usize>,
pub idle_ttl: Option<Duration>,
}
#[cfg(feature = "whisper")]
#[derive(Debug, Clone)]
pub struct SttConfig {
pub model: String,
pub device: loqui_whisper::Device,
pub idle_ttl: Option<Duration>,
}
#[cfg(feature = "whisper")]
impl Default for SttConfig {
fn default() -> Self {
Self { model: "large-v3-turbo".into(), device: loqui_whisper::Device::Cpu, idle_ttl: Some(Duration::from_secs(600)) }
}
}
pub struct EngineBuilder {
cache_dir: Option<PathBuf>,
downloads: Downloads,
tts: Option<TtsConfig>,
#[cfg(feature = "whisper")]
stt: Option<SttConfig>,
speaker: Option<SpeakerConfig>,
max_input_chars: usize,
max_audio_secs: u64,
preload: bool,
voices: Vec<(String, String)>,
}
impl EngineBuilder {
pub fn cache_dir(mut self, dir: impl Into<PathBuf>) -> Self {
self.cache_dir = Some(dir.into());
self
}
pub fn downloads(mut self, downloads: Downloads) -> Self {
self.downloads = downloads;
self
}
pub fn tts(mut self, config: Option<TtsConfig>) -> Self {
self.tts = config;
self
}
#[cfg(feature = "whisper")]
pub fn stt(mut self, config: Option<SttConfig>) -> Self {
self.stt = config;
self
}
pub fn speaker(mut self, config: Option<SpeakerConfig>) -> Self {
self.speaker = config;
self
}
pub fn max_input_chars(mut self, chars: usize) -> Self {
self.max_input_chars = chars;
self
}
pub fn max_audio_secs(mut self, secs: u64) -> Self {
self.max_audio_secs = secs;
self
}
pub fn preload(mut self, preload: bool) -> Self {
self.preload = preload;
self
}
pub fn voice(mut self, name: impl Into<String>, spec: impl Into<String>) -> Self {
self.voices.push((name.into(), spec.into()));
self
}
pub fn build(self) -> Result<Engine, Error> {
let names = named_voices(self.voices)?;
let cache = match self.cache_dir {
Some(dir) => dir,
None => {
default_cache_dir().ok_or_else(|| Error::Config("no cache directory: set HOME or XDG_CACHE_HOME, or pass one".into()))?
}
};
let downloads = self.downloads;
let tts_variant = self.tts.as_ref().map(|cfg| cfg.variant);
let tts = self.tts.map(|cfg| {
let cache = cache.clone();
let ttl = cfg.idle_ttl;
Slot::new(ttl, Box::new(move || load_kokoro(&cache, &cfg, downloads)))
});
#[cfg(feature = "whisper")]
if let Some(cfg) = &self.stt {
models::whisper_file(&cfg.model)?;
}
#[cfg(feature = "whisper")]
let stt_model = self.stt.as_ref().map(|cfg| cfg.model.clone());
#[cfg(not(feature = "whisper"))]
let stt_model = None;
#[cfg(feature = "whisper")]
let stt = self.stt.map(|cfg| {
let cache = cache.clone();
let ttl = cfg.idle_ttl;
Slot::new(ttl, Box::new(move || load_whisper(&cache, &cfg, downloads)))
});
let speaker = self.speaker.map(|cfg| {
let cache = cache.clone();
let ttl = cfg.idle_ttl;
Slot::new(ttl, Box::new(move || load_speaker(&cache, &cfg, downloads)))
});
let inner = Arc::new(Inner {
cache,
downloads,
tts,
tts_variant,
#[cfg(feature = "whisper")]
stt,
stt_model,
speaker,
names,
max_input_chars: self.max_input_chars,
max_audio_secs: self.max_audio_secs,
});
if inner.has_ttl() {
start_reaper(Arc::downgrade(&inner));
}
let engine = Engine { inner };
if self.preload {
engine.preload()?;
}
Ok(engine)
}
}
struct Inner {
cache: PathBuf,
downloads: Downloads,
tts: Option<Slot<Kokoro>>,
tts_variant: Option<KokoroVariant>,
#[cfg(feature = "whisper")]
stt: Option<Slot<loqui_whisper::Whisper>>,
stt_model: Option<String>,
speaker: Option<Slot<loqui_speaker::SpeakerEncoder>>,
names: BTreeMap<String, Named>,
max_input_chars: usize,
max_audio_secs: u64,
}
impl Inner {
fn has_ttl(&self) -> bool {
let tts = self.tts.as_ref().is_some_and(|s| s.ttl().is_some());
#[cfg(feature = "whisper")]
let stt = self.stt.as_ref().is_some_and(|s| s.ttl().is_some());
#[cfg(not(feature = "whisper"))]
let stt = false;
let speaker = self.speaker.as_ref().is_some_and(|s| s.ttl().is_some());
tts || stt || speaker
}
fn reap(&self) {
if let Some(slot) = &self.tts
&& slot.reap()
{
tracing::info!(kind = "tts", "idle model unloaded");
}
#[cfg(feature = "whisper")]
if let Some(slot) = &self.stt
&& slot.reap()
{
tracing::info!(kind = "stt", "idle model unloaded");
}
if let Some(slot) = &self.speaker
&& slot.reap()
{
tracing::info!(kind = "speaker", "idle model unloaded");
}
}
}
struct Named {
spec: String,
blend: Blend,
}
fn named_voices(voices: Vec<(String, String)>) -> Result<BTreeMap<String, Named>, Error> {
let defined: Vec<String> = voices.iter().map(|(name, _)| name.clone()).collect();
let mut names = BTreeMap::new();
for (name, spec) in voices {
let bad = |why: &str| Error::Config(format!("voice {name:?}: {why}"));
if name.is_empty() || !name.bytes().all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'_') {
return Err(bad("names may contain only lowercase ASCII letters, digits and _"));
}
if is_kokoro_shaped(&name) {
return Err(bad("names shaped like Kokoro's (af_, bm_, ...) are reserved for its own voices"));
}
let blend = Blend::parse(&spec, |_| None).map_err(|e| bad(&e.to_string()))?;
if let Some((id, _)) = blend.parts().iter().find(|(id, _)| !loqui_kokoro::ENGLISH_VOICES.contains(&id.as_str())) {
return Err(bad(&if defined.contains(id) {
format!("{id} is a named voice; named voices are made of built-in voices only")
} else {
format!("{id} is not a built-in voice")
}));
}
if names.insert(name.clone(), Named { spec: spec.trim().to_owned(), blend }).is_some() {
return Err(bad("named twice"));
}
}
Ok(names)
}
fn is_kokoro_shaped(name: &str) -> bool {
matches!(name.as_bytes(), [lang, b'f' | b'm', b'_', ..] if lang.is_ascii_lowercase())
}
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct VoiceInfo {
pub id: String,
pub name: String,
pub language: &'static str,
pub gender: &'static str,
pub blend: Option<String>,
}
impl VoiceInfo {
fn builtin(id: &str) -> Self {
let mut name = id.get(3..).unwrap_or(id).to_owned();
if let Some(initial) = name.get_mut(..1) {
initial.make_ascii_uppercase();
}
Self { id: id.to_owned(), name, language: language(id), gender: gender(id), blend: None }
}
fn named(name: &str, voice: &Named) -> Self {
let mut genders = voice.blend.audible().map(|(id, _)| gender(id));
let first = genders.next().unwrap_or("unknown");
let gender = if genders.all(|g| g == first) { first } else { "unknown" };
Self { id: name.to_owned(), name: name.to_owned(), language: language(voice.blend.lead()), gender, blend: Some(voice.spec.clone()) }
}
}
fn language(id: &str) -> &'static str {
if id.starts_with('b') { "en-gb" } else { "en-us" }
}
fn gender(id: &str) -> &'static str {
match id.as_bytes().get(1) {
Some(b'f') => "female",
Some(b'm') => "male",
_ => "unknown",
}
}
fn start_reaper(inner: Weak<Inner>) {
let spawned = std::thread::Builder::new().name("loqui-reaper".into()).spawn(move || {
loop {
std::thread::sleep(Duration::from_secs(15));
match inner.upgrade() {
Some(inner) => inner.reap(),
None => return,
}
}
});
if let Err(e) = spawned {
tracing::warn!("could not start the idle-unload thread, models will stay resident: {e}");
}
}
fn load_kokoro(cache: &std::path::Path, cfg: &TtsConfig, downloads: Downloads) -> Result<Kokoro, Error> {
let pinned = cfg.variant.file();
let onnx = models::fetch(cache, &models::KOKORO_REPO, pinned.file, Some(pinned.sha256), downloads)?;
let default_voice = models::fetch(cache, &models::KOKORO_REPO, &voice_file(loqui_kokoro::DEFAULT_VOICE), None, downloads)?;
let voices_dir = default_voice.parent().map(PathBuf::from).ok_or_else(|| Error::Io("voice path has no parent".into()))?;
let model = KokoroModel::load(&onnx, cfg.device, cfg.threads)?;
tracing::info!(variant = ?cfg.variant, device = ?cfg.device, "Kokoro loaded");
Ok(Kokoro::new(model, voices_dir, cfg.fallback))
}
fn load_speaker(cache: &std::path::Path, cfg: &SpeakerConfig, downloads: Downloads) -> Result<loqui_speaker::SpeakerEncoder, Error> {
let pinned = &models::SPEAKER_FILE;
let path = models::fetch(cache, &models::SPEAKER_REPO, pinned.file, Some(pinned.sha256), downloads)?;
let encoder = loqui_speaker::SpeakerEncoder::load(&path, cfg.threads)?;
tracing::info!(model = SPEAKER_MODEL_ID, "speaker model loaded");
Ok(encoder)
}
#[cfg(feature = "whisper")]
fn load_whisper(cache: &std::path::Path, cfg: &SttConfig, downloads: Downloads) -> Result<loqui_whisper::Whisper, Error> {
let model = models::whisper_file(&cfg.model)?;
let path = models::fetch(cache, &models::WHISPER_REPO, model.file, Some(model.sha256), downloads)?;
let whisper = loqui_whisper::Whisper::load(&path, cfg.device)?;
tracing::info!(model = cfg.model, device = ?cfg.device, "Whisper loaded");
Ok(whisper)
}
fn voice_file(id: &str) -> String {
format!("voices/{id}.bin")
}
#[derive(Debug, Clone)]
pub struct SpeakRequest {
pub text: String,
pub voice: String,
pub speed: f32,
pub format: Format,
}
impl SpeakRequest {
pub fn new(text: impl Into<String>) -> Self {
Self { text: text.into(), voice: loqui_kokoro::DEFAULT_VOICE.into(), speed: 1.0, format: Format::Wav }
}
}
#[derive(Debug, Clone)]
pub struct Speech {
pub audio: Vec<u8>,
pub format: Format,
pub duration_secs: f64,
}
#[cfg(feature = "whisper")]
pub use loqui_whisper::{Device as SttDevice, Error as SttError, Segment, Task, Transcription};
#[cfg(feature = "whisper")]
#[derive(Debug, Clone, Default)]
pub struct TranscribeRequest {
pub audio: Vec<u8>,
pub language: Option<String>,
pub prompt: Option<String>,
pub task: Task,
pub temperature: f32,
pub threads: Option<u16>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum ModelKind {
Tts,
Stt,
Speaker,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ModelInfo {
pub id: String,
pub kind: ModelKind,
pub loaded: bool,
}
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct ModelFile {
pub kind: ModelKind,
pub repo: &'static str,
pub file: String,
pub path: PathBuf,
pub bytes: u64,
}
struct Required {
kind: ModelKind,
pinned: &'static models::Pinned,
file: String,
sha256: Option<&'static str>,
bytes: u64,
}
#[derive(Clone)]
pub struct Engine {
inner: Arc<Inner>,
}
impl std::fmt::Debug for Engine {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("Engine").field("cache", &self.inner.cache).field("models", &self.models()).finish()
}
}
impl Engine {
pub fn builder() -> EngineBuilder {
EngineBuilder {
cache_dir: None,
downloads: Downloads::Allow,
tts: Some(TtsConfig::default()),
#[cfg(feature = "whisper")]
stt: None,
speaker: None,
max_input_chars: 4096,
max_audio_secs: 1800,
preload: false,
voices: Vec::new(),
}
}
pub fn preload(&self) -> Result<(), Error> {
if let Some(slot) = &self.inner.tts {
slot.get()?;
for named in self.inner.names.values() {
named.blend.audible().try_for_each(|(id, _)| self.fetch_voice(id))?;
}
}
#[cfg(feature = "whisper")]
if let Some(slot) = &self.inner.stt {
slot.get()?;
}
if let Some(slot) = &self.inner.speaker {
slot.get()?;
}
Ok(())
}
pub fn unload(&self) {
if let Some(slot) = &self.inner.tts {
slot.unload();
}
#[cfg(feature = "whisper")]
if let Some(slot) = &self.inner.stt {
slot.unload();
}
if let Some(slot) = &self.inner.speaker {
slot.unload();
}
}
pub fn models(&self) -> Vec<ModelInfo> {
let mut out = Vec::new();
if let Some(slot) = &self.inner.tts {
out.push(ModelInfo { id: TTS_MODEL_ID.into(), kind: ModelKind::Tts, loaded: slot.is_loaded() });
}
#[cfg(feature = "whisper")]
if let (Some(slot), Some(id)) = (&self.inner.stt, &self.inner.stt_model) {
out.push(ModelInfo { id: id.clone(), kind: ModelKind::Stt, loaded: slot.is_loaded() });
}
if let Some(slot) = &self.inner.speaker {
out.push(ModelInfo { id: SPEAKER_MODEL_ID.into(), kind: ModelKind::Speaker, loaded: slot.is_loaded() });
}
out
}
pub fn stt_model_id(&self) -> Option<&str> {
self.inner.stt_model.as_deref()
}
pub fn voices(&self) -> Result<Vec<VoiceInfo>, Error> {
self.inner.tts.as_ref().ok_or(Error::Disabled("text-to-speech"))?;
let builtin = loqui_kokoro::ENGLISH_VOICES.iter().map(|id| VoiceInfo::builtin(id));
Ok(builtin.chain(self.inner.names.iter().map(|(name, voice)| VoiceInfo::named(name, voice))).collect())
}
pub fn missing(&self) -> Vec<ModelFile> {
self.required()
.into_iter()
.filter(|r| models::cached(&self.inner.cache, r.pinned, &r.file).is_none())
.map(|r| ModelFile {
kind: r.kind,
repo: r.pinned.repo,
path: models::expected_path(&self.inner.cache, r.pinned, &r.file),
file: r.file,
bytes: r.bytes,
})
.collect()
}
pub fn fetch(&self) -> Result<(), Error> {
self.required()
.iter()
.try_for_each(|r| models::fetch(&self.inner.cache, r.pinned, &r.file, r.sha256, self.inner.downloads).map(drop))
}
fn required(&self) -> Vec<Required> {
let mut out = Vec::new();
if let Some(variant) = self.inner.tts_variant {
let model = variant.file();
out.push(Required {
kind: ModelKind::Tts,
pinned: &models::KOKORO_REPO,
file: model.file.to_owned(),
sha256: Some(model.sha256),
bytes: model.bytes,
});
let named = self.inner.names.values().flat_map(|named| named.blend.audible().map(|(id, _)| id.to_owned()));
let voices: BTreeSet<String> = std::iter::once(loqui_kokoro::DEFAULT_VOICE.to_owned()).chain(named).collect();
out.extend(voices.into_iter().map(|id| Required {
kind: ModelKind::Tts,
pinned: &models::KOKORO_REPO,
file: voice_file(&id),
sha256: None,
bytes: models::VOICE_PACK_BYTES,
}));
}
#[cfg(feature = "whisper")]
if let Some(model) = self.inner.stt_model.as_deref().and_then(whisper_model) {
let pinned = model.pinned();
out.push(Required {
kind: ModelKind::Stt,
pinned: &models::WHISPER_REPO,
file: pinned.file.to_owned(),
sha256: Some(pinned.sha256),
bytes: pinned.bytes,
});
}
if self.inner.speaker.is_some() {
let pinned = &models::SPEAKER_FILE;
out.push(Required {
kind: ModelKind::Speaker,
pinned: &models::SPEAKER_REPO,
file: pinned.file.to_owned(),
sha256: Some(pinned.sha256),
bytes: pinned.bytes,
});
}
out
}
pub fn fetch_voices(&self) -> Result<(), Error> {
self.inner.tts.as_ref().ok_or(Error::Disabled("text-to-speech"))?;
loqui_kokoro::ENGLISH_VOICES.iter().try_for_each(|id| self.fetch_voice(id))
}
fn resolve(&self, spec: &str) -> Result<Blend, Error> {
Ok(Blend::parse(spec, |id| self.inner.names.get(id).map(|named| &named.blend))?)
}
fn fetch_voice(&self, id: &str) -> Result<(), Error> {
models::fetch(&self.inner.cache, &models::KOKORO_REPO, &voice_file(id), None, self.inner.downloads).map(drop)
}
pub fn speak(&self, request: &SpeakRequest) -> Result<Speech, Error> {
let slot = self.inner.tts.as_ref().ok_or(Error::Disabled("text-to-speech"))?;
let chars = request.text.chars().count();
if request.text.trim().is_empty() {
return Err(Error::Invalid("input text is empty".into()));
}
if chars > self.inner.max_input_chars {
return Err(Error::InputTooLong { chars, limit: self.inner.max_input_chars });
}
if !(0.25..=4.0).contains(&request.speed) {
return Err(Error::Invalid(format!("speed {} is outside 0.25 to 4.0", request.speed)));
}
let voice = self.resolve(&request.voice)?;
if voice.parts().iter().any(|(id, _)| !loqui_kokoro::ENGLISH_VOICES.contains(&id.as_str())) {
return Err(Error::Invalid("unknown voice".into()));
}
voice.audible().try_for_each(|(id, _)| self.fetch_voice(id))?;
let kokoro = slot.get()?;
let samples = kokoro.speak(&request.text, &voice, request.speed)?;
let pcm = loqui_audio::Pcm { samples, rate: loqui_kokoro::SAMPLE_RATE };
let duration_secs = pcm.duration_secs();
let audio = loqui_audio::encode(&pcm, request.format)?;
Ok(Speech { audio, format: request.format, duration_secs })
}
pub fn speaker_embedding(&self, audio: &[u8]) -> Result<SpeakerEmbedding, Error> {
let slot = self.inner.speaker.as_ref().ok_or(Error::Disabled("speaker embeddings"))?;
let pcm = loqui_audio::decode_mono_16k(audio, Some(self.inner.max_audio_secs))?;
let encoder = slot.get()?;
speaker::embed(&encoder, &pcm.samples, MIN_EMBED_SECS)
}
#[cfg(feature = "whisper")]
pub fn transcribe(&self, request: &TranscribeRequest) -> Result<Transcription, Error> {
let slot = self.inner.stt.as_ref().ok_or(Error::Disabled("speech-to-text"))?;
let pcm = loqui_audio::decode_mono_16k(&request.audio, Some(self.inner.max_audio_secs))?;
let whisper = slot.get()?;
let options = loqui_whisper::Options {
language: request.language.clone(),
prompt: request.prompt.clone(),
task: request.task,
temperature: request.temperature,
threads: request.threads,
};
Ok(whisper.transcribe(&pcm.samples, &options)?)
}
}
#[cfg(test)]
mod tests {
use super::*;
fn engine(voices: &[(&str, &str)]) -> Result<Engine, Error> {
let builder = Engine::builder().cache_dir(std::env::temp_dir().join("loqui-unused-cache")).downloads(Downloads::Deny);
voices.iter().fold(builder, |b, (name, spec)| b.voice(*name, *spec)).build()
}
fn close(blend: &Blend, expected: &[(&str, f32)]) -> bool {
let parts = blend.parts();
parts.len() == expected.len() && parts.iter().zip(expected).all(|((a, x), (b, y))| a == b && (x - y).abs() < 1e-6)
}
#[test]
fn named_voices_are_checked_when_the_engine_is_built() {
let refused = [
("Will", "am_puck"),
("will smith", "am_puck"),
("", "am_puck"),
("af_custom", "am_puck"),
("jf_alpha", "am_puck"),
("will", "am_puck(x)"),
("will", "zz_nobody"),
("will", "jf_alpha"),
];
for (name, spec) in refused {
let err = engine(&[(name, spec)]).expect_err(&format!("{name:?} = {spec:?}"));
assert!(matches!(err, Error::Config(_)), "{name:?} = {spec:?}: {err}");
}
assert!(matches!(engine(&[("will", "am_puck"), ("will", "am_liam")]), Err(Error::Config(_))));
let err = engine(&[("will", "am_puck"), ("bill", "will(2)+am_liam")]).unwrap_err().to_string();
assert!(err.contains("built-in voices only"), "{err}");
}
#[test]
fn named_voices_resolve_alone_and_inside_blends() {
let engine = engine(&[("will", "am_puck(1)+am_liam(1)+am_onyx(0.5)")]).unwrap();
assert!(close(&engine.resolve("will").unwrap(), &[("am_puck", 0.4), ("am_liam", 0.4), ("am_onyx", 0.2)]));
let blend = engine.resolve("will(2)+af_sky(1)").unwrap();
assert!(close(&blend, &[("am_puck", 0.8 / 3.0), ("am_liam", 0.8 / 3.0), ("am_onyx", 0.4 / 3.0), ("af_sky", 1.0 / 3.0)]));
}
#[test]
fn a_name_can_take_over_an_openai_name_and_use_it() {
let engine = engine(&[("nova", "nova(3)+af_sky(1)")]).unwrap();
assert!(close(&engine.resolve("nova").unwrap(), &[("af_nova", 0.75), ("af_sky", 0.25)]));
assert!(close(&engine.resolve("alloy").unwrap(), &[("af_heart", 1.0)]));
}
#[test]
fn unknown_voices_are_refused_without_echoing_them() {
let engine = engine(&[]).unwrap();
let err = engine.speak(&SpeakRequest { voice: "af_heart+zz_secret".into(), ..SpeakRequest::new("hello") }).unwrap_err();
assert!(matches!(err, Error::Invalid(_)), "{err}");
assert!(!err.to_string().contains("secret"), "{err}");
}
#[test]
fn voices_lists_the_roster_then_named_voices() {
let engine = engine(&[("will", "am_puck(1)+am_liam(1)"), ("duo", " af_sky + am_adam "), ("lady", "bf_emma(0)+af_sky")]).unwrap();
let voices = engine.voices().unwrap();
assert_eq!(voices.len(), loqui_kokoro::ENGLISH_VOICES.len() + 3);
let heart = voices.iter().find(|v| v.id == "af_heart").unwrap();
assert_eq!((heart.name.as_str(), heart.language, heart.gender, heart.blend.as_deref()), ("Heart", "en-us", "female", None));
let george = voices.iter().find(|v| v.id == "bm_george").unwrap();
assert_eq!((george.name.as_str(), george.language, george.gender), ("George", "en-gb", "male"));
let named: Vec<_> = voices[loqui_kokoro::ENGLISH_VOICES.len()..].iter().map(|v| (v.id.as_str(), v.language, v.gender)).collect();
assert_eq!(named, [("duo", "en-us", "unknown"), ("lady", "en-gb", "female"), ("will", "en-us", "male")]);
assert_eq!(voices.last().unwrap().blend.as_deref(), Some("am_puck(1)+am_liam(1)"));
}
fn scratch(name: &str) -> PathBuf {
let dir = std::env::temp_dir().join(format!("loqui-{name}-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&dir);
dir
}
fn populate(cache: &std::path::Path, pinned: &models::Pinned, files: &[&str]) {
let repo = cache.join(format!("models--{}", pinned.repo.replace('/', "--")));
std::fs::create_dir_all(repo.join("refs")).unwrap();
std::fs::write(repo.join("refs").join(pinned.revision), pinned.revision).unwrap();
for file in files {
let path = repo.join("snapshots").join(pinned.revision).join(file);
std::fs::create_dir_all(path.parent().unwrap()).unwrap();
std::fs::write(path, b"weights").unwrap();
}
}
#[test]
fn missing_lists_what_the_configuration_needs_without_touching_the_cache() {
let cache = scratch("missing");
let engine = Engine::builder().cache_dir(&cache).voice("will", "am_puck(1)+am_liam(1)+af_heart(0)").build().unwrap();
let missing = engine.missing();
let files: Vec<_> = missing.iter().map(|f| (f.kind, f.file.as_str(), f.bytes)).collect();
assert_eq!(
files,
[
(ModelKind::Tts, "onnx/model.onnx", 325_532_232),
(ModelKind::Tts, "voices/af_heart.bin", models::VOICE_PACK_BYTES),
(ModelKind::Tts, "voices/am_liam.bin", models::VOICE_PACK_BYTES),
(ModelKind::Tts, "voices/am_puck.bin", models::VOICE_PACK_BYTES),
],
"the model, the default voice, and the audible parts of named voices, once each"
);
assert!(missing.iter().all(|f| f.repo == models::KOKORO_REPO.repo && f.path.starts_with(&cache) && f.path.ends_with(&f.file)));
assert!(!cache.exists(), "missing() must not create the cache");
}
#[test]
fn cached_files_are_not_missing() {
let cache = scratch("cached");
populate(&cache, &models::KOKORO_REPO, &["onnx/model_quantized.onnx", "voices/af_heart.bin"]);
let tts = TtsConfig { variant: KokoroVariant::Quantized, ..TtsConfig::default() };
let engine = Engine::builder().cache_dir(&cache).tts(Some(tts)).build().unwrap();
assert_eq!(engine.missing(), []);
let with_named = Engine::builder().cache_dir(&cache).voice("sky", "af_sky").build().unwrap();
let files: Vec<_> = with_named.missing().into_iter().map(|f| f.file).collect();
assert_eq!(files, ["onnx/model.onnx", "voices/af_sky.bin"], "only what is absent");
std::fs::remove_dir_all(&cache).unwrap();
}
#[test]
fn fetch_with_downloads_off_reports_what_is_missing() {
let cache = scratch("fetch-deny");
let engine = Engine::builder().cache_dir(&cache).downloads(Downloads::Deny).build().unwrap();
assert!(matches!(engine.fetch(), Err(Error::Missing(_))));
assert!(Engine::builder().cache_dir(&cache).tts(None).build().unwrap().fetch().is_ok(), "an engine with no models needs nothing");
std::fs::remove_dir_all(&cache).unwrap();
}
#[cfg(feature = "whisper")]
#[test]
fn missing_includes_the_whisper_model() {
let cache = scratch("missing-stt");
let stt = SttConfig { model: "tiny.en".into(), ..SttConfig::default() };
let engine = Engine::builder().cache_dir(&cache).tts(None).stt(Some(stt)).build().unwrap();
let files: Vec<_> = engine.missing().into_iter().map(|f| (f.kind, f.repo, f.file, f.bytes)).collect();
assert_eq!(files, [(ModelKind::Stt, models::WHISPER_REPO.repo, "ggml-tiny.en.bin".to_owned(), 77_704_715)]);
}
#[cfg(feature = "whisper")]
#[test]
fn an_unsupported_language_is_the_callers_error() {
assert!(Error::Stt(loqui_whisper::Error::Language("fr".into())).is_client_error());
assert!(!Error::Stt(loqui_whisper::Error::Inference("boom".into())).is_client_error());
}
#[test]
fn voices_needs_text_to_speech() {
let engine = Engine::builder().cache_dir(std::env::temp_dir()).tts(None).build().unwrap();
assert!(matches!(engine.voices(), Err(Error::Disabled(_))));
}
fn tone_wav() -> Vec<u8> {
let samples = (0..32_000).map(|i| 0.3 * (i as f32 * 0.05).sin()).collect();
loqui_audio::encode(&loqui_audio::Pcm { samples, rate: 16_000 }, Format::Wav).unwrap()
}
#[test]
fn the_speaker_model_is_needed_only_when_enabled() {
let cache = scratch("missing-speaker");
let without = Engine::builder().cache_dir(&cache).tts(None).build().unwrap();
assert!(without.missing().is_empty());
assert!(without.models().is_empty());
let with = Engine::builder().cache_dir(&cache).tts(None).speaker(Some(SpeakerConfig::default())).build().unwrap();
let files: Vec<_> = with.missing().into_iter().map(|f| (f.kind, f.repo, f.file, f.bytes)).collect();
assert_eq!(
files,
[(ModelKind::Speaker, models::SPEAKER_REPO.repo, "wespeaker_en_voxceleb_resnet34_LM.onnx".to_owned(), 26_530_550)]
);
assert_eq!(with.models(), [ModelInfo { id: SPEAKER_MODEL_ID.into(), kind: ModelKind::Speaker, loaded: false }]);
}
#[test]
fn speaker_embeddings_need_the_speaker_model_enabled() {
let engine = Engine::builder().cache_dir(std::env::temp_dir()).tts(None).build().unwrap();
assert!(matches!(engine.speaker_embedding(&tone_wav()), Err(Error::Disabled("speaker embeddings"))));
}
#[test]
fn missing_speaker_weights_are_reported_with_downloads_off() {
let cache = scratch("speaker-deny");
let engine = Engine::builder()
.cache_dir(&cache)
.downloads(Downloads::Deny)
.tts(None)
.speaker(Some(SpeakerConfig::default()))
.build()
.unwrap();
assert!(matches!(engine.speaker_embedding(&tone_wav()), Err(Error::Missing(_))));
let _ = std::fs::remove_dir_all(&cache);
}
#[test]
fn a_short_recording_and_a_cancelled_match_are_the_callers() {
assert!(Error::Speaker(loqui_speaker::Error::TooShort { secs: 0.2, min_secs: 0.5 }).is_client_error());
assert!(!Error::Speaker(loqui_speaker::Error::Model("boom".into())).is_client_error());
assert!(Error::Cancelled.is_client_error());
}
}