체인지로그 → 브랜디드 비디오
입력: 체인지로그 .md 파일 (테마 + 항목, 주간 HyperFrames 다이제스트와 같은 형식).
출력: 린트-클린, 심-게이트-그린 HyperFrames 프로젝트가 projects/active/weekly-changelog-<범위>/에 생성됩니다. 요청 시에만 렌더링합니다.
먼저 로드해야 하는 필수 사항: 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개의 스포큰 비트를 산출합니다.
- 테마는 스토리 순서로 정렬: 마키 기능 → 제품 표면 → 성능 → 신뢰성 (다이제스트는 일반적으로 이미 이 순서로 읽힙니다).
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, 고정)
# spoken-layer 텍스트만; words JSON = SPOKEN 텍스트의 ground-truth 타임스탬프
# 레포 네이티브 경로: 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 .
# 그런 다음 --words voiceover.json(동일한 형태)로 align-captions.mjs 실행
Whisper는 TTS 렌더링을 잘못 이해할 수 있습니다 ("gee-sap" → "gsap", "heyjen" → "hey Jen" 등). 자막은 여전히 script-tokens.json의 DISPLAY 철자를 사용합니다. whisper는 타임스탬프만 제공합니다. align-captions.mjs가 조인을 처리합니다. 이 대체 방법은 자막이 있는 빌드와 조용히 자막 없는 빌드의 차이입니다.
5 · 빌드
references/build-spec.md를 정확히 따르십시오: 브랜드 토큰 + 폰트(<SKILL_DIR>/assets/에 번들됨), 애니메이션 배경 인코딩, 장면 스캐폴드, 크롬, 자막 레일, 각 장면당 하나의 제한된 그린 모먼트. 그런 다음 doctrine 순서: ledger.json (모든 일반 심은 cut-the-curve LEFT) → 심-스탬프 → VO 단어의 내부 비트 → 심-게이트 확인.
자막은 선택 사항이 아닙니다. 마스터-스켈레톤은 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(또는 설치된hyperframesCLI from the repo-localskills/hyperframes-cli/skill) — 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-<range>/
├── index.html # 단일 문서 마스터 (슬라이드로 된 장면, 스탬프된 심)
├── ledger.json # 벡터 원장 (심-스탬프 입력)
├── 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 강제 정렬로 대체; 자막은 선택 사항이 아님 |