文档 / CLI 参考

场景和音乐

搭建、检查和画出 3D 场景的每条命令，以及检查、播放和测量一集音乐的每条命令。

3D 场景和歌曲都是你的 Agent 写的文件。CLI 检查它们，然后在你的电脑上画出场景或播放歌曲。这些命令不会向任何模型发送东西。

本页的每条命令都需要这台电脑已登录。没登录时，每条命令都会打印 You are not signed in. Ask your agent to run minicut login.，并以退出码 10 结束。见账号。

minicut scene api

打印一行导入语句，用于你自己用 Node.js 运行的场景脚本。

Usage

Usage

minicut scene api

说明

把打印出来的那一行放在你脚本的最上面。脚本就有了场景编辑器自己的各项操作，以及一个写文件之前先检查场景的保存函数。MiniCut 从不运行你的脚本。脚本由你运行，所以你的 Agent 应用的权限检查能看到每一次运行。

全局选项：见全局选项。

示例

拿到导入语句

Command

minicut scene api

你会看到一行导入语句，复制到你的脚本里。

另见

minicut scene build、minicut scene check

minicut scene build

把一列场景操作应用到一个全新的场景上，检查它，并写出场景文件。

Usage

Usage

minicut scene build NAME.scene.ops.json [--out FILE]

替换下面的内容：

NAME.scene.ops.json：一个数据文件，列出场景操作和它们的参数。
FILE：要写出的场景文件。

说明

操作文件只能是数据。里面有代码的文件会被拒绝。不加 --out 时，命令在操作文件旁边写出 NAME.scene.json，并把它的修订号加 1。如果场景有问题，什么都不写。

选项

选项	类型	默认值	说明
`--out`	路径	`NAME.scene.json`	要写出的场景文件。

全局选项：见全局选项。

示例

用操作文件生成场景

Command

minicut scene build episodes/ep01/scenes/c03.scene.ops.json

你会看到 Wrote，后面是场景文件、它的修订号和场景的简短摘要。

输出

退出码	含义
`0`	场景文件写好了。
`1`	场景有问题。什么都没写。
`2`	文件缺失，或者命令不对。

另见

minicut scene check

按场景编辑器自己的规则和限制检查一个场景文件。

Usage

Usage

minicut scene check FILE [--loose]

替换下面的内容：

FILE：要检查的场景文件。

说明

检查先读场景的结构和限制。然后它在每一帧里，检查每个身体对每个道具和地面的关系。每个问题打印一行。

选项

选项	类型	默认值	说明
`--loose`	开关	关	不用严格规则运行检查。

全局选项：见全局选项。

示例

检查一个镜头的场景

Command

minicut scene check episodes/ep01/scenes/c03.scene.json

你会看到 OK 和场景的摘要，或者问题的数量加上每个问题一行。

输出

退出码	含义
`0`	没有问题。没有身体穿过道具或地面。
`1`	有一个或多个问题。每个都会打印出来。
`2`	文件缺失，或者命令不对。

另见

minicut scene render、检查和环节

minicut scene render

在你的电脑上把场景画成静帧或片段。

Usage

Usage

minicut scene render FILE [--camera CAMERA] {--still SECOND|--still middle|--clip} [--project PROJECT --episode EPISODE --clip CLIP] [--id LIBRARY_ID] [--draft | --size WIDTH] [--force]
minicut scene render FILE FILE ... {--still SECOND|--clip} [--draft] [--force]
minicut scene render --project PROJECT --episode EPISODE {--still SECOND|--clip} [--draft] [--force]

替换下面的内容：

FILE：要画的场景文件。
CAMERA：场景里一个机位的 id。
SECOND：场景里要画成静帧的那一秒。
PROJECT、EPISODE、CLIP：片段存在哪里，例如 night-market、ep01、c03。
LIBRARY_ID：要把静帧存进去的素材库条目。
WIDTH：画面宽度，单位是像素。

说明

片段会存成指定镜头的下一个版本。静帧加上 --project 或 --id 就进你的素材库。不加的话，它进 MiniCut 主文件夹的 cache/stills 文件夹，并打印路径。每次渲染保留两份：干净的图片，以及 labeled/ 里的一份，每个资产上都有名字标签，给人看。

