ThomasHMD/rough-cut

rough-cut: Premiere Pro 자동 러프 컷

일회성 설정: 키트 루트의 INSTALL.md를 참조하세요. 플러그인이 설치된 경우 설정 라인은 bash "${CLAUDE_PLUGIN_ROOT}/install.sh" --data "${CLAUDE_PLUGIN_DATA}"입니다. 수동 설치(4개의 skills/ 폴더를 ~/.claude/skills/에 나란히 복사)의 경우 키트 루트에서 bash install.sh를 실행하세요. 스크립트는 이 스킬의 scripts/ 폴더에 있습니다.

범위

• 가능: 재촬영, 잘못된 시작, 더듬음, 필러 단어 및 긴 침묵이 이미 제거된 Final Cut Pro 7 XML(XMEML, .xml) 타임라인; 마크다운 보고서; 사용자가 결정해야 할 부분에 빨간색 마커 표시.
• 불가능: 클립 수정, 트랜스코딩, 비디오 내보내기, 컬러 그레이딩, 믹싱, 명백한 표현 변경을 넘어서는 두 테이크 중 선택(이는 편집자의 판단).

핵심 규칙: 원본 클립은 절대 수정되지 않음

이 스킬은 클립 옆에만 파일을 씁니다:

• <clip>_Derush_v1.xml: 가져올 편집본 (FCP7 / XMEML)
• <clip>_Derush_v1.report.md, <clip>_Derush_v1.log.txt
• <clip>_Derush_v1_work/: 작업 폴더 (보관됨: 트랜스크립트, 중간 컷)

