| name | video-motion-analysis |
| description | YouTube URL 또는 로컬 영상 파일을 받아 구간별 프레임을 추출하고, 노래·춤·연주
등 인물의 동작과 안무를 시퀀스 단위로 분석하는 스킬. yt-dlp로 영상을 받고
ffmpeg로 타임스탬프가 박힌 콘택트 시트(타일 몽타주)를 만들어, 한 장의 이미지에서
여러 프레임의 자세 변화를 한눈에 읽어낸다. 스프라이트/애니메이션 키프레임 참고에 적합.
다음 상황에서 반드시 이 스킬을 사용할 것:
- "이 유튜브 영상 분석해줘", "유튜브 구간별 프레임 분석", "영상 동작 분석해줘"
- "이 영상에서 노래부르는 사람 동작 분석", "가수 제스처 분석해줘"
- "춤/안무 동작 분석", "댄스 프레임 분석", "이 영상 안무 따줘"
- "연주자 동작 분석", "퍼포먼스 동작 시퀀스 분석"
- "영상에서 캐릭터 동작을 스프라이트/애니메이션 키프레임으로 뽑아줘"
- YouTube URL 또는 로컬 mp4/webm 파일과 함께 "동작/움직임/포즈/제스처" 분석 요청
- "영상 프레임 추출해줘", "콘택트 시트 만들어줘", "영상 타임라인 분석"
|
| allowed-tools | Bash, PowerShell, Read, Glob, Write, Agent |
Video Motion Analysis — 영상 동작/안무 분석 스킬
YouTube URL이나 로컬 영상에서 인물의 동작·안무·제스처를 구간별 프레임 시퀀스로
분석한다. 핵심 아이디어: 영상을 직접 "볼" 수는 없으므로, 일정 간격으로 프레임을
뽑아 타임스탬프가 박힌 타일 콘택트 시트 한 장으로 합친 뒤 그 이미지를 읽는다.
한 번에 수십 프레임의 자세 변화를 비교할 수 있어 토큰 효율이 높고, 동작의 흐름
(포즈 → 전환 → 클라이맥스)을 놓치지 않는다.
번들 스크립트 scripts/vframes.py가 다운로드·프레임 추출·몽타주를 모두 처리한다.
ffmpeg 필터를 매번 새로 짜지 말고 이 스크립트를 쓴다 — 폰트/도구 경로 탐색,
타임코드 오버레이, Windows 콘솔 인코딩까지 이미 해결돼 있다.
사전 요구
- ffmpeg / ffprobe: 프레임 추출·메타 조회에 필수.
- yt-dlp: YouTube 등 URL 입력에만 필요(로컬 파일은 불필요).
없으면
pip install -U yt-dlp로 설치. 스크립트가 PATH·pip Scripts·python -m yt_dlp 순으로 자동 탐색한다.
도구가 없으면 스크립트가 명확한 한글 에러로 안내하므로, 먼저 실행해보고 실패 시
설치한다.
워크플로우 (3단계)
스크립트는 prepare → overview → montage 순으로 점진적으로 좁혀간다.
호출 형식(파이썬 인터프리터는 환경에 맞게):
python <skill>/scripts/vframes.py <subcommand> ...
1단계 — prepare: 영상 확보 + 메타 파악
URL이면 받고(기본 480p — 동작 분석엔 충분), 로컬 파일이면 그대로 쓴다.
길이·해상도·fps를 읽어 meta.json과 콘솔 요약을 남긴다.
python vframes.py prepare --source "<URL 또는 로컬경로>" --outdir <작업폴더>
- 작업 폴더는
image/video-analysis/<videoId 또는 이름>/ 컨벤션을 따른다.
- 길이를 보고 구간 전략을 세운다(3분이면 overview 5초 간격이면 충분).
2단계 — overview: 전체 흐름 파악
영상 전체를 그리드 칸 수에 맞춰 자동 간격으로 한 장에 담는다. 이걸 읽고
인물이 등장하는 구간, 카메라가 클로즈업되는 구간, 동작이 큰 구간을 식별한다.
python vframes.py overview --video <영상> --outdir <작업폴더> --grid 6x8
overview를 Read 툴로 직접 본 뒤, 어디를 더 촘촘히 볼지 정한다. 동작 분석의
핵심은 보통 인물 클로즈업/미디엄 샷 구간이다.
3단계 — montage: 핵심 구간 정밀 추출
식별한 구간을 짧은 간격으로 다시 뽑는다. 간격(step) 가이드:
| 목적 | step | 비고 |
|---|
| 구간 식별/전체 흐름 | 5s (overview) | 어떤 동작이 어디 있는지 |
| 동작 흐름 파악 | 1s | 프레이즈 단위 변화 |
| 정밀 동작 시퀀스 | 0.5s | 자세 전환·키프레임 추출 |
| 빠른 안무/타격 동작 | 0.2~0.3s | 손/발 빠른 움직임 |
python vframes.py montage --video <영상> --outdir <작업폴더> \
--start 47 --end 56 --step 0.5 --grid 5x6 --name fine_47-56
--grid colsxrows: 구간 프레임 수 ≤ 그리드 용량이 되게 잡는다(초과 시 스크립트가
경고한다). 예: 9초 구간 / 0.5s = 19프레임 → 5x6(=30) 그리드면 여유.--name: 의미 있는 이름(fine_47-56, chorus_1m20)으로 저장해 나중에 구분.--width: 타일 한 칸 가로 px(기본 400). 클로즈업 정밀 분석은 키우고, 넓은 개관은
줄여 한 장에 더 많이 담는다.
각 몽타주는 Read 툴로 보고 분석한다. 좌상단 노란 타임코드(HH:MM:SS.mmm)로 각
프레임의 정확한 시점을 참조할 수 있다.
동작 분석 작성법
동작/안무 특화 스킬이므로, 단순 장면 묘사가 아니라 움직임의 문법을 추출한다.
산출 구조:
# 🎬 [영상 제목] 동작 분석
## 영상 개요
- 출처 / 길이 / 해상도 / 인물·구성
## 구간별 타임라인 (표)
| 구간 | 카메라 | 동작 |
## 핵심 동작 시퀀스 (0.5s 단위)
- 타임코드별 자세 전환 서술 (도입 → 전개 → 클라이맥스)
## 동작 어휘 정리 (애니메이션/스프라이트 참고용)
1. 베이스 포즈 (전 구간 유지되는 기본 자세)
2. 반복 모션 (스웨이/스텝/제스처)
3. 강조 모션 (클라이맥스 — 팔 거상, 챈 업 등)
4. 전환 패턴
분석 시 주목할 요소:
- 베이스 포즈: 마이크 홀드, 스탠스 등 계속 유지되는 기준 자세.
- 반복 주기: 머리 스웨이, 스텝, 박자 제스처 — 몇 프레임 주기로 반복되는가.
- 강조/클라이맥스: 턱 들기, 양팔 거상, 점프 등 감정 정점의 큰 동작.
- 전환: 포즈 A에서 B로 넘어가는 중간 프레임(애니메이션 인비트윈 후보).
- 신체 부위별 분해: 머리·상체·팔·손·하체를 따로 추적하면 키프레임화가 쉽다.
스프라이트/애니메이션 키프레임이 목적이면, 시퀀스에서 대표 포즈 4~8개를 골라
루프 구성(예: 베이스 → 스웨이L → 베이스 → 스웨이R)을 제안한다. 후속으로 Case S
(스프라이트 시트) 워크플로우와 연결할 수 있다.
출력물 컨벤션
image/video-analysis/<id>/
├── video.<ext> # 원본 (URL 입력 시)
├── meta.json # 길이/해상도/fps/경로
├── overview.png # 전체 개관
├── dense_<구간>.png # 1s 간격
└── fine_<구간>.png # 0.5s 이하 정밀
분석 텍스트는 대화에 직접 출력하고, 산출물 경로를 함께 안내한다.
팁 & 함정
- 직접 영상을 못 본다: 반드시 몽타주를 만들어 Read로 확인한다. 추측 금지.
- 그리드 초과: 구간이 길고 step이 작으면 프레임이 그리드 용량을 넘어 잘린다.
스크립트 경고를 보고 구간을 쪼개거나 그리드를 키운다.
- 점진적 좁히기: 처음부터 0.2s로 전체를 뽑지 말 것 — overview로 구간을 찾은 뒤
그 구간만 정밀 추출하는 게 빠르고 싸다.
- 해상도: 동작 분석엔 480p로 충분. 자막/표정 디테일이 필요하면
--height 720.
- 빠른 동작: 타격·턴 등은 0.2~0.3s로 잡아야 모션 블러 사이의 키포즈가 잡힌다.
- 여러 인물: 화면에 여러 명이면 누구를 추적할지 먼저 정하고, 그 인물이 크게
잡히는 구간을 골라 정밀 추출한다.
