v0.14.0

Five features in one release — the next slice of the opportunity backlog, bundled. Two build on prior art from the capcut-cli-david fork (thanks @Davidb-2107). The sixth backlog item, keyframeable mask geometry (#44), is deliberately not in this release: no public ground truth exists for the on-disk encoding, and a guessed encoding would silently no-op in the app — it ships once a real app-authored mask-keyframe draft is captured.

Added

• duplicate <project> <segment-id> [--track <track-name>] [--new-track] — duplicate a segment at the SAME timeline position and duration onto a track that renders above the source: the PIP local-retouch flow from #44 (copy the clip above itself, then mask the copy) without hand-editing JSON. By default — and with the explicit --new-track — the copy goes onto a fresh track of the same type inserted directly after the source track in the tracks array: sortTracks is stable within a type and a later same-type track renders above, so the copy sits exactly on top of its source (a second copy gets a unique <name>-copy-2 track name). --track <track-name> places the copy onto that existing same-type track instead, and exits 1 with a clear error when the target range is occupied there, when the track is missing, or when its type does not match the source segment's; --track and --new-track together are rejected. ID hygiene: the new segment gets a fresh id; the source material entry — media included — is cloned with a fresh id (the media FILE on disk stays shared), so material-level edits on the copy (crop, mix-mode, replace-media) never leak to the source segment underneath it; every per-segment companion referenced via extra_material_refs (speed, placeholder_info, sound_channel_mapping, vocal_separation, canvas, material_color, masks, animations, ...) is cloned the same way — the app treats those as per-segment instances, so two segments never share one. Embedded keyframe list/entry ids are re-minted on the copy. The timeline duration is unchanged. Prints { new_segment_id, track_name, cloned_materials } plus the copy's material_id, track_id, and new_track; mutating, atomic save with .bak + history snapshot, honors --dry-run.
• register <project-dir> [--apply] [--drafts <dir>] — the meta-repair sidecar for EXISTING drafts. init registers only the drafts it creates, so an existing folder missing its draft_meta_info.json sidecar or its entry in the store's root_meta_info.json is invisible to the CapCut app with no repair path (doctor checks the environment, diagnose is read-only). register derives id/name/duration from draft_content.json — a read-only source that is never written — and reports per target (needs_repair, per-target state/action/detail/stale_fields). Accepts the project directory or its draft_content.json path (any other filename exits 1). Plan-only by default (always exit 0); --apply recreates a missing/corrupt sidecar and inserts/updates the index entry — new entries clone the shape of an existing entry so they match the installed CapCut version, updates repair only the stale identifying fields (draft_id, draft_fold_path, draft_json_file, draft_root_path, tm_duration) in place and preserve everything else, including a non-empty draft_name (CapCut's display name is user data). Writes are atomic (temp+fsync+rename) with a .bak per file that already existed; applied / backups list exactly the files written. Idempotent: a re-run writes nothing and reports applied: [], exit 0. The store root is the draft's parent directory and must be known — a root_meta_info.json beside the draft folder, a managed com.lveditor.draft path (init's default location), or an explicit --drafts <dir> (which, like init, creates the index on a fresh store); a draft outside any known store root is reported explicitly and nothing is written. An unreadable root_meta_info.json is never rewritten (it lists every draft) and is reported blocked instead. --apply refuses while the editor is running and when a target changed on disk since the plan read, unless --force-write; --apply --dry-run previews (would_apply, applied: []). Exits 2 on --apply when a target stays blocked (unknown store root, unreadable index). diagnose now recommends the register plan form when it sees draft_meta_info.json missing.
• crop <project> <segment-id> [--ratio <r> | --rect <x,y,w,h> | --reset] — read and set the crop on a video/photo segment's source material: the 8-corner normalized struct CapCut stores on materials.videos[], which the factory wrote full-frame at creation and no command could read or edit before. With no flags the command is read-only: it prints the material's crop struct as JSON plus the stored source width/height (crop is null when the material carries none) and writes nothing. --ratio <free|1:1|16:9|9:16|4:3|3:4> computes the centered maximal crop of that aspect against the source dimensions stored in the draft — when the dims are missing or zero it exits 1 with an error that points at --rect (free restores the full frame without needing dims). --rect <x,y,w,h> sets an explicit normalized rect, all values 0..1 fractions of the source frame, validated as x,y >= 0, w,h > 0, x+w <= 1, y+h <= 1 (a float-ulp tolerance keeps sums like 0.3 + 0.7 valid, and the written corners are clamped to 1); --rect overrides --ratio when both are given. --reset restores the full frame. The corner mapping matches the factory default exactly — y grows downward: upper_left = (x, y), upper_right = (x+w, y), lower_left = (x, y+h), lower_right = (x+w, y+h). When the material carries a crop_ratio field it is stamped "free" — CapCut's preset enum values are not published, so the app recomputes from the corner points; stated in --help. Mutating command: registered in the mutating set, writes atomically with a .bak snapshot like its siblings, honors --dry-run, and prints the resulting crop JSON on write. The new --ratio/--rect/--reset flags are release-scoped to crop, so free-text positionals of other commands containing those substrings survive verbatim.
• caption / import-srt — per-word keyword emphasis and per-cue colour cycling as ergonomic flags, replacing hand-written --styles JSON for the viral-caption workflow (prior art: capcut-cli-david --keyword-size v1.15 and import-captions --color-cycle):
  • --highlight-words <w1,w2,...|@file> — case-insensitive whole-word matches per cue get an emphasis text range; @file reads one word/phrase per line (phrases match across spaces). Word boundaries are Unicode-aware, so für matches in Grüße für alle but never inside fürs, and cap never matches inside capcut. Overlapping matches (e.g. New York + York) keep the earlier one.
  • --keyword-color <#RRGGBB> — emphasis colour; defaults to #FFD700, the same gold caption --karaoke paints the active word with (now the shared KARAOKE_HIGHLIGHT_COLOR constant). Requires --highlight-words.
  • --keyword-size <multiplier> — emphasis size as a multiplier on the cue's base font size (style-ref/preset/--font-size aware), default 1.2 when --highlight-words is present. Validated: must be > 0 and <= 10. Requires --highlight-words.
  • --color-cycle <#hex1,#hex2,...> — rotates the BASE text colour per cue in list order, wrapping around; an independent axis from keyword emphasis. Precedence: explicit --color still sets the base colour for all cues unless --color-cycle is given (then the cycle wins per cue).
  • Precedence contract (documented in --help): keyword emphasis ranges sit on top of base/karaoke styling and override the matched words' colour/size; with --karaoke, karaoke ranges are built first and keyword matches override those words while inheriting their bold — the v0.13 "explicit flags beat preset ranges" spirit.
  • One offset scheme. Emphasis ranges are computed in the exact code-unit → UTF-16LE-byte scheme text-ranges/setTextRanges and the karaoke writer already use — correct for multibyte text (umlauts, CJK); no second offset scheme was introduced.
  • The four flags are release-scoped like the v0.13 parser additions: on commands that don't declare them (everything except caption and import-srt) the tokens fall through to free-text positionals verbatim.
  • JSON output gains keyword_matches / color_cycle only when the flags are used; with no flags, behaviour and output are byte-identical to v0.13.

