@autoaiai/aicut 0.1.7 → 0.1.11

package/skills/youtube/references/thumbnail-ctr-guide.md

@@ -0,0 +1,73 @@
+# Thumbnail CTR Guide
+
+## What Drives CTR (Data-Backed)
+
+| Element | CTR Impact | Source |
+|---------|-----------|--------|
+| Face in thumbnail | +38% | vidIQ, 5M channel dataset |
+| Dark background | Higher in tech/tutorial | SERP pattern analysis |
+| High contrast text | Readable at small size | A/B testing data |
+| Result shown (not process) | Higher than "building" state | Focus Digital, 2025 |
+| 2–3 words max | Better than 5+ words | vidIQ analysis |
+
+## The Winning Formula (Tutorial / Tech Niche)
+
+```
+Background: DARK (black or very dark gray — not white, not grey)
+Subject:    The OUTPUT in its final, revealed state — NOT the Elementor editor
+Text:       2–3 words max, bold, high contrast (white or brand accent)
+Concept:    Viewer instantly sees: "I want that result"
+```
+
+**What NOT to show**: The Elementor backend while building. Nobody clicks on a screenshot of panel settings. Show the finished website in action.
+
+## 3 Proven Thumbnail Archetypes
+
+### Type A — Result Showcase
+- Full-width finished UI on dark background
+- 2–3 word overlay stating the outcome
+- Best for: widget demos, design tutorials
+- Example: Dark background + the animated side menu in open state + "HOVER MENU"
+
+### Type B — Before/After Split
+- Left: plain/boring version | Right: polished version
+- Visual contrast = instant curiosity
+- Best for: comparison, transformation, "fix this" tutorials
+- Example: Default Elementor nav | The fancy hover sidebar
+
+### Type C — Text-Heavy (Bold Statement)
+- Large typography dominates
+- For when the words ARE the hook
+- Best for: controversial or curiosity-gap titles
+- Example: "NOT A POPUP" in huge text
+
+## Title-Thumbnail Synergy Check
+
+Your title and thumbnail must not say the same thing — they should complement each other:
+
+| Title says | Thumbnail shows |
+|-----------|----------------|
+| "No Code Needed" | The polished result (implies code-level quality) |
+| "Smooth Hover Menu" | Menu in motion / revealed state |
+| "NOT Off-Canvas Popup" | The alternative design they'd prefer |
+
+If both say the same thing, you're wasting one signal. Thumbnail = visual promise, Title = keyword search + hook.
+
+## Thumbnail Text Rules
+
+- Max 3 words (ideally 2)
+- Use CAPS for 1–2 power words only
+- Don't put the full video title on the thumbnail
+- Readable at 120px × 68px (YouTube search size) — test by zooming out
+
+## A/B Testing
+
+YouTube Studio shows title/thumbnail A/B results after ~1,000 impressions.
+- Run tests for minimum 7 days before deciding
+- Change one variable at a time (thumbnail OR title, not both)
+- The winning variant becomes permanent — update within 2 weeks
+
+## Sources
+- vidIQ 5M-channel thumbnail analysis dataset
+- Focus Digital, December 2025
+- YouTube Creator Academy A/B test documentation

package/skills/youtube-shorts-factory/SKILL.md

