Skip to content

feat(web): internal route to backfill transcripts for existing videos - #26

Merged
hjescalona merged 3 commits into
smgfrom
internal/transcript-backfill
Nov 15, 2026
Merged

hjescalona merged 3 commits into
smgfrom
internal/transcript-backfill

Conversation

@hjescalona

Copy link
Copy Markdown

Why

Imported Loom videos only get a transcript when someone opens them, and the public API only lets a video's owner request one. Transcribing the existing backlog needs a way to start transcription for videos owned by many people without signing in as each of them.

What

  • POST /api/internal/transcripts/backfill next to the Loom import routes, authenticated the same way: the x-media-server-secret header compared with MEDIA_SERVER_WEBHOOK_SECRET through timingSafeEqual over SHA-256 digests. Up to 25 ids per request (same id pattern as the redrive route), deduplicated, five at a time.
  • Each id goes through the existing transcribeVideo as the video's own owner. The owner matters beyond permissions: the audio is read from and the VTT written to <ownerId>/<videoId>/. Every rule inside it still applies: media processing suspension, transcription disabled on the video or organization, live transcription claims, uploads in progress, and the atomic NULL → PROCESSING claim.
  • AI generation is not requested (aiGenerationEnabled = false), so the workflow ends after saving the transcript. Summaries still follow Cap's normal behavior: a later view of a transcribed video without a summary can start one, as for any other video.
  • Videos that already have a transcription status (COMPLETE, PROCESSING, SKIPPED, NO_AUDIO, ERROR) are returned as skipped with that status and never touched; missing videos and screenshots are skipped too. This makes calling the route again a safe way to read progress.
  • Each result is started | skipped | failed with a reason, the current transcription and AI generation status, and the duration. The response also carries inFlight, the number of transcriptions claimed in the last hour that are still processing, so a caller can hold back instead of starting more work than the in-process workflow runtime can carry.

New files only: apps/web/app/api/internal/transcripts/backfill/route.ts, apps/web/lib/transcript-backfill.ts and its test. No schema change, no edit to upstream files.

Verified

  • __tests__/unit/transcript-backfill.test.ts (16 tests: 401 without or with a wrong secret, 400 for invalid batches, owner id and false passed to transcribeVideo, every existing status left alone, missing and screenshot videos, failures and throws mapped per id, repeated ids handled once, unknown in-flight count) and loom-importer-redrive.test.ts pass.
  • bun run typecheck clean; Biome clean on the touched files.

Operating note

Cap Web's workflows run in process, so a deploy while a bulk backfill is running leaves the videos it was transcribing in PROCESSING, which nothing retries for older videos. Turn off Cap Web's GitHub autodeploy in Railway for the duration of a bulk run and back on after it.

Imported Loom videos only get a transcript when someone opens them, and
the public API only lets a video's owner request one. This adds
POST /api/internal/transcripts/backfill, authenticated with the media
server secret like the Loom import routes, so an operator can start
transcription for a list of videos.

Each id goes through transcribeVideo as the video's own owner, so the
storage paths and every existing rule still apply (media processing
suspension, transcription disabled, live claims, uploads in progress).
AI generation is not requested. Videos that already have a transcription
status are reported with that status and left alone, which also makes
the route safe to call again to read progress. The response includes how
many transcriptions started in the last hour are still processing, so a
caller can hold back instead of flooding the in-process workflow runtime.
@hjescalona
hjescalona merged commit 609b8ec into smg Nov 15, 2026
6 checks passed
@hjescalona
hjescalona deleted the internal/transcript-backfill branch November 15, 2026 05:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant