asr-core 0.0.3

Unified streaming, offline, and cloud speech-to-text engine for Rust
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
//! The ASR server: one prepared engine, exposed over the OpenAI-compatible
//! transcription API (`serve-openai-http`).
//!
//! [`run`] answers `POST /v1/audio/transcriptions` with the same multipart
//! shape the `backend-openai-http` client sends, and returns the same
//! `{"text": ...}` body that client parses (or plain text under
//! `response_format=text`) — client and server are the two
//! halves of one protocol, defined once in this crate. A host can point its
//! existing OpenAI-compatible callers at a locally prepared engine without
//! any client change. `GET /health` and `GET /v1/models` exist for
//! orchestration and for clients that list models before they talk.
//!
//! `stream=true` answers `text/event-stream`: the `transcript.text.delta`
//! / `transcript.text.done` / `error` events the client's `HttpResponse::Sse`
//! mode parses — the same wire for both halves of the protocol. Engines
//! with an incremental endpoint (streaming zipformer, cloud backends)
//! emit deltas as the transcription runs; a client disconnect cancels the
//! session. Engines without one (the offline families) keep the 400
//! refusal — see [`Transcribe::supports_streaming`].
//!
//! The engine face is a trait ([`Transcribe`]) so the handlers test against
//! a mock without any model files; [`Engine`](crate::Engine) is the
//! production implementor. The engine is prepared once by the host (the
//! seconds-to-minutes part, which is the whole point of a server) and
//! shared across requests: each
//! request runs its own recognition session through
//! [`Engine::transcribe`](crate::Engine::transcribe),
//! bounded by the engine's `max_active_sessions` — a request beyond that
//! budget is refused with 503, never queued.
//!
//! Memory contract: the multipart upload is fully buffered (bounded by
//! [`ServeOptions::max_body_bytes`], a limit enforced on the body stream
//! itself, so over-limit uploads are cut off mid-flight) and the decoded
//! mono f32 result is resident before any session limit applies — the same
//! decode-layer contract [`crate::audio::decode_audio`] documents; the
//! per-request budget is enforced twice, cooperatively by the engine's
//! deadline and forcibly by an HTTP-layer hard wall (the streaming path
//! has no wall — headers are already sent, so the cooperative deadline
//! alone bounds it).
//!
//! Engine assembly (family detection, model loading) stays with the host:
//! it prepares an [`Engine`](crate::Engine) from its own model
//! configuration and hands it
//! to [`run`] or [`router`].

use serde::{Deserialize, Serialize};
use serde_json::json;
use std::net::SocketAddr;
use std::sync::Arc;
use std::time::{Duration, Instant};

use axum::extract::{
    multipart::MultipartError, DefaultBodyLimit, FromRequest, Multipart, Request, State,
};
use axum::http::StatusCode;
use axum::response::sse::{Event, KeepAlive, Sse};
use axum::response::{IntoResponse, Response};
use axum::routing::{get, post};
use axum::{Json, Router};
use futures::StreamExt;

use crate::{
    AsrError, AudioBuffer, ErrorKind, SessionFailure, SessionOptions, SessionOutcome,
    SessionResult, TranscriptSnapshotSink,
};

pub mod delta;
use delta::TextDeltaBuilder;

/// The engine face the handlers consume, as a trait so tests (and hosts)
/// can run the server over a stand-in without any model load;
/// [`Engine`](crate::Engine) is the production implementor. A host may wrap
/// `Engine` with metrics,
/// queueing or retries and serve the wrapper instead.
pub trait Transcribe: Send + Sync {
    fn transcribe(
        &self,
        buffer: &AudioBuffer,
        options: SessionOptions,
        deadline: Instant,
    ) -> SessionResult;