如果在要画的帧里有身体穿过道具或地面，渲染会被拒绝。一个片段的场景、机位和尺寸自它最新的版本以来都没有变，就不会重画。

给出多个文件，或者只给 --project 和 --episode，命令一次运行画出多个场景。只给 --project 和 --episode 时，它按镜头顺序画出这一集的每个镜头场景。

选项

选项	类型	默认值	说明
`--camera`	字符串	场景自己的机位	从哪个机位画。
`--still`	秒数或 `middle`	无	在这一秒，或者在中间那一秒，画一张静帧。
`--clip`	开关，或镜头 id	无	画一个片段。
`--project`	字符串	无	要存进的项目。
`--episode`	字符串	无	要存进的集。
`--id`	字符串	无	要把静帧存进去的素材库条目。
`--draft`	开关	关	每条边画一半大小（16:9 时是 640 x 360），用于预览片的效果。
`--size`	数字	完整尺寸	从 128 到完整宽度之间的任意偶数宽度。
`--force`	开关	关	即使什么都没变，也重新画一个片段。

全局选项：见全局选项。

示例

从场景中间画一张静帧

Command

minicut scene render episodes/ep01/scenes/c03.scene.json --still middle --draft

把一集的每个镜头场景画成片段

Command

minicut scene render --project night-market --episode ep01 --clip

你会看到每个场景画出来的过程，然后一行写着画了多少个、没变化多少个、没画多少个。

输出

退出码	含义
`0`	每个场景都画好了，或者本来就是最新的。
`1`	某个场景里有身体穿过道具或地面。
`2`	命令不对，或者文件缺失。
`5`	某个选项的值不对。信息里会点名。

另见

minicut scene check、生成

minicut scene undo

恢复场景上一次写入之前的版本。

Usage

Usage

minicut scene undo FILE

替换下面的内容：

FILE：场景文件。

说明

它撤销从 MiniCut 应用或从 Agent 做的上一次写入。最近 20 个版本会保留。

全局选项：见全局选项。

另见

minicut scene build

minicut scene panorama

设置或清除场景的全景图片。

Usage

Usage

minicut scene panorama FILE {--image PICTURE|--box BOX_ID|--clear}

替换下面的内容：

FILE：场景文件。
PICTURE：你电脑上的一张图片。它同时会放到这一集的画布面板上。
BOX_ID：这一集的画布面板上一个图片节点的 id。

选项

选项	类型	默认值	说明
`--image`	路径	无	使用你电脑上的这张图片。
`--box`	字符串	无	使用画布面板上的这个图片节点。
`--clear`	开关	关	移除全景图片。

全局选项：见全局选项。

另见

minicut scene to-board

把一张图片或一个片段复制到场景旁边，并作为一个节点加到这一集的画布面板上。

Usage

Usage

minicut scene to-board FILE MEDIA [--label WORDS]

替换下面的内容：

FILE：一集之内的场景文件，<project>/episodes/epNN/scenes/NAME.scene.json。
MEDIA：要送到画布面板上的图片或片段。
WORDS：新节点的标签。

说明

这一集要先有画布面板。用 minicut board new --project PROJECT --episode EPISODE 建一个。

选项

选项	类型	默认值	说明
`--label`	字符串	无	新节点的标签。

全局选项：见全局选项。

另见

minicut scene panorama、生成

minicut music

给你自己的音乐脚本提供它需要的东西，然后检查、播放和测量它写出的歌曲文件。

Usage

Usage

minicut music api [--json]
minicut music instruments [--json]
minicut music cuts EPISODE_FOLDER [--json]
minicut music check SONG
minicut music render SONG [--from SECONDS --to SECONDS] [--stems] [--no-mp3]
minicut music measure WAV [--episode EPISODE_FOLDER]
minicut music from-midi MIDI --map MAP [--out SONG]

替换下面的内容：

EPISODE_FOLDER：这一集的文件夹，例如 episodes/ep01。
SONG：歌曲文件，NAME.song.json。
SECONDS：歌曲里的一个时间点，单位是秒。
WAV：minicut music render 做出的 .wav 文件。
MIDI：任何音乐工具做出的 .mid 文件。
MAP：一个 .json 文件，把 MIDI 轨道对应到乐器。

