# clip-edits

> The pure parts of editing one sound on a track of an arrangement: taking time out and the crossfade at its seam, the fades and level of a stretch of time, how far a pause is shrunk, and which keys are a field's own.

```bash
npx shadcn@latest add @audio-ui/clip-edits
```

```ts
import { SPLICE, EDGE_EPS, SHRINK_GAP, SHRINK_GAPS, LEVEL_NUDGE, /* … */ } from "@/lib/clip-edits";
```

- Files: `lib/clip-edits.ts`
- Depends on: `arrangement`, `use-arrangement`; npm: nothing
- Used by: `block-audio-editor`, `use-clip-edits`

| Export | Kind | What it is |
| --- | --- | --- |
| `SPLICE` | const | The crossfade of an edit's seam: half of it each side of the cut, in seconds. |
| `EDGE_EPS` | const | How near an edge a pause has to start or end to be the silence at the start or the end of the sound, in seconds. |
| `SHRINK_GAP` | const | The length a shrunk pause keeps, in seconds, as audio.js's `shrink` does by default. |
| `SHRINK_GAPS` | const | The lengths a pause can be shrunk to: 0 takes it out whole. |
| `LEVEL_NUDGE` | const | How far Louder and Quieter move the selection's level, in dB. |
| `MIN_DB` | const | A selection's level range, in dB: silence at the bottom, a boost of 6 dB at the top. |
| `MAX_DB` | const |  |
| `typing` | function | Whether a key went to a field you type in, where its keys are its own. |
| `removing` | const | Taking the time from `from` to `to` out, the time after it moving in: nothing when it is empty. |
| `splice` | const | The crossfade of an edit's seam at `at`, in a sound `length` long: the clip that ends there and the one that starts there play through each other. |
| `StretchShape` | interface | What fades and level on a selection set: the fades at its two ends, their curves, and its level in dB. |
| `FLAT` | const |  |
| `clipEnd` | const |  |
| `near` | const | Two times the same, to the frame. |
| `shapeOf` | function | What the selection has now: the shape of the one clip it covers exactly, or none. |
| `pieceOf` | function | A clip's piece from `from` to `to` on the timeline, the source following, with no fades of its own. |
| `shapeStretch` | function | The track's clips with the stretch from `from` to `to` cut out of them as clips of their own, the shape on those: the fade-in on the first, the fade-out on the last, the level on all. |

## Usage

The functions [`useClipEdits`](/docs/hooks/use-clip-edits) is made of, with no React in them, so a command list can be built and tested on its own.

```ts
import { removing, shapeStretch, splice, SPLICE } from "@/lib/clip-edits";

// Take 2 s to 3.5 s out, then crossfade the seam it leaves.
const commands = [...removing(2, 3.5), ...splice("track-1", 2, length - 1.5)];

// The clips of a track with a fade and a level put on a stretch of them.
const shaped = shapeStretch(clips, [2, 4], { fadeIn: 0.1, fadeInShape: "linear", fadeOut: 0.2, fadeOutShape: "cos", gain: -3 });
```

`removing(from, to)` is the command that takes a stretch of time out and closes the gap; `splice(track, at, length)` the short crossfade at a seam, none at either end of the sound. `shapeOf(clips, range)` reads the fades and level a selection has now. `typing(target)` tells whether a key went to a field, where the keys are its own.