Skip to content

JimLiu/baocut / skills/baocut

baocut

Flagged

用 BaoCut 处理视频与音频:转录、字幕、翻译、配音、剪口播、切短视频、分章、总结写稿、从链接下载、压缩转码、导出成片,或从零做一条成片。有媒体文件、视频链接、字幕文件或 BaoCut 视频时用;只翻译纯文本、与视频无关的写作或作图、别的剪辑器与 FFmpeg 的用法、BaoCut 源码开发不用。

FileKindSize
SKILL.mdskill md46.5 KB
built-in-skills/README.mdmarkdown9.6 KB
references/catalog/editing.mdmarkdown24.4 KB
references/catalog/export.mdmarkdown6.6 KB
references/catalog/media.mdmarkdown45.1 KB
references/catalog/models.mdmarkdown7.9 KB
references/catalog/music.mdmarkdown17.1 KB
references/catalog/subtitles.mdmarkdown20.8 KB
references/catalog/system.mdmarkdown9.6 KB
references/catalog/voice-gemini-tts.mdmarkdown2.6 KB
references/catalog/voice-language-rates.mdmarkdown6.5 KB
references/catalog/voice.mdmarkdown12.3 KB
references/catalog/web.mdmarkdown10.9 KB
references/conventions.mdmarkdown16.1 KB
references/craft/.gitkeepother0 B
references/craft/README.mdmarkdown480 B
references/craft/character-animation.mdmarkdown6.8 KB
references/craft/character-animation/examples/mini-film/art.example.jsonconfig918 B
references/craft/character-animation/examples/mini-film/index.htmlother628 B
references/craft/character-animation/examples/mini-film/scene.jsscript2.1 KB
references/craft/character-animation/references/art.mdmarkdown4.6 KB
references/craft/character-animation/references/checks.mdmarkdown2.6 KB
references/craft/character-animation/references/rig.mdmarkdown5.3 KB
references/craft/character-animation/references/style-and-story.mdmarkdown5.0 KB
references/craft/character-animation/references/timing-and-sound.mdmarkdown3.1 KB
references/craft/character-animation/rig-kit/rig-kit.jsscript33.0 KB
references/craft/character-animation/scripts/cutout.mjsscript26.9 KB
references/craft/character-animation/scripts/jump-scan.mjsscript3.2 KB
references/craft/character-animation/scripts/place-sfx.mjsscript5.1 KB
references/craft/character-animation/scripts/rig-check.mjsscript8.9 KB
references/craft/clip-montage.mdmarkdown11.5 KB
references/craft/clip-montage/references/assembly.mdmarkdown5.0 KB
references/craft/clip-montage/references/sourcing.mdmarkdown6.3 KB
references/craft/clip-montage/references/structure.mdmarkdown3.8 KB
references/craft/cover-and-title.mdmarkdown5.6 KB
references/craft/cross-video-qa.mdmarkdown5.8 KB
references/craft/design-system.mdmarkdown18.5 KB
references/craft/design-system/references/cover.mdmarkdown6.9 KB
references/craft/design-system/references/craft.mdmarkdown8.8 KB
references/craft/design-system/references/demo.jsonconfig161.1 KB
references/craft/design-system/references/format.mdmarkdown18.6 KB
references/craft/design-system/references/from-code.mdmarkdown11.5 KB
references/craft/design-system/references/from-design-tool.mdmarkdown16.2 KB
references/craft/design-system/references/sample-seazar-tokens.jsonconfig11.0 KB
references/craft/design.mdmarkdown19.3 KB
references/craft/design/references/brand-colors.mdmarkdown2.4 KB
references/craft/design/references/brand-typography.mdmarkdown1.7 KB
references/craft/design/references/craft.mdmarkdown15.4 KB
references/craft/design/references/design-system-components.mdmarkdown11.8 KB
references/craft/design/references/diagrams.mdmarkdown10.1 KB
references/craft/design/references/format.mdmarkdown11.8 KB
references/craft/design/references/print.mdmarkdown5.6 KB
references/craft/design/references/questions.mdmarkdown4.7 KB
references/craft/design/references/view-state.mdmarkdown5.7 KB
references/craft/docs.mdmarkdown19.9 KB
references/craft/docs/references/comments.mdmarkdown4.4 KB
references/craft/docs/references/editing.mdmarkdown12.9 KB
references/craft/docs/references/tabs.mdmarkdown4.7 KB
references/craft/docs/references/uploads.mdmarkdown1.7 KB
references/craft/explainer-video.mdmarkdown23.4 KB
references/craft/explainer-video/references/3d.mdmarkdown5.9 KB
references/craft/explainer-video/references/footage.mdmarkdown9.6 KB
references/craft/explainer-video/references/length-and-pace.mdmarkdown6.7 KB
references/craft/explainer-video/references/script.mdmarkdown14.7 KB
references/craft/explainer-video/references/subject.mdmarkdown12.5 KB
references/craft/history-video.mdmarkdown20.6 KB
references/craft/history-video/references/brief.mdmarkdown5.1 KB
references/craft/history-video/references/forms.mdmarkdown11.2 KB
references/craft/history-video/references/old-recordings.mdmarkdown12.4 KB
references/craft/history-video/references/self-check.mdmarkdown5.3 KB
references/craft/history-video/references/sources.mdmarkdown5.9 KB
references/craft/motion-graphics.mdmarkdown17.3 KB
references/craft/motion-graphics/exemplars/big-number/16x9.htmlother11.4 KB
references/craft/motion-graphics/exemplars/big-number/9x16.htmlother11.5 KB
references/craft/motion-graphics/exemplars/callout-pin/16x9.htmlother11.6 KB
references/craft/motion-graphics/exemplars/callout-pin/9x16.htmlother11.6 KB
references/craft/motion-graphics/exemplars/keyword-caption/16x9.htmlother11.3 KB
references/craft/motion-graphics/exemplars/keyword-caption/9x16.htmlother11.3 KB
references/craft/motion-graphics/exemplars/logo-sting/16x9.htmlother12.1 KB
references/craft/motion-graphics/exemplars/logo-sting/9x16.htmlother12.1 KB
references/craft/motion-graphics/exemplars/lower-third/16x9.htmlother11.2 KB
references/craft/motion-graphics/exemplars/lower-third/9x16.htmlother11.2 KB
references/craft/motion-graphics/references/audio-backdrop.mdmarkdown22.9 KB
references/craft/motion-graphics/references/grammar.mdmarkdown11.1 KB
references/craft/motion-graphics/scaffold.htmlother9.0 KB
references/craft/motion-graphics/scripts/build-bundle.mjsscript25.2 KB
references/craft/narration.mdmarkdown11.1 KB
references/craft/polish-transcript.mdmarkdown13.8 KB
references/craft/production-scripts.mdmarkdown15.7 KB
references/craft/production-scripts/references/pipeline.mdmarkdown37.8 KB
references/craft/production-scripts/scene-kit/geo110.jsscript27.3 KB
references/craft/production-scripts/scene-kit/scene-kit.jsscript38.3 KB
references/craft/production-scripts/scripts/align.mjsscript11.6 KB
references/craft/production-scripts/scripts/assemble.mjsscript26.4 KB
references/craft/production-scripts/scripts/build.mjsscript18.1 KB
references/craft/production-scripts/scripts/captions.mjsscript18.6 KB
references/craft/production-scripts/scripts/clips.example.jsonconfig3.2 KB
references/craft/production-scripts/scripts/coverage.mjsscript10.0 KB
references/craft/production-scripts/scripts/envelope.mjsscript2.9 KB
references/craft/production-scripts/scripts/explainer.example.jsonconfig2.2 KB
references/craft/production-scripts/scripts/fonts.mjsscript7.0 KB
references/craft/production-scripts/scripts/frames.mjsscript7.7 KB
references/craft/production-scripts/scripts/gaps.mjsscript11.3 KB
references/craft/production-scripts/scripts/host.mjsscript14.8 KB
references/craft/production-scripts/scripts/legibility.mjsscript5.7 KB
references/craft/production-scripts/scripts/level.mjsscript9.2 KB
references/craft/production-scripts/scripts/lib.mjsscript19.3 KB
references/craft/production-scripts/scripts/overlay.mjsscript34.7 KB
references/craft/production-scripts/scripts/preview.mjsscript4.6 KB
references/craft/production-scripts/scripts/quotes.mjsscript7.4 KB
references/craft/production-scripts/scripts/sources.mjsscript6.2 KB
references/craft/production-scripts/scripts/srt.mjsscript5.8 KB
references/craft/production-scripts/scripts/voice.mjsscript7.7 KB
references/craft/shorts-segments.mdmarkdown30.8 KB
references/craft/slides.mdmarkdown13.8 KB
references/craft/slides/references/design-system.mdmarkdown6.3 KB
references/craft/slides/references/design.mdmarkdown9.3 KB
references/craft/slides/references/format.mdmarkdown12.2 KB
references/craft/slides/references/images.mdmarkdown4.2 KB
references/craft/speaker-labeling.mdmarkdown6.6 KB
references/craft/subtitle-workflow.mdmarkdown13.1 KB
references/craft/talking-head-cut.mdmarkdown9.3 KB
references/craft/talking-head-cut/references/picture-and-sound.mdmarkdown10.1 KB
references/craft/titles-and-description.mdmarkdown5.2 KB
references/craft/titles-and-description/references/description.mdmarkdown5.1 KB
references/craft/titles-and-description/references/titles.mdmarkdown5.5 KB
references/craft/titles-and-description/references/writing-baseline.mdmarkdown11.9 KB
references/craft/translate-subtitles.mdmarkdown13.4 KB
references/craft/video-blog.mdmarkdown17.1 KB
references/craft/video-blog/references/writing-baseline.mdmarkdown11.9 KB
references/craft/video-chapters.mdmarkdown9.7 KB
references/craft/video-production.mdmarkdown31.9 KB
references/craft/video-production/examples/bundle-preview.htmlother17.7 KB
references/craft/video-production/examples/post-fx.jsscript7.5 KB
references/craft/video-production/references/code-scenes.mdmarkdown31.9 KB
references/craft/video-production/references/shot-plan.mdmarkdown5.1 KB
references/craft/video-production/references/sound-design.mdmarkdown4.4 KB
references/craft/video-production/references/visuals.mdmarkdown19.7 KB
references/craft/video-summary.mdmarkdown22.8 KB
references/craft/video-summary/references/writing-baseline.mdmarkdown11.9 KB
references/craft/virtual-host.mdmarkdown14.9 KB
references/craft/virtual-host/examples/character-partmap.example.jsonconfig600 B
references/craft/virtual-host/examples/character.example.jsonconfig336 B
references/craft/virtual-host/references/art.mdmarkdown22.1 KB
references/craft/virtual-host/references/hosts.mdmarkdown4.4 KB
references/craft/virtual-host/references/lipsync.mdmarkdown10.1 KB
references/craft/virtual-host/scripts/lipsync.mjsscript39.8 KB
references/craft/virtual-host/scripts/pinyin-table.mjsscript83.2 KB
references/craft/virtual-host/scripts/puppet-build.mjsscript48.6 KB
references/craft/virtual-host/scripts/puppet-mask.mjsscript3.0 KB
references/craft/virtual-host/scripts/puppet/align.mjsscript4.1 KB
references/craft/virtual-host/scripts/puppet/brows.mjsscript17.2 KB
references/craft/virtual-host/scripts/puppet/edits.mjsscript4.3 KB
references/craft/virtual-host/scripts/puppet/expression-labels.jsonconfig1.1 KB
references/craft/virtual-host/scripts/puppet/expreyes.mjsscript35.9 KB
references/craft/virtual-host/scripts/puppet/eyes.mjsscript8.6 KB
references/craft/virtual-host/scripts/puppet/fill.mjsscript10.5 KB
references/craft/virtual-host/scripts/puppet/layers.mjsscript5.7 KB
references/craft/virtual-host/scripts/puppet/mapbuild.mjsscript50.4 KB
references/craft/virtual-host/scripts/puppet/ops.mjsscript7.4 KB
references/craft/virtual-host/scripts/puppet/pack.mjsscript10.2 KB
references/craft/virtual-host/scripts/puppet/partmap.mjsscript8.5 KB
references/craft/virtual-host/scripts/puppet/parts.mjsscript7.0 KB
references/craft/virtual-host/scripts/puppet/png.mjsscript5.8 KB
references/craft/virtual-host/scripts/puppet/seg.mjsscript21.6 KB
references/craft/virtual-host/scripts/puppet/segment.mjsscript26.6 KB
references/craft/virtual-host/scripts/puppet/zip.mjsscript2.0 KB
references/craft/virtual-host/scripts/visemes.mjsscript21.4 KB
references/craft/vlog-from-clips.mdmarkdown13.2 KB
references/craft/vlog-from-clips/references/footage-log.mdmarkdown3.3 KB
references/mcp.mdmarkdown8.9 KB
references/start.mdmarkdown6.3 KB
references/workflows.mdmarkdown29.8 KB

