product_os_voice/lib.rs
1//! Product OS : Voice — text-to-speech and voice generation with pluggable backends.
2//!
3//! This library provides a unified API for synthesizing speech from text. Multiple backends
4//! can be enabled via feature flags: local TTS (Piper, eSpeak NG, Edge TTS) or cloud (AWS Polly).
5//!
6//! **Library-handled setup:** The **piper** (subprocess) backend is fully handled by the library—no
7//! shell scripts. Call [create_engine](fn.create_engine.html) with `"piper"` and `None` config to
8//! trigger download and setup. This works without piper-rs. The **piper_embedded** backend is
9//! optional and may have dependency constraints (e.g. piper-rs, cmake for first build).
10//!
11//! # Features
12//!
13//! - **piper**: Piper TTS (subprocess; binary and ONNX model auto-downloaded when config is `None`). Recommended.
14//! - **piper_embedded**: Piper TTS in-process via piper-rs (optional; dependency compatibility may vary).
15//! - **kokoro_embedded**: Kokoro TTS in-process via ONNX Runtime + eSpeak phonemization (optional).
16//! - **sherpa_embedded**: Sherpa-ONNX offline VITS via C API + same ONNX Runtime as Piper/Kokoro (optional; requires native Sherpa libs).
17//! - **espeak**: eSpeak NG (requires `espeak-ng` binary on PATH).
18//! - **edge_tts**: Edge TTS (requires `edge-tts` on PATH or `python3` with `pip install edge-tts`; no API key).
19//! - **aws_polly**: AWS Polly (requires AWS credentials and network).
20//!
21//! No backend is enabled by default; add the feature you need.
22//!
23//! # Example
24//!
25//! ```no_run
26//! # #[allow(clippy::unwrap_used)]
27//! # #[cfg(feature = "piper")]
28//! # {
29//! use product_os_voice::{create_engine, VoiceEngine, VoiceOptions};
30//! use std::path::PathBuf;
31//!
32//! let engine = product_os_voice::create_engine("piper", None).expect("piper feature enabled");
33//! // Piper requires a model; in real use configure with PiperEngine::new().with_model(path)
34//! let options = VoiceOptions::default();
35//! let audio = engine.synthesize("Hello, world!", &options);
36//! if let Ok(bytes) = audio {
37//! std::fs::write("output.wav", bytes).expect("write");
38//! }
39//! # }
40//! ```
41//!
42//! # Doc-test
43//!
44//! Building options and error types (no backend required):
45//!
46//! ```
47//! use product_os_voice::{AudioFormat, VoiceOptions};
48//!
49//! let opts = VoiceOptions {
50//! sample_rate: Some(16000),
51//! format: AudioFormat::Wav,
52//! ..Default::default()
53//! };
54//! assert_eq!(opts.sample_rate, Some(16000));
55//! ```
56
57#![warn(missing_docs)]
58#![warn(clippy::unwrap_used)]
59
60#[cfg(feature = "ffi")]
61uniffi::setup_scaffolding!();
62
63pub mod backends;
64pub mod config;
65pub mod engine;
66pub mod error;
67pub mod platform;
68
69#[cfg(feature = "ffi")]
70pub mod mobile;
71
72pub use config::EngineConfig;
73pub use engine::{AudioFormat, VoiceEngine, VoiceInfo, VoiceOptions};
74pub use error::VoiceError;
75
76#[cfg(feature = "piper")]
77pub use backends::piper::is_piper_available;
78#[cfg(feature = "piper")]
79pub use backends::PiperEngine;
80
81#[cfg(feature = "piper_embedded")]
82pub use backends::piper_embedded::{is_piper_embedded_config_usable, is_piper_embedded_supported};
83#[cfg(feature = "piper_embedded")]
84pub use backends::PiperEmbeddedEngine;
85
86#[cfg(feature = "kokoro_embedded")]
87pub use backends::KokoroEmbeddedEngine;
88
89#[cfg(feature = "sherpa_embedded")]
90pub use backends::SherpaEmbeddedEngine;
91
92#[cfg(feature = "espeak")]
93pub use backends::espeak::is_espeak_available;
94#[cfg(feature = "espeak")]
95pub use backends::EspeakEngine;
96
97#[cfg(feature = "aws_polly")]
98pub use backends::{PollyConfig, PollyEngine};
99
100#[cfg(feature = "edge_tts")]
101pub use backends::edge_tts::is_edge_tts_available;
102#[cfg(feature = "edge_tts")]
103pub use backends::EdgeTtsEngine;
104
105/// Create a voice engine by name, with optional backend-specific config.
106///
107/// Supported names depend on enabled features: `"piper"`, `"piper_embedded"`, `"kokoro_embedded"`, `"sherpa_embedded"`, `"models_tts"` (aliases: `"model_tts"`, `"tts"`; generic local dispatcher), `"espeak"`, `"edge_tts"`, `"polly"`.
108/// Returns [VoiceError::UnknownEngine] if the name is unknown or the backend is not enabled.
109///
110/// # Example
111///
112/// ```no_run
113/// # #[allow(clippy::unwrap_used)]
114/// # #[cfg(feature = "espeak")]
115/// # {
116/// use product_os_voice::{create_engine, VoiceEngine, VoiceOptions};
117///
118/// let engine = create_engine("espeak", None).expect("espeak feature enabled");
119/// let audio = engine.synthesize("Hello!", &VoiceOptions::default()).unwrap();
120/// # }
121/// ```
122pub fn create_engine(
123 name: &str,
124 config: Option<EngineConfig>,
125) -> Result<std::sync::Arc<dyn VoiceEngine>, VoiceError> {
126 backends::create_engine(name, config)
127}