    /// Whether [`Transcribe::transcribe_streaming`] carries progress for
    /// this engine. The handler refuses `stream=true` with a 400 up front
    /// when this is false — a wrapper that does not override the streaming
    /// face keeps the pre-streaming contract instead of a stream that
    /// never carries progress. Override both methods together (or
    /// neither).
    fn supports_streaming(&self) -> bool {
        false
    }

    /// The streaming face `stream=true` requests transcribe through: same
    /// one-shot upload, plus a sink receiving the full emerging transcript
    /// each time it changes (a snapshot to overwrite, not a delta —
    /// see [`TranscriptSnapshotSink`]). The default implementation refuses, so an
    /// engine that reports [`Transcribe::supports_streaming`] but does not
    /// override this still fails the request instead of stalling.
    fn transcribe_streaming(
        &self,
        buffer: &AudioBuffer,
        options: SessionOptions,
        deadline: Instant,
        progress: TranscriptSnapshotSink,
    ) -> SessionResult {
        let _ = (buffer, options, deadline, progress);
        Err(Box::new(SessionFailure {
            error: AsrError::new(
                ErrorKind::UnsupportedCapability,
                "serve",
                "this engine wrapper does not expose streaming progress",
            ),
            outcome: SessionOutcome::default(),
        }))
    }
}

impl Transcribe for crate::Engine {
    fn transcribe(
        &self,
        buffer: &AudioBuffer,
        options: SessionOptions,
        deadline: Instant,
    ) -> SessionResult {
        crate::Engine::transcribe(self, buffer, options, deadline)
    }

    fn supports_streaming(&self) -> bool {
        // The dedicated capability flag (not `partial_results`): the two
        // can diverge for a future backend that reports session partials
        // without a serve-streamable incremental face, or vice versa.
        self.capabilities().streaming_transcription
    }

    fn transcribe_streaming(
        &self,
        buffer: &AudioBuffer,
        options: SessionOptions,
        deadline: Instant,
        progress: TranscriptSnapshotSink,
    ) -> SessionResult {
        crate::Engine::transcribe_streaming(self, buffer, options, deadline, progress)
    }
}

fn default_bind() -> String {
    "127.0.0.1:8080".to_string()
}

fn default_max_body_bytes() -> usize {
    25 * 1024 * 1024
}

fn default_max_audio_secs() -> u64 {
    3600
}

fn default_model_id() -> String {
    "asr-core".to_string()
}

fn default_family() -> String {
    "unknown".to_string()
}

/// The server's one-time configuration, fixed when the engine is prepared:
/// `language` is pinned at startup — the engine config cannot switch
/// languages at runtime, so a request naming a different language is
/// refused with an explanation rather than silently transcribed under the
/// wrong one.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct ServeOptions {
    /// Address to listen on (used by [`run`] only), e.g. `127.0.0.1:8080`.
    #[serde(default = "default_bind")]
    pub bind: String,
    /// Request body cap. The multipart upload is fully buffered before any
    /// check runs, so this is the memory ceiling per in-flight request.
    /// The default matches the OpenAI API's own 25 MiB transcription
    /// upload cap; asr-core's client default (24 MiB) fits beneath it.
    #[serde(default = "default_max_body_bytes")]
    pub max_body_bytes: usize,
    /// Decode budget in seconds of audio (measured against 48 kHz, the
    /// highest supported decode rate): longer uploads are refused with 400
    /// before the engine sees them.
    #[serde(default = "default_max_audio_secs")]
    pub max_audio_secs: u64,
    /// Per-request hard wall; `None` stretches with the audio length
    /// (`max(120s, audio_secs * 3)` — local inference usually runs faster
    /// than real time, so the stretch never bites early).
    pub timeout_secs: Option<u64>,
    /// The recognition language pinned by the engine config, if given.
    pub language: Option<String>,
    /// Model id reported by `/v1/models` and `/health`.
    #[serde(default = "default_model_id")]
    pub model_id: String,
    /// Engine family name reported by `/health`.
    #[serde(default = "default_family")]
    pub family: String,
}

