diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx index c186b36622..3b65380cc7 100644 --- a/docs/packages/cli.mdx +++ b/docs/packages/cli.mdx @@ -20,17 +20,17 @@ npm install -g hyperframes ## Find your command -| You want to | Use | -| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Start a project | [`init`](#init), [`add`](#add), [`catalog`](#catalog) | -| Bring in source material | [`capture`](#capture), [`transcribe`](#transcribe), [`tts`](#tts), [`remove-background`](#remove-background), [`media-treatment`](#media-treatment), [`beats`](#beats), [`normalize-audio`](#normalize-audio) | -| Look at it, or share it | [`preview`](#preview), [`present`](#present-and-play), [`play`](#present-and-play), [`publish`](#publish), [`open`](#open-and-catch-up), [`catch-up`](#open-and-catch-up) | -| Find problems | [`lint`](#lint), [`check`](#check), [`snapshot`](#snapshot), [`keyframes`](#keyframes), [`compare`](#compare-and-grade-compare), [`grade-compare`](#compare-and-grade-compare) | -| Edit from the terminal | [`timeline`](#timeline), [`history`](#history) | -| Make a file | [`render`](#render), [`benchmark`](#benchmark) | -| Render somewhere else | [`cloud`](#hyperframes-cloud), [`lambda`](#hyperframes-lambda), [`cloudrun`](#hyperframes-cloudrun) | -| Fix your setup | [`doctor`](#doctor), [`browser`](#browser), [`upgrade`](#upgrade), [`docs`](#docs), [`info`](#info-and-compositions), [`compositions`](#info-and-compositions) | -| Connect other tools | [`auth`](#hyperframes-auth), [`skills`](#skills), [`figma`](#figma-and-events), [`telemetry`](#telemetry), [`feedback`](#feedback) | +| You want to | Use | +| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Start a project | [`init`](#init), [`add`](#add), [`catalog`](#catalog) | +| Bring in source material | [`capture`](#capture), [`transcribe`](#transcribe), [`tts`](#tts), [`remove-background`](#remove-background), [`media-treatment`](#media-treatment), [`beats`](#beats), [`audio`](#audio), [`normalize-audio`](#normalize-audio) | +| Look at it, or share it | [`preview`](#preview), [`present`](#present-and-play), [`play`](#present-and-play), [`publish`](#publish), [`open`](#open-and-catch-up), [`catch-up`](#open-and-catch-up) | +| Find problems | [`lint`](#lint), [`check`](#check), [`snapshot`](#snapshot), [`keyframes`](#keyframes), [`compare`](#compare-and-grade-compare), [`grade-compare`](#compare-and-grade-compare) | +| Edit from the terminal | [`timeline`](#timeline), [`history`](#history) | +| Make a file | [`render`](#render), [`benchmark`](#benchmark) | +| Render somewhere else | [`cloud`](#hyperframes-cloud), [`lambda`](#hyperframes-lambda), [`cloudrun`](#hyperframes-cloudrun) | +| Fix your setup | [`doctor`](#doctor), [`browser`](#browser), [`upgrade`](#upgrade), [`docs`](#docs), [`info`](#info-and-compositions), [`compositions`](#info-and-compositions) | +| Connect other tools | [`auth`](#hyperframes-auth), [`skills`](#skills), [`figma`](#figma-and-events), [`telemetry`](#telemetry), [`feedback`](#feedback) | `validate`, `inspect`, and `layout` still work but are [deprecated](#deprecated-validate-inspect-and-layout). Use `check` instead. @@ -504,6 +504,49 @@ Needs a local Chrome, the same one `render` uses. Run within a frame or two — a different headless-Chrome audio sample rate can shift a beat slightly. +### `audio` + +Measure how sound moves in time, so a cut or an animation can land on it. + +```bash +npx hyperframes audio sfx/whoosh.mp3 # one file, in file seconds +npx hyperframes audio sfx/hit.wav --place-at 4.2 # not in the film yet: where it lands if it starts at 4.2 s +npx hyperframes audio --element '#riser' # one clip of the film, in film seconds +npx hyperframes audio --at 12 # every sound playing at 12 s +npx hyperframes audio --range 10,14 --only onsets # every hit between 10 and 14 s +``` + +Each sound reports: + +- **moments**: where it starts (RMS first reaches 20% of its peak), where it + rises fastest, its loudest point, and where its tail fades 40 dB under the peak. + A short impact accents on its peak; a slow whoosh accents on its steepest rise. +- **onsets**: every hit, with a strength relative to the strongest. +- **loudness**: integrated and short-term-max LUFS (ITU-R BS.1770, matching + FFmpeg's `ebur128` to 0.1 LU), sample and true peak, clipping. +- **silence**: quiet spans under `--silence-db` (−50 dBFS). +- **kind**: a first guess of `sfx`, `voice` or `music`, with the features behind it. +- **envelope**: the level over time, about 2,000 values per sound. + +A film query (`--element`, `--at`, `--range`) reads the project in +the current directory or `--dir`, finds the `