1. 1//! Offline voice engines. Each is an operator-installed executable reached by
2. 2//! path, never a shell command, run with an empty environment so provider
3. 3//! credentials cannot leak into it (invariant 12). Neither engine is bundled:
4. 4//! an unconfigured engine fails closed rather than pretending silence is
5. 5//! speech or a transcript. Callers resolve the paths ([`TRANSCRIBER_VAR`],
6. 6//! [`TTS_VAR`]) through the configuration chain; this crate never reads the
7. 7//! environment.
8. 8use crate::{SpeakFormat, VoiceError};
9. 9use std::path::PathBuf;
10. 10use std::process::Stdio;
11. 11use tokio::io::{AsyncReadExt, AsyncWriteExt};
12. 12use tokio::process::Command;
13. 13use tokio_util::sync::CancellationToken;
14. 14
15. 15const MAX_ENGINE_OUTPUT_BYTES: u64 = 16 * 1024 * 1024;
16. 16
17. 17/// Names the local speech-to-text executable.
18. 18pub const TRANSCRIBER_VAR: &str = "VAK_LOCAL_TRANSCRIBER";
19. 19/// Names the local text-to-speech executable.
20. 20pub const TTS_VAR: &str = "VAK_LOCAL_TTS";
21. 21
22. 22/// Read-only readiness of one local engine for administration and doctor
23. 23/// surfaces. It inspects filesystem metadata only; it never executes the
24. 24/// program and never exposes inherited environment values.
25. 25#[derive(Debug, Clone, serde::Serialize)]
26. 26pub struct EngineReadiness {
27. 27 pub configured: bool,
28. 28 pub ready: bool,
29. 29 pub executable: Option<String>,
30. 30 pub detail: String,
31. 31}
32. 32
33. 33pub fn engine_readiness(executable: Option<&std::path::Path>) -> EngineReadiness {
34. 34 let Some(path) = executable else {
35. 35 return EngineReadiness {
36. 36 configured: false,
37. 37 ready: false,
38. 38 executable: None,
39. 39 detail: "not configured".into(),
40. 40 };
41. 41 };
42. 42 let (ready, detail) = match std::fs::metadata(path) {
43. 43 Ok(meta) if meta.is_file() => (true, "executable is present".to_string()),
44. 44 Ok(_) => (false, "configured path is not a regular file".to_string()),
45. 45 Err(error) => (
46. 46 false,
47. 47 format!("configured executable is unavailable: {error}"),
48. 48 ),
49. 49 };
50. 50 EngineReadiness {
51. 51 configured: true,
52. 52 ready,
53. 53 executable: Some(path.display().to_string()),
54. 54 detail,
55. 55 }
56. 56}
57. 57
58. 58/// Local speech-to-text. The executable ([`TRANSCRIBER_VAR`]) receives
59. 59/// encoded audio on stdin — WAV from the voice socket, the channel's own
60. 60/// container otherwise — and writes the transcript to stdout.
61. 61pub struct LocalTranscriber {
62. 62 executable: Option<PathBuf>,
63. 63}
64. 64
65. 65impl LocalTranscriber {
66. 66 pub fn new(executable: Option<PathBuf>) -> Self {
67. 67 Self { executable }
68. 68 }
69. 69
70. 70 /// The transcript, trimmed. An engine that hears nothing may print
71. 71 /// nothing; that is an empty transcript, not an engine failure.
72. 72 pub async fn transcribe(
73. 73 &self,
74. 74 audio: &[u8],
75. 75 cancel: &CancellationToken,
76. 76 ) -> Result<String, VoiceError> {
77. 77 if audio.is_empty() {
78. 78 return Err(VoiceError::InvalidRequest("audio must not be empty".into()));
79. 79 }
80. 80 let Some(executable) = &self.executable else {
81. 81 return Err(VoiceError::Unavailable(
82. 82 "local transcription is unavailable: configure VAK_LOCAL_TRANSCRIBER to an executable that reads audio on stdin and writes text on stdout".into(),
83. 83 ));
84. 84 };
85. 85 let output = run_engine(executable, &[], audio, cancel, "local transcription").await?;
86. 86 let text = String::from_utf8(output).map_err(|_| {
87. 87 VoiceError::Unavailable("local transcription returned non UTF-8 output".into())
88. 88 })?;
89. 89 Ok(text.trim().to_owned())
90. 90 }
91. 91}
92. 92
93. 93/// Local text-to-speech. The executable ([`TTS_VAR`]) is invoked with the
94. 94/// requested encoding as its only argument (`wav`, `pcm16`, `ogg_opus` or
95. 95/// `mp3`), receives UTF-8 text on stdin and writes that encoding to stdout;
96. 96/// the bytes are returned unchanged.
97. 97pub struct LocalTtsSpeaker {
98. 98 executable: Option<PathBuf>,
99. 99}
100. 100
101. 101impl LocalTtsSpeaker {
102. 102 pub fn new(executable: Option<PathBuf>) -> Self {
103. 103 Self { executable }
104. 104 }
105. 105
106. 106 pub async fn speak(
107. 107 &self,
108. 108 text: &str,
109. 109 format: SpeakFormat,
110. 110 cancel: &CancellationToken,
111. 111 ) -> Result<Vec<u8>, VoiceError> {
112. 112 if text.trim().is_empty() {
113. 113 return Err(VoiceError::InvalidRequest(
114. 114 "speech text must not be empty".into(),
115. 115 ));
116. 116 }
117. 117 let Some(executable) = &self.executable else {
118. 118 return Err(VoiceError::Unavailable("local TTS is unavailable: configure VAK_LOCAL_TTS to an executable that reads UTF-8 text on stdin and writes audio on stdout".into()));
119. 119 };
120. 120 let audio = run_engine(
121. 121 executable,
122. 122 &[format.as_arg()],
123. 123 text.as_bytes(),
124. 124 cancel,
125. 125 "local TTS",
126. 126 )
127. 127 .await?;
128. 128 if audio.is_empty() {
129. 129 return Err(VoiceError::Unavailable(
130. 130 "local TTS returned empty audio".into(),
131. 131 ));
132. 132 }
133. 133 Ok(audio)
134. 134 }
135. 135}
136. 136
137. 137async fn run_engine(
138. 138 executable: &std::path::Path,
139. 139 args: &[&str],
140. 140 input: &[u8],
141. 141 cancel: &CancellationToken,
142. 142 label: &str,
143. 143) -> Result<Vec<u8>, VoiceError> {
144. 144 if cancel.is_cancelled() {
145. 145 return Err(VoiceError::Cancelled);
146. 146 }
147. 147 let mut child = Command::new(executable)
148. 148 .args(args)
149. 149 .env_clear()
150. 150 .stdin(Stdio::piped())
151. 151 .stdout(Stdio::piped())
152. 152 .stderr(Stdio::piped())
153. 153 .kill_on_drop(true)
154. 154 .spawn()
155. 155 .map_err(|error| {
156. 156 VoiceError::Unavailable(format!("{label} engine could not start: {error}"))
157. 157 })?;
158. 158 if let Some(mut stdin) = child.stdin.take() {
159. 159 stdin
160. 160 .write_all(input)
161. 161 .await
162. 162 .map_err(|error| VoiceError::Unavailable(format!("{label} input failed: {error}")))?;
163. 163 }
164. 164 let (Some(stdout), Some(stderr)) = (child.stdout.take(), child.stderr.take()) else {
165. 165 return Err(VoiceError::Unavailable(format!(
166. 166 "{label} did not provide output pipes"
167. 167 )));
168. 168 };
169. 169 let mut output = Vec::new();
170. 170 let mut diagnostics = Vec::new();
171. 171 let mut stdout = stdout.take(MAX_ENGINE_OUTPUT_BYTES + 1);
172. 172 let mut stderr = stderr.take(4096);
173. 173 // Drain both pipes together: an engine that fills stderr while stdout is
174. 174 // unread would otherwise block forever.
175. 175 let read = async {
176. 176 tokio::try_join!(
177. 177 stdout.read_to_end(&mut output),
178. 178 stderr.read_to_end(&mut diagnostics)
179. 179 )
180. 180 };
181. 181 tokio::select! {
182. 182 result = read => {
183. 183 result.map_err(|error| VoiceError::Unavailable(format!("{label} output failed: {error}")))?;
184. 184 }
185. 185 () = cancel.cancelled() => {
186. 186 let _ = child.kill().await;
187. 187 return Err(VoiceError::Cancelled);
188. 188 }
189. 189 }
190. 190 if output.len() as u64 > MAX_ENGINE_OUTPUT_BYTES {
191. 191 let _ = child.kill().await;
192. 192 return Err(VoiceError::InvalidRequest(format!(
193. 193 "{label} output exceeds 16 MiB"
194. 194 )));
195. 195 }
196. 196 let status = child
197. 197 .wait()
198. 198 .await
199. 199 .map_err(|error| VoiceError::Unavailable(format!("{label} failed: {error}")))?;
200. 200 if !status.success() {
201. 201 let detail = String::from_utf8_lossy(&diagnostics).trim().to_owned();
202. 202 return Err(VoiceError::Unavailable(format!(
203. 203 "{label} engine exited unsuccessfully{}",
204. 204 if detail.is_empty() {
205. 205 String::new()
206. 206 } else {
207. 207 format!(": {detail}")
208. 208 }
209. 209 )));
210. 210 }
211. 211 Ok(output)
212. 212}
213. 213
214. 214#[cfg(test)]
215. 215#[allow(clippy::expect_used, clippy::unwrap_used)]
216. 216mod tests {
217. 217 use super::*;
218. 218
219. 219 #[cfg(unix)]
220. 220 fn script(name: &str, body: &str) -> PathBuf {
221. 221 use std::os::unix::fs::PermissionsExt;
222. 222 let path = std::env::temp_dir().join(format!(
223. 223 "vak-voice-{name}-{}-{}",
224. 224 std::process::id(),
225. 225 std::time::SystemTime::now()
226. 226 .duration_since(std::time::UNIX_EPOCH)
227. 227 .expect("clock is after epoch")
228. 228 .as_nanos()
229. 229 ));
230. 230 std::fs::write(&path, body).unwrap();
231. 231 let mut perms = std::fs::metadata(&path).unwrap().permissions();
232. 232 perms.set_mode(0o700);
233. 233 std::fs::set_permissions(&path, perms).unwrap();
234. 234 path
235. 235 }
236. 236
237. 237 #[tokio::test]
238. 238 async fn transcription_fails_closed_without_an_installed_engine() {
239. 239 let result = LocalTranscriber::new(None)
240. 240 .transcribe(&[0, 0], &CancellationToken::new())
241. 241 .await;
242. 242 assert!(matches!(result, Err(VoiceError::Unavailable(_))));
243. 243 }
244. 244
245. 245 #[cfg(unix)]
246. 246 #[tokio::test]
247. 247 async fn local_engine_receives_audio_without_provider_secrets() {
248. 248 let path = script(
249. 249 "stt",
250. 250 "#!/bin/sh\nif [ -n \"$GEMINI_API_KEY\" ] || [ -n \"$OPENAI_API_KEY\" ]; then exit 9; fi\ncat >/dev/null\nprintf 'offline transcript\\n'\n",
251. 251 );
252. 252 let result = LocalTranscriber::new(Some(path.clone()))
253. 253 .transcribe(&[1, 2, 3], &CancellationToken::new())
254. 254 .await;
255. 255 let _ = std::fs::remove_file(&path);
256. 256 assert_eq!(result.unwrap(), "offline transcript");
257. 257 }
258. 258
259. 259 #[cfg(unix)]
260. 260 #[tokio::test]
261. 261 async fn an_engine_that_hears_nothing_returns_an_empty_transcript() {
262. 262 let path = script("stt-empty", "#!/bin/sh\ncat >/dev/null\n");
263. 263 let result = LocalTranscriber::new(Some(path.clone()))
264. 264 .transcribe(&[1, 2], &CancellationToken::new())
265. 265 .await;
266. 266 let _ = std::fs::remove_file(&path);
267. 267 assert_eq!(result.unwrap(), "");
268. 268 }
269. 269
270. 270 #[cfg(unix)]
271. 271 #[tokio::test]
272. 272 async fn a_failing_engine_reports_its_stderr() {
273. 273 let path = script(
274. 274 "stt-fail",
275. 275 "#!/bin/sh\ncat >/dev/null\necho 'model missing' >&2\nexit 3\n",
276. 276 );
277. 277 let result = LocalTranscriber::new(Some(path.clone()))
278. 278 .transcribe(&[1, 2], &CancellationToken::new())
279. 279 .await;
280. 280 let _ = std::fs::remove_file(&path);
281. 281 let error = result.unwrap_err().to_string();
282. 282 assert!(error.contains("model missing"), "{error}");
283. 283 }
284. 284
285. 285 #[tokio::test]
286. 286 async fn local_tts_fails_closed_without_an_installed_engine() {
287. 287 let result = LocalTtsSpeaker::new(Some("/definitely/missing/vak-tts".into()))
288. 288 .speak("hello", SpeakFormat::Wav, &CancellationToken::new())
289. 289 .await;
290. 290 assert!(matches!(result, Err(VoiceError::Unavailable(_))));
291. 291 }
292. 292
293. 293 #[cfg(unix)]
294. 294 #[tokio::test]
295. 295 async fn local_tts_receives_text_and_returns_audio() {
296. 296 let path = script(
297. 297 "tts",
298. 298 "#!/bin/sh\n[ \"$1\" = mp3 ] || exit 4\ncat >/dev/null\nprintf 'audio-bytes'\n",
299. 299 );
300. 300 let audio = LocalTtsSpeaker::new(Some(path.clone()))
301. 301 .speak("hello", SpeakFormat::Mp3, &CancellationToken::new())
302. 302 .await;
303. 303 let _ = std::fs::remove_file(&path);
304. 304 assert_eq!(audio.unwrap(), b"audio-bytes");
305. 305 }
306. 306}
307. 307