qiaomu-cut-skill: an agent-native video director that plans, sources and renders

The gap qiaomu-cut fills between a chat answer and an actual edit

Ask a general assistant for a video and you get suggestions. You still have to find footage, check rights, install ffmpeg, write subtitles, choose transitions and verify the output encoding. qiaomu-cut is built around the claim that those steps belong in one reproducible project rather than in a conversation.

The target user is someone working inside an agent environment who wants the agent to produce a video project, not advice about one. The README frames it as a "source-aware, renderer-ready, verifiable video project." That phrasing matters: the deliverable is a project directory with a timeline, an assets manifest and provenance, and the render is one step inside it.

It is not a timeline editor with a GUI, and the README never presents it as one. It is a skill that an agent invokes, plus a CLI (`scripts/qcut.js`) that the skill and a human can both call. If you want to drag clips around, this is the wrong shape of tool.

QiaoCut IR and the routing decision that follows it

The mechanism starts with an intermediate representation. A one-line request becomes a QiaoCut IR covering duration, aspect ratio, audience, style, shot breakdown, asset strategy and renderer. Everything downstream reads that IR rather than reinterpreting the original sentence.

From the IR, the skill routes to whichever engines the environment actually has: the 33台词 app for film dialogue, ClipSeek or Pexels or Pixabay for stock, local files, ListenHub and MarsWave for images, video, TTS, voice and music, Coli for local ASR, agent image generation, and HTML, Manim or PPT paths. Rendering is done by ffmpeg-full.

The honest part of the README is the list of what v0.5 actually implements: project timeline rendering, three-layer bilingual ASS subtitles, mobile large-type and platform safe areas, twenty brand intro and outro templates, a no-scale fast outro, sentence-boundary cutting rules, an asset file and scene deduplication gate, macOS and file-based narration, programmatic music, original-audio mixing, three render profiles, layered acceptance checks and in-project caching. HTML video capture, Manim and PPT direct output, complex masks, speed ramps and a full transition library are described as workflow interfaces and extension directions, not as shipped features. Read that paragraph before you plan around the tool.

Installing qiaomu-cut-skill and running a first plan

The README gives a one-line install through the skills CLI. It fetches the skill into your agent skills directory.

npx skills add joeseesun/qiaomu-cut-skill --skill qiaomu-cut

For local development or a manual install, the README shows copying the directory into `~/.agents/skills`. After either route, the documented verification step is the doctor command, which reports local capabilities as JSON.

node ~/.agents/skills/qiaomu-cut/scripts/qcut.js doctor --json

The prerequisites list is specific. Node.js 18+ is the floor; ListenHub provider work needs Node.js 20+ and a check of `scripts/bootstrap_listenhub.sh --check`. On macOS, Homebrew is recommended and `scripts/bootstrap_macos.sh --install` installs ffmpeg-full. The script does not overwrite your system `ffmpeg`; at runtime the skill prefers `QIAOMU_FFMPEG`, then `/opt/homebrew/opt/ffmpeg-full/bin/ffmpeg`, then `/usr/local/opt/ffmpeg-full/bin/ffmpeg`, then plain `ffmpeg`.

A first real use is planning rather than rendering. The README's example asks for a 60-second excavator English-learning video.

node scripts/qcut.js plan "做一个 60 秒挖掘机英语启蒙视频" --workflow sto

The plan step is where the visual bible is produced: a palette, era and material, camera and composition, lighting, contrast, texture, typography, characters and negative constraints, plus a visual bible ID and prompt prefix. Generated images must carry that same ID back into the manifest, through `qcut ingest --visual-bible-id <id> --prompt <prompt> --seed <seed>` for local files or the same parameters on `qcut fetch` for URLs. That is the consistency mechanism, and it only works if you keep the ID attached.

The submit, poll and fetch loop for generated footage

Remote generation is where the skill's governance shows. The README describes a closed loop: submit a task, poll it and save a private capture, then fetch the result and write it into the assets manifest.

node scripts/qcut.js listenhub openapi video create \
  --prompt "slow cinematic push-in on an excavator at dawn" \
  --model doubao-seedance-2-pro --resolution 720p --duration 5 --ratio 16:9 \
  --no-wait --json --qcut-project ./excavator-video --yes

Because this uses the API key route, the command must be `openapi video`. The README is explicit that configuring an API key does not grant OAuth state to the top-level `listenhub video ...` internal route; that route requires `listenhub auth login`. The two are separate authentication namespaces.

Poll with the returned task ID. A read-only `get` with `--qcut-project` also saves a private result capture.

node scripts/qcut.js listenhub openapi video get TASK_ID_FROM_SUBMIT \
  --json --qcut-project ./excavator-video

Then localize the temporary URL from that poll capture into the manifest.

node scripts/qcut.js fetch ./excavator-video \
  --result .qiaocut/jobs/listenhub/<poll-capture>.json \
  --field result.videoUrl --kind video --provider listenhub --json

The downloader is the most defensible piece of engineering described here. It only allows HTTPS, blocks private and loopback addresses, limits redirects and size, checks Content-Type and media magic numbers, and writes with a temporary file plus atomic no-clobber rename. It does not write temporary URLs into the manifest. Captures live only under `.qiaocut/jobs/listenhub/` with `0600` permissions, and the terminal prints a redacted summary. Cost-bearing operations require `--yes` and `--qcut-project`; referencing local media also requires `--allow-upload`.

