Viva Video

한 편의 제품 문서로부터 정확하게 전달하고, 선명하게 보여주며, 모든 프레임이 코드로 생성되는 영상을 제작합니다.

cinematic-product-video와의 차이점: 해당 스킬은 SeedDance를 사용하여 영화적인 소재를 생성하며, 브랜드 중심입니다. 이 스킬은 생성된 소재를 전혀 사용하지 않고 모든 것을 코드로 렌더링하며, 정보 중심입니다. 두 스킬은 독립적이며 혼용하지 마십시오.

납품하는 것은 완성본이며, 스토리보드가 아닙니다. 사양이나 프롬프트만 수정하라는 요청을 받으면 파일 수정 및 검증에 그치고, 유료 생성 또는 전체 렌더링을 시작하지 않습니다.

첫 번째 작업: 문서를 완전히 이해하십시오. 이 단계를 통과하지 못하면 이후 모든 것이 잘못됩니다.

영상이 전달에 실패하는 첫 번째 이유는 렌더링이 아니라 문서를 완전히 이해하지 못한 상태에서 레이아웃을 시작하기 때문입니다. film-rules.yaml의 comprehension 섹션은 차단(blocking) 되며, compose_spec.py가 이를 확인합니다.

세 가지 문서를 생성해야 합니다

파일	내용	역할
`UNDERSTANDING.md`	이것이 무엇인지, 누구의 어떤 문제를 해결하는지, 메커니즘 인과 관계, 핵심 수치 및 측정 조건, 시청자가 시청 후 답할 수 있어야 하는 세 가지 질문, 문서가 주장하지 않은 사항, 이해할 수 없는 지점은 unknown으로 표시	영상이 잘못 말하거나 과장하는 것을 방지
`CLAIMS.md`	각 결론마다 한 줄: claim / 출처 / 메커니즘 / 이점 / 제한 조건 / 시각적 증거 / 위험 표현	영상의 모든 문장이 이 표에 역추적 가능해야 함
`CONCEPT_MAP.md`	문서 장 → claim → 메커니즘 및 이점 → 시각적 주제 및 동작 → 금지된 오해 → 판단에 필요한 증거	"무엇을 말할지"를 "무엇을 그릴지"로 변환

동시에 결론을 content.yaml의 content.understanding에 채웁니다. compose_spec.py가 이를 검증합니다.

문서를 덮고 다음 다섯 가지 질문에 답하십시오

답할 수 없으면 다시 읽고, 의문을 가진 상태로 진행하지 마십시오.

이 제품이 해결하는 문제는 무엇이며, 사용자가 기존에 어떻게 했고,痛点은 무엇인가?
메커니즘을 인과 관계 체인으로 설명하되, 중간 단계를 건너뛰지 마십시오.
결론을 가장 잘 증명하는 숫자는 무엇이며, 어떤 조건에서 측정되었는가? 조건이 바뀌어도 유효한가?
시청자가 이것을 가장 오해할 수 있는 것은 무엇이며, 화면에서 어떻게 방지할 것인가?
문서에서 마케팅 레토릭이며 사실로 방송되어서는 안 되는 문장은 무엇인가?

이해한 후에 재구성해야 하며, 목차를 그대로 따라가지 마십시오

순서는 문제 → 기존 방식의 비용 → 새로운 메커니즘 → 증거 → 적용 범위 → 다음 단계입니다. 각 장면은 하나의 결론만 말합니다. 결론을 먼저 제시하고, 그 다음 메커니즘, 그 다음 증거를 제시합니다. 용어가 처음 등장할 때는 한 문장으로 설명합니다.

금지: "대폭 향상", "전면 업그레이드", "현저히 최적화"와 같은 표현으로 문서에 이미 제공된 구체적인 숫자를 대체하는 것; 문서에 숫자가 없을 때 직접 만드는 것; 로드맵을 이미 출시된 것처럼 말하는 것; 예제 코드를 더 예쁘지만 실행되지 않는 방식으로 다시 작성하는 것; 특정 장을 이해하지 못하고 제목으로 추측하는 것. compose_spec.py가 이러한 관용구를 검색하고 오류를 보고합니다.

체크포인트

content.yaml을 작성하기 전에, UNDERSTANDING.md, 장 개요, 각 장의 한 문장 결론, 각 장에 사용할 시각적 프로토타입을 사용자에게 검토하도록 제출하십시오.

사실 레이어가 승인되지 않으면 시각적 레이어로 진행하지 마십시오. 이 단계에서의 재작업이 가장 저렴하고, 완성본 재작업이 가장 비쌉니다.

방법 출처: 전환 결정 테이블, 포커스 세 가지, 에너지 프레임워크, 3미터 테스트, 중국어 조판 등의 섹션은 huashu-design(화슈)에서 차용했습니다. 무엇을 가져왔고, 무엇을 보았지만 가져오지 않았으며, 왜 가져오지 않았는지는 references/borrowed-from-huashu-design.md에 기록되어 있습니다.

세 가지 레이어 구조, 가운데 레이어만 매번 변경됨

레이어	파일	영상 제작 시
규칙 레이어	`references/film-rules.yaml`	변경하지 않음. 반드시 충족해야 할 사항: 문서 이해, 한 프레임에 한 가지, 내레이션과 정보 단위의 일대일 대응, 말하는 대상 강조, 절대적인 컷 없음, 밀도 하한선, 렌더링 불변량 R01–R30, 승인 게이트 Q01–Q38, 측정 방법 및 임계값
테마 패키지	`themes/<name>/theme.yaml`	느낌을 바꿀 때만 변경. 모양: 색상 팔레트, 글꼴 크기, 좌표, 카드 및 탐색 표시 방법, 애니메이션 곡선, 전환 유형 선택, 포커스의 먹(잉크) 양, 배경 음악의 BPM 및 악기 구성
제품 콘텐츠	당신의 `content.yaml`	이것만 작성. 이해, 사실, 장, claims, 지표, 브랜드 리소스, 발음 표, 각 장의 설명 방식 및 정보 단위
합성 결과물	`video-spec.resolved.yaml`	수동으로 편집하지 마십시오, 스크립트로 생성

