metricon 0.0.3

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

When the beat times are already known, track_bars decodes only the bar lines and meter on top of them (the beat-synchronous equivalent of madmom's DBNBarTrackingProcessor):

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

Constrain the path through events you already know (the rest are filled in) — beats for track_beats, beats and/or downbeats 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])

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 "fill-in" anchored decoding from known beats and downbeats, and beat-synchronous bar tracking from known beats (track_bars).

Roadmap

• Arbitrary beat-in-bar anchors. Beat and downbeat anchors work today (force a beat, or a downbeat / bar line, at a known time). Forcing a specific beat-in-bar position — e.g. "this is beat 3 of the bar" — needs per-state masking in the decoder rather than the current per-column masking, since the beat-in-bar lives in the state, not the emission column. Planned.

License

MIT. See NOTICE for algorithm citations.