Skip to content

joeseesun/qiaomu-cut-skill

qiaomu-cut

Verified

把一句话需求转成可复现、可验收视频工程的乔木智能剪辑导演。Use when the user asks to create, plan, edit, remix, explain, narrate, subtitle, animate, composite, or render a video—including one-line requests such as “制作一个科普视频:介绍 LLM 中的 RL”. Builds English-learning movie mixes, person profiles, explainers, code-drawn motion graphics (UI morph loops, showreels, kinetic-type promos, line-art/pixel/Three.js animation, lyric MVs), product launch videos, cinematic shorts, social clips, course/PPT videos, AI image/video/TTS/music-assisted stories, stock-footage stories, or multi-source montage. Routes across 33台词, ClipSeek/open media, local files, ListenHub, image generation, HTML/SVG/Canvas motion graphics with beat-grid storyboards and determinism probes, Manim, ffmpeg-full, captions, sound design, frame-0 video covers with YouTube thumbnails, and release checks.

FileKindSize
SKILL.mdskill md54.0 KB
agents/interface.yamlconfig17.2 KB
agents/openai.yamlconfig323 B
assets/explainer-social/base.cssother24.9 KB
assets/explainer-social/component-runtime.jsscript41.1 KB
assets/explainer-social/scene-shell.htmlother829 B
assets/motion-kit/qiaocut-motion.jsscript8.2 KB
assets/qiaomu-profile/qiaomu_avatar.jpegbinary5.6 MB
assets/qiaomu-profile/qiaomu_reward_qr.pngbinary515.9 KB
assets/qiaomu-profile/qiaomu_wechat_public_account_qr.jpgbinary8.3 KB
references/ad-concept-library.mdmarkdown6.5 KB
references/aesthetic-preferences.mdmarkdown3.0 KB
references/brand-card-templates.mdmarkdown1.6 KB
references/chinese-font-themes.mdmarkdown804 B
references/cinematic-techniques.mdmarkdown2.8 KB
references/code-motion-direction.mdmarkdown11.1 KB
references/cover-thumbnail-method.mdmarkdown6.4 KB
references/english-mix-fast-path.mdmarkdown6.0 KB
references/explainer-autopilot.mdmarkdown11.1 KB
references/feedback-evolution.mdmarkdown37.6 KB
references/ffmpeg-full.mdmarkdown1.7 KB
references/incremental-production.mdmarkdown4.4 KB
references/licensing.mdmarkdown1.9 KB
references/listenhub-provider.mdmarkdown12.6 KB
references/motion-prompt-patterns.mdmarkdown9.3 KB
references/movie-montage-fast-path.mdmarkdown4.4 KB
references/qiaocut-ir.mdmarkdown4.2 KB
references/renderer-engines.mdmarkdown3.3 KB
references/schemas/qiaocut.timeline.v1.schema.jsonconfig7.2 KB
references/social-safe-zones.mdmarkdown3.3 KB
references/source-adapters.mdmarkdown5.7 KB
references/source-selection-gate.mdmarkdown2.5 KB
references/styles/cinematic.mdmarkdown475 B
references/styles/explainer.mdmarkdown1.5 KB
references/styles/social-short.mdmarkdown383 B
references/timeline-schema.mdmarkdown12.2 KB
references/trust-boundary.mdmarkdown3.0 KB
references/workflows.mdmarkdown7.5 KB
scripts/adapters/33tc.jsscript2.1 KB
scripts/adapters/33tc_cli.jsscript4.8 KB
scripts/adapters/clipseek.jsexecutablescript5.4 KB
scripts/adapters/listenhub.jsscript35.7 KB
scripts/adapters/listenhub_cli.jsexecutablescript2.1 KB
scripts/adapters/local.jsscript2.4 KB
scripts/audio_beats.jsscript17.5 KB
scripts/bilingual_typography_smoke.jsscript1.4 KB
scripts/bootstrap_listenhub.shexecutablescript5.4 KB
scripts/bootstrap_macos.shexecutablescript2.5 KB
scripts/brand_templates.jsscript2.4 KB
scripts/brand_templates_smoke.jsscript869 B
scripts/complete_sentence.jsscript3.9 KB
scripts/component_motion_smoke.jsscript21.2 KB
scripts/concept_smoke.jsscript5.6 KB
scripts/cover.jsscript9.1 KB
scripts/cover_smoke.jsscript5.1 KB
scripts/english_mix.jsscript24.1 KB
scripts/english_mix_smoke.jsscript5.7 KB
scripts/explainer_beats.jsscript6.7 KB
scripts/explainer_beats_smoke.jsscript4.8 KB
scripts/explainer_cognitive_timing_smoke.jsscript5.8 KB
scripts/explainer_e2e_smoke.jsscript7.4 KB
scripts/explainer_pipeline.jsscript49.3 KB
scripts/explainer_pipeline_smoke.jsscript12.7 KB
scripts/explainer_spec.jsscript51.4 KB
scripts/explainer_timing.jsscript8.6 KB
scripts/fetch_generated.jsexecutablescript17.4 KB
scripts/ffmpeg_retry_shim_smoke.jsscript2.3 KB
scripts/file_narration_smoke.jsexecutablescript6.6 KB
scripts/ingest_asset.jsexecutablescript15.0 KB
scripts/kinetic_caption_smoke.jsscript1.4 KB
scripts/license_report.jsexecutablescript2.3 KB
scripts/listenhub_narration.jsexecutablescript11.0 KB
scripts/listenhub_smoke.jsexecutablescript26.7 KB
scripts/local_preferences.jsscript1.8 KB
scripts/motion_studio.jsscript55.9 KB
scripts/motion_studio_smoke.jsscript11.0 KB
scripts/movie_montage.jsscript24.7 KB
scripts/movie_montage_smoke.jsscript4.0 KB
scripts/qcut.jsexecutablescript40.8 KB
scripts/release_check.jsscript7.0 KB
scripts/render_project.jsscript85.1 KB
scripts/render_scene.jsscript26.4 KB
scripts/renderers/ass.jsexecutablescript2.7 KB
scripts/renderers/bilingual_ass.jsscript12.6 KB
scripts/renderers/html_scene.jsexecutablescript3.9 KB
scripts/renderers/procedural_music.jsscript7.6 KB
scripts/scene_content_cache.jsscript3.2 KB
scripts/scene_renderer_smoke.jsscript2.8 KB
scripts/security_smoke.jsscript10.2 KB
scripts/sentence_boundary_smoke.jsscript1.6 KB
scripts/setup_deps.jsscript8.4 KB
scripts/shims/ffmpegexecutablescript3.0 KB
scripts/source_review.jsexecutablescript5.1 KB
scripts/timeline_features_smoke.jsscript3.7 KB
scripts/trigger_eval.pyexecutablescript2.5 KB
scripts/validate_skill.pyexecutablescript3.1 KB
scripts/verify_marswave_vendor.jsexecutablescript3.5 KB
scripts/verify_video.jsexecutablescript3.4 KB

