# Editor

Every command that opens, changes, checks or renders the edited cut of an episode, with its usage, options and errors.

These commands work on one episode's cut, the file `index.html` in the episode folder. An episode folder is `<project>/episodes/ep01`. Your agent runs them in the Edit loop, after the Videos loop.

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).

Every command except `minicut edit` and `minicut catalog` runs in the episode folder. A path you name must be inside that folder.

## minicut edit

Opens the MiniCut editor on one episode and prints a link to it.

### Usage

```bash Usage
minicut edit PROJECT [--episode EPISODE] [--port PORT]
```

Replace the following:

- `PROJECT`: the project id or the project folder.
- `EPISODE`: the episode, `ep01` to `ep999`.
- `PORT`: the port on your computer the editor listens on.

### Details

The editor runs on your computer until you stop it. Each episode keeps its port, so the link stays the same on every restart while that port is free. If another program holds the port, the editor moves to a free one and says the link changed. If this episode's editor is already running, the command prints its address and starts nothing new.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--episode` | string | `ep01` | The episode to open. |
| `--port` | number | the episode's own port | The port to start on. If it is in use, the editor takes a free port and says so. |

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

### Examples

### Open the first episode of a project

```bash Command
minicut edit night-market
```

You see the editor version, a link that works once within 2 minutes, and the command that stops the editor.

### Open episode 2

```bash Command
minicut edit night-market --episode ep02
```

### Output

The link carries a one-time code. To open the editor again after 2 minutes, run `minicut edit` again. Stop the editor with Ctrl+C.

| Exit code | Meaning |
|---|---|
| `0` | The editor ran and stopped, or it was already running. |
| `2` | The project or episode has no cut, or the editor is not installed. |
| `10` | This computer is not signed in. |

### See also

