revfactory/subtitle-pro

Purpose and Entry Points

Subtitle Pro is a Next.js web service that generates Korean subtitles for YouTube videos, then synchronizes them as an in-player overlay. The landing flow begins at app/page.tsx; direct viewing uses /watch?v=VIDEO_ID via app/watch/page.tsx. Server work is initiated and polled through app/api/subtitles/route.ts.

Application Boundary

The project uses Next.js 16 App Router, React 19, and TypeScript. Browser components own YouTube playback, job polling, and subtitle rendering; server-side API/pipeline code owns media processing and third-party API access. The shared boundary contract is types/subtitle.ts, defining cues, job states, and job payloads. Cue timestamps are seconds, matching YouTube Player getCurrentTime().

Job API and State Lifecycle

app/api/subtitles/route.ts exposes POST job creation and GET job-status polling. It coordinates with the in-memory job registry in lib/job-store.ts; this registry tracks stages such as extracting, transcribing, translating, done, and failures. hooks/use-subtitle-job.ts repeatedly queries the API and supplies status/results to the watch UI.

Subtitle Generation Pipeline

lib/pipeline.ts orchestrates the sequential generation flow:

1. Extract audio from a YouTube video.

2. Transcribe audio into timestamped source-language segments.

3. Batch/parallel translate segments to Korean.

4. Persist and return finalized subtitle cues.

It composes lib/extract.ts, lib/transcribe.ts, and lib/translate.ts. Pipeline behavior—including cache, model, and batching settings—is centralized in lib/config.ts.

External Processing and Persistence

Audio extraction invokes local yt-dlp and ffmpeg, requiring both as host-installed system tools. lib/transcribe.ts calls AssemblyAI for speech-to-text; lib/translate.ts calls Anthropic Claude for Korean translation. API credentials are environment-provided (ASSEMBLYAI_API_KEY, ANTHROPIC_API_KEY). Completed subtitles are cached on local disk under .cache/, keyed by video ID; job state itself is process-local and is not durable across server restarts.

Watch and Playback Composition

components/watch-view.tsx assembles the viewing experience. components/youtube-player.tsx integrates the YouTube IFrame Player and emits playback time. components/subtitle-overlay.tsx selects and displays the active cue for that time, while components/subtitle-controls.tsx and lib/overlay-settings.ts manage presentation preferences. hooks/use-fullscreen.ts handles fullscreen behavior around the player/overlay boundary.

Input and Navigation Flow

components/video-id-form.tsx accepts a YouTube URL or ID and routes the user to the watch page. lib/youtube.ts normalizes or validates YouTube identifiers before pipeline usage. The resulting control flow is: user input or direct watch URL → watch UI starts/polls subtitle job → server pipeline creates/caches cues → player time drives overlay selection.