generate-script

name	generate-script
description	완성된 씬 데이터(프롬프트, 내레이션, scene_meta)를 마스터 대본 JSON, 마크다운 대본, CSV 파일로 저장한다. JSON은 FlowGenie/TTS/SceneWeaver가 소비하는 마스터 포맷이다. 모든 씬 상세가 확정된 후 자동으로 실행되거나, '파일 생성해줘', '저장해줘'라고 요청하면 사용한다.

출력 파일 생성

완성된 씬 데이터를 3가지 형식으로 저장한다. 경로/파일명의 {prefix}는 _manifest.json의 절 prefix(예: 22). 없으면 장 번호 2자리(ch03).

사전 조건

• prompt-craft에서 모든 씬의 상세가 확정되어야 한다
• _series_guide.json(narration_style·genre·audience), _manifest.json(prefix·part·title) 참조

생성 절차

Step 1: 출력 폴더 생성

output/{prefix}/ 폴더를 생성한다 (없으면).

Step 2: JSON 생성 — 마스터 대본

output/{prefix}/{prefix}_script.json

CLAUDE.md에 정의된 풀 스키마를 따른다. 최상위 필드:

{
  "version": "1.0",
  "chapter": 22,                 // prefix를 정수로
  "title": "...",                // manifest/MD
  "subtitle": "...",             // MD 부제목 또는 요약
  "part": "2",                   // manifest
  "genre": "classic-documentary-full",
  "category": "fullform",
  "aspect_ratio": "16:9",
  "channel_format": "youtube_long",
  "total_duration_seconds": 0,   // 모든 씬 narration_seconds 합계
  "estimated_video_minutes": 0,  // round(total_duration_seconds / 60)
  "default_model": "nano_banana",
  "default_transition": "crossfade",
  "narration_style": { /* 시리즈 가이드에서 복사 */ },
  "scenes": [ /* 각 씬: scene, scene_type, title, narration_text, narration_seconds,
                 voice_style, image_filename, prompt, model, visual_description,
                 reference_image, scene_meta{era,mood,transition_hint,text_overlay,subtitle,bgm_hint} */ ],
  "video_meta": { /* 아래 */ }
}

계산/규칙:

• total_duration_seconds: 모든 씬 narration_seconds 합계
• estimated_video_minutes: round(total_duration_seconds / 60)
• narration_seconds: ceil(공백 제외 글자수 / narration_style.chars_per_second) (기본 3.0)
• FlowGenie 소비 필드(prompt/model/image_filename)는 이름·의미 불변

video_meta:

• aspect_ratio: 시리즈 가이드 또는 16:9
• opening_title: 챕터 제목
• closing_text: 마지막 절이면 "시리즈 완결", 아니면 "다음 편에서 계속..."
• default_transition: 시리즈 가이드 또는 crossfade
• bgm_track: null (미정)

Step 3: MD 생성 — 사람이 읽는 대본

output/{prefix}/{prefix}_script.md

# [prefix]. [챕터 제목]

> 장르: [genre] | 씬: [N]개 | 총 시간: [M]분 [S]초 | 청중: [audience]

---

## Scene 1 [opening_title]: [씬 제목] (N초)

**내레이션:**
> [내레이션 텍스트]

**이미지 프롬프트:**
[영문 프롬프트]

**비주얼 메모:** [visual_description]
**파일명:** [image_filename] | **모델:** [model]
**시대:** [era] | **분위기:** [mood] | **전환:** [transition_hint] | **자막:** [subtitle] | **BGM:** [bgm_hint]

---
...

## 영상 정보
- 화면비: [aspect_ratio]
- 오프닝: [opening_title]
- 엔딩: [closing_text]
- 기본 전환: [default_transition]

Step 4: CSV 생성 — Excel 검토용

output/{prefix}/{prefix}_script.csv — 반드시 UTF-8 BOM으로 생성한다.

① Excel 호환 — UTF-8 BOM 필수

한국어 Windows Excel은 CSV를 더블클릭으로 열 때 시스템 로케일(CP949)로 해석한다. BOM이 없으면 한글이 깨진다. CSV는 반드시 UTF-8 BOM(첫 3바이트 EF BB BF)으로 시작해야 한다.

방법 A — Python:

import csv
with open(f'output/{prefix}/{prefix}_script.csv', 'w', encoding='utf-8-sig', newline='') as f:
    writer = csv.writer(f)
    writer.writerow(['scene','scene_type','title','narration_text','narration_seconds',
                     'prompt','model','image_filename','visual_description',
                     'era','mood','transition','subtitle','bgm_hint'])
    for s in scenes:
        writer.writerow([...])

핵심: encoding='utf-8-sig'(BOM 자동) + newline=''(Excel 호환 줄바꿈)

방법 B — Write 도구로 직접 텍스트를 쓸 때: 콘텐츠 맨 첫 글자에 보이지 않는 BOM 문자(, U+FEFF)를 포함시킨다(Write는 BOM을 자동 추가하지 않음).

✅ 생성 후 필수 검증

head -c 3 output/{prefix}/{prefix}_script.csv | xxd   # 기대: efbb bf

검증 실패 시 BOM 추가:

printf '\xef\xbb\xbf' | cat - {prefix}_script.csv > tmp.csv && mv tmp.csv {prefix}_script.csv

컬럼: scene, scene_type, title, narration_text, narration_seconds, prompt, model, image_filename, visual_description, era, mood, transition, subtitle, bgm_hint

(옵션) XLSX 동시 생성

Excel을 자주 쓰는 워크플로우면 {prefix}_script.xlsx도 생성:

• 헤더 강조(#305496 배경, 흰 글씨, bold), 첫 행+첫 두 컬럼 고정(freeze_panes='C2'), 자동 필터
• 짝수 행 스트라이프(#F2F2F2), 한글 폰트 맑은 고딕(헤더 11pt bold, 본문 10pt)
• 행 높이 헤더 32/본문 110, 컬럼 자동 너비(narration_text 60, prompt 80 등), wrap_text=True, vertical='top'

XLSX는 인코딩 문제가 없으므로 BOM과 무관하게 안전하다.

Step 5: 매니페스트 업데이트

output/_manifest.json에 생성 결과를 반영(있으면 해당 절 항목만 추가/업데이트). 입력 manifest의 sections 메타는 보존하고, 생성물 정보(scene_count, total_seconds, generated_at, files)를 더한다.

{
  "chapter": 22, "title": "...", "part": "2",
  "scene_count": 22, "total_seconds": 960, "generated_at": "...",
  "files": { "json": "22/22_script.json", "md": "22/22_script.md", "csv": "22/22_script.csv" }
}

Step 6: 결과 보고

✅ 대본 생성 완료

📁 output/22/
   ├── 22_script.json  (FlowGenie/Veo·TTS·SceneWeaver용)
   ├── 22_script.md    (사람이 읽는 대본)
   └── 22_script.csv   (Excel 검토용, UTF-8 BOM)

📊 요약: 22씬 | 16분 0초 | nano_banana ×22 | 이미지 22_01~22_22

💡 다음 단계:
   - JSON을 FlowGenie/Veo에 넣어 이미지 생성
   - /forge-review로 수정
   - /forge-batch로 나머지 절 일괄 처리