Fixed

• Every user-supplied text/JSON read now tolerates a leading UTF-8 BOM (U+FEFF), the byte prefix Windows PowerShell's Set-Content (and some editors) writes — previously the draft failed to load with a JSON parse error, .capcutrc was silently ignored, and the SRT/ASS/JSONL parsers misread the first token. Covered paths: draft_content.json / draft_meta_info.json / root_meta_info.json and every other draft store candidate, --preset files, @file arguments (e.g. text-ranges --styles @ranges.json, --highlight-words @words.txt), stdin (import-srt -, import-ass -, batch, keyframe --batch JSONL), subtitle files (import-srt, import-ass, quickstart --srt, compile captions ops), compile specs, template files, and .capcutrc. The CLI never writes a BOM: saving a BOM'd draft drops it (atomic write, .bak and history snapshots preserve the loaded content), the concurrent-change guard no longer reports a BOM-only difference as "changed on disk", and fixture bundles are emitted BOM-free. Output for BOM-free files is byte-identical to before. Prior art: capcut-cli-david eb2f0e0 (thanks @Davidb-2107).

v0.13.2

Documentation

• Wider README hero / media/og-card.png banner (1280x640, 2:1) replacing the 0.13.1 card. Docs-only release; no code changes.

v0.13.1

Documentation

• Refreshed the README hero / media/og-card.png social card (EN + zh reference the same asset). Docs-only release; no code changes since 0.13.0.

v0.13.0

Six features in one release — the top of the opportunity backlog, bundled. Two build on prior art from the capcut-cli-david fork (thanks @Davidb-2107); see #36.

Added

