MKT AI 비디오 — MP3에서 SRT + 세그먼트 추출
음성 해설 MP3를 단편 동영상 제작 파이프라인 전체에서 사용하는 두 파일로 변환합니다:
<stem>.srt— 표준 SRT 자막 (세그먼트 수준 타임스탬프, 캡션에 사용)<stem>_segments.json— 단어 수준 타임스탬프 (정확한 SFX 배치, 단어별 캡션 애니메이션, 다운스트림 세그먼트 분류에 사용)
두 파일 모두 기본적으로 MP3 파일 옆에 생성됩니다. 파일 이름은 MP3 스템을 따릅니다. 예: voiceover.mp3 → voiceover.srt + voiceover_segments.json
이 스킬을 사용해야 하는 경우
- 사용자가 MP3 음성 해설을 제공하고 SRT/트랜스크립트/세그먼트를 요청할 때
- 다운스트림 스킬(
plan-short-video-edit,heygen-remotion-short-video-editor, 캡션 렌더링)이 단어 수준 타임스탬프를 필요로 하지만 아직 존재하지 않을 때 - 기존 음성 해설에 대한 세그먼트를 다시 생성해야 할 때 (예: 재녹음 후)
두 출력 파일이 이미 존재하고 MP3보다 최신이면 Whisper를 다시 실행하는 대신 기존 파일을 재사용하는 것이 좋습니다.
입력
| 인자 | 필수 | 기본값 | 설명 |
|---|---|---|---|
mp3_path | 예 | — | MP3 파일의 절대 경로 |
language | 아니오 | vi | Whisper 언어 코드. 베트남어 음성 해설에는 vi, 영어에는 en 사용 |
model | 아니오 | base | Whisper 모델 크기: tiny / base / small / medium / large. base는 베트남어에 적절한 균형을 제공하며, small은 약 2배 비용으로 눈에 띄게 더 나은 정확도를 제공합니다. |
output_dir | 아니오 | MP3의 상위 폴더 | SRT + JSON 파일을 저장할 위치 |
1단계 — 변환 스크립트 실행
heygen-short-video 스킬의 기존 Whisper 스크립트를 재사용합니다. 이 스크립트는 이미 이 동작을 정확히 구현하고 있으므로 코드를 중복하지 않습니다:
uv run .claude/skills/heygen-short-video/scripts/transcribe_mp3.py "<mp3_path>" --language vi --model base
이 명령은 다음을 생성합니다:
<mp3_parent>/<stem>.srt<mp3_parent>/<stem>_segments.json
출력을 다른 곳에 저장하려면 --output-dir <path>를 추가하십시오.
예시 — workspace/content/2026-04-09/video-short/learn-claude-code/voiceover.mp3의 경우:
uv run .claude/skills/heygen-short-video/scripts/transcribe_mp3.py \
"workspace/content/2026-04-09/video-short/learn-claude-code/voiceover.mp3" \
--language vi --model base
출력:
workspace/content/2026-04-09/video-short/learn-claude-code/voiceover.srtworkspace/content/2026-04-09/video-short/learn-claude-code/voiceover_segments.json
2단계 — 출력물 검증
스크립트 실행이 완료된 후 두 파일이 모두 존재하고 내용이 비어 있지 않은지 확인합니다:
ls -lh "<output_dir>/<stem>.srt" "<output_dir>/<stem>_segments.json"
head -20 "<output_dir>/<stem>.srt"
예상 결과:
- SRT는
1\n00:00:00,000 --> 00:00:0X,XXX\n<text>\n\n으로 시작해야 합니다. - JSON은 객체 배열이어야 하며, 각 객체는
id,start,end,text및{word, start, end}형태의words배열을 포함해야 합니다.
파일이 없거나 비어 있으면 실행이 실패한 것입니다. 1단계의 stderr를 다시 읽고 조용히 넘어가지 말고 사용자에게 오류를 알리십시오.
출력 형식 참조
voiceover.srt
1
00:00:00,000 --> 00:00:05,139
Đây là tài liệu học Claude Code tốt nhất mình từng thấy…
2
00:00:05,139 --> 00:00:07,299
Nếu bạn mới bắt đầu tìm hiểu Claude Code,
voiceover_segments.json
[
{
"id": 0,
"start": 0.0,
"end": 5.14,
"text": "Đây là tài liệu học Claude Code tốt nhất…",
"words": [
{ "word": "Đây", "start": 0.0, "end": 0.34 },
{ "word": "là", "start": 0.94, "end": 1.12 }
]
}
]
단어 수준 타임스탬프가 이 JSON을 가치 있게 만드는 핵심입니다. 다운스트림 스킬은 단어별 캡션 애니메이션, 단어별 SFX 큐, 정확한 세그먼트 경계 감지에 이를 사용합니다. 후처리 시 words 배열을 절대 제거하지 마십시오.
3단계 — 스크립트 기반 텍스트 보정 (스크립트를 사용할 수 있을 때 필수)
Whisper는 베트남어와 영어 기술 용어가 혼합된 경우(예: "Claude Code" → "Clocot", "MCP Servers" → "MCP Service", "prompt" → "PromGtt")를 자주 잘못 인식합니다. 원본 스크립트를 사용할 수 있을 때는(비디오 파이프라인에서는 거의 항상 가능) 항상 이 보정을 수행하십시오. 모든 타임스탬프는 유지하면서 SRT/JSON 텍스트만 수정하십시오:
- 생성된 SRT + JSON을 읽습니다 (모든
start/end는 변경하지 않고 유지). - 각 SRT 항목을 원본 스크립트의 해당 부분과 위치별로 정렬합니다.
- 해당 부분의 Whisper 텍스트를 스크립트 텍스트로 교체합니다.
voiceover_segments.json의 세그먼트 수준text필드에도 동일한 보정을 적용합니다. 단어 수준 항목은 신뢰할 수 있는 단어 정렬이 없는 한 Whisper가 생성한 그대로 두어도 됩니다. 다운스트림 스킬은 주로 단어 타이밍을 사용하고 단어 문자열 자체는 덜 중요하기 때문에words[].word는 그대로 두어도 괜찮습니다.- 두 파일을 모두 제자리에 다시 씁니다.
이유: SRT 텍스트는 렌더링된 캡션에 사용됩니다. 잘못된 텍스트는 잘못된 캡션으로 이어집니다. Whisper의 타임스탬프는 신뢰할 수 있지만 텍스트는 그렇지 않습니다.
사용자가 명시적으로 스크립트를 제공하지 않은 경우에만 이 단계를 건너뜁니다. 전체 비디오 파이프라인(mkt-full-ai-video)에서는 스크립트를 항상 사용할 수 있으므로 이 보정이 항상 수행됩니다.
팁 및 주의사항
- 모델 선택:
base는 대부분의 깨끗한 음성 해설을 잘 처리합니다. 노이즈가 많은 녹음이나 강한 악센트의 경우small또는medium으로 업그레이드하십시오.small이상에서는 비용이 급격히 증가하지만 짧은 형식의 콘텐츠에서는 효과가 거의 없습니다. - 언어: 베트남어의 경우 항상
--language vi를 명시적으로 전달하십시오. 자동 감지는 짧은 클립에서 가끔 다른 언어로 잘못 인식할 수 있습니다. - 재실행: Whisper는 동일한 모델과 오디오에 대해 결정적이므로 모델을 변경하거나 오디오를 수정하지 않는 한 재실행해도 결과가 개선되지 않습니다. 동일한 모델 크기에서 더 나은 결과를 기대하며 재실행하지 마십시오.
- 경로 따옴표: MP3 경로는 항상 따옴표로 묶으십시오. 작업 공간 폴더에는 따옴표 없이 셸 확장이 깨질 수 있는 하이픈, 날짜, 슬래시가 포함되는 경우가 많습니다.
- 중복 금지: 이 스킬은 의도적으로 자체 스크립트를 포함하지 않습니다. 새 변환 스크립트를 작성하려고 한다면 중단하고
heygen-short-video/scripts/transcribe_mp3.py를 사용하십시오. 해당 스크립트에 변경이 필요하면 그곳에서 수정하여 모든 소비자가 혜택을 볼 수 있도록 하십시오.
인계
두 파일이 저장되고 확인된 후 다음 정보를 보고하십시오:
SRT: <절대 경로>.srt
Segments: <절대 경로>_segments.json
Segments count: N
총 길이: X.X초
그런 다음 사용자(또는 호출 스킬)가 다음 단계를 결정하도록 하십시오. 일반적으로는 생산 계획을 위해 plan-short-video-edit을 사용하거나 heygen-remotion-short-video-editor에서 직접 소비합니다.