BLOG
技術分解 016｜jianying-headless：プログラムに剪映の操作を代行させる——完成動画を確定させず、直接ローカルのプロジェクトドラフトを生成
技術分解：AI技術フレームワークの解析——説明、分析、技術評価、価値判断、実運用。著者：永亮
AI生成動画のブームがますます過熱する中、素材の生成が完了した後も、ラストマイルの編集には人が剪映の前に座り、タイムラインをドラッグし、トラックを揃え、フォントサイズを調整しなければならない。2026年9月15日、GitHubに剪映プロ版 macOS向けのローカル自動化ツール「jianying-headless」が登場し、1週間で1972スターを獲得した。そのアプローチは他とは異なる：FFmpegで完成動画をハードコードして出力する方法をスキップし、プログラムが直接、剪映で開け、修正を続けられ、ローカルエンジンでエクスポートできるプロジェクトのドラフトを生成するようにしたのだ。本稿では6つの事項に分解して解説する：何であるか、なぜバズったのか、アーキテクチャの構築方法、導入ハードル、制限と落とし穴、誰に向いているか。
一、何であるか
jianying-headlessは剪映プロ版 macOS向けのローカル自動化ツールであり、READMEでの公式位置づけは一言で言えば次の通りだ：構造化された編集計画を通じて編集可能なドラフトを生成し、独立したコピー内でマルチトラックプロジェクトを修正し、ローカルの剪映エンジンを呼び出してMP4をエクスポートする。リポジトリは9月15日に作成され、確認時点で1972スター、主にPythonで構成されている。リポジトリ全体でわずか78ファイル——36のPythonファイル、18のMarkdown、8のJSON、1のヘッダーファイル、さらにブリッジ層のソースコード bridge/ と1つの native_export.cpp から成る。小さいながらも五臓は揃っており、「剪映にインポートできる」という基準に沿って作られている。
これを最もよく表しているのは、ある実際のコラボレーション事例である：Hypitチームが約50.23秒のIGスクロールアニメーションチュートリアルを作成した際、Hypitから剪映へのプロジェクトの引き継ぎがすべてプログラムによって行われた——39のオリジナル素材、8つの動画・画像トラックに合計38のクリップ、1つのナレーショントラックに7つのクリップ、14のテキストトラックに109のクリップ、合計23トラック154クリップである。この規模を手作業の編集に置けば、テキストトラックに109個の字幕項目を配置するだけで一人が半日を費やすほどである；プログラムに任せれば、単なる1つのJSON計画のデータ量の問題に過ぎない。このドラフトは、構築、開いて再生、保存、終了、コールドリスタート、構造の読み戻しという全プロセスの検証を完了し、ネイティブエクスポートの1507/1507フレームチェックと完全なデコードチェックがすべて通過した。納品物は剪映自身が認識する完全なプロジェクトであり、「まあ開ける」はその基準には含まれない。
機能面では、動画の分割、マルチトラックの組み合わせ、速度変更、音量、ピクチャーインピクチャー、字幕タイトルをカバーしている；素材はすべてローカルからインポートされる——動画、PNG、JPEG、GIF、ナレーション、音楽・効果音；ローカルフォント（静的OTF/TTF）はドラフトと共に保存される；線形キーフレームは位置、スケール、回転、透明度、音量の5つの次元をサポートする；さらに、6種類の静的ジオメトリックマスク、クロスディゾルブトランジション、および微小な揺れがある。READMEには同時に前提条件も明記されている：揺れなどの効果には、ローカルマシンに対応するリソースと使用権限が既に存在している必要がある。
二、なぜバズったのか
バズった理由は、ツール自体がどれほど精巧かではなく、それがAI動画ワークフローのもっとも厄介な空白地帯を突いたからである。
今日の典型的なAI動画パイプラインは次の通りである：スクリプトモデルが書き、ナレーションモデルが読み上げ、画像モデルが画像や動画を出力し、素材が揃った後——人が座って剪映を開く。前段のすべての工程は自動化できるが、唯一最後のまとめの工程だけが人手に阻まれている。市場に出回っている代替案の多くは、FFmpegを使って直接完成動画を合成するというものだ。この方法でも実行は可能だが、アウトプットは変更不能な動画となる：クライアントが2つの字幕を変更したいと思えば、パイプラインに戻って再レンダリングしなければならず；編集者がトランジションを変えたいと思っても、方法はない。
jianying-headlessが選んだのは別の道である：ドラフトレベルでのプロジェクト引き継ぎだ。プログラムが直接、構造が完全でトラックが揃った剪映プロジェクトを納品し、人が開けばそのまま仕上げの編集を続けられ、仕上げが終われば剪映自身のエンジンを使ってエクスポートすることもできる。この引き継ぎの粒度は、完成動画をインポートするよりもはるかに価値がある——AIは粗編集と力仕事を担当し、人は最後の10%の美的感覚を担当する、両者はそれぞれ得意なことを行うのだ。マトリックスアカウントを運営し、毎日ショート動画を更新するチームにとって、「数十のドラフトを一括生成し、人間は最終審査だけを行う」という構想は、まさにこのステップから成立するようになるのだ。
また、これはAgent時代の切実なニーズにも副次的に答えている：編集の意思決定自体をAgentに任せた後、Agentが必要とする出力の媒体は、下流のツールと人間の両方が開けるプロジェクトファイルであり、ブラックボックスな動画の塊ではない。剪映はまさに中国語インターネット上でインストール数が最も多い編集ソフトであるが、そのプロジェクトフォーマットは公開インターフェースではない——このギャップこそが、1972スターが投じられた理由である。さらに、見落とされがちな点がもう一つある：それは「JSONを書ける」層と「剪映を使える」層を疎結合にしたことだ。計画を書く人は剪映のUI操作を知る必要がなく、剪映を知る人はコードを書く必要がなく、両者の間にあるのは、レビュー可能で、バージョン管理可能で、diffを取れる構造化テキストのみである。協力コストが下がって初めて、バッチ処理が成立するのだ。
三、アーキテクチャの実現方法
パイプライン全体は4つのステップからなり、コマンドラインで駆動します：第1歩D、4#、JSONの編集計画を記述します——トラック”クリップ、開始・終E4D、速度変更、キーフレーム、字幕をすべて構造化して記述します。第2D、headless_draft.py build が計画を剪映のドラフトにコンパイルし、verify-build が生成結果の構造検証を行います。第3D、剪映が完全に終了した後に publish を実行します——これはローカルマシンのホーム画面にドラフトを登録するだけで、インターネットに何かを公開するわけではないことに注意してください。第4D、export がローカルマシンの剪映エンジンを呼び出して H.264/AAC の MP4 をエクスポートし、出力ファイル名は render.mp4 となります。
このアーキテクチャで最も語る価値があるのはブリッジ層であり、これが本稿全体におけるエンジニアリングの潔癖さの所在でもあります。
エクスポートのこのステップでは、剪映独自のレンダリングエンジンを回避することはできません——フォント、エフェクト、トランジションの実際の見た目を知っているのはそれだけだからです。本プロジェクトは剪映をダウンロードしておらず、公式ライブラリを内包してもいません。そのやり方は、bridge/ ディレクトリ内でプロジェクト自身のソースコードのみをコンパイルし、その後、ローカルマシンに既にインストールされている剪映のプログラムライブラリにリンクするというものです。重要なのは検証です：コンパイル成果物は固定のハッシュ値と一致しなければならず、一致しなければ実行を拒否します。バージョンが不明な場合やコンポーネントが一致しない場合も同様に拒否し、検証を緩めて無理やり実行することはありません。言い換えれば、ブリッジ層は「確かにプロジェクトのソースコードのみをコンパイルし、あなたのマシン上のその公式ライブラリにリンクしたこと」を自分自身で証明できる前提でのみ動作します。これは意図的な設計姿勢です：自動化をローカルのエンジニアリング操作の範囲内に厳格に収め、公式プログラムのクラックや改造を行わないようにしています。
エクスポートは独立したプロセスで実行され、デフォルトではネットワークに接続せず、アカウントデータも読み取りません。ハッシュ検証と組み合わせることで、作者は「ツールが何に触れてよくて、何に触れてはいけないか」を免責事項に書くだけでなく、コードの構造に書き込んでいます。同種のアプローチと比較すると、一般的な做法は公式プログラムのリバースエンジニアリングやインジェクションであり、機能的にはより「完全」かもしれないものの、公式の更新のたびに攻防戦が発生します。ハッシュ検証がもたらすのは、メンテナンス姿勢のクリーンさです：新バージョンへの適応はハッシュの再確認と同義であり、確認できなければサポート外であることを明確に伝え、不具合を抱えたままこっそり中身の変わってしまった動画出力を実行することはありません。
リポジトリにはAgent Skillも付属しています：skills/yichen-jianying-edit/ ディレクトリが SKILL.md、スクリプト、参考資料を提供しており、インストール後に環境変数 JIANYING_HEADLESS_ROOT をコアプロジェクトのパスに向けて設定すれば、Agentはドキュメントに従って一連のコマンドを呼び出せます。このSkillは作者の yichen-skills スキルセットにも収録されています——これから分かるのは、ターゲットユーザーのペルソナは最初からAgentとワークフローであり、一般的な動画編集者ではないということです。
四、導入のハードル
そのハードルは本当に高く、先に冷水を浴びせかける必要があるほどです。
環境要件を項目ごとに列挙します：Apple Silicon チップを搭載した Mac；macOS 26.0 以上（26.5.1 で検証済み）；剪映プロ版 11.5.0、11.4.2 と互換性あり；Python 3.9 以上；FFmpeg および ffprobe；Xcode コマンドラインツール、検証済みのツールチェーンは Apple clang 21.0.0。この5つのうち1つでも欠けていると実行できず、Windowsユーザーは即座に脱落します。
プロジェクトには環境チェックを行う doctor コマンドが内蔵されており、推奨される順序は明確です：先に doctor を実行してすべての依存関係にチェックマークを付け、それから build に触ることです。この順序を逆にしないでください——環境が整っていない状態でドラフトを生成すると、問題が発生した際に計画の書き間違いなのか、それとも環境に欠落があるのかを判断するのが非常に難しくなります。
また、正直に認めるべきギャップがもう一つあります：プロジェクトは現在、主に作者自身のマシンと協力事例のマシンでの検証を終えており、クリーンなマシンでの完全な受入テストは完了していません。つまり、手順通りにインストールしても、ドキュメントに記載されていない落とし穴に遭遇する可能性があり、特に剪映のバージョンの微調整、システム権限、フォントレンダリングのあたりでそれが起きやすいです。これを「クロスマシンでパッケージング・配布された成熟したソフトウェア」として期待するのではなく、「作者が自ら可用性を保証した環境」として期待する方が、ずっと健全な心持ちになれます。
また、実行時には一致するバージョンの剪映をインストールする必要があります——これは実行時の依存関係であり、オプションではありません。サーバーやCI環境でヘッドレス実行することを期待している人は、まずそのマシンに剪映プロ版をインストールできるかを確認してください。
五、制限と落とし穴
README自身が挙げている制限リストはかなり率直なので、1つずつ確認していく。
第一に、視覚的なロスレス変換ではない。Hypitのケースでは1507/1507フレームの数の検証はすべて通過したが、フレーム数が合っていても画面が完全に一致するとは限らない。特殊なフォント、単語ごとのカラーアニメーション、一部のクロップとシャドウはそのまま保持されておらず、37秒目の補足画面は元のプロジェクトと目に見える差異がある。コンテンツが特定のフォントスタイルに強く依存している場合、エクスポート後にフレームごとに人間が目視確認しなければならない。
第二に、画像とGIFで間欠的に1フレーム少なくなることがある。厳密なフレーム数チェックはフレーム欠落の出力を拒否するため、この保護メカニズムは存在するが、根本原因は解決されていない——エラーに遭遇した場合は、再実行するか素材を変更すべきであり、安定した再現と修正を期待してはならない。
第三に、バージョンロックである。ブリッジ層のハッシュ検証の代償として、剪映のメジャーバージョンが更新されると、ブリッジが機能しなくなる可能性があり、作者の適応を待つ必要がある。任意の剪映バージョンをサポートするわけではなく、任意のエフェクトの組み合わせもサポートしない。
第四に、複合フラグメントは実験的なサポートのみである。オフラインでの変更のみ可能で、エク#スポート時には静的画像として固定される。複合フラグメントを多用するプロジェクトについては、現段階では期待しない方がよい。
第五に、サポート範囲の縮小である。HD白黒フィルタとオレンジ色の縁取り装飾文字はすでにサポート範囲から外れている——「退出」という言葉に注意され8れたい。これはかつてサポートされていたが作者によって能動的に削除されたことを示しており、最初から実装されていなかったのではなく、メンテナンスコストや整合性の問題による取捨選択である可能性が高い。オンラインテンプレート、リソースダウンロード、クラウドプロジェクト、アカウント権益は一切サポートされない。このツールはローカルプロジェクトのみを管理し、その境界線ははっ$きりと引かれている。
第六に、そして最も重要)要な点：ライセンスである。LICENSEは「個人学習および非商業利用ライセンス」-—コードはsource-availableであり、閲覧、クローン、学習、変更は可能だが、個人の学習、研究、および非商業的な個人のワークフローに限定される。商業利用には作者の書面による許可が必要である。これはMITでもApache-2.0でもなく、さらにコードのライセンス自-体に剪映の統合許可、アカウント(権益、)または素材の許可は含まれていない——素材の著作権、音楽の著作権、フォントの著作権は、元の権利者のままである。作者は同時に、これが剪映の公式SDKではないことを明確に宣言している。法律のグレーゾーンについては本稿では判断を避け、作者が自ら設定した境界のみを述べる：剪映をダウンロードしない、公式ライブラリを変更しない、アカウント権益に触れない。
六、結論と適しているユーザー
3つの文でまとめる。第一に、jianying-headlessの価値は剪映を代替することではなく、「編集プロジェクト」をプログラムによる読み書きが可能な一次産物に変えることにある——AIが素材を出力し、スクリプトがドラフトを作成し、人間が最終審査を行うという分業において、初めて使いやすい引き継ぎフォーマットが得られた。第二に、ハッシュ検証ブリッジは本稿で最も参考にすべきエンジニアリング思想である。固定ハッシュを用いて「自分のコードだけをコンパイルし、ローカルに既存の公式ライブラリのみをリンクする」ことを、単なるスローガンではなく検証可能な事実に変えている——ローカル自動化ツールを作る人は皆、この境界をコードに書き込む潔癖さを学ぶべきである。第三に、ハードルと制限も同様に現実である。macOSとApple Siliconと指定バージョンの剪映というハードル、非商業ライセンス、バージョンロックのメンテナンスコストにより、現時点では「個人のワークフローにおける鋭利なパーツ」であり、チームの生産ラインの標準装備ではないことが決定づけられている。
適している人：自メディアマトリックスを運営し、剪映のドラフトをバッチ出力してから人間が最終審査を行う必要がある個人や小規模チーム。Agentの編集ワークフローを構築し、剪映プロジェクトレベルの出力媒体を必要とする開発者。
適していない人：Windowsユーザー。商業利用の許可が必要なチーム——作者の書面による許可を得るか、ライセンスが緩和されるのを待つ必要がある。そして「任意のエフェクト、任意のバージョンで自動エクスポートできる」ことを期待する人——この境界は作者によって厳しく引かれているので、無理に突破してはならない。
最後の注意：このツールで生成されたドラフトに含まれる各素材、各フォント、各音楽の権利帰属は、このツールとは無関係である。ツールはプロジェクト構造のみを管理し、著作権のコンプライアンスは利用者自身の課題である。この点はREADMEとLICENSEに明記されている。
参考ソース
- GitHubリポジトリ：mcncarl/jianying-headless（README、LICENSE、skills/yichen-jianying-edit/、bridge/）、2026-09-21時点、★1972
- リポジトリのファイル構成とコード統計（78ファイル：36 .py / 18 .md / 8 .json / 1 .h）
- READMEのHypitコラボレーションケースと既知の制限リスト（50.23秒、23トラック154フラグメント、1507/1507フレーム、非ロスレス宣言）
- LICENSE：Personal Learning and Non-Commercial Use License