references/timeline-schema.md

View on GitHub
# QiaoCut Timeline v1

`qiaocut.timeline.v1` 是可直接渲染的工程时间线。它与导演层的 `qiaocut.ir.v0` 分工不同:IR 描述意图,timeline 只描述已经落实到本地素材、时间码、字幕和声音的确定性成片。

## 目录约定

渲染器只读取项目目录内的路径。`shots[].path`、字幕、旁白 JSON、字体目录、音乐、报告和最终视频都必须是项目相对路径;绝对路径和 `..` 越界会在运行 ffmpeg 前被拒绝。

```text
project/
├── .qiaocut/cache/      # project-private generated cache; do not publish
├── timeline.json
├── narration.json
├── captions/captions.json
├── assets/
├── renders/
└── reports/
```

完整 JSON Schema:[`schemas/qiaocut.timeline.v1.schema.json`](schemas/qiaocut.timeline.v1.schema.json)。

## 最小可渲染示例

```json
{
  "schema": "qiaocut.timeline.v1",
  "title": "一个词,三层意思",
  "output": {
    "width": 1080,
    "height": 1920,
    "fps": 30,
    "duration": 8,
    "loudnessLufs": -14,
    "truePeakDb": -1.5,
    "file": "renders/final.mp4"
  },
  "captionSource": "captions/captions.json",
  "captions": "captions/final.ass",
  "narration": "narration.json",
  "music": {
    "mode": "procedural",
    "path": "assets/audio/original-score.wav",
    "bpm": 88,
    "seed": 1337,
    "energy": 0.55
  },
  "shots": [
    {
      "id": "s01",
      "kind": "image",
      "path": "assets/opening.jpg",
      "duration": 4,
      "fit": "cover",
      "motion": "pushIn"
    },
    {
      "id": "s02",
      "kind": "video",
      "path": "assets/example.mp4",
      "in": 2,
      "duration": 4,
      "fit": "containBlur",
      "sourceAudio": true,
      "sourceGainDb": -2
    }
  ]
}
```