impl Default for ServeOptions {
    fn default() -> Self {
        Self {
            bind: default_bind(),
            max_body_bytes: default_max_body_bytes(),
            max_audio_secs: default_max_audio_secs(),
            timeout_secs: None,
            language: None,
            model_id: default_model_id(),
            family: default_family(),
        }
    }
}

/// The router over an already-prepared engine. Public so hosts can run the
/// server inside their own axum app ([`run`] is the batteries-included
/// listener); `bind` in `options` is only meaningful to `run`.
pub fn router(engine: Arc<dyn Transcribe>, options: ServeOptions) -> Router {
    let max_body_bytes = options.max_body_bytes;
    let state = Arc::new(AppState { engine, options });
    Router::new()
        .route("/v1/audio/transcriptions", post(transcriptions))
        .route("/v1/models", get(models_list))
        .route("/health", get(health))
        .layer(DefaultBodyLimit::max(max_body_bytes))
        .with_state(state)
}

struct AppState {
    engine: Arc<dyn Transcribe>,
    options: ServeOptions,
}

async fn transcriptions(State(state): State<Arc<AppState>>, req: Request) -> Response {
    // The extractor's rejection is only the missing/invalid boundary
    // (a malformed request); size and stream errors surface through the
    // field reads below, where the 413 mapping lives. The body limit is
    // not a middleware pass over the buffered request: `Multipart`'s only
    // constructor wraps the body in a cumulative stream limit, so an
    // over-limit upload is cut off mid-flight, never fully buffered.
    let mut multipart = match Multipart::from_request(req, &state).await {
        Ok(multipart) => multipart,
        Err(error) => {
            return error_response(
                StatusCode::BAD_REQUEST,
                format!("invalid multipart request: {error}"),
            )
        }
    };
    let mut file: Option<axum::body::Bytes> = None;
    let mut language: Option<String> = None;
    let mut response_format = "json".to_string();
    let mut stream = false;
    loop {
        let field = match multipart.next_field().await {
            Ok(Some(field)) => field,
            Ok(None) => break,
            Err(error) => return multipart_error(&error),
        };
        match field.name() {
            Some("file") => match field.bytes().await {
                Ok(bytes) => file = Some(bytes),
                Err(error) => return multipart_error(&error),
            },
            Some("language") => match field.text().await {
                Ok(text) => language = Some(text).filter(|s| !s.trim().is_empty()),
                Err(error) => return multipart_error(&error),
            },
            Some("response_format") => match field.text().await {
                Ok(text) => response_format = text,
                Err(error) => return multipart_error(&error),
            },
            Some("stream") => match field.text().await {
                Ok(text) => stream = matches!(text.trim(), "true" | "1"),
                Err(error) => return multipart_error(&error),
            },
            // `model` names a model the server does not select on (the
            // engine was loaded at startup); `prompt`/`temperature` have
            // no offline counterpart. Accepted, ignored.
            _ => {}
        }
    }
    let Some(bytes) = file else {
        return error_response(
            StatusCode::BAD_REQUEST,
            "multipart field 'file' is required",
        );
    };
    if response_format != "json" && response_format != "text" {
        return error_response(
            StatusCode::BAD_REQUEST,
            format!(
                "unsupported response_format '{response_format}'; only 'json' and \
                 'text' are supported"
            ),
        );
    }
    if stream && response_format != "json" {
        return error_response(
            StatusCode::BAD_REQUEST,
            "streaming requires response_format 'json' (SSE data frames carry JSON \
             events); drop 'stream' or use response_format 'json'",
        );
    }
    if let Some(requested) = &language {
        match &state.options.language {
            Some(pinned) if pinned == requested => {}
            Some(pinned) => {
                return error_response(
                    StatusCode::BAD_REQUEST,
                    format!(
                        "this server pins language '{pinned}'; the engine cannot \
                         switch languages at runtime — restart it with language \
                         '{requested}'"
                    ),
                );
            }
            None => {
                return error_response(
                    StatusCode::BAD_REQUEST,
                    "this server was started without a pinned language; the engine \
                     cannot switch languages at runtime — restart it with language \
                     '<lang>'",
                );
            }
        }
    }
    let engine = state.engine.clone();
    let options = state.options.clone();
    // Decode first, off the tokio workers: the request budget stretches
    // with the decoded length, so it does not exist until the audio is
    // known.
    let buffer = match tokio::task::spawn_blocking({
        let options = options.clone();
        move || decode_upload(&bytes, options.max_audio_secs)
    })
    .await
    {
        Ok(Ok(buffer)) => buffer,
        Ok(Err(error)) => {
            return error_response(
                StatusCode::BAD_REQUEST,
                format!("audio decoding failed: {error}"),
            )
        }
        Err(join) => {
            return error_response(
                StatusCode::INTERNAL_SERVER_ERROR,
                format!("decoding task failed: {join}"),
            )
        }
    };
    let (session_options, budget) = session_plan(&buffer, &options);
    let deadline = Instant::now() + budget;
    if stream {
        // The pre-flight probe (not the trait default's runtime refusal):
        // engines without an incremental endpoint — the offline families —
        // keep answering 400 here, as they did before streaming existed.
        if !state.engine.supports_streaming() {
            return error_response(
                StatusCode::BAD_REQUEST,
                "streaming responses are not supported by this engine (no incremental \
                 endpoint); drop 'stream' and read the json body",
            );
        }
        return streaming_transcription(state.engine.clone(), buffer, session_options, deadline);
    }
    // The budget is enforced twice: the engine checks the deadline
    // cooperatively, and the HTTP layer holds a hard wall around the
    // blocking call for engines that never look at it. `spawn_blocking`
    // work cannot be cancelled, so a hung engine still occupies its
    // thread until it returns — the wall bounds the request, not the
    // thread.
    let outcome = tokio::time::timeout(
        budget,
        tokio::task::spawn_blocking(move || {
            engine
                .transcribe(&buffer, session_options, deadline)
                .map(|outcome| outcome.transcript.text())
                .map_err(|failure| engine_failure(&failure))
        }),
    )
    .await;
    match outcome {
        Ok(Ok(Ok(text))) if response_format == "text" => text.into_response(),
        Ok(Ok(Ok(text))) => Json(json!({ "text": text })).into_response(),
        Ok(Ok(Err(failure))) => failure_response(failure),
        Ok(Err(join)) => error_response(
            StatusCode::INTERNAL_SERVER_ERROR,
            format!("transcription task failed: {join}"),
        ),
        Err(_elapsed) => error_response(
            StatusCode::GATEWAY_TIMEOUT,
            format!("transcription exceeded the request budget ({budget:?})"),
        ),
    }
}