@@ -0,0 +1,358 @@
+---
+name: youtube-shorts-factory
+description: "유튜브 레퍼런스 영상 분석 → 벤치마킹 → 30%+ 각색 → 스토리보드 기획 → rfn-video-pipeline용 JSON 생성 → 이미지 생성 → HTML 시각화 → AI 영상 제작까지의 전체 쇼츠 제작 워크플로우. 유튜브 쇼츠 분석, 벤치마킹, 각색, 스토리보드, 레퍼런스 영상, 바이럴 분석, 감정 공학, 쇼츠 팩토리, 영상 기획, 콘텐츠 클론 시 자동 활성화. Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
+license: MIT
+source: "ninestonelee/youtube-shorts-factory"
+---
+
+# YouTube Shorts Factory — 레퍼런스 기반 AI 쇼츠 제작 스킬
+
+## Running it in AICUT
+
+AICUT's film is `film.html`: it cuts pages, footage, pictures and sound together on tracks. A page is a web page that
+sets `window.film = { frame(t) }` and draws that moment — no framework, no build step, no composition object, no
+`registerRoot`. Five shots are five pages cut together, not one page that changes scene, so each shot stays trimmable
+and replaceable in Studio.
+
+```sh
+npx -y @autoaiai/aicut@latest          # the manual: the format and the commands, always current
+npx -y @autoaiai/aicut@latest open .   # make this folder a film and print Studio's address
+npx -y @autoaiai/aicut@latest look     # a contact sheet of the whole film, its sound, and a determinism check
+npx -y @autoaiai/aicut@latest look 4.5 # one frame, full size — look at the PNG, not at the code
+npx -y @autoaiai/aicut@latest render   # the MP4, beside film.html
+```
+
+Run the manual before the first film: it is authoritative for the format, and this skill is about the method above it.
+
+Where the words below name another program's part, it becomes this:
+
+| elsewhere | in AICUT |
+|---|---|
+| composition, timeline, project file | `film.html`; tracks and clips inside it |
+| a scene, a sequence, a slide | a page (`pages/<name>.html`) cut onto a track |
+| `useCurrentFrame()`, `interpolate()` | `frame(t)` — the picture depends only on `t`, never on state or `Date.now()` |
+| a still, a screengrab | `aicut look <t>` |
+| `render` / `build` / `export` | `aicut render` (the person can also export from Studio) |
+| a dev server, a preview window | `aicut open` and the Studio address it prints |
+
+Hard rules that hold whatever the method says: the picture depends only on `t`; every value in the person's prompt is
+binding; look at the frames `look` writes before saying a film is done.
+
+
+## 전체 워크플로우
+
+```
+Step 1: 유튜브 URL 입력 & 자막 추출
+         ↓
+Step 2: 영상 포렌식 분석 (바이럴 공식 해부)
+         ↓
+Step 3: 30%+ 각색 스토리보드 기획
+         ↓
+Step 4: rfn-video-pipeline용 Story JSON 생성
+         ↓
+Step 5: 이미지 생성 (한국인/K드라마 스타일 고정)
+         ↓
+Step 6: 스토리보드 HTML 시각화
+         ↓
+Step 7: AI 영상 생성 & 자막 추가
+```
+```
+---
+```
+
+## Step 1: 유튜브 자막 추출
+
+### 방법 A: youtube-transcript 스킬 사용
+```
+/youtube-transcript {URL}
+```
+
+### 방법 B: Python 직접 추출
+```python
+from youtube_transcript_api import YouTubeTranscriptApi
+
+# Shorts URL에서 ID 추출
+
+# youtube.com/shorts/1nZRnJVtSew → ID: 1nZRnJVtSew
+video_id = "1nZRnJVtSew"
+api = YouTubeTranscriptApi()
+transcript = api.fetch(video_id, languages=['ko'])
+```
+**주의:** Shorts URL(`youtube.com/shorts/`)은 일반 URL과 ID 추출 패턴이 다름. 직접 비디오 ID만 전달할 것.
+
+---
+```
+
+## Step 2: 영상 포렌식 분석
+
+### 분석 프레임워크 (7개 축)
+
+| 분석 축 | 핵심 질문 |
+|---------|----------|
+| **Hook 구조** | 첫 1~3초에 어떤 시각적/텍스트 훅을 사용했는가? |
+| **내러티브 아크** | 3막 구조(설정→전개→반전)가 어떻게 구성되었는가? |
+| **감정 곡선** | 어떤 감정이 어떤 순서로 배치되었는가? |
+| **Open Loop** | 시청자가 "다음엔?"이라고 궁금해하게 만드는 장치는? |
+| **Silent Hero 패턴** | 대사 없이 행동으로 감동을 전달하는 구조인가? |
+| **Payoff 설계** | 마지막 반전/감동의 장치는 무엇인가? |
+| **바이럴 계수** | 공유 욕구를 자극하는 요소는? (10점 만점 평가) |
+
+### 출력 형식
+
+```markdown
+
+## 포렌식 분석 결과
+
+### 1. Hook 분석
+- 시각적 훅: {설명}
+- 텍스트 훅: {설명}
+- 호기심 갭: {설명}
+
+### 2. 내러티브 구조
+- Act 1 (설정): 00:00~{mm:ss} — {요약}
+- Act 2 (전개): {mm:ss}~{mm:ss} — {요약}
+- Act 3 (반전): {mm:ss}~{mm:ss} — {요약}
+
+### 3. 감정 엔지니어링
+| 타임스탬프 | 감정 | 장치 |
+|-----------|------|------|
+| 00:00 | {감정} | {장치 설명} |
+
+### 4. Open Loop 카운트
+- Loop 1: {설명}
+- Loop 2: {설명}
+
+### 5. 바이럴 계수: {X}/10
+- 공유 트리거: {설명}
+```
+---
+```
+
+## Step 3: 30%+ 각색
+
+각색은 **원본의 감정 공학 공식은 유지**하되, **설정·인물·소품·반전장치를 30% 이상 변경**하는 것.
+
+### 각색 체크리스트
+
+| 요소 | 원본 | 각색 | 변경률 |
+|------|------|------|--------|
+| 주인공 | {원본} | {각색} | ✅/❌ |
+| 관계 | {원본} | {각색} | ✅/❌ |
+| 장소 | {원본} | {각색} | ✅/❌ |
+| 핵심 소품 | {원본} | {각색} | ✅/❌ |
+| Payoff 장치 | {원본} | {각색} | ✅/❌ |
+| **총 변경률** | | | **≥30%** |
+
+### 각색 원칙
+1. **감정 공식 보존**: Hook → 긴장 → 행동 → 반전의 구조는 그대로 유지
+2. **문화적 공감**: 한국 가정의 현실적 디테일 반영 (예: 약통, 된장찌개, 냉장고 메모)
+3. **소품 교체**: 원본의 핵심 소품을 동일 감정을 유발하는 다른 소품으로 교체
+4. **인물 변환**: 부부→부모자식, 친구→동료 등 관계축 변경
+
+상세 가이드: [adaptation-guide.md](resources/adaptation-guide.md)
+
+---
+
+## Step 4: Story JSON 생성
+
+rfn-video-pipeline 스킬의 스토리 JSON 스키마 v2.0을 따름.
+
+### 필수 구조
+
+```json
+{
+  "schema_version": "2.0",
+  "title": "영상 제목",
+  "slug": "story_파일명",
+  "description": "한 줄 설명",
+  "category": "family|inspiration|humor|drama",
+  "target_duration_seconds": 60,
+  "aspect_ratio": "9:16",
+  "scenes": [
+    {
+      "frame": 1,
+      "timestamp": "00:00",
+      "act": 1,
+      "description": "장면 설명 (한글)",
+      "emotion": "establishing_character",
+      "prompt": "이미지 프롬프트 (영어, K드라마 스타일 고정)",
+      "video_prompt": "영상 움직임 프롬프트 (영어)",
+      "video_duration": 6,
+      "camera_motion": "slow_push_in",
+      "video_engine": "veo_fast",
+      "video_priority": "high",
+      "subtitle": "화면 자막 (한국어)"
+    }
+  ]
+}
+
+### 감정 → 엔진 자동 매핑
+
+| 감정 | 엔진 | 비용 |
+|------|------|------|
+| `emotional_climax`, `sacrifice` | `veo_standard` | $1.20 |
+| `suspense`, `warmth`, `joy` | `veo_fast` | $0.45 |
+| `action`, `hope`, `determination` | `minimax` | $0.05 |
+| `establishing_character`, `reflection` | `ken_burns` | $0.00 |
+
+### 비용 확인 (Dry-run)
+
+```bash
+cd rfn_generator
+python scripts/run.py stories/{slug}.json --dry-run
+```
+```
+---
+```
+
+## Step 5: 이미지 생성
+
+### 스타일 고정값 (필수)
+
+모든 이미지 프롬프트에 아래 키워드를 반드시 포함:
+
+```
+Korean actor/actress, realistic Korean facial features,
+Korean drama style, K-drama cinematography, Korean drama lighting,
+warm cinematic, 9:16 vertical, hyperrealistic
+```
+
+### 생성 전 컨펌 프로세스 (필수)
+
+이미지 생성 전에 반드시 아래 테이블을 사용자에게 보여주고 컨펌을 받을 것:
+
+```markdown
+| Frame | 장면 | 핵심 시각 요소 | 스타일 |
+|-------|------|---------------|--------|
+| 1 | {장면 설명} | {핵심 요소} | K드라마 |
+| 2 | {장면 설명} | {핵심 요소} | K드라마 |
+| ... | ... | ... | ... |
+
+### 실행
+
+```bash
+cd rfn_generator
+```
+
+# 기존 이미지 삭제 후 재생성 (프롬프트 수정 시)
+rm output/{slug}/frames/*.png
+python scripts/run.py stories/{slug}.json --max-frames 999 --dry-run  # 비용 확인
+python scripts/run.py stories/{slug}.json  # Phase 1만 실행
+
+### 이미지 검증
+
+생성 후 각 프레임을 반드시 시각적으로 확인하고, 스토리와 불일치하는 프레임은:
+1. 프롬프트에 네거티브 키워드 추가 (`NO face, NO skincare` 등)
+2. 구체적 묘사 강화 (`70s elderly man, eyes closed, lying on sofa`)
+3. 해당 프레임만 삭제 후 재생성
+
+---
+
+## Step 6: 스토리보드 HTML 시각화
+
+생성된 이미지를 스토리보드 HTML에 base64로 주입.
+
+### 이미지 주입 패턴
+
+```python
+import base64, re
+
+def inject_images(html_path, frames_dir, scene_frame_map):
+    """
+    scene_frame_map: {"sc1": [1], "sc2": [2], "sc3": [3,4,5], ...}
+    """
+    with open(html_path, 'r') as f:
+        html = f.read()
+
+    for scene_id, frame_nums in scene_frame_map.items():
+        for frame_num in frame_nums:
+            img_path = f"{frames_dir}/frame_{frame_num:04d}.png"
+            with open(img_path, 'rb') as f:
+                b64 = base64.b64encode(f.read()).decode()
+            img_tag = f'<img src="data:image/png;base64,{b64}" style="width:100%;border-radius:12px;">'
+            # scene-body-inner 안에 삽입
+            pattern = f'(id="{scene_id}"[^>]*>.*?class="scene-body-inner"[^>]*>)'
+            html = re.sub(pattern, f'\\1\n{img_tag}', html, flags=re.DOTALL)
+
+    with open(html_path, 'w') as f:
+        f.write(html)
+
+### AI 텍스트 한계 대응
+
+AI 이미지 생성기는 한국어 텍스트를 정확히 렌더링하지 못함. 텍스트가 중요한 프레임(메모, 간판 등)은 CSS 오버레이로 보완:
+
+```html
+<div style="position:relative;">
+  <img src="data:image/png;base64,...">
+  <div style="position:absolute; bottom:20%; left:50%; transform:translateX(-50%);
+    background:rgba(255,255,240,0.92); padding:16px 28px;
+    font-family:'Nanum Pen Script',cursive; font-size:1.5rem;
+    color:#333; border-radius:8px;">
+    밥 먹었어.<br>고마워.
+  </div>
+</div>
+```
+---
+```
+
+## Step 7: AI 영상 생성
+
+### Google AI 스택 (권장)
+
+| 단계 | 도구 | 용도 |
+|------|------|------|
+| 영상 생성 | Google Veo 2 (VideoFX) | 이미지→영상 변환 |
+| 나레이션 | Google Cloud TTS `ko-KR-Journey-D` | 한국어 내레이션 |
+| BGM | Google MusicFX | AI 배경음악 생성 |
+| 편집 | Google Vids | 최종 편집 |
+
+### rfn-video-pipeline 실행
+
+```bash
+cd rfn_generator
+```
+
+# Phase 2: 영상 생성 (이미지 완료 후)
+python scripts/run.py stories/{slug}.json --resume
+
+# 자막 추가
+python scripts/add_subtitles.py stories/{slug}.json
+
+### 출력 구조
+
+```
+rfn_generator/output/{slug}/
+├── frames/frame_0001.png    # Phase 1 이미지
+├── clips/clip_0001.mp4      # Phase 2 영상 클립
+├── final.mp4                # Phase 3 조립
+└── final_subtitled.mp4      # 자막 burn-in
+```
+```
+---
+```
+
+## 빠른 실행 가이드
+
+사용자가 유튜브 URL을 제공하면 아래 순서로 진행:
+
+1. **자막 추출** → youtube-transcript 스킬 또는 Python API
+2. **포렌식 분석** → 7축 프레임워크로 바이럴 공식 해부
+3. **각색 테이블** → 30%+ 변경 체크리스트 작성 후 사용자 컨펌
+4. **Story JSON** → `rfn_generator/stories/{slug}.json` 생성
+5. **Dry-run** → 비용 확인 후 사용자 컨펌
+6. **이미지 생성** → 스타일 테이블 보여준 후 컨펌 → 생성 → 검증
+7. **HTML 스토리보드** → 이미지 주입한 시각 스토리보드 생성
+8. **영상 제작** → `run.py --resume` + `add_subtitles.py`
+
+---
+
+## 리소스 파일
+
+- [워크플로우 단계별 상세](resources/workflow-steps.md)
+- [각색 가이드 & 사례](resources/adaptation-guide.md)
+- [스토리보드 HTML 템플릿](resources/storyboard-template.md)
+
+## Source
+
+Rewritten for AICUT from [`ninestonelee/youtube-shorts-factory`](https://github.com/ninestonelee/youtube-shorts-factory)
+(MIT), SKILL.md. The method is that skill's own; the way it runs is AICUT's.

package/skills/youtube-shorts-factory/resources/adaptation-guide.md

@@ -0,0 +1,133 @@
+# 각색 가이드 & 사례 모음
+
+## 각색의 원칙
+
+### 30% 규칙
+
+저작권 침해 없이 레퍼런스 영상의 성공 공식을 활용하려면 최소 30% 이상 변경이 필요.
+
+### 변경 가능 요소 (외피)
+
+| 요소 | 설명 | 변경 용이도 |
+|------|------|-----------|
+| 인물 관계 | 부부→부모자식, 친구→동료 | ★★★★★ |
+| 장소/배경 | 집→사무실, 도시→시골 | ★★★★☆ |
+| 핵심 소품 | 편지→메모, 꽃→음식 | ★★★★☆ |
+| 시대/계절 | 현대→과거, 여름→겨울 | ★★★☆☆ |
+| Payoff 장치 | 메시지 전달 방식 변경 | ★★★☆☆ |
+
+### 보존해야 할 요소 (뼈대)
+
+| 요소 | 설명 |
+|------|------|
+| 감정 곡선 | Hook → 긴장 → 행동 → 반전 순서 |
+| Silent Hero 패턴 | 대사 없이 행동으로 보여주기 |
+| Open Loop 개수 | 원본과 동일한 수의 궁금증 장치 |
+| Payoff 타이밍 | 마지막 3~5초에 반전 배치 |
+| 페이싱 | 컷 길이와 템포 |
+
+---
+
+## 각색 사례: "밥 먹었어, 고마워"
+
+### 원본 분석
+
+| 항목 | 원본 |
+|------|------|
+| 제목 | (남편이 아내를 위해 집안일하는 쇼츠) |
+| 관계 | 부부 (남편 → 아내) |
+| 상황 | 지친 아내가 잠든 사이 남편이 집안일 |
+| 행동 | 세탁, 청소, 요리 |
+| Payoff | 아내의 감사 메시지/눈물 |
+
+### 각색 결과
+
+| 항목 | 각색 |
+|------|------|
+| 제목 | 밥 먹었어, 고마워 |
+| 관계 | 부모자식 (성인 자녀 → 노인 아버지) |
+| 상황 | 혼자 사시는 아버지 집을 방문, 잠든 아버지 발견 |
+| 행동 | 이불 덮기, 설거지, 약통 정리, 된장찌개 |
+| Payoff | 냉장고 메모 "밥 먹었어. 고마워." |
+
+### 변경률 분석
+
+| 요소 | 변경 여부 | 설명 |
+|------|----------|------|
+| 주인공 | ✅ | 남편 → 성인 자녀 |
+| 수혜자 | ✅ | 아내 → 노인 아버지 |
+| 장소 | ✅ | 신혼집 → 노인 1인 아파트 |
+| 소품 1 | ✅ | 세탁기 → 약통 |
+| 소품 2 | ✅ | - → 빈 냉장고 (신규) |
+| 음식 | ✅ | 일반 요리 → 된장찌개 |
+| Payoff | ✅ | 눈물 → 냉장고 메모 |
+| **총 변경률** | **7/7** | **100% (외피 완전 교체)** |
+
+---
+
+## 각색 패턴 라이브러리
+
+### 패턴 1: 관계축 전환
+
+```
+부부 → 부모자식
+부부 → 조부모-손주
+연인 → 오래된 친구
+상사-부하 → 선배-후배
+```
+
+### 패턴 2: 공간축 전환
+
+```
+집 → 사무실 (야근하는 동료를 위해)
+집 → 병원 (환자를 위해)
+집 → 군대 (전우를 위해)
+도시 → 시골 (귀향)
+```
+
+### 패턴 3: 시간축 전환
+
+```
+현재 → 과거 회상 (어린 시절)
+일상 → 특별한 날 (생일, 기일)
+평일 → 명절 (추석, 설)
+```
+
+### 패턴 4: Payoff 장치 교체
+
+```
+편지 → 냉장고 메모
+직접 말함 → SNS 메시지
+선물 → 조용히 해놓은 행동 발견
+눈물 → 미소 (역전 감정)
+```
+
+---
+
+## 한국적 디테일 소품 라이브러리
+
+감정별로 사용할 수 있는 한국 가정의 소품:
+
+### 외로움/그리움
+- 빈 냉장고 (혼자 사는 노인)
+- 주간 약통 (빈칸 있는)
+- 바래진 가족사진
+- 작은 TV 앞 혼자 놓인 밥상
+
+### 사랑/돌봄
+- 된장찌개/김치찌개 끓이는 장면
+- 이불 덮어주기
+- 약 챙겨놓기
+- 반찬통 채워놓기
+
+### 반전/감동
+- 냉장고 메모 ("밥 먹었어. 고마워.")
+- 현관문 앞 놓인 반찬 봉지
+- 통장에 찍힌 이체 기록
+- 오래된 일기장 한 줄
+
+### 시간의 흐름
+- 달력의 X표시
+- 닳은 슬리퍼
+- 색 바랜 커튼
+- 벽시계의 째깍소리