규칙 레이어와 테마 패키지의 경계는 단 하나입니다: 느낌을 바꾸는 것이 "내레이션이 화면과 일치해야 한다"를 바꿀 수 없어야 합니다. 판단 기준은 규칙 레이어에 남아 있고, 느낌은 테마 패키지에 위임됩니다. theme_contract는 양쪽을 모두 기계가 확인 가능한 체크리스트로 작성합니다. 패키지에 키가 없거나, 범위를 벗어나거나, 판단 기준을 변경하려고 하면 validate_spec.py가 즉시 거부합니다. 기본 패키지는 daylight(거의 흰색 배경 + 흰색 카드 + 브랜드 색상 3중 정지 그래디언트)이며, 스킬의 기본 느낌입니다. 새 패키지를 작성하는 방법은 themes/README.md를 참조하십시오.

SKILL=~/.agents/skills/viva-video
cp $SKILL/templates/content.example.yaml ./content.yaml
# 먼저 문서를 읽고 이해한 후, understanding을 채우고; 나머지 TODO를 채우십시오
python3 $SKILL/scripts/compose_spec.py  ./content.yaml -o ./video-spec.resolved.yaml  # --theme <패키지명> 추가하여 느낌 변경
python3 $SKILL/scripts/validate_spec.py ./video-spec.resolved.yaml --self-test

examples/content.viva-video.yaml은 작성 예시입니다(viva-video 1.0 자체 출시 영상, 7개 장).

음성 및 비디오 모델: 사용자가 제공하는 것을 사용하고, 제공하지 않으면 자신의 능력만 사용

스킬은 어떤 음성 또는 비디오 모델의 주소나 키도 포함하지 않습니다.

사용자가 자신의 TTS, 음성 인식 또는 비디오 모델을 호출하는 방법을 명시한 경우(명령어, API 문서, 기존 스크립트 등): 이를 하나의 명령어로 묶어 providers.json에 작성합니다. 그런 다음 tts.mjs, pron_calibrate.mjs, asr_check.mjs --backend command 모두 이를 사용합니다. 키는 환경 변수나 사용자 자신의 설정에만 남겨두고, 엔지니어링 파일, 로그 및 메시지에는 작성하지 않습니다.
사용자가 말하지 않은 경우: 에이전트가 현재 가지고 있는 능력만 사용합니다. 환경에 기성 음성 도구가 있으면 사용하고; 없으면 자막만 있고 내레이션이 없는 영상을 출력하며, 발음 검사는 not_tested로 기록합니다. 특정 서비스의 주소나 키를 추측하거나 검색하지 마십시오.

형식, 검색 순서 및 폴백 테이블은 references/providers.md를 참조하십시오.

제품을 변경할 때 처음 세 가지 작업, 순서를 바꿀 수 없음

1. 발음 결정

중국어 TTS는 Rspack을 하나의 영어 단어로 전체적으로 읽으며, 중간의 s가 생략됩니다. 실제 측정 결과 회전 쓰기는 Spac이 됩니다.

수정 방법은 TTS가 문자 단위로 읽도록 하는 것이며, 이름을 한자로 변환하는 것이 아닙니다. 작성법: RS + 공백 + 나머지 영어 단어.

표시	TTS에 전달	읽히는 소리
Rspack	`RS pack`	R-S-pack
Rsbuild	`RS build`	R-S-build
Rstest	`RS test`	R-S-test
Rsdoctor	`RS doctor`	R-S-doctor

2026-11-04 실제 측정(특정 중국어 여성 음색, 속도 1.24, 합성 후 로컬 faster-whisper로 회전 쓰기):

작성법	회전 쓰기	판정
`Rspack`	Spac	아니오, s 손실
`RS pack`	RSPAC	채택, 네 단어 총 길이 7.78초
`R S pack`	RS Pack	사용 가능, 약간 김
`R 斯 pack`	OSPAC	아니오, 한자 "斯"가 앞의 R을 왜곡시킴
`R-S-pack`	RS Pack	아니오, 하이픈이 멈춤을 삽입하여 전체 문장이 1.5초 길어짐
`而斯派克`	而斯派克	아니오, 전체가 중국어화되어 영어 단어가 사라짐

단위는 반드시 펼쳐야 합니다: 실제 측정 결과 915.8 ms는 "915.8 미터"로 읽힙니다. "915.8 밀리초"로 작성하십시오. pronounce.py가 이 작업을 자동으로 수행합니다(숫자 뒤의 단위만 대체).

문자 약어(SSR / BFF / SWC / CLI), 소수, 백분율, 버전 번호 3.0은 실제 측정 결과 모두 올바르게 읽히므로, 불필요하게 다시 작성하지 마십시오.

python3 scripts/pronounce.py --self-test                 # 8개 테스트
python3 scripts/pronounce.py "분석 소요 시간이 915.8 ms에서 51.6 ms로 감소했습니다."
node     scripts/pron_calibrate.mjs --terms terms.json   # 제품/음색 변경 시 실제 측정하여 작성법 선택
node     scripts/asr_check.mjs --spec video-spec.resolved.yaml --voice voice/

음색, 속도 변경, 또는 새로운 전문 용어 도입 시, 항상 먼저 pron_calibrate.mjs를 실제 실행하여 테스트하고, 위의 결론을 그대로 복사하지 마십시오. 음색마다 문자 읽는 방식이 다릅니다. 미회귀 테스트 시 발음 통과로 표시하지 마십시오. ASR 통과가 청감상 자연스러움을 의미하지는 않으며, 미청취 시 not_tested로 표시하십시오.

2. 테마 색상 및 그래디언트 결정

python3 scripts/theme_resolve.py --svg brand/logo.svg --out qa/theme-resolution.json
python3 scripts/theme_resolve.py --hex '#F93920'

design.theme.resolution_order에 따름: 사용자 지정 → 브랜드 SVG → 공식 CSS 변수 → 문서 장식 색상 → 폴백. 획득한 원시 색상을 먼저 OKLCH로 변환하고, 밝기를 0.45–0.62로, 채도를 0.12–0.22로 클램핑하며, 원래 색상을 유지합니다. sRGB 범위를 벗어나면 채도를 낮추어 매핑하고, 채널별 자르기를 허용하지 않습니다. 자르기는 색상을 변경하여 정규화를 무효화합니다.