[minicut render](#minicut-render), [Projects](/docs/cli/projects)

## minicut render

Renders the episode in this folder to a video file, or runs the editor's lint, check or transcript import on it.

### Usage

```bash Usage
minicut render [-o FILE] [--quality {draft|looks|delivery}]
minicut render lint [--json]
minicut render check [--json]
minicut render transcribe TRANSCRIPT
```

Replace the following:

- `FILE`: the video file to write, a `.mp4`, `.webm` or `.mov` path inside the episode folder, for example `renders/ep01.mp4`.
- `TRANSCRIPT`: a `.json` transcript file inside the episode folder.

### Details

`minicut render` makes the finished episode as one video file in the episode folder. `lint` is a fast check of the cut while you edit. `check` runs lint, then opens the cut and checks it again. `transcribe` puts a transcript into the episode.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `-o`, `--out` | path | none | The video file to write. |
| `--quality` | `draft`, `looks` or `delivery` | `looks` | `draft` while you try changes, `looks` for the first real render, `delivery` for the final file. |
| `--json` | switch | off | `lint` and `check` only: print the result as JSON. |

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

### Examples

### Render the final file

```bash Command
minicut render -o renders/ep01.mp4 --quality delivery
```

You see the render's progress, then the file appears at `renders/ep01.mp4`.

### Check the cut before a render

```bash Command
minicut render check
```

### Output

`lint` and `check` print one line for each problem. With `--json` they print the result as JSON.

| Exit code | Meaning |
|---|---|
| `0` | The render or check finished. |
| `2` | A flag is wrong, or this folder has no `index.html`. |
| `10` | This computer is not signed in. |

### See also

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

## minicut timeline

Prints the cut, or changes it in one step that `minicut timeline undo` reverses.

### Usage

```bash Usage
minicut timeline [--json]
minicut timeline {move|trim|split|delete|duplicate|ids|apply|undo} ...
minicut timeline set '#CLIP_ID' --text "WORDS" [--json]
minicut timeline fit [--plan] [--json]
minicut timeline fit --undo
```

Replace the following:

- `CLIP_ID`: the id of a caption, title or card clip, for example `cap-c05-l01`.
- `WORDS`: the new words for that clip.

### Details

With no subcommand, `minicut timeline` lists every track and clip: starts, ends and what plays. Each change is one step, and each step can be undone. Run `minicut timeline SUBCOMMAND --help` for the arguments a subcommand takes.

| Subcommand | Does |
|---|---|
| `move`, `trim`, `split`, `delete`, `duplicate` | One edit to a clip. |
| `set` | Changes the words of a caption, title or card. |
| `ids` | Prints the clip ids. |
| `apply` | Applies a list of edits from a file in one step. |
| `undo` | Reverses one change, from its undo receipt. |
| `fit` | Cuts every shot that is longer than its take down to the take. |

`fit` moves everything after a shortened shot up, so the cut gets shorter and no take ends on a still frame. A shot whose `clip.json` says `"fit": "freeze"` keeps its still frame.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--text` | string | none | `set` only: the new words. |
| `--json` | switch | off | Print the result as JSON. On `set`, this prints the undo receipt. |
| `--plan` | switch | off | `fit` only: print the edits and change nothing. |
| `--undo` | switch | off | `fit` only: reverse the last fit. |

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

### Examples

### List the clips in the cut

```bash Command
minicut timeline
```

You see every track and clip in the cut, with its start and end.

### Change the words of one caption

```bash Command
minicut timeline set '#cap-c05-l01' --text "I never left." --json
```

### Preview a fit without changing the cut

```bash Command
minicut timeline fit --plan
```

### Output

| Exit code | Meaning |
|---|---|
| `0` | The cut was printed or changed. |
| `2` | A subcommand or flag is wrong, or this folder has no `index.html`. |
| `10` | This computer is not signed in. |

### See also

[minicut captions](#minicut-captions), [minicut render](#minicut-render)

## minicut captions

Redoes every caption in the episode to one standard.

### Usage

```bash Usage
minicut captions [EPISODE_FOLDER] [--top LINE_IDS] [--bottom LINE_IDS] [--json]
```

Replace the following:

- `EPISODE_FOLDER`: the episode folder. Without it, the current folder.
- `LINE_IDS`: one or more spoken line ids, comma separated, for example `c05-l01`.

### Details

Each caption goes bottom centre inside the title safe area, at most 2 lines, split at the natural break and timed to its line's audio. The words stay as they are. Run it again after you change the words with `minicut timeline set`. The Mock and Edit loops check captions with `minicut check captions`.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--top` | line ids | none | Put these lines at the top of the frame, for a shot whose bottom carries text. |
| `--bottom` | line ids | none | Bring these lines back to the bottom. |
| `--json` | switch | off | Print the result as JSON. |

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

### Examples

### Redo every caption in episode 1

```bash Command
minicut captions episodes/ep01
```

### Move one line to the top of the frame

```bash Command
minicut captions episodes/ep01 --top c05-l01
```

You see the captions it changed, then whether every caption now meets the standard.

### Output

| Exit code | Meaning |
|---|---|
| `0` | Every caption meets the standard. |
| `1` | Captions were redone, and some still fail the standard. Each one is named. |
| `2` | The folder has no `index.html`, or Python 3 is missing. |
| `10` | This computer is not signed in. |

### See also

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

## minicut snapshot

Saves still pictures of the episode in this folder, with no render.

### Usage

```bash Usage
minicut snapshot [--frames COUNT | --at SECONDS] [-o FOLDER]
```

Replace the following:

- `COUNT`: how many stills to take across the episode.
- `SECONDS`: the times to take stills at, comma separated, for example `1.5,3`.
- `FOLDER`: the folder for the stills, inside the episode folder.

### Details

A snapshot is the fast way to look at the cut. It needs the browser that `minicut setup` installs.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--frames` | number | none | Take this many stills, spread across the episode. |
| `--at` | seconds | none | Take a still at each of these times. |
| `-o`, `--output` | path | none | The folder to save the stills in. |

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

### Examples

### Take stills at three times

```bash Command
minicut snapshot --at 1,3,5 -o snapshots
```

You see the path of each still it saved.

### See also

[minicut keyframes](#minicut-keyframes), [minicut compare](#minicut-compare)

## minicut keyframes

Saves pictures of how each animation in the episode moves.

### Usage

```bash Usage
minicut keyframes [TARGET] [--selector SELECTOR]
```

Replace the following:

- `TARGET`: a file inside the episode folder to look at. Without it, the episode.
- `SELECTOR`: a CSS selector. Only the elements that match it are shown.

### Details

Use it to check that a title, name tag or effect moves the way you want. It needs the browser that `minicut setup` installs.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--selector` | string | none | Show only the elements that match this CSS selector. |

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

### Examples

### Check every animation in the episode

```bash Command
minicut keyframes
```

### See also

[minicut snapshot](#minicut-snapshot)

## minicut compare

Puts versions side by side in one picture.

### Usage

```bash Usage
minicut compare FOLDER [--out FILE]
```

Replace the following:

- `FOLDER`: a folder inside the episode folder that holds the versions to compare.
- `FILE`: the picture to write, inside the episode folder.

### Details

Use it to choose between versions of a shot or a still. It needs the browser that `minicut setup` installs.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--out` | path | none | The picture to write. |

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

### Examples

### Compare the stills in one folder

```bash Command
minicut compare snapshots --out compare.png
```

### See also

[minicut grade-compare](#minicut-grade-compare), [minicut snapshot](#minicut-snapshot)

## minicut grade-compare

Puts colour looks for one clip side by side in one picture.

### Usage

```bash Usage
minicut grade-compare --for CLIP [--grades LOOKS]
```

Replace the following:

- `CLIP`: the clip to show the looks on.
- `LOOKS`: the colour looks to compare, comma separated.

### Details

Use it to pick the colour look of the episode before the final render. It needs the browser that `minicut setup` installs.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--for` | path | none | The clip to show the looks on. |
| `--grades` | list | none | The colour looks to compare. |

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

### See also

[minicut compare](#minicut-compare)

## minicut catalog

Lists the ready-made titles, name tags, transitions and effects that come with the editor.

### Usage

```bash Usage
minicut catalog [WORDS] [--type {block|component}] [--json]
```

Replace the following:

- `WORDS`: what you want, in English, for example `reveal a headline one line at a time`.

### Details

The search runs on your computer. Search before you build a title or effect by hand, then add the one you pick with `minicut add`. `minicut catalog` works in any folder.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--type` | `block` or `component` | both | Only list one kind of piece. |
| `--json` | switch | off | Print the results as JSON. |

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

### Examples

### Search for a title

```bash Command
minicut catalog "reveal a headline one line at a time" --json
```

You see the matching pieces, best match first, each with its name.

### See also

[minicut add](#minicut-add)

## minicut add

Puts a ready-made piece into the episode in this folder.

### Usage

```bash Usage
minicut add NAME [--force]
```

Replace the following:

- `NAME`: the piece's name, as `minicut catalog` lists it.

### Details

The piece's files go into the episode folder. You then place it in the cut.

### Options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--force` | switch | off | See `minicut add --help`. |

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

### Examples

### Add a film grain effect

```bash Command
minicut add grain-overlay
```

### See also

[minicut catalog](#minicut-catalog)

## 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. |
| `This folder has no index.html.` | Run the command in the episode folder, for example `episodes/ep01`. |
| `no episode timeline at ...` | The episode has no cut yet. Run `minicut new PROJECT --timeline ep01`. |
| `The MiniCut editor is not installed: ...` | Follow the step in the message: run `minicut setup`, or run the install line again. |
| `The browser for pictures is not installed. Run: minicut setup` | Run `minicut setup`. |
| `... is not inside this episode folder.` | Name a path inside the episode folder. |
| `-o takes a .mp4, .webm or .mov path inside this episode folder.` | Give `-o` a video file name inside the episode folder. |
| `--quality is draft, looks or delivery.` | Use one of those three values. |
| `--top takes caption line ids, comma separated, like c05-l01` | Give line ids such as `c05-l01,c06-l02`. |
| `no Python 3 found. Run: minicut setup` | Run `minicut setup`. |

## Next

[Scene and music](/docs/cli/scene-and-music) [Checks and loops](/docs/cli/checks-and-loops) [Global options](/docs/cli/global-options)