Communitygithub.com

josueh04/product-video-skills

제품 영상의 내레이션 대본을 작성하고, 단어 타이밍, 발음 수정, 음향 효과 및 음량이 포함된 음성 클립으로 변환합니다.

product-video-skills란 무엇인가요?

이 스킬은 제품 영상 제작 과정에서 대본 작성부터 음성 생성, 음향 효과 추가까지의 전체 워크플로우를 자동화합니다. 사용자가 영상의 대본을 '순간(moment)' 단위의 표로 작성하면, 각 문장을 개별 오디오 클립으로 변환하고 단어별 타이밍 정보를 timings.json에 기록합니다. ElevenLabs 또는 macOS 무료 say 음성을 사용하여 TTS(텍스트 음성 변환)를 수행하며, 브랜드 이름의 발음 재작성을 원래 화면 표기로 매핑하고 모든 클립의 음량을 정규화합니다. 또한 실제 키보드 입력음을 기반으로 타이핑 사운드 트랙을 생성하고, 클릭 및 팝 사운드 효과를 배치합니다. 이 스킬은 Claude Code와 같은 AI 에이전트 환경에서 사용되며, 대본 변경 시 해당 클립만 재생성하고 이후 모든 타이밍을 자동으로 조정합니다. 대본 검증(금지된 용어 확인, 발음 검사 등)을 통해 오류가 렌더링 단계로 전달되는 것을 방지합니다.

지원 대상✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/josueh04/product-video-skills/tree/HEAD/skills/script-and-voice

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

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

문서

대본 및 음성

음성은 영상의 시계입니다. 애니메이션의 모든 비트는 내레이션의 단어에 고정됩니다(build.py에서 T[clip] + w(clip, "word")). 따라서 대본과 클립은 애니메이션보다 먼저 생성되며, 문장을 변경하면 하나의 클립이 재생성되고 이후의 모든 타이밍이 다시 계산됩니다. 이 스킬이 사용된 실제 프로덕션에서는 TTS 엔진 전체를 교체했을 때 완성된 영상의 타이밍이 수동 편집 없이 재조정되었습니다. 먼저 애니메이션을 만들고 나중에 음성을 맞추는 방식은 변경이 있을 때마다 오디오를 늘리거나 비트를 수동으로 드래그해야 합니다.

<video_dir>/audio/ 디렉토리 아래에서만 작업합니다(BRIEF.md의 대본 섹션 포함). 모든 문장은 TRUTH.md에 근거해야 하며 CLAIMS.md를 준수해야 합니다. 필요한 문장에 출처가 없으면 검증을 요청하거나 삭제하세요.

docs/contracts.md에 정의된 대로 호출되는 스크립트:

PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
S="$PVS_HOME/skills/script-and-voice/scripts"
"$PVS_HOME/bin/pvs-py" "$S/check_script.py" <video_dir>                 # lines.tsv 린트
"$PVS_HOME/bin/pvs-py" "$S/tts.py" <video_dir> [--only N3,N4] [--provider say] [--force] [--restore]
"$PVS_HOME/bin/pvs-py" "$S/pronounce_check.py" <video_dir> [--only N3]  # ASR이 브랜드 단어를 들었는가?
"$PVS_HOME/bin/pvs-py" "$S/make_sfx.py" <video_dir> [--list]            # sfx.tsv 생성 또는 라이브러리 목록 출력

1. 대본은 순간들의 표입니다

제품 녹화본은 참조 자료일 뿐, 타임라인이 아닙니다. 실제 로딩 시간과 화면 전환은 영상에 포함되지 않습니다. 대본은 각각 화면에서 일어나는 일, 문장(또는 무음), 지속 시간을 포함하는 순간(모멘트) 단위로 작성합니다. 순간의 지속 시간은 액션과 문장 중 더 긴 쪽입니다. 실제 대기 시간은 압축합니다: 40초 로딩은 약 2초의 생각 상태로 표현합니다.

BRIEF.md의 ## Script 섹션에 장 순서대로 표를 추가합니다:

