jianying-agent-cli (jy)

• Headless — no window, no clicks, no mouse. Runs on a machine nobody is watching.
• Agent-friendly — stdout is always one jy.v1 JSON object; ok is the single truth, errors carry a code and retriable. ffmpeg logs go to stderr.
• Honest output — every file-producing command re-probes its output with ffprobe, so ok:true means a real, playable file.
• 39 commands (56 with subcommands) — probe, trim, concat, speed, montage/beat cut, subtitles, ASS text animations, 50+ transitions, filters/LUTs, curves/HSL, chroma key, picture-in-picture, audio mix/ducking/loudnorm, local ASR, covers, GIF, batch export, background jobs.
• Two engines — jianying renders drafts through the 剪映 app you already have installed, with its real transitions, filters, effects, 花字 and text animations (fetched on demand); local (ffmpeg, offline, deterministic) for preprocessing or when you explicitly want no 剪映.
• Finds and fetches 剪映 materials — jy effects search-remote 推近 searches 剪映's full live material catalog (transitions, filters, effects, 花字, text animations, stickers; cached listings as offline fallback), jy effects fetch 推近 downloads the package into 剪映's cache (md5-checked, atomic), and a spec can just say "transition":{"name":"推近"} — jy draft build --fetch resolves and downloads by name.
• Speaks 剪映 — jy transition --type 叠化, jy filter --preset 日系: Chinese 剪映 names resolve to a local implementation and report how close they are (fidelity: exact | close | rough).
• Zero Python dependencies — standard library + ffmpeg. Ships an agent skill so your agent knows how to use it.

git clone https://github.com/risingjerry/jianying-agent-cli.git && cd jianying-agent-cli && python3 install_global.py

Needs Python 3.9+ and ffmpeg. brew install ffmpeg-full is recommended (libass for subtitles/text, x264/x265, zimg); plain ffmpeg works and jy degrades per capability instead of pretending. The installer symlinks jy into ~/.local/bin (an existing non-jy file there is moved to jy.bak-<time>, never deleted). Then:

jy doctor     # ffmpeg builds + capability matrix + 剪映 engine state

jy probe a.mp4 b.mp4                                   # codec / size / fps / duration / audio + concat compatibility
jy trim a.mp4 --start 4 --duration 8 -o seg.mp4
jy concat seg.mp4 b.mp4 -o rough.mp4                   # stream copy when specs match, otherwise normalised
jy transition a.mp4 b.mp4 --type 叠化 --duration 0.5 -o joined.mp4
jy text joined.mp4 --content "Title" --position top --animation slideup -o titled.mp4
jy subtitle titled.mp4 --srt subs.srt --style cinematic -o subbed.mp4
jy export subbed.mp4 -o final.mp4 --resolution 1080p --fps 30 --quality 20 --faststart
jy frame final.mp4 --at 50% -o check.jpg               # look before you ship

A failure is still one JSON object:

{"schema":"jy.v1","command":"export","ok":false,"outcome":"unknown","data":null,
 "error":{"code":"NOT_FOUND","message":"input not found: missing.mp4","retriable":false,"details":{}},
 "warnings":[],"meta":{"ffmpeg":"/opt/homebrew/opt/ffmpeg-full/bin/ffmpeg","elapsed_ms":3}}

The repo ships an Agent Skill (rules, the jy.v1 envelope, recipes, limits) plus a tool-agnostic AGENTS.md.

python3 install_global.py --with-skill     # copies the skill to ~/.claude/skills and ~/.agents/skills (backs up existing)
# or, with the skills CLI:
npx skills add risingjerry/jianying-agent-cli
# or by hand:
cp -r skills/jianying-native ~/.claude/skills/     # Claude Code
cp -r skills/jianying-native ~/.agents/skills/     # Codex and other Agent Skills hosts

Then just ask: "Cut these three clips into a 15-second vertical video with a title and subtitles." The agent calls jy, branches on ok / error.code, and checks frames before delivering.

