변경 로그 → 브랜드 비디오
입력: 변경 로그 .md (테마 + 항목, 주간 HyperFrames 다이제스트 등).
출력: projects/active/weekly-changelog-<범위>/ 디렉토리에 있는 린트-클린, Seam-Gate-Green HyperFrames 프로젝트. 요청 시에만 렌더링합니다.
우선 로드, 절대 변경 불가: motion-doctrine (+ 커서가 나타나는 경우 cut-the-curve, oversized-cursor, seam-craft) 및 captions-overlay. 이 스킬은 변경 로그 관련 파이프라인을 제공하며, Doctrine은 모션 법칙을 제공합니다.
최우선 원칙: 시각화하라, 나열하지 마라
모든 테마는 텍스트 불릿이 아닌 실제 UI 또는 충실한 유사체의 애니메이션 모형을 통해 변경 사항을 경험적으로 보여줍니다. 스크립트를 작성하기 전에 각 테마/항목을 references/visualization-registry.md를 통해 라우팅하세요. 레지스트리는 ui-recreate / ui-analog / terminal / checklist를 결정합니다. 텍스트 체크리스트는 최후의 수단으로, 진정으로 시각화할 수 없는 항목(신뢰성 수정 목록)에만 사용합니다.
파이프라인
0 · 이 스킬의 자산에서 프로젝트 부트스트래핑 — 절대 변경 불가
구성 HTML을 작성하기 전에 이 작업을 수행하세요. 건너뛰면 항상 이전에 구축한 유사한 프로젝트처럼 보이는 비디오가 생성되며, 이 스킬의 브랜드가 아닙니다. 이것이 이 스킬이 브랜드에서 벗어나는 가장 흔한 방식입니다. 이 스킬의 자산, 폰트, 스캐폴드가 바로 스킬이며, SKILL.md 프롬프트는 라우터입니다.
mkdir -p project/assets/fonts
cp <SKILL_DIR>/assets/fonts/*.woff2 project/assets/fonts/
cp <SKILL_DIR>/assets/bgm.mp3 project/bgm.mp3
ffmpeg -y -stream_loop 15 -i <SKILL_DIR>/assets/bg-pattern.mp4 -t <TOTAL> \
-vf "scale=1080:1080,fps=30,eq=saturation=0.72,[email protected]:t=fill" \
-an -c:v libx264 -crf 20 -pix_fmt yuv420p project/assets/bg-pattern-<TOTAL>s.mp4
cp <SKILL_DIR>/examples/master-skeleton.html project/index.html
그런 다음 references/build-spec.md를 처음부터 끝까지 (대충 훑지 말고) 읽으세요. 모든 장면이 스캐폴드에서 상속받는 브랜드 토큰(TT Norms Pro + ABC Solar Display + TT Norms Mono, 크림색 #f5f6f4, 제한된 녹색 #5ef17c, 녹색 테두리가 있는 유리 카드, 킥커/섹-칩 알약 모양, top: 990에 위치한 32px 캡션 레일)을 정의합니다.
그런 다음에야 아래 1-6단계를 시작하세요. 1-4단계(파싱, 라우팅, 스크립트, VO)는 스캐폴드에 들어갈 내용을 계획합니다. 5단계는 이미 복사된 project/index.html 내부의 자리 표시자(<RANGE>, <TOTAL>, <CUT_N>, <DUR_N>, 장면 본문)를 채웁니다. 스캐폴드의 크롬, 폰트, 팔레트 또는 레이아웃 셸을 다시 작성하지 않습니다.
이전 비디오의 index.html에 대해 cp를 사용하려고 하거나, 직접 @font-face 선언을 작성하거나, 인코딩된 bg-pattern MP4 대신 WebGL 셰이더 배경을 디자인하려는 경우: 중지하세요. 현재 index.html을 삭제하고 master-skeleton 스캐폴드의 cp부터 다시 시작하세요. 올바른 스캐폴드에서 장면 콘텐츠를 재구축하는 것이 잘못된 스캐폴드에 브랜드를 맞추는 것보다 비용이 적게 듭니다.
1 · 파싱 + 편집 컷
- 추출: 주 범위, 헤드라인 통계(릴리스, 커밋), 테마, 항목.
- 예산: 총 45-60초. 제목 ≤2초, 아웃트로 ≤3.5초, 4개 테마 ≈ 각 9-12초.
- 각 테마당 하나의 히어로 시각화 + 최대 3개의 구어 항목을 유지하세요. 그 외 모든 것은 아웃트로의 "전체 다이제스트" 포인터로만 존재합니다. 컷팅이 작업입니다: 30개 항목이 있는 변경 로그라도 ≤14개의 구어 비트로 이어져야 합니다.
- 스토리에 따라 테마 정렬: marquee 기능 → 제품 표면 → 성능 → 신뢰성 (일반적으로 다이제스트가 이미 이 순서로 되어 있습니다).
2 · 시각화 라우팅
각 테마에 대해 references/visualization-registry.md에서 표면을 선택하고 한 줄을 작성하세요: 테마 → 표면 → 모형이 수행하는 2-4개의 순차적 액션 (각각 스크립트 구문에 연결됨). 레지스트리 표면이 맞지 않고 충실한 유사체도 없는 경우, 체크리스트 장면입니다. 정직하게 표현할 수 없는 것에 대해 가짜 UI를 발명하지 마세요.
3 · 이중 레이어 스크립트 (구어 vs 표시)
references/script-voice.md에 따라 스크립트를 토큰 라인으로 작성하세요: 대화체 레지스터, 모든 기술 용어는 references/lexicon.json에서 spoken 음성 형태를 가지며, display는 표준 철자를 유지합니다. 자막은 display를 표시합니다. VO는 spoken을 읽습니다. 용어집에 없는 용어: 중지하고 사용자에게 발음을 물어본 후 용어집에 추가하세요. 프로젝트에 script-tokens.json으로 저장합니다.
4 · VO — Annie (HeyGen, 고정)
# 구어 텍스트만; words JSON = 구어 텍스트의 그라운드-트루스 타임스탬프
# 저장소 네이티브 경로: changelog-video 스킬은 hyperframes 저장소 루트에서 실행되므로,
# 추적된 hyperframes-media TTS 도우미를 직접 사용합니다 (`npx hyperframes
# skills` 설치 단계 없음). 스킬을 다른 저장소로 복사한 경우,
# media-use / hyperframes-media heygen-tts.mjs에 대한 자체 경로로 대체하세요.
node skills/hyperframes-media/scripts/heygen-tts.mjs ./vo-spoken.txt \
-o voiceover.mp3 --words vo-words.json \
--voice 330290724a1b470fb63153f34d4c0183 # Annie — 사실적 (대체 금지)
heygen CLI ≥0.3.0이 인증되어 있어야 합니다 (heygen auth login --oauth).
그런 다음 구어 타임스탬프를 표시 토큰에 다시 정렬합니다:
node <SKILL_DIR>/scripts/align-captions.mjs \
--tokens script-tokens.json --words vo-words.json --out captions.json
captions.json은 캡션 레일 입력입니다 (표시 철자, 구어 타이밍).
정렬기는 MISMATCH 경고를 출력합니다. 빌드 전에 모든 경고를 해결하세요 (일반적으로 TTS가 여러 단어로 렌더링하는 용어집 철자로 인해 발생). 오디오가 시계입니다: 모든 비트 시간은 vo-words.json에서 비롯됩니다. VO 재생성은 모든 이음새를 다시 엽니다.
단어 타이밍은 하드 게이트입니다. 5단계로 이동하기 전에 vo-words.json이 비어 있지 않고 각 단어에 start/end가 있는 words: [...] 배열이 있는지 확인하세요. 비어 있거나(0바이트) 배열이 누락된 경우( TTS 제공자가 오디오는 반환하지만 타임스탬프 페이로드는 반환하지 않는 알려진 오류 모드), 진행하지 마십시오. 폴백: 로컬 whisper를 사용하여 생성된 오디오를 표시 스크립트에 대해 강제 정렬합니다:
uvx --from openai-whisper whisper voiceover.mp3 \
--model base.en --language en --word_timestamps True \
--output_format json --output_dir .
# 그런 다음 align-captions.mjs를 --words voiceover.json (동일한 형태)로 실행
Whisper는 TTS 렌더링을 잘못 들을 수 있습니다 ("gee-sap" → "gsap", "heyjen" → "hey Jen" 등). 자막은 script-tokens.json의 표시 철자를 계속 사용합니다. whisper는 타임스탬프만 제공합니다. align-captions.mjs가 조인을 처리합니다. 이 폴백은 자막이 있는 빌드와 조용히 자막이 없는 빌드의 차이입니다.
5 · 빌드
references/build-spec.md를 정확히 따르세요: 브랜드 토큰 + 폰트(<SKILL_DIR>/assets/에 번들링됨), 애니메이션 배경 인코딩, 장면 스캐폴드, 크롬, 캡션 레일, 각 장면당 하나의 제한된 녹색 순간. 그런 다음 Doctrine 순서: ledger.json(모든 일반 이음새는 cut-the-curve LEFT) → seam-stamp → VO 단어의 내부 비트 → seam-gate 확인.
자막은 선택 사항이 아닙니다. master-skeleton은 LINES 배열을 읽는 캡션-레일 IIFE를 제공합니다. 해당 배열을 비워두는 것은 스타일 선택이 아닌 배송 버그입니다. 6단계로 진행하기 전에 captions.json에서 채우세요:
// 캡션-레일 IIFE에서 "const LINES = /* … */ []"를 다음으로 대체:
const LINES = /* captions.json 내용 */ [
{ id: 0, end: 2.74, w: [["This", 0.0], ["week,", 0.30], …] },
…
];
align-captions.mjs를 건너뛰거나 LINES가 []인 경우, 6단계의 프레임 검사가 실패합니다. 스캐폴드에서 #cap-line을 제거하여 은폐하지 마세요.
6 · 게이트 (제시 전에 모두 통과)
bun run --cwd packages/cli hyperframes check(또는skills/hyperframes-cli/스킬의 설치된hyperframesCLI) — 0 오류 (대비: 어두운 텍스트 ≥ .66 알파).npx hyperframes@latest에 의존하지 마십시오. 추적된 저장소-로컬 CLI가 이 스킬이 생성하는 구성 계약에 대한 진실의 원천입니다.seam-gate.mjs verify— 0 실패.- 미리보기 서버를 다시 시작하고(번들을 캐시함), 원시 컴포 페이지에서
__player.seek를 통해 3-4비트를 샘플링 확인합니다. - 사용자가 요청하지 않는 한 렌더링하지 마십시오. 요청된 렌더링 후, MP4에서 프레임을 확인합니다(
ffmpeg -ss <t> … -frames:v 1): 자막 표시, 배경 비디오 검은색 아님, 작거나 정지된 프레임 없음. - 자막 존재 게이트 — 하드 실패. VO의 구어 창 전체에 걸쳐 3-4개 프레임을 샘플링합니다(예: 48초 VO의 경우
t=3,t=15,t=30,t=42).top: 990의 캡션 레일이 각 프레임에 표시 텍스트를 렌더링하는지 확인하세요. 구어 구간의 프레임에서 자막이 누락된 경우, 빌드는 자막 없이 배송됩니다. 빨간 게이트로 처리하고 5단계의LINES채우기를 다시 확인하세요. 이것이 Jul 13-20 v4 빌드에서 정확히 문제였던 부분입니다.
프로젝트 레이아웃
projects/active/weekly-changelog-<범위>/
├── index.html # 단일 문서 마스터 (슬라이드로서의 장면, 찍힌 이음새)
├── ledger.json # 벡터 원장 (seam-stamp 입력)
├── script-tokens.json # 이중 레이어 스크립트 (VO + 자막의 진실 소스)
├── vo-spoken.txt # 생성됨: 구어 레이어, 한 줄
├── voiceover.mp3 + vo-words.json + captions.json
├── bgm.mp3 # 사용자가 제공하지 않는 한 <SKILL_DIR>/assets/bgm.mp3 (하우스 트랙)에서 복사
└── assets/fonts/ + assets/bg-pattern-<dur>s.mp4
안티-패턴
| 하지 말아야 할 것 | 대신 이렇게 하세요 |
|---|---|
| UI 변경 사항에 대한 불릿 포인트 슬라이드 | 변경 사항을 보여주는 표면 모형 애니메이션 |
| 표현할 수 없는 항목에 대한 가짜 UI | 정직한 체크리스트 장면 |
| TTS 텍스트에 일반 "JSON"/"CLI" | 용어집 구어 형태 사용; 표시는 표준 유지 |
| 자막에서 음성 철자 사용 | 자막은 항상 표시 레이어를 렌더링 |
| 알 수 없는 용어 발음 추측 | 질문하고 용어집 확장 |
| 모든 변경 로그 항목 말하기 | 테마당 ≤3개; 다이제스트 링크가 나머지 전달 |
| 모든 곳에 녹색 악센트 사용 | 장면당 하나의 녹색 순간 (#5ef17c) |
| 이전 비디오의 index.html에서 시작 | 0단계 — 이 스킬의 examples/master-skeleton.html을 project/index.html에 항상 복사 |
수동 @font-face / WebGL 셰이더 / 사용자 정의 BGM | 0단계 — 이 스킬의 assets/를 그대로 복사; 스킬의 자산이 브랜드입니다 |
| CloudFront 무효화 없이 배송 | S3 교체 후 정확한 경로에 대해 배포 E2BSLVSZ7FG3U0에서 aws cloudfront create-invalidation 실행 — 그렇지 않으면 CDN이 이전 파일을 캐시함 |
스캐폴드에서 LINES 배열을 비워두고 배송 | 4단계는 채워진 captions.json을 생성해야 함; 5단계는 이를 IIFE에 붙여넣어야 함; 6단계 게이트 5는 렌더링된 프레임에서 자막을 확인해야 함. 빈 LINES = 자막 없는 배송 = 실행 다시 수행 |
vo-words.json 없이 자막 건너뛰고 그냥 배송 | 생성된 오디오에 대해 whisper 강제 정렬로 폴백; 자막은 선택 사항이 아님 |