프로젝트 소개
reelbench-skills는 영상 작업을 위한 Claude Code 및 Codex skill 모음입니다. 현재 프로젝트에는 완성본 분석과 장면 전환에 맞춰 콘티 정보를 동기화하는 영상 제작에 각각 사용되는 video-shots와 video-sync가 포함되어 있습니다.
프로젝트에는 Node.js 18 이상, ffmpeg, ffprobe만 필요합니다. npm 의존성이나 별도의 API Key 설정이 필요하지 않으며, 현재 Claude Code 또는 Codex 세션의 사용량을 이용합니다.
두 가지 핵심 기능
video-shots: 장면별 완성본 분석
video-shots는 전체 영상을 장면별 분석표로 분해하고, 장면 길이, 샷 크기, 유형, 카메라 움직임, 화면 구성, 리듬 등의 정보를 기록합니다. 장면 전환 지점과 길이는 ffmpeg가 측정하고, 의미 이해가 필요한 내용은 모델이 판단합니다. 마지막으로 15개 품질 게이트를 통해 결과를 하나씩 점검합니다.
생성되는 보고서는 외부 의존성이 없는 단일 파일 인터랙티브 페이지로, 오프라인에서 더블 클릭해 열 수 있습니다. 페이지에는 내장 플레이어, 재생 동기화 하이라이트, 장면 클릭 이동, 장면 리듬 바, 검색, 필터, 정렬, 목록 및 카드 보기, 시작·끝 키프레임, 통계 분포, 등장인물, 품질 점검 기능이 포함됩니다.
좁은 화면의 기기에서도 장면표를 확인할 수 있어 다양한 화면 크기에서 분석 결과를 점검하기 편리합니다.
video-sync: 콘티 정보가 포함된 동기화 영상 합성
video-sync는 완성본과 콘티 정보를 하나의 영상 화면에 결합하는 데 사용됩니다. 영상의 장면이 전환되면 해당 정보도 함께 업데이트되고, 장면 목록은 자동으로 스크롤되며 현재 항목을 강조 표시합니다.
- 가로형 소재는 상하 배치 레이아웃을 사용할 수 있습니다.
- 세로형 소재는 좌우 병렬 배치 레이아웃을 사용할 수 있습니다.
- 레이아웃이 하나의 CSS 파일에 모여 있어 일괄 조정하기 쉽습니다.
설치 전 준비
시작하기 전에 시스템에 다음 도구가 설치되어 있는지 확인하세요.
- Node.js: 18 이상.
- ffmpeg: 영상 처리와 장면 전환 지점 측정에 사용합니다.
- ffprobe: 일반적으로 ffmpeg와 함께 설치되며, 미디어 정보를 읽는 데 사용합니다.
macOS 사용자는 Homebrew로 설치할 수 있습니다.
brew install node ffmpeg또한 Claude Code 또는 Codex 중 하나 이상을 설치해야 합니다. 설치 스크립트는 현재 환경을 확인하고, 이미 존재하는 해당 디렉터리에 skill을 연결합니다.
reelbench-skills 설치
복제 후 자동 설치
먼저 저장소를 복제한 다음 설치 스크립트를 실행합니다.
git clone https://github.com/eternityspring/reelbench-skills.git
cd reelbench-skills
./scripts/install.sh기본적으로 스크립트는 로컬 환경에 따라 skill을 ~/.claude/skills/ 및/또는 ~/.codex/skills/에 심볼릭 링크로 연결합니다.
설치 대상 선택
특정 도구에만 설치하려면 해당 옵션을 사용할 수 있습니다.
./scripts/install.sh --claude
./scripts/install.sh --codex첫 번째 명령은 Claude Code에만 설치하고, 두 번째 명령은 Codex에만 설치합니다.
하나의 skill만 설치
현재 완성본 분석 기능만 필요하다면 이름으로 설치할 수 있습니다.
./scripts/install.sh video-shots마찬가지로 실제 필요에 따라 저장소에서 제공하는 다른 skill을 선택할 수 있습니다.
심볼릭 링크를 사용하지 않는 방법
각 skill은 독립적으로 실행할 수 있으므로 대상 디렉터리에 직접 복사할 수도 있습니다.
cp -r skills/video-shots ~/.claude/skills/복사 방식은 간단하고 직접적이지만 저장소를 업데이트한 후 다시 복사해야 합니다. 심볼릭 링크를 사용하면 업데이트가 Claude Code 또는 Codex의 skill 디렉터리에 즉시 반영됩니다.
기본 사용 흐름
video-shots로 완성본 분석하기
video-shots가 현재 사용하는 Claude Code 또는 Codex에 설치되어 있는지 확인합니다.- 분석할 영상 파일을 준비합니다.
- 현재 세션에서
video-shots를 사용해 영상을 분석해 달라고 명확히 요청하고, 원하는 출력 언어를 지정합니다. - 작업이 완료되면 생성된 HTML 보고서를 먼저 열어 장면 분할, 키프레임, 품질 결과를 확인합니다.
- 후속 처리가 필요하면 JSON, Markdown 또는 움직임 곡선 데이터를 읽을 수 있습니다.
세션에서 다음과 같이 작업을 요청할 수 있습니다.
video-shots를 사용해 이 영상을 장면별로 분석하고, 장면 길이, 샷 크기, 유형, 카메라 움직임, 화면 구성 및 리듬을 분석한 뒤 품질 게이트를 점검해 주세요.저장소의 영어 광고 예제에서는 --lang en을 사용하며, 생성된 보고서도 영어로 작성됩니다. 영어 결과물이 필요하면 작업 요청에 언어를 명시하고 해당 옵션 설정을 참고하세요.
완성본 분석 결과 이해하기
저장소에서 제공하는 demo-report는 202.9초 길이의 AI 단편 영화 《啥是AI》에서 생성되었습니다. 예제에서는 53개 장면을 식별했으며, 평균 장면 길이는 3.83초, 분당 전환 횟수는 15.7회이고, 15개 품질 게이트를 모두 통과했습니다.
예제 디렉터리는 일반적인 결과물의 구성 방식을 보여줍니다.
demo-report/
├── shots-report.html
├── shots.json
├── shots.md
├── track.json
└── frames/shots-report.html: 더블 클릭해 바로 열 수 있는 단일 파일 인터랙티브 분석 보고서입니다.shots.json: 장면별 분석의 주요 데이터입니다.shots.md: Markdown 형식의 장면표입니다.track.json: 프레임별 차이로 계산한 움직임 곡선으로, 기계 측정의 근거로 사용됩니다.frames/: 각 장면의 시작·끝 키프레임입니다. 53개 장면 예제에는 총 106장의 이미지가 있습니다.
먼저 HTML 보고서에서 시각적으로 확인한 다음, 후속 자동화 요구에 따라 shots.json 또는 track.json을 사용하는 것이 좋습니다.
video-sync로 동기화 표시 영상 제작하기
- 완성본과 해당 콘티 정보를 준비합니다.
video-sync가 설치되어 있는지 확인합니다.- Claude Code 또는 Codex 세션에서 해당 skill을 사용해 영상을 합성해 달라고 요청합니다.
- 가로형 또는 세로형 소재에 따라 상하 배치나 좌우 병렬 배치를 선택합니다.
- 생성 후 장면 전환, 정보 업데이트, 목록 스크롤 및 하이라이트가 동기화되는지 확인합니다.
작업 요청은 다음과 같이 작성할 수 있습니다.
video-sync를 사용해 이 영상과 콘티 정보를 합성해 주세요. 장면이 전환될 때 정보를 동기화해 업데이트하고, 장면 목록이 자동으로 스크롤되며 현재 장면을 강조 표시하게 해 주세요.저장소 예제에는 30초 길이의 영어 광고 영상과 5개 장면의 콘티 정보를 합성한 결과가 포함되어 있으며, 출력 크기는 1280×1296입니다. 관련 파일은 demo-sync 예제 디렉터리에서 확인할 수 있습니다.
고급 팁
심볼릭 링크로 빠르게 업데이트하기
설치 스크립트로 심볼릭 링크를 만들었다면 저장소에서 다음 명령만 실행하면 됩니다.
git pull업데이트된 내용은 연결된 skill에 즉시 적용되므로 파일을 다시 복사할 필요가 없습니다. 프로젝트 버전을 지속적으로 따라갈 때 특히 유용한 방식입니다.
필요한 것만 설치해 환경 간섭 줄이기
Claude Code만 사용한다면 --claude를, Codex만 사용한다면 --codex를 추가하세요. 완성본 분석 작업만 처리한다면 video-shots만 설치해 skill 디렉터리를 간결하게 유지할 수도 있습니다.
기계 측정 근거를 우선 확인하기
분석 결과에 의문이 생기면 track.json의 프레임별 차이 움직임 곡선과 각 장면의 시작·끝 키프레임을 함께 확인할 수 있습니다. 프로젝트에서는 전환 지점과 장면 길이를 ffmpeg가 측정하도록 하여 정량화할 수 있는 부분과 모델이 판단하는 부분을 분리합니다.
보고서로 빠르게 재검토하기
영상을 재생하면서 현재 장면이 올바르게 강조 표시되는지 확인한 다음, 검색·필터·정렬 기능으로 특정 샷 크기, 유형 또는 인물을 찾을 수 있습니다. 장면을 클릭하면 해당 시점으로 이동하고, 키프레임을 클릭하면 큰 이미지로 볼 수 있습니다. 확인을 마친 뒤 품질 점검 영역이 모두 통과했는지도 확인하세요.
video-sync 레이아웃 조정하기
video-sync의 레이아웃은 하나의 CSS 파일에 모여 있습니다. 다양한 화면 비율에 맞춰야 할 때는 여러 곳의 스타일을 분산해서 수정할 필요 없이 가로형의 상하 배치나 세로형의 좌우 배치부터 조정하면 됩니다.
심볼릭 링크 제거하기
더 이상 이 skill이 필요하지 않다면 다음 명령을 실행할 수 있습니다.
./scripts/install.sh --uninstall이 명령은 설치 스크립트가 만든 심볼릭 링크를 제거합니다.
정리
reelbench-skills는 영상 분석과 콘티 동기화 표시 기능을 Claude Code 및 Codex에서 사용할 수 있는 skill로 제공합니다. video-shots를 사용하면 기계 측정 근거, 키프레임, 품질 점검이 포함된 인터랙티브 보고서를 얻을 수 있고, video-sync를 사용하면 장면 전환과 콘티 정보가 동기화되는 영상을 제작할 수 있습니다. 의존성이 적고 별도의 API Key가 필요하지 않으며, 심볼릭 링크 업데이트와 보고서 오프라인 확인을 지원하므로 검증 가능한 영상 분석 워크플로를 구축하기에 적합합니다.