웹 비디오 프레젠테이션 (Web Video Presentation)
한 편의 글(文章)이나 구술 대본(口播稿)을 단계별로 녹화 가능한 "비디오로 위장한 웹페이지"로 만듭니다. 구술 오디오 합성도 선택 가능합니다. 결과물 = Vite + React + TS 프로젝트 + 챕터별로 분할된 오디오 파일.
적용 시나리오
- "구술 대본이나 한 편의 글이 있는데, 비디오로 만들어 주세요" — 구술(口播) 중심 콘텐츠
- "다이내믹 PPT"를 만들고 싶을 때
- 16:9 가로 녹화, 큰 글자, 여백, 모든 화면에 모션 효과
- 교육 / 제품 시연 / 키노트에 영화 같은 감성을 더하고 싶을 때
- Bilibili / YouTube / TikTok 영상 콘텐츠
본 스킬은 방법론과 협업 프로세스를 핵심으로 합니다. 스캐폴딩 템플릿은 토큰과 원시 개념을 제공하지만, 모든 미적 결정 (색상, 글꼴, 모션 분위기) 은 여러분의 주제에 맞게 재설계되어야 합니다 — 그대로 따라 하지 마세요.
워크플로우 개요
Phase 1 콘텐츠 작성
1.1 사용자 입력 식별
1.2 script.md + outline.md 한 번에 생성
(구술 대본 + 개발 계획)
▼
[Checkpoint Plan] ← 반드시 멈춤. 5가지 항목을 한 번에 정렬:
대본 / 아웃라인 / 테마 / 소재 / 개발 모드
▼
Phase 2 웹 개발
2.1 스캐폴딩 (선택한 테마 적용)
2.2 1장 = 메인 스레드 + 완전 버전 (강제 앵커)
▼
[하드 노드] 사용자 1장 검수 ← 건너뛸 수 없음
▼
2.3 2~N장 (선택한 모드에 따라: A 장별 확인 / B 순차 개발 / C 병렬 개발)
▼
[Checkpoint Audio] ← 반드시 멈춤. 오디오 합성 여부 결정
▼
Phase 3 오디오 합성 (선택 사항)
▼
Phase 4 녹화 + 후반 작업
작업 디렉토리 규칙 (에이전트는 사용자의 현재 디렉토리에서 생성/편집):
my-video/
├── article.md # 사용자가 원문을 제공한 경우 반드시 존재 — 삭제 금지! 개발 단계 화면 정보 소스
├── script.md # 반드시 존재: 원문 언어를 유지한 플랫폼화된 구술 대본 (비트 결정)
├── outline.md # 반드시 존재: 개발 계획 (챕터 분할 + 각 단계 내용 + 정보 풀)
└── presentation/ # 스캐폴딩이 생성한 Vite + React + TS 프로젝트
├── src/chapters/<NN>-<id>/
│ ├── <Chapter>.tsx # 시각적 구현
│ ├── <Chapter>.css
│ └── narrations.ts # ★ 단계(step) 수와 구술 텍스트의 유일한 진실 공급원
├── scripts/
│ ├── extract-narrations.ts # 모든 narrations.ts 스캔 → audio-segments.json 생성
│ ├── synthesize-audio.sh # 공급자에 구애받지 않는 러너 (세그먼트 반복)
│ └── tts-providers/ # 공급자별 .sh 파일 (내장 2개)
│ ├── README.md # 3함수 계약 + 5개 기성 코드 조각 (11labs / edge-tts / say / azure / gcloud)
│ ├── minimax.sh # 기본 공급자, mmx-cli 사용
│ └── openai.sh # 내장 OpenAI TTS (curl + OPENAI_API_KEY)
├── audio-segments.json # extract 결과물 (합성 전 검토용)
└── public/audio/<id>/<N>.mp3 # 선택 사항: 합성된 오디오 파일
중요:
narrations.ts는 단계(step) 수와 오디오 합성의 유일한 진실 공급원입니다. 챕터.tsx파일에if (step === N)이 등장하는 최대 N + 1 값은 반드시narrations.length와 일치해야 합니다. 이는 5군데 (script / outline / 챕터 코드 / chapters.ts / 오디오 파일)가 서로 엇나가는 것을 방지합니다.
하드 자체 점검 프로토콜 (스킬 전반에 걸쳐 적용)
아래 세 가지 산출물은 각각 완료 후 반드시 자체 점검 → 수정 → 재보고/진행 순서를 따라야 합니다:
| 산출물 | 자체 점검 목록 출처 |
|---|---|
script.md | SCRIPT-STYLE.md 3단계 자체 점검 (형식 / 풍격 / 소리 내어 읽기) |
outline.md | OUTLINE-FORMAT.md 자체 점검 |
| 단일 챕터 구현 완료 | CHAPTER-CRAFT.md 완료 자체 점검 |
실행 방식 (역량 순으로, 더 격리된 방식을 우선 사용):
- Agent Teams (최적): 독립적인 리뷰어 에이전트를 열어 "산출물 파일 경로 + 해당 체크리스트 + 핵심 컨텍스트"를 제공하고, 항목별로 확인하여 엄격하게 결론을 보고하도록 합니다 (통과 항목 / 실패 항목 + 증거 + 재작성 제안).
- subAgent (차선): Teams 기능은 없지만 subagent를 열 수 있다면 동일한 프로세스로 진행합니다.
- 자체 점검 (최후): 현재 에이전트가 위의 어떤 기능도 없다면, 스스로 엄격하게 항목별로 확인합니다 — 대충 훑어보고 넘어가는 것은 허용되지 않습니다.
불변의 법칙: 결론을 받은 후 먼저 실패(fail) 항목을 수정한 다음, 사용자에게 "완료 + 자체 점검 결론 + 수정한 내용"을 보고합니다. 원시 결론을 그대로 보고하면서 수정하지 않는 것은 위반입니다.
단계별 파일 읽기 가이드
각 단계마다 읽어야 할 파일이 다릅니다. 긴 세션에서 에이전트는 원칙을 잊기 쉬우며, 특히 Phase 2.4의 "단일 챕터 구현"은 N번 반복되므로 — 매번 핵심 제약 조건을 다시 참조해야 합니다.
| 단계 | 필독 (매번 읽어야 함) | 한 번에 읽거나 / 필요 시 참조 |
|---|---|---|
| Phase 1.1-1.2 콘텐츠 작성 | references/SCRIPT-STYLE.md + references/OUTLINE-FORMAT.md + article.md (사용자 원문, 있는 경우) | —— |
| Checkpoint Plan 테마 선택 | —— | themes/*/theme.json (동적으로 모두 읽어서, 목록 + bestFor 추천 + descriptionZh 표시); references/THEMES.md (사용자가 테마 시스템을 알고 싶어할 때) |
| Phase 2.1 스캐폴딩 | —— | SKILL.md 이 섹션을 한 번 읽기 |
| Phase 2.4 단일 챕터 구현 (×N회, 2.2 / 2.3에서 호출) | references/CHAPTER-CRAFT.md 단일 진입점 — Part 0 10가지 원칙 / Part 1 시작 5문 / Part 2 관계→동작 결정 트리 / Part 3 시각적 도구 상자 / Part 4 시간 참고 / Part 5 반 AI 냄새 안티 패턴 / Part 6 코드 하드 규칙 (narrations.ts 강제 제약 포함) / Part 7 완료 자체 점검 / Part 8 피드백 빠른 참조 + 현재 테마의 themes/<id>/theme.json + 현재 챕터의 outline.md 문단 + article.md의 해당 챕터 문단 + 소재 목록 | references/EXAMPLES/ (구조 예시, 복사할 템플릿 아님); references/THEMES.md 전체 토큰 계약 |
| Phase 3 오디오 합성 | references/AUDIO.md (narrations.ts → segments.json → 임의 공급자 흐름, 내장 minimax + openai 포함) | templates/scripts/tts-providers/README.md (공급자 교체 / 자체 TTS 사용 시) |
| Phase 4 녹화 + 후반 작업 | references/RECORDING.md (?auto=1 자동 녹화 포함) | —— |
| 테마 선택 / 생성 / 수정 | —— | references/THEMES.md |
챕터 작성 시에는
CHAPTER-CRAFT.md하나만 읽으세요. 10가지 원칙 / 시작 셀프 프롬프팅 / 결정 트리 / 반 AI 냄새 안티 패턴 / 완료 자체 점검이 모두 이 단일 진입점에 통합되어 있습니다.EXAMPLES/는 필독 사항이 아닙니다 — 먼저 내용에 따라 자유롭게 디자인하고, 막혔을 때만 참고하세요 (앵커 형식을 참고하되, 그대로 베끼지 마세요).
Phase 1 — 콘텐츠 작성 (한 번에 생성)
1.1 사용자 입력 식별
| 사용자가 제공한 것 | 수행할 작업 |
|---|---|
| 원문 글 (문어체 / 공식 계정 / 논문 / 블로그) | script.md + outline.md 한 번에 생성 (1.2), Checkpoint Plan 통과 |
| 직접 작성한 구술 대본 / 비디오 스크립트 | script.md로 저장, outline.md 한 번에 생성 (1.2 간소화 버전), Checkpoint Plan 통과 |
| 아무것도 없이 "X 주제로 비디오 좀 만들어 줘"라고만 함 | 역질문: 먼저 자료나 개요를 제공해 주세요. 스킬이 사용자를 대신해 콘텐츠를 구상하지 않습니다 |
1.2 script.md + outline.md 한 번에 생성
두 산출물을 한 번의 사고 과정에서 완료:
script.md생성:references/SCRIPT-STYLE.md의 규칙에 따라 article을 원문 언어를 유지한 플랫폼화된 구술 대본으로 변환합니다.article.md는 삭제하지 않고 유지합니다 — 이는 아웃라인의 정보 풀과 챕터 구현 시 세부 정보의 소스 역할을 합니다 (이중 소스 원칙).outline.md생성:references/OUTLINE-FORMAT.md규칙에 따라 챕터를 분할하고 단계(step)를 나누며, 각 챕터의 첫 문단에 정보 풀을 추출합니다.
아웃라인의 경계 (핵심):
| 아웃라인에 반드시 써야 할 것 | 아웃라인에 쓰지 말아야 할 것 |
|---|---|
| 챕터 분할 / 각 챕터 단계(step) 수 / 예상 시간 | 구체적인 애니메이션 유형 (blur clear / wipe / 스프링) |
| 각 단계의 화면 내용 (히어로 / 데이터 / 슬로건 / 목록 항목) | CSS 구현 수단 (filter / SVG / clip-path) |
| 챕터 수준 정보 풀: article에서 추출한 숫자 / 인용문 / 사례 / 태그 | 시간 값 (~2.5s / 80~120ms 등은 쓰지 않음) |
| 단계 간 관계명 접두사 ("대조 대비" / "점진적 목록" / "명문" 등 선택적 힌트) | 지속적인 미세 움직임 / 엇박자 양 등 미시적 리듬 |
아웃라인에 애니메이션을 쓰지 않는 이유: 애니메이션을 고정하면 챕터 에이전트가 번역기로 퇴화합니다. 빈칸을 남겨두면 챕터 에이전트가 각 단계 작업 시작 시
CHAPTER-CRAFT.md의 "콘텐츠 기반 결정 트리"에 따라 자유롭게 디자인하여 진정한 비디오 감각을 얻을 수 있습니다. 자세한 내용은CHAPTER-CRAFT.mdPart 0 원칙 7을 참조하세요.
저장 후 반드시 자체 점검을 먼저 수행한 후 Checkpoint Plan으로 진행: 위의 '하드 자체 점검 프로토콜'에 따라 script.md / outline.md 각각에 대해 실행하고 (Agent Teams → subAgent → 자체 점검 우선 순위), 결론에 따라 수정을 완료한 후 Checkpoint Plan으로 진행합니다.
Checkpoint Plan — 5가지 항목 한 번에 정렬 (하드 노드)
script.md + outline.md 작성이 완료되면 반드시 멈춰야 합니다. 사용자는 이 하나의 노드에서 동시에 5가지 항목을 확인합니다.
에이전트가 이때 수행해야 할 준비 작업
- 모든
themes/*/theme.json을 읽어nameZh/descriptionZh/bestFor/mood를 가져옵니다 — 목록을 하드코딩하지 마세요 script.md의 콘텐츠 유형 / 키워드 / 어조에 따라 능동적으로 테마 중에서 2~3개의 가장 적합한 추천을 골라냅니다 (bestFor필드와 매칭)outline.md末尾의 "소재 목록" 부분을 훑어봅니다
요약 템플릿 (뼈대, 에이전트가 상황에 따라 채움)
콘텐츠 계획 작성 완료, 산출 파일:
📄 article.md {사용자가 원문을 제공한 경우 유지}
📄 script.md {X} 자 / 약 {T} 분
📄 outline.md {N} 장 / {M} 단계 + 각 장 정보 풀 + 말미 소재 목록
챕터 개요:
1. <id> <챕터 제목> <S> 단계 약 <T>초
2. ...
다음으로 5가지 항목을 한 번에 정렬합니다:
1. 대본 (script.md) 수정 필요?
직접 파일을 편집하거나, 구두로 수정 방향을 알려주세요.
2. 개발 계획 (outline.md) 수정 필요? 중점 확인:
- 챕터 분할 / 단계(step) 수 / 예상 시간이 합리적인가 (합리적 판단: 각 장 30~60초)
- 각 단계의 화면 내용이 명확한가
- 각 장 첫 문단의 '정보 풀'에 화면을 구성할 수 있는 충분한 article 세부 정보가 있는가
- 말미 소재 목록이 완전한가
3. 어떤 테마를 선택할까요? 제 추천:
★ <추천 1: nameZh (id)> — <bestFor 매칭 이유>; <descriptionZh 요약>
★ <추천 2 / 추천 3>
기타 선택 가능: <나머지 테마, nameZh + 한 줄 설명>
제가 새 테마를 만들어 드릴 수도 있습니다 (자세한 내용은 references/THEMES.md 참조).
4. 진짜 소재는 어떻게 준비할까요? 이 비디오에 필요할 것으로 보이는 이미지: <대략적인 목록>
a) 제가 <기존 소재 경로>에서 골라드립니다 b) 직접 제공 c) 전부 플레이스홀더
5. 개발 모드는 어떤 걸로 할까요?
**1장은 어떤 모드든 메인 스레드로 완료 + 사용자 검수가 필요합니다** (강제 앵커).
2장 이후부터 차이가 있습니다:
A) 기본 · 장별 확인 (추천)
각 장 완료 시마다 중단 후 검수 → 위험 통제 가능 / 리듬이 가장 안정적
B) 1장 후 순차 개발 (병렬 아님)
2~N장을 메인 스레드에서 순서대로 완료 후 통합 검수 → 속도 중간 / 에이전트가 병렬을 지원하지 않는 환경에 적합
C) 1장 후 병렬 개발 (subagent)
2~N장을 subagent로 병렬 처리 → 가장 빠름 / 사용자가 병렬 수 제어 (한 번에 몇 장)
⚠️ 각 장 스타일에 차이가 있을 수 있습니다 (예상된 현상이며, 테마 제한으로 기본은 지켜짐)
피드백 수신 후:
- 대본 / 아웃라인 수정 필요: 직접 파일 편집, 편집 완료 후 핑 (또는 구두로 설명하면 에이전트가 수정)
- 테마는 반드시 명확해야 Phase 2로 진입합니다. 사용자가 "테마는 당신이 골라 줘"라고 하면 → 추천한 첫 번째 것을 선택하고, 사용자에게 무엇을 선택했는지, 왜 그런지 알린 후 번복할 기회를 줍니다
- 모드 선택 완료 → Phase 2 진입
Phase 2 — 웹 개발
2.1 스캐폴딩
bash <path-to-web-video-presentation>/scripts/scaffold.sh \
./presentation \
--theme=<사용자가 선택한 테마 id>
bash <path-to-web-video-presentation>/scripts/scaffold.sh --list-themes
커스텀 테마 → 먼저
references/THEMES.md의 "새 테마 생성" 프로세스에 따라themes/<my-theme>/를 만든 후,--theme=<my-theme>를 사용합니다.
스캐폴딩에는 01-example 데모가 포함되어 있습니다. 첫 번째 장의 실제 내용을 작성하기 전에 삭제:
rm -rf presentation/src/chapters/01-example
그리고 presentation/src/registry/chapters.ts에서 EXAMPLE_CHAPTER의 import와 배열 항목을 제거합니다.
2.2 1장 — 메인 스레드 + 강제 검수
핵심: 1장 = 완전 버전을 한 번에 완성 (리듬 + 시각 + 실제 소재 모두 포함). "뼈대 버전" 개념은 없습니다 — 첫 장부터 사용자가 직접 검수할 수 있는 샘플을 만들어야 합니다.
왜 1장이 메인 스레드여야 하는가:
- 이것은
CHAPTER-CRAFT.md지침이 현재 테마 + 현재 소재에 처음으로 적용되는 순간입니다. - 지침에 사각지대가 있거나 테마 색상/글꼴 토큰이 부족하면 1장에서 반드시 드러납니다 — 이때 인간의 피드백을 받아 지침을 수정하거나 테마를 조정할 수 있으며, 일찍 고칠수록 비용이 가장 낮습니다.
- 후속 챕터 (순차/병렬 여부와 관계없이) 모두 1장의 코드 패턴을 참고하므로, 1장 = 해당 프로젝트의 "스타일 앵커 (챕터 간 일관성을 강요하지는 않지만, 단일 챕터 자체는 완전한 설득력이 있어야 함)"입니다.
1장 완료 후 반드시 멈춰서 사용자 검수를 기다립니다:
1장 <id> 완료, dev server가 localhost:5173에서 실행 중입니다.
검수 중점:
□ 시각적 분위기가 맞나요? <theme nameZh>의 예상과 일치하나요?
□ 리듬이 적절한가요? 특정 단계가 너무 빠르거나 / 느리거나 / 정보가 너무 얇은가요?
□ 콘텐츠 기반 애니메이션이 적절하게 구현되었나요? 아니면 몇몇 단계는 생각 없는 입장 애니메이션인가요?
□ 이중 소스 원칙: 화면에 "구술에서는 언급되지 않았지만 article에서 가져올 수 있는" 세부 정보가 있나요?
□ 반 AI 냄새 점검: 보라색-분홍색 그라데이션 / 둥근 모서리 컬러 테두리 / 가짜 일러스트레이션 / 이모지가 있나요?
문제가 있으면 알려주시면 맞춰서 수정하겠습니다. 괜찮으면 "계속"이라고 알려주세요. 선택한 모드에 따라 2장 이후를 진행하겠습니다.
2.3 2~N장 — 선택한 모드에 따라
모든 모드의 공통 규칙: 각 장은 독립적으로 CHAPTER-CRAFT.md에 따라 개발합니다. 챕터 간 스타일이 완전히 일치할 필요는 없습니다 — 테마 색상/글꼴 토큰이 시각적 통일성을 보장하며, 애니메이션/리듬/시각적 표현은 각 장이 자유롭게 구현하는 것이 설계 의도입니다.
모드 A · 기본 · 장별 확인
2장 완료 → 중단 후 검수 → OK → 3장 → 중단 → ... → N장. 각 장을 독립적으로 검수하며, 문제는 즉시 수정합니다. 위험이 가장 낮고 리듬이 가장 안정적입니다. 사용자가 명시적으로 모드를 선택하지 않은 경우 기본적으로 이 모드를 사용합니다.
모드 B · 1장 후 순차 개발
2장 → 3장 → ... → N장 메인 스레드에서 순서대로 완료 후, 마지막에 통합 검수. 속도는 중간 정도이며, 에이전트가 병렬 작업을 지원하지 않는 환경에 적합합니다.
모드 C · 1장 후 병렬 개발 (subagent)
subagent를 사용하여 2~N장을 병렬로 완료하며, 최대 병렬 수는 사용자가 제어합니다 ("한 번에 4장" / "한 번에 2장"). 가장 빠르지만, 각 장의 스타일에 차이가 있을 수 있습니다 — 이는 예상된 현상입니다. 이유:
- 각 subagent는 다른 subagent의 결과물을 볼 수 없으므로 기계적으로 정렬할 수 없습니다.
- 챕터 코드는 물리적으로 분리되어 있습니다 (각 장은 별도 폴더 / 자체 CSS 접두사 사용). 서로를 손상시키지 않습니다.
- 테마 토큰이 시각적 통일성을 보장합니다 (색상 / 글꼴 / 히어로 숫자 / 카드 / 구분선 성격 / 장식). 분위기가 크게 벗어나지 않습니다.
- 스타일 불일치 = 사람이 손으로 쓴 비디오의 숨결 (다양한 목소리 / 다양한 시각).
병렬 subagent의 프롬프트에는 다음이 반드시 포함되어야 합니다:
- 현재 챕터의 outline 문단 (정보 풀 포함)
references/CHAPTER-CRAFT.md경로 (단일 필독 — 시각적 표현 요구 사항 + 단계적 공개 + 이중 소스 원칙 + 반 AI 냄새 + 코드 레드 라인 + 완료 자체 점검이 모두 이 파일 하나에 있음)- 현재 테마
theme.json의descriptionZh/mood/bestFor(분위기 참고용, 애니메이션/시간/글자 크기/이모지는 챕터 에이전트가 자유롭게 결정) - 1장 코드를 "코드 스타일" 참고 자료로 사용 ("시각적 모방 대상"이 아님)
- 하드 규칙: 각 장은 독립적인 CSS 접두사 사용 (
.cd-/.mg-/.pm-/ ...);chapters.ts수정 금지; 완료 후npx tsc --noEmit실행
중요: 어떤 모드를 선택하든, 사용자는 언제든지 중간에 모드를 전환할 수 있습니다. 2장이 OK된 후 사용자가 "나머지는 병렬로" / "나머지는 장별로"라고 해도 됩니다.
2.4 단일 챕터 구현 (각 장마다 필수)
자세한 지침은 references/CHAPTER-CRAFT.md를 참조하세요 — 단일 필독 진입점이며, 다음을 다룹니다: 시각적 표현 요구 사항 / 단계적 공개 / 콘텐츠 선택 / 이중 소스 원칙 / 비디오 표현 기본 미학 / 반 AI 냄새 / 코드 레드 라인 / 완료 자체 점검.
핵심 요점 (CHAPTER-CRAFT.md에 상세히 설명됨):
- 각 장에는 반드시 CSS / SVG / Canvas / JS 시각적 표현이 있어야 하며, 순수 텍스트 챕터는 금지됩니다.
- 단계적 공개: 목록은 반드시 1개 항목 = 1단계(step)여야 하며, 한 번에 모두 표시하는 것은 금지됩니다.
- 이중 소스 원칙: 리듬은 구술 대본을 따르고 (순서를 바꿀 수 없음), 세부 정보는 원문 article에서 가져옵니다 (정보 풀 + 해당 챕터의 article 문단).
- 완료 자체 점검을 항목별로 수행하며, 기준 미달 시 수정합니다 — 위의 '하드 자체 점검 프로토콜'에 따라 실행하고 (Agent Teams → subAgent → 자체 점검 우선 순위), 수정한 후에야 사용자에게 해당 챕터 인도 완료를 보고합니다.
2.5 대규모 수정 후 STORAGE_KEY 증가
chapters.ts를 변경한 후 (챕터 추가/삭제/재배열, 또는 특정 챕터의 narrations.ts 길이 변경), presentation/src/hooks/useStepper.ts의 STORAGE_KEY를 증가시킵니다 (예: v4 → v5). 이는 지속화된 커서가 존재하지 않는 단계(step)를 가리키는 것을 방지합니다.
Checkpoint Audio — 오디오 합성 여부 결정 (하드 노드)
Phase 2 종료 후 반드시 멈춰서 사용자에게 질문해야 합니다:
웹 페이지 완료, {N}장 {M}단계, dev server가 localhost:5173에서 실행 중입니다.
"자동 재생 녹화"를 위해 오디오를 합성할까요?
✓ 합성 → 모든 챕터의 narrations.ts를 스캔하여 audio-segments.json 생성,
TTS 공급자를 호출하여 각 단계별 mp3를 public/audio/에 합성합니다.
합성 후 ?auto=1 모드를 사용하여 한 번에 녹화할 수 있습니다 (오디오-비디오 자연 동기화).
내장 공급자 2개:
• minimax (mmx-cli) — 기본값, 중국어 음색 안정적
• openai (OPENAI_API_KEY) — curl 기반, 대부분 이미 키 보유
기타 백엔드 (ElevenLabs / edge-tts 무료 / macOS say 오프라인 /
Azure / Google)는 scripts/tts-providers/README.md의 기성 코드 조각 참조.
✗ 합성 안 함 → Phase 3 건너뛰고, 직접 Phase 4 수동 녹화 + 후반 작업 더빙으로 진행.
합성 선택 → Phase 3. 합성 안 함 → 바로 Phase 4.
Phase 3 — 오디오 합성 (선택 사항)
자세한 프로세스는 references/AUDIO.md를 참조하세요. 간략 버전:
cd presentation
npm run extract-narrations # 모든 narrations.ts 스캔 → audio-segments.json 생성
# 사용자가 audio-segments.json을 훑어보고 텍스트가 올바른지 확인
npm run synthesize-audio # 기본 minimax 공급자, 증분 방식
# 또는 내장 openai 사용 (OPENAI_API_KEY 필요):
PRESENTATION_TTS=openai npm run synthesize-audio
# 또는 커스텀: scripts/tts-providers/<name>.sh 작성, 해당 디렉토리의 README.md 참조
합성이 완료되면 사용자에게 알립니다: 출력 위치 / 총 세그먼트 수 / 비정상적으로 긴 세그먼트 (너무 길면 해당 step 분할 필요; 너무 짧으면文案이 너무 얇음) — 리듬을 최종 조정할 기회를 제공합니다. 그런 다음 Phase 4로 진행합니다.
Phase 4 — 녹화 + 후반 작업
자세한 내용은 references/RECORDING.md를 참조하세요. 두 가지 경로:
| 시나리오 | 추천 경로 |
|---|---|
| Phase 3에서 오디오 합성 완료 | Auto 모드 원테이크: 브라우저에서 localhost:5173/?auto=1 열기 → SPACE 누르기 → 전체 영상 자동 재생 완료 → 녹화 중지 → 앞뒤 자르기만 하면 완성, 후반 작업에서 오디오 트랙을 맞출 필요 없음 |
| Phase 3 건너뜀 | 기본 Manual 모드: 수동 클릭으로 진행 → 후반 작업에서 원하는 편집 도구로 더빙 |
에이전트는 Phase 3 / Checkpoint Audio 후에 사용자에게 적합한 녹화 경로를 능동적으로 알려줍니다.
10가지 원칙 (한 줄 요약 목록)
전체 내용은 references/CHAPTER-CRAFT.md Part 0을 참조하세요 — 챕터 작성 시에는 그곳에서 확인하세요. 아래는 색인일 뿐입니다.
| # | 원칙 | 한 줄 요약 |
|---|---|---|
| 1 | 16:9 고정 스테이지 | 콘텐츠는 1920×1080 + transform scale, 반응형 없음 |
| 2 | 전역 step 카운터 | 챕터는 step의 순수 함수, 타이머 없음 |
| 3 | 각 step이 전체 화면 차지 | if (step === N) return <FullScene /> |
| 4 | 구술 비트 = step | 한 비트 = 한 step = 하나의 집중된 생각 |
| 5 | 숨겨진 모서리 컨트롤 | 진행률 표시줄 / 페이지 넘김 버튼 기본 opacity 0 |
| 6 | 스테이지에 크롬 없음 | 헤더 / 푸터 / 페이지 번호 / 브랜드 바 없음 |
| 7 | 콘텐츠 기반 애니메이션 | 먼저 내재된 동작을 찾고, 찾을 수 없을 때만 입장 애니메이션으로 대체; 지속적인 미세 움직임은 신중하게 사용 |
| 8 | 여러 점을 하나씩 공개 | 1개 항목 = 1 step, N개 항목을 동시에 stagger로 보여주는 것 금지 |
| 9 | 전체 영상 동일 테마 | 챕터 간 표면 색상 변경 금지; 색상/글꼴은 토큰 사용, 다른尺度는 챕터 자유 |
| 10 | 이중 소스 원칙 | script는 비트를 결정, article은 화면 밀도를 결정 (정보 풀에 반영) |
일반적인 사용자 피드백 빠른 참조
간소화된 표는 references/CHAPTER-CRAFT.md Part 8 '일반 피드백 빠른 참조'를 참조하세요. 핵심: 먼저 어느 계층 (리듬 / 시각 / 콘텐츠 / 코드)의 문제인지 파악한 후, 가장 작은 조각만 수정하고 전체 장을 다시 만들지 마세요.
관련 리소스
"언제 읽을지" 표시를 통해 한 번에 모두 읽지 않도록 합니다:
| 파일 | 언제 읽을지 | 내용 |
|---|---|---|
references/SCRIPT-STYLE.md | Phase 1.2 필독 | 글 → 구술 대본 규칙, 플랫폼 변형 |
references/OUTLINE-FORMAT.md | Phase 1.2 필독 | outline.md 필드 스펙, 명명 규칙, 챕터 분할, 정보 풀 |
references/CHAPTER-CRAFT.md | Phase 2.4 각 장의 단일 필독 진입점 | Part 0 10가지 원칙 / Part 1 시작 5문 / Part 2 관계→동작 결정 트리 / Part 3 시각적 도구 상자 / Part 4 시간 / Part 5 반 AI 냄새 안티 패턴 / Part 6 코드 하드 규칙 / Part 7 완료 자체 점검 / Part 8 피드백 빠른 참조 |
references/EXAMPLES/ | 선택 사항 — 구조 확인 | 챕터 구조 예시 (hook / list-reveal / case-tech-review); 복사할 템플릿이 아님 |
references/THEMES.md | 테마 선택 / 생성 / 수정 시 | 전체 토큰 계약 + 내장 테마 목록 + 생성 프로세스 |
references/AUDIO.md | Phase 3에서만 읽음 | 공급자에 구애받지 않는 오디오 합성 프로세스, 내장 minimax 사용법, 공급자 교체 경로, 문제 해결 |
templates/scripts/tts-providers/README.md | TTS 공급자 교체/추가 시 | 3함수 계약 + 내장 2개 (minimax / openai) + 5종 기성 코드 조각 (ElevenLabs / edge-tts / macOS say / Azure / Google) |
references/RECORDING.md | Phase 4에서만 읽음 | 녹화 도구 + 후반 합성 |
themes/ | Checkpoint Plan / Phase 1.2 시 참조 | 내장 테마 (각각 theme.json + tokens.css 포함) |
scripts/scaffold.sh | Phase 2.1에서 한 번 실행 | 원클릭 프로젝트 스캐폴딩 |