|
| 1 | +# Beat sync |
| 2 | + |
| 3 | +Cut and animate to a track by measuring it, not by trusting the tempo you asked for. A generated track keeps a stated BPM but puts its drops and sections where it likes, and a tempo found by ear or by a general-purpose library is often half a beat off the kick. A cut that lands a quarter-beat late reads as a mistake. |
| 4 | + |
| 5 | +## 1. Get the track before you compose |
| 6 | + |
| 7 | +Analysis needs a file. A `prompt` on the timeline's `audio` asset only generates at render time, so there is nothing to measure while you write the edit. |
| 8 | + |
| 9 | +- **The user's track:** use its hosted URL. |
| 10 | +- **A library track:** use its URL as is. |
| 11 | +- **A generated track:** generate it on its own first, then use the URL it returns as a plain `audio` `src`. Still state the BPM in the prompt; measure the result anyway. |
| 12 | + |
| 13 | +<!-- surface:cli --> |
| 14 | +Host a local file with `shotstack ingest upload <file> --watch`. Generate a track with `shotstack generate <music-model> "<prompt>" --length <seconds> --watch`, after quoting it with `--quote`. |
| 15 | +<!-- /surface --> |
| 16 | + |
| 17 | +## 2. Analyse it |
| 18 | + |
| 19 | +Analysis is free, takes 15–30 s and reads the first 10 minutes of the track. |
| 20 | + |
| 21 | +<!-- surface:cli,api --> |
| 22 | +It needs no API key. The `src` must be a direct, public link to an audio or video file: share pages and redirects are refused. |
| 23 | +<!-- /surface --> |
| 24 | +<!-- surface:cli --> |
| 25 | +```sh |
| 26 | +shotstack analyze https://shotstack-assets.s3.amazonaws.com/music/unminus/lit.mp3 --output json > map.json |
| 27 | +``` |
| 28 | +<!-- /surface --> |
| 29 | + |
| 30 | +## 3. Read the map |
| 31 | + |
| 32 | +| Field | Meaning | |
| 33 | +|---|---| |
| 34 | +| `steady` | `true`: the tempo holds, and `bpm`, `beat`, `bar`, `meter` and `origin` describe a grid. `false`: use `beats[]` and `downbeats[]` instead. | |
| 35 | +| `bpm`, `beat`, `bar` | Tempo, and the beat and bar lengths in seconds. | |
| 36 | +| `meter` | Beats per bar. | |
| 37 | +| `origin` | Time of the first downbeat. Bar `n` starts at `origin + n × bar`. | |
| 38 | +| `bars.count`, `bars.energy[]` | Number of bars, and loudness per bar from 0 to 1. | |
| 39 | +| `drops[]` | `{ bar, time }` where the low end comes in hard. | |
| 40 | +| `sections[]` | `{ bar, time, change }`, where `change` is `rise` or `fall`. | |
| 41 | +| `downbeat.confidence` | How sure the bar phase is, 0 to 1. | |
| 42 | +| `precision` | How far to trust each part: `grid` is `frame` or `beat`, `sections` is `bar`, `downbeat` is `estimate`. | |
| 43 | +| `beats[]`, `downbeats[]` | Beat and bar times, only when `steady` is `false`. | |
| 44 | + |
| 45 | +## 4. Write every cue in bars |
| 46 | + |
| 47 | +- **Cuts on bar lines.** A shot holds a whole number of bars. Compute each `start` and `length` from the map and keep three decimals; never round to whole seconds. |
| 48 | +- **Let energy set the pace.** Hold two or four bars where `bars.energy` is low and cut every bar where it is high. |
| 49 | +- **Spend the big moment on a drop.** Put the reveal, the logo or the hardest cut at a `drops[].time`. |
| 50 | +- **Change scene at sections.** A `rise` opens a new idea; a `fall` is where to breathe. |
| 51 | +- **Accents on beats.** A pulse, flash or kick-on-the-beat sits at `origin + k × beat`. |
| 52 | +- **No grid?** When `steady` is `false`, cut on `downbeats[]` and accent on `beats[]`. |
| 53 | +- **Downbeat off by one?** The bar phase is an estimate. If `downbeat.confidence` is low, look at the first drop: if it lands mid-bar, shift `origin` by a beat. |
| 54 | + |
| 55 | +## 5. Drive `html5` motion from the map |
| 56 | + |
| 57 | +An `html5` clip's time is local to the clip. Put the map's numbers and the clip's own `start` in the page and place every tween from them, on a timeline the harness seeks (not `paused`): |
| 58 | + |
| 59 | +```js |
| 60 | +const ORIGIN = 0.062, BAR = 1.9998, BEAT = BAR / 4, CLIP_START = 8.062; // from the map and this clip |
| 61 | +const at = (bar, beat = 0) => ORIGIN + bar * BAR + beat * BEAT - CLIP_START; |
| 62 | +const tl = gsap.timeline(); |
| 63 | +tl.from(".title", { yPercent: 110, duration: BEAT, ease: "power3.out" }, at(4)) |
| 64 | + .to(".title", { scale: 1.06, duration: BEAT / 2, yoyo: true, repeat: 1 }, at(5)) |
| 65 | + .to(".title", { opacity: 0, duration: BEAT }, at(7, 3)); |
| 66 | +``` |
| 67 | + |
| 68 | +Built-in motion works the same way: a clip whose `start` is a bar line makes its `transition` land on the beat. |
| 69 | + |
| 70 | +## 6. Keep the music a plain audio clip |
| 71 | + |
| 72 | +Put the track on its own track as an `audio` asset at `start: 0` with `length: "end"`; a fade (`effect: "fadeOut"`) is fine. Anything that moves the audio moves the grid with it. If you trim the track or start it later, add that offset to every time: timeline time = map time − `trim` + the audio clip's `start`. |
| 73 | + |
| 74 | +## 7. Check frames at bar lines |
| 75 | + |
| 76 | +Before calling it done, look at a few cuts and the first drop at their bar times: the new shot should be on screen at the bar line, not a frame or two after it. |
| 77 | + |
| 78 | +<!-- surface:cli --> |
| 79 | +Preview with `shotstack studio`, or render on stage and pull a frame at a bar time with `ffmpeg -ss <time> -i out.mp4 -frames:v 1 bar.png`. |
| 80 | +<!-- /surface --> |
0 commit comments