feat: wire SystemEngine rate/pitch/volume to speech-dispatcher, add pause/resume/synth_to_bytes C API

- SystemEngine now calls set_voice_rate_all/pitch_all/volume_all with proper
  float-to-SPD scale conversion (0.1-10.0 range → -100 to +100)
- SystemEngine.pause()/resume() call speech-dispatcher pause_all/resume_all
- New C API: tts_pause(), tts_resume(), tts_synth_to_bytes(), tts_free_bytes()
- Updated tts_wrapper.h with new function declarations
- Fix unused variable warning in factory.rs

Author: willwade

include/tts_wrapper.h

@@ -5,7 +5,6 @@
 
 #include <stdint.h>
 #include <stdbool.h>
-
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -231,8 +230,46 @@ void tts_free_engine_info(struct tts_engine_info *engines, int32_t count);
  */
 const char *tts_get_last_error(void);
 
+/**
+ * Pause in-progress speech.
+ *
+ * # Safety
+ * `ctx` must be valid.
+ */
+void tts_pause(struct tts_ctx *ctx);
+
+/**
+ * Resume paused speech.
+ *
+ * # Safety
+ * `ctx` must be valid.
+ */
+void tts_resume(struct tts_ctx *ctx);
+
+/**
+ * Synthesize text to audio bytes without playback.
+ * Writes a heap-allocated buffer to `*out_bytes` and its length to `*out_len`.
+ * Caller must free with [`tts_free_bytes`].
+ * Returns 0 on success, -1 on failure.
+ *
+ * # Safety
+ * `ctx` must be valid. `out_bytes` and `out_len` must be non-null.
+ */
+int32_t tts_synth_to_bytes(struct tts_ctx *ctx,
+                           const char *text,
+                           uint8_t **out_bytes,
+                           uintptr_t *out_len);
+
+/**
+ * Free a byte buffer returned by [`tts_synth_to_bytes`].
+ *
+ * # Safety
+ * `bytes` must be from `tts_synth_to_bytes` with the matching `len`.
+ */
+void tts_free_bytes(uint8_t *bytes, uintptr_t len);
+
 #ifdef __cplusplus
-}
-#endif
+}  // extern "C"
+#endif  // __cplusplus
 
 #endif  /* TTS_WRAPPER_H */

src/factory.rs

@@ -16,7 +16,7 @@ use crate::system_engine::SystemEngine;
 /// `credentials_json` is a JSON object with engine-specific credentials
 /// (e.g. `{"apiKey": "..."}`). Pass `""` for engines that don't need credentials.
 #[must_use]
