From c3254c3da0253a60d9975fd9d99dfc94a8533dda Mon Sep 17 00:00:00 2001 From: hauke Date: Thu, 5 Nov 2026 16:20:30 +0100 Subject: [PATCH] feat #14740: deepscript transcriber Co-Authored-By: Claude Opus 5.5 (1M context) --- crates/core/Cargo.toml | 1 + crates/core/src/lib.rs | 1 + crates/core/src/transcribe/deepscript.rs | 624 +++++++++++++++++++++++ crates/core/src/transcribe/mod.rs | 128 +++++ 4 files changed, 754 insertions(+) create mode 100644 crates/core/src/transcribe/deepscript.rs create mode 100644 crates/core/src/transcribe/mod.rs diff --git a/crates/core/Cargo.toml b/crates/core/Cargo.toml index d2aa100..8f6fc62 100644 --- a/crates/core/Cargo.toml +++ b/crates/core/Cargo.toml @@ -26,3 +26,4 @@ tokio = { version = "1", features = ["rt", "fs", "time", "macros"] } [dev-dependencies] tempfile = "3" +tokio = { version = "1", features = ["test-util"] } diff --git a/crates/core/src/lib.rs b/crates/core/src/lib.rs index 53189a4..087fad1 100644 --- a/crates/core/src/lib.rs +++ b/crates/core/src/lib.rs @@ -15,6 +15,7 @@ pub mod retention; pub mod secrets; pub mod settings; pub mod store; +pub mod transcribe; #[cfg(any(test, feature = "test-util"))] pub mod testing; diff --git a/crates/core/src/transcribe/deepscript.rs b/crates/core/src/transcribe/deepscript.rs new file mode 100644 index 0000000..3bb02d5 --- /dev/null +++ b/crates/core/src/transcribe/deepscript.rs @@ -0,0 +1,624 @@ +//! [`Transcriber`] implementation talking to DeepScript +//! (`https://api.deepscript.com/v1`), per its OpenAPI 3.1 spec. + +use std::path::Path; +use std::sync::atomic::{AtomicBool, Ordering}; +use std::sync::Arc; +use std::time::Duration; + +use async_trait::async_trait; +use serde::Deserialize; +use tokio::time::Instant; + +use crate::http::{ + HttpBody, HttpRequest, HttpResponse, HttpTransport, Method, Part, TransportError, +}; +use crate::model::Word; + +use super::{TranscribeError, TranscribeOptions, Transcriber}; + +const DEFAULT_BASE_URL: &str = "https://api.deepscript.com/v1"; +const DEFAULT_POLL_INTERVAL: Duration = Duration::from_secs(5); +const DEFAULT_MAX_WAIT: Duration = Duration::from_secs(60 * 60); + +/// DeepScript client. Build with [`DeepScript::new`]; the `with_*` builders +/// exist so tests can shrink `poll_interval`/`max_wait` and point +/// `base_url` at whatever a [`crate::testing::FakeTransport`] expects. +pub struct DeepScript { + transport: Arc, + api_key: String, + base_url: String, + poll_interval: Duration, + max_wait: Duration, + /// Set once an unrecognized status string has been logged, so `wait` + /// doesn't spam the log while polling. + warned_unknown_status: AtomicBool, +} + +impl DeepScript { + pub fn new(transport: Arc, api_key: String) -> Self { + DeepScript { + transport, + api_key, + base_url: DEFAULT_BASE_URL.to_string(), + poll_interval: DEFAULT_POLL_INTERVAL, + max_wait: DEFAULT_MAX_WAIT, + warned_unknown_status: AtomicBool::new(false), + } + } + + pub fn with_base_url(mut self, base_url: impl Into) -> Self { + self.base_url = base_url.into(); + self + } + + pub fn with_poll_interval(mut self, poll_interval: Duration) -> Self { + self.poll_interval = poll_interval; + self + } + + pub fn with_max_wait(mut self, max_wait: Duration) -> Self { + self.max_wait = max_wait; + self + } + + fn auth_header(&self) -> (String, String) { + ( + "Authorization".to_string(), + format!("Bearer {}", self.api_key), + ) + } + + /// Sends `req` and maps transport-level failures to [`TranscribeError`]. + /// A non-2xx response is *not* an error here; callers inspect + /// `resp.status` themselves. + async fn send(&self, req: HttpRequest) -> Result { + self.transport.send(req).await.map_err(|e| match e { + TransportError::Timeout => TranscribeError::Timeout, + TransportError::Io(msg) | TransportError::Network(msg) => { + TranscribeError::Transport(msg) + } + }) + } + + async fn fetch_detail(&self, remote_id: &str) -> Result { + let req = HttpRequest { + method: Method::Get, + url: format!("{}/transcriptions/{remote_id}", self.base_url), + headers: vec![self.auth_header()], + body: HttpBody::Empty, + }; + let resp = self.send(req).await?; + match resp.status { + 200 => resp + .json::>() + .map(|envelope| envelope.data) + .map_err(|e| TranscribeError::Failed(format!("ungültige Antwort: {e}"))), + other => Err(error_for_status(other, &resp.body)), + } + } + + async fn collect_words(&self, remote_id: &str) -> Result, TranscribeError> { + let detail = self.fetch_detail(remote_id).await?; + let words = detail + .result_json + .map(|result| result.words) + .unwrap_or_default() + .into_iter() + .map(|w| Word { + text: w.word, + start: w.start, + end: w.end, + speaker: w.speaker, + }) + .collect(); + Ok(words) + } + + async fn collect_failure(&self, remote_id: &str) -> Result, TranscribeError> { + let detail = self.fetch_detail(remote_id).await?; + let message = detail + .error_message + .unwrap_or_else(|| "unbekannter Fehler".to_string()); + if message.starts_with("NO_SPOKEN_AUDIO") { + Ok(Vec::new()) + } else { + Err(TranscribeError::Failed(message)) + } + } +} + +#[async_trait] +impl Transcriber for DeepScript { + async fn submit( + &self, + audio: &Path, + opts: &TranscribeOptions, + ) -> Result { + if self.api_key.is_empty() { + return Err(TranscribeError::MissingKey); + } + + let file_name = audio + .file_name() + .map(|n| n.to_string_lossy().into_owned()) + .unwrap_or_else(|| "audio".to_string()); + let is_flac = audio + .extension() + .and_then(|e| e.to_str()) + .is_some_and(|e| e.eq_ignore_ascii_case("flac")); + let mime = if is_flac { "audio/flac" } else { "audio/wav" }; + + let mut parts = vec![ + Part::File { + name: "file".to_string(), + file_name, + path: audio.to_path_buf(), + mime: mime.to_string(), + }, + Part::Text { + name: "model".to_string(), + value: opts.model.clone(), + }, + Part::Text { + name: "language".to_string(), + value: opts.language.clone(), + }, + ]; + if opts.single_speaker { + parts.push(Part::Text { + name: "num_speakers".to_string(), + value: "1".to_string(), + }); + } + + let req = HttpRequest { + method: Method::Post, + url: format!("{}/transcriptions", self.base_url), + headers: vec![self.auth_header()], + body: HttpBody::Multipart(parts), + }; + + let resp = self.send(req).await?; + match resp.status { + 202 => resp + .json::>() + .map(|envelope| envelope.data.id) + .map_err(|e| TranscribeError::Failed(format!("ungültige Antwort: {e}"))), + 402 => Err(TranscribeError::InsufficientBalance), + 422 => Err(TranscribeError::Rejected(problem_slug(&resp.body))), + other => Err(error_for_status(other, &resp.body)), + } + } + + async fn wait(&self, remote_id: &str) -> Result, TranscribeError> { + let deadline = Instant::now() + self.max_wait; + loop { + if Instant::now() >= deadline { + return Err(TranscribeError::Timeout); + } + + let req = HttpRequest { + method: Method::Get, + url: format!("{}/transcriptions/{remote_id}/status", self.base_url), + headers: vec![self.auth_header()], + body: HttpBody::Empty, + }; + let resp = self.send(req).await?; + match resp.status { + 200 => { + let envelope: DataEnvelope = resp + .json() + .map_err(|e| TranscribeError::Failed(format!("ungültige Antwort: {e}")))?; + match envelope.data.status.as_str() { + "completed" => return self.collect_words(remote_id).await, + "failed" => return self.collect_failure(remote_id).await, + "queued" | "processing" => {} + other => { + if !self.warned_unknown_status.swap(true, Ordering::Relaxed) { + eprintln!( + "DeepScript: unbekannter Transkriptionsstatus '{other}', warte weiter" + ); + } + } + } + } + other => return Err(error_for_status(other, &resp.body)), + } + + tokio::time::sleep(self.poll_interval).await; + } + } + + async fn delete(&self, remote_id: &str) -> Result<(), TranscribeError> { + let req = HttpRequest { + method: Method::Delete, + url: format!("{}/transcriptions/{remote_id}", self.base_url), + headers: vec![self.auth_header()], + body: HttpBody::Empty, + }; + let resp = self.send(req).await?; + match resp.status { + 204 | 404 => Ok(()), + other => Err(error_for_status(other, &resp.body)), + } + } +} + +/// Maps a non-2xx status that isn't handled specially by the caller (401, +/// 429, and a generic fallback carrying the problem body's `detail`/`title` +/// — the set shared by every DeepScript endpoint). +fn error_for_status(status: u16, body: &[u8]) -> TranscribeError { + match status { + 401 => TranscribeError::Unauthorized, + 429 => TranscribeError::Transport("Rate limit".to_string()), + _ => TranscribeError::Failed(format!("HTTP {status}: {}", problem_message(body))), + } +} + +/// RFC 7807 `application/problem+json` body (the shape DeepScript uses for +/// every error response). +#[derive(Deserialize, Default)] +struct ProblemBody { + #[serde(rename = "type")] + type_: Option, + title: Option, + detail: Option, +} + +fn parse_problem(body: &[u8]) -> ProblemBody { + serde_json::from_slice(body).unwrap_or_default() +} + +/// `detail`, falling back to `title`, for a problem+json body. +fn problem_message(body: &[u8]) -> String { + let problem = parse_problem(body); + problem + .detail + .or(problem.title) + .unwrap_or_else(|| "unbekannter Fehler".to_string()) +} + +/// The last path segment of a problem+json body's `type` slug-URL, e.g. +/// `"unsupported-format"` for `https://deepscript.com/errors/unsupported-format`. +fn problem_slug(body: &[u8]) -> String { + let problem = parse_problem(body); + problem + .type_ + .and_then(|t| t.rsplit('/').next().map(str::to_string)) + .unwrap_or_else(|| "unknown".to_string()) +} + +#[derive(Deserialize)] +struct DataEnvelope { + data: T, +} + +#[derive(Deserialize)] +struct SubmitData { + id: String, +} + +#[derive(Deserialize)] +struct StatusData { + status: String, +} + +#[derive(Deserialize)] +struct DetailData { + #[serde(rename = "errorMessage")] + error_message: Option, + #[serde(rename = "resultJson")] + result_json: Option, +} + +#[derive(Deserialize)] +struct ResultJson { + words: Vec, +} + +#[derive(Deserialize)] +struct ApiWord { + word: String, + start: f64, + end: f64, + speaker: Option, +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::http::HttpBody; + use crate::testing::FakeTransport; + + const BASE: &str = "https://api.deepscript.com/v1"; + + fn opts(model: &str, language: &str, single_speaker: bool) -> TranscribeOptions { + TranscribeOptions { + language: language.to_string(), + model: model.to_string(), + single_speaker, + } + } + + fn deep_script(transport: &Arc) -> DeepScript { + DeepScript::new(transport.clone(), "test-key".to_string()) + .with_poll_interval(Duration::ZERO) + } + + #[tokio::test] + async fn submit_sends_multipart_with_single_speaker_hint() { + let transport = Arc::new(FakeTransport::new()); + transport.expect( + Method::Post, + &format!("{BASE}/transcriptions"), + 202, + r#"{"data":{"id":"job-1","status":"queued","model":"premium","originalFileName":"mic.flac","createdOn":"2026-01-01T00:00:00Z"}}"#, + ); + let ds = deep_script(&transport); + + let id = ds + .submit(Path::new("mic.flac"), &opts("premium", "de", true)) + .await + .unwrap(); + + assert_eq!(id, "job-1"); + let requests = transport.requests(); + assert_eq!(requests.len(), 1); + let req = &requests[0]; + assert_eq!(req.url, format!("{BASE}/transcriptions")); + assert_eq!(req.header("authorization"), Some("Bearer test-key")); + let HttpBody::Multipart(parts) = &req.body else { + panic!("expected multipart body, got {:?}", req.body); + }; + assert!(parts.contains(&Part::File { + name: "file".to_string(), + file_name: "mic.flac".to_string(), + path: Path::new("mic.flac").to_path_buf(), + mime: "audio/flac".to_string(), + })); + assert!(parts.contains(&Part::Text { + name: "model".to_string(), + value: "premium".to_string(), + })); + assert!(parts.contains(&Part::Text { + name: "language".to_string(), + value: "de".to_string(), + })); + assert!(parts.contains(&Part::Text { + name: "num_speakers".to_string(), + value: "1".to_string(), + })); + transport.assert_done(); + } + + #[tokio::test] + async fn submit_without_hint_for_output_track() { + let transport = Arc::new(FakeTransport::new()); + transport.expect( + Method::Post, + &format!("{BASE}/transcriptions"), + 202, + r#"{"data":{"id":"job-2","status":"queued","model":"premium","originalFileName":"output.wav","createdOn":"2026-01-01T00:00:00Z"}}"#, + ); + let ds = deep_script(&transport); + + let id = ds + .submit(Path::new("output.wav"), &opts("premium", "de", false)) + .await + .unwrap(); + + assert_eq!(id, "job-2"); + let requests = transport.requests(); + let HttpBody::Multipart(parts) = &requests[0].body else { + panic!("expected multipart body"); + }; + assert!(parts.contains(&Part::File { + name: "file".to_string(), + file_name: "output.wav".to_string(), + path: Path::new("output.wav").to_path_buf(), + mime: "audio/wav".to_string(), + })); + assert!(!parts + .iter() + .any(|p| matches!(p, Part::Text { name, .. } if name == "num_speakers"))); + transport.assert_done(); + } + + #[tokio::test] + async fn wait_polls_until_completed_and_maps_words() { + let transport = Arc::new(FakeTransport::new()); + let status_url = format!("{BASE}/transcriptions/job-3/status"); + transport.expect( + Method::Get, + &status_url, + 200, + r#"{"data":{"id":"job-3","status":"queued","progress":0}}"#, + ); + transport.expect( + Method::Get, + &status_url, + 200, + r#"{"data":{"id":"job-3","status":"processing","progress":50}}"#, + ); + transport.expect( + Method::Get, + &status_url, + 200, + r#"{"data":{"id":"job-3","status":"completed","progress":100}}"#, + ); + transport.expect( + Method::Get, + &format!("{BASE}/transcriptions/job-3"), + 200, + r#"{"data":{"id":"job-3","status":"completed","resultJson":{"words":[ + {"word":"Hallo","start":0.0,"end":0.4,"speaker":"0"}, + {"word":"wie","start":0.5,"end":0.7,"speaker":"1"}, + {"word":"geht's","start":0.8,"end":1.2,"speaker":"1"} + ]}}}"#, + ); + let ds = deep_script(&transport); + + let words = ds.wait("job-3").await.unwrap(); + + assert_eq!( + words, + vec![ + Word { + text: "Hallo".to_string(), + start: 0.0, + end: 0.4, + speaker: Some("0".to_string()), + }, + Word { + text: "wie".to_string(), + start: 0.5, + end: 0.7, + speaker: Some("1".to_string()), + }, + Word { + text: "geht's".to_string(), + start: 0.8, + end: 1.2, + speaker: Some("1".to_string()), + }, + ] + ); + transport.assert_done(); + } + + #[tokio::test] + async fn no_spoken_audio_is_empty_track() { + let transport = Arc::new(FakeTransport::new()); + transport.expect( + Method::Get, + &format!("{BASE}/transcriptions/job-4/status"), + 200, + r#"{"data":{"id":"job-4","status":"failed"}}"#, + ); + transport.expect( + Method::Get, + &format!("{BASE}/transcriptions/job-4"), + 200, + r#"{"data":{"id":"job-4","status":"failed","errorMessage":"NO_SPOKEN_AUDIO: nothing detected in track"}}"#, + ); + let ds = deep_script(&transport); + + let words = ds.wait("job-4").await.unwrap(); + + assert_eq!(words, Vec::::new()); + transport.assert_done(); + } + + #[tokio::test] + async fn failed_other_error_is_failed() { + let transport = Arc::new(FakeTransport::new()); + transport.expect( + Method::Get, + &format!("{BASE}/transcriptions/job-5/status"), + 200, + r#"{"data":{"id":"job-5","status":"failed"}}"#, + ); + transport.expect( + Method::Get, + &format!("{BASE}/transcriptions/job-5"), + 200, + r#"{"data":{"id":"job-5","status":"failed","errorMessage":"ENGINE_CRASH: decoder died"}}"#, + ); + let ds = deep_script(&transport); + + let err = ds.wait("job-5").await.unwrap_err(); + + assert_eq!( + err, + TranscribeError::Failed("ENGINE_CRASH: decoder died".to_string()) + ); + transport.assert_done(); + } + + #[tokio::test] + async fn maps_401_and_402() { + let transport = Arc::new(FakeTransport::new()); + transport.expect( + Method::Post, + &format!("{BASE}/transcriptions"), + 401, + r#"{"type":"https://deepscript.com/errors/unauthorized","title":"Unauthorized","status":401,"detail":"Missing Authorization header."}"#, + ); + let ds = deep_script(&transport); + let err = ds + .submit(Path::new("mic.flac"), &opts("premium", "de", true)) + .await + .unwrap_err(); + assert_eq!(err, TranscribeError::Unauthorized); + transport.assert_done(); + + let transport = Arc::new(FakeTransport::new()); + transport.expect( + Method::Post, + &format!("{BASE}/transcriptions"), + 402, + r#"{"type":"https://deepscript.com/errors/insufficient-balance","title":"Insufficient balance","status":402,"detail":"Top up your workspace."}"#, + ); + let ds = deep_script(&transport); + let err = ds + .submit(Path::new("mic.flac"), &opts("premium", "de", true)) + .await + .unwrap_err(); + assert_eq!(err, TranscribeError::InsufficientBalance); + transport.assert_done(); + } + + #[tokio::test] + async fn delete_treats_404_as_ok() { + let transport = Arc::new(FakeTransport::new()); + transport.expect( + Method::Delete, + &format!("{BASE}/transcriptions/job-6"), + 404, + "", + ); + let ds = deep_script(&transport); + + ds.delete("job-6").await.unwrap(); + + transport.assert_done(); + } + + #[tokio::test] + async fn missing_key_sends_nothing() { + let transport = Arc::new(FakeTransport::new()); + let ds = DeepScript::new(transport.clone(), String::new()); + + let err = ds + .submit(Path::new("mic.flac"), &opts("premium", "de", true)) + .await + .unwrap_err(); + + assert_eq!(err, TranscribeError::MissingKey); + assert!(transport.requests().is_empty()); + transport.assert_done(); + } + + #[tokio::test(start_paused = true)] + async fn wait_times_out_after_max_wait() { + let transport = Arc::new(FakeTransport::new()); + let status_url = format!("{BASE}/transcriptions/job-7/status"); + for _ in 0..3 { + transport.expect( + Method::Get, + &status_url, + 200, + r#"{"data":{"id":"job-7","status":"processing"}}"#, + ); + } + let ds = DeepScript::new(transport.clone(), "test-key".to_string()) + .with_poll_interval(Duration::from_secs(10)) + .with_max_wait(Duration::from_secs(30)); + + let err = ds.wait("job-7").await.unwrap_err(); + + assert_eq!(err, TranscribeError::Timeout); + transport.assert_done(); + } +} diff --git a/crates/core/src/transcribe/mod.rs b/crates/core/src/transcribe/mod.rs new file mode 100644 index 0000000..9967d3d --- /dev/null +++ b/crates/core/src/transcribe/mod.rs @@ -0,0 +1,128 @@ +//! Speech-to-text seam: each call's mic/output track is submitted to a +//! remote transcription service, polled until done, and mapped to +//! [`crate::model::Word`]s. [`deepscript::DeepScript`] is the only +//! implementation today (Task 12); a fake implementing [`Transcriber`] is +//! how later tasks (call processing pipeline) unit-test without the +//! network. + +pub mod deepscript; + +use std::path::Path; + +use async_trait::async_trait; + +use crate::model::Word; + +/// Per-track options for a transcription request. +#[derive(Debug, Clone, PartialEq)] +pub struct TranscribeOptions { + /// ISO 639-1 code, or `"auto"`. + pub language: String, + /// Provider-specific model identifier (e.g. DeepScript's `"premium"`). + pub model: String, + /// Hint that the track has exactly one speaker (the mic track, always + /// the user) — the output track may have several, so this is left + /// unset there. + pub single_speaker: bool, +} + +/// Uploads an audio file to a remote speech-to-text service, waits for the +/// result and cleans up afterwards. +#[async_trait] +pub trait Transcriber: Send + Sync { + /// Uploads `audio` and returns the service's id for the resulting job. + async fn submit( + &self, + audio: &Path, + opts: &TranscribeOptions, + ) -> Result; + + /// Polls until the job referenced by `remote_id` finishes, returning its + /// words (empty if the service detected no spoken audio). + async fn wait(&self, remote_id: &str) -> Result, TranscribeError>; + + /// Deletes the job and its uploaded audio at the remote service. + async fn delete(&self, remote_id: &str) -> Result<(), TranscribeError>; +} + +/// Everything that can go wrong talking to a transcription service. +#[derive(Debug, Clone, PartialEq)] +pub enum TranscribeError { + /// No API key configured; nothing was sent. + MissingKey, + /// The API key was rejected. + Unauthorized, + /// The account/workspace balance is too low to proceed. + InsufficientBalance, + /// The service rejected the upload itself (bad format, too large, ...). + /// Carries the problem type's slug, e.g. `"unsupported-format"`. + Rejected(String), + /// The job failed for a reason other than "no spoken audio", or a + /// request got an unexpected non-2xx response. + Failed(String), + /// Gave up waiting after `max_wait`. + Timeout, + /// The request could not be sent, or its response could not be read. + Transport(String), +} + +impl TranscribeError { + /// German, user-facing text for this error. Never includes the API key. + pub fn user_message(&self) -> String { + match self { + TranscribeError::MissingKey => { + "API-Schlüssel für DeepScript fehlt – bitte in den Einstellungen eintragen." + .to_string() + } + TranscribeError::Unauthorized => { + "DeepScript hat den API-Schlüssel abgelehnt.".to_string() + } + TranscribeError::InsufficientBalance => "DeepScript-Guthaben aufgebraucht.".to_string(), + TranscribeError::Rejected(slug) => { + format!("DeepScript hat die Datei abgelehnt ({slug}).") + } + TranscribeError::Failed(msg) => format!("Transkription fehlgeschlagen: {msg}"), + TranscribeError::Timeout => { + "Transkription dauert zu lange – bitte erneut versuchen.".to_string() + } + TranscribeError::Transport(msg) => format!("Keine Verbindung zu DeepScript: {msg}"), + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn user_message_texts_are_german() { + assert_eq!( + TranscribeError::MissingKey.user_message(), + "API-Schlüssel für DeepScript fehlt – bitte in den Einstellungen eintragen." + ); + assert_eq!( + TranscribeError::Unauthorized.user_message(), + "DeepScript hat den API-Schlüssel abgelehnt." + ); + assert_eq!( + TranscribeError::InsufficientBalance.user_message(), + "DeepScript-Guthaben aufgebraucht." + ); + assert_eq!( + TranscribeError::Rejected("unsupported-format".to_string()).user_message(), + "DeepScript hat die Datei abgelehnt (unsupported-format)." + ); + assert_eq!( + TranscribeError::Failed("boom".to_string()).user_message(), + "Transkription fehlgeschlagen: boom" + ); + assert_eq!( + TranscribeError::Timeout.user_message(), + "Transkription dauert zu lange – bitte erneut versuchen." + ); + assert_eq!( + TranscribeError::Transport("Rate limit".to_string()).user_message(), + "Keine Verbindung zu DeepScript: Rate limit" + ); + } +}