muvid.footage.beat_fit

Fitting a cut’s timing to the beat — the pure numerics behind service.fit_to_beat.

A cut shows its clip through an affine map of song time (edl.clip_time_at): clip_in + rate * (t - song_start) with clip_in = song_start - offset + slip. So a movement accent recorded at clip time tau lands at song time song_start + (tau - clip_in) / rate. Fitting a cut means choosing (slip, rate) so the clip’s accents (beats.MOTION_STOPS) land on the song’s beat grid.

The score of a candidate is the accents’ weighted mean alignment with the grid, sum(w * cos(2 pi (t - phase) / period)) / sum(w): +1 when every accent is on a beat, -1 when every one is half a beat off, 0 when they ignore the beat. Weights are the accent strengths above their median, so the steady floor of a moving crowd does not vote.

The confidence of the best fit is a z-score against a null that keeps what the signal is made of and destroys only its relation to the beat: the samples are cut into blocks of about two beats and each block is rotated by its own random amount, and the SAME search is run on every such null signal. The search’s own freedom (it will always find some slip that looks good) is therefore in the null too. A whole-signal rotation would not do: it only turns every phase by the same angle, which the slip search undoes.

The window is wider than a short cut: a 1.5 s cut holds three beats, too few to judge by. The fit is judged over at least window_s of the clip around the cut, read through the same map — the same dancer, a few seconds either side.

Pure numpy; nothing here reads a file.

Module Attributes

FIT_WINDOW_S	Seconds of clip the fit is judged over, at least (centred on the cut).
FIT_MIN_BEATS	A cut shorter than this many beats is not fitted.

Functions

fit_cut(tau, values, *, song_start, ...[, ...])

The best timing for a cut over song time [song_start, song_end] of a clip at offset, from the clip's accent signal values sampled at clip times tau.

Classes

BeatGrid(period, phase)	A steady beat: beat k falls at phase + k * period seconds of the song.
Fit(slip_s, rate, score, current_score, z, ...)	The best (slip, rate) for one cut, its score, the current setting's score, and the z of the best score against the null.

class muvid.footage.beat_fit.BeatGrid(period, phase)

Bases: object

A steady beat: beat k falls at phase + k * period seconds of the song.

classmethod fitted(beats, *, min_beats=8)

The least-squares grid through tracked beat instants (each beat numbered by beats._beat_numbers, so a skipped or spurious beat does not bend it), or None when the beats are too few or not steady (beats.fitted_tempo).

Return type:

Optional[BeatGrid]

muvid.footage.beat_fit.FIT_MIN_BEATS = 3.0

A cut shorter than this many beats is not fitted.

muvid.footage.beat_fit.FIT_WINDOW_S = 8.0

Seconds of clip the fit is judged over, at least (centred on the cut).

class muvid.footage.beat_fit.Fit(slip_s, rate, score, current_score, z, n_accents)

Bases: object

The best (slip, rate) for one cut, its score, the current setting’s score, and the z of the best score against the null.

muvid.footage.beat_fit.fit_cut(tau, values, *, song_start, song_end, offset, current_slip=0.0, current_rate=1.0, grid, feasible=None, window_s=8.0, slips=None, rates=None, null_draws=200, seed=0)

The best timing for a cut over song time [song_start, song_end] of a clip at offset, from the clip’s accent signal values sampled at clip times tau.

feasible(slip, rate) -> bool rules out settings the clip cannot hold. None when no accent lands in the window under any setting.

Return type:

Optional[Fit]