`shots[].duration` 总和必须等于 `output.duration`。所有档位采用 H.264 High / yuv420p / BT.709、AAC 48 kHz stereo;`preview` / `standard` 使用单遍 loudnorm,`final` 使用两遍 loudnorm。

## 镜头转场

转场写在后一个镜头上,表示“从上一镜头进入当前镜头”。首镜头不能有非零转场。

```json
{
  "id": "s02",
  "kind": "video",
  "path": "assets/scenes/mechanism.mp4",
  "duration": 4,
  "transition": { "type": "fade", "duration": 0.25 }
}
```

支持 `cut`、`fade`、`dissolve`、四向 `wipe/slide/smooth`、`circleopen/circleclose`和 `pixelize`。非零转场同时对画面做 `xfade`、对镜头原声做 `acrossfade`。

> 存在重叠转场时,`output.duration = sum(shots[].duration) - sum(transition.duration)`。

## 双语三层字幕

`captionSource` 接受两种写法。紧凑的 `cues` 会自动展开为英文、中文、顶部注释三层:

```json
{
  "title": "Bilingual lesson",
  "font": "Noto Sans CJK SC",
  "cues": [
    {
      "start": 0.2,
      "end": 3.8,
      "english": "One word. [[THREE LAYERS.]]",
      "chinese": "一个词,三层意思。",
      "note": "EARTH → INVESTIGATE → LIKE",
      "source": "来源说明(如需要)"
    }
  ]
}
```

复杂排版可直接提供 `events`,支持 `English`、`Chinese`、`Note`、`Source`、`Card`、`CardChinese`、`BigWord`、`BigChinese` 样式。`[[文字]]` 会变成强调色。

### 动态字幕

`events[]` 可使用 `animation: fade|none|pop|slide-up|word-follow|karaoke|typewriter`。逐词模式建议显式给出 `segments`,避免中文自动按字切分不符合语义节奏。

```json
{
  "start": 0.2,
  "end": 2.2,
  "style": "BigChinese",
  "text": "模型看到的是 Token",
  "animation": "word-follow",
  "segments": [
    { "text": "模型看到的 ", "durationMs": 900 },
    { "text": "是 ", "durationMs": 250 },
    { "text": "Token", "durationMs": 850 }
  ]
}
```

`slide-up` 需要 `pos: [x, y]`才能建立明确运动路径。`word-follow/karaoke/typewriter` 底层使用 ASS karaoke timing,可在无浏览器的终稿渲染中复现。

`pos` 默认使用 timeline 原始输出画布作为作者坐标系,例如竖屏为 1080×1920。preview/standard 改变分辨率时会同比缩放坐标和 slide-up 位移;不要为不同 profile 维护两套位置。

若 timeline 明确设置 `fontsDir`,渲染器优先使用项目内字体。没有设置时,会查找本机已经安装的 Noto Sans CJK SC,并复制到项目私有的 `.qiaocut/cache/fonts/`,以隔离 Fontconfig 并稳定本机渲染;这只是本地缓存,不属于项目素材。

skill、Git 仓库和发布包不得捆绑、上传或再分发从用户机器发现的字体。跨机器复现若需要固定字体,应由项目维护者自行选择具有相应再分发许可的字体,记录许可证后再配置 `fontsDir`。找不到中文字形时,渲染器会明确失败或留下未验证状态,不会悄悄输出缺字成片。

## 旁白、音乐与独立音效

`narration` 可以内联,也可以指向项目内 JSON。本机确定性 TTS 后端为 `macos-say`:

