비디오 자막
하나의 명령으로 동영상(또는 오디오) 파일을 읽기 좋은 자막으로, 선택적으로 자막이 포함된 MP4로 변환합니다. 음성 인식의 원시 세그먼트는 종종 단어 중간에서 끊기거나("cen" / "ts") 너무 길게 실행됩니다. 이 스킬은 전체 단어를 재구성하고 적절한 큐로 다시 흐름을 정리합니다.
사용 시기
- "이 동영상에 자막을 추가해 줘", "내 강연의 SRT 파일을 만들어 줘", "자막을 동영상에 입혀 줘."
- "틱톡/릴스/쇼츠 스타일 자막을 만들어 줘" ->
--style shorts --burn사용. - 사용자가 웹사이트
<track>이나 유튜브 업로드를 위해.vtt파일이 필요할 때.
단계
-
MIRAGEA_API_KEY가 설정되어 있는지 확인합니다. (절대 출력하지 마세요.) 없으면 https://miragea.ai 에서 키를 만들고export MIRAGEA_API_KEY=...하라고 사용자에게 알려주세요. -
사용자의 파일에 대해 스크립트를 실행합니다:
python3 scripts/captions.py path/to/video.mp4 # -> video.srt + video.vtt python3 scripts/captions.py path/to/video.mp4 --burn # + video.captioned.mp4 python3 scripts/captions.py path/to/short.mp4 --style shorts --burn # 팝 자막, 중앙 정렬 -
출력된 JSON(
srt,vtt,video,cues)을 읽고 사용자에게 경로를 알려줍니다. -
사용자가 문구 수정을 원하면
.srt파일을 편집하고(타임스탬프 유지)--burn으로 다시 실행하세요: 트랜스크립트는<file>.transcript.json에 캐시되므로 재실행 비용이 들지 않습니다.
옵션
| 플래그 | 기본값 | 기능 |
|---|---|---|
--style standard | 예 | 한 큐에 2줄 x 42자, 1-7초 (방송 규격) |
--style shorts | 한 큐에 1-3단어, 대문자, 하드코딩 시 중앙 정렬 | |
--burn | 꺼짐 | <name>.captioned.mp4 작성 (H.264, 원본 오디오 복사) |
--upper | 꺼짐 | 표준 자막 대문자화 |
--out-dir DIR | 입력 파일 옆 | 출력 위치 |
--force | 꺼짐 | 캐시된 트랜스크립트 무시하고 다시 변환 |
비용 및 제한
오디오 트랙(동영상 아님)만 16kHz 모노로 업로드되며, 파일당 최대 90분 / 1GB입니다. Miragea는 오디오 1초당 3포인트를 청구하며, 캐시된 재실행은 무료입니다. 실시간 요금은 GET https://miragea.ai/v1/capabilities에서 확인하세요.
문제 해결
ffmpeg not found-> ffmpeg 설치 (brew install ffmpeg,sudo apt install ffmpeg,winget install ffmpeg).401-> 키가 잘못됨;402-> miragea.ai에서 충전;429-> 잠시 기다렸다가 다시 실행(재시도해도 안전).- 음악이 강한 클립에서 자막이 약간 빠르거나 늦음: 인트로를 자른 후
--force로 다시 실행하세요.
examples/ 디렉토리에서 샘플 출력을 확인하세요.