metricon 0.1.0

Beats, downbeats and bars from neural logits — a fast state-space decoder.

metricon

Beats, downbeats and bars from neural logits — a fast state-space decoder.

metricon is the decoder half of a beat-tracking pipeline. You bring per-frame beat/downbeat logits from any model (e.g. Beat This!, an RNN/TCN, your own); metricon turns them into metrical structure — beats, downbeats, tempo and meter — with a state-space HMM decoded by Viterbi. No audio, no neural net, no torch: just numpy.

import metricon

beats = metricon.track_beats(beat_logits, fps=50)
print(beats.times)            # numpy array of beat times (seconds)
beats.to_tsv("beats.tsv")

# snap="center" reports the center of each activation peak (sub-frame),
# instead of the default strongest frame
beats = metricon.track_beats(beat_logits, fps=50, snap="center")

From probabilities instead of logits:

act = metricon.Activations.from_activations(beat_prob, fps=50)
beats = metricon.track_beats(act)

Downbeats, bars and meter (needs downbeat logits). multi_meter selects whether the time signature is fixed for the piece or may change mid-song:

# one meter for the whole piece (the best-scoring of the candidates)
bars = metricon.track_downbeats(beat_logits, downbeat_logits, beats_per_bar=(3, 4))

# or let the time signature change within the piece
bars = metricon.track_downbeats(beat_logits, downbeat_logits,
                                beats_per_bar=(3, 4, 6), multi_meter=True)
print(bars.times)            # beat times (seconds)
print(bars.numbers)          # position in the bar, 1 = downbeat
print(bars.downbeat_times)   # just the downbeats

# favour a meter when the evidence is ambiguous (a proper Bayesian prior —
# it tips a near-tie, strong evidence still wins)
bars = metricon.track_downbeats(beat_logits, downbeat_logits,
                                beats_per_bar=(3, 4), meter_prior={4: 4, 3: 1})

When the beat times are already known, track_bars decodes only the bar lines and meter on top of them:

bars = metricon.track_bars(downbeat_logits, beats, beats_per_bar=(3, 4))
print(bars.numbers)          # position in the bar for each given beat

Every result carries tempo, derived from the beats:

print(beats.bpm)              # median tempo (BPM)
print(beats.tempo)            # per-interval tempo (BPM), one per gap

Constrain the path through events you already know (the rest are filled in) — beats for track_beats, beats / downbeats / specific bar positions for track_downbeats:

beats = metricon.track_beats(beat_logits, fps=50, anchors=[1.02, 2.05, 3.07])

# force bar lines without pinning the meter — the decoder still picks 3/4 vs 4/4
bars = metricon.track_downbeats(beat_logits, downbeat_logits,
                                downbeat_anchors=[0.51, 2.49, 4.47])

# force a specific beat-in-bar — "this is beat 3" — meter still free
bars = metricon.track_downbeats(beat_logits, downbeat_logits,
                                position_anchors=[(2.49, 3)])

Stream it — push logits in any-size chunks, get beats out as they arrive (causal forward decode; track_beats/track_downbeats stay the offline path):

track = metricon.StreamingDownbeatTracker(beats_per_bar=(3, 4), fps=50, delay=4)
for beat_chunk, downbeat_chunk in logit_stream:
    times, numbers = track.process(beat_chunk, downbeat_chunk)

See docs/api.md for the full API.

Why

Built from the published Krebs/Böck/Widmer equations (CC BY 4.0 — see docs/algorithm.md): the efficient bar-pointer DBN with a fast, low-memory decoder that comfortably handles long, high-fps tracks.

Status

Beats, downbeats, bars and within-song meter changes all work today, decoded by the compiled float32 kernel, plus per-beat tempo, "fill-in" anchored decoding from known beats / downbeats / specific bar positions, beat-synchronous bar tracking from known beats (track_bars), and streaming beat / downbeat / bar tracking via a causal forward decode (StreamingBeatTracker / StreamingDownbeatTracker / StreamingBarTracker).

Each task comes in three forms: a one-shot function (track_beats), a reusable batch class that builds the model once (BeatTracker), and a streaming class (StreamingBeatTracker). Plus a meter_prior (favour 4/4 on ambiguous tracks) that keeps how likely a meter is separate from how likely it is to switch.

License

MIT. See NOTICE for algorithm citations.