그래디언트 3중 정지 색상은 색상환을 따라 같은 방향으로 이동하며, 마젠타 앵커 포인트(H=350°)를 향하고, 스팬은 55°–86°로 클램핑되며, secondary는 40% 지점에 있습니다. 양방향 이동은 그래디언트가 중간에 방향을 바꾸어 버그처럼 보이게 합니다. 참조 영상의 자체 주 색상을 입력하면 자체의 #376CFF → #8E33F2 → #E3429B를 재현할 수 있습니다.

두 개의 경사: 제목은 채도가 높은 경사를 사용하고, ≥96px의 큰 숫자는 더 밝은 단계(L +0.13, C −0.06)를 사용합니다. 큰 숫자는 면적이 넓어 채도가 높으면 제목을 압도할 수 있습니다.

대비 등급: 본문 먹(잉크) 색상 4.5, 브랜드 색상이 담당하는 큰 글자 3.0, ≥96px 주요 숫자 2.3(참조 영상 자체 실제 측정 2.37–2.86, 더 엄격하면 전체 그라데이션이 탁해짐).

빨간색, 녹색, 주황색은 의미론적 색상이며 유도에 참여하지 않습니다. 오류 빨간색을 일반 컨테이너 테두리나 장식으로 사용하는 것을 금지합니다.

3. 각 장에 대한 시각적 프로토타입 및 설명 방식 선택

시각적 프로토타입은 scene_language.archetypes의 여덟 가지 중에서 선택합니다: 의존성 그래프, 코드 더하기 관계, 요청-응답, 먼저 발견 후 요청, 전후 지표, 역량 매트릭스, 상태 머신, 계층형 아키텍처. 인접한 두 장은 반복될 수 없습니다.

설명 방식(explanation_mode)은 explanation_modes.vocabulary에서 선택하여 이 페이지가 움직일지, 어떻게 움직일지 결정합니다. 먼저 정보 유형을 확인한 다음 선택 테이블을 참조합니다(아래 "추상 정보를 설명하는 방법" 섹션 참조).

정보 단위는 각 장마다 3–5개의 짧은 레이블을 작성합니다. 이는 밀도 하한선의 기준이자 "한 화면에 너무 많은 내용"의 상한선입니다.

세 항목 모두 compose_spec.py가 검증합니다.

레이아웃: 가득 찼는지, 흩어져 있는지

제목은 항상 "서문, 결론"의 두 부분으로 구성

앞 부분은 먹(잉크) 색상, 뒷 부분은 전체에 그래디언트를 적용합니다. 구분은 구두점에만 위치해야 하며, 결론 부분은 35%–70%를 차지합니다.

간결하고, 선형적이며, ｜각 단계가 개별적으로 읽혀도 성립
한 번 선언하고,  ｜실행 시 검사와 설명서가 자동 준비
동일 기계 실제 측정,｜더 많이, 더 빠르게, 더 적게 실행

content.yaml에서는 headline_lead + headline_emphasis로 작성하며, compose_spec.py가 비율과 구분을 검증합니다. 이는 title(장 이름)과 다른 것임에 유의하십시오. 장 이름은 장 페이지와 탐색에 사용되고, headline은 본문 페이지의 큰 제목입니다.

그래디언트 예산: 페이지당 최대 1개의 제목 + 1개의 주요 숫자 + 2개의 키워드. 초과하면 더 이상 강조 신호가 아닙니다. 그래디언트는 <32px 글자(실제 측정 시 띠 모양 단층 발생)에 사용하는 것이 금지되며, 테두리, 그림자, 광택, 또는 움직이는 효과를 추가하는 것도 금지됩니다.

슬롯을 먼저 채우고, 핵심 내용은 나중에 제공

장면의 첫 번째 프레임에서 모든 슬롯을 그립니다. 컨테이너 테두리, 슬롯 제목(chip + 제목 + 구분선), 콘텐츠 스켈레톤. 이후에는 내용과 투명도만 변경하고, 경계 상자는 변경하지 않습니다. 핵심 내용(숫자, 코드, 레이블)은 내레이션이 해당 내용을 언급할 때까지 남겨둡니다.

이 한 가지 규칙이 세 가지 문제를 동시에 해결합니다. 레이아웃은 첫 번째 프레임부터 가득 차 있어 시청자가 "내용이 아직 생성되지 않은" 빈 페이지를 보지 않습니다. 채우는 과정에서 레이아웃이 재구성되어 흔들리지 않습니다. 첫눈에 이 페이지의 구조를 보고, 몇 가지를 설명할 것임을 알 수 있습니다.

스켈레톤에는 제목 또는 자리 표시자 구조가 있어야 하며, 순수한 빈 둥근 모서리 사각형이어서는 안 됩니다.

슬롯 헤더는 내용과 함께 기다리면 안 됩니다. 2026-11-05에 실제로 발견된 버그: feature 및 stage 유형의 슬롯이 제목을 내용의 공개 이벤트에 연결하여 페이지가 열릴 때 아래 두 카드가 순백색 직사각형이었습니다. 헤더는 컨테이너에 속하고, 내용은 비트(박자)에 속합니다.

이 규칙에는 픽셀 수준의 판정이 있습니다(R18의 실제 측정 절반): 장면 시작 프레임(전환이 완료된 순간)에서 본문 영역의 최대 빈 사각형 ≤ 0.26. 정지 프레임만 측정하면 알 수 없습니다. 정지 프레임에서는 페이지가 당연히 가득 차 보이지만, 처음 8초 동안의 반쯤 빈 상태는 보이지 않습니다.

아직 내용이 채워지지 않은 슬롯을 어둡게 하지 마십시오. 아래 "포커스" 섹션 참조: 빈 슬롯도 초점이 흐려진 수준으로 낮추면 페이지가 즉시 "아직 생성되지 않음"으로 읽히며, 이는 사전 할당된 슬롯이 해결하려는 문제와 정확히 일치합니다. 실제 측정 결과 빈 슬롯을 0.38에서 0.80으로 올린 후, 7개 장면의 시작 프레임 최대 빈 사각형이 0.29–0.62에서 0.058–0.199로 감소했습니다.

프레임이 없는 콘텐츠는 반드시 수습되어야 함

사용자 피드백: "카드가 없을 때 매우 분산됨". 규칙이 다음과 같이 강화되었습니다.