Narration, subtitles and the places where the tool stops

The default narration strategy is opinionated. Narration audio prefers ListenHub with a speaker named 向阳乔木, and the README tells you to use the closed-loop command rather than assembling a speaker ID by hand.

node scripts/qcut.js listenhub narration \
  --text-file scripts/narration.txt \
  --qcut-project ./excavator-video --yes --json

The command performs a read-only speaker list, does an exact local match on the name, calls TTS, verifies the audio signature and container, imports into `assets-manifest.json`, cleans staging and returns a `timelineNarration`. Output defaults to lossless WAV to avoid decoding MP3 and re-encoding AAC; `--format mp3` is available when space matters. If the speaker is missing, ambiguous, unauthorized or the call fails, the command stops rather than substituting another voice. That is the right failure mode, and it also means the default path is brittle in exactly the way a named voice is brittle.

The cost story is incomplete by the project's own admission. The README states that the current OpenAPI TTS has no verified estimate subcommand, so you must be told the cost is unknown and give a per-call `--yes`; pseudo-confirmations like `--yes=false` are rejected. That is a real limitation, not a footnote.

Local ASR is the escape hatch: `node scripts/qcut.js listenhub asr assets/interview.wav --model sensevoice --json --qcut-project ./excavator-video` costs no ListenHub credits, but the README describes it only as full-text transcription and explicitly does not claim word-level subtitle alignment. If you need karaoke-style timing, this is not the tool for it. The first ASR run may download roughly 60 MB.

Render profiles and what a preview actually proves

Rendering is staged: `preview` for fast iteration, then `standard` or `final` once content is locked. The package scripts expose them directly.

npm run render:preview
npm run render:standard
npm run render:final

The output is described as matching the profile, with a contact sheet, cache-hit information, stage timings and quality-check data. The caching is project-local, and the deduplication gate operates on asset files and scenes, which is the mechanism that keeps a re-render from silently pulling in a near-duplicate clip.

The three-layer bilingual ASS subtitle system, mobile large-type sizing and platform safe areas are implemented, per the README. What is not implemented in v0.5 is the transition library and speed ramps, so a request that depends on them will fall back to interface-level handling rather than a built-in effect. The `release-check` script chains vendor verification, bilingual typography, brand templates, sentence boundary and release checks, which suggests the project treats those as its regression surface. It also tells you what the maintainers consider likely to break.

Alternatives and the difference in approach

The closest comparison is a general-purpose editing library driven by ffmpeg, such as the various Node or Python wrappers that expose filter graphs. Those give you a rendering primitive and leave sourcing, rights checking, subtitle layering and provenance to you. qiaomu-cut sits one level above: it assumes an agent is making the decisions and therefore invests in the IR, the routing table and the manifest, which a filter-graph wrapper has no reason to include.

A second comparison is a cloud video-generation API used directly. That gives you a task ID and a URL, and the rest is your problem. The qiaomu-cut loop wraps the same class of API with capture files, redaction, HTTPS-only download and manifest provenance. If you are already comfortable writing that plumbing yourself, the wrapper is overhead.

A third is a template-driven renderer where you fill in a JSON file and get an MP4. That is more predictable than an agent choosing shots, and it is the better choice when the video structure is fixed. qiaomu-cut is aimed at the opposite case, where the structure is derived from a sentence and the value is in the derivation being inspectable.

Maintenance, licence and what to check before you depend on it

The repository is not archived and the last push was on 2026-07-19. The package version is 0.5.0 and the package is marked private, so this is not a published npm library you resolve by version range; the install path is the skills CLI or a directory copy. There are no releases retrieved, so version pinning happens through the repository state you copy.

Upgrade cost concentrates in the vendored dependencies. The bootstrap script pins `@marswave/listenhub-cli@0.0.15` with protocol version `0.1.0` and `@marswave/coli@0.0.20`. The script does not run `npm view` and does not follow `latest`; `--check` fails on a missing package, an unverifiable package name or a version mismatch, and `--install` performs exact-version installs. Upstream drift is therefore a manual event, and `vendor:verify` exists to detect it. If you depend on ListenHub behaviour, that pinned snapshot is the compatibility boundary you are actually testing against.

The licence is MIT. The repository also carries a `THIRD_PARTY_NOTICES.md` file, which is where the obligations of the vendored and referenced components are collected. Whether your use of the 33台词 adapter, the stock providers or the MarsWave CLI creates separate obligations is a question for your own review; the README notes that the `33tc` CLI adapter must be separately installed and authorized, and that credentials should not be placed in the command, the project or the repository. The doctor command checks that both credential file types are regular files with permissions no wider than `0600`.

Editorial conclusion

Adopt qiaomu-cut if you already run an agent environment with Node.js 18+ and macOS tooling, and you want the planning, sourcing and rendering steps recorded rather than improvised. Do not adopt it if you need HTML capture, Manim or PPT output today, since the README lists those as interfaces and extension directions rather than built-in features. Before committing, run the doctor command and check that ffmpeg-full resolves through QIAOMU_FFMPEG or the Homebrew paths, because the renderer is the one dependency the skill cannot route around.

Frequently asked questions

Official sources

1. Issues
2. joeseesun/qiaomu-cut-skill on GitHub
3. License: MIT
4. README