비디오 트랜스크라이브
이 저장소의 파이프라인을 헤드리스로 실행합니다: 플랫폼 자막(초 단위, 가능한 경우), 로컬 Whisper 폴백(fallback), 그다음 최적화 -> 번역 -> 요약.
실행 전
명령은 AI 비디오 트랜스크라이버 저장소 루트에서 실행해야 하며, 프로젝트 가상 환경(virtualenv)과 ffmpeg가 필요합니다. 세션당 한 번 확인하세요:
ls venv/bin/python && command -v ffmpeg
- 가상 환경 없음:
./install.sh실행, 또는python3 -m venv venv && venv/bin/pip install -r requirements.txt - ffmpeg 없음: macOS에서는
brew install ffmpeg, Debian/Ubuntu에서는sudo apt install ffmpeg로 먼저 설치하세요. 설치 없이 진행하지 마세요. 오디오 추출이 실패합니다.
실행하기
venv/bin/python transcribe.py "<URL 또는 파일 경로>" --json
항상 --json을 전달하세요: 머신이 읽을 수 있는 출력을 표준 출력(stdout)으로 보내고 진행 상황은 표준 에러(stderr)로 유지합니다. 로그 줄을 긁어오지 말고 JSON을 파싱하세요.
유용한 플래그:
| 플래그 | 사용 시기 |
|---|---|
-l, --summary-language <코드> | 요약 언어: en, zh, es, fr, de, it, pt, ru, ja, ko, ar. 기본값 en |
--no-llm | API 키를 사용할 수 없거나 사용자가 원시 대본만 원하는 경우. optimize/translate/summarize를 건너뜁니다 |
--no-video | 사용자가 소스 비디오를 보관하지 않으려는 경우 |
--whisper-model small | 속도보다 정확성이 중요한 경우. tiny에서 large까지, 기본값 base |
-o <디렉토리> | Markdown을 ./temp 대신 다른 곳에 쓰려는 경우 |
LLM 단계는 OPENAI_API_KEY를 통해 OpenAI 호환 키가 필요하며, 선택적으로 OPENAI_BASE_URL도 필요합니다. 키가 없어도 파이프라인은 여전히 대본을 생성하지만 기본 포맷팅으로 폴백됩니다. 사용자가 대본만 필요할 때는 --no-llm을 선호하세요.
공급자 설정:
export OPENAI_API_KEY="your_api_key_here"
export OPENAI_BASE_URL="https://openrouter.ai/api/v1"
export OPENAI_TRANSLATION_MODEL="gpt-4o" # 선택 사항
일회성 실행의 경우 transcribe.py는 --api-key, --base-url, --model도 허용합니다. API 키가 셸 히스토리에 기록되지 않도록 가능하면 환경 변수를 선호하세요.
결과 읽기
{
"title": "...",
"no_speech": false,
"detected_language": "en",
"files": { "raw": "...", "transcript": "...", "summary": "...", "translation": "..." },
"media": { "path": "...", "kind": "video", "size_bytes": 2243691 }
}
transcript와 summary 경로를 읽어 콘텐츠를 확인하세요. translation은 소스 언어가 요약 언어와 다를 때만 존재합니다.
중요: no_speech
"no_speech": true인 경우 소스에 음성이 포함되어 있지 않습니다. 대본, 요약, 번역이 없습니다. 파이프라인은 의도적으로 LLM을 건너뛰어 아무것도 만들어내지 않도록 합니다.
이 경우 사용자에게 비디오에 음성이 없다고 알리세요. 내용을 추측하거나, 제목에서 유추하거나, 비디오가 무엇에 관한 것인지 설명하지 마세요.
실패 모드
- 종료 코드
2: 잘못된 입력 (파일 없음, 지원되지 않는 확장자, 빈 텍스트 파일 등). 메시지를 보고 인수를 수정하세요. - 종료 코드
1: 다운로드/트랜스코딩 실패 (보통 도달할 수 없는 URL, 지역 제한/비공개 비디오, 또는 ffmpeg 누락). 실제 오류를 보고하세요. - 첫 실행 시 Whisper 가중치를 다운로드하므로 잠시 멈춘 것처럼 보일 수 있습니다.
- 긴 비디오는 Whisper 모드에서 느립니다. 플랫폼 자막이 없으면 시작 전에 사용자에게 경고하세요.