내보내기(완성 영상)
이것은 체인의 마지막 단계이며, 전체 제품에서 실제로 픽셀을 그리는 유일한 곳입니다.
이전의 모든 단계는 주석(annotation)입니다. 장부(account book)는 "어떤 단어를 재생할지" 기록하고, 자막(subtitle)은 "화면에 무엇을 쓸지" 기록하고, 비주얼(visual)은 "어떤 레이어를 덮을지" 기록하며, 미리보기는 이 세 가지를 실시간으로 조합하여 사용자에게 보여줍니다. 디스크에 저장하지 않습니다. 내보내기는 이들을 하나의 파일로 합쳐(burn) 만듭니다.
필요 항목: edit-list.json(필수), subtitles.json, visuals.json + modules/
출력물: 완성 영상.mp4
전제 도구: 머신에 Google Chrome이 설치되어 있어야 함(자막과 애니메이션을 이미지로 렌더링하는 데 사용). 데스크톱에 설치된
FFmpeg / FFprobe는 앱과 함께 Product의 관리형 디렉토리로 제공됩니다. 순수 CLI 설치는 여전히 시스템에
ffmpeg ≥ 6이 필요합니다. Chrome이 없으면 명확한 오류 메시지와 함께 중단됩니다. 이를 우회하지 마십시오. Chrome이 없으면 자막 레이어와 애니메이션 레이어를 만들 수 없습니다.
먼저 비즈니스 Skill 단계 계약의 "결론 등급" 섹션을 읽고 실행합니다. 내보내기는 편집 상태 머신(edit state machine)에 진입하지 않습니다. 프로젝트 파일을 수정하지 않고, CAS 쓰기를 수행하지 않으며, stage를 진행하지 않습니다. 출력은 새 파일이며, 다시 실행하면 덮어씁니다. 따라서 확인 카드(confirmation card)가 필요하지 않습니다.
0. 준비
먼저 업데이트 확인의 "준비 확인"을 실행합니다. skills가
최신인지, Runtime이 호환되는지 확인합니다. 플러그인 루트도 여기서 찾습니다(이 문서의 명령에서 <플러그인 루트>는 모두 해당 리터럴 경로를 의미합니다).
"준비 완료" 상태인 경우에만 계속합니다. "새 세션 필요" 또는 "중지" 상태인 경우 해당 처리 지침에 따릅니다
("자체 제작 대체 인터페이스 금지" 명령 포함). 비즈니스 Skill은 자체 환경 로직을 포함하지 않습니다.
준비 결과가 runtime.kind=desktop-managed인 경우, 데스크톱 앱에 이미 설치된 안정적인 CLI,
미디어 도구 및 동일한 launchd/windows-task 서비스를 직접 재사용합니다. Electron 경로를 구문 분석하거나,
FFmpeg/Bun을 별도로 설치하거나 두 번째 Runtime을 시작하지 마십시오.
명령어
node "<플러그인 루트>/scripts/ensure-running.cjs" --json
node "<플러그인 루트>/scripts/videocut-cli.cjs" export <프로젝트> --dry-run --json # 먼저 계획만 확인, 인코딩하지 않음
node "<플러그인 루트>/scripts/videocut-cli.cjs" export <프로젝트> --json # 완성 영상 생성(기본값: 2배속, 원본 프레임 레이트)
node "<플러그인 루트>/scripts/videocut-cli.cjs" export <프로젝트> --out /경로/완성영상.mp4 --json
node "<플러그인 루트>/scripts/videocut-cli.cjs" export <프로젝트> --scale 1 --json # 원본 크기만 사용
node "<플러그인 루트>/scripts/videocut-cli.cjs" export <프로젝트> --keep-work --json # 중간 파일 및 프레임별 PNG를 남겨 디버깅용으로 사용
ensure-running이 ID 불일치, 포트 충돌 또는 서비스 비정상 상태를 감지하면 즉시 중단합니다. 포그라운드에서
임시로 대체한 후 내보내기를 계속하는 것은 허용되지 않습니다.
두 단계, 두 번째 단계만 실행하지 마세요
① --dry-run 으로 먼저 계획 보고: 영상 길이, 프레임 수, 자막 화면 수, 비주얼 레이어 수,
줌인(推近) 섹션 수, 출력 해상도
사용자에게 읽어서 알려줍니다.
숫자가 맞지 않으면 상위 단계에 문제가 있는 것이며,
10분 인코딩으로 해결되지 않습니다.
② 실제 실행: assemble → overlay → compose → verify 네 단계 진행
--dry-run의 warnings는 반드시 있는 그대로 전달해야 합니다. 이는 한 가지 유형의 문제만 보고합니다: 일부 자막 화면 또는 비주얼 레이어의 단어가
이미 잘려나갔으므로 최종 완성 영상에 나타나지 않습니다. 이는 상위 단계에서 결정할 문제이며, 내보내기 단계에서 대신 결정하거나 숨겨서는 안 됩니다.
선명도: 원본이 최고 수준, 원본을 먼저 확인한 후 확대를 논의하세요
내보내기 전에 원본 해상도를 확인하세요(--dry-run의 source 필드에 있음):
원본 너비 ≥2560(Retina 네이티브 화면 녹화) → --scale 1, 출력이 네이티브 픽셀입니다. 가장 좋은 경우입니다.
원본 너비 <1920(예: 960×720) → 일단 중단: 사용자에게 동일한 녹화 세션의 고해상도 내보내기가 있는지 물어보세요.
화면 녹화 도구는 종종 동일한 녹화 세션을 3배 해상도로 다시 내보낼 수 있습니다.
원본을 교체하는 것이 어떤 후처리보다 효과적입니다(아래 섹션 참조).
확실히 없는 경우 → --scale 2
--scale 2가 저해상도 원본에 유용한 이유: 기본 영상을 확대해도 선명해지지 않지만, 자막과 애니메이션은 출력 크기에 맞춰
다시 그려집니다 — 시청자가 실제로 읽는 것은 바로 이것들입니다. 플랫폼이 다시 압축할 때 큰 이미지가 더 높은 비트레이트를 할당받습니다.
"더 선명하게" 만들기 위해 --fps를 조정하지 마세요. 프레임 레이트는 원본 영상을 따라야 합니다.
변경하면 애니메이션 샘플링과 화면 녹화가 일치하지 않게 됩니다.
원본 교체: 사용자가 동일한 녹화 세션의 고해상도 버전을 제공하는 경우
이것은 내보내기 흐름의 일부가 아닙니다. 내보내기 자체는 항상 읽기 전용입니다. 원본 교체는 사용자가 명시적으로 동의한 후의 독립적인素材 작업이며, 완료된 후 다시 정상 내보내기를 진행합니다.
먼저 동일한 원본인지 판단하십시오(처음 두 가지 조건으로 충분히 확실함):
ffprobe -v error -show_entries format=duration -of csv=p=0 <두 파일> # 재생 시간이 밀리초 단위까지 동일
ffmpeg -v error -i <파일> -map 0:a:0 -c copy -f md5 - # 오디오 스트림이 비트 단위로 동일
# 그런 다음 2-3프레임을 추출하여 화면 내용을 눈으로 확인
오디오가 비트 단위로 동일 = 타임라인이 동일함: 단어 대본(word script), 장부(account book), 자막, 비주얼 레이어 모두 단어 ID에 바인딩되므로 하나도 수정할 필요가 없습니다. 이것이 바로 "단어에 바인딩하고 초에 바인딩하지 않는" 방식이 원본 교체 상황에서 실제로 효과를 발휘하는 지점입니다.
원본 교체 4단계(2026-07-29에 실제로 한 번 수행됨. 당시 ③단계를 놓쳐서 클립 미리보기가 즉시 "생성 실패" 오류를 보고함. 핑거프린트 기록이 한 군데만 있는 것이 아니므로, grep으로 이전 핑거프린트를 모두 찾아 처리해야 함):
① 파일 교체 input/source.mp4 와 uploads/source.mp4 는 하드 링크 관계입니다.
둘 다 삭제하고, 새 파일을 input/ 에 복사한 후 uploads/ 에 하드 링크를 다시 만듭니다.
(macOS: ln 사용; Windows: New-Item -ItemType HardLink 사용)
② 핑거프린트 업데이트 project.json 의 source.sha256 을 새 파일의 값으로 변경합니다.
③ 다른 위치 확인 workbench.json 의 sourceSha256 도 원본 영상의 핑거프린트를 기록하고 있습니다.
클립 미리보기 파이프라인이 검증하는 것은 바로 이 파일입니다.
이 단계를 놓치면 미리보기 생성이 거부됩니다.
(이것은 제품의 올바른 동작입니다. 핑거프린트가 일치하지 않으면 실패하는 것이 옳으며,
오래된 미리보기를 새로운 것으로 가장하지 않습니다.)
④ 다시 내보내기 --scale 1 —— 원본 교체의 목적은 네이티브 픽셀을 사용하기 위한 것이므로,
다시 확대하지 마십시오.
안전한 방법: 검색 도구를 사용하여 <프로젝트 디렉토리>의 모든 *.json 파일에서 이전 핑거프린트의 처음 8자를 찾습니다. 나열된 모든 위치를 처리해야 합니다(캐시 레코드(예: preview-edited/current.json)는 자동으로 재계산되므로 수동으로 수정할 필요 없음).
오디오가 다른 경우(다시 녹음했거나, 편집했거나, 길이가 다른 경우)는 원본 교체가 아니라 새 프로젝트입니다. 단어 대본을 다시 변환해야 하며, 모든 주석이 무효화됩니다. 억지로 적용하지 마십시오.
검수: 세 가지 항목, 하나라도 없으면 내보내기 완료로 간주하지 않음
① 명령어가 성공적으로 반환됨 제품이 완성 영상의 해상도, 프레임 수, 오디오 트랙을 계획과
항목별로 비교합니다.
일치하지 않으면 readback_mismatch 오류가 발생하고,
파일은 디스크에 증거로 남으며 내보내기 완료로 간주되지 않습니다.
② 프레임을 추출하여 픽셀 확인 완성 영상에서 프레임을 추출하여 눈으로 확인합니다.
최소한 다음을 포함해야 함: 줌인 섹션 하나,
전체 화면 애니메이션 섹션 하나, 자막만 있는 섹션 하나, 레이어 경계 부분
③ 사람의 귀로 듣기 아무도 실제로 들어본 적이 없으므로,一律 "인간 청취 UNVERIFIED"로 기록
②는 미리보기 스크린샷으로 대체할 수 없습니다. 미리보기와 완성 영상은 두 가지 다른 렌더링 경로이며, 검수에서 확인해야 하는 것이 바로 이 둘이 일치하는지 여부입니다. 미리보기 이미지를 완성 영상의 증거로 사용하는 것은 검증하려는 것을 전제로 삼는 것과 같습니다.
줌인 판단 시 구별 가능한 랜드마크를 찾으십시오. 전체적인 인상은 속일 수 있습니다(2026-07-29에 실제로 경험함): 1.6배 줌인 후의 화면 페이지가 여전히 "한 페이지"처럼 보여서 축소판과 전체 샷이 거의 구별되지 않았습니다. 한때는 올바른 줌인 프레임을 "줌인이 누락됨"으로 잘못 판단하여 30분을 낭비하고 두 번 다시 내보냈습니다. 올바른 판단 방법은 자르기(crop)만이 만들 수 있는 증거를 찾는 것입니다: 절반이 잘린 요소(가운데가 끊긴 말풍선), 사라진 가장자리 요소(사이드바, 제목 표시줄). 원본 영상의 같은 시점 프레임과 비교하면 한눈에 결정할 수 있습니다.
ffmpeg를 사용하여 프레임을 추출합니다:
ffmpeg -v error -ss 8.84 -i 완성영상.mp4 -frames:v 1 -y frame.png
문제 발생 시 확인 위치
--keep-work는 프로젝트의 .chengfeng-videocut/export/ 디렉토리에 세 가지 항목을 남기며,
"어느 절반이 잘못되었는지"를 직접 분리합니다:
assembled.mkv 순수 편집만 포함, 덮어씌워진 것은 없음. 이 파일이 잘못됨 = 장부 또는 클립(clip) 오류
overlay/*.png 덮어씌워진 것만 포함, 투명 배경. 이 파일이 잘못됨 = 자막 스타일 또는 모듈 오류
spans/*.mp4 합성 후 세그먼트. 이 파일이 잘못됨 = 줌인 또는 정렬 오류
대조표:
완성 영상에 자막/애니메이션 없음 overlay PNG가 완전히 투명한가? 모듈이 seek을 수락하지 않았는가?
애니메이션이 첫 프레임에서 정지 모듈이 seek을 구현하지 않았거나, GSAP 타임라인이 paused 상태가 아님
화면 전체가 흰색 블록 모듈에 `:root { color-scheme: dark }`가 누락됨
줌인 박스가 비뚤어짐 모듈의 viewBox와 레이어의 zoom이 동일한 숫자 세트가 아님
완성 영상이 계획보다 짧음 특정 span의 프레임 수가 부족함. compose 단계의 오류 메시지 확인
레이어 경계에 짧은 원본 영상 깜빡임 overlay 스크린샷이 오래됨(프레임 마커 검증 실패).
제품은 페이지 상단의 프레임 마커 막대를 사용하여 각 스크린샷이
어떤 프레임에 속하는지 증명합니다. 재발 시, overlay
PNG 상단에 마커 막대가 있고 compose가 crop으로 이를
잘라내는지 먼저 확인하세요.
Chrome을 찾을 수 없음 Google Chrome을 설치하세요. 다른 렌더링 경로로 변경하지 마십시오.
금지 사항
- "내보내기 성공"을 "검수 통과"라고 말하지 마십시오. 명령어가 성공적으로 반환된 것은 제품 자체가 일치함을 의미할 뿐, 화면이 맞다는 것을 의미하지 않습니다.
- 미리보기 스크린샷, DOM, 로그를 완성 영상의 프레임 추출 대신 사용하지 마십시오.
- 아무도 들어본 적이 없는데 human listening PASS라고 보고하지 마십시오.
- 내보내기를 실행하기 위해 프로젝트 파일(자막 수정, 레이어 삭제, 장부 변경)을 수정하지 마십시오. 내보내기는 읽기 전용이며 쓰지 않습니다.
- 내보내기에서 상위 단계의 작업을 대신 수행하지 마십시오. 자막이 없으면 자막을 작성하러 가고, 비주얼이 없으면 비주얼을 만들러 가십시오. 이 단계에서 임시로 얼버무리지 마십시오.