Caption Local API v1

Loopback-only, multiple trusted producers. Use the local page or a trusted local client. There is no CORS allowance, authentication layer, multi-tenant isolation or permanent store.

Health

GET /health is available only after model load and actual decoder warmup. It returns ready, version, sample_rate (16000), max_seconds (12), multilingual, model, languages, device, compute_type, modes, translation_target, busy, completed, and failed. Precision is the requested CTranslate2 compute mode; internal hardware fallback may differ. A native watchdog exits if an individual running inference remains busy for more than 90 seconds. Use Docker or systemd for automatic restart.

Stream scheduling

One request may upload, queue or run per stream. Independent streams share FIFO worker admission. Default limits: twelve sessions, one inference worker, twenty seconds queue wait, ten seconds upload time, and twelve seconds audio per chunk. A busy stream receives 429 without buffering a second body. At most twelve bodies can exist at default capacity. Increase workers with --workers; use the same setting for the model and scheduler (the CLI handles this).

Idle sessions and their retry caches expire opportunistically after 120 seconds. DELETE /streams/{stream_id} with X-Caption-Local: 1 closes an idle session and forgets its cached results immediately; a busy session returns 409. Stop and drain before closing. The browser does this automatically on successful Stop. There is no persistent reservation while a stream is silent beyond the idle timeout.

Health additionally reports max_streams, workers, threads_per_worker, beam_size, sessions, running, pending (uploads plus queued requests), queue_timeout, rejected (busy/capacity admission refusals), and queue_timeouts. queue_seconds excludes upload and inference. A cached retry returns the original timing values. Stream IDs are not credentials: local trusted clients can access this API and must use distinct, unguessable IDs to avoid accidental collisions.

Transcribe

POST /transcribe?language=es&mode=both

Required headers:

Content-Type: application/octet-stream
X-Caption-Local: 1
Optional X-Stream-ID: 8–80 ASCII letters, numbers, _ or -; use a random UUID per input stream. Omission uses the shared legacy stream.
Optional X-Request-ID: 8–80 ASCII letters, numbers, _ or -.

Body: little-endian float32 mono PCM, 16 kHz, normalized to [-1, 1], finite samples, 0.01–12 seconds. No WAV header. Upload time is limited to ten seconds.

language defaults to en and accepts Whisper language codes or auto. mode is transcribe (default), translate (English only), or both. English-only models reject non-English languages and translation modes.

{
  "text": "Bienvenidos al teatro.",
  "transcript": "Bienvenidos al teatro.",
  "translation": "Welcome to the theatre.",
  "language": "es",
  "output_language": "es",
  "translation_language": "en",
  "mode": "both",
  "audio_seconds": 3.0,
  "committed_seconds": 3.0,
  "request_id": "example-12345678",
  "stream_id": "example-stream-123",
  "queue_seconds": 0.2,
  "inference_seconds": 0.8
}

Timings are illustrative. text is the transcript except in translate-only mode, where it is the English translation. language describes source speech; output_language describes text. Unrequested output fields are empty strings. Silence with automatic detection can return language: null.

Rolling windows

Add window=1, final=0, and context_seconds=0.5 to decode an unfinished window. Context is previously committed audio retained at the front, from zero to one second. At least two seconds of new audio are required for an unfinished window.

The decoder retains the last second of unfinished speech and emits only decoded words ending before that cutoff. committed_seconds identifies how far the caller may advance in the supplied audio. Retain 0.5 seconds before this point as context for the next window; append new audio after the old uncommitted tail. Do not advance by the request's whole duration. On a pause or Stop, send final=1 (the default), which commits the complete supplied window. The browser's tested buffer implementation is in static/audio-buffer.js.

For translation, the service first chooses the source-language word boundary and then translates only the newly committed audio. Both outputs therefore correspond to the same committed source interval. Word timestamps are estimates: this method reduces boundary artifacts but cannot guarantee perfect word alignment.

Retry and error behavior

Reuse the same stream ID and request ID with identical audio and options after a lost response. Successful results are kept in memory for up to 120 seconds, with at most 64 entries per stream. Different audio/options with a cached ID returns 409. The cache does not survive server restart and does not guarantee exactly-once delivery to external caption relays. A client disconnect does not unlock a running worker.

Status	Meaning	Client action
400	Invalid audio, language, mode, context or ID	Correct input; retain audio if recoverable
403	Wrong/missing local header or foreign Origin	Use the local page/client
408	Upload exceeded ten seconds	Retry the same request ID
409	Reused ID with different input	Fix client ID handling
413 / 415	Oversized audio / wrong content type	Correct the request
429	Stream busy, stream capacity reached, or queue deadline exceeded	Honor Retry-After and retain pending audio
500	Inference failed	Retain audio; inspect server logs, then retry
503	HTTP concurrency limit or restarting service	Back off and retry

The browser retries network errors and 408/429/502/503/504 up to three times after the first attempt, then stops capture with manual recovery controls. It never silently discards a failed request. Response caching is disabled at the HTTP layer; transcripts are not saved to disk by the service.

6.0 KiB Raw Permalink Blame History Unescape Escape