references/catalog/editing.md

View on GitHub
---
description: 时间线修改的机制:一笔修改的事务与版本、预检、按需查操作、常用操作的例子、内置的声波与进度条、剪口播的提案与剪口、章节、撤销与读回执。第一次改时间线之前读。
---

# 编辑:时间线上的修改

## 何时用

- 剪辑:放素材、裁切、拆分、挪动、删除、波纹删除、变速、转场。
- 剪口播:去口癖与长停顿、删掉录废的部分(剪口)。
- 章节、文字与元素、画面摆法与外观、效果、声音与闪避、画布尺寸。
- 旁白按段配、画面按段上时间线的片子:把制作计划(各段的代码包与旁白、实拍片段、卡片)一次放好,改了只动变了的(下面的「一次放好制作计划」)。
- 写文档(转写、译文)也是一笔修改:已有文档的局部修改用 {{tool:edits_apply}} 的文档操作,新建或整体替换用 {{tool:documents_put}}(见 [subtitles](subtitles.md));作者的章节用 {{tool:chapters_adopt}} 写进视频(见下面的「章节」)。

剪哪里、留哪句、停顿多长是 craft 的事:{{skill:talking-head-cut}}、{{skill:video-chapters}}、{{skill:shorts-segments}}。这一页只讲怎么提交、怎么读回执。