순간화면라인텍스트(또는 무음)유지 시간
오프닝앱이 흐릿하게 보이는 상태에서 제품명N1이것은 Acme Tasks, 당신의 하루를 계획하는 할 일 목록입니다.0.8초 후
대기계획 수립 중(무음)2.0초

그런 다음 비디오 형식에 맞는 템플릿을 선택하고 그 구조를 따릅니다: references/script-templates.md 읽기(pitch, tour, docs page, tutorial, silent loop).

라인 작성 방법 및 이유:

  • 중요한 기능을 설명하되 나열하지 마세요. UI가 기능을 수행하는 동안 시청자에게 그 기능이 어떤 도움을 주는지 말하세요. 이 스킬이 사용된 프로덕션에서는 기능을 설명하지 않고 이름만 언급한 영상으로 인해 26개 버전 중 9개가 발생했습니다. COVERAGE.md는 화면에서 설명해야 하는 기능을 명시합니다: "반드시 설명"으로 표시된 모든 행은 최소한 하나의 설명 라인이 필요합니다.
  • 제품을 처음 보는 사람에게 각 단계를 설명하세요. 캐릭터가 누구인지, 무엇을 요청하는지, 각 단계가 무엇을 하는지. 빠르고 설명 없는 오프닝은 리뷰에서 거부되었습니다.
  • 한 문장에 하나의 아이디어, 한 클립에 하나의 문장. 그러면 문장 변경 시 하나의 클립만 교체됩니다.
  • 커서가 닿는 요소의 이름을 그대로 사용하세요. 비트가 해당 단어에 고정되므로 화면에 보이는 명사와 클립의 단어가 동일해야 합니다.
  • 실제 UI 레이블을 사용하세요. 리뷰어가 다른 단어를 사용하더라도 마찬가지입니다. 영상은 시청자가 제품에서 보게 될 내용과 일치해야 합니다.
  • 숫자와 시간은 단어로 작성하세요 ("열 시", "30분 후"). TTS 엔진은 숫자를 일관성 없이 읽으며, 음성-텍스트 QA는 단어 단위로 비교합니다.
  • 대기 시간 주변에 여유를 두세요. 전화가 울리기 약 3초 전, 아무도 확인할 수 없는 정확한 숫자 대신 "약 1분"이라고 표시합니다.
  • 완전한 문장으로 끝내고, 약간 느리게 읽으세요. 마지막 라인이 태그라인 조각일 경우 리뷰에서 끊긴 것처럼 들렸습니다. CLAIMS.md의 포지셔닝을 포함한 완전한 문장은 그렇지 않았습니다.
  • 비디오 내에서 인칭을 일관되게 유지하세요: 가상의 사용자로서 1인칭("먼저 캘린더를 연결합니다.") 또는 그에 대한 3인칭. 모든 비디오에서 동일한 이름으로 product.yaml의 가상 캐스트만 사용하세요.
  • 포지셔닝은 소스 문서가 아닌 CLAIMS.md에서 가져옵니다: 소스 문서에는 팀이 금지한 문구가 포함될 수 있으며, 규칙이 우선합니다.

2. lines.tsv

audio/lines.tsv, 탭으로 구분, 헤더: id role speed text, 재생 순서대로 한 행에 한 클립, # 라인은 주석. 전체 형식과 build.py가 결과를 읽는 방법: references/audio-formats.md.

  • id: 내레이션은 N1, N2, N7b; 다른 문자는 다른 글자 사용(에이전트는 A1, 고객은 C1). N7과 N8 사이에 라인을 N7b로 삽입하면 다른 모든 id와 해당 id를 사용하는 모든 앵커가 안정적으로 유지됩니다.
  • role: product.yaml의 voice.roles 키 중 하나(narrator, agent, customer 또는 narrator_close 같은 읽기 변형, 섹션 3 참조). role이 id가 아닌 음성을 선택합니다.
  • speed: 기본 1.0, 범위 0.71.2. 오프닝과 클로징 라인은 0.90.96 사용.
  • text: 화면과 자막에 표시되는 그대로, 제품명의 표준 철자 사용. 여기에 발음 재작성(respelling)을 절대 쓰지 마세요; 발음은 product.yaml에 있습니다.

