transcribe: add Deepgram nova-3 as an alternative provider

[shoaib90]

Why

Scribe is the only transcription path, so an ElevenLabs key is a hard requirement even for someone who already pays for another ASR. This adds Deepgram as an option — it does not change or deprecate anything.

Why it's small

The pipeline is far less coupled to ElevenLabs than it first appears. transcribe.py is the only module that touches the API, and every downstream consumer reads just five fields per token: {type, text, start, end, speaker_id}. Everything else in a Scribe response is unused.

So this is an adapter, not a second pipeline. pack_transcripts.py and render.py --build-subtitles consume the output unchanged.

Mapping from results.channels[0].alternatives[0].words[]:

Deepgram	→ contract
punctuated_word (fallback word)	text
start / end	passthrough
speaker: 0	speaker_id: "speaker_0"
(no discriminator)	type: "word"
(none)	type: "spacing", synthesized per inter-word gap

Details worth reviewing

smart_format is deliberately OFF, with filler_words=true and punctuate=true on. smart_format rewrites numbers and dates, which is precisely the normalization Hard Rule 8 forbids.

Synthesized spacing tokens. Deepgram sends none. pack_transcripts.py would group phrases correctly anyway, since it also breaks on start - prev_end, but emitting them keeps this a faithful drop-in for any consumer that reads them.

Shared audio front-end. It imports extract_audio, peak_dbfs, count_audio_tracks and transcript_path from transcribe.py rather than copying them, so the audio handling and the cache key cannot drift between providers. Caching, the silent-track guard and --audio-track all behave identically.

--convert <response.json> runs the mapping offline with no API call, which makes the schema testable for free.

Known gap, documented in SKILL.md

Deepgram's standard STT returns no audio-event tokens, so Scribe's (laughter) / (applause) / (sigh) markers are unavailable — the beat signals Cut craft leans on. It does diarize. SKILL.md now says to prefer Scribe for reaction-heavy or multi-speaker material, and to lean on silence gaps plus timeline_view otherwise.

--num-speakers is accepted for parity with transcribe.py but ignored and warned about, since Deepgram auto-detects and takes no hint.

Testing

Verified end to end on real footage: a live nova-3 call produced correct word timings and diarization, pack_transcripts.py grouped phrases with correct S0/S1 tags, and render.py --build-subtitles produced a master.srt with correct Hard Rule 5 output-timeline offsets. tests/ passes (16 tests, 15 subtests).

One field note in case it's useful to others: on a clip where the speaker opened with "Um, so ninety percent…", Deepgram dropped the leading Um, while preserving a mid-sentence uh,. Scribe kept both. Worth knowing if filler removal is the goal.

---

Summary by cubic

Adds Deepgram nova-3 as an alternative transcription provider, so a Deepgram key now works where only an ElevenLabs one did before. It emits the same on-disk schema, so pack_transcripts.py and render.py --build-subtitles consume the output unchanged.

Details worth reviewing

• Reuses the audio front-end and cache key from transcribe.py so the two providers can't drift apart.
• The shared cache is now validated per provider and options: transcripts are stamped with _provider, _model, _language, and _spacing_threshold, and a mismatch is refused with a message rather than silently returning the wrong file. --force re-transcribes.
• Language auto-detection is actually sent when --language is omitted, and the detected language is read from the channel; _language_confidence is recorded. A wrong --language silently returns fluent nonsense on code-switched audio, so SKILL.md now says to establish the spoken language before a batch and pass --language multi for code-switching.
• Expected operator errors (cache mismatch, silent track, API failure) exit with a plain message instead of a traceback.
• smart_format stays off to avoid number/date normalization; filler_words and punctuate stay on.
• Synthesizes spacing tokens per inter-word gap because Deepgram sends none.
• --convert <response.json> maps an existing response offline, with no API call.
• Deepgram returns no audio-event tokens, so (laughter) / (applause) markers are unavailable; SKILL.md now steers reaction-heavy or multi-speaker material to Scribe.
• --num-speakers is accepted for parity but ignored, with a warning.

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

[cubic-dev-ai]

All reported issues were addressed across 2 files

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

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

[cubic-dev-ai]