## 前置检查

- {{tool:videos_inspect}} 拿当前版本(`revision`)与对象 ID(轨道、片段、素材、文档)。片段多时用 {{arg:fromSeconds}} / {{arg:toSeconds}} 读一段。
- 分清两种时钟:移动、裁切、拆分、波纹删除、章节用**时间线上的秒**;剪口(`addCuts`)用**素材自己的秒**。换算见 [conventions](../conventions.md) 的「时间」。
- 锁定的片段与轨道不能改;要动先问用户。

## 命令与例子

### 一笔修改:{{tool:edits_apply}}

- {{arg:operations}} 是按顺序执行的操作数组;**全部成功才提交**,任何一步失败整笔不生效、视频不变。
- {{arg:expectedRevision}} 带上 {{tool:videos_inspect}} 或上一次回执的版本;不一致时拒绝(`PROJECT_REVISION_CONFLICT`)。
- {{arg:label}} 写一句简短说明,显示在历史与撤销里(例如「删掉开头的寒暄」)。
- 相关的几步放进同一笔:用户说「不要那一批」时一次撤销就退回去。同一笔里后面的操作可以用 `ref` 引用前面 `importAsset` 导入的素材。
- 时间写秒数(`1.5`),也可以写 `{"unit":"frames","value":30}`。
- 回执的 `createdIds` 是这一笔新建的全部对象,按 ID 前缀分辨种类(`item_`、`track_`、`asset_`、`doc_`),**不按操作或 `items` 的顺序排**。一笔插了几个片段、接着要按片段做事(加转场、调次序)时,用 {{tool:videos_inspect}} 按轨道与起点认回各自的 ID。

