"""What a deck needs to know about its song: peaks to draw, its tempo to a tenth of a BPM, where the beats fall, and how to sync to the other deck. Tempo comes from ``bpm_detect`` (spectral flux + autocorrelation), but at its full 0.1 BPM resolution rather than the whole number the library stores: an integer can be 0.5 BPM out, which drifts a quarter beat in 30 seconds. The file's own BPM, when there is one, only settles which octave the answer is in (the detector can land on half or double). """ import numpy as np from lintunes import bpm_detect PEAKS_PER_SECOND = 200 def peaks(samples: np.ndarray, rate: int, per_second: int = PEAKS_PER_SECOND) -> np.ndarray: """Loudest absolute sample (0..1) in each 1/per_second of a song. ``samples`` is (frames, channels) int16 or float.""" if len(samples) == 0: return np.zeros(0, np.float32) data = np.abs(samples.astype(np.float32)).max(axis=1) if samples.dtype == np.int16: data /= 32768.0 step = max(1, rate // per_second) count = len(data) // step if count == 0: return np.array([data.max()], np.float32) return data[:count * step].reshape(count, step).max(axis=1) def mono_11k(samples: np.ndarray, rate: int = 44100) -> np.ndarray: """A mono float32 copy at ~11025 Hz (every 4th frame of a 4-frame average), the rate bpm_detect works at.""" data = samples.astype(np.float32).mean(axis=1) if samples.dtype == np.int16: data /= 32768.0 factor = max(1, round(rate / bpm_detect.SAMPLE_RATE)) count = len(data) // factor return data[:count * factor].reshape(count, factor).mean(axis=1) def precise_bpm(mono: np.ndarray, file_bpm: int | None = None) -> float | None: """The tempo to 0.1 BPM, folded into the octave the file's BPM names (when it has one) or into 70–180.""" bpm = bpm_detect.estimate_bpm(mono[:bpm_detect.SAMPLE_RATE * bpm_detect.MAX_SECONDS]) if bpm is None: return float(file_bpm) if file_bpm else None target = float(file_bpm) if file_bpm else None if target: candidates = [bpm / 4, bpm / 2, bpm, bpm * 2, bpm * 4] bpm = min(candidates, key=lambda b: abs(np.log2(b / target))) else: while bpm < 70: bpm *= 2 while bpm > 180: bpm /= 2 return round(bpm, 1) def onset_times(mono: np.ndarray, sr: int = bpm_detect.SAMPLE_RATE, window: int = 128, hop: int = 32) -> tuple[np.ndarray, np.ndarray]: """(strength, seconds): how sharply the log energy rises, every ~3 ms. bpm_detect's spectral flux is right for *tempo* but its 1024-sample window smears *when* a beat lands by tens of ms; this short energy window places it within a few. A rise between two windows is timed at the later window's middle, where an onset entering it peaks.""" data = np.asarray(mono, dtype=np.float64) if len(data) <= window + hop: return np.zeros(0), np.zeros(0) total = np.concatenate([[0.0], np.cumsum(data * data)]) starts = np.arange(0, len(data) - window, hop) energy = (total[starts + window] - total[starts]) / window level = np.log1p(1e4 * energy) rise = np.maximum(np.diff(level), 0.0) times = (np.arange(len(rise)) + 1) * hop / sr + window / (2 * sr) return rise, times def _fold(rise, times, bpm: float, bins: int): """Onsets folded over one beat, smoothed around the circle.""" beat = 60.0 / bpm phase = (times % beat) / beat folded = np.bincount((phase * bins).astype(int) % bins, weights=rise, minlength=bins) kernel = np.array([0.25, 0.5, 1.0, 0.5, 0.25]) padded = np.concatenate([folded[-2:], folded, folded[:2]]) return np.convolve(padded, kernel, mode="valid") def beat_grid(mono: np.ndarray, bpm: float, bins: int = 256, search: float = 0.25, step: float = 0.01) -> tuple[float, float]: """(bpm, offset): the tempo refined to 0.01 BPM and the seconds from the start to the first beat. A tempo 0.1 BPM out smears two minutes of beats across a fifth of a beat, so of the tempos within ``search`` of the estimate, the one whose folded onsets peak sharpest wins; the peak is the first beat (within ~4 ms on a synthetic kick track).""" if not bpm: return bpm, 0.0 limit = bpm_detect.SAMPLE_RATE * bpm_detect.MAX_SECONDS rise, times = onset_times(mono[:limit]) if len(rise) == 0 or not np.any(rise): return bpm, 0.0 best = (-1.0, bpm, None) for candidate in np.arange(bpm - search, bpm + search + step / 2, step): smooth = _fold(rise, times, candidate, bins) sharpness = smooth.max() / max(smooth.mean(), 1e-12) if sharpness > best[0]: best = (sharpness, float(candidate), smooth) _, refined, smooth = best offset = (int(np.argmax(smooth)) + 0.5) / bins * 60.0 / refined return round(refined, 2), offset def beat_offset(mono: np.ndarray, bpm: float) -> float: """Seconds to the first beat at exactly ``bpm`` (no refining).""" if not bpm: return 0.0 rise, times = onset_times(mono[:bpm_detect.SAMPLE_RATE * bpm_detect.MAX_SECONDS]) if len(rise) == 0: return 0.0 smooth = _fold(rise, times, bpm, 256) return (int(np.argmax(smooth)) + 0.5) / 256 * 60.0 / bpm def sync_ratio(own_bpm: float, target_bpm: float) -> float: """The speed that makes ``own_bpm`` play at ``target_bpm``: of the straight ratio and its half/double, the one nearest normal speed (a 70 BPM song syncs to a 140 BPM one at its own speed, beat on every other beat).""" if not own_bpm or not target_bpm: return 1.0 ratio = target_bpm / own_bpm # as many octaves as it takes (½× against 2× is two apart) while ratio > 2 ** 0.5: ratio /= 2 while ratio < 2 ** -0.5: ratio *= 2 return ratio def sync_speed(own_beat_bpm: float, target_beat_bpm: float, plausible: tuple[float, float] = (0.75, 1.34)) -> float: """The speed that plays ``own`` at ``target``, both as the decks count their beats (the ½×/1×/2× switch already applied). Taken straight when it's a plausible change of speed; a ratio further out than that means the two are counted an octave apart, so the nearest octave wins.""" if not own_beat_bpm or not target_beat_bpm: return 1.0 ratio = target_beat_bpm / own_beat_bpm if plausible[0] <= ratio <= plausible[1]: return ratio return sync_ratio(own_beat_bpm, target_beat_bpm) def beat_phase(position_s: float, offset_s: float, bpm: float) -> float: """Where in its beat a song is, 0..1.""" if not bpm: return 0.0 return ((position_s - offset_s) * bpm / 60.0) % 1.0 def phase_shift(own_phase: float, target_phase: float, own_bpm: float) -> float: """Seconds (of the song's own time) to move it so its beat lines up with the target's, by the shortest way: never more than half a beat.""" if not own_bpm: return 0.0 delta = (target_phase - own_phase + 0.5) % 1.0 - 0.5 return delta * 60.0 / own_bpm