데모 내레이터은(는) 무엇을 하나요?
파이프라인: 프레임 → 분석 → 스크립트 초안 → 사용자 승인 게이트 → SFX + TTS → 렌더링 → 검증.
출력: output_final.mp4 (H.264/AAC, -16 LUFS, 자막 포함) + subtitles.srt.
SKILL="<이 SKILL.md 파일이 포함된 디렉토리의 절대 경로>" # 예: ~/.claude/skills/demo-narrator 또는 ./.claude/skills/demo-narrator
PY="$SKILL/.venv/bin/python"
SKILL은 처음에 한 번 결정하고(스킬이 설치된 위치에 따라 다름) 이후에는 절대 경로를 사용하십시오.
0. 사전 점검
$PY가 존재하지 않으면, 사용자에게 설치 과정에서 ffmpeg + espeak-ng (Homebrew/apt), Python 3.12 가상 환경, PyTorch 및 약 400MB의 무료 모델 가중치를 설치한다고 알립니다. 사용자가 동의하면bash "$SKILL/setup.sh"를 실행합니다(몇 분 소요; 백그라운드에서 실행).- 비디오 파일 옆에 작업 디렉토리를 선택합니다:
WORK="<비디오 디렉토리>/demo-narrator-work/<비디오 파일명(확장자 제외)>". 절대 스킬 디렉토리 안에 쓰지 마십시오. - 다음 정보를 한 번에 물어봅니다(모르는 것만): 제품 이름과 기능, 대상 청중, 어조(기본값: 친근하고, 자신감 있고, 간결함), 음성 선호도(기본값
af_heart), 그리고 반드시 언급해야 할 내용(CTA, URL). 사용자가 이미 "그냥 해"라고 말했다면 프레임에서 추론하십시오.
1. 프레임 추출 + 길이 확인
"$PY" "$SKILL/scripts/extract_frames.py" "<비디오 파일>" --out "$WORK"
- 길이/해상도를 출력하고, 2초당 1프레임을 샘플링하며, 장면 전환을 감지하고, 3×3 접촉 시트를 만듭니다.
- 3초 미만 또는 15분 초과 비디오는 거부합니다(
--force/--max-duration으로 재정의 가능; 긴 비디오는--interval 4사용). - 먼저
$WORK/sheets/*.jpg를 검토하십시오(각각 타임스탬프가 표시됨). 작은 UI 텍스트나 클릭이 발생하는 정확한 순간처럼 세부 정보가 필요할 때만 개별$WORK/frames/*.jpg를 여십시오. $WORK/frames.json→duration,scene_changes(휙 효과에 가장 적합한 위치), 프레임 목록.
비트 목록을 작성하십시오: 각 순간에 화면에 무엇이 있는지, 어떤 동작이 발생하는지(클릭, 입력, 페이지 변경, 성공 상태), 시청자가 무엇을 얻어가야 하는지.
2. $WORK/script.json 초안 작성
{
"video": "/abs/path/to/demo.mp4",
"voice": "af_heart",
"speed": 1.0,
"approved": false,
"segments": [
{"id": 1, "start": 0.4, "end": 4.6, "text": "Meet Relay, the fastest way to turn customer calls into tickets."},
{"id": 2, "start": 5.0, "end": 10.8, "text": "Drop in a recording, and Relay pulls out every bug, request, and follow-up for you."}
],
"sfx": [
{"name": "whoosh", "at": 4.8},
{"name": "pop", "at": 7.2, "gain_db": -12},
{"name": "ding", "at": 10.4}
]
}
타이밍 규칙
- 세그먼트당 예상 단어 수 ≈
(end - start) × 2.5단어 (Kokoro 속도 1.0에서 분당 약 150단어). 이 한도를 넘지 마십시오. - 세그먼트 사이에 0.3초 이상의 간격을 두십시오. 첫 번째 줄은 약 0.3~0.8초에 시작하십시오. 큰 장면 후에는 비디오가 숨 쉴 시간을 주십시오.
start를 설명하는 내용이 나타나는 시점에 맞추고 그 이전에 맞추지 마십시오. 내레이션은 동작보다 약 0.3초 먼저 시작할 수 있습니다.- 세그먼트가 비디오 길이를 초과하지 않아야 합니다. 마지막 세그먼트는 비디오 종료 1초 전에 끝나야 합니다.
듣기 좋은 글쓰기
- 대화체, 2인칭("당신"), 축약형, 능동 동사를 사용하십시오. 세그먼트당 하나의 아이디어.
- 픽셀이 아니라 발생하는 일의 이점을 설명하십시오. 절대 "여기서 볼 수 있듯이…" / "보시다시피…"를 사용하지 마십시오.
- 말하는 대로 철자를 쓰십시오: "two-x faster", "A-P-I"는 철자를 하나씩 말해야 하는 경우에만, "dot com". 기호, 이모지, 슬래시가 포함된 URL, 괄호를 피하십시오.
- 짧은 문장. 사용자가 CTA를 제공했다면 명확한 CTA로 끝내십시오.
SFX (whoosh, whoosh_soft, pop, click, ding) — at은 비디오 절대 시간입니다.
whoosh: 페이지/화면 전환 시(scene_changes사용),whoosh_soft: 패널/모달 슬라이드 시,pop: 요소/토스트(알림) 나타날 때,click: 주요 버튼 클릭 시,ding: 성공/완료 시.- 절제: 최대 4~6초당 약 1개 큐. 0.3초 이내에 큐를 겹치지 마십시오. 기본 레벨은 음성 아래 -9dB입니다. 미묘한 효과에는
gain_db(예: -14)를 설정하십시오.
음성(Kokoro): af_heart (따뜻한 미국 여성, 기본값), af_bella, am_michael / am_fenrir (미국 남성), bf_emma (영국 여성), bm_george (영국 남성). 다른 음성은 처음 사용 시 한 번 다운로드됩니다.
3. ⛔ 스크립트 승인 게이트 — 필수
사용자가 스크립트를 명시적으로 승인할 때까지 오디오를 생성하지 마십시오.
-
스크립트를 표로 제시하고 중단하십시오:
# 시간 단어 수 / 예산 내레이션 SFX 1 0:00.4–0:04.6 11 / 10 ⚠ Meet Relay, … — 예산을 초과하는 세그먼트는 ⚠로 표시하십시오. 사용된 음성과 총 내레이션 길이를 언급하십시오. 다음으로 끝내십시오: "이 스크립트를 승인하거나, 변경할 사항을 알려주세요."
-
턴을 끝내고 기다리십시오. 침묵, "괜찮아 보여?", 또는 이전 초안에 대한 승인은 현재 스크립트의 승인이 아닙니다.
-
수정 사항이 있으면:
script.json을 업데이트하고, 변경된 행을 다시 제시한 후 다시 기다리십시오. -
현재 텍스트에 대해 명시적인 승인("approve", "yes", "go", "ship it")이 있을 때만 다음을 실행하여 스탬프를 찍으십시오:
"$PY" "$SKILL/scripts/generate_tts.py" "$WORK/script.json" --approve스탬프는 내레이션 텍스트의 다이제스트입니다.
generate_tts.py와render_video.py는 스탬프가 찍히지 않았거나 스탬프 이후 텍스트가 변경된 스크립트에서 실행을 거부합니다. 반드시 이 게이트를 다시 통과해야 합니다.approved/approved_digest를 수동으로 설정하지 마십시오. 타이밍(start/end) 및sfx편집은 재승인이 필요하지 않습니다.
4. SFX + 음성 해설 생성
"$PY" "$SKILL/scripts/generate_sfx.py" --out "$WORK/sfx"
"$PY" "$SKILL/scripts/generate_tts.py" "$WORK/script.json"
- TTS는
$WORK/audio/seg_###.wav+tts.json을 씁니다. 엔진: Kokoro, 자동으로 Piper로 대체됨(--engine piper로 강제). - 각 클립은 해당 슬롯(다음 세그먼트 시작까지)에 맞춰집니다. 오버런은
--max-speed 1.25까지 더 빠르게 재합성됩니다. - 표에 여전히
OVER가 표시되면start/end또는 이후 세그먼트를 이동하는 것이 좋습니다(재승인 불필요). 텍스트를 짧게 만들어야 한다면 텍스트 변경이므로 게이트로 돌아가십시오. - 단일 세그먼트 재실행:
--only 3 5. 다른 SFX 변형:--seed 7.
5. 렌더링
"$PY" "$SKILL/scripts/render_video.py" "$WORK/script.json"
- 클립을
start시간에 배치하며 절대 겹치지 않습니다. 작은 오버런은 피치를 유지하는atempo압축(≤ 1.12배)을 적용하고, 나머지는 이후 클립을 이동시킵니다(이동량 출력). 내레이션이 비디오보다 길면 마지막 프레임을 유지합니다. - 음성 + SFX를 믹싱하고, 음량을 -16 LUFS로 정규화하며, 자막을 포함(Pillow 렌더링 카드 + FFmpeg
overlay, libass 불필요)하고,$WORK/output_final.mp4와subtitles.srt를 씁니다. - 선택적 배경 음악(원본, 로컬에서 합성, 라이선스 불필요):
"$PY" "$SKILL/scripts/generate_bgm.py" --duration <비디오 초> --out "$WORK/bgm.wav"(스타일:positive(기본값) = 어쿠스틱 기타 16분음표 피킹과 울리는 개방현, 매 박자 따뜻한 코드 스트럼, 포 온 더 플로어 킥, 당김음 림/박수, 오프비트 베이스, 부드러운 플럭 리드, 111 BPM, 중간 브레이크, B2B 데모 레퍼런스 모델링;demo-bright/demo-dorian= 일반 제품 데모 트랙을 모델링한 SaaS 데모 그루브: 110 BPM, 8분음표로 맥동하고 부드러운 킥으로 펌핑되는 따뜻한 코드, 2박과 4박에 박수, 8분음표 하이햇, 코드 루트의 베이스, 지속되는 상단 라인, 가벼운 플럭 멜로디, 인트로 → 그루브 → 중간 8마디 브레이크 → 그루브 → 깔끔한 엔딩;uke,marimba,pluck,kalimba= 밝은 소프트웨어 데모 배경음, 간단한 소프트 킥 + 스냅/박수 + 셰이커 비트와 약간의 베이스 위에 하나의 플럭/말렛 모티브, 100-112 BPM, 장조;lofi(기본값) = 스윙 그루브의 차분한 비트;keys= 일렉트릭 피아노;upbeat= 포 온 더 플로어 + 아르페지오;ambient= 패드 전용.--bpm,--key(밝은 스타일),--mood(다른 스타일), 변형을 위한--seed N.--duration 40으로 30-40초 미리보기를 만들어 사용자가 귀로 선택한 후--bgm "$WORK/bgm.wav"로 전체 렌더링하십시오.--bgm은 사용자가 제공한 트랙(mp3/m4a/wav)도 허용합니다. 자동으로 동일한 기준 레벨로 조정되고, 비디오보다 짧으면 2.5초 크로스페이드로 반복되며, 끝에서 페이드 아웃됩니다. 사용자가 제공하는 트랙에 대한 권한을 확인하도록 요청하십시오. 음악은 음성 아래에서 자동으로 덕킹됩니다.--bgm-db(기본값 -2.5) 및--duck-db(기본값 -5)로 조정하십시오. - 유용한 플래그:
--out <경로>,--orig-volume 0.15(원본 오디오를 조용히 유지),--sfx-gain-db -12,--no-subs(여전히subtitles.srt는 씀; 비디오에 이미 화면 하단에 자막이 있는 경우 사용),--font <ttf>,--font-scale 0.05,--crf 20.
6. 보고 전 검증
- 렌더링 출력물 확인: 드리프트 열 ~0, 홀드 프레임 경고 없음(또는 설명).
- 자막 스팟 체크: 2-3개 세그먼트 중간 지점에서
ffmpeg -ss <t> -i "$WORK/output_final.mp4" -frames:v 1 "$WORK/check_<t>.jpg"를 실행한 후 이미지를 확인합니다. 자막이 읽기 쉽고 주요 UI를 가리지 않는지 확인하십시오. 중요한 것을 가리는 경우--font-scale을 고려하거나 사용자에게 알리십시오. - 보고: 출력 경로, 길이, 사용된 엔진/음성, 속도가 빨라지거나 이동된 세그먼트, 그리고 조정 방법(
script.json편집 → 4-5단계 재실행; 텍스트 편집은 게이트를 다시 거쳐야 함).
문제 해결
| 증상 | 해결책 |
|---|---|
kokoro unavailable … trying fallback | setup.sh를 다시 실행하십시오. .venv에서 Python이 3.10-3.12인지 확인하십시오. Piper 출력도 괜찮지만 덜 자연스럽습니다. |
| 잘못 발음된 단어/이름 | text에서 음성 철자를 사용하십시오(예: "Kubernetes" → "koo-ber-net-eez"). 승인을 받고 --only로 해당 세그먼트를 다시 생성하십시오. |
| 음성이 급하게 느껴짐 | speed를 0.95로 낮추거나, 세그먼트 창을 넓히거나, 단어를 줄이십시오. |
| 자막이 너무 작거나 큼 | --font-scale 0.035–0.06. |
| 잘못된 색상 / VFR 끊김 | --fps 30을 추가하십시오. |
| 비디오에 유지하려는 음악이 있음 | --orig-volume 0.12–0.2. |
모든 작업은 일회성 모델 다운로드 후 오프라인에서 실행됩니다. 라이선스: Kokoro-82M Apache-2.0, Piper GPL-3.0(piper-tts ≥1.3), 음성은 모델 카드 기준, FFmpeg LGPL/GPL.