본문 영역의 각 정보 단위는 컨테이너에 속하거나 레이블이 있는 그룹에 속해야 합니다.
프레임이 없는 것은 세 가지 경우만 허용됩니다: 컨테이너 바로 아래에 위치한 요점 목록, 페이지 하단의 한 문장 결론, 상단의 kicker와 제목.
프레임이 없는 요점은 인접한 컨테이너와 왼쪽 경계 및 너비를 공유해야 하며, 최대 7열 너비, 최대 4개이며, 모양은 "원 번호 + 굵은 짧은 제목 + 콜론 + 본문"이 같은 행에서 시작되어야 합니다.
같은 페이지의 모든 프레임 없는 텍스트 블록은 하나의 왼쪽 경계만 가질 수 있습니다.
프레임 없는 콘텐츠가 본문 영역의 40%를 초과하면 컨테이너에 넣어야 합니다.

금지: 서로 가운데 정렬되고 여백이 있는 3~4개의 텍스트 단락; 빈 행을 사용하여 간격을 벌려 "채우는" 것; 한 페이지에 두 가지 이상의 왼쪽 경계가 있는 경우.

밀도 하한선(본문 영역 `[120, 280, 1680, 610]`)

지표	하한선	측정 방법
컨테이너 점유율 occupancy	≥ 0.55	장면 객체 경계 상자
수직 스팬	≥ 0.72	장면 객체 경계 상자
수평 스팬	≥ 0.86	장면 객체 경계 상자
최대 빈 사각형	≤ 0.14	장면 객체 경계 상자
최대 빈 띠	≤ 150 디자인 px	장면 객체 경계 상자
독립 정보 단위	≥ 3개	장면 객체 목록
안정 프레임 최대 빈 사각형	≤ 0.20	안정 프레임 에지 맵

마지막 항목은 픽셀 수준이며, 장 페이지/표지/결말은 면제됩니다. "비배경 픽셀 비율"을 사용하지 마십시오. 이 비주얼 시스템은 거의 흰색 배경에 흰색 카드를 사용하므로 카드 채우기가 최빈색이 되어 측정이 역전됩니다(실제 측정 결과 참조 영상 0.144, 심미적으로 나쁘다고 판단된 버전 0.419, 방향이 완전히 잘못됨). 에지 맵은 영향을 받지 않습니다.

내용이 충분하지 않으면 density.escalation에 따라 아래로 보충하며, 0단계는 먼저 슬롯이 사전 할당되지 않았거나 내용이 컨테이너에 들어가지 않았는지 확인합니다. 대부분의 "비어 있음"은 내용 부족이 아니라 이 때문입니다. 직접 비워두는 것을 금지합니다. 글꼴 크기를 키워 레이아웃을 채우는 것을 금지합니다. 입자, 후광, 기하학적 블록을 정보 단위로 가장하는 것을 금지합니다.

창 셸은 정보량에 따라 결정, 선호도에 따르지 않음

사용해야 하는 경우: 콘텐츠가 자연스럽게 특정 인터페이스(파일, 구성, 터미널, 편집기, 칸반, 보고서)에 속하는 경우; 정보 단위가 ≤3개로 희소하여 경계를 통해 수습해야 하는 경우; "파일 이름 + 내용"의 종속 관계를 표현해야 하는 경우.

사용해서는 안 되는 경우: 더 정확한 표현 형식이 있고 본문 영역을 채울 수 있는 경우; 이전 두 장면에서 연속으로 이미 사용된 경우; 내용이 추상적인 메커니즘이고 구체적인 인터페이스가 아닌 경우.

사용하는 경우 채워야 함: 내용 채우기 비율 ≥ 78%. 창 제목은 실제 파일 이름을 사용하고, "예시" 또는 "Demo"를 사용하지 않습니다. 전체 영상에서 창 장면 ≤ 50%, 동일한 구도의 세 장면이 연속되지 않아야 함.

관계도 및 순서도

최소 4개의 노드와 3개의 간선. 노드에는 제목과 한 줄 설명이 있어야 합니다. 각 유향 간선에는 동작 레이블과 화살표가 있어야 하며, 양 끝점은 실제 객체 ID의 경계점에 고정되어야 하며, 끝점이 빈 공간에 있으면 결함입니다. 설명 패널을 반드시 배치해야 하며, 본문 영역 너비의 30%–42%를 차지합니다. 의사 코드, 구성 조각, 상태 테이블, 메시지 샘플, 지표 막대, 단계 시퀀스 중에서 선택할 수 있습니다. 의사 코드는 5–12줄이며, 각 줄은 그래프의 노드 또는 간선 하나에 해당하며, 렌더링 시 동시에 강조 표시됩니다.

지표 페이지

주요 숫자 외에 최소 2개의 지원 콘텐츠: 전후 비교 그래프, 구성 분해, 테스트 조건 블록, 동일 메커니즘의 두 번째 지표, 해당 지표를 생성하는 실제 구성, 기준 정의. 차트는 기준선을 공유하고, 눈금과 값을 표시해야 합니다. 다른 단위(qps 및 ms)는 반드시 다른 차트 또는 다른 축을 사용해야 합니다. 순서: 먼저 원래 값과 테스트 조건을 표시 → 새 값으로 변경 → 개선 폭 확정 → 안정적으로 유지. 숫자는 등폭, 단위는 고정, 한 번만 강조합니다.

중국어 조판: 서양 방식은 그대로 사용할 수 없음

	규칙	이유