已有文档只修改局部时用 `renameSpeakers`(姓名)、`updateWords`(词文本)或 `patchDocument`(字幕、译文、章节、换行、样式等)。先用 {{tool:edits_ops}} 查询操作格式,按稳定 ID 提交变化(`patchDocument` 的路径从正文里面算起:{{tool:documents_read}} 返回的 `body.cues` 写成 `["cues",{"id":…},"text"]`,不带 `body`;路径错了预检发现不了,提交时才报 `path-missing`),保持 `expectedRevision` 与编辑依据一致。不要为改几个名字或校订几个词上传整份文稿;`putDocument` 留给新建或整体替换。

### 先预检

不确定操作写得对不对、会影响多少时,先给 {{tool:edits_apply}} 带上 {{arg:dryRun}} 提交一次:形态、参数、引用的对象与文件、版本对不上时与真正提交报同样的错,通过时返回补全后的操作与影响(`committed: false`),视频不变、不进历史。同轨重叠、锁定与任务保护只有真正提交时才知道。

### 按需查操作:{{tool:edits_ops}}

不要背操作清单,也不要一次拉全部。要用哪个操作就只查那一个:{{tool:edits_ops}} 给 {{arg:op}}(如 `removeRange`),返回它的说明、参数的 JSON Schema 与一个示例。
<!-- surface: cli -->
同样的内容也可以 `baocut spec edits.<操作>` 取。
<!-- /surface -->

操作族一览(字段一律按需查):

| 族 | 操作 | 做什么 |
| --- | --- | --- |
| 素材 | `importAsset`、`collectAssets`、`removeAssets` | 登记素材(链接或复制进视频);把链接的素材收进视频;删掉没有引用的素材 |
| 片段 | `addItem`、`moveItem`、`moveItems`、`trimItem`、`splitItem`、`joinItems`、`deleteItems`、`updateItem`、`arrangeItem` | 放上时间线、挪、裁、拆、合、删(留空隙)、改名与启用、跟随策略;调整画面的叠放次序 |
| 波纹 | `removeRange`、`insertRange` | 删掉一段时间并让后面的前移,或空出一段时间让后面的后移;要一起动的配音、字幕轨都要列上 |
| 画面 | `setTransform`、`setStyle`、`setEffects`、`setSpeed` | 位置与大小、铺满或画中画、裁切与外观、调色与效果、恒定变速 |
| 文字 | `setText` | 改文字片段的文字或改成计时读数 |
| 声音 | `setAudioMix`、`setDucking`、`removeDucking` | 音量、静音、淡入淡出;人声响起时压低配乐 |
| 转场 | `setTransition`、`removeTransition` | 片段之间或单侧的转场 |
| 章节 | `setChapters`、`upsertChapter`、`removeChapter` | 整个替换或逐章修改章节 |
| 剪口 | `proposeCuts`、`acceptCutSuggestions`、`addCuts`、`restoreCut` | 生成口癖与停顿的剪辑提案、接受建议、直接剪、恢复 |
| 轨道与画布 | `addTrack`、`updateTrack`、`moveTrack`、`deleteTrack`、`updateSequence` | 加轨道、锁定与隐藏、挪动与删除轨道、画布尺寸与底色 |
| 文档与历史 | `patchDocument`、`renameSpeakers`、`updateWords`、`putDocument`、`createCheckpoint`、`renameVideo`、`setVideoBrief` | 写文档、留检查点、改视频名、写视频速览 |

常用操作(由目录生成):

<!-- generated: common-ops -->
**导入素材**(`importAsset`):把媒体文件登记为视频的素材。

```json
{"type":"importAsset","path":"demo.mp4","ref":"clip"}
```

**放素材**(`addItem`):把素材放到时间线上;省略 at 时接在轨道末尾,省略 trackId 时用第一条未锁定的同类轨道(视频、图片放视觉轨,音频放音频轨)。

