Tempo map from hit points
doseedo_tempo_mapScoring to picture: turn HIT POINTS (a cut, an impact, the title card — as seconds from the cue start or SMPTE timecodes) into a TEMPO MAP that lands each hit exactly on a downbeat (or a beat / an eighth — per hit with hits[].land), staying near your tempo and inside bpm_range. A cue whose pace changes (she runs faster, then stops): give the hit where it changes a bpm, and the map moves to that tempo from there, every hit still landed. An AD or any cue that must hold ONE tempo: fixed_bpm: true (+ max_deviation_bpm, tolerance_ms) finds the tempo and the bar-1 offset (music_offset_s) landing the most hits, and says which ones it could not. Returns tempo_map [{beat, bpm}] to pass unchanged to doseedo_render_midi / doseedo_render_score / doseedo_session_from_stems, and hits[] with the beat, bar and beat-in-bar each hit lands on — write the accent, stinger or change there. Handles 23.976 / 24 / 25 / 29.97 (";" = drop-frame) / 30 / 50 / 59.94 / 60 fps timecode. Pure math: free, instant, no key needed.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| bpm | Yes | The cue's tempo (20–300) — the map stays as close to it as the hits allow. | |
| fps | No | Frame rate of the timecodes: 23.976, 24, 25, 29.97, 30, 50, 59.94, 60. | |
| hits | Yes | The moments the music must land on: [{time_s} (seconds from the cue start) or {timecode: "01:00:12:08"} (film timecode, with fps and start_timecode), label?, land?, bpm?}] — land = THIS hit's landing ("downbeat", "beat" or "eighth"; default: the request's land), e.g. the big cuts on bar lines and a quick accent on an eighth. bpm = the tempo FROM this hit on, a new section (the chase at 160 from the cut where she starts running, back to 112 when she stops), until a later hit names another; the range around it scales with it. A bare number = {time_s}. | |
| land | No | Land hits on bar lines (default), on any beat, or on any eighth — the default for every hit without its own land. | |
| start_s | No | Alternative: the cue start in seconds of film time (informational when hits are time_s). | |
| bpm_range | No | Allowed tempo range [min, max] (default ±12 % of bpm). | |
| fixed_bpm | No | ONE tempo for the whole cue (an ad, a song-form cue): the solver picks the tempo (within max_deviation_bpm of bpm; default exactly bpm) and where bar 1 sits (music_offset_s, default within the first bar; offset_range_s) so the most hits land within tolerance_ms (default 40). Hits it cannot land come back landed:false with nearest_beat — never an error. | |
| tolerance_ms | No | SOFT hits (0–250 ms): a hit within this of the grid counts as landed, and one the grid can't reach is reported (landed:false), never refused. Every hit then carries error_ms; hit_rate = landed / all. | |
| offset_range_s | No | fixed_bpm: where bar 1 may sit on the cue, [min, max] seconds (default [0, one bar]). | |
| start_timecode | No | Film timecode of the cue's first downbeat (bar 1); hit timecodes are measured from it. | |
| time_signature | No | Meter (default 4/4). | |
| max_deviation_bpm | No | How far the tempo may move from bpm (both modes; in place of bpm_range). A variable map at 124 ±12 % can swing 11+ bpm between hits — 3 keeps it a steady groove. |