줄 높이	display 1.15, 제목 1.35, 본문 1.65	한자는 꽉 찬 격자 형태이며, 서양 소문자 사이의 자연스러운 간격이 없어 줄 간격이 충분하지 않으면 뭉개져 보입니다. 중국어는 서양어보다 전체적으로 약 0.2 더 높습니다.
자간	display(>60px) -0.02em, 제목 0, 본문 0	한자의 자간은 자연스럽게 균일합니다. 제목에 양의 자간을 추가하면 느슨해지고, display에 음의 자간을 더하면 획이 충돌합니다. 대문자 서양 레이블에만 0.08–0.15em이 필요합니다.
줄 길이	한 줄에 22–38자, 최적 28–32	한자는 밀도가 높아 동일한 너비에 서양어보다 더 많은 정보를 담으므로, 줄이 너무 길면 다음 줄 찾기가 어렵습니다.
폰트 스택	서양어가 먼저, 중국어가 나중	문자별 일치: 서양어 글꼴에는 CJK 코드 포인트가 없으므로 한자는 자연스럽게 중국어 글꼴로 전달됩니다. 반대로 작성하면 모든 서양어가 중국어 글꼴에 포함된 보기 흉한 서양어 문자로 표시됩니다.
강조	글자 굵기 변경 또는 배경색 추가	중국어에는 이탤릭체가 없으며, 브라우저/렌더러의 합성 이탤릭체는 한자를 왜곡시킵니다. 합성 굵게도 마찬가지로 모두 금지됩니다.
인용 부호	직각 인용 부호 「」『』	둥근 인용 부호는 중국어 글꼴에서 전각 점유, 서양어 모양으로 시각적으로 떠 보입니다.
숫자	서양어 글꼴 사용 + tabular-nums	그렇지 않으면 1과 8의 너비가 같지 않아 데이터 열이 좌우로 흔들립니다.

등폭 글꼴은 한자/일본어 형태를 반드시 확인해야 합니다. JetBrains Mono에는 CJK가 없어 코드 창의 중국어 주석이 네모 상자로 표시됩니다. 모노 글꼴 패밀리에는 명시적으로 중국어 폴백을 추가해야 합니다.

3미터 테스트

임의의 프레임을 정지했을 때, 화면에서 가장 큰 단어가 3미터 거리에서 읽을 수 있어야 합니다. 키 프레임을 휴대폰 화면 크기로 축소해도 여전히 읽을 수 있어야 합니다. 시청자는 비디오를 볼 때 각 프레임에 정지 이미지를 볼 때보다 더 적은 주의를 기울이므로, 글꼴 크기는 더 작게가 아니라 더 크게만 할 수 있습니다. 이 규칙은 밀도 하한선과 상호 하한선 역할을 합니다. 밀도 하한선은 텅 빈 것을 방지하고, 3미터 테스트는 "채우기 위해 글꼴 크기를 줄이는 것"을 방지합니다.

한 프레임에는 한 가지 주제만

사용자 피드백: 콘텐츠, 특수 효과, 내레이션 모두 정보를 명확하게 전달해야 하며, 모호하지 않아야 하고, 한 화면에 너무 많은 콘텐츠가 있으면 안 됩니다. 이 섹션의 모든 규칙은 motion_audit.py로 판정할 수 있으며, 미적 조언이 아닙니다.

정보 예산: 하한선 외에도 상한선이 있음

	값	설명
정보 단위 하한선	3	이 미만이면 페이지가 비어 있음
정보 단위 상한선	5	이를 초과하면 2초 정지 프레임 테스트를 통과할 수 없음
본문 영역 총 텍스트 양	≤ 120 카운트 단위	한자는 자수로, 영어는 단어 수로 계산
각 비트(박자)에 새로 들어오는 정보	1곳	그룹 stagger는 한 곳으로 계산

카운트는 가장 바깥쪽 컨테이너 또는 레이블이 있는 그룹을 기준으로 하며, 그룹 내 하위 항목은 별도로 계산하지 않습니다. 참조 영상의 01:32 페이지는 이 기준으로 3개의 단위(구성 코드 창 + 클라우드 장치 카드 그룹 + 프로세스 표시줄)이며, 카드가 5장이어도 여전히 1개로 계산됩니다.

초과하는 경우 글꼴 크기를 줄여 넣지 마십시오. 다음 순서로 시도하십시오: 두 개의 장면으로 분할 → 유사한 항목을 제목이 있는 그룹으로 병합 → 세부 정보를 설명 패널로 이동.

읽기 경로는 F자 형태이며, 측정 가능해야 함

시선 추적 연구에 따르면 콘텐츠 영역의 응시는 세 곳에 집중됩니다: 상단 가로 막대(kicker 및 제목), 두 번째 가로 막대(주 콘텐츠의 첫 번째 줄), 왼쪽 세로 막대(공유되는 왼쪽 경계). 이 영상에 적용하면:

시작점: 장면의 첫 번째로 공개되는 정보 단위의 무게 중심은 본문 영역의 왼쪽 상단에 위치해야 합니다(정규화된 x ≤ 0.50, y ≤ 0.45).
순서: 공개 시퀀스의 수직 무게 중심은 단조 감소하지 않으며, 최대 한 번의 위쪽 점프가 허용됩니다.
세로 막대: 프레임 없는 텍스트 블록은 하나의 왼쪽 경계를 공유합니다(R14). 컨테이너 왼쪽은 열 그리드에 맞춥니다(R13).
선행 정보: 제목, 슬롯 제목, 요점 제목의 처음 두 단어는 자체 정보를 포함해야 합니다. "~에 대해", "우리의", "더 나은", "어떻게"로 시작하는 제목은 compose_spec.py가 직접 오류를 보고합니다.

실제 측정(content_box 내, 12fps, 각 장면 전환 후 1.5초의 변화 무게 중심):

	시작점 x	시작점 y	아래로 펼쳐지는 장면 전환 비율
참조 영상	0.393 ± 0.121	0.336 ± 0.126	67%
이전 버전(심미적으로 나쁘다고 판단된 완성본)	0.660 ± 0.175	0.498 ± 0.152	48%

참조 영상은 왼쪽 상단에서 시작하여 아래로 펼쳐지는 반면, 해당 버전은 오른쪽 중앙에서 바깥쪽으로 펼쳐졌습니다. 이것이 "분산되어 보이는" 직접적인 원인 중 하나이며, 밀도와는 무관합니다.

화면과 내레이션은 동일한 내용을 전달해야 함

각 정보 단위는 해당하는 내레이션 문장을 명시해야 하며, 공개 시간은 [문장 시작 −0.4, 문장 끝 +0.8]초 사이에 있어야 합니다. 해당 문장을 작성할 수 없으면 이 단위는 내레이션에서 언급되지 않으므로 삭제하거나 추가로 설명해야 합니다.

화면의 텍스트는 결론 구문, 고유 명사, 숫자, 레이블이며, 내레이션을 문장 단위로 그대로 옮겨 적은 것이 아닙니다. 같은 내용을 동시에 듣고 읽으면 서로 방해가 됩니다. 자막은 별도 트랙이므로 텍스트 예산에 포함되지 않습니다.