```json
{"type":"addItem","asset":{"ref":"clip"},"at":1}
```

**裁剪**(`trimItem`):裁切片段的开头或结尾,at 是这条边在时间线上的新位置。

```json
{"type":"trimItem","itemId":"item_1","edge":"end","at":8}
```

**挪动**(`moveItem`):移动片段;at 是新的开始时间,offset 是相对移动(可为负),二选一。

```json
{"type":"moveItem","itemId":"item_1","at":5}
```

**删除**(`deleteItems`):删除片段(不移动其他片段,留下空隙)。

```json
{"type":"deleteItems","itemIds":["item_1"]}
```

**分割**(`splitItem`):在时间线上的这个位置把片段一分为二;关键帧按两半各自的窗口分开,裁切时关键帧跟着内容走。

```json
{"type":"splitItem","itemId":"item_1","at":3.5}
```

**调音量**(`setAudioMix`):改音频、视频或有声合成的声音;volume 是线性倍数,在 0 到 4,1 为原音量(0.5 约 -6 dB,2 约 +6 dB);淡变 0 表示去掉。

```json
{"type":"setAudioMix","itemId":"item_1","volume":0.5,"fadeOut":1}
```

**改文字**(`setText`):改文字片段的文字,或改成计时读数、章节文字;三者只给一个,给了的替换另外两个。

```json
{"type":"setText","itemId":"item_1","text":"第一章"}
```

字幕层用 {{tool:captions_create}} 建,不是这里的操作;剪掉一段并让后面前移用 `removeRange`,空出一段让后面后移用 `insertRange`,口播的剪口用 `addCuts`。其余操作与每个字段的写法用 {{tool:edits_ops}} 取。
<!-- /generated -->

**换片段的素材**(重截的背景图、重剪的视频):用 `replaceItemAsset` 原地换。片段的 ID、轨道、起点、长度、摆位、裁剪、效果与关键帧都不动,挂在它上面的转场、按它投影的字幕(`scopeItemIds`)与指着它的闪避规则照旧。新文件在同一笔里先 `importAsset`(带 `ref`),再用 `assetImportRef` 指过去;素材库里已有的素材给 `assetRef`。编辑器的「替换」也是这样做的,一次撤销就能退回。

```json
[{"type":"importAsset","path":"/abs/take2.mp4","ref":"take2"},
 {"type":"replaceItemAsset","itemId":"item_1","assetImportRef":"take2","timeMap":{"kind":"linear","sourceIn":{"ticks":"0","timescale":1000},"rate":{"num":1,"den":1}}}]
```

- 一次换一个片段;同一个素材用了几段,就写几条。
- 种类要对上:视频片段换视频,图片换图片,音频片段换音频或视频(取它的声音)。代码画面换包用 `replaceCodeBundle`。
- 不给 `timeMap` 就沿用原来的取用位置,新素材盖不住那段时整笔拒绝(`SOURCE_TIME_OUT_OF_RANGE`)。重剪的新视频通常从 0 秒起放,像上面那样给 `timeMap`。图片不给 `timeMap`。
- 新素材比片段短:同一笔里先 `trimItem` 收短终点,再换;同轨后面的片段要跟上就 `moveItems`。
- 新素材的余量不够两侧转场时,转场会被去掉,回执的 `removedTransitions` 列出;回执的 `assetSwaps` 列出每个片段换前换后的素材。

### 一次放好制作计划:{{tool:edits_assemble}}

旁白按段配、画面按段上时间线的片子(讲解、解说混剪、旁白片)不用一段一段 `importAsset` 与 {{tool:compositions_import}}:把制作计划写成 {{arg:plan}},或 {{arg:planFile}} 指向一份 JSON(里面的相对路径按它所在目录解析),一次放好。

