# malfoy-meme-kit

- 「악역영애 말포이」 밈 쇼츠 5편(V1 S랭크 뽑기·V2 에이전트 쇼케이스·V3 로판 오프닝·V4 하이퍼 에디트·V5 로판 오프닝 영어판)을 만든 재료 일체
- 실제로 적용된 최종 프롬프트(이미지·Flow·음악·TTS·효과음) + 파이프라인 정의·상태 공간(State) + 실제로 돌린 스크립트 사본
- 내려받아 프롬프트만 재사용하거나, 같은 순서로 파이프라인을 다시 돌리는 용도

## 폴더 구조

```
malfoy-meme-kit/
├── README.md               이 문서
├── KIT-PLAN.md             키트 구성 계약(각 파일 형식 정의)
├── prompts/                실제 적용 프롬프트(기계가 읽는 형식)
│   ├── README.md           프롬프트 폴더 설명
│   ├── verify_prompts.py   프롬프트 파일 형식·내용 검사
│   ├── images.jsonl        codex $imagegen(gpt-image-2) 이미지 프롬프트 + 참조 이미지 + 최종 파일명
│   ├── flow_jobs.jsonl     Google Flow(Gemini Omni Flash) 영상 잡: 모드·첫/끝 프레임·프롬프트·크레딧·판정
│   ├── audio/
│   │   ├── music.json      편별 채택 곡 composition_plan 원문 + 자르기·이어붙이기 기록
│   │   ├── tts.jsonl       대사별 보이스·설정·태그 포함 텍스트
│   │   └── sfx.jsonl       효과음 프롬프트·길이
│   └── templates/          조립 공식(고정 블록·가변 블록·꼬리) 템플릿 + fill.py + examples/
├── pipeline/               파이프라인 정의와 상태 공간
│   ├── pipeline.yaml       노드·엣지·사용자 반려 되돌림(interrupts)·예산
│   ├── state_schema.json   State 전체 JSON Schema(키별 쓰는 노드·읽는 노드)
│   ├── state.py            LangGraph TypedDict + reducer
│   ├── graph.py            LangGraph StateGraph 골격(`python graph.py --dry-run` = 구조만 출력, 외부 호출 없음)
│   ├── verify.py           파이프라인 정의 검사
│   └── STATE.md            상태 키 표 + 노드별 읽기/쓰기 행렬 + 상태 전이도(Mermaid)
└── tools/                  실제로 돌린 스크립트 사본(설명·필요 환경은 tools/README.md)
    ├── _tools/             imagegen_runner.py · heavy.sh · matte_queue.sh · render-win.sh · RENDER-FAST.md
    ├── 05_matte/           matte.sh + bin/(keyer.py · aimask_dml.py 등)
    ├── 07_render/          v2/tools/comp.py · v4/tools/comp4.py · edl.py · shots.py
    └── 04_audio/_work/     analyze.py · gen_music.py · tts.py · sfx.py
```

## 재실행 순서

