# Generate Script

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

- Skill: `leedonwoo2827-ship-it/generate-script` (Agent Skill)
- Install (CLI): `npx skillmds@latest add leedonwoo2827-ship-it/generate-script`
- Raw SKILL.md: https://api.skillmd.com/api/skills/leedonwoo2827-ship-it/generate-script/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: leedonwoo2827-ship-it (https://skillmd.com/u/leedonwoo2827-ship-it)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/leedonwoo2827-ship-it/generate-script

---


# 출력 파일 생성

완성된 씬 데이터를 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에 정의된 **풀 스키마**를 따른다. 최상위 필드:

```jsonc
{
  "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`

```markdown
# [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:**
```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을 자동 추가하지 않음).

#### ✅ 생성 후 필수 검증

```bash
head -c 3 output/{prefix}/{prefix}_script.csv | xxd   # 기대: efbb bf
```
검증 실패 시 BOM 추가:
```bash
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)를 더한다.

```json
{
  "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로 나머지 절 일괄 처리
```