```json
{
  "engine": "macos-say",
  "voice": "Samantha",
  "rate": 174,
  "cues": [
    { "id": "n01", "start": 0.2, "maxDuration": 3.4, "text": "One word. Three layers." }
  ]
}
```

ListenHub TTS、ListenHub Voice、播客片段或用户录音先下载/导入项目,再使用文件型旁白:

```json
{
  "engine": "file",
  "path": "assets/generated/listenhub/audio/narration.mp3",
  "provider": "listenhub",
  "assetId": "listenhub-audio-<sha-prefix>",
  "speakerId": "<resolved-speaker-id>",
  "speakerName": "向阳乔木",
  "narrationTextSha256": "<64-char-sha256>",
  "start": 0,
  "trim": 0,
  "gain": 1
}
```

渲染器会把文件旁白转换为 48 kHz stereo、应用 trim/start/gain,并限制在成片时长内。声明 `provider=listenhub` 时必须带 asset/speaker/text provenance,且渲染前会校验 manifest 的 path、文件 SHA-256、speaker 与文本摘要;文件被替换会失败。远端临时 URL 不能直接写入 timeline。非 macOS 环境可使用 `file`,或设 `narration.engine` 为 `none`。程序音乐由固定 seed 合成,因此同一时间线可重复得到相同结果;`music: false` 可关闭音乐,`music.mode: file` 可使用项目内现成音频。

按钮、切分、吸附、转折等画面音效使用顶层 `soundEffects[]`:

```json
{
  "soundEffects": [
    {
      "id": "token-snap",
      "path": "assets/audio/token-snap.wav",
      "start": 3.42,
      "trim": 0,
      "duration": 0.28,
      "gain": 0.7,
      "fadeInMs": 8,
      "fadeOutMs": 60
    }
  ],
  "audio": { "sfxGain": 1 }
}
```

设置 `"alignPeak": true` 时,`start` 表示**画面命中时刻**而不是文件起点:渲染器用 `qcut audio peak` 同一算法测出音效峰值偏移,把文件提前放置,让实测峰值正好落在事件帧上(起点不足时自动增加 trim)。render report 的 cue 会记录 `hitAt`、`peakMs` 和实际 `start`。所有 UI 点击、吸附、落位类音效默认应开启 `alignPeak`。

音效会先按各自时间码归一化为 48 kHz stereo,再与原声、旁白和被旁链压低的音乐混合。独立音效默认不参与音乐 ducking,预览时必须人工检查是否遮挡旁白。

多部电影原声直接拼接时,可显式使用 `audio.masteringMode: "montage"`。它会在 loudnorm 前加入温和动态压缩,收拢不同年代、不同混音规格素材的瞬时差异;`default` 或省略字段保持现有行为。该模式不替代 final 的两遍响度与真峰值检查。

## HTML / SVG / Manim 场景资产

时间线仍只接收已落盘的 `image/video`,不在 final render 期间临时运行任意网页或 Python。先使用:

```bash
node scripts/qcut.js scene render ./project scenes/token.html \
  --engine html --output assets/scenes/token.mp4 \
  --duration 4 --width 1080 --height 1920 --fps 30

node scripts/qcut.js scene render ./project scenes/attention.py \
  --engine manim --scene-class AttentionMap \
  --output assets/scenes/attention.mp4 \
  --duration 6 --width 1080 --height 1920 --fps 30
```

然后将输出 MP4 作为 `shots[].kind=video` 的项目内素材。HTML/SVG 的 PNG buffer 通过 `image2pipe` 直接进入 ffmpeg,不建立逐帧 PNG 目录;这个两阶段设计仍保留场景 MP4,便于缓存、评审、重试和跨时间线复用。

## 渲染接口

```bash
node scripts/render_project.js ./project --profile preview --json
node scripts/render_project.js ./project --profile standard --json
node scripts/render_project.js ./project --profile final --json
node scripts/render_project.js ./project --timeline timelines/vertical.json --keep-build
```

### 渲染档位

