# Scene and music

Every command that builds, checks and draws a 3D scene, and every command that checks, plays and measures an episode's music.

A 3D scene and a song are both files your agent writes. The CLI checks them, then draws the scene or plays the song on your computer. These commands send nothing to a model.

Every command on this page needs a signed-in computer. Signed out, each one prints `You are not signed in. Ask your agent to run minicut login.` and exits with code `10`. See [Account](/docs/cli/account).

## minicut scene api

Prints the import line for a scene script that you run yourself with Node.js.

### Usage

```bash Usage
minicut scene api
```

### Details

Put the printed line at the top of your script. The script then has the scene composer's own operations and a save that checks the scene before it writes. MiniCut never runs your script. You run it, so your agent app's permission check sees every run.

Global options: see [Global options](/docs/cli/global-options).

### Examples

### Get the import line

```bash Command
minicut scene api
```

You see one import line to copy into your script.

### See also

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

## minicut scene build

Applies a list of scene operations to a fresh scene, checks it, and writes the scene file.

### Usage

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

Replace the following:

- `NAME.scene.ops.json`: a data file that lists the scene operations and their arguments.
- `FILE`: the scene file to write.

### Details

An operations file is data only. A file that holds code is refused. Without `--out`, the command writes `NAME.scene.json` beside the operations file and raises its revision number by one. If the scene has problems, nothing is written.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--out` | path | `NAME.scene.json` | The scene file to write. |

Global options: see [Global options](/docs/cli/global-options).

### Examples

### Build a scene from an operations file

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

You see `Wrote` with the scene file, its revision and a short summary of the scene.

### Output

| Exit code | Meaning |
|---|---|
| `0` | The scene file was written. |
| `1` | The scene has problems. Nothing was written. |
| `2` | The file is missing or the command is wrong. |

### See also

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

## minicut scene check

Checks a scene file against the composer's own rules and limits.

### Usage

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

Replace the following:

- `FILE`: the scene file to check.

### Details

The check reads the scene's structure and limits first. Then it checks every body against every prop and the floor, at every frame. It prints one line for each problem.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--loose` | switch | off | Run the check without the strict rules. |

Global options: see [Global options](/docs/cli/global-options).

### Examples

### Check a shot's scene

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

You see `OK` with a summary of the scene, or the number of problems and one line for each.

### Output

| Exit code | Meaning |
|---|---|
| `0` | No problems. No body goes through a prop or the floor. |
| `1` | One or more problems. Each one is printed. |
| `2` | The file is missing or the command is wrong. |

### See also