- **段落**(`segments`)按播放顺序:每段一个代码包目录(包的长度就是段长),可带旁白(`narration` 给音频文件或配音产物的 `artifactId`)与对齐结果(`timing`:`{ lines: [{ text, start, chars? }], gaps? }` 或它的 JSON 路径,秒数从段首算)。段按整帧首尾相接放在 Scenes 轨,旁白在段首放在 Narration 轨;轨道按 `tracks` 给名字或 ID,没有就建。
- **实拍片段**(`clips`)属于某一段,起点按句子(`line`,加 `cue` 对到句里几个字被说到的时刻)、留白(`gap`,对到 `timing.gaps` 里给它留的那段)、紧跟上一个片段(`follow`)或段内秒数(`at`)定,截在本段下一个片段或段尾。`from`、`to` 是素材自己的秒(图片只有 `to`,当时长);`audio` 留原声或给音量;`fit`、`crop`、`pip`(画中画)、单侧转场 `in`、`out`。{{arg:footageLayer}} 为 `under` 时实拍轨挪到 Scenes 下面当底,代码包要透明。
- **卡片**(`cards`)是透明代码包,按 `line` + `cue` 或 `at` 放在最上面的 Cards 轨,长度就是包的长度。
- **水印**(`watermarks`)是图片,`dur` 秒长:属于某一段时按 `line` + `cue` 或段内 `at` 定起点,不带 `seg` 时 `at` 是整片的秒;`pip` 给位置与宽度(不给就铺满),放在最上面的 Watermark 轨,彼此不能重叠,越过最后一段的尾巴截掉并给警告。
- 先带 {{arg:dryRun}} 看排布与每一步要做的事(place、resize、replace、keep、move、remove),再真正提交:一次确认覆盖整趟,每一步各自可撤销。代码包默认进后台烘焙任务,结果里每段、每张卡带 `bakeJobId`,导出前用 {{tool:jobs_inspect}} 核对;`background: false` 时当场烘焙,结果带 `bake`(渲染器、帧率、耗时),退回逐帧截图的会给警告。
- **重跑是增量的**:放好之后视频里存一份「制作计划」记录。段落变长变短或换了包走带波纹的换包,后面的内容一起挪;中间插进的段先腾位置;换了旁白文件或产物就换旁白;同一路径的素材文件重新剪过(大小或修改时间变了)也算变了;没变的片段、卡片与水印不动。要动的轨道或条目锁着时什么都不改,报 `TARGET_LOCKED`,解锁后重跑。计划里删掉已放好的段落会拒绝(`PLAN_SEGMENT_REMOVED`:先用 `removeRange` 删掉那段);段落被手动挪得不再首尾相接时 `LAYOUT_MISMATCH`。
- 它不切素材、不配音、不对齐,也不烧来源标签、双语字幕或照片的推拉:这些在它之前做好,把剪好的文件当普通素材给它;有命令行环境时现成的脚本见 {{skill:production-scripts}}。

### 声波与进度条:内置元素

跟着声音起伏的声波和进度条是 BaoCut 的内置元素:引擎逐帧画,预览与导出一致,用户在编辑器的属性页里能换款、改色、挪位置。一笔 {{tool:edits_apply}} 的 `insertItems` 放上,马上出现在画面上。声波**只用**这个内置元素:不写代码包、不按 {{skill:motion-graphics}} 写 HTML、不自己分析音量或逐帧渲染,整段音频要渲染很久,用户也改不了;用户要的样子内置款式里没有时,挑最接近的款改色、挪位置,告诉用户能调哪些。

- **声波**:`{"type":"visualizer","visualizer":{"style":…}}`。横条款有 `audio_envelope`(默认)、`bars`、`bars_rounded`、`bars_bottom`、`spectrum_area`、`oscilloscope`、`ribbons`、`dots`,正方款有 `ring_bars`、`ring_wave`、`pulse_rings`。`mainColor`、`secondaryColor`(`#RRGGBB`)不写时用这一款的配色。缺省跟着整条序列混好的声音动;只在某位说话人说话时动给 `speaker`。
- **默认声波**:`audio_envelope` 是播放头前后约 5.4 秒的真实音量包络,121 根细圆柱上下对称,固定中线左侧为已播放青绿、右侧为未播放灰色,下方带片段进度与起止时间。默认 `mainColor` 为 `#7FE0CF`、`secondaryColor` 为 `#54616B`;可改色、换款、移动与缩放。它读取音频缓存的时域 RMS,不是瞬时频谱,dB 窗与频谱平滑不参与;无需代码包与全片烘焙。用户没指定声波样式时使用它;有字幕时用 `place` 居中到 `y:54`、`w:85`,并按 `scaleY = (画布宽 × 0.85 × 340) / (1632 × 画布高 × 0.2)` 保持参考比例;1920×1080 时约为 `1.574074`。版面另有计时,或声波收窄后下方的小字看不清时,`visualizer` 里写 `"readout": false`,去掉进度线与起止时间,只留细柱与中线。
- **进度条**:`{"type":"progress","progress":{"style":…}}`,只看播放头,在片段时长里从头走到尾。横条款有 `normal`、`rounded`;正方款有 `circle`、`donut`、`snake`、`snake_spin`、`snake_rainbow`、`snake_spin_rainbow`;画面四周的边框款有 `border`、`reverse_border`、`rainbow_border`、`reverse_rainbow_border`、`strobe_border`、`reverse_strobe_border`。`mainColor`、`secondaryColor`(`#RRGGBB`,可带透明度 `#RRGGBBAA`)是这一款的两种颜色,多数款前者是走过的那段、后者是底,不写时用这一款的配色;两款彩虹边框的颜色固定,两款彩虹游走只有底色(写在 `mainColor`)。`startProgress`、`endProgress` 是起止的值(0–1),起点大于终点时倒着走。不写 `place` 时:横条款 `w` 80、高为画面的 5%,正方款 `w` 30,边框款铺满。
- **时长与轨道**:`span` 从第 0 帧铺到序列末尾({{tool:videos_inspect}} 的 `sequence.durationFrames`)。同一条轨道上的片段不能重叠:画面轨上已有背景时,同一笔里先 `addTrack`(`kind` 为 `visual`,给 `ref`),再用 `trackRef` 指向它;新轨道排在最上面,盖在背景之上。
- **落位**(`place`):`x`、`y` 是框中心在画面宽、高上的百分比,`w` 是框宽占画面宽的百分比(正方款按画面短边)。不写时按种类的缺省:声波横条宽铺满、高为画面的 20%,中心在 `y` 85,正好压在字幕的默认位置(中线在画面高 86%)上;正方款 `w` 30。画面上有字幕时把声波挪开,例如居中 `{"y":50,"w":70}`。