| Profile | 有效输出 | 音频 | 默认 Validation | Contact sheet |
|---|---|---|---|---|
| `preview` | 长边最多 960、最高 24 fps、x264 `ultrafast` / CRF 25;中间片段 CRF 28 | 单遍 loudnorm | `basic` | 默认关闭 |
| `standard` | 长边最多 1280、最高 30 fps、x264 `veryfast` / CRF 21;中间片段 CRF 24 | 单遍 loudnorm | `standard` | 开启,最多 8 帧、缩略图宽度最多 240 |
| `final` | 保留 timeline 的原始尺寸、帧率、preset 和 CRF | 两遍 loudnorm | `full` | 开启,服从 timeline 配置 |

为兼容 v0.2,不传 `--profile` 时仍使用 `final`。非 final 档自动派生独立输出,例如 timeline 的 `renders/final.mp4` 会对应为 `renders/final.preview.mp4` 或 `renders/final.standard.mp4`;生成的 ASS、contact sheet 和 render report 同样带档位后缀。`--output` 可指定新的项目相对输出路径,但仍遵守路径和 no-clobber 规则。

### 校验档位

| Validation | 始终检查 | 额外检查 |
|---|---|---|
| `basic` | 视频/音频流、非空文件、有效时长、有效尺寸、帧率、yuv420p | 无全片诊断扫描 |
| `standard` | `basic` 全部 | 最终响度、true peak、静音边界 |
| `full` | `standard` 全部 | 全片黑场区间 |

路径边界、软链接逃逸、输入输出别名、no-clobber、素材存在性、timeline 时长一致性和资源上限属于所有档位的前置安全门,不能通过降低 validation 绕过。`--validation basic|standard|full` 仅用于诊断覆盖范围;只有 `profile=final`、`validation=full`、验证成功且字幕字体不是 `system-unverified` 时,报告的 `releaseReady` 才为 `true`。

`qcut render` 已执行相应 validation 并把结果写入 render report。不要在它成功后对同一成片重复运行 `qcut verify`;独立 verify 用于外部生成、移动后或单独收到的视频。

### 缓存与性能证据

默认缓存位于 `.qiaocut/cache/`,包括镜头片段、macOS TTS、已烧录字幕的画面和仅供本机使用的字体副本。Fontconfig 运行状态放在每次唯一的构建目录,不作持久缓存。素材指纹、时间线参数、profile 或 ffmpeg 版本变化会产生新的缓存键;`--no-cache` 可在诊断时完全绕过缓存。报告中的 `cache` 和 `timings` 用于判断冷热缓存与各阶段耗时。

在同一开发机、同一个 60 秒 DIG 双语样片上的实测为:原始 final 71.6 秒;preview 冷缓存 27.7 秒、暖缓存 3.3 秒;standard 冷缓存 27.1 秒(TTS 已暖)、暖缓存 4.1 秒;final/full 冷缓存 65.6 秒(TTS 已暖)、暖缓存 8.5 秒。数字只用于同机相对比较。

- 成功退出码为 `0`;渲染或依赖错误为 `1`;CLI 用法错误为 `2`。
- `--json` 时 stdout 只输出最终 JSON,进度和 ffmpeg 日志写入 stderr。
- 每次使用唯一的 `.qiaocut/render-*` 构建目录;成功后默认只删除本次目录,`--keep-build` 用于排错。
- `.qiaocut/cache/` 默认跨构建复用;`--no-cache` 只关闭缓存,不降低安全检查。
- 所有已有生成目标默认保留;只有逐项核对后才使用 `--force`。输入与输出别名即使加 `--force` 也会拒绝。
- 默认限制超大分辨率、超过 4 小时、超过 120 fps 或超过 1000 个镜头;确有需要时审查资源成本后使用 `--allow-large`。
- 输出包括成片、按档位可选的 contact sheet、render report、缓存统计、阶段耗时和流级技术验证。

脚本也可作为 Node 模块调用:

```js
const { renderProject } = require('./scripts/render_project');
const report = renderProject('/absolute/runtime/project/path', {
  timeline: 'timeline.json',
  profile: 'preview',
  validation: 'basic',
  cache: true,
  keepBuild: false,
  onProgress: console.error
});
```

项目路径在运行时可以是绝对路径;timeline 内部路径仍必须保持项目相对。
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 323kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall