04-shorts-asset-extractor

name	04-shorts-asset-extractor
description	영상 분석 결과에서 필요한 에셋 목록을 5개 카테고리로 구조화 추출. Use when "에셋 추출", "asset extraction", "에셋 목록", "뭐가 필요해", "필요한 에셋", "asset list".

Shorts Asset Extractor

Reads 01-shorts-analyzer Phase 3~4 outputs and extracts all assets needed for Remotion reproduction into 5 categories under {videoId}/04-needed-assets/.

The Insight

Video analysis and Remotion implementation require an asset preparation step between them. Systematically extracting backgrounds/graphics/SFX/VO/BGM from the 01-analysis.md Scene tree prevents missing assets during implementation.

Recognition Pattern

Use this skill when:

• Video analysis is complete and an asset list is needed
• Identifying required resources before Remotion reproduction
• Answering "what does this video need?"
• Pre-asset-preparation step before shorts-recreator

Input

File	Required	Purpose
{videoId}/01-analysis.md	Required	Scene tree → extract 배경/그래픽/SFX/텍스트
{videoId}/01-audio.json	Recommended	Whisper STT segments → VO timestamps
{videoId}/01-audio-demucs/demucs-result.json	Recommended	BPM/악기/장르 + RMS cross-validation

Output

{videoId}/04-needed-assets/ — 5 category files + background frame directory

{videoId}/04-needed-assets/
├── backgrounds.md          # 배경 목록 + 프레임 범위 + 디렉토리 경로
├── backgrounds/            # Scene별 배경 프레임 (심볼릭 링크)
│   ├── scene_1.1/          # frame_NNNN.jpg → ../../frames/frame_NNNN.jpg
│   ├── scene_2.1/
│   └── ...
├── extract-backgrounds.sh  # 배경 프레임 추출 스크립트 (재실행 가능)
├── vo.md                   # 나레이션 segment
├── bgm.md                  # BGM 구간
├── sfx.md                  # SFX 피크
└── graphics.md             # 그래픽 에셋

Step 1: Validate Input

Check that required files exist.

Required:
- {videoId}/01-analysis.md

Missing → error: "01-shorts-analyzer를 먼저 실행하세요."

Checklist

• {videoId}/01-analysis.md exists
• {videoId}/01-audio.json checked (if absent, mark VO section "01-audio.json 없음 — 수동 확인 필요")
• {videoId}/01-audio-demucs/demucs-result.json checked (if absent, mark BGM "dB 수동 계산 필요")

Step 2: Parse 01-analysis.md — Extract Assets per Scene

Read 01-analysis.md and extract from each Scene:

Per Scene N.N block:
├── 배경: → create backgrounds table row
│   └── effect: → record camera movement
├── 텍스트: → (handled in data.ts — skip here)
├── 그래픽: → create graphics asset table row + **카테고리 분류**
│   ├── 카테고리: graphics/ Source 폴더 매핑 (emoji, meme, icon, logo, effect, flag, photo)
│   ├── 코드 구현 에셋(글로우, 카드, 차트, 파티클, 카운터) → "code" (폴더 없음)
│   └── sfx: → cross-reference with SFX table
├── 오디오: → collect VO/BGM info
│   ├── VO: → record in narration table
│   └── BGM: → record in BGM table

Per Transition block:
└── sfx: → create SFX table row

Parallel processing recommended: For long 01-analysis.md files, parse by Act in parallel.

Transition handling: Transitions are code effects, not assets — exclude from backgrounds table. However, Transition sfx goes in the SFX table.

Checklist

• All Scene background sections parsed
• All Scene graphics sections parsed
• 모든 그래픽에 카테고리 매핑 완료 (emoji/meme/icon/logo/effect/flag/photo/code)
• All Scene audio (VO/BGM) sections parsed
• All Transition SFX parsed
• Row counts recorded (backgrounds N, graphics N, SFX N)

Step 3: SFX Category Classification

Classify SFX from Step 2 into Mixkit MECE categories:

1. 카테고리 분류: 시각 이벤트 설명 기반으로 Mixkit MECE 카테고리 매핑 ({category} > {sub})
   • 폭발/전쟁 → Warfare > Explosion, 전환/줌 → Transition > Whoosh, 임팩트 → Transition > Impact 등
   • sfx/{category}/{sub}/ 폴더 구조와 1:1 대응
2. 주요 임팩트 표기: delta dB ≥ 15 → ★ 표기

Checklist

• 모든 SFX에 Mixkit 카테고리 매핑 완료 ({category} > {sub} 형식)
• delta 15dB+ SFX에 ★ 표기

Step 4: BGM Extraction from demucs-result.json

Extract BGM info directly from demucs-result.json (no 001-story-analysis.md dependency):

