VL.Audio.BTrack
0.2.0-alpha
dotnet add package VL.Audio.BTrack --version 0.2.0-alpha
NuGet\Install-Package VL.Audio.BTrack -Version 0.2.0-alpha
<PackageReference Include="VL.Audio.BTrack" Version="0.2.0-alpha" />
<PackageVersion Include="VL.Audio.BTrack" Version="0.2.0-alpha" />
<PackageReference Include="VL.Audio.BTrack" />
paket add VL.Audio.BTrack --version 0.2.0-alpha
#r "nuget: VL.Audio.BTrack, 0.2.0-alpha"
#:package VL.Audio.BTrack@0.2.0-alpha
#addin nuget:?package=VL.Audio.BTrack&version=0.2.0-alpha&prerelease
#tool nuget:?package=VL.Audio.BTrack&version=0.2.0-alpha&prerelease
VL.Audio.BTrack
A real-time beat tracker node for vvvv gamma and VL.Audio: a C# port of BTrack by Adam Stark (Queen Mary University of London). Licensed GPL-3.0-or-later, as BTrack's licence requires: patches that use it fall under the GPL. To stay MIT, use VL.Audio.BeatNet instead.
- BTrack node (category
Audio.Analysis.BeatTracking):AudioSignalin, Beat (bang), BPM, Phase and Beat Count out. - Works at 44.1 kHz and 48 kHz. The original BTrack only supports 44.1 kHz.
- Allocates no memory on the audio thread in steady state.
- The DSP lives in
VL.Audio.BTrack.Core, a plain managed library (netstandard2.1 / net8.0) with no dependencies besidesVL.Audio.BeatTracking.Core. Only the thin VL adapter is Windows-specific, because VL.Audio is.
Installed along (MIT); their nodes are available wherever you reference VL.Audio.BTrack:
- VL.Audio.BeatTracking: the BeatScaler node (one beat per bar, quarter to quadruple tempo, and bars counted for BTrack), used below BTrack; tap tempo.
- VL.Audio.BeatNet: BeatNet, a newer tracker with a neural network and a particle filter.
help/HowTo Compare BTrack and BeatNet.vlruns both side by side.
Using it in vvvv
- Build the repository:
dotnet build -c Releasein its root (see the repository README). The assemblies go tolib/net8.0-windows7.0/of each package. - Make vvvv find the packages. Do one of the following:
- start vvvv with
--package-repositories "<repository root>", or - add the repository root under Settings > Package Repositories.
- start vvvv with
- Open
help/HowTo Track beats using BTrack.vl, or add theBTracknode to your own patch.
| Pin | Description |
|---|---|
| Input | Mono AudioSignal. Sum stereo channels first. |
| Offset (s) | Shifts the beat output in time, -1 to 1 s. Negative fires the beat earlier, to compensate for audio, processing and display latency (effective up to about half a beat). Positive delays it, e.g. when the sound reaches the audience later than this input (PA delay, video). Phase shifts along. |
| Fixed Tempo (optional) | If greater than 0, restricts the tracker to that tempo (folded into 80–160 BPM, see below). |
| Reset | Resets the tracker. |
| Tap Tempo | Tap at least 4 times on the beat to set the tempo and the beat position (see below). |
| Beat | True for one frame per beat. Beats are counted on the audio thread, so none get lost between audio buffers and frames. |
| BPM | Tempo measured from the recent beat intervals. Always within 80–160 BPM. |
| Phase | 0 at the beat, rising linearly to 1 one beat period later. |
| Beat Count | Number of beats so far. |
| Beat Info | All beat values in one (Beat, BPM, Phase, Beat Count; BTrack knows no bars, so Downbeat is off and Beat In Bar and Beats Per Bar are 0), for a single link to the BeatScaler; Split (BeatInfo) takes it apart. See VL.Audio.BeatTracking. |
| Status (optional) | Sample rate, hop size, tap tempo progress, errors. |
| CPU Load (optional) | Processing time on the audio thread as a fraction of real time, over the last second (0–1): 0.01 means 1 % of one core, 1 means the tracker cannot keep up. Wall-clock time; higher in Debug builds. |
Pin options shows, with illustrations, what problem each option solves.
Tempo range and folding
BTrack only knows tempi from 80 to 160 BPM (41 tempo states in steps of 2 BPM). Everything outside is folded into this range by halving or doubling:
- Music faster or slower than that is tracked at half or double tempo: a 170 BPM drum & bass track gets beats at 85 BPM, a 70 BPM ballad at 140 BPM. BPM shows the folded value.
- Tempi you enter are folded the same way: Fixed Tempo 70 means 140, and tapping at 70 BPM sets 140. The Status output says so when it folds a tapped tempo.
If you need the beats at the musical tempo, use the BeatScaler below BTrack.
Tap tempo
The tracker sometimes locks onto the wrong tempo, typically half or double, or onto the off-beat. It also needs a few seconds to lock on at the start. Tap Tempo corrects that:
- Tap at least 4 times on the beat. The Status output shows the progress ("tap tempo: 2 of 4 taps").
- From the 4th tap on, every tap sets the tempo (median of the last 8 tap intervals) and the beat position (your last tap). The beats then continue on your grid.
- Stop tapping: the tracker takes over from there and keeps following the music. After a pause of 2 s, the next tap starts a new series.
Limits:
- The tempo has BTrack's resolution: 2-BPM tempo states and a beat period in whole hops (about 11.6 ms).
- The beat position is as precise as your taps plus one frame, because the node sees a tap only at the next mainloop frame. Use a keyboard key rather than the mouse for steady timing.
- Tap tempo is a starting point, not a lock: the tracker keeps re-estimating the tempo at every beat, so music that contradicts your taps can pull it back to its own estimate.
- Fixed Tempo takes precedence: while it is set, the tempo returns to the fixed one at the next beat, and tap tempo effectively only sets the beat position.
If you need the beats at the musical tempo (BTrack folds into 80–160 BPM), use the BeatScaler (from VL.Audio.BeatTracking,
installed along) below BTrack; help/HowTo Track beats using BTrack.vl shows this setup. BTrack knows no bars; for downbeats or one
beat per bar, set the BeatScaler's Beats Per Bar and press Tap Downbeat on beat 1.
How 44.1 / 48 kHz support works
BTrack's tuned constants assume an onset-detection-function (ODF) rate of 44100 / 512 ≈ 86.13 Hz. These include:
- the Rayleigh tempo prior, peaking at a lag of 43,
- the comb filter lags,
- the 41 tempo states,
- the 6 s ODF history, and
- the cumulative-score mixing per ODF sample.
This port keeps that rate at every sample rate by using a hop size of round(512 · fs / 44100). That is 512 at 44.1 kHz and
557 at 48 kHz, with the frame size staying 1024 (the FFT is still a power of two).
The ODF history is then exactly 512 samples, and no resampling is needed. All places where the original hard-codes
44100 use the actual sample rate. Other hop sizes are supported through a windowed-sinc resampler, which replaces
libsamplerate.
A comparison on synthetic drum loops (82–158 BPM, 3 variants each) measured mean tempo error and beat offset:
| Configuration | Mean tempo error | Mean beat offset |
|---|---|---|
| 44.1 kHz, hop 512 (original) | 1.42 BPM | 10.2 ms |
| 48 kHz, hop 512 | 2.13 BPM (up to −6 at 142–154 BPM) | 12.3 ms |
| 48 kHz, hop 557 (used) | 1.57 BPM | 10.0 ms |
Fidelity and deviations from the original
The port follows BTrack 1.0.7 literally. That includes:
- the MATLAB-style indexing,
- the asymmetric adaptive threshold windows,
- the integer division
41 / 8, and - C
round()semantics.
Deviations:
- Recovery after silence. If all tempo probabilities become 0 (silence or a constant signal), the previous tempo state is kept. The original multiplies its state to zero and can never recover.
SetTempoapplies the new beat period. The original computes it but discards it. An added overload also sets the beat phase; tap tempo uses it.- Time-domain ACF and windowed-sinc resampler instead of FFT/Kiss FFT and libsamplerate. The ACF is mathematically equivalent; the resampler is only used for non-default hop sizes. All arithmetic is in double precision.
- Measured BPM output. BTrack's own tempo estimate is quantised: 2-BPM states and an integer beat period.
It is also biased slightly slow (typically 0–4 BPM), because the comb filter reads ACF lags centred on
a·i − 1. That bias is in the original and is kept. The node's BPM output is instead measured from the actual beat intervals (trimmed mean of the last 8), which is accurate to about ±0.5 BPM on steady material.
Like the original, BTrack reports a beat on average 1–2 hops (≈ 10–25 ms) after the onset. Use a negative Offset to compensate.
Repository layout
src/VL.Audio.BTrack.Core/ port of BTrack (BeatTracker, OnsetDetectionFunction, BeatTrackerProcessor, FFT,
resampler); namespace VL.Audio.BTrack
src/VL.Audio.BTrack/ VL adapter: BTrackNode ([ProcessNode]) on top of BeatTrackerController and
BeatTrackerSignal (VL.Audio SinkSignal)
tests/VL.Audio.BTrack.Core.Tests/ unit and behavioural tests
tests/VL.Audio.BTrack.Tests/ integration test that drives VL.Audio's real audio callback without vvvv
VL.Audio.BTrack.vl VL document (package entry point)
help/ help patches (the BTrack node; BTrack vs. BeatNet side by side)
dotnet test in this folder runs its tests (they use the two other packages next to it).
Licence
GPL-3.0-or-later (see LICENSE.txt), as required by the original BTrack licence.
- BTrack: Copyright © 2008–2014 Adam Stark, Queen Mary University of London.
- If you use this in research, please cite A. M. Stark, M. E. P. Davies and M. D. Plumbley, "Real-Time Beat-Synchronous Analysis of Musical Audio", DAFx 2009.
- The two MIT dependencies and their third-party notices are listed in
THIRD-PARTY-NOTICES.md.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0-windows7.0 is compatible. net9.0-windows was computed. net10.0-windows was computed. |
-
net8.0-windows7.0
- VL.Audio (>= 1.9.19)
- VL.Audio.BeatNet (>= 0.2.0-alpha)
- VL.Audio.BeatTracking (>= 0.2.0-alpha)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 0.2.0-alpha | 58 | 11/15/2026 |