subtitle-pro

KO | EN

gitlite — search

#hacktoberfest #react #llm #go #machine-learning #deep-learning #linux #docker #macos #awesome #cli #pytorch #security #ios

(★ 24)

YouTube 영상에 AssemblyAI 음성인식 + Claude 번역으로 한글 자막을 생성·오버레이하는 웹 서비스 (에이전트 하네스 기반)

subtitle-pro 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# subtitle-pro

> YouTube 영상에 **한글 자막을 자동 생성**해 영상 위에 실시간으로 오버레이하는 웹 서비스.

[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
[![Next.js](https://img.shields.io/badge/Next.js-16-black)](https://nextjs.org)
[![TypeScript](https://img.shields.io/badge/TypeScript-5-blue)](https://www.typescriptlang.org)

`http://localhost:3001/watch?v=VIDEO_ID` 로 접속하면, 해당 YouTube 영상의 오디오를 음성 인식(STT)하고 Claude로 한글 번역해 만든 자막을 플레이어 위에 얹어 보여줍니다. 자막이 없거나 원어만 제공되는 영상을 한국어로 편하게 시청하기 위한 도구입니다.

![Subtitle Pro 자막 생성 과정 — 오디오 추출·음성 인식·한글 번역](https://raw.githubusercontent.com/revfactory/subtitle-pro/main/demo-generation.gif)

_자막 생성 과정: URL을 입력하면 오디오 추출 → 음성 인식(STT) → 한글 번역이 순차 진행됩니다 (타임랩스)._

![Subtitle Pro 데모 — 영상 위에 실시간 오버레이되는 한글 자막](https://raw.githubusercontent.com/revfactory/subtitle-pro/main/demo.gif)

_실제 동작 화면: YouTube 영상 위에 한글 자막이 재생 위치에 맞춰 실시간으로 표시됩니다._

![Subtitle Pro 시작 화면](https://raw.githubusercontent.com/revfactory/subtitle-pro/main/screenshot.png)

---

## 동작 방식

자막 생성은 4단계 파이프라인으로 진행되며, 각 단계의 진행 상태는 Job 폴링 API로 프론트엔드에 전달됩니다.

```
YouTube 영상
   │
   ├─ 1. extracting    yt-dlp 로 오디오만 mp3 추출
   │
   ├─ 2. transcribing  AssemblyAI 로 원어 음성 인식(STT) → 타임스탬프가 붙은 세그먼트
   │
   ├─ 3. translating   Claude 로 세그먼트를 배치 병렬 한글 번역
   │
   └─ 4. done          완성 자막을 디스크(.cache/)에 캐시 → 이후 즉시 로드
                       프론트엔드가 재생 위치에 맞춰 자막을 오버레이
```

- **시간 단위 계약**: 모든 자막 cue의 시간은 **초 단위 실수(seconds)** 로 통일됩니다. YouTube IFrame Player의 `getCurrentTime()`이 초를 반환하므로 변환 없이 `startSec <= currentTime < endSec`로 현재 cue를 찾을 수 있습니다.
- **단일 진실 원천**: 백엔드/프론트엔드 경계의 데이터 shape은 [`types/subtitle.ts`](types/subtitle.ts) 한 곳에서 정의합니다 (`SubtitleCue`, `JobStatus`, `SubtitleJob`).
- **캐시**: 한 번 생성한 자막은 `videoId` 기준으로 `.cache/`에 저장되어, 같은 영상을 다시 열면 재생성 없이 즉시 표시됩니다.

## 기술 스택

| 영역 | 사용 기술 |
|------|-----------|
| 프레임워크 | Next.js 16 (App Router) · React 19 · TypeScript 5 |
| UI | TailwindCSS 4 · shadcn/ui · lucide-react |
| 음성 인식(STT) | [AssemblyAI](https://www.assemblyai.com/) SDK |
| 번역 | [Claude](https://www.anthropic.com/) (`@anthropic-ai/sdk`) |
| 오디오 추출 | `yt-dlp` + `ffmpeg` (시스템 도구) |

## 사전 요구사항

- **Node.js** 20 이상
- **[yt-dlp](https://github.com/yt-dlp/yt-dlp)** — YouTube 오디오 추출
  ```bash
  brew install yt-dlp        # macOS
  # 또는
  pip install yt-dlp
  ```
- **[ffmpeg](https://ffmpeg.org/)** — 오디오 변환 (yt-dlp가 내부적으로 사용)
  ```bash
  brew install ffmpeg        # macOS
  ```
- **API 키 2종**
  - [Anthropic API 키](https://console.anthropic.com/) (`ANTHROPIC_API_KEY`) — 한글 번역용
  - [AssemblyAI API 키](https://www.assemblyai.com/) (`ASSEMBLYAI_API_KEY`) — 음성 인식용

## 시작하기

1. **저장소 클론 및 의존성 설치**
   ```bash
   git clone https://github.com/revfactory/subtitle-pro.git
   cd subtitle-pro
   npm install
   ```

2. **환경변수 설정** — `.env.example`을 복사해 `.env`를 만들고 API 키를 채웁니다.
   ```bash
   cp .env.example .env
   ```
   ```dotenv
   ANTHROPIC_API_KEY=sk-ant-...
   ASSEMBLYAI_API_KEY=...
   ```
   > `.env`는 `.gitignore`에 포함되어 커밋되지 않습니다. 실제 키가 저장소에 올라가지 않도록 주의하세요.

3. **개발 서버 실행** (포트 3001)
   ```bash
   npm run dev
   ```

4. **영상 열기** — 브라우저에서 자막을 보고 싶은 YouTube 영상 ID로 접속합니다.
   ```
   http://localhost:3001/watch?v=VIDEO_ID
   ```
   예: `https://www.youtube.com/watch?v=dQw4w9WgXcQ` → `http://localhost:3001/watch?v=dQw4w9WgXcQ`

첫 접속 시 자막 생성 파이프라인이 돌며 진행 상태가 표시되고, 완료되면 영상 위에 한글 자막이 오버레이됩니다.

## 프로덕션 빌드

```bash
npm run build
npm run start        # 포트 3001
```

## 프로젝트 구조

```
app/
  api/subtitles/route.ts   Job 생성(POST) · 상태 폴링(GET) API
  watch/page.tsx           /watch?v=VIDEO_ID 페이지
lib/
  extract.ts               yt-dlp 오디오 추출
  transcribe.ts            AssemblyAI 음성 인식
  translate.ts             Claude 배치 병렬 번역
  pipeline.ts              4단계 파이프라인 오케스트레이션
  job-store.ts             인메모리 Job 상태 저장소
  config.ts                모델·배치·캐시 등 설정 상수
components/                플레이어 · 자막 오버레이 UI
types/subtitle.ts          백엔드/프론트 공유 타입 계약
```

이 프로젝트는 **에이전트 하네스**로 개발되었습니다. `.claude/`(에이전트·스킬 정의)와 `_workspace/`(단계별 작업 리포트)에 개발 과정이 기록되어 있습니다.

## 기여

기여를 환영합니다. [CONTRIBUTING.md](CONTRIBUTING.md)와 [행동 강령](CODE_OF_CONDUCT.md)을 참고하세요.

## 라이선스

[GNU AGPL-3.0-or-later](LICENSE). 이 소프트웨어를 네트워크 서비스로 제공하는 경우, 사용자에게 소스 코드를 공개할 의무가 있습니다.

subtitle-pro

subtitle-pro 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

subtitle-pro

subtitle-pro 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README