씬첩 | 영상 하나가 장면별 콘택트 시트가 됩니다

가편집본을 리뷰에 넘기기 전에 "몇 컷짜리 영상인지", "어디서 몇 초짜리 장면이
나오는지"를 정리해야 하는데, 영상을 처음부터 끝까지 돌려보며 손으로 타임코드를
받아 적어본 적이 있다면 그 지루함을 압니다. 프리미어·다빈치를 열어 마커를
하나씩 찍는 것도 결국 같은 작업의 반복입니다. 씬첩은 이 작업을 스크립트
다섯 개로 줄입니다. ffmpeg가 컷 경계를 찾고, 대표 프레임을 뽑고, 인쇄 가능한
콘택트 시트와 리뷰용 코멘트 칸 버전, 장면 목록, 컷 리듬 차트까지 한 번에
만듭니다.

파이프라인

1. 장면전환 검출: ffmpeg select='gt(scene,T)' + showinfo 로 컷
   경계를 찾습니다. threshold를 0.10~0.60으로 스윕해 컷 개수가 안정적으로
   유지되는 구간을 표로 보여주고, 너무 짧아지는 경계는 인접 장면에 병합해
   내부 모션이 격렬한 장면(빠른 줌, 글리치 등)에서 생기는 오탐을 걸러냅니다.
2. 대표 프레임 추출: 각 장면의 중간 지점에서 정지 프레임을 뽑습니다.
3. 콘택트 시트: A4 가로(150dpi) 레이아웃에 장면 번호·타임코드·길이
   배지를 붙인 카드를 격자로 배치합니다. 한 페이지에 안 들어가면 자동으로
   페이지를 나누고, 모든 페이지를 묶은 PDF도 같이 만듭니다. 카드마다 빈
   코멘트 칸(밑줄 3줄)이 붙은 리뷰용 버전도 별도로 만듭니다.
4. 장면 목록: 시작·끝·길이를 CSV(엑셀 호환)와 Markdown 표로 정리합니다.
5. 컷 리듬 차트: 장면 길이를 막대그래프로 그리고 평균 컷 길이를 점선으로
   표시합니다. 평균·중앙값·최소·최대·표준편차 통계도 같이 나옵니다.

실제 명령

uv run scripts/detect.py --input video.mp4 --out out/scenes.json \
  --threshold 0.27 --min-scene 1.0
uv run scripts/frames.py --scenes out/scenes.json --out-dir out/frames
uv run scripts/sheet.py --scenes out/scenes.json \
  --out-prefix out/contact_sheet --variant plain
uv run scripts/sheet.py --scenes out/scenes.json \
  --out-prefix out/contact_sheet_review --variant review
uv run scripts/list.py --scenes out/scenes.json \
  --out-csv out/scenes.csv --out-md out/scenes.md
uv run scripts/rhythm.py --scenes out/scenes.json --out out/rhythm_chart.png

35초짜리 샘플 영상 기준 전체 파이프라인(threshold 스윕 포함)이 7초가 채
걸리지 않았습니다. 아래는 위 명령을 그대로 돌린 실제 결과입니다.

포함 구성

사용 예시 3개

1. 가편집본 리뷰 준비: 15분짜리 가편집본을 넣고 콘택트 시트 리뷰용
   버전을 뽑아 관계자에게 공유합니다. 각자 카드 밑 코멘트 칸에 의견을 적어
   돌려주면 어느 장면 얘기인지 다시 설명할 필요가 없습니다.
2. 브이로그 컷 수 점검: 최근 업로드한 영상들의 평균 컷 길이가 점점
   길어지는 것 같다는 감이 들 때, 컷 리듬 차트로 실제 평균·표준편차를
   확인하고 편집 리듬을 조정합니다.
3. 소재 정리: 촬영본이 여러 장면으로 섞여 있을 때 장면 목록 CSV를
   뽑아 어느 구간에 뭐가 있는지 표로 훑어보고, 쓸 장면만 타임코드로 골라
   가편집 순서를 짭니다.

필요한 준비물

