From c4f83ead466eae759c7d34ad57155a3d6a8866a4 Mon Sep 17 00:00:00 2001 From: Hildegar Escalona Date: Sun, 15 Nov 2026 01:25:21 -0400 Subject: [PATCH 1/3] feat(web): internal route to backfill transcripts for existing videos 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. --- .../unit/transcript-backfill.test.ts | 240 ++++++++++++++++++ .../internal/transcripts/backfill/route.ts | 98 +++++++ apps/web/lib/transcript-backfill.ts | 92 +++++++ 3 files changed, 430 insertions(+) create mode 100644 apps/web/__tests__/unit/transcript-backfill.test.ts create mode 100644 apps/web/app/api/internal/transcripts/backfill/route.ts create mode 100644 apps/web/lib/transcript-backfill.ts diff --git a/apps/web/__tests__/unit/transcript-backfill.test.ts b/apps/web/__tests__/unit/transcript-backfill.test.ts new file mode 100644 index 00000000000..804252e88b7 --- /dev/null +++ b/apps/web/__tests__/unit/transcript-backfill.test.ts @@ -0,0 +1,240 @@ +import type { HttpApi } from "@effect/platform"; +import type { Layer as EffectLayer } from "effect"; +import { NextRequest } from "next/server"; +import { beforeEach, describe, expect, it, vi } from "vitest"; + +type Condition = { column: string; value: unknown }; + +const mocks = vi.hoisted(() => ({ + videos: new Map>(), + inFlight: 0 as number | Error, + transcribe: vi.fn(), +})); + +vi.mock("@cap/database", () => ({ + db: () => ({ + select: (fields: Record) => ({ + from: () => ({ + where: (condition: Condition) => { + if ("total" in fields) + return mocks.inFlight instanceof Error + ? Promise.reject(mocks.inFlight) + : Promise.resolve([{ total: mocks.inFlight }]); + return { + limit: async () => { + const row = mocks.videos.get(String(condition.value)); + return row ? [row] : []; + }, + }; + }, + }), + }), + }), +})); +vi.mock("@cap/database/schema", () => ({ + videos: { + id: "v.id", + isScreenshot: "v.isScreenshot", + transcriptionStatus: "v.transcriptionStatus", + updatedAt: "v.updatedAt", + }, +})); +vi.mock("drizzle-orm", () => ({ + and: (...conditions: Condition[]) => conditions, + count: () => "count", + eq: (column: string, value: unknown) => ({ column, value }), + gte: (column: string, value: unknown) => ({ column, value }), +})); +vi.mock("@cap/env", () => ({ + serverEnv: () => ({ MEDIA_SERVER_WEBHOOK_SECRET: "media-secret" }), +})); +vi.mock("@cap/web-domain", () => ({ + Video: { VideoId: { make: (id: string) => id } }, +})); +vi.mock("@/lib/transcribe", () => ({ transcribeVideo: mocks.transcribe })); + +type ApiLayer = EffectLayer.Layer; + +vi.mock("@/lib/server", async () => { + const { HttpApiBuilder, HttpServer } = await import("@effect/platform"); + const { Layer } = await import("effect"); + return { + apiToHandler: (api: ApiLayer) => { + const { handler } = HttpApiBuilder.toWebHandler( + Layer.mergeAll(api, HttpServer.layerContext), + ); + return (request: Request) => handler(request); + }, + }; +}); + +import { POST } from "@/app/api/internal/transcripts/backfill/route"; + +const VIDEO = "abcdefghjkmnpqr"; +const OTHER = "__hDHviwdUl78Gf"; + +const video = (overrides: Record = {}) => ({ + ownerId: "owner-a", + isScreenshot: false, + transcriptionStatus: null, + duration: 125.5, + metadata: { transcribeOnView: true }, + ...overrides, +}); + +const call = (body: unknown, secret: string | null = "media-secret") => + POST( + new NextRequest("https://cap.so/api/internal/transcripts/backfill", { + method: "POST", + headers: { + "Content-Type": "application/json", + ...(secret ? { "x-media-server-secret": secret } : {}), + }, + body: JSON.stringify(body), + }), + ); + +const results = async (body: unknown) => { + const response = await call(body); + expect(response.status).toBe(200); + return response.json(); +}; + +beforeEach(() => { + mocks.videos = new Map([[VIDEO, video()]]); + mocks.inFlight = 3; + mocks.transcribe.mockReset().mockResolvedValue({ + success: true, + message: "Transcription workflow started", + }); +}); + +describe("POST /api/internal/transcripts/backfill", () => { + it("requires the media server secret", async () => { + expect((await call({ videoIds: [VIDEO] }, null)).status).toBe(401); + expect((await call({ videoIds: [VIDEO] }, "wrong")).status).toBe(401); + expect(mocks.transcribe).not.toHaveBeenCalled(); + }); + + it.each([ + {}, + { videoIds: [] }, + { videoIds: ["../../etc"] }, + { + videoIds: Array.from( + { length: 26 }, + (_, i) => `abcdefghjkmn${String(i).padStart(3, "0")}`, + ), + }, + ])("rejects invalid batches %#", async (body) => { + expect((await call(body)).status).toBe(400); + expect(mocks.transcribe).not.toHaveBeenCalled(); + }); + + it("starts transcription as the video's owner without AI generation", async () => { + await expect(results({ videoIds: [VIDEO] })).resolves.toEqual({ + inFlight: 3, + results: [ + { + videoId: VIDEO, + status: "started", + transcriptionStatus: "PROCESSING", + aiGenerationStatus: null, + durationSeconds: 125.5, + }, + ], + }); + expect(mocks.transcribe).toHaveBeenCalledTimes(1); + expect(mocks.transcribe).toHaveBeenCalledWith(VIDEO, "owner-a", false); + }); + + it.each(["COMPLETE", "PROCESSING", "SKIPPED", "NO_AUDIO", "ERROR"])( + "leaves a %s video alone and reports its status", + async (status) => { + mocks.videos.set( + VIDEO, + video({ + transcriptionStatus: status, + metadata: { aiGenerationStatus: "COMPLETE" }, + }), + ); + const body = await results({ videoIds: [VIDEO] }); + expect(body.results).toEqual([ + { + videoId: VIDEO, + status: "skipped", + reason: `transcription ${status}`, + transcriptionStatus: status, + aiGenerationStatus: "COMPLETE", + durationSeconds: 125.5, + }, + ]); + expect(mocks.transcribe).not.toHaveBeenCalled(); + }, + ); + + it("skips missing videos and screenshots", async () => { + mocks.videos.set(OTHER, video({ isScreenshot: true })); + mocks.videos.delete(VIDEO); + const body = await results({ videoIds: [VIDEO, OTHER] }); + expect(body.results).toMatchObject([ + { videoId: VIDEO, status: "skipped", reason: "video not found" }, + { videoId: OTHER, status: "skipped", reason: "screenshot" }, + ]); + expect(mocks.transcribe).not.toHaveBeenCalled(); + }); + + it("reports what transcribeVideo decided when it does not start", async () => { + mocks.videos.set(OTHER, video()); + mocks.transcribe.mockImplementation(async (videoId: string) => + videoId === VIDEO + ? { + success: false, + message: "Transcription is unavailable for this account", + } + : { success: true, message: "Video upload is still in progress" }, + ); + const body = await results({ videoIds: [VIDEO, OTHER] }); + expect(body.results).toMatchObject([ + { + videoId: VIDEO, + status: "failed", + reason: "Transcription is unavailable for this account", + transcriptionStatus: null, + }, + { + videoId: OTHER, + status: "skipped", + reason: "Video upload is still in progress", + transcriptionStatus: null, + }, + ]); + }); + + it("fails only the video whose start throws", async () => { + mocks.videos.set(OTHER, video({ ownerId: "owner-b" })); + mocks.transcribe.mockImplementation(async (videoId: string) => { + if (videoId === VIDEO) throw new Error("connection lost"); + return { success: true, message: "Transcription workflow started" }; + }); + const body = await results({ videoIds: [VIDEO, OTHER] }); + expect(body.results).toMatchObject([ + { videoId: VIDEO, status: "failed", reason: "connection lost" }, + { videoId: OTHER, status: "started" }, + ]); + expect(mocks.transcribe).toHaveBeenCalledWith(OTHER, "owner-b", false); + }); + + it("handles a repeated id once", async () => { + const body = await results({ videoIds: [VIDEO, VIDEO] }); + expect(body.results).toHaveLength(1); + expect(mocks.transcribe).toHaveBeenCalledTimes(1); + }); + + it("reports an unknown in-flight count instead of failing the batch", async () => { + mocks.inFlight = new Error("count failed"); + const body = await results({ videoIds: [VIDEO] }); + expect(body.inFlight).toBeNull(); + expect(body.results).toMatchObject([{ status: "started" }]); + }); +}); diff --git a/apps/web/app/api/internal/transcripts/backfill/route.ts b/apps/web/app/api/internal/transcripts/backfill/route.ts new file mode 100644 index 00000000000..90958aef253 --- /dev/null +++ b/apps/web/app/api/internal/transcripts/backfill/route.ts @@ -0,0 +1,98 @@ +import { createHash, timingSafeEqual } from "node:crypto"; +import { serverEnv } from "@cap/env"; +import { + HttpApi, + HttpApiBuilder, + HttpApiEndpoint, + HttpApiError, + HttpApiGroup, + HttpServerRequest, +} from "@effect/platform"; +import { Effect, Layer, Schema } from "effect"; +import { apiToHandler } from "@/lib/server"; +import { + backfillTranscript, + countTranscriptionsInFlight, + type TranscriptBackfillOutcome, +} from "@/lib/transcript-backfill"; + +const MAX_VIDEOS_PER_REQUEST = 25; +const CONCURRENCY = 5; + +class Api extends HttpApi.make("TranscriptBackfillApi").add( + HttpApiGroup.make("root").add( + HttpApiEndpoint.post("backfill")`/api/internal/transcripts/backfill` + .setPayload( + Schema.Struct({ + videoIds: Schema.Array( + Schema.String.pipe(Schema.pattern(/^[A-Za-z0-9_-]{15}$/)), + ).pipe(Schema.minItems(1), Schema.maxItems(MAX_VIDEOS_PER_REQUEST)), + }), + ) + .addSuccess( + Schema.Struct({ + inFlight: Schema.NullOr(Schema.Number), + results: Schema.Array( + Schema.Struct({ + videoId: Schema.String, + status: Schema.Literal("started", "skipped", "failed"), + reason: Schema.optional(Schema.String), + transcriptionStatus: Schema.NullOr(Schema.String), + aiGenerationStatus: Schema.NullOr(Schema.String), + durationSeconds: Schema.NullOr(Schema.Number), + }), + ), + }), + ) + .addError(HttpApiError.Unauthorized), + ), +) {} + +function digest(value: string) { + return createHash("sha256").update(value, "utf8").digest(); +} + +const ApiLive = HttpApiBuilder.api(Api).pipe( + Layer.provide( + HttpApiBuilder.group(Api, "root", (handlers) => + handlers.handle("backfill", ({ payload }) => + Effect.gen(function* () { + const request = yield* HttpServerRequest.HttpServerRequest; + const secret = serverEnv().MEDIA_SERVER_WEBHOOK_SECRET; + const header = request.headers["x-media-server-secret"]; + if ( + !secret || + !header || + !timingSafeEqual(digest(header), digest(secret)) + ) + return yield* new HttpApiError.Unauthorized(); + const results = yield* Effect.forEach( + [...new Set(payload.videoIds)], + (videoId) => + Effect.promise( + (): Promise => + backfillTranscript(videoId).catch((error) => ({ + videoId, + status: "failed", + reason: + error instanceof Error ? error.message : String(error), + transcriptionStatus: null, + aiGenerationStatus: null, + durationSeconds: null, + })), + ), + { concurrency: CONCURRENCY }, + ); + const inFlight = yield* Effect.promise(() => + countTranscriptionsInFlight().catch(() => null), + ); + return { inFlight, results }; + }), + ), + ), + ), +); + +export const POST = apiToHandler(ApiLive); +export const maxDuration = 300; +export const dynamic = "force-dynamic"; diff --git a/apps/web/lib/transcript-backfill.ts b/apps/web/lib/transcript-backfill.ts new file mode 100644 index 00000000000..1109ce63926 --- /dev/null +++ b/apps/web/lib/transcript-backfill.ts @@ -0,0 +1,92 @@ +import { db } from "@cap/database"; +import { videos } from "@cap/database/schema"; +import { Video } from "@cap/web-domain"; +import { and, count, eq, gte } from "drizzle-orm"; +import { transcribeVideo } from "@/lib/transcribe"; + +const TRANSCRIPTION_STARTED_MESSAGE = "Transcription workflow started"; + +// A transcription claim stamps updatedAt when it flips the row to PROCESSING. +// Rows a deploy orphaned keep PROCESSING forever, so only recent claims count +// as in flight. +export const IN_FLIGHT_WINDOW_MS = 60 * 60 * 1000; + +export type TranscriptBackfillOutcome = { + videoId: string; + status: "started" | "skipped" | "failed"; + reason?: string; + transcriptionStatus: string | null; + aiGenerationStatus: string | null; + durationSeconds: number | null; +}; + +export async function backfillTranscript( + videoId: string, +): Promise { + const id = Video.VideoId.make(videoId); + const [video] = await db() + .select({ + ownerId: videos.ownerId, + isScreenshot: videos.isScreenshot, + transcriptionStatus: videos.transcriptionStatus, + duration: videos.duration, + metadata: videos.metadata, + }) + .from(videos) + .where(eq(videos.id, id)) + .limit(1); + + if (!video) + return { + videoId, + status: "skipped", + reason: "video not found", + transcriptionStatus: null, + aiGenerationStatus: null, + durationSeconds: null, + }; + + const current = { + transcriptionStatus: video.transcriptionStatus ?? null, + aiGenerationStatus: video.metadata?.aiGenerationStatus ?? null, + durationSeconds: video.duration ?? null, + }; + + if (video.isScreenshot) + return { videoId, status: "skipped", reason: "screenshot", ...current }; + + if (current.transcriptionStatus) + return { + videoId, + status: "skipped", + reason: `transcription ${current.transcriptionStatus}`, + ...current, + }; + + const result = await transcribeVideo(id, video.ownerId, false); + + if (!result.success) + return { videoId, status: "failed", reason: result.message, ...current }; + if (result.message !== TRANSCRIPTION_STARTED_MESSAGE) + return { videoId, status: "skipped", reason: result.message, ...current }; + return { + videoId, + status: "started", + ...current, + transcriptionStatus: "PROCESSING", + }; +} + +export async function countTranscriptionsInFlight(now = new Date()) { + const [row] = await db() + .select({ total: count() }) + .from(videos) + .where( + and( + eq(videos.isScreenshot, false), + eq(videos.transcriptionStatus, "PROCESSING"), + gte(videos.updatedAt, new Date(now.getTime() - IN_FLIGHT_WINDOW_MS)), + ), + ); + return row?.total ?? 0; +} From 58623f4e9a749f691a3f704da4ccebec7e214a75 Mon Sep 17 00:00:00 2001 From: Hildegar Escalona Date: Sun, 15 Nov 2026 01:26:13 -0400 Subject: [PATCH 2/3] docs(smg): add the transcript backfill route to the ledger --- SMG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/SMG.md b/SMG.md index 7fd13be595a..c1b6bfd7036 100644 --- a/SMG.md +++ b/SMG.md @@ -55,6 +55,7 @@ What we carry on top of upstream. `git log --first-parent --oneline main..smg` i | `feat/share-unfurl-ai-summary` | A | Not opened (improvement, not a fix; propose later if wanted) | In smg ([#11](https://github.com/Solomedia/cap/pull/11)) | `apps/web/app/s/[videoId]/page.tsx`, `apps/web/lib/share-video-metadata.ts` | | `feat/google-account-linking` | A | [CapSoftware/Cap#3964](https://github.com/CapSoftware/Cap/pull/3964) | In smg ([#12](https://github.com/Solomedia/cap/pull/12)), PR open upstream | `packages/database/auth/auth-options.ts`, `apps/web/app/(org)/login/form.tsx` | | `feat/self-hosted-geoip` | A | [CapSoftware/Cap#4158](https://github.com/CapSoftware/Cap/pull/4158) | In smg ([#21](https://github.com/Solomedia/cap/pull/21), [#23](https://github.com/Solomedia/cap/pull/23)), PR open upstream | `apps/web/app/api/analytics/track/route.ts`, `apps/web/app/api/mobile/[...route]/route.ts`, `packages/env/server.ts`, `apps/web/package.json`, `bun.lock`, `README.md` | +| `internal/transcript-backfill` | B | Not opened (operator route for our imported backlog) | PR open into smg ([#26](https://github.com/Solomedia/cap/pull/26)) | None: new files only (`apps/web/app/api/internal/transcripts/backfill/route.ts`, `apps/web/lib/transcript-backfill.ts`, its unit test) | Type A: upstream-able (`feat/*`). Type B: SMG-only (`internal/*`). States: `In smg`, `PR open`, `Merged upstream`, `Rejected upstream → SMG-only`. From eeb3b45fc1bb095278891b8fe20220e1942f6eeb Mon Sep 17 00:00:00 2001 From: Hildegar Escalona Date: Sun, 15 Nov 2026 01:34:10 -0400 Subject: [PATCH 3/3] docs(smg): record the transcript backfill row as in smg --- SMG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SMG.md b/SMG.md index c1b6bfd7036..1902dcd9d49 100644 --- a/SMG.md +++ b/SMG.md @@ -55,7 +55,7 @@ What we carry on top of upstream. `git log --first-parent --oneline main..smg` i | `feat/share-unfurl-ai-summary` | A | Not opened (improvement, not a fix; propose later if wanted) | In smg ([#11](https://github.com/Solomedia/cap/pull/11)) | `apps/web/app/s/[videoId]/page.tsx`, `apps/web/lib/share-video-metadata.ts` | | `feat/google-account-linking` | A | [CapSoftware/Cap#3964](https://github.com/CapSoftware/Cap/pull/3964) | In smg ([#12](https://github.com/Solomedia/cap/pull/12)), PR open upstream | `packages/database/auth/auth-options.ts`, `apps/web/app/(org)/login/form.tsx` | | `feat/self-hosted-geoip` | A | [CapSoftware/Cap#4158](https://github.com/CapSoftware/Cap/pull/4158) | In smg ([#21](https://github.com/Solomedia/cap/pull/21), [#23](https://github.com/Solomedia/cap/pull/23)), PR open upstream | `apps/web/app/api/analytics/track/route.ts`, `apps/web/app/api/mobile/[...route]/route.ts`, `packages/env/server.ts`, `apps/web/package.json`, `bun.lock`, `README.md` | -| `internal/transcript-backfill` | B | Not opened (operator route for our imported backlog) | PR open into smg ([#26](https://github.com/Solomedia/cap/pull/26)) | None: new files only (`apps/web/app/api/internal/transcripts/backfill/route.ts`, `apps/web/lib/transcript-backfill.ts`, its unit test) | +| `internal/transcript-backfill` | B | Not opened (operator route for our imported backlog) | In smg ([#26](https://github.com/Solomedia/cap/pull/26)) | None: new files only (`apps/web/app/api/internal/transcripts/backfill/route.ts`, `apps/web/lib/transcript-backfill.ts`, its unit test) | Type A: upstream-able (`feat/*`). Type B: SMG-only (`internal/*`). States: `In smg`, `PR open`, `Merged upstream`, `Rejected upstream → SMG-only`.