//! [`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); /// How many status polls in a row may fail transiently (network, timeout, /// HTTP 429/5xx) before `wait` gives up. const MAX_POLL_RETRIES: u32 = 3; /// 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(transport_error) } /// Asks for the status of `remote_id` once. async fn poll_status(&self, remote_id: &str) -> Result { let req = HttpRequest { method: Method::Get, url: format!("{}/transcriptions/{remote_id}/status", self.base_url), headers: vec![self.auth_header()], body: HttpBody::Empty, follow_redirects: true, }; let resp = match self.transport.send(req).await { Ok(resp) => resp, Err(e @ (TransportError::Network(_) | TransportError::Timeout)) => { return Err(PollError::Transient(transport_error(e))) } Err(e) => return Err(PollError::Fatal(transport_error(e))), }; match resp.status { 200 => resp .json::>() .map(|envelope| envelope.data.status) .map_err(|e| { PollError::Fatal(TranscribeError::Failed(format!("ungültige Antwort: {e}"))) }), 429 | 500..=599 => Err(PollError::Transient(error_for_status( resp.status, &resp.body, ))), other => Err(PollError::Fatal(error_for_status(other, &resp.body))), } } 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, follow_redirects: true, }; 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(), }); } if !opts.vocabulary.is_empty() { parts.push(Part::Text { name: "vocabulary".to_string(), // The documented format: "JSON array of custom words, or // comma-separated string." value: serde_json::to_string(&opts.vocabulary) .expect("Vec always serializes"), }); } let req = HttpRequest { method: Method::Post, url: format!("{}/transcriptions", self.base_url), headers: vec![self.auth_header()], body: HttpBody::Multipart(parts), follow_redirects: true, }; 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)), } } /// Polls until the job is done. A poll that fails transiently is retried /// at the normal interval, up to [`MAX_POLL_RETRIES`] times in a row. async fn wait(&self, remote_id: &str) -> Result, TranscribeError> { let deadline = Instant::now() + self.max_wait; let mut failed_polls = 0; loop { if Instant::now() >= deadline { return Err(TranscribeError::Timeout); } match self.poll_status(remote_id).await { Ok(status) => { failed_polls = 0; match 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) { log::warn!( "DeepScript: unbekannter Transkriptionsstatus '{other}', warte weiter" ); } } } } Err(PollError::Transient(e)) if failed_polls < MAX_POLL_RETRIES => { failed_polls += 1; log::warn!( "DeepScript: Statusabfrage für {remote_id} fehlgeschlagen ({}), Versuch {failed_polls} von {MAX_POLL_RETRIES}", e.user_message() ); } Err(PollError::Transient(e) | PollError::Fatal(e)) => return Err(e), } 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, follow_redirects: true, }; let resp = self.send(req).await?; match resp.status { 204 | 404 => Ok(()), other => Err(error_for_status(other, &resp.body)), } } } /// A failed status poll: `Transient` ones (network, timeout, HTTP 429/5xx) /// are worth retrying. enum PollError { Transient(TranscribeError), Fatal(TranscribeError), } fn transport_error(e: TransportError) -> TranscribeError { match e { TransportError::Timeout => TranscribeError::Timeout, TransportError::Io(msg) | TransportError::Network(msg) => TranscribeError::Transport(msg), } } /// 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, vocabulary: Vec::new(), } } 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_sends_vocabulary_as_a_json_array_string() { let transport = Arc::new(FakeTransport::new()); transport.expect( Method::Post, &format!("{BASE}/transcriptions"), 202, r#"{"data":{"id":"job-voc","status":"queued","model":"premium","originalFileName":"mic.flac","createdOn":"2026-01-01T00:00:00Z"}}"#, ); let ds = deep_script(&transport); let mut vocab_opts = opts("premium", "de", true); vocab_opts.vocabulary = vec!["Tschüss".to_string(), "Euvino".to_string()]; ds.submit(Path::new("mic.flac"), &vocab_opts).await.unwrap(); let requests = transport.requests(); let HttpBody::Multipart(parts) = &requests[0].body else { panic!("expected multipart body"); }; assert!(parts.contains(&Part::Text { name: "vocabulary".to_string(), value: r#"["Tschüss","Euvino"]"#.to_string(), })); transport.assert_done(); } #[tokio::test] async fn submit_omits_vocabulary_when_empty() { let transport = Arc::new(FakeTransport::new()); transport.expect( Method::Post, &format!("{BASE}/transcriptions"), 202, r#"{"data":{"id":"job-novoc","status":"queued","model":"premium","originalFileName":"mic.flac","createdOn":"2026-01-01T00:00:00Z"}}"#, ); let ds = deep_script(&transport); ds.submit(Path::new("mic.flac"), &opts("premium", "de", true)) .await .unwrap(); let requests = transport.requests(); let HttpBody::Multipart(parts) = &requests[0].body else { panic!("expected multipart body"); }; assert!(!parts .iter() .any(|p| matches!(p, Part::Text { name, .. } if name == "vocabulary"))); 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] async fn wait_retries_a_transient_status_error() { let transport = Arc::new(FakeTransport::new()); let status_url = format!("{BASE}/transcriptions/job-8/status"); transport.expect(Method::Get, &status_url, 503, ""); transport.expect( Method::Get, &status_url, 200, r#"{"data":{"id":"job-8","status":"completed"}}"#, ); transport.expect( Method::Get, &format!("{BASE}/transcriptions/job-8"), 200, r#"{"data":{"id":"job-8","status":"completed","resultJson":{"words":[]}}}"#, ); let ds = deep_script(&transport); let words = ds.wait("job-8").await.unwrap(); assert_eq!(words, Vec::::new()); transport.assert_done(); } #[tokio::test] async fn wait_gives_up_after_four_transient_errors_in_a_row() { let transport = Arc::new(FakeTransport::new()); let status_url = format!("{BASE}/transcriptions/job-9/status"); // A successful poll in between resets the count. for status in [503, 429, 200, 502, 503, 500, 503] { let body = if status == 200 { r#"{"data":{"id":"job-9","status":"processing"}}"# } else { r#"{"title":"Service Unavailable"}"# }; transport.expect(Method::Get, &status_url, status, body); } let ds = deep_script(&transport); let err = ds.wait("job-9").await.unwrap_err(); assert_eq!( err, TranscribeError::Failed("HTTP 503: Service Unavailable".to_string()) ); transport.assert_done(); } #[tokio::test] async fn wait_does_not_retry_a_client_error() { let transport = Arc::new(FakeTransport::new()); transport.expect( Method::Get, &format!("{BASE}/transcriptions/job-10/status"), 401, "", ); let ds = deep_script(&transport); let err = ds.wait("job-10").await.unwrap_err(); assert_eq!(err, TranscribeError::Unauthorized); 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(); } }