autopitch 0.1.0

/// A generic pitch detection interface.
///
/// Implementations estimate the fundamental frequency of a signal,
/// returning `None` if no stable pitch can be determined.
pub trait PitchDetector {
    /// Detects the fundamental frequency (pitch) of the given audio samples.
    ///
    /// The method takes `&mut self` because some pitch detection algorithms,
    /// such as autocorrelation-based methods, internally reuse preallocated
    /// buffers to avoid heap allocations on each call.
    ///
    /// This mutability is not conceptually modifying detector state — it's a
    /// practical performance optimization that enables real-time use without
    /// violating functional behavior.
    ///
    /// # Parameters
    /// - `samples`: A short slice of raw audio data (for example, 20–100 milliseconds of sound),
    ///   represented as floating-point numbers where each value is the loudness of the signal
    ///   at a single point in time.
    /// - `sample_rate`: Sampling rate in Hz (e.g., 44_100.0).
    ///
    /// # Returns
    /// The estimated fundamental frequency in Hz, or `None` if detection fails.
    fn detect(&mut self, samples: &[f32], sample_rate: f32) -> Option<f32>;
}

pub fn detect_pitch<D: PitchDetector>(
    detector: &mut D,
    samples: &[f32],
    sample_rate: f32,
) -> Option<f32> {
    detector.detect(samples, sample_rate)
}