说明

你的 Agent 用 Python 3.9 或更新的版本写自己的音乐脚本，并自己运行它。脚本写出一个歌曲文件。歌曲文件只能是数据：按目录 id 写乐器，按预设 id 写合成器，没有路径，也没有代码。MiniCut 从不运行你的脚本，音乐命令也不会打开任何网络连接。你的 Agent 在预览片环节运行这些命令。

子命令	作用
`api`	打印你的音乐脚本用的导入语句。这个模块只用 Python 标准库。
`instruments`	列出乐器 id、音域、鼓组的各个部件和设置。
`cuts`	以秒为单位，列出这一集的镜头、切换点、场景变化和台词。
`check`	检查歌曲文件能不能播放：id、音域和限制。
`render`	把歌曲播放成它旁边的音频文件。
`measure`	报告响度、峰值、切换点上的音符，以及台词下面的音乐音量。
`from-midi`	把 MIDI 文件转成歌曲文件。

render 在歌曲旁边写出 NAME.wav、NAME.mp3、NAME.beats.json、NAME-waveform.png 和 NAME.report.json。它需要 minicut setup 一次性装好的乐器采样，大约 396 MB。

选项

选项	类型	默认值	说明
`--json`	开关	关	`api`、`instruments` 和 `cuts`：把结果打印成 JSON。
`--from`	秒	开头	`render`：从这个时间点开始播放。
`--to`	秒	结尾	`render`：播放到这个时间点停止。
`--stems`	开关	关	`render`：同时把每个乐器写成单独的文件。
`--no-mp3`	开关	关	`render`：不写 `.mp3` 文件。
`--episode`	路径	无	`measure`：把音乐和这一集的切换点和台词对比。
`--map`	路径	无	`from-midi`：把 MIDI 轨道对应到乐器的文件。必须给。
`--out`	路径	MIDI 文件旁边的 `NAME.song.json`	`from-midi`：要写出的歌曲文件。

全局选项：见全局选项。

示例

读出一集的时间安排

Command

minicut music cuts episodes/ep01 --json

检查并播放一首歌

Command

minicut music check episodes/ep01/music/score.song.json
minicut music render episodes/ep01/music/score.song.json

你会看到歌曲文件里的问题（如果有的话），然后是 render 写出的文件。

对照这一集测量结果

Command

minicut music measure episodes/ep01/music/score.wav --episode episodes/ep01

输出

退出码	含义
`0`	命令完成了。
`2`	命令没法运行：文件缺失，或者某个工具需要先运行 `minicut setup`。
`5`	歌曲文件或 MIDI 映射有问题。每个都会打印出来。

限制

限制	值
歌曲文件大小	32 MB
一次 `render` 的时间	30 分钟
一次 `measure` 的时间	10 分钟

另见

初始设置、检查和环节

错误

信息	怎么做
`You are not signed in. Ask your agent to run minicut login.`	运行 `minicut login`，再运行一次命令。
`no such file: ...`	检查场景文件的路径。
`Not written: N problem(s). ... is unchanged.`	修好它上面打印的问题，再生成一次。
`Use --draft or --size <width>, not both.`	两个选一个。
`--size is the frame width in pixels: an even number from 128 to ...`	给这个范围内的偶数宽度。
`Each clip is saved as the next take of its shot: add --project <id> --episode epNN.`	要从多个场景画片段，加上 `--project` 和 `--episode`。
`this episode has no board yet: make one with minicut board new ...`	运行信息里的 `minicut board new` 命令。
`no Python found. Run: minicut setup`	运行 `minicut setup`。
`the music tools are not set up (...). Run: minicut setup`	运行 `minicut setup`。
`no instrument samples in .... Run: minicut setup (about 396 MB, once). Nothing was rendered.`	运行 `minicut setup`。
`the song file is over 32 MB`	把歌曲文件做小一点。
`Stopped: it ran past the time limit.`	用 `--from` 和 `--to` 渲染短一点的一段。

下一步

剪辑器检查和环节全局选项