• ffmpeg(Homebrew 등)와 uv가 설치돼 있어야 합니다.
• 한글이 들어간 OS 폰트가 필요합니다: macOS/Windows/Linux 주요 배포판은
  자동으로 찾지만, 못 찾으면 --font로 TTF/TTC 경로를 직접 넘겨야 합니다.
• 장면전환 검출은 하드컷(순간 전환) 위주로 정확합니다. 크로스페이드나
  디졸브처럼 점진적으로 바뀌는 전환은 경계가 흐릿해서 threshold를 조정해도
  놓치거나 애매하게 잡힐 수 있습니다. 이런 편집물은 콘택트 시트를 직접 보고
  검수하는 걸 권합니다.
• 정확도 실측(정답 10장면 대비 precision/recall 100%, 경계 오차 0ms)은
  재인코딩 없는 하드컷 샘플 기준입니다. 실제 촬영본을 재인코딩해서 넘기면
  인코더 구조 때문에 최대 1프레임(24fps 기준 약 42ms) 정도 오차가 생길 수
  있습니다.
• 정답 장면 수를 모르는 실전 상황에서는 --auto 스윕 표를 보고 threshold를
  직접 판단해야 합니다. 자동으로 "찍어주지" 않습니다.

추천

• 가편집본을 정기적으로 리뷰에 돌리는 1인 편집자나 소규모 팀
• 컷 편집 리듬(평균 컷 길이, 분포)을 데이터로 확인하고 싶은 채널 운영자
• 촬영 소재가 많아 장면별로 타임코드를 정리해야 하는 작업

비추천

• 크로스페이드·디졸브 위주로 편집된 영상의 정밀한 장면 분할: 하드컷 기준
  도구라 점진적 전환에서는 정확도가 떨어집니다.
• 실시간 편집 중 프리뷰가 필요한 용도: 이 스킬은 완성본(또는 가편집본)을
  넣고 한 번에 정리하는 배치 작업입니다.

FAQ

Q1. threshold를 얼마로 잡아야 할지 모르겠습니다.
--auto 옵션으로 스윕 표를 먼저 봅니다. 컷 개수가 안정적으로 유지되는
구간(예: 0.25~0.40에서 계속 9개)을 찾으면 그 구간 안에서 고르면 됩니다.
guides/threshold-tuning.md에 영상 종류별 출발점 표를 정리해뒀습니다.

Q2. 화면이 빠르게 움직이는 장면(줌, 카메라 워크)에서 오탐이 생기지
않나요?
생길 수 있습니다. 실제로 이 카드의 E2E 테스트에서 빠른 확대 장면 안에서
80ms 차이로 가짜 컷이 하나 더 잡히는 걸 확인했습니다. 다만 기본값
--min-scene 1.0이 이렇게 너무 짧아지는 경계를 자동으로 인접 장면에
합쳐서, 최종 결과에서는 오탐 없이 정답과 정확히 일치했습니다(E2E.md 참고).

Q3. 장면 수가 아주 많으면 콘택트 시트가 어떻게 되나요?
자동으로 페이지를 나눕니다. 내부적으로 30장면짜리 시트로 별도 테스트한
결과 3페이지로 정확히 나뉘었고, 모든 페이지를 묶은 PDF도 같이 생성됩니다.

Q4. 코멘트 칸 버전과 일반 버전을 둘 다 매번 만들어야 하나요?
아닙니다. sheet.py를 --variant plain 또는 --variant review로 원하는
것만 골라 실행할 수 있습니다. 둘 다 필요하면 두 번 실행하면 됩니다.

Q5. 이 스킬이 영상이나 얼굴을 새로 만들어내나요?
아닙니다. 원본 영상에서 프레임을 그대로 잘라 타임코드·번호와 함께 배치할
뿐이며, 얼굴이나 장면을 합성·생성하지 않습니다.

구매 안내

다운로드 후 package/ 폴더를 그대로 프로젝트에 두고
uv run package/scripts/detect.py ...로 시작하면 됩니다. 별도 설치나 API
키 등록은 필요 없습니다. ffmpeg와 uv만 준비하면 됩니다.

예시 이미지는 Blender Foundation 의 오픈 무비 Big Buck Bunny(CC BY 3.0, bigbuckbunny.org) 예고편으로 실제로 돌린 결과입니다.