/// The `stream=true` half: an SSE response whose data frames carry the
/// same events asr-core's own SSE client parses — `transcript.text.delta`
/// per progress snapshot (the delta against the last frame, since the
/// engine reports snapshots while the wire format is incremental),
/// `transcript.text.done` with the final text, and `error` — then the
/// stream ends.
///
/// Progress crosses the sync/async boundary through a watch channel, not
/// an mpsc: `send_replace` never blocks, so a stalled client cannot park
/// the engine thread — the newest snapshot simply replaces the queued one,
/// which is what makes the partial display lag behind without delaying
/// recognition. `is_closed` detects the receiver being dropped: a client
/// that disconnects fails the sink, the engine cancels its session, and
/// the watch closing turns the engine call's own outcome into the terminal
/// frame.
fn streaming_transcription(
    engine: Arc<dyn Transcribe>,
    buffer: AudioBuffer,
    session_options: SessionOptions,
    deadline: Instant,
) -> Response {
    let (progress_tx, progress_rx) = tokio::sync::watch::channel(String::new());
    let sink = TranscriptSnapshotSink::new(move |text| {
        progress_tx.send_replace(text.to_string());
        !progress_tx.is_closed()
    });
    let handle = tokio::task::spawn_blocking(move || {
        engine
            .transcribe_streaming(&buffer, session_options, deadline, sink)
            .map(|outcome| outcome.transcript.text())
            .map_err(|failure| engine_failure(&failure))
    });
    // The JoinHandle rides the unfold state as an Option: the terminal
    // frame consumes it, so the next poll sees None and the stream ends —
    // progress frames carry it along untouched.
    let events = futures::stream::unfold(
        (Some(handle), progress_rx, TextDeltaBuilder::new()),
        |(handle, mut progress, mut deltas)| async move {
            let mut handle = handle;
            // The previous poll emitted the terminal frame.
            handle.as_ref()?;
            let event = loop {
                // An Err means the engine call has ended (the sender was
                // dropped) with every value observed — its outcome is the
                // terminal frame. A pending unseen value resolves Ok first,
                // so the final delta still precedes done.
                if progress.changed().await.is_err() {
                    match handle.take() {
                        Some(handle) => break terminal_event(handle).await,
                        None => return None,
                    }
                }
                let snapshot = progress.borrow_and_update().clone();
                // Snapshot → append-only delta: snapshots that add nothing
                // expressible (no change, or a revision of sent text) are
                // skipped — see [`TextDeltaBuilder`].
                let Some(delta) = deltas.update(&snapshot) else {
                    continue;
                };
                break sse_event("transcript.text.delta", json!({ "delta": delta }));
            };
            // `handle` is None only when the terminal frame consumed it.
            Some((event, (handle, progress, deltas)))
        },
    );
    Sse::new(events.map(Ok::<_, std::convert::Infallible>))
        .keep_alive(KeepAlive::default())
        .into_response()
}

