snip — 동영상 자르기 및 재배열
동영상을 여러 세그먼트로 자르고, 순서를 재배열한 후 지정된 프레임율로 내보냅니다. 하이라이트 영상 제작, 장면 재구성, 영상 속도 변경에 유용합니다.
이 스킬 디렉터리(SKILL.md가 있는 곳)를 아래에서는 $SKILL_DIR로 표시합니다.
사용 시기
다음과 같은 경우에 이 스킬을 사용하세요:
- 동영상을 특정 세그먼트로 자르기
- 동영상 세그먼트를 다른 순서로 재배열하기
- 원하지 않는 구간 제거하기
- 출력 프레임율(초당 컷 수) 변경하기
- 음성 구간 자동 감지로 자연스러운 컷 생성 (우선)
- 장면 전환 자동 감지로 대체 (폴백)
설정 (최초 1회)
cd "$SKILL_DIR" && uv sync
에이전트 워크플로우
1. 사용자에게 질문
동영상을 자르기 전에 다음 정보가 필요합니다:
📹 소스 동영상
동영상 파일과 위치를 알려주세요
✂️ 자를 세그먼트
각 세그먼트에 대해 다음을 지정하세요:
- source: 파일명
- start: 시작 시간(초) (예: 0.0, 5.5)
- end: 종료 시간(초) (예: 2.0, 10.0)
세그먼트 예시:
[
{"source": "video.mp4", "start": 0.0, "end": 1.0},
{"source": "video.mp4", "start": 3.0, "end": 4.5},
{"source": "video.mp4", "start": 1.5, "end": 2.5}
]
🎬 출력 FPS (선택 사항)
기본값: 30 fps
일반적인 옵션: 24, 30, 60
📁 입력/출력 디렉터리 (기본값: ./input 및 ./output)
사용자 응답을 기다린 후 진행하세요.
2. 자르기 전략 결정
우선 순위:
- 명시적 세그먼트 — 사용자가 특정 시작/종료 시간을 제공하면 그대로 사용
- 오디오 전사 —
transcription.enabled: true(기본값)인 경우, 전사 데이터를 찾거나 생성하여 음성 구간 경계에서 자름 - 적응형 장면 감지 — 전사가 불가능하거나 실패할 경우 대체
오디오 전사 (기본 방식)
이 스킬은 먼저 오디오 전사를 통해 동영상에서 타임스탬프가 포함된 음성 구간을 얻으려고 시도합니다. 이렇게 하면 음성 콘텐츠에 맞춰 더 자연스러운 컷이 생성됩니다.
🤖 오디오 전사 모드 (우선)
커터는 다음을 수행합니다:
1. output_dir에 기존 전사 JSON(예: video_transcription.json)이 있는지 확인
2. 없으면 자동으로 오디오 전사 실행
3. 음성 구간 경계에서 동영상 자름
⚙️ 설정:
- transcription.enabled: true (기본값)
- fallback_to_adaptive: true (기본값) — 전사 실패 시 장면 감지 사용
- min_segment_duration: 세그먼트 최소 시간(초) (기본값: 1.0)
- max_segment_duration: 세그먼트 최대 시간(초) (기본값: 30.0)
설정 예시:
{
"segments": [{"source": "video.mp4", "start": 0, "end": 60}],
"transcription": {
"enabled": true,
"fallback_to_adaptive": true,
"min_segment_duration": 1.0,
"max_segment_duration": 30.0
}
}
적응형 장면 감지 (대체)
전사가 비활성화되거나 실패하면, 시각적 장면 감지로 대체됩니다:
🎬 적응형 장면 감지 (대체)
동영상에서 장면 전환을 자동으로 감지하여 컷을 만듭니다.
자연스러운 전환 지점에서 잘라 지루하거나 반복적인 콘텐츠를 피합니다.
⚙️ 감지 모드:
- adaptive — 조명 변화/점진적 변화에 적합 [기본값]
- content — 빠르고 명확한 장면 컷에 적합
- threshold — 페이드 인/아웃 감지에 적합
📏 장면 길이 필터:
- min_scene_duration: 장면 최소 시간(초) (기본값: 1.0)
- max_scene_duration: 장면 최대 시간(초) (기본값: 10.0)
🎛️ 고급 설정 (선택 사항):
- threshold: content 모드의 픽셀 차이 임계값 (기본값: 27.0)
- adaptive_threshold: adaptive 모드의 비율 임계값 (기본값: 3.0)
- window_width: 평균 낼 프레임 수 (기본값: 2)
- min_scene_len: 컷 전 최소 프레임 수 (기본값: 15)
- min_content_val: 최소 콘텐츠 변화량 (기본값: 15.0)
자동 감지 대체 설정 예시:
{
"segments": [{"source": "video.mp4", "start": 0, "end": 60}],
"transcription": {
"enabled": false
},
"auto_detect": {
"enabled": true,
"mode": "adaptive",
"min_scene_duration": 1.0,
"max_scene_duration": 10.0
}
}
3. config.json 편집
사용자의 선택에 따라 $SKILL_DIR/config.json을 작성하거나 업데이트합니다.
4. 실행
cd "$SKILL_DIR" && uv run python scripts/cutter.py --config config.json
5. 결과 보고
사용자에게 출력 파일 경로, 길이 및 FPS를 알려줍니다. 사용된 방식(전사 기반 또는 장면 감지)을 함께 언급합니다.
설정 참고
| 키 | 값 | 기본값 | 설명 |
|---|---|---|---|
input_dir | 경로 | ./input | 입력 동영상이 있는 폴더 |
output_dir | 경로 | ./output | 출력 대상 폴더 |
segments | 배열 | (필수) | 세그먼트 정의 목록 |
output_fps | 정수 | 30 | 출력 프레임율 |
세그먼트 정의
| 키 | 타입 | 설명 |
|---|---|---|
source | 문자열 | input_dir 내 파일명 |
start | 실수 | 시작 시간(초) |
end | 실수 | 종료 시간(초) |
전사 (우선 방식)
| 키 | 값 | 기본값 | 설명 |
|---|---|---|---|
enabled | 불리언 | true | 전사 기반 자르기 활성화 |
fallback_to_adaptive | 불리언 | true | 전사 실패 시 장면 감지 사용 |
min_segment_duration | 실수 | 1.0 | 이 값보다 짧은 세그먼트 건너뜀 (초) |
max_segment_duration | 실수 | 30.0 | 이 값보다 긴 세그먼트 건너뜀 (초) |
자동 감지 (대체)
| 키 | 값 | 기본값 | 설명 |
|---|---|---|---|
enabled | 불리언 | false | 자동 장면 감지 활성화 (대체 전용) |
mode | adaptive, content, threshold | adaptive | 감지 알고리즘 |
min_scene_duration | 실수 | 1.0 | 이 값보다 짧은 장면 건너뜀 (초) |
max_scene_duration | 실수 | 10.0 | 이 값보다 긴 장면 건너뜀 (초) |
threshold | 실수 | 27.0 | content/threshold 모드의 픽셀 차이 임계값 |
adaptive_threshold | 실수 | 3.0 | adaptive 모드의 비율 임계값 |
window_width | 정수 | 2 | 전후 평균 프레임 수 |
min_scene_len | 정수 | 15 | 컷 전 최소 프레임 수 |
min_content_val | 실수 | 15.0 | 최소 콘텐츠 변화량 |
감지 모드 (대체)
- adaptive (기본값): 조명 변화나 점진적 전환이 있는 동영상에 적합
- content: 날카롭고 명확한 장면 컷에 적합
- threshold: 페이드 인/아웃 전환 감지에 적합
일반적인 실행법
# 기본 설정 (전사 사용 가능 시 사용, 실패 시 adaptive로 대체)
cd "$SKILL_DIR" && uv run python scripts/cutter.py --config config.json
# 적응형 장면 감지 강제 사용 (전사 건너뜀)
cd "$SKILL_DIR" && uv run python scripts/cutter.py --config config.json --no-transcription
# 사용자 지정 디렉터리
cd "$SKILL_DIR" && uv run python scripts/cutter.py \
--input /path/to/videos --output /path/to/output
출력
각 설정은 output_dir에 output.mp4 파일 하나를 생성하며, 연결된 세그먼트로 구성됩니다.
오디오는 원본 동영상 세그먼트에서 그대로 보존됩니다.
오류 처리
- 세그먼트가 정의되지 않은 경우 → 오류 메시지 출력 후 종료
- 잘못된 세그먼트 시간 → 예상 형식과 함께 명확한 오류 출력
- 소스 동영상을 찾을 수 없는 경우 → 파일을 찾을 수 없다는 오류 출력
- 전사 실패 → 활성화된 경우 adaptive로 대체, 그렇지 않으면 오류 출력
- 개별 세그먼트 오류 → 로그로 기록; 나머지 세그먼트는 계속 처리