Skip to main content

beatnet_rs/
lib.rs

1//! Streaming BeatNet beat/downbeat tracking without Python or an async runtime.
2//!
3//! Construct and process on a worker thread. Only [`transport::AudioProducer`]
4//! belongs in an audio callback. Frame/event times refer to the source audio,
5//! not wall-clock delivery time; the frontend needs 706 samples of lookahead.
6#![forbid(unsafe_code)]
7
8#[cfg(feature = "live")]
9pub mod capture;
10pub mod features;
11pub mod model;
12pub mod tracker;
13pub mod transport;
14
15use features::{FeatureExtractor, SAMPLE_RATE};
16pub use model::{Inference, Model, OnnxModel};
17mod resample;
18use resample::RateConverter;
19use tracker::ParticleFilter;
20pub use tracker::TrackerConfig;
21
22#[derive(Debug, thiserror::Error)]
23pub enum Error {
24    #[error("invalid configuration: {0}")]
25    Config(&'static str),
26    #[error("PCM contains non-finite samples")]
27    InvalidPcm,
28    #[error("invalid model probabilities or recurrent output")]
29    ModelOutput,
30    #[error("processor must be reset after a backend failure")]
31    NeedsReset,
32    #[error("timestamp must be finite, nonnegative, and increase between frames")]
33    InvalidTime,
34    #[error("model requires finite feature values")]
35    ModelInput,
36    #[error("incompatible ONNX interface: {0}")]
37    ModelInterface(&'static str),
38    #[cfg(feature = "live")]
39    #[error(transparent)]
40    Capture(#[from] cpal::Error),
41    #[error("stream has been finished; reset before processing more audio")]
42    Finished,
43    #[error("incomplete interleaved frame at end of stream")]
44    IncompleteFrame,
45    #[error(transparent)]
46    Onnx(#[from] ort::Error),
47    #[error(transparent)]
48    Io(#[from] std::io::Error),
49    #[error(transparent)]
50    ResamplerConstruction(#[from] rubato::ResamplerConstructionError),
51    #[error(transparent)]
52    Resample(#[from] rubato::ResampleError),
53}
54/// Source audio format, pretrained model, and tracker settings.
55#[derive(Clone, Debug)]
56pub struct BeatNetConfig {
57    /// Input samples per second (8,000 through 192,000).
58    pub sample_rate: u32,
59    /// Interleaved channel count (1 through 64).
60    pub channels: u16,
61    pub model: Model,
62    pub tracker: TrackerConfig,
63}
64impl Default for BeatNetConfig {
65    fn default() -> Self {
66        Self {
67            sample_rate: SAMPLE_RATE,
68            channels: 1,
69            model: Model::One,
70            tracker: TrackerConfig::default(),
71        }
72    }
73}
74impl BeatNetConfig {
75    /// Validate settings without allocating DSP buffers or loading a model.
76    pub fn validate(&self) -> Result<(), Error> {
77        validate_audio_format(self.sample_rate, self.channels)?;
78        self.tracker.validate()
79    }
80}
81
82pub(crate) fn validate_audio_format(rate: u32, channels: u16) -> Result<(), Error> {
83    if !(8_000..=192_000).contains(&rate) || !(1..=64).contains(&channels) {
84        return Err(Error::Config(
85            "sample rate must be 8000..=192000; channels 1..=64",
86        ));
87    }
88    Ok(())
89}
90
91pub(crate) fn validate_probabilities(probabilities: &[f32; 3]) -> Result<(), Error> {
92    if probabilities
93        .iter()
94        .any(|p| !p.is_finite() || !(0.0..=1.0).contains(p))
95        || (probabilities.iter().sum::<f32>() - 1.0).abs() > 1e-4
96    {
97        return Err(Error::ModelOutput);
98    }
99    Ok(())
100}
101
102/// An accepted beat on the source audio timeline.
103#[derive(Clone, Copy, Debug, PartialEq)]
104pub struct BeatEvent {
105    /// Seconds from the beginning of the source audio.
106    pub time: f64,
107    pub bpm: f32,
108    pub downbeat: bool,
109    /// Circular concentration of beat particles, not a calibrated probability.
110    pub confidence: f32,
111}
112/// Posterior estimates for a single 20 ms feature frame.
113#[derive(Clone, Copy, Debug, PartialEq)]
114pub struct TrackingState {
115    pub time: f64,
116    pub bpm: Option<f32>,
117    /// Phase within a beat, in [0, 1); absent before the first accepted beat.
118    pub phase: Option<f32>,
119    pub meter: Option<u8>,
120    pub confidence: f32,
121    /// Class probabilities: beat, downbeat, non-beat.
122    pub probabilities: [f32; 3],
123}
124/// State and optional beat event produced together for one feature frame.
125#[derive(Clone, Copy, Debug, PartialEq)]
126pub struct FrameOutput {
127    pub state: TrackingState,
128    pub event: Option<BeatEvent>,
129}
130
131struct Engine<M> {
132    features: FeatureExtractor,
133    model: M,
134    tracker: ParticleFilter,
135    origin: f64,
136    frames: u64,
137    frame_limit: Option<u64>,
138}
139impl<M: Inference> Engine<M> {
140    fn push(&mut self, sample: f32, emit: &mut impl FnMut(FrameOutput)) -> Result<(), Error> {
141        if self.frame_limit.is_some_and(|limit| self.frames >= limit) {
142            return Ok(());
143        }
144        if let Some((position, features)) = self.features.push(sample) {
145            let probabilities = self.model.infer(&features)?;
146            let (state, event) = self.tracker.process(
147                probabilities,
148                self.origin + position as f64 / SAMPLE_RATE as f64,
149            )?;
150            self.frames += 1;
151            emit(FrameOutput { state, event });
152        }
153        Ok(())
154    }
155}
156/// Synchronous PCM processor. `process` accepts arbitrary interleaved chunk sizes,
157/// including chunks ending partway through a multichannel frame.
158pub struct BeatNet<M = OnnxModel> {
159    config: BeatNetConfig,
160    engine: Engine<M>,
161    converter: Option<RateConverter>,
162    channel: usize,
163    sum: f64,
164    input_frames: u64,
165    status: Status,
166}
167#[derive(Clone, Copy, Debug, PartialEq, Eq)]
168enum Status {
169    Active,
170    Failed,
171    Finished,
172}
173
174impl BeatNet<OnnxModel> {
175    /// Load and warm the selected model, then allocate processing buffers.
176    pub fn new(config: BeatNetConfig) -> Result<Self, Error> {
177        config.validate()?;
178        let model = OnnxModel::bundled(config.model)?;
179        Self::with_model(config, model)
180    }
181}
182impl<M: Inference> BeatNet<M> {
183    /// Use a caller-supplied synchronous backend; its recurrent state is reset.
184    pub fn with_model(config: BeatNetConfig, mut model: M) -> Result<Self, Error> {
185        config.validate()?;
186        let tracker = ParticleFilter::new(config.tracker.clone())?;
187        let converter = if config.sample_rate == SAMPLE_RATE {
188            None
189        } else {
190            Some(RateConverter::new(config.sample_rate)?)
191        };
192        model.reset();
193        Ok(Self {
194            config,
195            engine: Engine {
196                features: FeatureExtractor::new(),
197                model,
198                tracker,
199                origin: 0.,
200                frames: 0,
201                frame_limit: None,
202            },
203            converter,
204            channel: 0,
205            sum: 0.,
206            input_frames: 0,
207            status: Status::Active,
208        })
209    }
210    /// Output callback runs on the calling thread; it should not block.
211    /// Invalid PCM is rejected before consuming any of the supplied chunk.
212    /// A backend error or unwinding callback puts this processor in `NeedsReset`
213    /// state. Reset before resuming; already emitted outputs are not rolled back.
214    pub fn process(&mut self, pcm: &[f32], mut emit: impl FnMut(FrameOutput)) -> Result<(), Error> {
215        match self.status {
216            Status::Finished => return Err(Error::Finished),
217            Status::Failed => return Err(Error::NeedsReset),
218            Status::Active => {}
219        }
220        if pcm.iter().any(|v| !v.is_finite()) {
221            return Err(Error::InvalidPcm);
222        }
223        // A backend or user callback can unwind after advancing only part of a chunk.
224        // Stay failed unless the entire operation returns successfully.
225        self.status = Status::Failed;
226        let channels = usize::from(self.config.channels);
227        if channels == 1 {
228            self.input_frames += pcm.len() as u64;
229            self.process_mono(pcm, &mut emit)?;
230        } else {
231            let mut mono = [0.; features::HOP];
232            for block in pcm.chunks(mono.len() * channels) {
233                let mut frames = 0;
234                for &sample in block {
235                    self.sum += f64::from(sample);
236                    self.channel += 1;
237                    if self.channel == channels {
238                        mono[frames] = (self.sum / channels as f64) as f32;
239                        frames += 1;
240                        self.sum = 0.;
241                        self.channel = 0;
242                    }
243                }
244                self.input_frames += frames as u64;
245                self.process_mono(&mono[..frames], &mut emit)?;
246            }
247        }
248        self.status = Status::Active;
249        Ok(())
250    }
251    fn process_mono(
252        &mut self,
253        samples: &[f32],
254        emit: &mut impl FnMut(FrameOutput),
255    ) -> Result<(), Error> {
256        if let Some(converter) = &mut self.converter {
257            converter.process(samples, &mut self.engine, emit)
258        } else {
259            for &sample in samples {
260                self.engine.push(sample, emit)?;
261            }
262            Ok(())
263        }
264    }
265    /// Drain resampler and centered-window lookahead with zero padding. Emits only
266    /// frames whose centers lie before the end of the original audio. Idempotent.
267    pub fn finish(&mut self, mut emit: impl FnMut(FrameOutput)) -> Result<(), Error> {
268        match self.status {
269            Status::Finished => return Ok(()),
270            Status::Failed => return Err(Error::NeedsReset),
271            Status::Active => {}
272        }
273        if self.channel != 0 {
274            return Err(Error::IncompleteFrame);
275        }
276        // Count frame centers with integers, including at large source offsets.
277        let frames = (u128::from(self.input_frames) * u128::from(features::FRAME_RATE))
278            .div_ceil(u128::from(self.config.sample_rate)) as u64;
279        self.status = Status::Failed;
280        self.engine.frame_limit = Some(frames);
281        while self.engine.frames < frames {
282            self.process_mono(&[0.0], &mut emit)?;
283        }
284        self.status = Status::Finished;
285        Ok(())
286    }
287    /// Reset a new stream at time zero.
288    pub fn reset(&mut self) {
289        self.discontinuity(0);
290    }
291    /// Reset after missing PCM. `source_frame` is the next frame's absolute
292    /// position at the configured input rate (one frame contains all channels).
293    pub fn discontinuity(&mut self, source_frame: u64) {
294        self.engine.origin = source_frame as f64 / self.config.sample_rate as f64;
295        self.engine.features.reset();
296        self.engine.model.reset();
297        self.engine
298            .tracker
299            .reset_at(self.engine.origin)
300            .expect("sample-derived time is finite and nonnegative");
301        self.engine.frames = 0;
302        self.engine.frame_limit = None;
303        if let Some(converter) = &mut self.converter {
304            converter.reset();
305        }
306        self.channel = 0;
307        self.sum = 0.;
308        self.input_frames = 0;
309        self.status = Status::Active;
310    }
311    /// The immutable settings used to construct this processor.
312    pub fn config(&self) -> &BeatNetConfig {
313        &self.config
314    }
315}