feat #14740: deepscript transcriber

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
hauke
2026-11-05 16:20:30 +01:00
co-authored by Claude Opus 5.5
parent 3facefeeed
commit c3254c3da0
4 changed files with 754 additions and 0 deletions
+624
View File
@@ -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<dyn HttpTransport>,
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<dyn HttpTransport>, 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<String>) -> 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<HttpResponse, TranscribeError> {
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<DetailData, TranscribeError> {
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::<DataEnvelope<DetailData>>()
.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<Vec<Word>, 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<Vec<Word>, 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<String, TranscribeError> {
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::<DataEnvelope<SubmitData>>()
.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<Vec<Word>, 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<StatusData> = 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<String>,
title: Option<String>,
detail: Option<String>,
}
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<T> {
data: T,
}
#[derive(Deserialize)]
struct SubmitData {
id: String,
}
#[derive(Deserialize)]
struct StatusData {
status: String,
}
#[derive(Deserialize)]
struct DetailData {
#[serde(rename = "errorMessage")]
error_message: Option<String>,
#[serde(rename = "resultJson")]
result_json: Option<ResultJson>,
}
#[derive(Deserialize)]
struct ResultJson {
words: Vec<ApiWord>,
}
#[derive(Deserialize)]
struct ApiWord {
word: String,
start: f64,
end: f64,
speaker: Option<String>,
}
#[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<FakeTransport>) -> 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::<Word>::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();
}
}
+128
View File
@@ -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<String, TranscribeError>;
/// 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<Vec<Word>, 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"
);
}
}