내레이션도 한 문장에 한 가지 사실

한 문장에 한 가지 사실. 두 가지 사실은 두 문장으로 작성하고, "동시에", "그리고"로 연결하지 마십시오. 단일 문장은 ≤ 32개 카운트 단위.
각 장면의 첫 번째 문장은 결론이고, 그 후에 메커니즘과 증거를 제시합니다.
"그것", "이것"과 같은 대명사를 연속으로 사용하지 마십시오. 한 문장을 건너뛰면 이름을 다시 말하십시오.
용어가 처음 등장하면 해당 문장에서 설명하고, 다음 문장으로 미루지 마십시오.
숫자를 말할 때는 같은 문장 또는 바로 다음 문장에 측정 조건을 포함해야 합니다.
금지: 키워드 목록 낭독("더 빠름, 더 강함, 더 안정적"), 광고 톤의 병렬 구조, 한 문장에 세 개의 고유 명사, 화면에 이미 명확히 쓰여진 내용을 다시 읽는 것.

내레이션을 문장 단위로 CLAIMS.md에 복사하여 매핑합니다. 매핑되지 않는 문장은 삭제하거나 출처가 있는 결론으로 보완합니다.

2초 정지 프레임 테스트

장면의 홀드 프레임을 가져와 내레이션과 자막을 가리고, 해당 제품에 대해 잘 모르는 사람에게 이 페이지의 결론과 그 숫자를 말하도록 요청합니다. 말할 수 없으면 이 페이지가 명확하지 않은 것입니다. 장면별로 passed / failed / not_tested를 기록합니다. 수행하지 않으면 not_tested입니다.

시간 분배: 먼저 홀드 예산을 책정하고, 그 다음에 모션 효과를 배치

멀티 샷 영상의 길이는 균등하게 분배되지 않습니다. 네 부분의 프레임워크, 비율은 고정 지표입니다:

부분	비율	에너지	내용	고정 지표
오프닝	8–12%	낮음	브랜드 노출 + 전체 영상이 설명할 내용을 한 문장으로	로고 고정 후 hold ≥1초; 0번째 프레임이 완전한 표지여야 함
전기	10–16%	낮음-중간, 전체에서 가장 느림	첫 번째 장, 가장 높은 퀄리티의 부분	—
상승	52–64%	중간-높음과 낮음이 번갈아 나타남	하나의 능력에 하나의 장면	1–2개의 콘텐츠 장면 사이에 장 페이지를 삽입하여 에너지 낮춤
마무리	10–16%	전체 최고점	回顾 + 핵심 숫자 + 진입점	페이드 아웃하지 않고, 읽은 후 마지막 프레임까지 유지

순서: ① 능력 목록을 작성하여 장면 수를 셈 → ② 침해할 수 없는 정지 시간을 먼저 할당(로고 hold, 읽기 체류, 장 페이지 완전 유지 1.1초, 끝 유지 2초) → ③ 남은 시간을 모션 효과에 할당 → ④ 각 연결부에 전환을 선택하고, 전환 시간은 인접한 두 장면의 예산에서 각각 절반씩 차감하며, 추가 시간을 더하지 않음.

연속으로 두 장면의 에너지가 높아서는 안 됩니다. 장 페이지는 에너지를 낮추기 위한 "호흡 카드"입니다. 저밀도, 큰 여백, 2–6자이며, 또 다른 정보 장면으로 만들어서는 안 됩니다. 그렇게 하면 삽입하지 않은 것과 같습니다.

템플릿 장식 블랙리스트

이것들은 "보기 흉해서"가 아니라 "템플릿을 사용한 것이 한눈에 보여서"입니다. 발견 즉시 삭제하십시오:

각 제목 위에 또 다른 줄의 대문자 영어 레이블 추가 · 중간 점으로 연결된 문자열 "A · B · C" · 버튼이나 레이블 끝의 화살표 장식 · 제목에서 단어 하나만 색상 변경하기 · 내용이 시퀀스가 아닌데 01/02/03 번호 사용하기 · 메커니즘과 관련 없는 이모지 아이콘 · 왼쪽 색상 막대가 있는 둥근 모서리 카드 · 발광 입자, 데이터 스트림, 홀로그램 HUD, 네온 · 어두운 배경에 네온 후광을 추가하여 기술 감성 가장하기.

판단 기준은 "콘텐츠에서 자연스럽게 나온 것인가"이지, "템플릿처럼 보이는가"가 아닙니다. 번호는 실제로 시퀀스일 때 합법적입니다(장, 추론 단계). 그라데이션은 브랜드 색상 유도에서 비롯될 때 합법적입니다.

연결부: 전체 영상에 절대적인 컷 없음

사용자 피드백(2026-11-05): "각 챕터와 다음 챕터 간의 전환이 매우 자연스러워야 하며, 직접 표시되어 매우 딱딱해 보이면 안 됩니다." 공인된 훌륭한 출시 영상은全程 절대적인 컷이 없습니다. "컷" 효과를 원한다면, 디자인된 컷을 사용하십시오.

모든 장면 연결부는 전환을 선언해야 하며, 시간은 인접한 두 장면의 각 예산에서 절반씩 차감합니다. 전환은 영상 길이에 더해지는 것이 아니라 두 장면에서 빌려오는 것입니다. 윈도우는 [경계 − 시간/2, 경계 + 시간/2]이며, 이 시간 동안 두 장면이 동시에 화면에 표시됩니다.

인접한 두 장면	사용할 전환	시간	방법
표지 → 장 페이지	교차 페이드	0.62초	표지가 페이드 아웃되면서 점차 흐려지고, 장 번호가 동시에 흐려진 상태에서 해상됨
본문 → 장 페이지	교차 페이드	0.58초	이전 페이지가 페이드 아웃되는 동시에 번호가 흐려지며 들어오고, 두 가지가 동일한 윈도우에서 발생
장 페이지 → 본문	프리즘 스캔 라이트	0.92초	번호가 확대되어 흐려짐 → 무지개 빛 띠가 비스듬히 스캔 → 다음 페이지가 빛 띠 뒤에 이미 형성되었으며, 핵심 내용은 아직 표시되지 않음
본문 → 끝	교차 페이드	0.62초	동일
본문 → 본문(동일 장 내 장면 전환)	초점 흐림 릴레이	0.50초	흐림만 변경하고, 수평 이동은 하지 않음