[minicut scene render](#minicut-scene-render), [Checks and loops](/docs/cli/checks-and-loops)

## minicut scene render

Draws a scene as a still or a clip on your computer.

### 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]
```

Replace the following:

- `FILE`: the scene file to draw.
- `CAMERA`: the id of a camera in the scene.
- `SECOND`: the second of the scene to draw as a still.
- `PROJECT`, `EPISODE`, `CLIP`: where to save a clip, for example `night-market`, `ep01`, `c03`.
- `LIBRARY_ID`: the library entry to save a still into.
- `WIDTH`: the frame width in pixels.

### Details

A clip is saved as the next take of the named shot. A still goes into your library with `--project` or `--id`. Without them, it goes into the `cache/stills` folder of your MiniCut home folder, and the path is printed. Every render keeps two copies: the clean picture, and a copy in `labeled/` with a name tag on every asset, for people to read.

The render is refused while a body goes through a prop or the floor in the frames it would draw. A clip whose scene, camera and size are unchanged since its newest take is not drawn again.

With several files, or with `--project` and `--episode` alone, the command draws many scenes in one run. With `--project` and `--episode` alone, it draws every shot scene of the episode, in shot order.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--camera` | string | the scene's own camera | The camera to draw from. |
| `--still` | second or `middle` | none | Draw one still at this second, or at the middle second. |
| `--clip` | switch, or a clip id | none | Draw a clip. |
| `--project` | string | none | The project to save into. |
| `--episode` | string | none | The episode to save into. |
| `--id` | string | none | The library entry to save a still into. |
| `--draft` | switch | off | Draw half of each side (640 x 360 for 16:9), for mock looks. |
| `--size` | number | the full size | Any even width from 128 up to the full width. |
| `--force` | switch | off | Draw a clip again even if nothing changed. |

Global options: see [Global options](/docs/cli/global-options).

### Examples

### Draw a still from the middle of a scene

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

### Draw every shot scene of an episode as clips

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

You see each scene as it is drawn, then one line with how many were drawn, unchanged and not drawn.

### Output

| Exit code | Meaning |
|---|---|
| `0` | Every scene was drawn or was already up to date. |
| `1` | A scene has a body going through a prop or the floor. |
| `2` | The command is wrong or a file is missing. |
| `5` | An option value is wrong. The message names it. |

### See also

[minicut scene check](#minicut-scene-check), [Generate](/docs/cli/generate)

## minicut scene undo

Puts back the version of a scene before its last write.

### Usage

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

Replace the following:

- `FILE`: the scene file.

### Details

It undoes the last write from the MiniCut app or from an agent. The last 20 versions are kept.

Global options: see [Global options](/docs/cli/global-options).

### See also

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

## minicut scene panorama

Sets or clears the panorama picture of a scene.

### Usage

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

Replace the following:

- `FILE`: the scene file.
- `PICTURE`: a picture on your computer. It is also put on the episode's board.
- `BOX_ID`: the id of a picture box on the episode's board.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--image` | path | none | Use this picture from your computer. |
| `--box` | string | none | Use this picture box from the board. |
| `--clear` | switch | off | Remove the panorama picture. |

Global options: see [Global options](/docs/cli/global-options).

### See also

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

## minicut scene to-board

Copies a picture or clip next to the scene and adds it as a box on the episode's board.

### Usage

```bash Usage
minicut scene to-board FILE MEDIA [--label WORDS]
```

Replace the following:

- `FILE`: a scene file inside an episode, `<project>/episodes/epNN/scenes/NAME.scene.json`.
- `MEDIA`: the picture or clip to send to the board.
- `WORDS`: the label for the new box.

### Details

The episode needs a board first. Make one with `minicut board new --project PROJECT --episode EPISODE`.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--label` | string | none | The label for the new box. |

Global options: see [Global options](/docs/cli/global-options).

### See also

[minicut scene panorama](#minicut-scene-panorama), [Generate](/docs/cli/generate)

## minicut music

Gives your own music script what it needs, then checks, plays and measures the song file it writes.

### 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]
```

Replace the following:

- `EPISODE_FOLDER`: the episode folder, for example `episodes/ep01`.
- `SONG`: a song file, `NAME.song.json`.
- `SECONDS`: a time in the song, in seconds.
- `WAV`: a `.wav` file that `minicut music render` made.
- `MIDI`: a `.mid` file from any music tool.
- `MAP`: a `.json` file that maps the MIDI tracks to instruments.

### Details

Your agent writes its own music script in Python 3.9 or newer and runs it itself. The script writes a song file. A song file is data only: instruments by catalog id, synths by preset id, no paths and no code. MiniCut never runs your script, and the music commands open no network connection. Your agent runs these commands in the Mock loop.

| Subcommand | Does |
|---|---|
| `api` | Prints the import lines for your music script. The module uses the Python standard library only. |
| `instruments` | Lists instrument ids, note ranges, drum kit pieces and settings. |
| `cuts` | Lists the episode's shots, cuts, scene changes and spoken lines, in seconds. |
| `check` | Checks that a song file can be played: ids, ranges and limits. |
| `render` | Plays the song into audio files beside it. |
| `measure` | Reports loudness, peaks, hits on cuts and the music level under spoken lines. |
| `from-midi` | Turns a MIDI file into a song file. |

`render` writes `NAME.wav`, `NAME.mp3`, `NAME.beats.json`, `NAME-waveform.png` and `NAME.report.json` beside the song. It needs the instrument samples that `minicut setup` installs once, about 396 MB.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--json` | switch | off | `api`, `instruments` and `cuts`: print the result as JSON. |
| `--from` | seconds | the start | `render`: start playing at this time. |
| `--to` | seconds | the end | `render`: stop playing at this time. |
| `--stems` | switch | off | `render`: also write each instrument as its own file. |
| `--no-mp3` | switch | off | `render`: skip the `.mp3` file. |
| `--episode` | path | none | `measure`: compare the music with this episode's cuts and spoken lines. |
| `--map` | path | none | `from-midi`: the file that maps MIDI tracks to instruments. Required. |
| `--out` | path | `NAME.song.json` beside the MIDI file | `from-midi`: the song file to write. |

Global options: see [Global options](/docs/cli/global-options).

### Examples

### Read the timing of an episode

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

### Check and play a song

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

You see the problems in the song file, if any, then the files that `render` wrote.

### Measure the result against the episode

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

### Output

| Exit code | Meaning |
|---|---|
| `0` | The command finished. |
| `2` | The command could not run: a file is missing, or a tool needs `minicut setup`. |
| `5` | The song file or MIDI map has problems. Each one is printed. |

### Limits

| Limit | Value |
|---|---|
| Song file size | 32 MB |
| Time for one `render` | 30 minutes |
| Time for one `measure` | 10 minutes |

### See also

[Setup](/docs/cli/setup), [Checks and loops](/docs/cli/checks-and-loops)

## Errors

| Message | What to do |
|---|---|
| `You are not signed in. Ask your agent to run minicut login.` | Run `minicut login`, then run the command again. |
| `no such file: ...` | Check the path to the scene file. |
| `Not written: N problem(s). ... is unchanged.` | Fix the problems printed above it, then build again. |
| `Use --draft or --size <width>, not both.` | Pick one of the two. |
| `--size is the frame width in pixels: an even number from 128 to ...` | Give an even width in that range. |
| `Each clip is saved as the next take of its shot: add --project <id> --episode epNN.` | Add `--project` and `--episode` to draw clips from many scenes. |
| `this episode has no board yet: make one with minicut board new ...` | Run the `minicut board new` command in the message. |
| `no Python found. Run: minicut setup` | Run `minicut setup`. |
| `the music tools are not set up (...). Run: minicut setup` | Run `minicut setup`. |
| `no instrument samples in .... Run: minicut setup (about 396 MB, once). Nothing was rendered.` | Run `minicut setup`. |
| `the song file is over 32 MB` | Make the song file smaller. |
| `Stopped: it ran past the time limit.` | Render a shorter part with `--from` and `--to`. |

## Next

[Editor](/docs/cli/editor) [Checks and loops](/docs/cli/checks-and-loops) [Global options](/docs/cli/global-options)