PR 워크스루 비디오
풀 리퀘스트에 대한 내레이트 워크스루 비디오를 생성합니다. 이는 내부 아티팩트로 설계되어, PR 작성자가 만드는 Loom 비디오와 동일한 이점을 제공합니다. 즉, 코드 변경 사항을 살펴보고, 무엇이 변경되었고 왜 변경되었는지 설명하여, 시청자가 PR을 빠르게 이해할 수 있도록 합니다.
입력: GitHub PR URL (예: https://github.com/tldraw/tldraw/pull/7924). PR 번호 또는 다른 설명만 주어진 경우, PR이 tldraw/tldraw 저장소에 있다고 가정합니다.
출력: 오디오 내레이션, Whisper 타이밍의 노란색-검정 자막, 표준 인트로/아웃트로 슬라이드가 포함된 1280×720 (30fps) MP4 비디오. out/pr-<number>-walkthrough.mp4로 저장됩니다.
모든 중간 파일(오디오, 매니페스트, 스크립트)은 이 스킬 디렉토리 기준 tmp/pr-<number>/에 위치합니다. 이 디렉토리는 gitignore에 포함됩니다. 최종 .mp4 파일만 out/에 저장됩니다.
./scripts 또는 ./video를 참조하는 명령은 이 스킬 디렉토리에서 실행하세요.
철학
이것은 작성자 관점의 워크스루입니다. 목표는 PR 작성자가 누군가와 함께 앉아 변경 사항을 설명하는 것과 동일합니다. 즉, 특정 코드를 보여주고, 무엇이 변경되었고 왜 변경되었는지, 이해를 쌓을 수 있는 순서로 설명하는 것입니다. 시청자는 _코드가 무엇을 하는지_와 _변경 사항에 대해 어떻게 생각해야 하는지_를 모두 이해하게 되어야 합니다.
이는 다음을 의미합니다:
- 내레이션이 모든 것을 주도합니다. 워크스루 내레이션을 먼저 PR에 대한 연속적인 설명으로 작성하세요. 그런 다음 각 순간에 화면에 무엇이 표시되어야 할지 결정하여 말하는 내용을 지원합니다.
- 코드를 보여주세요. 기본 시각 요소는 코드 diff 또는 소스 파일입니다. 텍스트 슬라이드는 예외(인트로, 간단한 전환, 아웃트로)이지 규칙이 아닙니다. 내레이션이 함수에 대해 이야기할 때, 시청자는 그 함수를 보고 있어야 합니다.
- 변경 사항을 논리적인 순서로 살펴보세요. 파일 순서나 커밋 순서가 아닌, 항상 구체적인 코드에 기반하고 추상적인 설명에 기반하지 않아야 합니다.
- "무엇"뿐만 아니라 "왜"를 설명하세요. 화면의 코드는 무엇이 변경되었는지 보여줍니다. 내레이션은 추론, 즉 이 접근 방식을 선택한 이유, 해결하는 문제, 처리하는 엣지 케이스를 추가합니다.
워크플로우
1단계: PR 이해하기
PR 커밋, diff, 설명을 읽으세요. 내러티브 아크를 이해하세요:
- 이 PR은 어떤 문제를 해결하나요?
- 접근 방식은 무엇인가요?
- 주요 메커니즘은 무엇인가요?
gh pr view <number> --json title,body,commits
git log main..HEAD --oneline
git diff main..HEAD --stat
생성된 파일은 건너뛰세요. diff를 읽을 때 수동으로 편집된 파일이 아닌 자동 생성된 파일은 무시하세요. 이는 워크스루에 정보를 추가하지 않고 노이즈만 추가합니다. 이 저장소의 일반적인 예:
**/api-report.md,**/api-report.api.md— 생성된 API 표면 보고서**/*.api.json,**/temp/*.api.json— API 추출기 출력apps/docs/content/reference/**— 생성된 참조 문서pnpm-lock.yaml,package-lock.json— 잠금 파일**/CHANGELOG.md— 자동 생성된 변경 로그- 저장소 도구가 다시 생성하는 모든 파일(스냅샷, 스키마 덤프, 번들된 에셋)
파일이 생성된 것인지 확실하지 않은 경우, "DO NOT EDIT"와 같은 헤더 주석이 있는지 확인하거나 저장소에 해당 파일을 생성하는 생성기 명령이 있는지 확인하세요. diff/code 슬라이드에 포함할 파일을 선택할 때 이를 걸러내세요.
2단계: 내레이션 작성하기
내레이션을 연속적인 텍스트로 작성하고, 논리적 세그먼트로 나누세요. 각 세그먼트는 워크스루의 한 비트, 즉 개념, 변경 사항 또는 관련 변경 사항 그룹입니다. 이를 tmp/pr-<number>/SCRIPT.md로 저장하세요.
내레이션은 작성자가 동료에게 PR을 설명하는 것처럼 읽혀야 합니다: "자, 여기서 우리가 하는 일은... 핵심 문제는 X였습니다... 제가 취한 접근 방식은 Y입니다... 여기 이 함수를 보시면..."
구조: 인트로 → 맥락/문제 → 코드 워크스루 → 요약. 아래 스크립트 구조를 참조하세요.
커밋이 간단하고 잘 구성되어 있다면(종종 이름에 -clean이 포함된 브랜치에), 커밋 메시지와 설명을 따라 내레이션을 안내할 수 있습니다. 그렇지 않으면 코드를 검토하고 자신만의 내러티브를 만드세요. 이전 개념을 기반으로 구축할 수 있는 순서로 개념을 도입하세요.
특히 인트로와 첫 번째 콘텐츠 세그먼트 간의 중복을 피하세요.
3단계: 오디오 및 타임스탬프 생성
세그먼트당 하나의 TTS 호출로 세그먼트별 오디오 클립을 생성하세요. 이렇게 하면 청킹, 정렬 및 분할을 완전히 피할 수 있습니다. 각 세그먼트는 단일 안정적인 TTS 호출에 충분히 짧습니다.
narration.json 파일을 작성한 다음 generate-audio.sh CLI 도구를 실행하세요:
./scripts/generate-audio.sh narration.json tmp/pr-<number>/
API 키: 저장소 .env 파일(GEMINI_API_KEY)에서 자동으로 가져옵니다.
내레이션 JSON 형식
{
"style": "Read the following walkthrough narration in a calm, steady, professional tone. Speak at a measured pace as if the author of a pull request were walking a colleague through the code changes.",
"voice": "Iapetus",
"slides": [
"This pull request adds group-aware binding resolution to the arrow tool...",
"The core problem was that arrow bindings broke when the target shape...",
"If you look at the getBindingTarget method in ArrowBindingUtil.ts..."
]
}
style— 음성 페르소나 및 속도 지침. 짧고 구체적으로 유지하세요.voice— Gemini 음성 이름 (기본값:Iapetus).slides— 내레이션 텍스트 배열, 세그먼트당 하나의 항목.
작동 방식
- 각 세그먼트에 대해 스크립트는 프롬프트를 작성합니다: 스타일 전문 + 세그먼트 텍스트.
- 세그먼트당 하나의
gemini-3.1-flash-tts-previewAPI 호출로 WAV 클립을 직접 생성합니다. - 각 클립의 유효성을 검사하고(단어 수 대비 기간), 출력이 좋지 않으면 자동으로 재시도합니다.
- 각 클립에서 앞/뒤 무음을 제거합니다.
출력: 세그먼트별 오디오 클립(audio-00.wav, ...) 및 각 오디오 파일 이름을 초 단위 기간에 매핑하는 durations.json 파일.
의존성: ffmpeg / ffprobe. 표준 라이브러리 외에 Python 패키지가 필요하지 않습니다.
내레이션 텍스트에 [pause long] 또는 [pause medium] 마크업 태그를 사용하지 마세요 — 모델이 이를 문자 그대로 읽을 수 있습니다.
4단계: 매니페스트 작성
3단계의 durations.json에서 각 클립 길이를 읽은 다음 오디오 파일과 함께 manifest.json을 작성하세요. 각 슬라이드에 대해 순서대로 하나의 항목을 나열하며, 각각 type, audio 및 durationInSeconds를 포함합니다.
슬라이드 유형 및 해당 필드는 references/manifest.md를 참조하세요.
5단계: 비디오 렌더링
render.sh 스크립트를 실행하세요:
./video/render.sh \
tmp/pr-<number>/manifest.json \
out/pr-<number>-walkthrough.mp4
스크립트는:
- 참조된 오디오/이미지 파일을
video/assets/에 복사합니다. - 각 오디오 파일에 대해 Whisper 전사를 실행합니다 →
video/transcripts/audio-NN.json(멱등성 — 오디오가 기존 전사본보다 최신인 경우에만 다시 전사합니다). build.mjs <manifest>를 실행하여video/index.html을 생성합니다. 이는 모든 슬라이드에 대한 시간 제어 클립, 전환 및 코드 포커스 팬을 위한 GSAP 타임라인, Whisper 전사본에서 파생된 시작/종료 시간이 포함된 노란색-검정 자막 클립이 있는 하이퍼프레임 구성입니다.- 구성을 린트하고
npx hyperframes render를 통해 1920×1080 프레임을 렌더링합니다. - 최종 작지만 선명한 MP4를 위해 1280×720 / 30fps로 다운스케일하고 ffmpeg(CRF 26 + AAC 96k)로 다시 압축합니다.
의존성: Node.js 22+, ffmpeg, Python 3 (render.sh에서 매니페스트를 구문 분석하는 데 사용됨). hyperframes는 npx --yes를 통해 호출되므로 설치 단계가 필요하지 않습니다. Whisper는 로컬에서 실행됩니다(small.en 모델, 첫 번째 다운로드 시 약 150MB).
Whisper를 통한 자막 동기화
자막은 화면 하단에 고정된 단색 검정 필 위에 노란색 텍스트로 나타납니다. 시작/종료 시간은 5-7단어 덩어리로 그룹화된 단어 수준 Whisper 전사본에서 비롯되며, 자연스러운 일시 중지(>450ms 간격 = 문장 경계)에서 끊어집니다. 한 가지 의미: Whisper는 브랜드/코드 이름을 음성학적으로 전사합니다. "tldraw" → "TL Draw", "OverlayUtil" → "overlay util". 이는 자막에 허용되지만 build.mjs의 대체 테이블을 통해 나중에 정규화할 수 있습니다.
파일 크기 조정
기본 렌더링은 8분 비디오의 경우 약 30-60MB를 대상으로 합니다. 조정하려면:
render.sh내부의 ffmpeg 다운스케일 단계에서--crf <n>— 22는 거의 무손실, 26은 기본값, 30+는 훨씬 작습니다. CRF 28-30은 문서 품질 결과에 적합한 범위입니다.- 1080p 하이퍼프레임 렌더링은
-q draft --crf 30을 사용하여 중간 파일을 작게 유지합니다(어차피 다운스케일이 최종 크기를 지배합니다).
파일 구성
최종 출력은 이 스킬 디렉토리에 저장됩니다. 모든 중간 파일은 tmp/(gitignore됨)에 저장됩니다:
pr-walkthrough/
├── SKILL.md # 이 파일
├── scripts/ # CLI 도구 (체크인됨)
│ └── generate-audio.sh # narration.json → 슬라이드별 WAV + durations.json
├── video/ # Hyperframes 프로젝트 (체크인됨)
│ ├── hyperframes.json # hyperframes 구성
│ ├── meta.json # 프로젝트 메타
│ ├── build.mjs # manifest.json → index.html 구성
│ ├── render.sh # manifest.json → 720p MP4 (전체 파이프라인)
│ ├── assets/ # 렌더링 시 자동 채워짐 (gitignore됨)
│ ├── transcripts/ # Whisper 단어 수준 JSON (gitignore됨, 캐시됨)
│ └── renders/ # 중간 1080p 렌더링 (gitignore됨)
├── out/ # 최종 출력 (gitignore됨)
│ └── pr-XXXX-walkthrough.mp4
└── tmp/ # 중간 파일 (gitignore됨)
└── pr-XXXX/
├── SCRIPT.md # 내레이션 스크립트
├── narration.json # generate-audio.sh에 대한 입력
├── durations.json # 오디오 파일 이름 → 초 단위 기간
├── manifest.json # render.sh에 대한 입력
└── audio-XX.wav # 세그먼트별 오디오 클립
API 구성
- Gemini API 키: 프로젝트 루트
.env파일에GEMINI_API_KEY로 저장됨. TTS 및 오디오 정렬에 사용됨. - TTS 모델:
gemini-3.1-flash-tts-preview - TTS 음성:
Iapetus(항상)
스크립트 구조
워크스루는 일관된 내러티브 아크를 따릅니다. 모든 섹션에 자체 세그먼트가 필요하지는 않습니다. PR의 복잡성에 따라 섹션을 결합하거나 건너뛰세요. 목표는 총 8-12개의 세그먼트이며, 대부분이 코드를 표시합니다.
인트로 (1개 세그먼트)
인트로 카드: tldraw 로고 + PR 제목 + 날짜. 내레이션은 이 PR이 높은 수준에서 무엇을 하는지 설명하는 단일 문장이어야 합니다. 아직 세부 사항으로 들어가지 마세요.
매니페스트 슬라이드 유형: intro.
맥락 (0-1개 세그먼트)
코드에 들어가기 전에 간단한 오리엔테이션. 이 PR 이전의 상황은 어땠습니까? 어떤 문제나 필요가 작업을 동기부여했습니까? 코드 워크스루가 이해가 되도록 충분한 프레임만 유지하고 짧게 유지하세요.
- 구체적으로: "대상 모양이 그룹 내부에 있을 때 화살표 바인딩이 끊어졌습니다"가 아니라 "바인딩에 문제가 있었습니다"
- 영향을 받은 코드베이스 영역의 이름을 지정하세요
맥락이 첫 번째 관련 코드를 표시하면서 설명될 수 있다면, 독립형 맥락 세그먼트를 건너뛰고 첫 번째 코드 세그먼트에 통합하세요.
매니페스트 슬라이드 유형: text 또는 diff (문제가 있는 코드를 표시하는 경우).
코드 워크스루 (6-10개 세그먼트)
비디오의 주요 부분. 실제 코드 변경 사항을 살펴보고, 특정 diff 및 파일을 표시하면서 무엇이 변경되었고 왜 변경되었는지 설명하세요.
모든 세그먼트는 코드를 표시해야 합니다. 변경 사항에는 diff 슬라이드를, 변경되지 않은 참조 코드에는 code 슬라이드를 사용하세요.
지침:
- 파일 및 함수 이름을 지정하세요. 모든 내레이션 세그먼트는 하나 이상의 특정 파일 또는 함수를 참조해야 합니다.
- diff를 표시하세요. 각 세그먼트의 시각 자료는 논의 중인 실제 diff여야 합니다.
git diff main..HEAD -- path/to/file을 사용하여 diff를 가져온 다음 관련 헝크를 추출하세요. - 파일 순서가 아닌 이해 순서로 정렬하세요. 이해를 쌓는 순서로 변경 사항을 제시하세요. 새 유형이 한 파일에서 정의되고 다른 파일에서 사용되는 경우, 정의를 먼저 표시하세요.
- "무엇"뿐만 아니라 "왜"를 설명하세요. diff는 무엇이 변경되었는지 보여줍니다. 내레이션은 추론, 즉 처리하는 엣지 케이스, 고려된 대안을 추가합니다.
- 상용구는 건너뛰되, 언급하세요. 모든 import 변경이나 유형 내보내기에 세그먼트를 할애하지 말고, 지나가면서 언급하세요: "
index.ts에 추가된 유형 내보내기도 있습니다. 이것들은 우리가 다음에 볼 새 유형의 재내보내기일 뿐입니다." - 관련된 작은 변경 사항을 그룹화하세요. 세 파일 모두 동일한 한 줄 수정을 받은 경우, 하나의 세그먼트로 세 가지를 모두 다룰 수 있습니다. 각 파일을 이름으로 언급하세요.
요약 (1개 세그먼트)
PR이 달성한 것을 간단히 요약하세요. 이것은 짧은 마무리입니다. 전체 변경 사항을 요약하는 한두 문장으로, 관련된 경우 알려진 제한 사항이나 후속 작업을 언급하세요.
매니페스트 슬라이드 유형: text.
아웃트로 (1개 세그먼트, 무음)
tldraw 로고, 3초 무음. 항상 마지막 슬라이드로 포함하세요.
매니페스트 슬라이드 유형: durationInSeconds: 3인 outro.
내레이션 작성 팁
- 코드에 대해 구체적으로 말하세요. "바인딩 시스템이 업데이트되었습니다"가 아니라 "
BindingUtil.ts에서onAfterChange핸들러가 이제 그룹 조상을 확인합니다"라고 말하세요. 시청자가 내레이션을 화면의 내용과 연결할 수 있도록 파일 및 함수 이름을 지정하세요. - 각 세그먼트 = 하나의 변경 사항 또는 밀접하게 관련된 변경 사항 그룹. 세그먼트에 대해 특정 diff를 가리킬 수 없다면 아마도 너무 추상적일 것입니다.
- 작성자처럼 작성하세요. 어조는 설명적이고 자연스러워야 합니다. 마치 누군가에게 작업을 설명하는 것처럼요. "자, 여기서 중요한 점은..." 또는 "까다로운 부분은..."도 괜찮습니다.
- 인트로와 첫 번째 콘텐츠 세그먼트 간의 중복을 피하세요.
- 표시되지 않은 파일을 언급하세요. PR이 15개의 파일을 건드렸지만 6개만 흥미로운 경우, 나머지를 간략하게 인정하세요: "나머지 변경 사항은 유형 내보내기와 테스트 픽스처입니다."
- 총 내레이션 시간은 5-7분을 목표로 하세요.
체크리스트
- 모든 PR 커밋을 읽고 전체 diff를 이해했습니다.
- SCRIPT.md에 내레이션을 작성했습니다 (8-12개 세그먼트).
- 세그먼트별 오디오를 생성했습니다 (Iapetus 음성).
- durations.json을 읽어 세그먼트별 기간을 확인했습니다.
- manifest.json을 작성했습니다.
- render.sh를 실행하여 비디오를 생성했습니다.
- 최종 비디오를 확인했습니다 (오디오 싱크, 자막 정확도, 시각적 품질).
- 중간 파일을 정리했습니다 (tmp/ 디렉토리는 자동으로 gitignore되지만, 대용량 오디오 파일을 수동으로 제거할 수 있습니다).