feat(transcribe): add BW Labs STT as optional provider alongside ElevenLabs

[isweluiz]

Summary

Adds BW Labs STT as an optional second transcription provider alongside ElevenLabs Scribe.

• ElevenLabs remains the default — zero breaking changes for existing users
• Calls the BW Labs WebSocket API directly — the only new dependency is websockets (PyPI), declared as an optional extra
• Provider selected via --provider {elevenlabs,bw_stt}, TRANSCRIBE_PROVIDER env var, or auto-detected from whichever API key is present (ElevenLabs wins if both are set)

Usage

pip install websockets            # or: pip install "video-use[bw-stt]"
export BW_STT_API_KEY=bwa_key_... # get one at https://labs.bandwidth.com/
python helpers/transcribe.py clip.mp4 --provider bw_stt
python helpers/transcribe_batch.py raw_videos/ --provider bw_stt

Differences vs ElevenLabs

	ElevenLabs Scribe	BW Labs STT
Pricing	Paid (per-minute credits)	Free
Transport	HTTP multipart	WebSocket streaming
Duration limit	~2h	None
Speaker diarization	Yes	No (all words → speaker_0)
Audio events	Yes ((laughter), …)	No
Language selection	Yes	Auto-detect only
Docs	elevenlabs.io	labs.bandwidth.com/docs/speech-to-text

--language / --num-speakers still work for ElevenLabs and print a note when ignored by BW STT.

Implementation notes

• _call_bw_stt() streams raw PCM over the socket from a background thread while the main thread drains Segment messages — reading only after sending would stall long files once the client receive buffer fills
• Final audio chunk is padded with silence to the API's 20ms frame minimum
• websockets is lazy-imported with a clear install hint, so ElevenLabs users are unaffected
• Output JSON is normalized to the same schema pack_transcripts.py already consumes (type/text/start/end/speaker_id)

Testing

• Existing test suite: 16 passed, no regressions
• Live transcription of a 5-minute clip: 1200 words, timestamps covering full duration, packed cleanly by pack_transcripts.py
• Verified provider auto-detection, TRANSCRIBE_PROVIDER override, and CLI flags on both helpers
• Verified helpers/transcribe.py imports fine without websockets installed (ElevenLabs path untouched)

Known API quirk

BW STT occasionally emits sub-word tokens in words[] (e.g. "bel" + "ieve"). Timestamps remain correct so phrase-boundary detection works; noted here for anyone doing exact word matching.

Files changed

• helpers/transcribe.py — provider dispatch (resolve_provider, detect_provider), _call_bw_stt()
• helpers/transcribe_batch.py — --provider flag, passed through to workers
• pyproject.toml — bw-stt = ["websockets>=12"] optional extra
• .env.example — documents BW_STT_API_KEY and TRANSCRIBE_PROVIDER

---

Summary by cubic

Adds BW Labs STT as an optional transcription provider alongside ElevenLabs, which remains the default; existing ElevenLabs users are unaffected.

Behavior changes

• Provider is chosen via --provider {elevenlabs,bw_stt}, TRANSCRIBE_PROVIDER, or auto-detected from whichever API key is present (ElevenLabs wins if both are set).
• BW STT streams over WebSocket with no duration limit, but skips speaker diarization (all words tagged speaker_0), audio events, and language selection (auto-detect only).
• --language and --num-speakers still work for ElevenLabs and print a note when BW STT ignores them.
• Output JSON is normalized to the same schema pack_transcripts.py already consumes; BW STT may emit sub-word tokens in words[] with correct timestamps.
• If a BW STT WebSocket session closes before the server sends SessionClosed, the run raises an error instead of caching a partial transcript.
• Transcripts now record the provider that produced them; cached transcripts from a different provider are re-transcribed, legacy files without the field count as ElevenLabs, and files with unknown, corrupt, or unreadable provider values are re-transcribed. Batch mode treats any readable transcript as cached when no provider is explicitly set, so an all-cached rerun never needs an API key.

Dependencies

• Adds optional extra bw-stt = ["websockets>=12"]; websockets is lazy-imported, so ElevenLabs users don't need it.

^{Written for commit e1c754b. Summary will update on new commits.}

[cubic-dev-ai]

All reported issues were addressed across 4 files

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 2 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

1 issue found across 2 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="helpers/transcribe_batch.py">

<violation number="1" location="helpers/transcribe_batch.py:106">
P2: When a cache JSON contains a non-string provider such as `null`, auto mode marks it cached because `src != ""` is true, so the batch never repairs the malformed or stale file. Require a nonempty string before accepting an auto-mode cache.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic</sub>