1 issue found across 1 file (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_deepgram.py">

<violation number="1" location="helpers/transcribe_deepgram.py:356">
P2: Network failures from `requests.post` still escape this handler and print a traceback. Catch `requests.exceptions.RequestException` alongside `RuntimeError` (or wrap it in `call_deepgram`).</violation>
</file>

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

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

[cubic-dev-ai]

P2: Network failures from requests.post still escape this handler and print a traceback. Catch requests.exceptions.RequestException alongside RuntimeError (or wrap it in call_deepgram).

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At helpers/transcribe_deepgram.py, line 356:

<comment>Network failures from `requests.post` still escape this handler and print a traceback. Catch `requests.exceptions.RequestException` alongside `RuntimeError` (or wrap it in `call_deepgram`).</comment>

<file context>
@@ -255,15 +342,21 @@ def main() -> None:
+            spacing_threshold=args.spacing_threshold,
+            force=args.force,
+        )
+    except RuntimeError as exc:
+        # Cache mismatches and API/silent-track failures are expected operator
+        # errors, not bugs. Report them plainly rather than as a traceback.
</file context>

Suggested change

	except RuntimeError as exc:
	except (RuntimeError, requests.exceptions.RequestException) as exc:

[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="SKILL.md">

<violation number="1" location="SKILL.md:66">
P3: The new Setup bullet tells the agent to "pass `--language multi`" for code-switched speech, but this Setup section is provider-agnostic (it covers both ELEVENLABS_API_KEY and DEEPGRAM_API_KEY), and "transcribing a batch" maps to `transcribe_batch.py`, which is the ElevenLabs Scribe-only path (`from transcribe import ...`). `multi` is not an ISO language code and is only validated/supported on the Deepgram path, where it is explicitly scoped to `transcribe_deepgram.py` in the Helpers section. An agent following this under the ElevenLabs default would pass `--language multi` to the Scribe API, contradicting the "does not error" claim. Scope the `--language multi` advice to the Deepgram provider (e.g. "when using transcription_deepgram.py, pass `--language multi`").</violation>
</file>

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

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

[cubic-dev-ai]

P3: The new Setup bullet tells the agent to "pass --language multi" for code-switched speech, but this Setup section is provider-agnostic (it covers both ELEVENLABS_API_KEY and DEEPGRAM_API_KEY), and "transcribing a batch" maps to transcribe_batch.py, which is the ElevenLabs Scribe-only path (from transcribe import ...). multi is not an ISO language code and is only validated/supported on the Deepgram path, where it is explicitly scoped to transcribe_deepgram.py in the Helpers section. An agent following this under the ElevenLabs default would pass --language multi to the Scribe API, contradicting the "does not error" claim. Scope the --language multi advice to the Deepgram provider (e.g. "when using transcription_deepgram.py, pass --language multi").

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At SKILL.md, line 66:

<comment>The new Setup bullet tells the agent to "pass `--language multi`" for code-switched speech, but this Setup section is provider-agnostic (it covers both ELEVENLABS_API_KEY and DEEPGRAM_API_KEY), and "transcribing a batch" maps to `transcribe_batch.py`, which is the ElevenLabs Scribe-only path (`from transcribe import ...`). `multi` is not an ISO language code and is only validated/supported on the Deepgram path, where it is explicitly scoped to `transcribe_deepgram.py` in the Helpers section. An agent following this under the ElevenLabs default would pass `--language multi` to the Scribe API, contradicting the "does not error" claim. Scope the `--language multi` advice to the Deepgram provider (e.g. "when using transcription_deepgram.py, pass `--language multi`").</comment>

<file context>
@@ -62,6 +62,8 @@ First-time install lives in `install.md` (clone, deps, ffmpeg, skill registratio
     - `ELEVENLABS_API_KEY` → `transcribe.py` (Scribe). Tags audio events: `(laughter)`, `(applause)`, `(sigh)`.
     - `DEEPGRAM_API_KEY` → `transcribe_deepgram.py` (nova-3). Same on-disk schema, so everything downstream is identical, and it diarizes. But it returns **no audio-event tokens**, so the `(laughs)`/`(applause)` beat signals in *Cut craft* are unavailable — lean on silence gaps and `timeline_view` instead. Prefer Scribe for reaction-heavy or multi-speaker material where audio events carry the beats.
+
+- **Establish what language is actually spoken before transcribing a batch.** Transcribe one clip, read it against a frame, then run the rest. A wrong `--language` does not error or report low confidence — it returns fluent, grammatical nonsense and silently drops words. For code-switched speech (e.g. Hindi and English alternating mid-sentence) pass `--language multi`; `detect_language` cannot help, because it commits to a single language per file. This matters beyond captions: the cut is reasoned from the transcript, so a language mismatch corrupts the edit itself.
 - `ffmpeg` + `ffprobe` on PATH.
 - Python deps installed (`uv sync` or `pip install -e .` inside the repo).
</file context>