jianying-headless
The CN video lane's biggest day-4 find: hash-pinned, fail-closed everywhere, honest about the one machine it was verified on.
This is the most carefully gated four-day-old repo we have tested: every native path fails closed with a named component, the skill pins its engine by SHA-256, and the offline voice-edit layer passed all 12 of our functional checks with byte-identical renders. But the headline capability (headless Jianying drafts and native MP4 export) only runs against one exact CN-market editor install on Apple Silicon Macs, two of three open issues report that other machines cannot reproduce the pinned codec hash, and the custom non-commercial license blocks redistribution and commercial use. Study it as a design example, use it personally if your machine matches, do not build a product on it.
$git clone --depth 1 https://github.com/mcncarl/jianying-headless.git && python3 tools/start_here.py check
needs Jianying Pro 11.5.0/11.4.2 + Xcode CLT + ffmpeg
$python3 tools/build_native_codec.py
compiles and links local Jianying libraries, output must match a fixed hash
$npx skills add mcncarl/jianying-headless
lands the pointer skill; also set JIANYING_HEADLESS_ROOT to a core checkout
install if
- CN-market creators already running Jianying Pro 11.5.0 on an Apple Silicon Mac. If the codec hash reproduces on your machine, you get batch draft generation, agent-driven editing of isolated copies, and native-export automation for an editor that has no official SDK.
- Agent-workflow builders doing video handoffs. The Hypit case (39 assets, 23 tracks, 154 segments reconstructed as an editable draft, with frame-accurate export evidence) is a worked template for AI-tool-to-editor engineering handoff.
- Skill authors studying fail-closed design. The 14-file SHA-256 pin gate, the byte-pinned public-media allowlist, and the refusal-first CLI contract are patterns worth copying in any skill that drives a proprietary host application.
skip if
- Anyone without that exact editor, OS, and chip. There is no Windows or Linux path, no other editor versions, and no workaround; the tool fails closed by design.
- Commercial or production pipelines. The license requires prior written authorization (via WeChat) for any revenue-generating use and forbids redistribution as a packaged product, so it cannot ship inside your product, SaaS, or internal toolkit as-is.
- Readers who need English docs. README, references, and error-message prose are Chinese; only the license and third-party notices are English.
- Anyone wanting a one-command install. Even on a matched machine, expect editor install, codec compilation, hash verification, and a two-repo skill setup before the first draft.
What It Does
jianying-headless turns a structured JSON edit plan into a native, still-editable Jianying (εͺζ δΈδΈη, ByteDance's CN CapCut) draft on Apple Silicon Macs, edits existing multi-track projects in isolated copies without touching the originals, and exports verified snapshots to H.264/AAC MP4 through the locally installed editor's own engine. The repo is a 22 MB "public source preview" of a private project: an engine (3,070 lines of Python across 10 modules plus a C++ codec bridge), a standalone Agent Skill at skills/yichen-jianying-edit (SKILL.md, 6 references, 3 scripts), portable tests, and unusually detailed verification and distribution docs. It targets creators and agent-workflow builders in the CN video ecosystem who want batch draft generation, AI-workflow handoff (the README's Hypit case reconstructs a 23-track, 154-segment IG animation as an editable draft), or agent-assisted editing inside the real Jianying app rather than a parallel renderer. The repo detonated on creation day-plus-three: 1,309 stars and 585 forks (44.7 forks per 100 stars, the strongest organic fork signature the scanner has recorded at this scale), though skills.sh installs remain tiny (20 via the author's yichen-skills collection, 1 via this repo).
The Good
Every gate we could reach fails closed with a named component and a fix instruction. With Jianying absent, doctor exits 1 on ValueError: IO/codec component unavailable: jy14_codec_hardened_11_4; build with tools/build_native_codec.py. The codec build itself exits 1 on [Errno 2] No such file or directory: '/Applications/VideoFusion-macOS.app/Contents/Info.plist'. tools/smoke_test.py refuses at the doctor step instead of half-running, build refuses before creating any output directory, and the beginner preflight prints per-row PASS/FAIL/WARN with the failing row naming the exact missing install and stating you may not bypass it by editing hashes. Nothing we tried degraded into an undefined state.
The skill entrypoint pins its engine by hash, and the pin gate works. headless_draft.py carries a table of 14 SHA-256 pins over the engine files and refuses to run if any file differs. We recomputed all 14 against the shipped files (all matched), then appended a single comment line to engine/native_effects.py: the script refused with reverify before updating the pin: native_effects.py. This is the same anti-drift contract orca uses with binary-served guides, applied at skill level, and it means a registry-delivered skill cannot silently drift from the engine it drives.
The offline voice-edit layer is exact, deterministic, and negative-hardened. edit_plan.py compile turned our synthetic 4-second WAV plan (two keeps, 0-2s and 3-4s, two subtitles) into a compiled plan of exactly 60 + 30 = 90 frames at 3,000,000 microseconds, emitted subtitles.srt and a transcript.md review draft, and render-audio produced a review WAV of exactly 144,000 samples (3.0s at 48 kHz); a second render was byte-identical (sha256 486afc2e..., both runs). We independently re-derived the frame-grid math from the compiled ranges and it checks out. Four planted violations were each rejected with a named error: a tampered source fingerprint (Source fingerprint changed.), unconfirmed settings (Confirm this task's speed, sound and edit intensity before compiling.), overlapping keep ranges (Keeps must be ordered, non-overlapping...), and a subtitle endpoint inside deleted source, which is the failure mode that would otherwise desync captions after cuts.
The documentation is honest to a degree that is rare at any age, let alone day four. The README's limitations section names an unresolved intermittent one-frame loss on image/GIF segments and two retired effects that now hard-reject old plans instead of silently dropping them. docs/VERIFICATION.md is a dated log whose newest entry (the morning we tested) re-verified a clean checkout and then states, in bold, that it is not another independent machine and that clean_machine_acceptance remains not-completed. tools/check_package.py enforces that the four demo media files match exact SHA-256 and byte-size pins, scans every tracked file for personal paths, private keys, GitHub tokens, and signed URLs (clean pass on this clone), and THIRD_PARTY_NOTICES.md documents the pyJianYingDraft lineage while explicitly noting it is "not a clean-room originality claim."
The install path is version-gated rather than version-hopeful. The preflight verifies the installed editor's version, build, official library hash, signature, and developer identity, and the verified toolchain row on our host read Apple clang version 21.0.0 / SDK 26.5, exactly the combination the repo documents as verified. The repo refuses unknown versions instead of relaxing validation to run anyway, which is the correct posture for a tool that writes drafts into a proprietary app's data directory.
The Bad
Reproducibility is the wall, and the tracker already shows it. Two of the three open issues are reproduction blockers: issue #2 (Chinese) reports a clean machine cannot reproduce the codec's fixed output hash and asks the author to publish exact toolchain identifiers or distribute the verified binary, and issue #3 (English) reports the 11.5.0 codec build blocked by a libvideoeditor hash mismatch on a different install. The author's own VERIFICATION.md concedes every green result comes from one Mac, one editor install, one toolchain. For a repo whose security model depends on fixed hashes, "works on the machine it was built on" is a real limitation, and it is the gap between a personal tool and an installable skill.
The license blocks almost every ecosystem use. The custom "Personal Learning and Non-Commercial Use License" prohibits commercial use without written authorization obtained through a WeChat contact, and prohibits republishing, mirroring, packaging, or including the work in any skill collection, template bundle, marketplace item, SaaS component, or internal company toolkit. GitHub accordingly reports NOASSERTION. For the agent-skills ecosystem, whose distribution norm is MIT or Apache-2.0 packs installed through skills.sh, this repo can be studied and run personally but not folded into anyone's collection, and the 585 forks are almost all license-noncompliant by default if used as anything but private study.
The headline capability was not verifiable on a stock compliant Mac, and the supported surface is one cell wide. Native drafts, homepage registration, and MP4 export require Jianying Pro 11.5.0 or 11.4.2 installed (a CN-market desktop app), macOS 26+, Apple Silicon, and a matched Xcode toolchain. There is no Windows path (issue #1 is an unmerged community PR adding one), no Linux path, no other editor versions, and no headless install of the editor itself. Our Functional-Verified is partial by necessity, not by choice.
The skill/engine split creates registry friction. Installing via npx skills add lands a pointer skill that immediately refuses with Jianying Headless checkout unavailable... The Skill alone does not include the engine until you separately clone the engine repo and export JIANYING_HEADLESS_ROOT. The split is documented and intentional (the engine cannot be redistributed as a packaged product under the license), but a registry user gets a two-repo, one-env-var install with no English instructions: all documentation is Chinese-only, the only harness config is agents/openai.yaml, and Hermes, OpenClaw, Claude Code, and Codex are never mentioned.
Smaller rough edges. Of 112 discovered engine tests, 103 are fixture-paired standalone runners (test_headless.py --work --fixture) that need retained local evidence the repo does not distribute and error on NameError: FIXTURE from a fresh clone; only the 9 offline visual-effects checks (catalog integrity, retired-effect rejection) pass without it, alongside the 28-test portable suite (green in 0.24s). doctor prints a raw Python traceback above its clean one-line error. There are 5 commits from a single author, no tags, no releases, and no CI.
Smoke Test Results
Host-based run (the sbx daemon was unavailable): macOS 26.5.2 aarch64, Python 3.12.13, ffmpeg/ffprobe from Homebrew, Xcode CLT with Apple clang 21.0.0 and SDK 26.5, Jianying Pro NOT installed. The last point is deliberate: this host matches every documented requirement except the editor itself, which isolates the fail-closed contract for testing.
Run A. Fresh sandbox, no deps preinstalled
$ git clone --depth 1 https://github.com/mcncarl/jianying-headless
β
22 MB clone, skill SKILL.md + 6 references + 2 example plans present, frontmatter name/description valid
$ python3 tools/check_package.py
β
exit 0: no secrets, no personal paths, all 4 demo media files match byte-size + SHA-256 pins
$ python3 -m unittest discover -s tests
β
Ran 28 tests in 0.238s, OK (package, public-media pins, runtime profiles, beginner flow)
$ headless_draft.py doctor
β
fails closed: ValueError: IO/codec component unavailable: jy14_codec_hardened_11_4; build with tools/build_native_codec.py
$ recompute the 14 engine SHA-256 pins in headless_draft.py
β
all 14 match the shipped files
$ append one comment line to engine/native_effects.py, run doctor
β
refused: 'reverify before updating the pin: native_effects.py' (restored after probe)
$ python3 tools/build_native_codec.py
β
fails closed: [Errno 2] No such file or directory: '/Applications/VideoFusion-macOS.app/Contents/Info.plist'
Pass rate: 7 of 7. Every failure here is the product refusing to run without its required component, which is the documented contract, so each refusal counts as a pass of the gate.
Run B. Sandbox with deps preinstalled
$ python3 tools/start_here.py check
β
7 PASS / 1 FAIL / 2 WARN: arm64, macOS 26.5.2, Python 3.12.13, ffmpeg, ffprobe, clang 21.0.0, SDK 26.5 all PASS; sole FAIL is the missing Jianying identity row
$ grep FAIL-rows for non-Jianying causes
β
every FAIL row is the editor identity row (no host-requirement mismatch on a compliant Mac)
$ python3 -m unittest discover -s engine
β
112 run: 103 error on missing retained fixtures (NameError: FIXTURE in setUp), 9 offline visual-effects checks pass (catalog integrity, retired-effect rejection)
$ python3 tools/smoke_test.py
β
refuses at the doctor gate, retains audit directory, never builds partial output
$ ffmpeg testsrc2+sine -> synthetic.mp4 (the smoke test's own fixture recipe)
β
3s H.264/yuv420p+AAC fixture renders
$ headless_draft.py build --plan <valid-plan> --out <dir>
β
refuses without the editor; no half-built output directory left behind
Pass rate: 6 of 6. On a fully compliant Mac minus the editor, every documented prerequisite passes and the pipeline stops exactly where the design says it must.
Run C. Functional verification (does it do what it claims?)
Offline surface only: the voice-edit compiler and review renderer, with positive and negative cases, plus an independent re-derivation of the frame math.
$ edit_plan.py compile --plan voice-plan.json --out out/
β
{"duration": 3.0, "segments": 2, "subtitles": 2, "sfx": 0}; compiled.json + subtitles.srt (2 cues) + transcript.md written
$ edit_plan.py render-audio --plan out/compiled.json --out review.wav --work w/
β
{"samples": 144000, "duration": 3.0, "sha256": "486afc2e..."} exact-length render
$ render-audio a second time
β
byte-identical output (same sha256), deterministic pipeline
$ independent frame-math audit of compiled ranges
β
60+30=90 frames, duration_us 3000000, subtitle source-to-target mapping (3.05-3.9s -> ~2.03-2.94s) correct
$ compile with tampered source_sha256
β
rejected: Source fingerprint changed.
$ compile with settings_confirmed=false
β
rejected: Confirm this task's speed, sound and edit intensity before compiling.
$ compile with overlapping keeps
β
rejected: Keeps must be ordered, non-overlapping and inside source duration.
$ compile with a cue inside deleted source
β
rejected: A subtitle or cue endpoint is inside deleted source (caption-sync protection)
$ asr_once.py --help
β
exit 0, documents the optional $yichen-asr dependency path
Functional pass rate: 9 of 9. All assertions are on actual output values (frame counts, sample counts, hashes, error strings), not just exit codes.
What the runs tell you
The parts that can run anywhere (plan compilation, time mapping, review rendering, packaging hygiene, gating) are exact, deterministic, and refuse invalid input with named errors. The parts that make the project interesting (native draft writing, homepage registration, MP4 export through the editor's engine) sit behind the editor install and the fixed-hash codec, so this review verifies the gates and the offline layer, and credits the author's committed, dated, single-machine evidence for the rest. Issue #2 and #3 say other machines are currently stuck at exactly that boundary.
Setup Walkthrough
- Check your machine first: Apple Silicon Mac, macOS 26 or newer, then run
python3 tools/start_here.py checkfrom the clone. On our compliant host, 7 of 10 rows passed and the only FAIL was the editor identity row, with two WARNs (codec not yet built; draft home directory not initialized). - Install Jianying Pro (εͺζ δΈδΈη) 11.5.0, or a 11.4.2 configuration, from the CN App Store or ByteDance's site. The tool verifies version, build, the official
libvideoeditor.dylibhash, signature, and Team ID, and refuses anything else. - Build the bridge codec:
python3 tools/build_native_codec.py. It compiles the project's C++ source and links your locally installed editor libraries; the output binary must match a fixed SHA-256 or the build stops. This is the step issues #2 and #3 report failing on machines other than the author's. - Open Jianying once, create and save a blank project, and quit it, so the draft home directory (
~/Movies/JianyingPro/.../com.lveditor.draft) exists for the laterpublishstep. - Write a JSON plan per
skills/yichen-jianying-edit/references/headless-macos.md(or start fromexamples/basic.plan.json), thenbuild,verify-build,publish, and optionallyexportthroughheadless_draft.py. The beginner guide (docs/GETTING-STARTED.md, added the morning of our test) walks a first 2-second draft with all commands copy-pasteable. - To use the skill standalone from the registry, also clone this repo and
export JIANYING_HEADLESS_ROOT=/absolute/path/to/jianying-headless; the skill refuses to run until that points at a checkout whose engine files match all 14 pins.
Alternatives
- GuanYixuan/pyJianYingDraft - the Apache-2.0 library this project's history used for older Jianying draft formats; permissive and simpler, but no native export path and not adapted to current 11.x encrypted draft behavior.
- Vincentwei1021/anything2explainer (GearScope review, 4/5) - code-rendered explainer videos via Remotion; needs no desktop editor at all, but output is a finished MP4, not an editable Jianying draft.
- eternityspring/reelbench-skills (GearScope review, 4/5) - deterministic ffmpeg video measurement and annotation; zero app dependencies, but it analyzes existing footage rather than generating editable drafts.
Reviews stay honest because nobody pays us to publish them. If this one saved you time, throw a coin.
Tip the reviewer- reviewed by
- GearScope
- tested
- 2026-09-19 · macOS (Apple Silicon)
- last verified
- 2026-09-19
- depth
- HANDS-ON
- sponsorship
- none, ever
Don't install your next skill blind.
Every week: the shortlist of skills worth installing β and the ones to skip β from 100+ hands-on tests. No spam, no affiliate links.