# 场景和音乐

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

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

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

## minicut scene api

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

### Usage

```bash Usage
minicut scene api
```

### 说明

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

全局选项：见[全局选项](/zh-cn/docs/cli/global-options)。

### 示例

### 拿到导入语句

```bash Command
minicut scene api
```

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

### 另见

[minicut scene build](#minicut-scene-build)、[minicut scene check](#minicut-scene-check)

## minicut scene build

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

### Usage

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

替换下面的内容：

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

### 说明

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

### 选项

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

全局选项：见[全局选项](/zh-cn/docs/cli/global-options)。

### 示例

### 用操作文件生成场景

```bash Command
minicut scene build episodes/ep01/scenes/c03.scene.ops.json
```

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

### 输出

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

### 另见

[minicut scene check](#minicut-scene-check)

## minicut scene check

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

### Usage

```bash Usage
minicut scene check FILE [--loose]
```

替换下面的内容：

- `FILE`：要检查的场景文件。

### 说明

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

### 选项

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

全局选项：见[全局选项](/zh-cn/docs/cli/global-options)。

### 示例

### 检查一个镜头的场景

```bash Command
minicut scene check episodes/ep01/scenes/c03.scene.json
```

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

### 输出

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

### 另见

[minicut scene render](#minicut-scene-render)、[检查和环节](/zh-cn/docs/cli/checks-and-loops)

## minicut scene render

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

### Usage

```bash 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` | 开关 | 关 | 即使什么都没变，也重新画一个片段。 |

全局选项：见[全局选项](/zh-cn/docs/cli/global-options)。

### 示例

### 从场景中间画一张静帧

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

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

```bash Command
minicut scene render --project night-market --episode ep01 --clip
```

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

### 输出

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

### 另见

[minicut scene check](#minicut-scene-check)、[生成](/zh-cn/docs/cli/generate)

## minicut scene undo

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

### Usage

```bash Usage
minicut scene undo FILE
```

替换下面的内容：

- `FILE`：场景文件。

### 说明

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

全局选项：见[全局选项](/zh-cn/docs/cli/global-options)。

### 另见

[minicut scene build](#minicut-scene-build)

## minicut scene panorama

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

### Usage

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

替换下面的内容：

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

### 选项

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

全局选项：见[全局选项](/zh-cn/docs/cli/global-options)。

### 另见

[minicut scene to-board](#minicut-scene-to-board)

## minicut scene to-board

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

### Usage

```bash 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` | 字符串 | 无 | 新节点的标签。 |

全局选项：见[全局选项](/zh-cn/docs/cli/global-options)。

### 另见

[minicut scene panorama](#minicut-scene-panorama)、[生成](/zh-cn/docs/cli/generate)

## minicut music

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

### Usage

```bash 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`：要写出的歌曲文件。 |

全局选项：见[全局选项](/zh-cn/docs/cli/global-options)。

### 示例

### 读出一集的时间安排

```bash Command
minicut music cuts episodes/ep01 --json
```

### 检查并播放一首歌

```bash Command
minicut music check episodes/ep01/music/score.song.json
minicut music render episodes/ep01/music/score.song.json
```

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

### 对照这一集测量结果

```bash Command
minicut music measure episodes/ep01/music/score.wav --episode episodes/ep01
```

### 输出

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

### 限制

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

### 另见

[初始设置](/zh-cn/docs/cli/setup)、[检查和环节](/zh-cn/docs/cli/checks-and-loops)

## 错误

| 信息 | 怎么做 |
|---|---|
| `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` 渲染短一点的一段。 |

## 下一步

[剪辑器](/zh-cn/docs/cli/editor) [检查和环节](/zh-cn/docs/cli/checks-and-loops) [全局选项](/zh-cn/docs/cli/global-options)