XML은 절대 경로(file://localhost/...)로 클립을 참조합니다: Premiere는 이를 참조만 합니다. 새 패스를 실행하면 아무것도 덮어쓰지 않고 v2, v3...을 생성합니다.

사용자가 해야 할 일 (3단계)

1. Premiere에서: 클립을 가져오고, 트랜스크립션을 실행한 후(텍스트 패널 > 트랜스크립션), 프로젝트를 저장합니다. 트랜스크립트는 .prproj 내부에 있습니다: 사용자에게 내보내도록 요청하지 마십시오.
2. Claude에게 클립 경로와 비디오의 참조 스크립트(일반 텍스트, 마크다운, Google 문서, Notion 페이지 등 읽을 수 있는 모든 형태)를 제공합니다. 스크립트는 반복이 의도적인 것인지 판단하는 데만 사용됩니다. 스크립트가 없어도 패스는 작동하지만, 의도적인 반복은 컷 대신 플래그로 표시됩니다.
3. .xml을 가져옵니다(File > Import). Derush_vN 시퀀스가 나타나며, 이미 편집되어 있습니다: 컷된 부분은 타임라인에서 제거되었고(클립이 끝과 끝으로 연결됨, 닫을 간격 없음), 의심스러운 부분은 활성 클립과 빨간색 마커로 남습니다.

다른 것은 묻지 마세요: 언어, 클립 유형 및 옵션은 아래 설명된 대로 자동 추론되며, 클립 유형이 명확하지 않은 경우에만 질문할 가치가 있습니다.

언어

언어별 모든 것(필러 단어, 잘못된 시작 구문, 슬레이트 패턴, 고아 접속사, 잘라낼 오프너, 속삭임 환각, 마커의 이유 텍스트)은 languages/<code>.json에 있으며, 코드에 절대 하드코딩되지 않습니다. 프랑스어(fr)와 영어(en)가 기본 내장되어 있습니다. 언어는 --lang <code>로 선택하거나, 트랜스크립트에 기록된 언어를 사용하거나, 기본값은 en입니다. 세부 사항 및 언어 추가 방법: references/languages.md.

파이프라인 v2: 테이크 선택 (일반 경로)

결함만 감지하는 v1(아래)은 Whisper가 반복된 테이크를 자동으로 중복 제거하기 때문에 재현율이 약 57%에서 정체됩니다: whisper의 안티루프 디코더는 단어 단위로 반복된 문장을 환각으로 처리하여 한 번만 트랜스크립션합니다. 이는 설정으로 해결할 수 없습니다. Premiere의 트랜스크립트는 모든 테이크를 단어 그대로 유지하며, 긴 침묵 후에도 단어 시작점이 표류하지 않습니다(whisper는 그렇습니다). 따라서:

단계	도구	역할
1	extract_prproj_transcript.py project.prproj words_premiere.json [--rush CLIP.MOV]	.prproj를 words_premiere.json으로 (기본 소스). 프로젝트에 트랜스크립트가 없으면 종료 코드 2: 사용자에게 실행 후 저장하도록 요청. 대체: 수동 JSON 내보내기에 parse_premiere_transcript.py 사용
2	extract_audio.py + transcribe.py	whisper = 보조 의견 (텍스트 교차 확인, 경계는 확인하지 않음)
2b	calibrate_premiere_times.py	Premiere 트랜스크립트를 오디오에 재정렬합니다. 모든 러프 컷에서 오디오 추출 직후 실행하십시오(트랜스크립트가 정시에 있으면 아무것도 건드리지 않음). 교차 상관 관계를 통해 윈도우별로 오프셋을 측정합니다. 21분 클립 끝에서 1.8초 드리프트가 관찰되었습니다. 잊어버리면 silence_cuts.py가 수십 개의 "의심스러운 노이즈"를 보고합니다.
3	컨텍스트 내의 Claude	의미 분석: Premiere의 트랜스크립트를 스크립트 및 whisper와 비교하여 재촬영, 잘못된 시작 및 더듬음을 식별합니다. 규칙은 아래 참조
4	silence_cuts.py	Premiere 단어 사이 1.0초 이상의 침묵, 단어 끝을 사운드 레벨에 재정렬, 열거 방지(짧은 두 블록 사이의 짧은 일시 중지 = 의도적인 리듬), 노이즈 영역: 플래그 또는 컷 (아래 참조). 기본값은 완성된 편집본에 대해 보정됨: 재측정 없이 변경하지 마십시오(references/lessons.md, "측정" 참조)
5	apply_takes.py <work>	3단계에서 결정된 테이크를 takes.json에 기록합니다(단어 인덱스; 수동 경계 또는 초 단위 컷은 선택 사항). 스크립트는 에너지 골짜기에 경계를 설정하고, 침묵과 병합하고, 두 컷 사이에 남은 무음 조각을 녹이고, 모든 클립 가장자리를 실제 사운드에 재정렬하고, 클립 가장자리에서 0.25초 미만의 고립된 사운드를 플래그 지정하여 cuts_final.json을 씁니다. 사용자가 요청한 경우에만 protect (침묵 유지)
6	build_premiere_xml.py	XMEML. 옵션 meta["audio_file"]: 오디오를 전체 길이로 처리된 WAV로 지정합니다(알려진 한계 참조). 여러 클립: 클립당 하나의 XML, 그런 다음 merge_xml.py output.xml "name" a.xml b.xml = 단일 시퀀스, 끝과 끝
6b	편집본 다시 트랜스크립션	종단 간 확인: 유지된 audio.wav 구간을 연결하고, whisper로 트랜스크립션한 후, 컷 지점과 함께 텍스트를 읽습니다. 다른 검사가 놓치는 것을 포착합니다: 편집본에 남아 있는 침묵(3단어에 8초 클립), 잘린 단어, 살아남은 실패한 테이크
7	qc_repeat_scan.py	결정론적 검사: 편집본 내 30초 이내에 반복된 5-gram이 살아 있거나, 일시 중지 또는 컷 뒤에 오는 두 단어가 편집 시작 8초 미만 전에 이미 말해진 경우(변형과 함께 반복된 테이크) 종료 코드 2. 모든 적중은 스크립트와 귀로 확인됨(hear.py): 살아남은 재촬영(마지막 것을 유지) 또는 의도적인 수사법(anaphora, 열거)
7b	montage_qc.py <work>	편집본의 오디오가 트랜스크립션되고 클립별로 읽힘, Premiere 단어(P) 대 whisper(W): 1.6초 이상의 공백 또는 1초 미만의 조각에서 종료 코드 2. 의심스러운 가장자리는 hear.py audio.wav 12.3-14.0 ...(격리된 조각에 대한 whisper)로 확인
8	report_v2.py	보고서: 편집본 및 클립 길이, 테이크, 의심; --notes는 "의도적으로 유지" 및 스크립트의 민감한 지점을 건드리는 구절에 대해

3단계, 결정 규칙

하드 규칙:

• 반복 텍스트: 마지막 테이크 유지 (이전 테이크보다 덜 깔끔하더라도)
• 더듬음: 가장 긴 연속 부분 유지
• 의심: flag, 절대 disable 하지 마십시오. 과소 컷이 항상 과다 컷보다 낫습니다: 컷을 추가하는 것은 쉽고, 누락된 구절을 복구하는 것은 지옥입니다.
• 컷 경계는 Premiere 단어에 스냅되며, 유지되는 첫 번째 단어 앞에 약 0.15초의 여유를 둡니다.

실제 편집에서 배운 규칙:

• 두 테이크 컷 사이에 끼인 2초 미만의 모든 섬은 청취됩니다(hear.py). 거의 항상 잘못된 시작입니다. Premiere 텍스트로 판단하지 마십시오: 숨소리가 Premiere에서 단어를 전달할 수 있고, "Thanks for watching" 종류의 whisper 환각은 단어가 전혀 없음을 의미합니다.
• 스크립트의 문장이 아닌 노이즈가 있는 침묵 (부언, "자 시작합니다", 카메라 조작)은 플래그가 아닌 컷됩니다.
• 문장 시작 부분의 필러 오프너 (언어 파일의 "openers" 목록, 예: "그래서," 또는 "음,")는 컷됩니다.
• 문장 내 동일한 단어 반복 더듬음 ("It's it's")은 비활성화됩니다. 그러나 마침표 양쪽에서 반복된 이름 ("less documented than Nikon. Nikon has plenty of docs")는 더듬음이 아닙니다: Premiere가 이중으로 기록했을 수 있습니다. 단일 단어 컷 전에 hear.py로 조각을 청취하십시오.
• 고아 접속사 (컷 침묵 바로 앞의 고립된 "그리고 / 그래서 / 하지만")는 컷에 포함됩니다. 컷과 다른 공격 뒤의 일시 중지 사이에 끼인 모든 외로운 잘못된 시작 단어도 마찬가지입니다.
• Premiere 트랜스크립트에 있고 whisper에 해당 항목이 없는 무의미한 단어가 중복된 부언 내에 있는 경우: 최소한 플래그를 지정하십시오.
• 정보를 전달하지 않고 다음 문장을 반복하는 필러 구문: 플래그만 (편집자의 판단 사항).
• "재촬영"은 이전 문장의 끝일 수 있으며, Premiere가 잘못 날짜를 지정했습니다(5초 길이의 단어). 편집본의 whisper 텍스트가 이를 보여줍니다.
• Premiere는 때때로 한 문장을 둘로 나눕니다: 두 단어 "잘못된 시작"은 다음 문장의 시작일 수 있습니다.
• Premiere는 작고 중얼거리는 단어를 놓칩니다: 반복 문장을 자르면 고아 도입부가 남을 수 있습니다. 먼저 hear.py로 조각을 청취하십시오. takes.json 항목의 6번째 요소로 경계를 수동으로 설정하십시오.
• 단일 중복 단어 ("the the"): 경계가 앞 단어를 잡아먹을 수 있습니다. Premiere가 둘 다 같은 숨에 날짜를 지정하기 때문입니다. 이음새를 청취하십시오(두 유지 조각의 ffmpeg atrim, 그런 다음 hear.py).
• 두 클립 사이의 이음새: 클립 1의 끝과 클립 2의 시작을 함께 청취합니다. 클립 1 끝에서 시작되어 클립 2 시작에서 반복된 문장은 첫 번째 단어부터 잘라냅니다.
• 카메라를 향해 편집자에게 말하는 지시 ("이건 너를 위한 거야, 여기에 그래픽 좀 넣어")는 지시 사항으로 컷되고 보고서에 나열됩니다. 삽화를 넣을 위치를 알려주기 때문입니다.
• 테이크를 자른 후, 유지된 테이크의 공격을 청취하십시오 (Premiere에 두 개의 단어가 있을 때 첫 번째 단어가 먹힐 수 있습니다).

Premiere 트랜스크립트는 .prproj 내부에 있음

.prproj는 gzipped XML이며, 다음 블록을 포함합니다: <ExternallyProvidedTranscriptDocument><TranscriptData Encoding="base64">, 페이로드는 FlatBuffers 버퍼입니다. extract_prproj_transcript.py가 이를 디코딩합니다:

Segment -> f0 i64 start_ticks, f3 vector<Word>, f4 string language
Word    -> f0 i64 start_ticks, f1 i64 duration_ticks, f2 string text, f3 f32 confidence
Premiere ticks = 254016000000 per second

빈 텍스트가 있는 항목은 Premiere가 표시한 일시 중지입니다(해당 기간이 전체 침묵을 포함합니다). 스크립트는 이를 삭제합니다. 그렇지 않으면 단어 사이의 모든 간격이 0이 되어 silence_cuts.py가 아무것도 찾지 못합니다(증상: "gaps > 1s: 0" 및 단어 길이 39초).

한 프로젝트에 여러 클립: .prproj는 클립당 하나의 트랜스크립트를 보유합니다. --rush NAME.MOV는 클립 길이에 맞는 것을 선택합니다(없으면 가장 긴 것을 선택하고 경고 표시). 마지막 단어의 시작을 비교하며, 길이의 0.3% 드리프트 마진을 허용합니다. 클립 간 단어 수가 다른지 확인하십시오. 클립당 하나의 작업 폴더를 만든 후 merge_xml.py를 사용합니다.

이 트랜스크립트의 두 가지 함정:

1. 파일을 기준으로 표류할 수 있습니다: 2b단계. 컷은 파일 시간(XML이 읽는 시간)에 있으므로 단어가 수정되며, 그 반대는 아닙니다.
2. 단어 길이가 뒤따르는 침묵을 삼킬 수 있습니다: 침묵이 단어 사이에 더 이상 존재하지 않게 되어 컷되지 않습니다. silence_cuts.py는 이러한 단어를 실제 끝으로 되돌립니다(trim_overflow). Premiere 단어의 끝은 절대 신뢰하지 마십시오. 시작만 신뢰할 수 있습니다.

더 많은 함정 (침묵 내에 날짜가 지정된 단어, 무음 조각, 작은 섬): references/lessons.md.

테이크 컷 경계: 단어 시작의 가장 가까운 에너지 골짜기에, 유지된 단어의 공격 전 0.12초의 여유를 둡니다. 컷을 단어 인덱스로 설명하고 초 단위로 설명하지 마십시오: 재정렬 후에도 유지됩니다.

v1 파이프라인(아래)은 Premiere 트랜스크립트가 없을 때 대체로 남아 있습니다(단어 단위 재촬영이 누락될 가능성이 있다고 경고).

시스템 요구 사항

시작 시 확인됩니다. 누락된 것이 있으면 INSTALL.md(references/whisper-setup.md는 whisper만 해당)를 참조하십시오.

brew install whisper-cpp ffmpeg
mkdir -p ~/Models/whisper
curl -L -o ~/Models/whisper/ggml-large-v3-turbo.bin \
  https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo.bin

Python 3와 numpy(그 외에는 없음). API 키도, 계정도 없으며, 모델 다운로드 후 머신을 떠나는 것은 없습니다.

파이프라인 v1 (대체, 8단계)

scripts/derush.py에 의해 실행됩니다. 각 단계는 <clip>_Derush_vN_work/에 씁니다. 클립 옆에 있으며, 절대 삭제되지 않습니다(재개 및 검사 가능).

#	스크립트	역할
1	derush.py (진입점)	ffprobe 메타데이터, 버전 번호
2	extract_audio.py	ffmpeg로 audio.wav 16kHz 모노 생성
3	transcribe.py	whisper.cpp로 transcript.json 생성
4	mechanical_cuts.py	언어 파일의 단어 목록 및 패턴을 사용하여 cuts_mechanical.json 생성
5	의미 분석 (Claude)	cuts_semantic.json 생성 (아래 참조)
6	merge_cuts.py	병합, 단어에 스냅, 점수를 cuts_final.json에 기록
7	build_premiere_xml.py	.xml (XMEML / FCP7) 생성
8	build_report.py	.report.md 생성

5단계: 의미 분석

스크립트는 prompt_semantic.txt를 쓰고 중지합니다. 이것이 일반적인 경로입니다: Claude는 스킬을 실행하면서 다음을 수행합니다.

1. prompt_semantic.txt를 전체 읽기
2. 프롬프트의 규칙에 따라 트랜스크립트 분석
3. JSON을 cuts_semantic.json에 쓰기 (경로는 프롬프트에 제공됨)
4. 재개: derush.py <clip> --resume-from=6 --work-dir=<work>

cuts_semantic.json이 이미 존재하면 단계를 건너뜁니다.

세 가지 수준의 결정 (스킬의 철학)

모든 제안된 컷에는 0에서 1 사이의 신뢰도가 있습니다.

• disable: 구절이 타임라인에서 제거되며, 비활성화되지 않습니다. build_spine_clips()는 빼기 방식으로 시퀀스를 구축합니다: 유지된 구간만 끝에서 끝으로 남고, 시퀀스 길이는 유지된 구간의 합계입니다. 이미 적용된 "리플 삭제"와 동일합니다. 임계값: 기계적 컷의 경우 >= 0.85, 의미적 컷의 경우 >= 0.92 (LLM은 종종 경계를 초과합니다).
• flag (0.6 ~ 0.85): 컷 없음. 구절은 활성 클립으로 남으며, 적절한 위치에 빨간색 시퀀스 마커("의심 <유형> (신뢰도 <값>): 이유")가 표시됩니다. 사용자가 결정합니다.
• ignore (< 0.6): 아무것도 하지 않음. 타임라인을 혼란스럽게 만들지 않기 위함입니다.

이 의미를 절대 반전시키지 마십시오. 비활성화되고 회색으로 표시된 클립을 수동으로 삭제하도록 제공하면 사용자에게 작업을 전가하는 것이지 제거하는 것이 아닙니다: 약속은 바로 사용할 수 있는 시퀀스입니다.

컷 유형

• filler: 필러 단어 ("음", "어"...) 및 문장 시작 부분의...

…

[번역을 위해 잘렸습니다]