VL.Audio.BTrack 0.2.0-alpha

This is a prerelease version of VL.Audio.BTrack.
dotnet add package VL.Audio.BTrack --version 0.2.0-alpha
                    
NuGet\Install-Package VL.Audio.BTrack -Version 0.2.0-alpha
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="VL.Audio.BTrack" Version="0.2.0-alpha" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="VL.Audio.BTrack" Version="0.2.0-alpha" />
                    
Directory.Packages.props
<PackageReference Include="VL.Audio.BTrack" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add VL.Audio.BTrack --version 0.2.0-alpha
                    
#r "nuget: VL.Audio.BTrack, 0.2.0-alpha"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package VL.Audio.BTrack@0.2.0-alpha
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=VL.Audio.BTrack&version=0.2.0-alpha&prerelease
                    
Install as a Cake Addin
#tool nuget:?package=VL.Audio.BTrack&version=0.2.0-alpha&prerelease
                    
Install as a Cake Tool

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): AudioSignal in, 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 besides VL.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.vl runs both side by side.

Using it in vvvv

  1. Build the repository: dotnet build -c Release in its root (see the repository README). The assemblies go to lib/net8.0-windows7.0/ of each package.
  2. 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.
  3. Open help/HowTo Track beats using BTrack.vl, or add the BTrack node 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:

  1. Tap at least 4 times on the beat. The Status output shows the progress ("tap tempo: 2 of 4 taps").
  2. 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.
  3. 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:

  1. 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.
  2. SetTempo applies the new beat period. The original computes it but discards it. An added overload also sets the beat phase; tap tempo uses it.
  3. 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.
  4. 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 Compatible and additional computed target framework versions.
.NET net8.0-windows7.0 is compatible.  net9.0-windows was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

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