qiaomu-cut: Agent-Native Video Production as a Reproducible Engineering System

The Problem qiaomu-cut Solves in Agent-Driven Video Work

A typical AI assistant responding to a video request produces editing suggestions. The actual work, finding footage, verifying copyright status, installing encoding tools, writing subtitle files, and adjusting transitions, still falls on the user. qiaomu-cut reorganizes that work into a system an agent can execute, verify, and resume.

The skill generates a QiaoCut IR (Intermediate Representation) from the user's request. This document captures duration, aspect ratio, audience, style, shot plan, material strategy, and the chosen rendering engine. All downstream steps follow from the IR, making the production reproducible: another run with the same IR produces the same output structure, and a stalled pipeline can resume from its last completed stage without resubmitting paid sourcing tasks.

The README lists representative requests the skill is designed to handle: building a 60-second educational video from free stock footage, editing a talking-head clip into a platform-specific vertical format with dynamic captions, making a cinematic character short from reference photos and a timeline, or producing a code-driven motion graphics showreel synchronized to a beat grid. These span quite different workflows, and the skill handles them by routing each one through the appropriate subset of sourcing, rendering, and verification commands.

Material Sourcing and Rendering Architecture

Once the IR is written, qiaomu-cut routes material acquisition to whichever providers are available in the local environment. The README lists 33tc (a licensed TV and film dialogue tool), ClipSeek, Pexels, Pixabay, local files, ListenHub for images and video, MarsWave for TTS and voice, and Coli for local ASR. Image generation can be delegated to whatever image generation capability the current agent environment provides.

Rendering passes through ffmpeg-full as the default synthesizer, with optional paths to HTML and HyperFrames-style scene capture via headless Chromium, Manim for mathematical animations, and PPT or slide-based output. The three render tiers let the agent run cheap iterations before committing to a full-quality encode: preview for fast feedback, standard for content review, and final for delivery. A contact sheet and SHA audit trail accompany each rendered output so the agent or the user can verify what source material was used and at which quality level.

The skill also includes a film and TV English mix workflow (`qcut english-mix`) for building language learning videos from licensed dialogue clips. The workflow covers phrase matching, boundary trimming, audio fade timing, and a batch scene renderer that processes all title cards in a single headless Chrome session.

Installing the Skill and Verifying Dependencies

The one-line install adds the skill to an agent that supports the skills protocol:

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

For local development or manual installation, copy the directory instead:

mkdir -p ~/.agents/skills
cp -R qiaomu-cut ~/.agents/skills/qiaomu-cut

After installation, the doctor command reports which of ffmpeg-full, Chinese subtitle fonts, Playwright with Chromium, Manim, and ListenHub CLI are present and which are missing:

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

The setup command is idempotent. Components already installed are skipped; missing ones are installed via Homebrew on macOS or apt on Linux. Playwright installs into the skill's own `.deps/` directory to avoid interfering with system packages. When an agent encounters a missing dependency during a task, it can run setup automatically and continue without requiring manual intervention.

The bootstrap script for macOS installs ffmpeg-full without overwriting the system ffmpeg. At runtime, the skill checks for the binary in order: `QIAOMU_FFMPEG` environment variable, then the Homebrew paths at `/opt/homebrew/opt/ffmpeg-full/bin/ffmpeg` and `/usr/local/opt/ffmpeg-full/bin/ffmpeg`, then falls back to the system `ffmpeg`.

Motion Design Studio Added in v0.13

Version 0.13 adds a code-driven motion design workflow under the `qcut motion` command. The README states this was built with reference to 54 code-generated video examples and introduces a hard-gate methodology: shot descriptions must be written before code, beat grid alignment must be verified, and HTML scenes must use a deterministic `seek(t)` pure function rather than real-time animation state.

The workflow initializes a project with a motion brief, a beat grid derived from an audio file, a starter scene file, and a companion motion library:

node scripts/qcut.js motion init ./promo --style product-promo --audio assets/song.mp3 --json

Seven style presets are available: product-promo, ui-morph-loop, showreel, line-art-explainer, lyric-mv, pixel-art, and cinematic-3d. A check command validates that shots are written before code, that cut points land on beats, and that the deterministic lint passes before rendering begins. A separate audio analysis command extracts BPM, downbeats, and per-bar energy from any audio file:

node scripts/qcut.js audio beats assets/song.mp3 --output reports/beat-grid.json --json

Capture uses headless Chromium with CSS and Web Animations set at specific frame times. PNG buffers pass directly into ffmpeg via image2pipe without creating a per-frame PNG directory on disk, which avoids large intermediate storage use for longer animations.

What qiaomu-cut Cannot Do Without External Setup

The README is direct about current boundaries. PPT direct output, complex compositing masks, speed ramp effects, forced word-by-word subtitle alignment, and a more complete transition library are described as external capabilities that the skill does not claim to have built in. Mixing manual inpainting with a text prompt in the video mask mode is noted as unreliable in the author's testing; the README recommends picking one approach per mask operation.

The 33tc CLI adapter, which enables searching licensed film and TV dialogue, must be separately installed and requires a 33tc account with the desktop app running and logged in. The skill will not silently submit paid tasks: the `pick` and `cut` commands require explicit confirmation with `--yes` before any action that could consume account credits. If a download fails after a task ID has already been created, the correct path is to run the download resume command with that task ID rather than resubmitting.

ListenHub credentials use two separate authentication namespaces for the OpenAPI path and the OAuth path. The doctor command checks that credential files exist with permissions no wider than 0600 and will fail if they are absent or improperly secured.

Maintenance, Version History, and License

The last push was on 2026-09-28 and corresponds to v0.13.0. The release notes for this version describe the code motion design studio as the primary addition, along with a `qcut setup` command that handles dependency installation on first use. Earlier releases in the sequence added features including the English mix fast path, ListenHub integration, the 33tc adapter with bounded reconnect logic, and the vertical explainer pipeline with cognitive timing contracts.

The project is licensed under MIT. Vendor packages installed by the bootstrap scripts are pinned at specific versions: ListenHub CLI at 0.0.15 and Coli at version 0.0.20. The install script does not follow the npm `latest` tag, which prevents silent version drift in the vendor layer. Third-party license information is documented in THIRD_PARTY_NOTICES.md in the repository root.

Editorial conclusion

qiaomu-cut suits developers and content creators who already work with AI agents and want video production organized as a verifiable, resumable engineering pipeline rather than a series of manual steps. It is not a consumer video editor and requires Node.js, ffmpeg-full, and optional third-party CLI tools before the first render works. Before committing to it, run `node scripts/qcut.js doctor --json` to see which dependencies are present; the setup command installs most of them automatically, but the 33tc CLI adapter and ListenHub credentials must be obtained separately.

Frequently asked questions

Official sources

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