Communitygithub.com

데모 내레이터

무음 제품 데모나 화면 녹화를 자연스러운 인간 음성 내레이션, 깔끔한 UI 사운드 효과(휙, 팝, 클릭, 딩), 선택적 배경 음악, 자막(영상에 포함 또는 .srt 파일)이 포함된 내레이션 영상으로 변환합니다. 스크립트 승인 단계를 포함하며 100% 로컬에서 무료로 실행됩니다.

데모 내레이터란 무엇인가요?

이 스킬은 제품 데모, 화면 녹화, 워크스루 등의 무음 비디오를 전문가 수준의 내레이션 영상으로 자동 변환하는 AI 에이전트 스킬입니다. 프레임 추출 및 분석부터 시작하여 사용자 승인을 거친 스크립트 작성, TTS(Text-to-Speech)를 통한 음성 생성, SFX 및 배경 음악 추가, 최종 영상 렌더링까지 전체 파이프라인을 자동화합니다. 모든 처리는 로컬에서 이루어지며 FFmpeg, Kokoro-82M TTS(또는 Piper 대체), numpy/scipy 등을 사용하여 API 키나 유료 서비스 없이 완전히 무료로 작동합니다. 특히 스크립트 승인 게이트가 있어 음성 생성 전에 사용자가 내용을 검토하고 수정할 수 있어 품질을 보장합니다. 마지막으로 H.264/AAC 코덱의 출력 영상과 SRT 자막 파일을 생성하며, 영상 품질과 음량(-16 LUFS)을 전문가 수준으로 조정합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/GarvitSolanki/audio-generator/tree/main/skills/demo-narrator

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

데모 내레이터은(는) 무엇을 하나요?

파이프라인: 프레임 → 분석 → 스크립트 초안 → 사용자 승인 게이트 → 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. 사전 점검

  1. $PY가 존재하지 않으면, 사용자에게 설치 과정에서 ffmpeg + espeak-ng (Homebrew/apt), Python 3.12 가상 환경, PyTorch 및 약 400MB의 무료 모델 가중치를 설치한다고 알립니다. 사용자가 동의하면 bash "$SKILL/setup.sh"를 실행합니다(몇 분 소요; 백그라운드에서 실행).
  2. 비디오 파일 옆에 작업 디렉토리를 선택합니다: WORK="<비디오 디렉토리>/demo-narrator-work/<비디오 파일명(확장자 제외)>". 절대 스킬 디렉토리 안에 쓰지 마십시오.
  3. 다음 정보를 한 번에 물어봅니다(모르는 것만): 제품 이름과 기능, 대상 청중, 어조(기본값: 친근하고, 자신감 있고, 간결함), 음성 선호도(기본값 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. ⛔ 스크립트 승인 게이트 — 필수

사용자가 스크립트를 명시적으로 승인할 때까지 오디오를 생성하지 마십시오.

  1. 스크립트를 표로 제시하고 중단하십시오:

    #시간단어 수 / 예산내레이션SFX
    10:00.4–0:04.611 / 10 ⚠Meet Relay, …—

    예산을 초과하는 세그먼트는 ⚠로 표시하십시오. 사용된 음성과 총 내레이션 길이를 언급하십시오. 다음으로 끝내십시오: "이 스크립트를 승인하거나, 변경할 사항을 알려주세요."

  2. 턴을 끝내고 기다리십시오. 침묵, "괜찮아 보여?", 또는 이전 초안에 대한 승인은 현재 스크립트의 승인이 아닙니다.

  3. 수정 사항이 있으면: script.json을 업데이트하고, 변경된 행을 다시 제시한 후 다시 기다리십시오.

  4. 현재 텍스트에 대해 명시적인 승인("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. 보고 전 검증

  1. 렌더링 출력물 확인: 드리프트 열 ~0, 홀드 프레임 경고 없음(또는 설명).
  2. 자막 스팟 체크: 2-3개 세그먼트 중간 지점에서 ffmpeg -ss <t> -i "$WORK/output_final.mp4" -frames:v 1 "$WORK/check_<t>.jpg"를 실행한 후 이미지를 확인합니다. 자막이 읽기 쉽고 주요 UI를 가리지 않는지 확인하십시오. 중요한 것을 가리는 경우 --font-scale을 고려하거나 사용자에게 알리십시오.
  3. 보고: 출력 경로, 길이, 사용된 엔진/음성, 속도가 빨라지거나 이동된 세그먼트, 그리고 조정 방법(script.json 편집 → 4-5단계 재실행; 텍스트 편집은 게이트를 다시 거쳐야 함).

문제 해결

증상해결책
kokoro unavailable … trying fallbacksetup.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.

관련 스킬