• sync-timelines <project-dir> [--apply] [--force-write] — reconcile a CapCut >= 8.7 draft whose template-2.tmp / draft_info.json timeline mirror has drifted from draft_content.json, so CLI edits are honored by the app instead of silently ignored. draft_content.json is always canonical and is treated read-only. Accepts only a project directory or its draft_content.json (any other filename exits 1). Plan-only by default: the per-target drift report includes each mirror's mtime plus newer_mirrors / canonical_stale, and warns when draft_content.json is older than a drifted mirror (you would overwrite newer edits). --apply refuses that direction unless you add --force-write (exit 1), then rewrites only the drifted mirrors — the canonical file is never re-sorted or backed up, and in-sync mirrors are left untouched; reconciled / backups list exactly the files written. No-ops with exit 0 when all targets already agree. An unreadable (binary/encrypted) mirror is reported unreconcilable (ok:false, in_sync:false, exit 2) and stays idempotent on re-run instead of pretending success. --apply --dry-run reports the plan only (would_reconcile, reconciled: []). diagnose now recommends the plan form (with a back-up caution) instead of deferring to issue #35. Closes #39.
• lint <project> --fix — auto-repair mechanically-fixable draft defects, now four codes: cue-too-long (trims over-long captions to the configured cap), caption-overlap (shortens overlapping pairs so each ends where the next begins), line-too-long (greedy word wrap that swaps spaces for newlines 1:1, keeping styled-range byte offsets valid; never splits words — instances the wrap cannot actually fix, i.e. space-less/CJK text and over-cap single words, are stamped fixable:false), and caption-gap-too-small (pulls the earlier caption's end back to restore the minimum gap; never moves starts, never creates a new overlap). The gap repair honors a hard floor — exported MIN_CAPTION_DURATION_US = 100_000 (100ms) — so a shrink that would land a caption below the floor is skipped and stamped fixable:false for that instance instead of collapsing it. Writes atomically with a .bak snapshot; combine with --dry-run to preview. missing-material and missing-file stay report-only deliberately: the only mechanical repairs would delete user timeline content or act on host-dependent paths. Closes #40.
• lint — new report-only rule unknown-effect-slug (info severity, exit 0): flags effect/filter/animation resource ids in the draft that are not in the bundled enum table, surfacing them before CapCut silently drops them (the silent-failure mode reported across ecosystem tools, e.g. GuanYixuan/pyCapCut#12). Info rather than warning because store-downloaded effects on app-authored drafts are legitimate; only CLI-written stale slugs are at risk.
• export-srt <project> [--granularity line|word] [--format srt|vtt] — word-level caption export. Captions created by caption --karaoke carry real per-word timing and export it exactly; plain captions interpolate word timing proportionally by word length (stated in --help). SRT + word emits one cue per word; VTT + word emits one cue per phrase with inline <hh:mm:ss.mmm> karaoke timestamps for burn-in pipelines. Defaults (line, srt) reproduce the previous output byte-identically.
• keyframe ... --easing <linear|ease-in|ease-out|ease-in-out> — CapCut-native easing curves, also accepted per-line (easing key) in keyframe --batch JSONL and in the compile spec's keyframe op. The app does not store named curve types: the UI writes FreeCurveInOut bezier control handles on both keyframes of the eased segment, and the emitted encodings are locked against a UI-oracle capture (prior art: capcut-cli-david). The ken-burns skill default changed linear → ease-out to match what the CapCut UI itself produces.
• detect-scenes <video> [--threshold <0..1>] [--min-gap <s>] [--limit <n>] [--json] — deterministic ffmpeg scene-cut detection (no AI, zero new dependencies) to seed the long-form → shorts flow: prints detected cut points (seconds, hh:mm:ss.mmm timecode, scene score) plus a ready-to-use contiguous segment list in seconds and draft-native microseconds. Follows the probe/render external-binary pattern, including a clear actionable error when ffmpeg is missing.
• make-preset <project> <text-segment-id> --out <preset.json> — extract a hand-tuned text style (font, colors, style flags, alignment/transform, bubble, karaoke/multi-style ranges) from an existing draft into a versioned, portable preset file; apply it with the new --preset <file> flag on add-text, text-style, and caption. Addresses the recurring ecosystem ask for programmatic font/style reuse (GuanYixuan/pyJianYingDraft#192, Hommy-master/capcut-mate#57). Contract:
  • Explicit flags beat the preset — including its ranges. --color / --font-size override every captured text_ranges block over the covered span, not just the base style, so a karaoke/highlight preset re-renders in the flag color/size; applying the same preset without those flags preserves the per-range styling.
  • Presets are schema-validated on load. transform must be an object with finite numeric x/y, bubble must carry non-empty effect_id/resource_id, text_ranges must be an array of objects with integer start/end where end > start and correctly typed style fields. A malformed preset is rejected with a clear error and is never written into the draft.
  • Rangeless preset onto a multi-range segment collapses the ranges. Applying a preset that carries no text_ranges onto a segment that still holds multiple range blocks (leftover karaoke/highlight) collapses them to the single uniform preset style spanning the whole text — consistent with the "applies the full preset" contract. A preset that itself carries ranges applies them unchanged. Documented in --help.
  • make-preset --dry-run writes nothing — the --out file is neither created nor overwritten, and the JSON output reports dryRun:true with written:false (a normal run reports written:true).
• Parser: the value-consuming flags introduced in this release (--threshold, --min-gap, --limit, --json, --granularity, --format, --easing, --preset, --apply) are scoped to the commands that declare them instead of being consumed globally, so free-text positionals that contain a flag-like substring survive verbatim (e.g. add-text ... New Year --limit 5 drinks stores the literal text). Flags that earlier releases already parsed globally are unchanged.

Documentation

• docs/version-support.md — the CapCut 8.7 row now names sync-timelines as the repair path for drifted mirrors.
• docs/draft-schema/03-keyframes-and-animations.md — documents the FreeCurveInOut bezier-handle easing encoding.

v0.12.0 — quickstart, replace-media, fixture bundle

Added

• quickstart <name> [--video <f>] [--audio <f>] [--srt <f>] — the one-command path from a single file to an editable draft. Creates the draft, adds the input (durations from ffprobe when available, a 5s placeholder otherwise), lints it with the same checks as lint, inspects the storage layout like diagnose, and prints the exact open-in-CapCut step. Exit 0 when created and lint-clean, 2 when created with lint errors. Reduces first-run friction for a CLI that now has 50+ commands.
• fixture <project> --out <dir> — build a shareable, redacted compatibility bundle. Copies only the timeline JSON (never assets/ media), redacts user home paths and email addresses, and writes a reporter README plus a diagnose report. Automates the "attach a sanitized project folder" step in the version-support flow so reporters can safely contribute the real CapCut 8.7 (issue #35) fixtures the storage adapter still needs.
• replace-media <project> <segment-id> <new-file> [--retime] — swap a segment's source clip in place (placeholder/proxy > final render) while preserving its timeline position, timing, effects, and keyframes. Copies the file into assets/ and refreshes intrinsic duration/dimensions via ffprobe. Distinct from relink, which only repairs broken paths by basename. Warns when the new clip is shorter than the segment uses; --retime fits the segment to the new clip. Honors --dry-run (no write, no copy). This is the assemble-with-placeholders-then-swap-in-finals workflow that fits the CLI's local, deterministic, agent-drivable positioning.

Documentation

• docs/jianying-encryption.md — decision record for JianYing 6.0+ draft encryption: detect, do not decrypt, with the rationale (legal posture, algorithm in flux) and the tripwires that would reopen the decision. capcut decrypt now links to it.
• docs/version-support.md — the reporting flow and the CapCut 8.7 row now reference capcut fixture for one-command sanitized bundles.

capcut-cli v0.11.3

[0.11.3] — 2026-06-20

Documentation

• Synchronized the English and Chinese READMEs with the shipped v0.11 surface: version-aware storage, v0.11.2 Windows fixes, six templates, 13 enum categories, 205 tests, the full cross-platform CI matrix, and the current GitHub Action reference.

capcut-cli v0.11.2

[0.11.2] — 2026-06-20

Fixed

• Windows now resolves the bundled template and spawned serve CLI through proper filesystem paths instead of URL pathnames, fixing init, compile, and queued jobs on drive-letter paths.
• ESM test imports use file: URLs on Windows, and a single-file restore preserves the backup's exact bytes.
• The full Node 20 suite now passes on Windows, macOS, and Linux in GitHub Actions.

capcut-cli v0.11.1

[0.11.1] — 2026-06-20

Fixed

• GitHub Actions on Windows now uses Node's built-in test discovery instead of relying on POSIX shell expansion of test/*.test.mjs.

capcut-cli v0.11.0

[0.11.0] — 2026-06-20

A reliability and automation release spanning the full draft lifecycle. It closes the highest-value gaps found in the v0.10.1 repository audit while preserving the zero-runtime-dependency core.

Added

• CapCut 8.7+ draft store — version-aware discovery of draft_content.json, draft_info.json, draft_meta_info.json, and template-2.tmp, including nested/string JSON envelopes. Every readable timeline target is synchronized on write.
• diagnose — redacted storage report with canonical-file selection, hashes, timeline divergence, editor-process detection, and --bundle <report.json> output for compatibility reports.
• Command contract v2 — describe now exposes usage, typed positionals/options, defaults/enums, mutability, prerequisites, output form, and exit codes for every command. Help, completions, generated docs, and the typed runCommand() library API consume the registry.
• compile v2 — stable item refs, source timing, speed/volume/opacity/transforms, transitions, filters, effects, keyframes, audio fades, templates, SRT captions, text styles/ranges, plus --check / --plan validation without writes.
• Caption adapters + karaoke — explicit OpenAI Whisper, whisper.cpp, and faster-whisper dialects; word-timestamp parsing/grouping; --karaoke, --max-words, --max-chars, and --max-gap-ms generate time-varying highlighted caption segments.
• Full media probing — ffprobe duration, FPS, display rotation, dimensions, codecs, audio presence/channels, and a path+mtime cache. add-video, add-audio, and compile can infer omitted durations.
• Higher-fidelity proxy rendering — optional --all-video-tracks composition with transforms/opacity, audio fades, draft caption colour/size/position, explicit skipped-feature reports, and FFmpeg capability detection/fallbacks.
• Reliable serve runner — bounded async workers, per-project serialization, stable job-ID deduplication, retry/backoff, configurable timeout/output limits, and safe capture for outputs larger than 64 KiB.
• Cross-platform CI smoke matrix — Node 20 tests on Ubuntu, macOS, and Windows in addition to the existing Node 18/20/22 Linux matrix.

Changed

• Conflict-safe atomic persistence — writes are prepared and fsynced before same-directory rename, every synchronized target receives a backup/history snapshot, changed-on-disk drafts are refused, and managed drafts are protected while CapCut/JianYing is running. --force-write is the explicit override.
• Transactional batch — all operations validate against cloned state and commit once. Any failure writes nothing by default; --continue-on-error intentionally commits only successful operations and exits non-zero.
• doctor — now reports ffprobe and detailed FFmpeg filter/encoder capabilities alongside Whisper and project-directory checks.
• Lint gate — warnings now fail npm run lint; the existing lint debt was removed.

Fixed

• Large JianYing enum and serve results no longer truncate at the macOS 64 KiB synchronous pipe boundary.
• Proxy-render tests no longer assume every installed FFmpeg build includes drawtext; caption burn falls back cleanly when it is absent.
• Stale roadmap, version-support, Chinese README, skill reference, test-count, and release metadata claims were synchronized with the shipped surface.

v0.10.0 — render (proxy preview) + compile (declarative drafts)

Two commands that close the two biggest gaps in a headless CapCut workflow: seeing the result of an edit, and authoring a whole draft in one shot. No breaking changes; still zero npm-dep and JSON-by-default. ffmpeg is an opt-in shell-out (only when actually rendering), the same pattern caption uses for whisper.

Preview

• render — a low-res ffmpeg proxy preview of a draft, so you can watch an edit without opening CapCut. Flattens the main video track (per-segment source trim + speed), scales to a proxy size (--scale, default 0.5), mixes every audio-track segment, and optionally burns text in with --burn-captions. It is a preview, not CapCut's final render (no multi-track compositing/effects). The ffmpeg command is built by a pure, deterministic buildRenderPlan that is unit-tested without invoking ffmpeg; --dry-run prints that plan and needs no ffmpeg. Read-only.

  capcut render ./my-short --burn-captions       # -> ./my-short/preview.mp4
  capcut render ./my-short --dry-run             # print the ffmpeg plan, run nothing

Build

• compile — builds a whole draft from a declarative JSON spec (the inverse of describe): instead of chaining dozens of mutating add-* commands, emit one spec and compile constructs the draft atomically via the same factory functions the imperative commands use. Times in seconds; media paths resolve relative to the spec. The full spec is validated — and every media file checked to exist — before anything is written, so a bad spec fails clean. Writes both draft_content.json and draft_info.json so every downstream command reads the same data.

  capcut compile ./short.json --out ./my-short

12 new tests; full suite 171/171. Merged in #29.

Install: npm install -g capcut-cli@0.10.0