```json
[{"type":"addTrack","kind":"visual","ref":"wave"},
 {"type":"insertItems","items":[{"type":"visualizer","trackRef":"wave","span":{"fromFrame":0,"durationFrames":37840},"place":{"y":54,"w":85,"scaleY":1.574074},"visualizer":{"style":"audio_envelope"}}]}]
```

{{tool:videos_frames}} 的帧里没有这些元素;要看画面就导出一小段({{tool:export}},{{arg:purpose}} 为 `preview`)再抽帧。

### 剪口播的机制

1. `proposeCuts`(给素材 ID,`detect` 里选口癖、停顿与目标停顿长度)生成剪辑提案:一份 kind 为 `editorial-proposal` 的文档,不改时间线。
2. {{tool:documents_read}} 读提案:`suggestions` 每条有 `id`、`kind`(filler 或 pause)、源区间、`text`、`reason`。
3. `acceptCutSuggestions` 只接受该删的那些;要改区间就直接 `addCuts`(素材自己的秒)并把建议 ID 写进 `ref`。
4. 提案不检测说了两遍的句子:录废重来的自己按转写的词时间用 `addCuts` 剪。
5. 剪口可以 `restoreCut` 恢复;剪口集合是 kind 为 `cut-set` 的文档。

转写在提出提案之后改过时,接受会失败(`details.rule` 为 `proposal-stale`):重新 `proposeCuts`。

### 章节

- **自己分的章节**:`setChapters` 整个替换章节列表(按时间严格递增,第一章通常在 0);只改一章用 `upsertChapter`。怎么分见 {{skill:video-chapters}}。先用 {{tool:speech_topic_boundaries}}({{arg:video}};可给 {{arg:minChapterSec}}、{{arg:maxChapters}})取按意思找到的话题转折:`mode` 为 `topic` 时章节只落在 `first` 与 `candidates[].at`,可以合并不新增;为 `model` 时没有候选,读文稿自己判断。
- **作者的章节或用户贴的大纲**:{{tool:chapters_adopt}},不手工对时间。给 {{arg:video}}(可给 {{arg:asset}}、{{arg:document}})时取素材的作者章节(`assets[].source.chapters`);给 {{arg:outline}}(`[{ at, title }]` 或大纲原文)时用用户的大纲。它把每条吸到文稿最近的段落或句子起点(段落、句子、字幕条、词依次退),清洗标题后以 `setChapters` 写入;{{arg:dryRun}} 只看结果不写。回执的 `sourceChapters` 给出 `entries`、`matched`、`ambiguous`(附近几个起点,取了离作者时间最近的)、`snapped`、`unanchored`(对不上,保留原时间)与逐条的 `rows`,没对上的告诉用户。`untitled` 的章节平台只给了分界(`Untitled Chapter N` 是占位名):按转写起标题,连同其余各章用 {{arg:outline}} 再调用,直接采用会返回 `UNTITLED_SOURCE_CHAPTERS`。`NO_SOURCE_CHAPTERS`:没有作者章节,改按 {{skill:video-chapters}} 自己分;`ASSET_NOT_PLACED`:素材不在时间线上。

章节固定在时间线的时刻上,不跟着片段移动:移动、删除片段或波纹删除之后要重新核对。剪口播例外:`addCuts`、`acceptCutSuggestions` 与 `restoreCut` 让章节跟着内容走(剪掉的段后面的章前移,整章都剪掉的删掉;恢复时接缝之后的后移)。

### 派生子视频

{{tool:videos_derive}} 把父视频的一段建成旁边的一个可编辑子视频(做法见 {{skill:shorts-segments}})。{{arg:hook}}、{{arg:reason}}、{{arg:notes}} 写进子视频的派生来源文档(notes 每条至多 80 字、至多 8 条);结果原样回显文档里记下的 `hook`、`reason`、`notes`,没有的不带。认回已有的子视频(`reused` 为 true)时文档不改写,回显的是原来那份,不是这次传的。要再读一次就用 {{tool:documents_read}} 读结果的 `derivationDocumentId`。

