@vosjs/cli 0.84.0 → 0.85.0

package/README.md

@@ -135,6 +135,15 @@ Every join writes `join.json` beside the document: each input's path (relative t
 ```bash
 vos score film --track fresh-focus --at m1:share --dry-run   # a catalog slug, a step on media m1: print the plan and the envelope
 vos score film --track ./theme.wav --at 12 --gain 0.4        # a local file (copied into film/music/), output seconds
+vos score film --track best                                  # the bed vos music pick ranks first, placed on the film's payoff
+```
+
+**Choosing the bed.** An agent cannot listen, so the library says what each track is (`GET /api/music`, manifest version 2: tempo and the beat grid with a confidence, the quiet intro, the loop seam, how it ends, its sections, how busy it is; and, written by a person who listened, vocals, tags from a closed vocabulary, one sentence, loops). `vos music ls` prints it one line per track, filtered by `--mood`, `--vocals none|chops|lead`, `--loops`, `--bpm 90-120`, `--min-length <s>` and `--q <words>`. `vos music pick <take|config.json>` ranks every track against THIS film: its length, its cuts (captions landed on steps, joins, page changes, steps marked `"zoom": true`), its payoff (`--at`, else the last marked step, else the last cut) and whether a voice plays are read from the document; the hard rules go first (the track covers the film or loops, its placement does not start inside a quiet intro, no sung lead under a voice), then the scores (a swell landing on the payoff, cuts on the beat (never scored on an uncertain beat), the asked `--mood` or `--words`, a calm bed under a voice, an ending that meets the film's). The top three come back with their reasons and the exact `vos score` line that places each; `--json` carries every track, the refused ones with their reason; `--like <vos id|slug>` nudges the bed a project already uses. Ties fall to the take's own name, so two films asking the same thing get different beds and one film always gets the same answer. `LAUNCH.md`'s `music: <mood or words>` goes through the same ranking in `vos plan` (a slug stays that track), and the plan's report names the pick and the runner-up. When no bed fits, `pick` says so and a composed score (the `vos-score` skill) is the way.
+
+```bash
+vos music ls --mood chill --vocals none --loops            # what the library has for a calm loop
+vos music pick film --at share --words "warm piano"        # three beds for this film, the payoff on the share step
+vos music pick program/config.json --json                  # a program: its scene labels are the cuts
 ```
 
 The track is decoded (mediabunny in Node for PCM; a compressed track in the headless browser) and measured as a short-term loudness curve, a 1 s window every 0.5 s: K-weighted LUFS (BS.1770) for mono and stereo audio, RMS dBFS otherwise, and the output says which. Its strongest swell is the largest sustained rise to a peak (at least 3 dB, holding within 3 dB of the peak for 1.5 s), measured once the track has established its level: a rise starts no earlier than 5 s after the track first comes within 12 dB of its median level, and from no lower than that, so a fade in from silence at the top is the track starting, never its swell; it lands where it ARRIVES, within 1 dB of the peak. `--at` is where it should land: a step (its id, `step:<index>` by its index, `<media>:<step>` for another media's), resolved through the cut exactly as an anchored caption is, or output seconds. The clip's `in` is set so the swell plays there, `start` is 0, `out` is `in` plus the film's length, with `--gain` (0.5), `--fade-out` (1.5 s) and, whenever the track is entered mid-song (`in` > 0), a 0.8 s fade-in (`--fade-in` sets it, 0 for none); when the track cannot both hold the swell there and cover the film, the clamp is said in words. Without `--at` the track starts at its first moment above its median level. A second run replaces the clip; `--dry-run` writes nothing and prints the swell, the offset and the curve as one line of blocks (`--json` carries every point). The clip carries what the track measures (`loudness`, below) and a loudness target, `normalize: -16` (`--normalize <lufs>` sets another, `--normalize off` none), with `--gain` a trim on the target: a catalog track, mastered at about -16 LUFS, plays at the default 0.5 as it did before it had a target, and a file of your own lands at the same level.