Communitygithub.com

Chengfeng Export — カット・ズーム・字幕・オーバーレイを1本の MP4 に焼き込み

完成版トーキングヘッド動画をレンダリング。カット台帳、寄りズーム、字幕、HTML ビジュアルレイヤーを一度に mp4 へ焼き込む。まず dry-run で尺・フレーム数・字幕画面数・レイヤーを確認し、組み立て → 重ね → 合成 → 検証。Google Chrome と ffmpeg 6 以上が必要。

Chengfeng Export — カット・ズーム・字幕・オーバーレイを1本の MP4 に焼き込み とは?

ショート動画編集レシピ Step 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に質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

エクスポート(完成品)

これはチェーンの最後のセグメントであり、製品全体で唯一実際にピクセルを描画する場所です。

それ以前はすべてアノテーションです。台本には「どの単語を再生するか」、字幕には「画面に何を表示するか」、ビジュアルには「どのレイヤーを重ねるか」が記録され、 プレビューはこれら3つをリアルタイムで合成して人間に見せますが、ディスクには書き込みません。エクスポートはそれらを1つのファイルに焼き付けます。

必要   edit-list.json(必須)、subtitles.json、visuals.json + modules/
出力   完成品.mp4

前提ツール:マシンに Google Chrome が必要です(字幕とアニメーションを画像としてレンダリングするため)。デスクトップインストール元の FFmpeg / FFprobe はアプリと共に Product 管理ディレクトリに含まれています。純粋な CLI インストールの場合は、システムに ffmpeg ≥ 6 が必要です。Chrome がない場合は明確にエラーが報告されるため、回避しようとしないでください。Chrome がなければ字幕レイヤーとアニメーションレイヤーは存在しません。

最初に ビジネススキルのフェーズ契約 の「結論レベル」セクションを読み、実行します。エクスポートは編集ステートマシンには入りません。プロジェクトファイルを変更せず、CAS 書き込みも行わず、ステージを進めず、出力は新しいファイルであり、再実行すれば上書きされます。したがって、確認カードは必要ありません。

0. 準備

最初に 更新確認 の「準備確認」を実行します。スキルが最新か、ランタイムが対応しているか、プラグインルートもそこで特定されます(この記事のコマンド内の <プラグインルート> はすべてそのリテラルパスを代入します)。「準備完了」の場合のみ続行します。「新しいセッションが必要」または「停止」の場合は、その指示に従って処理します(「自作の代替インターフェースの禁止」禁令を含む)。ビジネススキル自体に環境ロジックは含まれません。

準備結果が runtime.kind=desktop-managed の場合、デスクトップアプリに既にインストールされている安定した CLI、メディアツール、および同じ launchd/windows-task サービスを直接再利用します。Electron パスを解決したり、FFmpeg/Bun を追加インストールしたり、2番目のランタイムを起動したりしないでください。

コマンド

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 の身元が一致しない、ポート競合が発生する、またはサービスが正常でない場合は直ちに停止します。フォアグラウンドで一時的に代用してエクスポートを続行することは許可されていません。

2ステップ、2番目のステップだけを実行しない

① --dry-run で計画を報告     長さ、フレーム数、字幕画面数、ビジュアルレイヤー数、ズームインセグメント数、出力サイズ
                           ユーザーに読み上げます。数字が間違っていれば上流が間違っている証拠であり、10分のエンコードでは修正できません
② 実際に実行                アセンブル → オーバーレイ → コンポーズ → 検証の4段階の進捗

--dry-run 内の warnings はそのまま伝える必要があります。報告されるのは1種類の問題だけです:一部の字幕画面やビジュアルレイヤーの単語が既にカットされているため、完成品には表示されません。これは上流が決定すべきことであり、エクスポートが代わりに飲み込むべき問題ではありません。

解像度:ソースファイルが上限、まずソースを確認してから拡大

エクスポート前にソース解像度を確認します(--dry-run の source フィールドにあります):

ソース幅 ≥2560(Retina ネイティブ録画)  → --scale 1、出力はネイティブピクセル、これが最良のケース
ソース幅 <1920(例:960×720)      → 一旦停止:ユーザーに同じ録画の高解像度エクスポートがないか確認します。
                              録画ツールは同じ録画を3倍の解像度で再エクスポートできることが多く、
                              ソースを置き換える方が後処理よりも効果的です(次のセクション参照)。本当にない場合 → --scale 2

--scale 2 が低解像度ソースで有効な理由:ベース画像を拡大しても鮮明にはなりませんが、字幕とアニメーションは出力サイズに合わせて再描画されます。視聴者が実際に読むのはこれら2つです。プラットフォームで再度圧縮する際、大きな画像にはより多くのビットレートが割り当てられます。

「より鮮明にする」ために --fps を調整しないでください。 フレームレートはソースファイルに従います。変更すると、アニメーションのサンプリングと録画が一致しなくなります。