배포된 버전의 라인을 변경하기 전에 lines.tsv를 lines-v<N>.tsv로, timings.json을 timings-v<N>.json으로 복사하여 이전 버전을 다시 빌드할 수 있게 하세요.

편집 후 매번 check_script.py를 실행하세요. 중복 id, 알 수 없는 role, 범위를 벗어난 speed, 40단어 초과 클립, 금지된 용어, 절대 사용하지 말아야 할(never_say) 문구, 레거시 이름, 대본 내 재작성(respelling) 등을 발견하면 실패합니다. 긴 클립, 숫자, 대시에 대해 경고합니다. 음성 생성 전에 모든 오류를 수정하세요: TTS에 전달된 금지 문구는 테이크(take) 비용을 발생시키고, 렌더링에 도달하면 버전 비용이 발생합니다.

3. 캐스팅

음성을 제안하기 전에 references/casting-and-pronunciation.md를 읽으세요. 요약:

  • 먼저 현실적인 음성을 제안하세요. 제품의 기본 음성과 가장 저렴한 모델은 리뷰에서 "매우 가짜"로 평가되었습니다. 사용 가능한 가장 자연스러운 모델이 캐릭터에 가치가 있습니다.
  • 컨텍스트에서 오디션: 역할당 실제 연속 두 줄, 역할당 3~6개 후보.
  • 각 선택을 거부권 행사가 가능한 폐쇄형 질문으로 제안하되 권장 기본값을 함께 제시하세요("내레이터: 목소리 B, 따뜻하고 여유로운. 유지할까요?"). 열린 옵션 목록은 며칠 동안 답변이 없었습니다.
  • 역할별 처리(treatment) 결정: 통화 중인 사람은 treatment: phone, 녹음된 회의는 treatment: room, 내레이터는 없음.
  • 라인별 읽기(더 안정적이고, 느리며, 스타일이 덜함)는 동일한 음성을 다른 설정으로 가리키는 역할 변형입니다. 따라서 선택이 설정(config)에 남아 재실행 시 유지됩니다.

voice.provider: say (또는 --provider say)는 무료 macOS 음성과 whisper를 단어 타이밍에 사용합니다. 키가 존재하기 전에 초안, 테스트 및 타이밍 작업에 사용하고, 실제 음성으로 최종 제공하세요.

4. 클립 생성

"$PVS_HOME/bin/pvs-py" "$S/tts.py" <video_dir>

각 라인에 대해 TTS에만 브랜드 단어를 재작성(respell)하고, 수정되지 않은 테이크는 audio/raw/에 보관합니다(이전 테이크는 audio/raw/prev/로 이동). 무음을 자르고, 48kHz 모노로 리샘플링하고, 역할의 처리를 적용하고, voice.clip_lufs로 정규화(ffmpeg loudnorm, 2패스; 피크 -1.5 dBTP 미만)하고, 양쪽 가장자리를 페이드 아웃/인하고, 클립의 항목을 audio/timings.json에 병합합니다.

각 처리 단계가 존재하는 이유:

  • 원시 테이크는 항상 보관되며 항상 소스입니다. 이전 클라이언트는 전체 재렌더링 후 오래된 원시 파일에서 정규화했습니다. 여기서는 클립이 항상 이를 생성한 테이크에서 재구축됩니다.
  • 꼬리는 마지막 단어 이후 최대 0.6초에서 잘리고 페이드 아웃됩니다. TTS 테이크는 클릭이나 다른 구문의 시작으로 끝날 수 있습니다. 그러한 클릭 하나가 오디오에서 "이상한 컷"으로 출시되었습니다.
  • 모든 클립의 음량이 동일합니다. 정규화 전에 한 캐릭터 음성이 내레이터보다 6dB 더 컸습니다.
  • 변경되지 않은 라인은 건너뜁니다(텍스트, 음성 및 설정의 해시를 audio/raw/cache.json에 저장). 따라서 한 라인 편집 후 전체 실행 시 공급자가 한 번만 호출됩니다. clip_lufs 또는 처리만 변경된 경우 보관된 테이크에서 클립이 무료로 재구축됩니다. --force는 어쨌든 새 테이크를 요청합니다.