/// The engine call's terminal frame: the final text, or the failure. The
/// JoinHandle is consumed here — the caller's stream ends right after.
async fn terminal_event(handle: tokio::task::JoinHandle<Result<String, RequestFailure>>) -> Event {
    match handle.await {
        Ok(Ok(text)) => sse_event("transcript.text.done", json!({ "text": text })),
        Ok(Err(failure)) => sse_event("error", json!({ "message": failure_message(&failure) })),
        Err(join) => sse_event(
            "error",
            json!({ "message": format!("transcription task failed: {join}") }),
        ),
    }
}

/// The error message of a [`RequestFailure`], for SSE `error` frames. The
/// status code is decided by the caller of [`failure_response`]; here only
/// the message travels, in the shape asr-core's client surfaces
/// (`SSE error` plus detail).
fn failure_message(failure: &RequestFailure) -> String {
    match failure {
        RequestFailure::BadRequest(message)
        | RequestFailure::Busy(message)
        | RequestFailure::Timeout(message)
        | RequestFailure::Engine(message) => message.clone(),
    }
}

fn sse_event(name: &str, payload: serde_json::Value) -> Event {
    // The event type travels twice: as the SSE `event:` field and inside
    // the JSON data. asr-core's own client (like OpenAI's transcription
    // stream) parses the type out of the JSON `type` field and ignores the
    // SSE field; both are written so either convention can read a frame.
    let mut payload = payload;
    if let Some(object) = payload.as_object_mut() {
        object.insert("type".to_string(), json!(name));
    }
    Event::default().event(name).data(payload.to_string())
}

/// Why a request's transcription failed, in status-code terms.
enum RequestFailure {
    BadRequest(String),
    Busy(String),
    Timeout(String),
    Engine(String),
}

