jianying-headless: editable CapCut/Jianying drafts from a JSON plan on macOS

What jianying-headless actually produces, and for whom

The output is not a rendered video. It is a Jianying Pro draft directory that a human can open, play, edit and save inside Jianying, plus an optional MP4 produced by the local Jianying engine from a verified snapshot. The README frames the core flow as materials and edit plan, then editable Jianying draft, then native engine export.

The audience is narrow and engineering-shaped: people handing off AI video workflows, teams generating drafts in batches, and Agent-assisted editing setups. The README states the project suits engineering handoff of AI video workflows, batch draft generation and Agent-assisted editing. If you want a one-click video generator, this is the wrong shape of tool, because the deliverable is a project file someone still has to open.

One boundary is stated bluntly: it is not an official Jianying SDK, and running it requires a matching version of Jianying installed. There is no bundled engine and no cloud service.

The mechanism: plan JSON in, validated draft out, native export last

The repository splits into engine/, bridge/, skills/, tools/ and tests/. The engine handles draft construction, isolated-copy editing, resource validation and native export. The bridge holds file and pipe bridge source plus interface headers that keep their provenance notices. The build step compiles this bridge against libraries already installed on the machine.

The plan format is JSON, described in skills/yichen-jianying-edit/references/headless-macos.md, with examples at examples/basic.plan.json and examples/hypit-handoff.plan.json. Supported plan features include video segmentation, multi-track composition, speed changes, volume, picture-in-picture, subtitles and titles, plus linear keyframes for position, scale, rotation, opacity and volume.

Editing an existing project happens in an independent copy. The README says the source draft is inspected and modified in a copy, without overwriting the original. That is a deliberate safety property, and it also means the copy is a separate artifact you must track.

Export runs in an isolated process that the README says does not use the network and does not read account data by default. Output must be H.264/AAC MP4, written as render.mp4 inside a directory that must not already exist.

One directional limit is explicit: manual changes made later inside Jianying do not sync back to the original plan or to older export snapshots. The plan is upstream of the draft, never downstream of it.

Installing it and building a first draft

The README points new users at docs/GETTING-STARTED.md, which covers prerequisites, environment checks, importing your own video, homepage registration, saving and reopening, and common errors. The prerequisites listed are an Apple Silicon Mac on macOS 26.0 or later (verified on 26.5.1), Jianying Pro 11.5.0 or a compatible 11.4.2 configuration, Python 3.9+, FFmpeg/ffprobe, and Xcode Command Line Tools. The verified bridge toolchain is Apple clang 21.0.0 with macOS SDK 26.5.

Clone the repository, build the native bridge, and run the environment check. The README gives exactly this sequence:

git clone https://github.com/mcncarl/jianying-headless.git
cd jianying-headless
python3 tools/build_native_codec.py
python3 skills/yichen-jianying-edit/scripts/headless_draft.py doctor

doctor checks the Jianying version, component identity and required tools. Passing it means the environment meets the runtime conditions; the README is careful to add that it does not mean any given draft has passed picture, audio or export acceptance.

The bridge build only compiles project source and links against libraries already installed on the machine. It does not download Jianying, and it does not modify official libraries or account entitlements. The compiled result must match a fixed hash or the build stops.

Prepare a plan JSON following the format reference, or start from examples/basic.plan.json. Material paths in the examples must be replaced with local files you have the right to use. Then build and verify:

python3 skills/yichen-jianying-edit/scripts/headless_draft.py build \
  --plan /absolute/path/to/plan.json --out "$PWD/work/new-build"
python3 skills/yichen-jianying-edit/scripts/headless_draft.py verify-build \
  --build "$PWD/work/new-build"

After saving your work and fully quitting Jianying, register the new draft on the local homepage:

python3 skills/yichen-jianying-edit/scripts/headless_draft.py publish \
  --build "$PWD/work/new-build" --audit "$PWD/work/new-publish-audit"

publish here means local homepage registration only, not publishing to the internet. The generated draft still has to be opened, played and saved as a real check. When you need a finished file, export the verified snapshot:

python3 skills/yichen-jianying-edit/scripts/headless_draft.py export \
  --build "$PWD/work/new-build" --out "$PWD/work/new-export"

The output directory must not exist beforehand, and the finished video is render.mp4 inside it.

For Agent use, skills/yichen-jianying-edit/ provides the call entry point, narration-plan helper scripts and operating references. The Skill does not contain the Jianying engine, so after installing it separately you still need the core project checked out and its path set:

export JIANYING_HEADLESS_ROOT="/absolute/path/to/jianying-headless"

Installation notes for the standalone Skill live in skills/yichen-jianying-edit/README.md.

Where it breaks: version pinning, frame counts and dropped effects