키는 환경 변수 또는 PVS_HOME/.env에서 스크립트가 읽으며 절대 출력되지 않습니다. .env를 직접 읽거나 채팅에서 키를 묻지 마세요: 키가 없으면 사용자에게 .env에 라인을 직접 추가하거나 say로 전환하도록 안내하세요.

새 테이크 후에 pronounce_check.py를 실행하세요. 각 클립을 ASR에 프롬프트 없이 전사하고, 인식되지 않은 브랜드 및 캐스트 단어, 들린 레거시 이름, 변동된 모음(섹션 5)에 플래그를 지정합니다. 플래그는 듣고 판단하라는 의미이지 재생성하라는 의미가 아닙니다: ASR은 올바르게 말한 브랜드 단어를 잘못 들을 수 있습니다.

5. 발음

대본과 화면은 실제 철자를 유지합니다. product.pronounce는 TTS로 보내는 내용만 변경하며, tts.py는 타이밍을 다시 매핑하여 timings.json이 w에는 화면상의 단어를, say에는 재작성된 발음을 보관합니다({"w": "Acme", "say": "AK-mee", ...}). build.py의 앵커는 화면상의 단어를 사용합니다.

product:
  pronounce:
    Acme: AK-mee                                    # 일반 재작성
    Acme Tasks: {say: AK-mee Tasks, vowel: ae, confusable: ey}   # 첫 모음 확인 포함

리뷰어가 이름 발음이 잘못되었다고 말하면, 한 라인에서 3~4개의 재작성을 시도하고 모음 확인으로 측정한 후 통과하는 것을 유지하고, 해당 단어가 있는 다른 모든 라인을 확인하세요: 공급자는 테이크마다 다릅니다. 자세한 내용 및 모음 표: references/casting-and-pronunciation.md.

6. 테이크

  • 사용자가 달리 말하지 않는 한 라인당 최대 2개의 테이크. 공급자 할당량은 일반적으로 팀 전체가 공유합니다. 실행 전에 전체 실행에 몇 글자가 소모될지 알려주세요.
  • 필요한 라인만 재생성: tts.py <video_dir> --only N7 --force.
  • 새 테이크가 더 나쁘면 --only N7 --restore로 타이밍과 함께 되돌립니다.
  • 톤 노트("너무 과장됨", "반쪽 문장처럼 들림")의 경우 역할 변형 또는 속도 변경으로 2~3개의 변형을 만들고 리뷰어가 이전 라인과 컨텍스트에서 비교하게 하세요.
  • 라인 변경 순서: 버전 파일 복사 → 행 편집 → check_script.py → tts.py --only <id> → pronounce_check.py --only <id> → 컴포저가 재구축; 해당 클립 이후의 모든 것이 자동으로 이동합니다.

7. 음향 효과

HyperFrames에 포함된 라이브러리(make_sfx.py --list)의 녹음된 사운드만 사용하세요. 합성 타이핑은 "키보드가 아닌 빨대"처럼 들렸고 합성 훙 소리는 "흰색 소음"처럼 들렸으므로, 훙 소리와 라이저는 스크립트에서 거부되며, 브리프가 요청하지 않는 한 내레이션 아래에 음악이 들어가지 않습니다. 이 스킬이 사용된 프로덕션은 배경 음악과 덕킹 없이 출시되었으며 아무도 불편함을 느끼지 못했습니다.

  • 타이핑: typing_track(text, start, cps)는 실제 녹음에서 추출한 개별 키 입력으로 트랙을 구축하며, 스페이스바에 더 무거운 스트로크와 시드된 리듬을 적용하여 결정적이어서 동일한 텍스트가 항상 동일하게 들립니다. 텍스트를 보여주는 비트만큼 정확히 지속되게 하고(dur=), 타이핑된 단어가 말해진 단어와 일치하게 합니다.
  • 클릭 및 팝: library_sfx("click", start) 커서가 누르는 프레임에 배치.
  • audio/sfx/CREDITS.md는 사용된 모든 라이브러리 파일을 나열하고 라이브러리 라이선스를 포함합니다.
  • 권장 레벨: 내레이션 1.0, 캐릭터 1.0, 클릭 0.35(드래그 릴리스 시 0.22), 타이핑 0.45, 팝 0.12~0.3. 동일한 오디오 트랙의 두 클립은 절대 겹치면 안 됩니다: 이전 클립이 끝난 후 최소 0.02초 후에 클립을 시작하거나 다른 트랙으로 이동하세요.