按镜头分别取景时给 {{arg:crops}}:每段 `from`、`to` 是父视频剪辑后时间线上的秒(直接用 {{tool:videos_shots}} 的 `shots`),加这段的四边裁剪。主素材的片段在取景变化处拆开,各带自己的裁剪;结果的 `framing` 是对到帧、截到区间后实际采用的各段,`crops-adjusted` 说明有段被截过或丢掉,`animation-split` 说明拆开的片段有循环动画或音量包络、每段从头算。区间之前、之后的部分沿用第一段、最后一段的取景:恢复首尾的话时放回来的画面跟着那一段,那截若是另一个镜头取景就不对,要在提示牌里说。全屏加 `cover` 的片段里这些裁剪存成取景点(`focalPoint`):画面一样,源画面不裁,用户之后把画布改回原画幅还能看到完整画面;要改单个片段的取景就用 `setStyle` 的 `focalPoint`;它的 `zoom`(1 到 4,缺省 1)是在铺满之上围着取景点再放大。用户在画布上对这种片段只能改放大,位置跟着取景点。

多人全景要每人一格时,{{arg:crops}} 的那一段写 `{from, to, layout, panels}`:`layout` 是 `rows`(2 或 3 人上下排开)或 `grid`(4 人田字格),`panels` 是每个人要看见的源区域(四边比例)。Runtime 按区域中心从左到右排进格子(最左的人在最上面),换成每格的取景点,主素材的全屏 `cover` 片段写成 `panels`;只在画幅变了、`fit` 为 `cover` 时生效,否则当一人裁剪(`panels-ignored`)。`split-short`(分屏段短于 3 秒)、`panel-upscaled`(某格放大量超过 2.5,会发虚)、`panel-region-cropped`(区域装不下)要如实转述。之后改某一格用 `setStyle` 的 `panels`(整份替换,`null` 换回一人)。

### 撤销与历史

- {{tool:edits_undo}}:撤销你自己最近的一笔;也可以给 {{arg:transactionId}} 指定一笔。撤销本身也是一笔新修改,返回同样的回执。
- {{tool:videos_history}}:列出历史(谁改的、改完的版本、能不能撤销)与检查点。
- 改错了就撤销自己那一步,不手工反向修改;用户改的那几笔不要替他撤。

### 版本记录

项目里的视频由 BaoCut 自动记版本(不依赖 git):一段连续的修改合成一个版本,带着谁改的、在哪个会话里改的。

- 要了解一部视频最近改了什么,先用 {{tool:videos_versions}} 读版本记录,不必翻 {{tool:videos_history}};某一版具体怎么改的用 {{tool:videos_version_diff}}({{arg:version}})。
- 用户要「回到之前那版」时用 {{tool:videos_restore_version}}:先在版本记录里找到版本号,拿不准时看 diff 或问用户;{{arg:before}} 为 true 是回到那一版开始之前。回到版本也是一笔修改,可以用 {{tool:edits_undo}} 撤销。
- 用户要存一版、或大改之前要留一个回得去的点时用 {{tool:videos_save_version}}({{arg:name}});平时的修改会自动记下,不用每次都存。
- 不要手改视频目录里的 `.bcut-snapshot/`,也不要替用户对它 `git checkout` 或 `git reset`。BaoCut 之外的改动(`git pull`、同步盘)会自动导入为一笔「外部变更」;{{tool:videos_versions}} 的 `snapshot.state` 是 `conflict` 时,视频里也有还没写进快照的修改,或快照读不出:告诉用户,由用户选保留哪边,你照常编辑。

## 结果怎么读

回执是唯一的事实:只有回执里的才是真正改了的。

- `revision`:新的版本,下一笔修改带它。
- `transactionId`:这一笔,撤销时用。
- 创建、修改、删除的对象 ID:新片段的 `itemId` 从这里取。
- 时长变化:剪口播后报告给用户。
- `timeResolution`:时间实际对齐到哪一帧。
- 附带的说明:`removedTransitions`(转场不再成立被删)、`removedByCuts`(整个落在剪掉范围里的片段)、`shortenedTransitions`、`orphanedAnchors` 等,出现了就向用户说明。

## 常见错误码

| 错误码 | 下一步 |
| --- | --- |
| `PROJECT_REVISION_CONFLICT` | 视频刚被改过:重新 {{tool:videos_inspect}},按新状态决定 |
| `TARGET_LOCKED` | 片段或轨道锁着:问用户要不要解锁,不要自己解 |
| `TRANSITION_HANDLES_INSUFFICIENT` | 剪切点两侧素材余量不够:`details` 给出缺几帧;裁短片段或缩短转场 |
| `INVALID_ARGUMENTS` | 操作写错:用 {{tool:edits_ops}} 查这个操作的 schema 后改 |
| `ASSET_MISSING` | 链接的素材文件不在了:请用户放回或给新位置 |

## 下一步

- 剪过之后转写的时间线视图变了,译文会过期:去 [subtitles](subtitles.md) 只重译变了的句子。
- 要看画面:去 [media](media.md) 取帧。
- 要文件:去 [export](export.md)。

## 验收

- 读回:{{tool:videos_inspect}} 看片段与时长,{{tool:documents_read}} 看剪口集合或章节,对照计划逐项核对:该删的删了,该留的还在。
- 剪点落在词与词之间,换气留着;停顿顺不顺要人听,导出一小段给用户听,并在报告里写明哪些只是量出来的。
- 挪过片段之后,别的轨道上的文字、放大、B-roll 要重新读一遍核对位置。
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall