Music

An agent can't hear a song, so rapid hears it first and writes down what matters. Bring a track and the video is planned to its beats, built to them, checked against them, and mixed over it. You must own the track or have the rights to use it.

rapid video --brief "Twenty seconds, vertical, cut to this." --music ~/Music/track.mp3

In Claude Code, name the track in the brief conversation, or pass music to new_video. A track outside the project is copied into assets/.

The listener needs uv, and sets itself up on first use.

#What the job does

1. Hears it. A listen node runs rapid listen before the storyboard. A track is heard once per machine: the result is kept by the file's hash, in $RAPID_HOME/listen/heard/, so the same song in another project answers at once.
2. Plans to it. The storyboarder reads the map and names the track in the storyboard's music, with from, where in it the video starts. Each scene's length is a whole number of beats.
3. Checks the plan. Code holds the start and every cut to a beat, within 0.07 s, and sends a plan that misses back, with or without a director.
4. Builds to it. A builder runs rapid beats <scene> for the music under its scene, in the scene's own seconds, and lands its moments there.
5. Checks the landings. rapid check --music marks a moment that misses, and the scene goes round again.
6. Mixes the bed. The track goes under the video, beneath the style's cue sounds.

#The map

rapid listen <track> writes <track>.music.json beside the track, and a picture of it, <track>.music.png, unless you pass --no-picture. Every time is in the track's own seconds.

A moment is a drop or a build:

• drop: a section start where the energy jumps. t is when, rise how much, 0 to 1.
• build: the bars before a section over which the energy climbs into it, from from to t.

Both name the section they open or lead into by index, and a bigger rise is a bigger moment.

rapid beats [scene] prints the same music for a video's scenes, each in its own seconds, laid out the way the join lays them, overlaps included. It reads each scene's built length where it has one.

#Cutting to it

• music.from sits on a downbeat, chosen so the video's length holds the part of the song worth having: a bar or two before a drop, or the top of a chorus.
• Cuts land on beats. Each scene's dur is a whole number of beats, most of them whole bars.
• Moves land on moments. The rationed big moves go on drops, a held breath in a section whose energy falls, and cuts shorten into a build.
• An overlap counts. The plan check measures each cut where the next scene starts, the first frame of a transition's overlap.

#In a scene

Land entrances, hits, and settles on beats, and the hero on a downbeat. A declared cue carries the moment, and data-cue-duck dips the track under it, for a word or a hit that has to read over the song:

<i hidden data-cue="land" data-cue-at="1.92" data-cue-key="hero" data-cue-duck></i>

From a frame callback: rapid.cue('land', { key: 'hero', duck: true }).

#The beat check

With a track, rapid check --music runs the beat check on each render. It holds every cue of a landing kind (land, hit, enter, drop, pop, kick) and every ducked cue to the nearest beat:

#The bed

The job's mix takes the track from music.from, brings it to −18 LUFS, and fades it out over the video's last 1.5 s. A video that outlasts the track loops it from the first downbeat at or after its start, crossfading the seam so the bar holds. Each ducked cue dips the bed to 40% with a soft attack and release.

By hand, rapid mix takes the same choices as --music, --music-from, --music-lufs, --music-tail, and --map, plus --music-at for where the bed enters. See rapid mix.