프리즘 스캔 라이트: 전체 화면을 surface_tint의 얇은 베일(최고점 0.62)로 덮고, 너비 1420의 빛 띠가 17° 기울어져 스캔하며, 정지 색상은 주 색상 0.34 → 보조 강조 색상 0.30 → accent 0.26입니다. 흰색 플래시, 전체 화면 지우기, 페이지 넘기기, 회전은 금지됩니다.

연결부는 내레이션 간격에 맞춥니다(move on pause). 미리만 가능하고, 지연은 안 되며, 상한은 0.8초입니다. 시청자가 청각적 공백에서 시선을 이동하는 비용이 가장 낮습니다.

판정(R27): 연결부 윈도우를 12fps로 프레임을 캡처하여 전체 화면의 프레임별 변화량을 계산합니다. 단일 프레임의 변화량은 전체 윈도우 변화량의 ≤ 0.55를 차지해야 합니다. 절대적인 컷은 변화의 90% 이상을 한 프레임에 집중시킵니다. 실제 측정 결과 이 버전의 7개 연결부는 0.155–0.35 범위에 있습니다.

표지는 반드시 0번째 프레임이어야 합니다. 플레이어는 t=0을 포스터로 사용합니다. 0번째 프레임이 비어 있으면 표지가 없는 것과 같습니다. 따라서 표지는 요소 등장으로 움직임을 만들지 않습니다. 요소는 처음부터 모두 있으며, 움직임은 경계 상자를 변경하지 않는 세 가지 작업에서 비롯됩니다: 정지된 동심원 고리, 두 번의 스캔 라이트, 내레이션이 방향을 언급할 때 해당 레이블을 한 번씩 깜빡임. 판정은 0번째 프레임의 본문 영역 가장자리 적용 범위가 표지 정지 프레임의 0.90배 이상이어야 합니다. 장식도 0번째 프레임에 준비되어 있어야 합니다. 실제 측정 결과 원형 고리를 0→1로 점진적으로 표시하도록 만든 경우 이 비율은 0.673에 불과했습니다.

포커스: 말하는 대상이 강조되지만, 말했던 내용은 여전히 읽을 수 있어야 함

사용자 피드백(2차): "한 가지 내용을 말할 때 다른 내용은 회색으로 표시되어 현재 말하는 내용을 강조합니다." 사용자 피드백(3차): "말하자마자 바로 회색으로 바뀌어서 전혀 보지 못했습니다." "너무 흐리게 하지 말고, 어둡게는 하지만 내용을 볼 수 있어야 합니다." "말한 내용과 다음에 말할 내용이 연관되어 있으면 잠시 어둡게 하지 마십시오."

4단계 상태, 선명도는 낮추지 않고 먹(잉크) 양만 낮춤

상태	먹(잉크) 양	카드	시기
active	1.0	그림자 있음, 주 색상 테두리	내레이션이 해당 내용을 말하는 중. "떠오름"으로 인식되며, 다른 내용이 흐려져서가 아님
read	0.70	그림자 없음, 일반 테두리	이미 말함. 먹(잉크) 색상이 시각적으로 약 `#5A6070`로 낮아지며, 대비는 여전히 6:1, 3미터 거리에서 읽을 수 있음
waiting	0.88	일반	아직 차례가 아님. 약간만 낮추며, 페이지는 가득 차 있어야 함
settled	1.0	일반	내레이션 완료, 전체 페이지가 불투명으로 돌아감

흐림을 사용하지 마십시오. 이 규칙은 huashu-design의 "초점 상실 세 가지에는 반드시 blur가 포함되어야 한다"는 것과 상충됩니다. 여기서는 정보 영상의 요구에 따라 해결합니다. 흐림의 목적은 요소가 주의력을 경쟁하지 않도록 하는 것이지만, 정보 영상의 시청자는 여전히 그 내용을 다시 읽어야 합니다. 흐림은 두 곳에만 유지됩니다. 장면 간 전환 및 장 페이지 번호의 등장과 퇴장.

언제 어두워지기 시작하는가

          문장 시작          문장 끝      +1.0초        +0.8초
             |--------------|------------|------------|
   active    ============================>
   어두워짐                                  [===그라데이션===]  read

단위는 자신의 해당 내레이션 문장이 끝나기 전에 어두워지기 시작해서는 안 됩니다(R30의 선언 절반).
말한 후 1.0초를 더 주어 시청자가 읽을 수 있게 하고, 0.8초에 걸쳐 천천히 낮춥니다.
이전 방식은 "다음 문장이 시작되면 즉시 초점을 전환"하는 것이었습니다. 시청자가 이전 블록을 아직 읽고 있는데 화면이 이미 그것을 빼앗아갔습니다.

서로 관련된 두 블록은 함께 밝아지고 함께 어두워짐

구성과 적용 범위, 숫자와 측정 조건. 이러한 쌍을 이루는 내용은 동일한 focus_group을 선언합니다. 그룹 내 어느 하나라도 말하는 중이면 전체 그룹이 active를 유지합니다. 그룹 내 마지막 항목이 말을 마친 후 + 1.0초 후에 전체 그룹이 함께 어두워집니다.

판정(R28)

특정 단위가 초점을 잃는 순간의 한 프레임과 정지 프레임의 동일한 프레임을 가져와 동일한 단위 경계 상자 내의 평균 그래디언트 크기를 비교합니다. 초점 상실 상태 ≤ 정지 상태의 0.85.

임계값 처리된 에지 수 대신 평균 그래디언트 사용: 대비만 낮추고 흐림을 추가하지 않을 때 임계값은 모두 통과하거나 모두 통과하지 못하므로 측정이 처리와 분리됩니다. 평균 그래디언트는 대비에 따라 선형적으로 변하며, 먹(잉크) 양 0.70은 약 0.70으로 측정됩니다.

공개: 지원 콘텐츠는 처음부터 있고, 핵심 항목만 내레이션을 기다림