| # | 단계 | 쓰는 것 | 키트 파일 |
|---|---|---|---|
| 1 | 리서치 | 밈 확산 경로·Flow 공식 문서(단가·워터마크·9:16)·레퍼런스 분류 | pipeline/pipeline.yaml |
| 2 | 스토리보드 | 편별 컷·대사·박자 설계 | pipeline/STATE.md |
| 3 | codex 이미지 | 캐릭터·의상·배경 원화(블루 #1E3CFF 배경) | prompts/images.jsonl, tools/_tools/imagegen_runner.py |
| 4 | 내용 대조 | 생성 이미지가 프롬프트·설정과 맞는지 검수, 어긋나면 재생성 | prompts/images.jsonl(final_file) |
| 5 | Flow 영상(Aside 브라우저) | 이미지를 첫 프레임·재료로 넣어 720p 9:16 클립 생성, 동시 5개 안팎 | prompts/flow_jobs.jsonl |
| 6 | 매팅 | 블루 배경 클립 → 알파 webm(색차 키 + isnet-anime 가이드) | tools/05_matte/, tools/_tools/matte_queue.sh |
| 7 | 오디오 | 음악·TTS·효과음 생성 → 비트 분석 | prompts/audio/, tools/04_audio/_work/ |
| 8 | 배경 블록 | HyperFrames로 배경·타이포·플레이트 렌더 | tools/_tools/RENDER-FAST.md, render-win.sh |
| 9 | 합성 | 배경 + 알파 캐릭터 + 가상 카메라 + 오버레이·효과 | tools/07_render/ |
| 10 | 판정 | 컨택트 시트·QC로 반려 여부 결정, 반려 시 해당 노드로 되돌림 | pipeline/pipeline.yaml(interrupts) |
| 11 | render | 최종 mp4 + 오디오 mux | tools/07_render/, tools/_tools/heavy.sh |

- 원칙: 텍스트만으로 Flow 영상 생성 금지 → 반드시 codex 이미지를 Flow 에셋으로 넣고 시작
- 사람 확인 지점: 스토리보드 승인, 이미지 내용 대조, 최종 판정

## 필요한 계정·도구

| 항목 | 용도 | 비고 |
|---|---|---|
| codex CLI(로그인) | `$imagegen` = gpt-image-2 이미지 생성 | 병렬 스폰은 imagegen_runner.py |
| Google Flow PRO | Gemini Omni Flash 영상 클립 | 크레딧 필요, 한국 계정은 워터마크 강제 |
| ElevenLabs Creator | Music·TTS(eleven_v4)·Sound Effects | env `ELEVENLABS_API_KEY` |
| Aside 브라우저 | Flow 웹 UI 조작(제출·다운로드) | Flow는 API 아닌 웹 UI |
| HyperFrames | 배경·타이포 블록 렌더 | `npx hyperframes render` |
| ffmpeg / ffprobe | 디코드·인코드(VP9 알파)·mux | |
| python3 | numpy·opencv-python·rembg·librosa·onnxruntime(-directml) | tools/README.md 참고 |
| GPU(선택) | 매팅 AI 가이드 가속(AMD·NVIDIA, Windows DirectML) | 없으면 CPU 또는 `--fast` |

## 비용 실적(5편 합계)

| 서비스 | 사용량 | 내역 |
|---|---|---|
| Google Flow | **386 크레딧**(1,050 → 664) | 테스트 10 + V1 88 + ref 88 + extra 71 + V3 59 + V4 70 |
| ElevenLabs | **약 19,475**(character_count) | V1 3,101 + V3 9,938 + V4 1,324 + V5(영어판) 5,112 |

## 주의

- **해리포터 2차 창작물**: 캐릭터·세계관 권리는 원저작권자에 있음. 개인·비상업 밈 용도로만 쓰고 **상업 이용 금지 권고**
- **IP 단어 프롬프트 금지 원칙**: 해리포터·말포이·슬리데린·호그와트 같은 IP 단어는 codex·Flow 프롬프트·노래 가사에 안 씀(자막·VO에서만). 외형·의상·분위기 묘사로만 생성, Flow 잡은 스크립트로 IP 단어 0건 검사
- 제목 표기는 "Fem Malfoy" / "악역영애 말포이". "Malfoid"는 비하어 기원이라 자막 메인 금지
- **Flow 한국 계정 워터마크**: 우하단 ✦ 반투명 워터마크가 강제로 박힘 → 이번엔 매팅 단계의 가비지 매트로 지워짐(캐릭터와 겹치면 남을 수 있음)
- 비밀값 없음: API 키·토큰·이메일은 키트에 포함하지 않음, 환경변수명만 표기
- 스크립트 경로는 원래 작업 폴더(`/mnt/d/malfoy-meme`) 하드코딩 그대로 → 실행 전 자기 경로로 바꿀 것

## 문서

- 제작 과정·프롬프트 원문 해설·파이프라인 그래프·도구별 상세는 사이트 문서 참고