bini-shorts-maker/README.md

Shorts Maker

중국 쇼츠 영상(Douyin, Kuaishou 등)을 다운로드하고 한글 자막을 자동으로 생성하는 웹 애플리케이션입니다.

주요 기능

• 영상 다운로드: Douyin, Kuaishou, TikTok, YouTube, Bilibili 지원
• 음성 인식: OpenAI Whisper로 자동 음성 인식
• 번역: GPT-4로 자연스러운 한글 번역
• 자막 합성: FFmpeg로 자막을 영상에 burn-in
• BGM 추가: 원본 음성 제거 후 BGM 삽입

시스템 요구사항

• Docker & Docker Compose
• 최소 8GB RAM (Whisper medium 모델)
• OpenAI API 키

빠른 시작

1. 환경 설정

cp .env.example .env

.env 파일을 열고 OpenAI API 키를 입력합니다:

OPENAI_API_KEY=sk-your-api-key-here

2. Docker 실행

docker-compose up -d --build

3. 접속

브라우저에서 http://localhost:3000 접속

사용 방법

1. 영상 URL 입력: Douyin, Kuaishou 등의 영상 URL을 입력
2. 다운로드: 자동으로 영상 다운로드
3. BGM 선택: (선택사항) 배경 음악 선택
4. 처리 시작: 자막 생성 및 영상 처리
5. 다운로드: 완성된 영상 다운로드

기술 스택

Backend

• Python 3.11 + FastAPI
• yt-dlp (영상 다운로드)
• OpenAI Whisper (음성 인식)
• OpenAI GPT-4 (번역)
• FFmpeg (영상 처리)

Frontend

• React 18 + Vite
• Tailwind CSS
• Axios

Infrastructure

• Docker & Docker Compose
• Redis (작업 큐)
• Nginx (리버스 프록시)

디렉토리 구조

shorts-maker/
├── backend/
│   ├── app/
│   │   ├── main.py          # FastAPI 앱
│   │   ├── config.py        # 설정
│   │   ├── routers/         # API 라우터
│   │   ├── services/        # 비즈니스 로직
│   │   └── models/          # 데이터 모델
│   ├── Dockerfile
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── pages/           # 페이지 컴포넌트
│   │   ├── components/      # UI 컴포넌트
│   │   └── api/             # API 클라이언트
│   ├── Dockerfile
│   └── package.json
├── data/
│   ├── downloads/           # 다운로드된 영상
│   ├── processed/           # 처리된 영상
│   └── bgm/                 # BGM 파일
├── docker-compose.yml
└── .env

API 엔드포인트

Method	Endpoint	설명
POST	/api/download/	영상 다운로드 시작
POST	/api/process/	영상 처리 시작
GET	/api/jobs/	작업 목록 조회
GET	/api/jobs/{id}	작업 상세 조회
GET	/api/jobs/{id}/download	처리된 영상 다운로드
GET	/api/bgm/	BGM 목록 조회
POST	/api/bgm/upload	BGM 업로드

설정 옵션

환경변수	기본값	설명
OPENAI_API_KEY	-	OpenAI API 키 (필수)
WHISPER_MODEL	medium	Whisper 모델 (small/medium/large)
PORT	3000	웹 서버 포트

문제 해결

다운로드 실패

• 일부 영상은 지역 제한이 있을 수 있습니다
• VPN 또는 프록시 설정이 필요할 수 있습니다

음성 인식 품질

• WHISPER_MODEL=large로 변경하면 정확도가 올라갑니다 (더 많은 메모리 필요)

메모리 부족

• WHISPER_MODEL=small로 변경하세요

라이선스

MIT License

주의사항

• 저작권이 있는 영상을 무단으로 재배포하지 마세요
• BGM은 저작권에 유의하여 사용하세요
• API 사용량에 따른 비용이 발생할 수 있습니다