39 lines
2.7 KiB
Markdown
Raw Permalink Normal View History

# waveform
Render the audio track of a video or audio file as a waveform PNG (local render, no credits) with a timestamp ruler: loudness over time, with silent stretches highlighted in red. A fast, token-efficient audio track preview; the silent spans are also returned as second ranges.
| | |
| --- | --- |
| MCP tool | `waveform` |
| CLI | `diffusion waveform <path> [options]` |
| CLI aliases | `diffusion wave` |
## Input
| Field | Type | CLI | Description |
| --- | --- | --- | --- |
| `path` | `string`, required | `<path>` | absolute file path or URL (works with or without an open project), or a library path like `b-roll/clip.mp4` (needs an open project) |
| `start` | `Time` | `-s, --start <time>` | start of the window — seconds ("1.5"), frames ("45f"), or "MM:SS" (default: 0) |
| `end` | `Time` | `-e, --end <time>` | end of the window — seconds ("1.5"), frames ("45f"), or "MM:SS" (default: asset duration) |
| `output` | `string` | `-o, --output <path>` | absolute path to write the PNG to (default: a fresh file under the system temp dir) |
| `scale` | `number` | `-x, --scale <factor>` | scale factor for the thumbnails; smaller fits more rows and columns, larger fits fewer (default: 1) |
Loudness over time is drawn from decoded audio peaks. An `end` past the asset's duration is clamped to it; a `start` at or past the end is an error, since the window would be empty. Tick labels use `HH:MM:SS:FF` timecode (hours, minutes, seconds, frame within the second) at every zoom level, so labels stay comparable regardless of the window's span. For a video, frames count against the video's frame rate; for a standalone audio asset, the ruler counts against a nominal 30 fps.
The overall canvas size stays fixed, so a smaller `scale` (clamped to `0.25`–`4`) fits **more rows and columns** — a denser time axis — and a larger one fits fewer but taller rows. Without `output` the PNG lands in a fresh file under the system temp directory; an `output` naming an existing directory gets that fresh file inside it.
## Output
One JSON object: the absolute path to the written PNG plus the silent stretches (the red spans on the waveform) as `[start, end]` second ranges, in absolute seconds (offset by `start` when a window is used). Over MCP the image also arrives inline when it is under a megabyte.
```ts
{
path: string, // e.g. "/tmp/dapi-waveform-3f2c1a8e-….png", or the `output` path
silences: Array<{ start: number, end: number }>,
}
```
## Errors
Fails when the path can't be resolved, the asset has no decodable audio track, the window is empty (`start` at or past the asset's end) or crosses (`start` >= `end`), `scale` isn't a positive number, or the PNG can't be written.