# Output time and source time

CutZal never changes the original recording. It keeps a list of the parts to keep, and the edited video plays those parts back to back.

- **Source time** is a moment in the original recording (the master recording when the project has several sources). It does not change when you cut.
- **Output time** is a moment in the edited video. Cutting earlier speech moves later output times earlier.

All times are seconds with up to 3 decimals.

## Where each time is used

| Place                               | Time                                                                  |
| ----------------------------------- | --------------------------------------------------------------------- |
| `transcript` words                  | both: `source` and `output` (`output` is `null` when the word is cut) |
| `transcript --from/--to`            | output by default, source with `--coordinate source`                  |
| range edit `cut`                    | either, set by `coordinate`                                           |
| range edit `restore`                | source only (cut parts have no output time)                           |
| speed edit `ranges`                 | either, set by `coordinate`                                           |
| layout edit `ranges`                | either, set by `coordinate`                                           |
| clip `anchor` with `kind: "output"` | output                                                                |
| `capture --at`                      | output                                                                |
| `insert --at`                       | output                                                                |
| `context.durationS`                 | output (length of the edited video)                                   |
| `context.masterDurationS`           | source (length of the recording)                                      |

## Converting

`context.output.segments` lists the kept parts in output order: `{ masterStartS, masterEndS, outputStartS }`. A part played faster or slower (a `speed` edit) also has `rate`, and `mute: true` when its sound is off. `rate` is 1 when it is missing. A segment covers output time `outputStartS` to `outputStartS + (masterEndS - masterStartS) / rate`.

- Output to source: find the segment that contains output time `t`, then `source = masterStartS + (t - outputStartS) * rate`.
- Source to output: find the segment whose `masterStartS <= s < masterEndS`, then `output = outputStartS + (s - masterStartS) / rate`. If no segment contains `s`, that moment is cut.

Usually you do not need to convert: `transcript` already gives both times for every word.

## Choosing the coordinate

- To cut what the viewer currently sees and hears, use output time from the current `transcript`. Read it again after each apply, because output times move.
- To refer to the recording itself (for example "the second take of the intro"), or to restore something that was cut, use source time. Source times stay valid across edits.
- Clips pinned with output anchors stay at their output time when speech is cut or restored. Check with `capture` after large cuts.

## Frame fields

Layout edits (`placement` with `camera` or `screen`) and the `frame` of screen and camera clips use these fields. Positions and sizes are fractions of the output picture, so they do not depend on its resolution.

- `pos`: a 9-grid name (`tl`, `tc`, `tr`, `ml`, `mc`, `mr`, `bl`, `bc`, `br` for top, middle, bottom and left, center, right; with a small margin from the edge) or `{ "x", "y" }` from 0 to 1 for the frame's top left corner.
- `sizePct`: width as a fraction of the output width, above 0 and at most 2. The camera default is 0.24.
- `radiusPx`: corner rounding in pixels, 0 to 4096.
- `padPx`: space inside the frame around the picture in pixels, 0 to 4096.
- `aspect`: `1:1`, `4:3`, `3:4`, `16:9`, or `media` (the recording's own shape).
- `mirror`: `true` flips left and right.
- `focus` (optional): `{ "x", "y" }` from 0 to 1, the point of the recording to keep at the center of the frame when the frame crops it (for example a `3:4` camera frame over a 16:9 recording shows only the middle 42% of its width). It is measured on the recording itself, top left, before `mirror`, so turning `mirror` on or off keeps the same part in view. Without it the frame shows the middle (`0.5, 0.5`); sending `{ "x": 0.5, "y": 0.5 }` removes it. Values that would show past the edge of the recording stop at the edge, and an axis the frame does not crop (the height in that `3:4` example) ignores its value. To center a face that sits left of the middle, give the face's position, such as `{ "x": 0.42, "y": 0.5 }`; check with `capture`. A project with a `focus` is saved as file version 20, so older CutZal versions refuse to open it instead of showing the middle.