FCPXML을 통한 Final Cut Pro 편집
시작하기 전에 알아야 할 것
inspect → diagnose → edit 순서를 항상 지키세요. 타임라인은 파일명만으로는 알 수 없는 구조를 가지고 있으며, 잘못된 가정 하에 편집하면 되돌리는 데 많은 비용이 듭니다.
inspect작업analyze_timeline으로 타임라인 형태, 길이, 해상도를 확인합니다.diagnose작업validate_timeline으로 갭, 플래시 프레임, 중복 등을 진단합니다.- 변경하기 전에
preview://<path>리소스를 읽어 타임라인을 실제로 확인합니다. 이 리소스는 자체 포함된 HTML 타임라인을 렌더링하며, 연결된 클립이 자체 레인 행에 표시되므로 B-롤과 오디오 레이어를 주 스토리라인뿐만 아니라 볼 수 있습니다.
일곱 가지 그룹
| 그룹 | 용도 |
|---|---|
inspect | 읽기 전용 분석. 항상 여기서 시작하세요. |
diagnose | 문제 찾기: 갭, 플래시 프레임, 무음 구간, 중복, 비트. |
edit | 클립 변경: 삽입, 삭제, 트림, 분할, 재정렬, 리타임, 무음 제거. |
mark | 마커 및 챕터, SRT/VTT 및 비트 가져오기 포함. |
generate | 새 구조 생성: 러프 컷, 몽타주, A/B 롤, 템플릿 및 import_edl_json (비디오 사용 컷 리스트에서). |
transcript | 로컬에서 트랜스크립션한 후, 말한 내용을 기준으로 편집하거나 정리. transcript_pack은 전체 촬영본을 한 페이지에 담습니다 — 대화 편집 계획 전에 읽으세요. 모든 작업은 화자 레이블과 오디오 이벤트를 위해 backend: "elevenlabs"를 지원합니다. 이 방식은 미디어를 ElevenLabs에 업로드하며 ELEVENLABS_API_KEY가 필요합니다. 기본값 local은 기계를 떠나지 않습니다. |
deliver | 다른 NLE로 내보내기, 포맷 변환, 재연결, FCP로 푸시. |
preview | 편집 내용 보기: 프록시 렌더, 콘택트 시트, 소스 미디어에서 읽은 필름스트립+웨이브폼. |
watch | 순환 종료: 운영자가 Cmd-E로 내보내는 것을 감지하고 마지막 내보내기와 비교. |
index | 분석 캐시. index_status는 캐시 수명을 알려주고, index_build는 타임라인의 모든 소스를 워밍업하며, index_clear는 삭제합니다. 이에 의존하는 것은 없습니다. |
scenes | 픽셀 기반 샷 경계. detect_scenes는 소스 및 타임라인 시간별 클립별 컷을 나열합니다 ([scenes]를 통해 PySceneDetect 설치 시, 그렇지 않으면 ffmpeg의 거친 scene 필터 사용); scenes_to_markers는 각 컷에 마커를 추가하고, scenes_split은 그 위치에서 클립을 자릅니다. 결과는 인덱스에 캐시됩니다. |
organize | 대량 라이브러리 로깅 및 원장(ledger). organize_auto는 캐시된 캡션과 트랜스크립트에서 클립별 키워드를 제안합니다 (apply=true이면 실제로 작성). clip_name glob, keyword 및/또는 role로 클립을 선택한 후, organize_keywords (추가/제거/교체), organize_rate (즐겨찾기/거부/초기화) 또는 organize_roles — 각각 _organized 복사본을 만듭니다. history는 파일 폴더의 모든 기록된 작업을 나열하고, undo는 마지막 n개의 출력을 저널의 undone/ 폴더로 이동합니다 (절대 삭제하지 않으며, 파일이 변경된 경우 거부합니다). |
find | "어디에…하는 부분이 있지?" 라우터. find_shots는 말한 내용(트랜스크립트), 로깅된 내용(이름, 키워드, 노트, 마커, 오디오 이벤트) 및 [find] 추가 기능과 다운로드된 로컬 모델이 있으면 프레임 모양에 따라 순위를 매깁니다 — 첫 번째 줄은 어떤 계층이 응답했고 왜 어떤 계층은 응답하지 못했는지 알려줍니다. find_index는 씬과 캡션을 워밍업하고 어떤 클립에 트랜스크립트가 없는지 보고합니다 (절대 트랜스크립션하지 않으며, 절대 온라인으로 가지 않습니다). find_to_timeline은 히트를 다양성 점수가 있는 _found 셀렉트 릴로 조합합니다. |
모든 호출은 {"action": "...", "args": {...}} 형식을 사용합니다. 그룹이 소유하지 않은 액션을 전달하면 오류에 유효한 액션 목록이 표시됩니다 — 추측하지 말고 읽으세요.
발목을 잡을 FCPXML 사실들
- 시간은 유리수이며, 절대 실수(float)가 아닙니다.
3600/2400s는 1.5초입니다. 타임코드에 실수 연산을 하거나 직접 반올림하지 마세요. offset은 타임라인 위치이고,start는 소스 인포인트입니다. 이 둘은 다른 숫자이며 혼동하면 편집이 조용히 틀어집니다.- 라이브러리 클립과 타임라인 클립은 다른 요소입니다.
<asset-clip>은 라이브러리에,<clip>은 타임라인에 있습니다. - 마커는 클립의 자식 요소이며, 형제가 아닙니다.
<spine>은 주 스토리라인입니다. 연결된 클립은 레인별로 스파인 클립에 매달립니다: 양수는 위(비디오), 음수는 아래(오디오)입니다..fcpxmld번들은 디렉터리로,Info.fcpxml과 사이드카 데이터를 감쌉니다. 저장 시 사이드카를 보존하지 않으면 객체 추적 및 시네마틱 데이터가 파괴됩니다.- 중복된 클립 이름은 흔합니다. 도구가 둘 다 제공한다면 이름 조회보다 요소 기반 작업을 선호하세요.
무음 제거: 올바른 방법 선택하기
두 가지 감지-수정 쌍이 있으며 서로 대체할 수 없습니다. 둘 다 이 서버의 다른 모든 감지/수정 쌍과 동일한 분할을 따릅니다: 감지기는 diagnose에, 수정기는 edit에 있습니다.
detect_media_silence(diagnose) →remove_media_silence(edit)은 ffmpeg로 실제 소스 오디오를 읽습니다. 정확하지만 느리며 ffmpeg가 설치되어 있어야 합니다.detect_silence_candidates(diagnose) →remove_silence_candidates(edit)은 타임라인 휴리스틱만 사용합니다. 빠르고 ffmpeg가 필요 없지만 추측에 기반합니다.
정확성이 중요할 때는 미디어 기반 버전을 사용하세요. 어떤 방법을 사용했는지 명시하세요.
일반적으로 잘 맞는 작업 순서
inspect→diagnose→preview://리소스 읽기.- 편집이 대화 중심이라면
transcript의transcript_pack작업 — 모든 대화를 한 페이지에 담아, 클립 이름이 아닌 실제 단어를 기반으로 계획을 세울 수 있습니다. generate로 어셈블리,edit으로 세부 조정,mark로 챕터 추가.- 변경한 범위에 대해
preview의preview_check작업을 실행한 후에만 편집이 완료되었다고 제안하세요. 이것이 편집을 맹목적이지 않게 만드는 단계입니다.preview://리소스와preview_timeline은 모두 XML에서 그리기 때문에 작성된 내용을 보여주며, 수정된 컷과 깨진 컷을 구분할 수 없습니다.preview_check는 미디어를 직접 읽습니다. 둘을 대체하지 말고, 도구 호출이 성공했다고 해서 건너뛰지 마세요. deliver— 내보내기 또는 실행 중인 앱으로push_to_fcp실행.- 세션당 한 번
watch의watch_start를 실행한 후, 운영자가 내보내면watch_pull을 실행합니다. Final Cut Pro에는 프로그래밍 방식 내보내기가 없습니다 — Apple은 제공하지 않았습니다 — 따라서 운영자가 Cmd-E를 누를 때만 순환이 종료됩니다. 침묵 속에서 기다리지 말고 이 사실을 명확히 말하세요.
하지 말아야 할 것
- 진단(diagnose) 패스 없이 편집하지 마세요. 플래시 프레임과 갭이 누적됩니다.
- ffmpeg나 Whisper가 설치되어 있다고 가정하지 마세요. 둘 다 우아하게 성능이 저하되며 오류 대신 빈 결과를 반환하므로 응답을 확인하세요.
preview_render요약에서 UNVERIFIED 라는 단어를 지나쳐 읽지 마세요. 이는 렌더링된 파일의 길이를 다시 읽을 수 없었음을 의미하므로, 해당 렌더링에 대해 확인된 것이 아무것도 없습니다.Substituted:줄을 무시하지 마세요. 프록시 렌더는 전환을 하드 컷으로 대체하므로, 타임라인의 디졸브가 지금 보고 있는 것과 동일하지 않습니다.push_to_fcp가 호출되어 성공을 보고하지 않았다면 편집이 Final Cut Pro에 적용되었다고 주장하지 마세요..fcpxml파일을 쓰는 것과 가져오는 것은 다릅니다.- 도구 자체의 성공 메시지만으로 타임라인이 올바르다고 믿지 마세요.
preview://를 읽고 직접 확인하세요.