ソースの置き換え:ユーザーが同じ録画の高解像度版を提供した場合

これはエクスポートフローの一部ではありません。エクスポート自体は常に読み取り専用です。ソースの置き換えは、ユーザーが明確に承諾した後の独立した素材操作であり、完了後に通常のエクスポートに戻ります。

まず同じ録画かどうかを判定します(最初の2つで十分です):

ffprobe -v error -show_entries format=duration -of csv=p=0 <2つのファイル>   # 長さがミリ秒単位で一致
ffmpeg -v error -i <ファイル> -map 0:a:0 -c copy -f md5 -                  # オーディオストリームがビット単位で一致
# さらに2~3フレームを抽出して画面内容を比較、目視確認

オーディオがビット単位で一致 = タイムラインが一致:ワード単位の台本、台帳、字幕、ビジュアルレイヤーはすべて単語IDにバインドされており、変更する必要はありません。これこそが「単語にバインドし、秒にバインドしない」という原則がソース置き換えで実現される点です。

ソース置き換えの4ステップ(2026-07-29 に実際に1回経験。③のステップを当時見落とし、クリッププレビューが即座に「生成失敗」と報告。フィンガープリント記録は1か所だけでなく、古いフィンガープリントを 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 などのキャッシュレコードは自動的に再計算されるため、手動で変更する必要はありません)。

オーディオが異なる場合(再録音、カット、長さの変更)はソースの置き換えではなく、新しいプロジェクトです: ワード単位の台本を再トランスクリプトし、すべてのアノテーションは無効になります。無理に適用しないでください。

検収:3つの項目、1つでも欠ければエクスポート完了とは見なさない

① コマンドが正常終了        製品自体が完成品のサイズ、フレーム数、オーディオトラックをカウントし、計画と項目ごとに比較。
                        一致しない場合は readback_mismatch エラーが報告され、ファイルはディスクに証拠として残り、
                        エクスポート完了とは見なされない
② フレームを抽出してピクセルを確認   完成品からフレームを抽出し、目視で確認。少なくとも以下をカバー:1つのズームインセグメント、
                        1つの全画面アニメーションセグメント、1つの字幕のみのセグメント、1つのレイヤー境界
③ 人間の聴覚チェック        実際に聞いた人はいないため、一律 human listening UNVERIFIED と記録

② はプレビュー画面で代用してはいけません。プレビューと完成品は2つの異なるレンダリングパスであり、検収で確認すべきはそれらが一致するかどうかです。 プレビューの画像を完成品の証拠として使用することは、確認すべきことを前提としてしまうことになります。

ズームインの判定には判別可能なランドマークを探し、全体的な印象に惑わされないでください(2026-07-29 に実際に踏みました):1.6倍ズームイン後の 画面ページはまだ「1ページ」のように見え、サムネイルでは全景とほとんど差がありません。正しいズームインフレームを「ズームインが失われた」と誤判定し、30分無駄に追跡し、2回再エクスポートしました。正しい判定方法は、トリミングによってのみ生じる証拠を探すことです: 半分にカットされた要素(バブルが中央で途切れる)、消えたエッジ要素(サイドバー、タイトルバー)。 ソースファイルの同じ時間のフレームと比較すれば、一目で確定します。

フレーム抽出には ffmpeg を使用:

ffmpeg -v error -ss 8.84 -i 完成品.mp4 -frames:v 1 -y frame.png

問題が発生した場合の確認場所

--keep-work を使用すると、プロジェクトの .chengfeng-videocut/export/ に3つのものが残り、 「どの半分が間違っているか」を直接分離します:

assembled.mkv    編集のみ、オーバーレイなし。これが間違っている = 台本またはカットが間違っている
overlay/*.png    オーバーレイのみ、透明な背景。これが間違っている = 字幕スタイルまたはモジュールが間違っている
spans/*.mp4      合成後のセグメント。これが間違っている = ズームインまたはアライメントが間違っている

対照表:

完成品に字幕/アニメーションがない       overlay PNG がすべて透明?モジュールが seek に応答していない?
アニメーションが最初のフレームで停止     モジュールが seek を実装していない、または GSAP タイムラインが paused されていない
画面全体が白                      モジュールに `:root { color-scheme: dark }` がない
ズームインのフレームが歪んでいる        モジュールの viewBox とレイヤーの zoom が同じ数値セットではない
完成品が計画より短い                 特定のスパンのフレーム数が不足、コンポーズ段階のエラーを確認
レイヤー境界に一瞬元の映像が表示される   overlay スクリーンショットが古い(フレームマーカー検証が機能していない)。製品はページ上部の
                                  フレームマーカーバーで各スクリーンショットがどのフレームに属するかを証明します。再発時は、overlay
                                  PNG の上部にマーカーバーがあり、コンポーズでそれをクロップしているか確認
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) 架构、工程自修复、智能配音字幕及录屏变焦。

関連スキル