사용자 피드백(3차): "중간 상자에 내용이 없고, 아래 상자에 내용은 없지만 스타일이 있어서 첫눈에 보기에 매우 이상했습니다." "사실 중요하지 않은 내용을 먼저 표시할 수 있습니다. 중요한 내용은 설명할 때 타자기로 표시합니다." "보통은 타자기로 내용을 출력하기만 하면 됩니다. 이미 출력된 후에 해당 줄이 나중에 다시 언급되면 배경을 강조 표시합니다."

이 규칙은 2차의 "핵심 내용은 내레이션이 언급할 때까지 남겨둠"을 좁히는 것이지, 뒤집는 것이 아닙니다. 뒤로 미루는 것은 각 단위의 핵심 항목 하나뿐이며, 전체 카드가 아닙니다.

처음부터 그려야 하는 것

카드, 칩, 제목, 구분선, 행 레이블, 보조 행, 구조. 단위당 하나의 핵심 항목만 내레이션을 기다립니다. 그 숫자, 그 코드, 그 레이블들.

한 줄에는 하나의 모션 효과만 사용

시기	사용할 효과	중복 금지
첫 등장	타자기, 왼쪽에서 오른쪽으로 한 글자씩, 0.4–1.0초	스캔 라이트, 배경색 띠, 왼쪽 색상 막대 미포함
이후 재언급	배경 강조 띠 `#FFF4D6` + 3px 왼쪽 색상 막대, 0.42초	—

강조는 "재언급"의 언어입니다. 첫 등장에 강조를 사용하면 이 언어가 사라져 시청자가 어떤 것이 새로운 것인지 구분할 수 없습니다.

이전 버전은 각 줄에 스캔 라이트를 하나씩 할당하여 "변화가 있는 프레임 비율 ≥ 0.45"를 맞추려고 했습니다. 사용자의 원래 말은 "안에 있는 텍스트에 해당하는 모션이 너무 많습니다"였습니다. 모션 양을 맞추기 위해 장식적인 모션 효과를 쌓았지만, 이제는 직접 통과할 수 없습니다.

스켈레톤 화면은 언제 사용할 수 있는가

내용을 실제로 나중에 설명해야 하고 스켈레톤 자체가 디자인된 경우에만 사용할 수 있지만, 다음 조건을 충족해야 합니다. 제목과 구조가 있어야 함(순수한 빈 둥근 모서리 사각형이 아님). 자리 표시자 막대의 너비가 같지 않아야 함(실제 콘텐츠의 윤곽선처럼 보임). 스켈레톤은 카드 높이의 60%를 초과할 수 없음. 각 카드의 스켈레톤은 동일하게 생겨서는 안 됨.

내레이션과 화면은 동일한 내용을 전달해야 합니다. 이것이底线입니다.

사용자 피드백(3차): "반드시 반드시 내레이션과 화면 내용 및 모션이 일치해야 합니다!!! 이것이底线입니다."

두 번째 버전의 실패는 선언 자체가 잘못되었기 때문입니다. R22는 "공개 시간이 선언된 문장의 시간 윈도우 내에 있는지"만 확인하고, 이 문장이 이 단위를 설명하고 있는지는 전혀 확인하지 않았습니다. 따라서 2.8배 카드가 "다른 소요 시간이 12.6초에서 4.0초로 감소했습니다"에 연결되었습니다. 해당 문장은 다른 카드의 두 번째 줄을 설명하는 것이었습니다. 시간 윈도우는 당연히 일치하고, 게이트는 당연히 모두 녹색이었습니다.

R29: 일대일 대응 및 텍스트 일치

각 정보 단위는 정확히 한 문장의 내레이션을 선언합니다.
두 단위가 동일한 문장을 공유할 수 없습니다. 동일한 stagger 그룹에 속하고 동일한 비트(박자)에 함께 진입하는 경우는 예외입니다.
장면의 모든 내레이션 문장은 반드시 어떤 단위에 의해 선언되어야 하며, 고아 문장이 허용되지 않습니다.
이 문장의 텍스트에는 반드시 해당 단위의 키워드가 포함되어야 합니다: 카드 제목, 행 레이블, 숫자, 레이블 텍스트, 파일 이름 중 하나. 따라서 content.yaml의 각 정보 단위에는 keywords를 작성해야 합니다.

R30: 화면은 내레이션을 따라야 함

선언 레이어: dim_t >= 해당 단위 문장 종료 시간 + 1.0초.
실제 측정 레이어: 각 내레이션 문장의 재생 중에는 해당 단위 상자 내에 가시적인 변화가 있어야 합니다.

시작하는 방법: `content.example.yaml` 복사, 문서 이해, 그리고 `compose_spec.py` 실행

# 환경 설정
SKILL=~/.agents/skills/viva-video
cp $SKILL/templates/content.example.yaml ./content.yaml

# 1단계: 문서를 완전히 이해
# UNDERSTANDING.md, CLAIMS.md, CONCEPT_MAP.md 수동으로 채우기
# 문서를 다시 읽고 그 후에 채우되, 동시에 채우지 마십시오

# 2단계: 콘텐츠 사양 편집
# $EDITOR content.yaml

# 3단계: 비디오 사양 구성 및 검증
python3 $SKILL/scripts/compose_spec.py ./content.yaml -o ./video-spec.resolved.yaml
python3 $SKILL/scripts/validate_spec.py ./video-spec.resolved.yaml --self-test

# 4단계: 발음 교정
node $SKILL/scripts/pron_calibrate.mjs --terms terms.json

# 5단계: 음성 합성(사용자 제공 공급자 또는 agent의 자체 기능 사용)
# providers.json이 구성되어 있으면
node $SKILL/scripts/tts.mjs --spec video-spec.resolved.yaml --voice voice/

# 6단계: 최종 검증
node $SKILL/scripts/asr_check.mjs --spec video-spec.resolved.yaml --voice voice/

구성 가능한 --theme 플래그로 다른 시각적 스타일을 실험해 보십시오. theme/README.md를 읽고 새 테마 패키지를 만드는 방법을 알아보십시오.

결론: 문서를 이해하는 것이 가장 중요합니다

이 스킬의 가장 중요한 작업은 영상의 모든 문장이 문서로 거슬러 올라가고, 모든 화면이 그 문장을 지원하는지 확인하는 것입니다. 기술(레이아웃, 타이포그래피, 모션, 색상)은 이해를 전달하는 도구일 뿐이며, 그 자체가 목적이 아닙니다.

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

문서