Communitygithub.com

Chengfeng Export — 컷·줌·자막·오버레이를 MP4 하나로 번인

완성된 토킹헤드 영상을 렌더링: 컷 장부, 펀치인 줌, 자막, HTML 비주얼 레이어를 한 번에 mp4로 번인. 먼저 dry-run으로 길이·프레임 수·자막 화면 수·레이어를 확인한 뒤 조립 → 오버레이 → 합성 → 검증. Google Chrome과 ffmpeg 6 이상 필요.

Chengfeng Export — 컷·줌·자막·오버레이를 MP4 하나로 번인란 무엇인가요?

숏폼 편집 레시피 3단계(내보내기): video-skill-ku-chengfeng-export. 실제로 픽셀을 그리는 유일한 단계로, 그 전은 모두 실시간 미리보기되는 주석. 자막이나 레이어가 잘린 단어를 가리키면 경고를 그대로 보고하고, 기본값은 2배 크기·원본 프레임레이트이며 디버깅용 중간 프레임도 보관 가능.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/2789927464king-jpg/video-skill-ku/tree/HEAD/chengfeng-videocut-skills/plugins/chengfeng-videocut/skills/chengfeng-export

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

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

문서

내보내기(완성 영상)

이것은 체인의 마지막 단계이며, 전체 제품에서 실제로 픽셀을 그리는 유일한 곳입니다.

이전의 모든 단계는 주석(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라고 보고하지 마십시오.
  • 내보내기를 실행하기 위해 프로젝트 파일(자막 수정, 레이어 삭제, 장부 변경)을 수정하지 마십시오. 내보내기는 읽기 전용이며 쓰지 않습니다.
  • 내보내기에서 상위 단계의 작업을 대신 수행하지 마십시오. 자막이 없으면 자막을 작성하러 가고, 비주얼이 없으면 비주얼을 만들러 가십시오. 이 단계에서 임시로 얼버무리지 마십시오.

Individual skills in this repo

This repo contains 8 individual skills — each has its own dedicated page.

2789927464king-jpg/video-skill-ku

剪辑环境的唯一管理者:就绪检查(skills 是否最新 → Runtime 是否配套)、Skills 更新激活、Runtime 安装与体检。用户说检查更新、安装剪辑环境、装播放器、检查剪辑环境、剪辑环境就绪了吗、配置转录凭证时使用;业务 Skill(剪口播/字幕/画面/导出)第 0 步也引用本 Skill 的就绪检查。不用于剪辑、字幕、画面、导出本身或项目数据迁移。

2789927464king-jpg/video-skill-ku

剪辑中文口播原素材:逐词转录、词典修字出修字表、五轮扫描找口误与重复、汇总表与重复句子表、打开 Studio 让用户复核、复盘沉淀用户偏好与词典。只产出一份已复核的删词账本,不切媒体、不做字幕、不做分镜动画。用户说剪口播、处理口误、生成口播基础素材、继续剪口播,或确认卡回传 action=return_cut_review 时使用。不要用于执行物理剪切、导出剪后视频、单独安装、单独打开工作台或口播分镜成片。

2789927464king-jpg/video-skill-ku

整理、脱敏并上报 chengfeng-videocut 的 GitHub Bug。用户说上报 Bug、反馈剪口播问题、提交 GitHub Issue、这个问题告诉开发者,或要求继续提交已预览的 Bug 草稿时使用。不要用于功能建议、普通排错、代码提交或未获用户确认的自动上报。

2789927464king-jpg/video-skill-ku

给剪好的口播做字幕:直接用已有的逐词稿加账本算出剪后时间(不必导出、不必重新转录)、用词典和作者文稿改写听错的专名、按句子分屏、在 Studio 里逐屏复核。用户说做字幕、加字幕、改字幕、重新分屏、字幕不对时使用。不要用于删词剪辑、物理剪切、分镜动画或成片渲染。

2789927464king-jpg/video-skill-ku

操作 chengfeng-videocut 剪辑工作台的已有工程,通过 Runtime CLI 查工程与词句位置、添加或替换画面覆盖层、移除画面、删除明确指定的词句或片段、拆分裁剪移动已有片段、调整画布比例并回读核验。用户说插入片段、删掉这句、移除动画、换个画面、调整顺序或管理时间线时使用;先区分画面覆盖与主轨顺延插入,不负责自动判断口误、创作动画、制作字幕、导出或排查安装故障。

2789927464king-jpg/video-skill-ku

Create Ian Xiaohei-style HTML/SVG motion illustrations for Chinese articles, scripts, storyboard scenes, workflow explanations, concept metaphors, and short video visual aids. Use when the user asks for 小黑 SVG、漫画感 HTML、分层 SVG 动效、把小黑生图做成 HTML/SVG、可编辑矢量动效、口播流程动画、手绘漫画动效、正文配图动画, or wants a Xiaohei illustration style adapted into controllable HTML/SVG/GSAP output instead of raster image generation.

2789927464king-jpg/video-skill-ku

给剪好的口播配画面:在录屏上盖 HTML 层(圈重点标注 / 小黑整屏动画 / 推近),层绑字幕屏、由播放器逐帧驱动、直接在预览里看。用户说做分镜、配画面、加动画、圈重点、B-roll、做 storyboard 时使用。不要用于删词剪辑、字幕、物理剪切或成片渲染。

2789927464king-jpg/video-skill-ku

剪映 (JianYing) AI自动化剪辑的高级封装 API (JyWrapper),提供开箱即用的 Python 接口,支持录屏、素材导入、字幕生成、Web 动效合成及项目导出。全面适配 MacOS (Apple Silicon/Intel) 与 Windows,支持 v5.9+ (draft_info.json) 架构、工程自修复、智能配音字幕及录屏变焦。

관련 스킬