The most consequential limitation is version coupling. The README states 11.5.0 as the primary target and 11.4.2 as compatible, and says unknown versions or mismatched components are rejected rather than forced through by relaxing checks. That is the right call for safety and the wrong call if you are on a different build, because there is no fallback path. The README also says 11.5.0 still needs to match a specific install identity and toolchain, and that install-and-run on any computer is not yet guaranteed. Clean-machine installation acceptance is listed as unfinished.

Composite clips are experimental. Offline modification and frozen-snapshot export work, but the README says they cannot yet be delivered as a save-reliable editable nested draft. If your workflow depends on nesting, you are outside the supported surface.

Image and GIF samples have intermittently come out one frame short. Strict frame-count checks reject the short output, and the root cause is unresolved. So a passing export is meaningful, but a failing one may be a known bug rather than your plan.

Two effects have been dropped from support entirely: the high-definition black-and-white filter and the orange-outline stylized text. Plans or old snapshots containing them will error out explicitly. That is better than silent corruption, but it is a hard stop.

The README also separates acceptance categories: project structure checks, native playback, visual consistency, subjective audio quality and material licensing are different things. Passing one does not imply the others. The Hypit case makes this concrete: the handoff is not a visually lossless conversion, and special fonts, per-word color animation, some cropping and shadows were not preserved, with a difference at second 37. Full subjective audio-visual acceptance is stated as incomplete.

The Windows FFmpeg path is a different tool wearing the same name

Windows gets a separate FFmpeg backend contributed by @instantgoing in PR #1. It generates a validated render snapshot from the edit plan and outputs MP4. Critically, the README says it does not require Jianying to be installed and does not generate a draft editable in Jianying. It supports only the documented video, audio and basic text capabilities, and it is not equivalent to the macOS native flow.

The Windows cloud run validated full decode, frame count and volume using the repository's public IG case. If your goal is a rendered file on Windows, that path may be enough. If your goal is a handoff into an editable Jianying project, it is not the same product, and treating it as one will surprise you at the point where you try to open the output.

As an alternative approach, the obvious comparison is to skip Jianying entirely and drive FFmpeg directly from your own render graph. The difference is what you get back: a direct FFmpeg pipeline gives you full control over filters and encoders and no version pinning, but it gives you a finished file, not a project a human editor can reopen and adjust. This project's whole value sits in that editable intermediate, and the Windows backend deliberately gives it up.

Licence, maintenance and what upgrades cost you

The repository carries NOASSERTION as its licence identifier, and the README describes the original parts as under a personal study and non-commercial use licence, with commercial use requiring written authorization from the author. Third-party content keeps its original licences, detailed in THIRD_PARTY_NOTICES.md. The README states plainly that this is not a whole-package MIT or Apache-2.0 grant, and that the code licence does not include Jianying integration rights, account entitlements or material licences. Distribution boundaries are in docs/DISTRIBUTION-SCOPE.md. That is a description of the terms, not legal advice; if you plan commercial use, read LICENSE and THIRD_PARTY_NOTICES.md yourself.

The repository is not archived, and the last push was on 2026-09-27. There are no retrieved releases, so upgrades are tracked through the repository rather than versioned artifacts.

The upgrade cost is real and specific. Because the bridge compiles against locally installed libraries and the result must match a fixed hash, a Jianying update can invalidate your build. Application version, build, official library hashes, signatures and developer identity are all checked, and mismatched components are refused. Practically, an upgrade means rebuilding the bridge, re-running doctor, and re-validating your plans against the new version, not just pulling the latest commit. The README also points to docs/ISSUE-REMEDIATION.md for build tool choices, install diagnostics, registration recovery and font support progress, and to docs/VERIFICATION.md for detailed results and known issues.

For your own source checks, the repository ships two commands:

python3 tools/check_package.py
python3 -m unittest discover -s tests -v

The README notes that native test materials and evidence are not distributed with the repository, so source checks cannot substitute for acceptance on a real project.

Editorial conclusion

Adopt jianying-headless if you are on an Apple Silicon Mac running macOS 26.0 or later, you already have Jianying Pro 11.5.0 or 11.4.2 installed, and you need batch draft generation or an Agent-driven handoff into an editable Jianying project rather than a finished file. Do not adopt it if you need Windows-native editable drafts, arbitrary Jianying versions, online templates, cloud projects, or account entitlements; the Windows path only produces MP4 through FFmpeg and cannot be opened in Jianying. Before committing, verify your exact Jianying build against the identity checks by running headless_draft.py doctor, confirm the bridge build matches the fixed hash, and read docs/VERIFICATION.md for the frame-count and filter limitations that still stand open.

Frequently asked questions

Official sources

1. Issues
2. mcncarl/jianying-headless on GitHub
3. README