fn failure_response(failure: RequestFailure) -> Response {
    match failure {
        RequestFailure::BadRequest(message) => error_response(StatusCode::BAD_REQUEST, message),
        RequestFailure::Busy(message) => error_response(StatusCode::SERVICE_UNAVAILABLE, message),
        RequestFailure::Timeout(message) => error_response(StatusCode::GATEWAY_TIMEOUT, message),
        RequestFailure::Engine(message) => {
            error_response(StatusCode::INTERNAL_SERVER_ERROR, message)
        }
    }
}

/// Session options and the request budget for one decoded upload. An
/// explicit `timeout_secs` is the hard wall — no silent stretching. The
/// built-in policy stretches with the audio length: audio_secs * 3 keeps
/// slack for inference of long material and never bites before that
/// would.
fn session_plan(buffer: &AudioBuffer, options: &ServeOptions) -> (SessionOptions, Duration) {
    let audio_secs = buffer.samples.len() as u64 / u64::from(buffer.spec.sample_rate.max(1));
    let mut session_options = SessionOptions::new(buffer.spec);
    session_options.max_duration = Duration::from_secs(audio_secs + 60);
    // Transcripts run orders of magnitude below the session default (8 MiB);
    // 2 MiB is already generous headroom for an hour of speech.
    session_options.max_transcript_bytes = 2 * 1024 * 1024;
    let budget = options.timeout_secs.map_or_else(
        || Duration::from_secs((audio_secs * 3).max(120)),
        Duration::from_secs,
    );
    (session_options, budget)
}

/// Why an engine failure maps to which status: Busy is the concurrency
/// budget (503, never queued), Timeout the deadline (504), InvalidInput a
/// malformed request (400), everything else the engine's own fault (500).
fn engine_failure(failure: &SessionFailure) -> RequestFailure {
    let message = format!("transcription failed: {}", failure.error);
    match failure.error.kind {
        ErrorKind::Busy => RequestFailure::Busy(
            "the server is at its concurrent-session limit; retry later".to_string(),
        ),
        ErrorKind::Timeout => RequestFailure::Timeout(message),
        ErrorKind::InvalidInput => RequestFailure::BadRequest(message),
        _ => RequestFailure::Engine(message),
    }
}

/// The decode layer's input policy for uploads: webm containers are
/// refused up front (webm audio is opus in practice and symphonia has no
/// opus decoder — the generic probe error would send callers chasing the
/// wrong fix), and the decoded buffer must be non-empty and within the
/// sample budget. The whole decode result is resident in memory before
/// the budget check runs, so this is a detection, not an allocation guard
/// (see `audio::decode_audio`'s memory contract).
fn decode_upload(bytes: &[u8], max_audio_secs: u64) -> Result<AudioBuffer, AsrError> {
    if is_webm(bytes) {
        return Err(AsrError::new(
            ErrorKind::InvalidInput,
            "serve",
            "webm audio uses opus, which cannot be decoded here; transcode to \
             wav, flac or mp3 first",
        ));
    }
    let buffer = crate::audio::decode_audio(bytes)?;
    if buffer.samples.is_empty() {
        return Err(AsrError::new(
            ErrorKind::InvalidInput,
            "serve",
            "no audio could be decoded from the input",
        ));
    }
    let max_samples = max_audio_secs.saturating_mul(48_000);
    if buffer.samples.len() as u64 > max_samples {
        return Err(AsrError::new(
            ErrorKind::InvalidInput,
            "serve",
            format!(
                "decoded audio exceeds the sample budget ({max_samples} samples); \
                 the input is too long for offline decoding"
            ),
        ));
    }
    Ok(buffer)
}

/// EBML magic plus the DocType element, matched as an anchored whole:
/// element ID 0x4282, size vint 0x84 (the DocType for webm is exactly the
/// four-byte string "webm"), then the string. Searching for the element
/// rather than the bare string keeps stray header bytes from matching;
/// matroska/mka files carry "matroska" instead and do not match. A
/// non-minimal size vint (legal per EBML) — or opus riding in a matroska
/// container — falls through and gets the generic decode error: correct,
/// just less specific.
fn is_webm(bytes: &[u8]) -> bool {
    if !bytes.starts_with(&[0x1A, 0x45, 0xDF, 0xA3]) {
        return false;
    }
    let head = &bytes[..bytes.len().min(128)];
    head.windows(7)
        .any(|w| w == [0x42, 0x82, 0x84, b'w', b'e', b'b', b'm'])
}

