Communitygithub.com

beatcut

사용자가 클립 폴더에서 음악 트랙의 비트에 맞춰 짧은 비디오를 자르거나, 비트 싱크 편집(shots.json)을 만들거나 수정하고, 클립의 시작/종료 지점과 비트 수를 선택하며, beatcut 명령줄 도구를 사용하여 ffmpeg로 드래프트 또는 최종 비디오를 렌더링할 때 사용합니다. 전체 워크플로우(프로젝트 초기화, 비트 감지, 로컬 선택기에서 샷 선택 또는 수동 편집, 확인, 드래프트 렌더링, 연락처 시트로 검사, 사용자 승인 후 최종 렌더링)를 다룹니다.

beatcut란 무엇인가요?

beatcut은 클립 폴더와 음악 파일을 입력받아 비트에 프레임 단위로 정확하게 맞춰 컷이 이루어지는 비디오를 생성하는 명령줄 도구입니다. 프로젝트 상태는 `project.json`(설정)과 `shots.json`(편집) 두 파일에 저장되며, Python으로 작성된 `beatcut.py` 스크립트를 통해 실행됩니다. 사용자는 프로젝트 초기화, 비트 감지, 로컬 웹 기반 선택기(또는 수동 편집)를 통한 샷 선택, 확인, 드래프트 렌더링, 연락처 시트로 결과 검토, 최종 사용자 승인 후 최종 렌더링 순서로 작업합니다. Claude Code, Cursor, Codex 등 AI 에이전트가 이 스킬을 통해 사용자와 협력하여 비트에 맞춘 편집을 만들고 수정할 수 있도록 설계되었으며, ffmpeg와 ffprobe가 PATH에 설치되어 있어야 합니다. 중요한 점은 드래프트 결과를 반드시 확인한 후에만 최종 렌더링을 진행해야 하며, 편집 내용을 직접 수정할 때는 `shots.json`의 규칙(예: 각 샷의 `clip`, `in`, `out`, `beats`)을 엄격히 준수해야 합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/faruk76150/beatcut/tree/main

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

beatcut은(는) 무엇을 하나요?

beatcut은 클립 폴더와 음악 파일을 입력받아 비트에 프레임 단위로 정확하게 맞춰 컷이 이루어지는 비디오를 생성합니다. 상태는 프로젝트 폴더의 두 파일, project.json(설정)과 shots.json(편집)에 저장됩니다. 명령줄 도구는 beatcut.py입니다.

경로

필요한 패키지가 설치된 Python으로 명령을 실행하세요(pip install -r requirements.txt; ffmpeg와 ffprobe는 PATH에 있어야 합니다). 이 스킬이 설치된 폴더를 저장소 폴더로 사용하세요:

python <skill folder>/beatcut.py <command> ...

아래에서 beatcut.py는 해당 전체 경로를 의미합니다. 클립과 프로젝트의 경로는 어디든 가능하며, 공백이 있으면 따옴표로 감싸주세요. 프로젝트는 항상 <clips folder>/beatcut입니다. init과 sheet를 제외한 모든 명령은 해당 프로젝트 폴더를 인자로 받습니다.

워크플로우

  1. 누락된 항목 확인: 클립 폴더, 음악 파일, 출력 해상도(기본값 1920x1080 드래프트, 3840x2160 최종; 1080x1920 같은 세로 크기도 가능).
  2. 초기화: beatcut.py init <clips folder> --music <music file>. created: <folder>를 출력하고 음악 파일을 프로젝트 폴더로 복사합니다. project.json already exists라고 출력되면 프로젝트가 이미 존재하는 것입니다. 기존 프로젝트를 사용하고 다시 초기화하지 마세요. 해상도, fill, fps, encoder, exclude_prefix 또는 커스텀 profiles를 변경해야 하면 project.json을 편집하세요(아래 규칙 참조).
  3. 비트 감지: beatcut.py beats <project>. period, t0, bpm을 출력하고 shots.json에 기록합니다. 감지는 일정한 템포를 가정하며 t0에서 수백 분의 1초 정도 오차가 있을 수 있습니다. fewer than 4 beats were detected와 함께 종료 코드 1로 종료되면 period와 t0을 직접 설정하세요(period = 60 / BPM; t0 = 첫 번째 비트의 초). 사용자에게 숫자를 알려주면 선택기에서 수정할 수 있습니다.
  4. 샷 선택, 두 가지 방법 중 하나:
    • 선택기(기본값). beatcut.py pick <project>를 백그라운드에서 실행합니다(중단될 때까지 블로킹; --no-open을 추가하지 않으면 브라우저를 엽니다; 기본 포트 8765, --port N으로 변경 가능). 사용자에게 출력된 URL(http://127.0.0.1:<port>/)과 페이지가 자동 저장된다는 점을 알려주세요. 사용자가 완료했다고 말할 때까지 기다린 후 서버를 중단(Ctrl+C 또는 백그라운드 프로세스 종료)하고 shots.json을 읽으세요. 선택기가 열려 있는 동안에는 shots.json을 편집하지 마세요: 페이지가 변경 사항을 덮어씁니다.
    • 수동 편집, 사용자가 편집을 만들라고 요청하거나 정확한 시간을 알려줄 때. 아래 규칙을 따른 후 check를 실행하세요.
  5. 확인: beatcut.py check <project>. 종료 코드 0과 ok: <n> shots, <s> s는 오류가 없음을 의미합니다; 경고(stderr)도 읽으세요. 렌더링 전에 모든 오류를 수정하세요.
  6. 드래프트: beatcut.py draft <project>. encoder: ..., segment i/n을 출력하고 마지막으로 out/<out_name>_draft.mp4의 경로를 출력합니다.
  7. 확인: beatcut.py sheet <video> --out <some .jpg path>는 5x4 연락처 시트를 작성합니다; 해당 이미지를 열고 결과를 사용자에게 설명하세요(샷 순서, 색상, 페이드, 검은 프레임, 잘못된 크롭). --out 경로는 클립 폴더 밖(예: 임시 폴더)을 선택하세요.
  8. 최종, 사용자의 승인 후에만: 드래프트를 보여준 후 최종 렌더링 여부를 물어보세요. 명확한 예라고 답한 후에만 beatcut.py final <project>를 실행하세요. 최종 렌더링은 더 느리고 결과물이 더 큽니다. 출력 경로를 알려주세요.

이후 사용자가 편집을 변경하면 4단계로 돌아가세요. 렌더링은 캐시된 세그먼트를 재사용하므로 두 번째 드래프트는 더 빠릅니다.

shots.json 수동 편집

파일을 유효한 JSON(UTF-8)으로 유지하세요. check는 모든 규칙 위반을 보고합니다.

최상위:

  • version: 1. period: 숫자, 0.05 초과 10 미만. t0: 숫자, 0 이상. tail: 0 ~ 30 (기본값 1.5). shots: 리스트, 최대 2000개.
  • 선택 사항: bad (클립 이름을 `{

관련 스킬