Full reference: USAGE.md (Chinese) · jy <command> --help · docs/CLI-HELP.txt · long-form per-command notes in docs/REFERENCE.zh-CN.md.

             ┌── local engine ──▶ ffmpeg / ffprobe (argv lists, no shell) ──▶ out.mp4 (re-probed)
jy <verb> ───┤
             └── jianying engine ─▶ jy draft build ─▶ draft_info.json (plain JSON)
                                    jy render ─────▶ 剪映's local bridge (127.0.0.1, per-launch token)
                                                     ─▶ 剪映's own exporter ─▶ out.mp4 (re-probed)

• Local engine: picks the most capable ffmpeg on the machine, validates every parameter, builds filter graphs, and verifies the result.
• jianying engine: writes a timeline as a plain 剪映 draft and asks the running 剪映 app to export it through the localhost bridge it already exposes. No UI automation, no pointer movement. A focus guard hands the foreground back to your app if 剪映 raises its window. Protocol notes: docs/BRIDGE.md.
• jy itself makes no network requests. 剪映 may talk to its own servers (material downloads); that traffic is the app's.

How do I edit videos with Claude Code or another AI agent? Install jy and its skill (python3 install_global.py --with-skill), then describe the edit in plain language. The agent runs jy commands; each returns one JSON object, so it can check ok, read data.output (duration, size, codec) and retry only when error.retriable is true.

Can I automate 剪映 / CapCut without the GUI? Partly. Everything an ffmpeg pipeline can do runs without 剪映 at all. For 剪映's own materials, jy draft build + jy render hand a draft to the running 剪映 desktop app through its local bridge — no clicking, no window to drive — but 剪映 must be open and logged in.

Does it need a 剪映 VIP membership? No for the local engine — it does not use 剪映 at all. The 剪映 engine follows 剪映's own rules: VIP/SVIP materials need your membership, and jy reports which item was refused (BLOCKED). --on-entitlement local re-renders with local approximations and lists every downgrade.

Does it work with CapCut (international)? It targets 剪映专业版 for macOS (/Applications/VideoFusion-macOS.app). The local engine is app-independent. CapCut international has not been tested.

How does my AI agent learn to use jy? Through skills/jianying-native/SKILL.md (Claude Code, Codex and other Agent Skills hosts) and AGENTS.md (any agent that reads repo instructions). Both point to jy doctor and jy <verb> --help as ground truth.

Is it safe to run on my real projects? Outputs are never overwritten without --force, inputs are read-only, draft-management commands are dry-run unless --apply and back up 剪映's index first, and render only renders drafts jy created. The bridge token is never written to disk or logs.

Why not just call ffmpeg directly? You can. jy adds the boring, error-prone parts agents trip over: parameter validation, filter-graph escaping, capability detection, concat normalisation, output verification, a stable JSON contract and background jobs.

rm ~/.local/bin/jy
rm -rf ~/.claude/skills/jianying-native ~/.agents/skills/jianying-native   # if you installed the skill
rm -rf ~/.cache/jy                                                         # jobs and scratch drafts

Then delete the cloned folder. ~/Movies/jy-staging exists only if you used the 剪映 engine (jy clean --staging --apply removes it).

./tests/smoke.sh                     # end-to-end suite on synthetic media; 剪映 checks skip when the app is not running
JY_SMOKE_RENDER=1 ./tests/smoke.sh   # also run one real 剪映 export (needs 剪映 running)
python3 docs/render_demo.py          # regenerate docs/demo.gif + demo.mp4 with 剪映 running (--engine local: ffmpeg only); needs Chrome, ffmpeg, jq, gifsicle

This is an unofficial, independent tool. It is not affiliated with, endorsed by, or sponsored by ByteDance, 剪映 / JianyingPro or CapCut. All trademarks belong to their owners. The 剪映 engine only drives a copy of the app you installed and logged into yourself, within that app's own entitlement rules.

If jy saved you an afternoon of ffmpeg flags, a ⭐ helps other people (and their agents) find it.

MIT