The events to reshape.
The groove template, from extractGrooveTemplate.
The time signature, used to compute the bar length.
Reshaped copies of events, in input order.
If template.ts is set and does not match ts, if slotsPerBar is
not the number of slots a bar of ts holds at the template's subdivision,
or if a slot carries a non-finite offset or a velocity outside [0, 127].
import { extractGrooveTemplate, applyGrooveTemplate, parseTimeSignature } from '@libraz/libcantus';
const ts = parseTimeSignature('4/4');
// Learn the feel from a loosely played performance...
const groovy = [
{ pitch: 36, startBeat: 0.02, durationBeat: 1, velocity: 100 },
{ pitch: 38, startBeat: 1.06, durationBeat: 1, velocity: 70 },
];
const template = extractGrooveTemplate(groovy, ts, 4);
// ...then impose it on stiff, quantized events.
const quantized = [{ pitch: 36, startBeat: 0, durationBeat: 1, velocity: 80 }];
applyGrooveTemplate(quantized, template, ts); // events nudged toward the captured feel
Apply a groove template to a set of (typically quantized) note events: each event is snapped to its grid slot and then offset by that slot's recorded timing deviation, pushing stiff timing toward the template's feel. Velocity is set to the slot's recorded average when it recorded one (a non-
nullvelocity, including a genuine 0); otherwise the event's own velocity is left untouched. Non-positive-duration input artefacts are omitted, so output positions do not retain a one-to-one correspondence with the input array.If the template carries a time signature (see GrooveTemplate.ts) it must match
ts, since a differing bar length would misalign the per-bar grid and drift the feel; a mismatch throws rather than corrupting timing silently.slotsPerBaris held to the same standard, since it is what the grid is read through: a template built by hand whose count does not match the bar would send a note past the end of the grid and land it on the next bar's downbeat. What the slots carry is checked too, so nothing this returns is a note event the rest of the library would refuse.