-pub fn create_engine(engine_id: &str, credentials_json: &str) -> Option<Box<dyn TtsEngine>> {
+pub fn create_engine(engine_id: &str, _credentials_json: &str) -> Option<Box<dyn TtsEngine>> {
     match engine_id {
         #[cfg(feature = "system")]
         "system" => Some(Box::new(SystemEngine::new())),

src/lib.rs

@@ -557,3 +557,99 @@ pub extern "C" fn tts_get_last_error() -> *const c_char {
         Err(_) => ptr::null(),
     }
 }
+
+/// Pause in-progress speech.
+///
+/// # Safety
+/// `ctx` must be valid.
+#[no_mangle]
+pub extern "C" fn tts_pause(ctx: *mut tts_ctx) {
+    if ctx.is_null() {
+        return;
+    }
+    let ctx_ref = unsafe { &*ctx };
+    let engine = ctx_ref.engine.lock().unwrap();
+    let _ = engine.pause();
+}
+
+/// Resume paused speech.
+///
+/// # Safety
+/// `ctx` must be valid.
+#[no_mangle]
+pub extern "C" fn tts_resume(ctx: *mut tts_ctx) {
+    if ctx.is_null() {
+        return;
+    }
+    let ctx_ref = unsafe { &*ctx };
+    let engine = ctx_ref.engine.lock().unwrap();
+    let _ = engine.resume();
+}
+
+/// Synthesize text to audio bytes without playback.
+/// Writes a heap-allocated buffer to `*out_bytes` and its length to `*out_len`.
+/// Caller must free with [`tts_free_bytes`].
+/// Returns 0 on success, -1 on failure.
+///
+/// # Safety
+/// `ctx` must be valid. `out_bytes` and `out_len` must be non-null.
+#[no_mangle]
+pub extern "C" fn tts_synth_to_bytes(
+    ctx: *mut tts_ctx,
+    text: *const c_char,
+    out_bytes: *mut *mut u8,
+    out_len: *mut usize,
+) -> i32 {
+    if ctx.is_null() || text.is_null() || out_bytes.is_null() || out_len.is_null() {
+        return -1;
+    }
+    let ctx_ref = unsafe { &*ctx };
+    let text_str = unsafe { CStr::from_ptr(text) }
+        .to_string_lossy()
+        .into_owned();
+    let voice = ctx_ref.voice_id.lock().unwrap().clone();
+    let rate = *ctx_ref.rate.lock().unwrap();
+    let pitch = *ctx_ref.pitch.lock().unwrap();
+    let volume = *ctx_ref.volume.lock().unwrap();
+
+    let engine = ctx_ref.engine.lock().unwrap();
+    match engine.synth_to_bytes(&text_str, voice.as_deref(), rate, pitch, volume) {
+        Ok(data) => {
+            if data.is_empty() {
+                unsafe {
+                    *out_bytes = ptr::null_mut();
+                    *out_len = 0;
+                }
+                return 0;
+            }
+            let len = data.len();
+            let layout = std::alloc::Layout::array::<u8>(len).unwrap();
+            let ptr = unsafe { std::alloc::alloc(layout) };
+            unsafe {
+                ptr::copy_nonoverlapping(data.as_ptr(), ptr, len);
+                *out_bytes = ptr;
+                *out_len = len;
+            }
+            0
+        }
+        Err(e) => {
+            *ctx_ref.last_error.lock().unwrap() = e.to_string();
+            -1
+        }
+    }
+}
+
+/// Free a byte buffer returned by [`tts_synth_to_bytes`].
+///
+/// # Safety
+/// `bytes` must be from `tts_synth_to_bytes` with the matching `len`.
+#[no_mangle]
+pub extern "C" fn tts_free_bytes(bytes: *mut u8, len: usize) {
+    if bytes.is_null() || len == 0 {
+        return;
+    }
+    let layout = std::alloc::Layout::array::<u8>(len).unwrap();
+    unsafe {
+        std::alloc::dealloc(bytes, layout);
+    }
+}

src/system_engine.rs

@@ -1,17 +1,13 @@
-//! System TTS engine via speech-dispatcher (Linux).
-
 use crate::engine::{estimate_word_boundaries, TtsEngine};
 use crate::types::{TtsError, TtsResult, Voice};
 use std::sync::Mutex;
 
-/// TTS engine that uses the system's speech-dispatcher daemon.
 #[derive(Debug)]
 pub struct SystemEngine {
     conn: Mutex<Option<speech_dispatcher::Connection>>,
 }
 
 impl SystemEngine {
-    /// Create a new system engine, connecting to speech-dispatcher.
     pub fn new() -> Self {
         let conn = speech_dispatcher::Connection::open(
             "rust-tts-wrapper",
@@ -26,14 +22,26 @@ impl SystemEngine {
     }
 }
 
+fn rate_to_spd(rate: f32) -> i32 {
+    ((rate.clamp(0.1, 10.0) - 1.0) * 100.0).round() as i32
+}
+
+fn pitch_to_spd(pitch: f32) -> i32 {
+    ((pitch.clamp(0.1, 10.0) - 1.0) * 100.0).round() as i32
+}
+
+fn volume_to_spd(volume: f32) -> i32 {
+    ((volume.clamp(0.0, 2.0) - 1.0) * 100.0).round() as i32
+}
+
 impl TtsEngine for SystemEngine {
     fn speak(
         &self,
         text: &str,
         voice: Option<&str>,
-        _rate: f32,
-        _pitch: f32,
-        _volume: f32,
+        rate: f32,
+        pitch: f32,
+        volume: f32,
         _on_audio: Option<crate::engine::OnAudioCallback>,
         mut on_boundary: Option<crate::engine::OnBoundaryCallback>,
     ) -> TtsResult<()> {
@@ -45,6 +53,11 @@ impl TtsEngine for SystemEngine {
         if let Some(v) = voice {
             let _ = conn.set_synthesis_voice_all(v);
         }
+
+        let _ = conn.set_voice_rate_all(rate_to_spd(rate));
+        let _ = conn.set_voice_pitch_all(pitch_to_spd(pitch));
+        let _ = conn.set_volume_all(volume_to_spd(volume));
+
         conn.say(speech_dispatcher::Priority::Important, text);
 
         if let Some(cb) = on_boundary.as_mut() {
@@ -83,6 +96,22 @@ impl TtsEngine for SystemEngine {
             .map_err(|e| TtsError(format!("Stop failed: {e}")))
     }
 
+    fn pause(&self) -> TtsResult<()> {
+        let guard = self.conn.lock().unwrap();
+        if let Some(conn) = guard.as_ref() {
+            let _ = conn.pause_all();
+        }
+        Ok(())
+    }
+
+    fn resume(&self) -> TtsResult<()> {
+        let guard = self.conn.lock().unwrap();
+        if let Some(conn) = guard.as_ref() {
+            let _ = conn.resume_all();
+        }
+        Ok(())
+    }
+
     fn get_voices(&self) -> TtsResult<Vec<Voice>> {
         Ok(vec![])
     }