build.py는 함수를 가져옵니다. make_sfx.py <video_dir>는 audio/sfx.tsv와 함께 명령줄에서 동일한 파일을 사전 빌드합니다(형식은 스크립트의 독스트링 참조).

8. 컴포저로 전달

<video_dir>/audio/ 아래에 다음을 전달: lines.tsv, clips/<id>.wav, timings.json, CREDITS.md가 포함된 sfx/. 각 비트가 고정되어야 하는 단어(커서가 닿는 명사, 타이핑이 도착하는 단어)와 순간 표의 대기 시간을 컴포저에게 알려주세요. timings.json을 수동으로 편집하지 마세요: 클립에서 재생성되며 수동 편집은 다음 실행 시 손실됩니다.

사용자에게 보고: 음성 처리된 라인, 각 클립의 지속 시간, 발음 플래그 및 들은 내용, 사용된 음성(아직 결정되지 않은 항목에 대한 권장 기본값 포함), 소모된 공급자 글자 수.

Individual skills in this repo

This repo contains 14 individual skills — each has its own dedicated page.

josueh04/product-video-skills

Extract, once per product, everything every video of it reuses and write it to kit/ and product.yaml (design tokens, font subsets as woff2, icon subsets as SVG from the product's own icon packages, logos in light, dark and app-tile variants from the repo, a fictional cast proposed once for veto and then frozen, the canonical-names map, pronunciations, banned terms and the read-only tool list). Use it when a product is set up or its kit is missing or incomplete, when a video needs an icon, font or logo that is not in kit/ yet, when someone asks for demo names, fake customers, phone numbers or emails, when a brand word is mispronounced or an old product name shows up, and when checking that demo data is fictional.

josueh04/product-video-skills

Interview the user about a product, then create products/<slug>/ with its own git history, a filled product.yaml and linked skills, fetch its sources and build its kit. Run only when the user types /product-new.

josueh04/product-video-skills

Back every sentence of a video's narration (audio/lines.tsv) and every screen it shows with a citation into the pinned source code (role/path:line@sha) or a docs URL, mark what is visible in the UI versus backend-only, flag restricted or unreleased features, and cut or rewrite anything unbacked; writes the video's TRUTH.md and checks it with truth_check.py. Use it whenever a script or narration is drafted or edited, before voice is generated, before a build, when someone asks "can we say this?", "is this true?", "does the product really do X?", when a reviewer asks for a feature or a claim the product may not support, and when a source document (pitch deck, PRD, marketing page) makes claims the video wants to repeat.

josueh04/product-video-skills

Check a rendered product video before anyone else sees it: worker-pattern flicker, black frames, loudness and true peak, clipping, clicks at clip edges, overlapping narration, speech to text against the script, banned terms and legacy names, camera zoom, contact sheets, frame strips at transitions and parity against the approved version; then write qa/REPORT.json, the only thing deliver.py accepts. Use it after every HyperFrames render, whenever someone asks "is the render clean", "QA this", "check the video", "check the audio", "why does it flicker", "there is a click", "compare v3 with v2", "did the approved part change", or before showing, sending, uploading or delivering any MP4, even when the request does not say QA. Also use it to triage a defect a reviewer reported in a render.

josueh04/product-video-skills

The animation rules that keep HyperFrames' parallel render workers from dropping, flashing or flickering elements, plus a static lint (lint_motion.py) that finds the violations in a video's template before it costs a render. Use it whenever you write or edit GSAP tweens, timelines, cursors, camera moves, typing, scrolls or pop-ups in a HyperFrames composition or a video's src/template.tpl, whenever a render shows flicker, stutter, an element that vanishes on some frames, a title that flashes, or a "WORKER PATTERN" line from scan_render.py or qa.py, and whenever the preview looks right but the MP4 does not. Also use it to review someone else's timeline code before rendering.

josueh04/product-video-skills

Pin a product's source code (read-only exports in sources/ plus sources.lock), confirm that the pinned commit is what runs in production, and map every screen of a video brief to its route, components, i18n strings and state, written to the video's SOURCES.md. Use it whenever a video needs to know where a screen lives in the code, when sources/ is missing or stale, before ui-spec-from-code or product-truth start on a video, after the product's frontend changed ("what changed", "which videos are affected", "refresh the sources", "is this checkout current", "which commit is in prod"), and when there is no code and you need an inventory of the no-code references (recordings, recovered captures, docs) a screen can be rebuilt from.

josueh04/product-video-skills

Compose a narrated product demo in HyperFrames: the stage (the product UI rebuilt at its real viewport and scaled to 1080p, camera, rack focus with veil, chapter titles, cursor and clicks, typing, streaming text, pop-ups, toasts, scrolls, end screen and lockup) and the build.py that anchors every beat to a word of the narration. Use it whenever you write or edit a video's video/build.py, src/template.tpl or src/app.css, place a beat on a word, add a chapter, a click, a pop-up or a push-in, frame a screen, build the end screen or lockup, snapshot setup beats, or render a draft or delivery MP4 of a product video in this workbench. Also use it when someone says "the cursor is off", "too zoomed in", "too fast", "it feels chaotic", "the title flashes", "sync the UI to the voice", or asks for a walkthrough, demo or pitch video of a UI.

josueh04/product-video-skills

Gather pixel references for UI that the code cannot show, or to check a rebuild against the real thing, using frames and timed OCR text from screen recordings, captures recovered from past Claude Code session transcripts, a local instance of the app built like production, and web research for third-party apps, plus side-by-side parity images and contact sheets. Use it whenever someone hands over a screen recording (.mov or .mp4) of the product, when a screen has no usable source code (a stale checkout, another company's UI such as a sign-in page, calendar or CRM, runtime output from a backend not in the repos), when asked "what does it really look like", "match the recording", "how long does that animation take in the app", "compare our render to the real app", or when screenshots from an earlier session might already exist. Never uses the reviewer's personal browser.

josueh04/product-video-skills

Turn a product's real frontend code into 1:1 rebuild specs for a video, one read-only subagent per screen, each returning static HTML, CSS with every variable resolved to its literal value and cited (role/path:line@sha), every state, transitions with exact durations and easings, icons from the code's own icon sets, and the exact i18n strings; plus resolve_tokens.py to write the product's design tokens to kit/tokens.css. Use it whenever a screen of the product has to appear in a video, when writing or fixing video/src/app.css or the template markup, when someone asks for exact sizes, colors, fonts, paddings, animations or icons of a screen, when a rebuilt screen "looks off" next to the real app, and when the design tokens or theme of a product need extracting. Framework adapters cover Angular with PrimeNG (proven), React, Vue, Tailwind and plain HTML (unproven).

josueh04/product-video-skills

Say where this session stands in the Product Video Skills workbench (setup state, which product and video the current folder belongs to, the stage of every video) and the exact next command to type. Also answers "how do I..." questions about the workbench from its docs.

josueh04/product-video-skills

Coordinate the build of one or more signed videos of the current product with subagents (source recon, product truth, UI specs, voice, one builder per video), re-run QA itself, then deliver. A light coordinator that never builds itself. Run only when the user types /video-build.

josueh04/product-video-skills

Start a new video of the current product - create videos/<video>/, write BRIEF.md, the feature coverage matrix (COVERAGE.md) and the claims sheet (CLAIMS.md), propose chapters, then stop for the reviewer's sign-off. Never builds. Run only when the user types /video-new.

josueh04/product-video-skills

Turn a batch of reviewer feedback on the product's videos into one table per video, fix every video that got notes in parallel (one subagent each) while keeping approved parts, re-run QA and parity, bump versions and deliver. Run only when the user types /video-review.

josueh04/product-video-skills

Check this machine and install the pinned video toolchain of the Product Video Skills workbench (HyperFrames CLI, its rendering Chrome and its agent skills from the same release, the Python environment, the speech model for QA), then run the self-check. Safe to run again. `/video-setup check` only reports.

관련 스킬