1. 트랙 특성: summary.bpm, summary.genres, summary.instruments 추출
2. 카테고리 분류: PANNs 장르를 뮤팟 음악장르 19개 중 하나로 매핑
   • bgm/{음악장르}/ 폴더 구조와 1:1 대응
   • 뮤팟 음악장르: 피아노, 클래식, 일렉트로닉, 팝, 힙합, 컨트리, 펑크, 인디, 포크 및 어쿠스틱, R&B, 재즈, 라틴, Lo-Fi, 레트로, 시네마틱, 블루스, 록, 하우스, 얼터너티브
   • ⚠️ PANNs 장르 1순위를 맹신하지 말 것 — other 트랙에 VO 잔여 신호가 남아 장르가 왜곡될 수 있음. 01-analysis.md의 BGM 분위기 설명을 우선 고려하여 판단
3. 구간별 분위기: 01-analysis.md Scene별 BGM: 라인에서 분위기 키워드 추출, Act 전환 기준으로 구간 분리
4. BGM dB 자동 계산 — SFX peak masking + percentile:
   • sfx_peaks[].frame ±30프레임(~0.5초) 마스킹 → SFX 영향 제거
   • bgm.md 구간별 시간 범위 → 프레임 범위 변환 (frame = time × fps)
   • 마스킹 후 남은 프레임의 25th~75th percentile → dB 범위로 기재

   sfx_frames = {p['frame'] for p in sfx_peaks}
   masked = set()
   for f in sfx_frames:
       masked.update(range(f - 30, f + 31))
   bgm_only = [db for i, db in enumerate(other[start:end]) if (start+i) not in masked]
   p25, p75 = percentile(bgm_only, [25, 75])
   

Checklist

• BGM 트랙 특성 (BPM/장르/악기) 추출 완료
• BGM 트랙 특성에 뮤팟 음악장르 카테고리 매핑 완료
• BGM 구간별 dB 범위가 rms_per_frame.other[]에서 계산되어 채워짐 (명시 없음 금지)

Step 6: Scene-Based VO Mapping

Core principle: VO units are Scenes, not 01-audio.json segments. If one segment spans multiple Scenes, split by Scene.

1. Extract VO text and time range per Scene from 01-analysis.md
2. If 01-audio.json exists, refine with exact start/end times
3. If 01-audio.json absent, extract text only (time → "수동 확인 필요")
4. 말속도 계산: 전체 텍스트 글자수 ÷ VO 총 시간(초) = N 글자/초
5. 콘텐츠 성격 판별: 정보 전달형 (팩트 나열, 빠른 템포) / 감성 호소형 (빌드업, 감정 곡선) / 혼합형

채널 레벨 템포 범위 + 영상 레벨 미세 조절: references/asset-categories.md § VO Notes

Checklist

• All Scene VO separated by Scene unit
• Segments spanning multiple Scenes split per Scene
• VO row count = Scene count (approximate)
• 말속도 계산 완료 (N 글자/초)
• 콘텐츠 성격 판별 완료

Step 7: Generate 04-needed-assets/

Create {videoId}/04-needed-assets/ with 5 files + backgrounds/ directory.

Output format details: references/output-templates.md

Key files: extract-backgrounds.sh, backgrounds.md, vo.md, bgm.md, sfx.md, graphics.md

Checklist

• 5 files + extract-backgrounds.sh + backgrounds/ directory created
• All Scenes appear in at least one file
• Each file header includes videoId
• Row counts: backgrounds N, VO N, BGM N, SFX N, graphics N
• backgrounds.md row count = 01-analysis.md Scene count (merged consecutive same-background Scenes allowed)
• backgrounds/ subdirectory count matches backgrounds.md row count
• After running extract-backgrounds.sh, each Scene directory has frame symlinks

Step 8: Verify

• Scene coverage: Every Scene number from 01-analysis.md appears somewhere in 04-needed-assets/
• Background row count = Scene count: backgrounds.md rows match 01-analysis.md Scene count (merged groups ≤ Scene count)
• Background directory match: backgrounds/ subdirectory count = backgrounds.md row count
• Frame existence: Spot-check symlinks exist in each Scene directory
• SFX completeness: 01-analysis.md Scene/Transition SFX 수 = sfx.md SFX row count
• VO completeness: vo.md row count ≈ Scene count, 시간 범위 누락 없음
• BGM completeness: bgm.md에 BPM, 악기 힌트, 장르, 구간별 분위기/dB 포함 (소스: demucs-result.json + 01-analysis.md)
• Graphics completeness: 01-analysis.md 그래픽 에셋 수 = graphics.md row count

Checklist

• Scene coverage 100%
• backgrounds.md row count = Scene count (or merged group count)
• backgrounds/ directory count = backgrounds.md row count
• Frame symlinks confirmed (1 sample per directory)
• No SFX peaks missing
• vo.md row count ≈ Scene count
• bgm.md에 BPM/악기/장르/구간별 분위기 포함
• graphics.md row count = 01-analysis.md 그래픽 에셋 수
• 카테고리 매핑 완료: SFX (Mixkit), BGM (뮤팟 음악장르), Graphics (Source 폴더)

소싱 방법은 05-shorts-asset-sourcer 스킬 참조