feat: POST /v1/transcribe batch endpoint + integration docs

[concil859856]

Adds HTTP batch transcription to the same pod so the Studio file-upload path can reuse the Parakeet model without a separate batch service.

Changes

• POST /v1/transcribe — accepts any audio (WAV/MP3/M4A/etc.), auto-resamples to 16 kHz mono, returns JSON with text + latency
• python-multipart dependency for FastAPI File/Form parsing
• docs/integration.md — protocol reference for the dashboard backend
• Bug fixes from local testing: api name mismatches between ws.py and metrics/vad/healthz

Tested

Local RTX 4090 build + smoke tests:

• WS /v1/stream: start → ready → final → clean close (1000)
• HTTP /v1/transcribe with synthesized speech: returned exact transcript (5.2s audio, 103ms latency)

Summary by CodeRabbit

Release Notes

• New Features

  • Added authenticated batch transcription endpoint for uploading audio files and receiving transcribed text with language, duration, and latency information.

• Documentation

  • Added integration guide documenting Voice backend endpoints, authentication, supported audio formats, batch and streaming message flows, health/metrics endpoints, and deployment guidance.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: a41d2027-c111-429c-994d-0a752967b2a0

📥 Commits

Reviewing files that changed from the base of the PR and between 7bd6b17 and 39df136.

📒 Files selected for processing (3)

• docs/integration.md
• pyproject.toml
• src/stt_streaming/server.py

---

📝 Walkthrough

Walkthrough

This PR introduces a batch HTTP audio transcription endpoint for the stt-streaming service. It adds comprehensive API documentation, integration instructions for upstream services, and server-side implementation with audio validation, decoding, and transcription execution.

Changes

Batch Transcription Endpoint

Layer / File(s)	Summary
Batch API Contract and Integration Documentation docs/integration.md	The new integration guide documents the POST /v1/transcribe endpoint contract (multipart request/response fields, error codes), provides code examples for updating upstream transcription services with pod selection logic and fallback routing, and describes health/metrics endpoints and migration strategy for co-running batch and streaming pods.
Batch Endpoint Implementation with Audio Decoding pyproject.toml, src/stt_streaming/server.py	The endpoint handler validates uploaded files, decodes audio to 16kHz mono float32 with soundfile (falling back to librosa), runs transcription in a background executor, records request metrics, and returns JSON with transcribed text, language, duration, latency, and model name. The python-multipart dependency is added to support form data parsing.

Sequence Diagram

sequenceDiagram
  participant Client
  participant Server
  participant Executor
  participant Model
  Client->>Server: POST /v1/transcribe<br/>(audio file, language, X-API-Key)
  Server->>Server: Validate file (non-empty,<br/>size ≤ 100MB)
  Server->>Server: Decode audio to 16kHz<br/>mono float32
  Server->>Executor: Run transcription<br/>(in background)
  Executor->>Model: model._run_transcribe(audio)
  Model->>Executor: Return transcribed text
  Server->>Server: Record metrics<br/>(latency, size)
  Server->>Client: Return JSON<br/>(text, language, duration,<br/>latency, model_name)

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 A batch of audio files arrive,
Via multipart they come alive,
Decoded to sixteen-kHz sound,
The model spins and looks around,
Returns the words it heard so clear,
The streaming future's finally here! ✨

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch ops

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}