async fn health(State(state): State<Arc<AppState>>) -> Response {
    Json(json!({
        "status": "ok",
        "model": state.options.model_id,
        "family": state.options.family,
    }))
    .into_response()
}

async fn models_list(State(state): State<Arc<AppState>>) -> Response {
    Json(json!({
        "object": "list",
        "data": [{
            "id": state.options.model_id,
            "object": "model",
            "created": 0,
            "owned_by": "asr-core",
        }],
    }))
    .into_response()
}

/// The OpenAI-style error body: any OpenAI-compatible caller that reads
/// error payloads gets `{"error": {"message": ...}}`. asr-core's own client
/// only surfaces the status code (and `x-request-id`), so the message is
/// there for the callers that do look.
fn error_response(status: StatusCode, message: impl std::fmt::Display) -> Response {
    let kind = if status.is_client_error() {
        "invalid_request_error"
    } else {
        "server_error"
    };
    (
        status,
        Json(json!({ "error": { "message": message.to_string(), "type": kind } })),
    )
        .into_response()
}

/// Multipart extraction failures carry their own status: a body over
/// `DefaultBodyLimit` is 413, everything else a malformed request (400).
fn multipart_error(error: &MultipartError) -> Response {
    let status = error.status();
    let message = if status == StatusCode::PAYLOAD_TOO_LARGE {
        format!("request body exceeds the server's size limit (max_body_bytes): {error}")
    } else {
        format!("invalid multipart request: {error}")
    };
    error_response(status, message)
}

/// Ctrl+C/SIGTERM stop the accept loop; in-flight requests finish first
/// (axum's graceful shutdown), then the process exits. Only [`run`] shuts
/// the server down — embedder routers live as long as their owners keep
/// them.
async fn shutdown_signal() {
    let ctrl_c = async {
        let _ = tokio::signal::ctrl_c().await;
    };
    #[cfg(unix)]
    let sigterm = async {
        use tokio::signal::unix::{signal, SignalKind};
        match signal(SignalKind::terminate()) {
            Ok(mut term) => {
                term.recv().await;
            }
            // Registration failure parks the future forever so the
            // select still works; the platform keeps its default
            // disposition then.
            Err(_) => std::future::pending::<()>().await,
        }
    };
    #[cfg(not(unix))]
    let sigterm = std::future::pending::<()>();
    tokio::select! {
        _ = ctrl_c => {},
        _ = sigterm => {},
    }
}

/// Bind `options.bind` and serve until Ctrl+C/SIGTERM; in-flight requests
/// finish first (axum's graceful shutdown), then the process exits. The
/// batteries-included entry point — hosts that compose their own axum app
/// use [`router`] instead.
pub async fn run(engine: Arc<dyn Transcribe>, options: ServeOptions) -> Result<(), AsrError> {
    let address: SocketAddr = options.bind.parse().map_err(|_| {
        AsrError::new(
            ErrorKind::InvalidInput,
            "serve",
            format!("invalid bind address '{}'", options.bind),
        )
    })?;
    let app = router(engine, options);
    let listener = tokio::net::TcpListener::bind(address).await.map_err(|e| {
        AsrError::new(
            ErrorKind::Io,
            "serve",
            format!("cannot bind {address}: {e}"),
        )
    })?;
    axum::serve(listener, app)
        .with_graceful_shutdown(shutdown_signal())
        .await
        .map_err(|e| AsrError::new(ErrorKind::Io, "serve", format!("server error: {e}")))?;
    Ok(())
}

#[cfg(test)]
mod tests;