pub struct Audio { /* private fields */ }Expand description
Planar floating-point audio. All channels have the same length. Samples may exceed ±1 to retain headroom; encoders clamp at quantization.
Implementations§
Source§impl Audio
impl Audio
Sourcepub fn dc_means(&self) -> Result<Vec<Option<f64>>>
pub fn dc_means(&self) -> Result<Vec<Option<f64>>>
Per-channel dc_mean, with None for each empty channel. Allocates at
most one Vec of channel-count options, not a PCM copy. Default Limits
apply, including to input decoded with custom larger limits.
Sourcepub fn threshold_silence(&self, threshold: f64) -> Result<ThresholdSilence>
pub fn threshold_silence(&self, threshold: f64) -> Result<ThresholdSilence>
Frame-exact threshold silence: a frame is quiet iff every channel’s absolute sample is <= threshold (linear input units, finite and >=0). Checks all samples, including inside the active range. Empty input has zero counts; wholly quiet input has two overlapping full-length counts. This is independent of detect_silence’s window-RMS/min-duration policy. Default Limits apply. O(samples) time, O(1) storage, no allocation.
Sourcepub fn stereo_measurements(&self) -> Result<StereoMeasurements>
pub fn stereo_measurements(&self) -> Result<StereoMeasurements>
stereo_measurements of this Audio, requiring exactly two channels.
No downmixing, channel selection or allocation. Default Limits apply.
Sourcepub fn measure_boundaries(
&self,
boundaries: &[MeasurementBoundary],
) -> Result<Vec<BoundaryMeasurement>>
pub fn measure_boundaries( &self, boundaries: &[MeasurementBoundary], ) -> Result<Vec<BoundaryMeasurement>>
Measure explicit joins, in request order (including duplicates), without changing samples/metadata or labeling steps as audible clicks. All ranges and finite samples are checked before allocating output. Frame boundaries must have two existing neighbors; LoopSeam yields None below two frames.
Default Limits cap input shape, including 64 channels. At most MAX_MEASUREMENT_BOUNDARIES requests (4,096), each with one bounded channel Vec; allocation failure/oversize returns LimitExceeded. Empty requests still validate PCM and return an empty Vec. Time O(samples+requestschannels), storage O(requestschannels), with no per-frame PCM copy/window scan.
Source§impl Audio
impl Audio
pub fn peak(&self) -> f64
pub fn peak_db(&self) -> f64
Sourcepub fn mean_square(&self) -> f64
pub fn mean_square(&self) -> f64
Mean squared sample amplitude, averaged equally over all channels and
frames: sum(sample^2) / (frames * channels). Empty and silent PCM return
zero. Finite samples outside +/-1 retain their power without clamping.
Accumulation is f64 in planar channel/frame order, O(samples) with no
allocation. This is unweighted signal power, not calibrated loudness.
For aggregation use frames() * channels() as the sample denominator;
combining regions uses the weighted mean of their powers.
Sourcepub fn rms(&self) -> f64
pub fn rms(&self) -> f64
Linear root-mean-square sample amplitude, sqrt(mean_square()).
Empty/silent PCM returns zero; channels have equal weight. This retains
the report-only numerical policy of Self::rms_db.
Sourcepub fn measure_deterministic(&self) -> Result<DeterministicMeasurements>
pub fn measure_deterministic(&self) -> Result<DeterministicMeasurements>
Measure this exact PCM with the deterministic normalization estimators. No gain, clipping, resampling, quantization or PCM clone is performed.
Uses unrounded f64 levels and deterministic coefficient/logarithm math. True peak is the existing 4x/32-tap-per-phase Blackman sinc estimate, including sample peak, with zero extension and scans at input frames. It is not a universal continuous-time bound or the limiter’s 8x detector.
Loudness uses full 400-ms blocks at 100-ms hops, inclusive -70 LUFS and relative -10 LU gates. A shorter input uses its entire ungated power. Empty, silent or wholly gated input has integrated/peak-momentary levels of negative infinity and range zero. Quad weights are 1/1/1.41/1.41, five-channel 1/1/1/1.41/1.41, six-channel 1/1/1/0/1.41/1.41; other counts use unit weights. Channel count does not infer a speaker layout. The range is a legacy block-percentile estimate, not certified EBU LRA.
Requires >=4000 Hz, finite input and finite filter results; violations
return InvalidArgument, including on empty input. Checks default
crate::Limits before workspace allocation (also for Audio decoded
with custom limits); a larger shape returns LimitExceeded. Offline
work/storage is proportional to samples and block count, as in
normalization. Existing report-only analysis keeps its platform math.
pub fn true_peak_db(&self) -> f64
pub fn waveform(&self, buckets: usize) -> Result<Waveform>
Sourcepub fn loudness(&self) -> LoudnessResult
pub fn loudness(&self) -> LoudnessResult
K-weighted, gated loudness; range is the legacy 400-ms block percentile estimate.
Source§impl Audio
impl Audio
pub fn new(data: Vec<Vec<f32>>, sample_rate: u32) -> Result<Self>
pub fn sample_rate(&self) -> u32
pub fn channels(&self) -> usize
pub fn frames(&self) -> usize
pub fn duration(&self) -> f64
pub fn info(&self) -> &DecodeInfo
pub fn channel_data(&self, channel: usize) -> Result<&[f32]>
pub fn all_channels(&self) -> &[Vec<f32>]
pub fn to_interleaved(&self) -> Vec<f32>
pub fn from_interleaved( samples: &[f32], channels: usize, rate: u32, ) -> Result<Self>
pub fn silence( duration: impl Into<TimePosition>, channels: usize, rate: u32, ) -> Result<Self>
pub fn cut( &self, from: impl Into<TimePosition>, to: impl Into<TimePosition>, ) -> Result<Self>
pub fn remove( &self, from: impl Into<TimePosition>, to: impl Into<TimePosition>, ) -> Result<Self>
pub fn concat(&self, other: &Self) -> Result<Self>
pub fn pad( &self, before: impl Into<TimePosition>, after: impl Into<TimePosition>, ) -> Result<Self>
pub fn reverse(&self) -> Self
pub fn mix( &self, overlay: &Self, offset: i64, gain: f32, extend: bool, ) -> Result<Self>
pub fn crossfade_to( &self, other: &Self, duration: impl Into<TimePosition>, ) -> Result<Self>
pub fn to_mono(&self) -> Self
pub fn to_stereo(&self) -> Self
pub fn to_channels(&self, count: usize) -> Result<Self>
pub fn map_channels(&self, mapping: &[usize]) -> Result<Self>
pub fn pan(&self, position: f64) -> Result<Self>
pub fn split(&self) -> Vec<Self>
pub fn merge(parts: &[Self]) -> Result<Self>
pub fn duration_formatted(&self) -> String
Source§impl Audio
impl Audio
pub fn gain(&self, linear: f64) -> Result<Self>
pub fn gain_db(&self, db: f64) -> Result<Self>
Sourcepub fn normalize(&self, options: NormalizeOptions) -> Result<Self>
pub fn normalize(&self, options: NormalizeOptions) -> Result<Self>
Normalize the complete signal with deterministic measurement and gain math.
LUFS normalization requires at least 4000 Hz for the K-weighting filters.
Report-only loudness/true_peak_db retain platform math; use this method
or Self::normalize_with_report when measurements drive rendered samples.
Sourcepub fn normalize_with_report(
&self,
options: NormalizeOptions,
) -> Result<(Self, NormalizeReport)>
pub fn normalize_with_report( &self, options: NormalizeOptions, ) -> Result<(Self, NormalizeReport)>
Normalize and report the deterministic measurement and applied gain in dB. Silence and wholly gated material return unchanged with zero gain. LUFS uses the existing short-input and channel-weight policies. Its peak ceiling uses four-times oversampled true peak, not a true-peak limiter.
pub fn fade( &self, in_seconds: f64, out_seconds: f64, curve: FadeCurve, ) -> Result<Self>
pub fn remove_dc_offset(&self) -> Self
Sourcepub fn resampled_frame_index(
&self,
source_frame: usize,
sample_rate: u32,
) -> Result<usize>
pub fn resampled_frame_index( &self, source_frame: usize, sample_rate: u32, ) -> Result<usize>
Map an absolute source boundary in 0..=frames() to the output of
Self::resample, without rendering or allocating PCM.
Uses the existing f64 policy: first ratio = output_rate / input_rate,
then round(source_frame * ratio), with positive half ties upward.
This is not exact rational arithmetic: e.g. 500 at 1000 -> 1001 Hz maps
to 500 because the floating product is just below 500.5. The same helper
determines the actual whole-buffer output length, preserving legacy PCM.
Mapping is monotonic, maps zero to zero and the input end to output end.
Map body/tail absolute boundaries, then subtract mapped boundaries;
do not sum independently rounded durations. At 48 -> 44.1 kHz, source
boundaries 0/80/160 map to 0/74/147: 74 body frames and 73 tail frames.
Invalid source boundaries return InvalidArgument; default output shape
limits (also used by resample) return LimitExceeded.
Sourcepub fn resample(&self, sample_rate: u32) -> Result<Self>
pub fn resample(&self, sample_rate: u32) -> Result<Self>
Offline Kaiser-windowed sinc resampling with clamped first/last samples.
Output length follows Self::resampled_frame_index at the input end;
empty input stays empty and identity-rate input is cloned bit for bit.
Output frame i samples source position i / ratio, so frame zero has
source-time zero. Symmetric filtering uses future context, with no added
leading delay or appended filter/release tail. A transient peak need not
remain at the corresponding rounded index. Short downsampled input may
round to zero frames. Additional samples beyond the mapped end are never
emitted. Default Limits bound the output before allocation.
pub fn filter(&self, options: FilterOptions) -> Result<Self>
pub fn limit(&self, options: LimiterOptions) -> Result<Self>
pub fn detect_silence( &self, options: SilenceOptions, ) -> Result<Vec<SilentRange>>
pub fn trim_silence(&self, options: SilenceOptions) -> Result<Self>
pub fn speed(&self, factor: f64) -> Result<Self>
Sourcepub fn tempo(&self, factor: f64) -> Result<Self>
pub fn tempo(&self, factor: f64) -> Result<Self>
WSOLA tempo adjustment; channel offsets are shared to preserve stereo phase.
pub fn pitch(&self, semitones: f64) -> Result<Self>
Source§impl Audio
impl Audio
Sourcepub fn limit_true_peak(&self, options: TruePeakLimiterOptions) -> Result<Self>
pub fn limit_true_peak(&self, options: TruePeakLimiterOptions) -> Result<Self>
Limit reconstructed peaks offline, linking gain across every channel.
Eight-times/64-tap detection drives instantaneous attack, lookahead and exponential release at the source rate. A final whole-output check against that reconstruction and the existing four-times estimator can apply an additional uniform attenuation. The default 0.3 dB safety margin is explicit; this finite reconstruction is not a proof for every continuous-time signal.
Output has exactly the input’s rate, channels, frame count and leading alignment. Lookahead and FIR context are read ahead from the complete input; no leading delay or release frames are added. Zero-extended FIR tails are checked even though they are not appended to the returned PCM.
Workspace is checked before allocation. Invalid settings return
crate::ErrorCode::InvalidArgument; workspace budget/size/reservation failures return
crate::ErrorCode::LimitExceeded. This is not a realtime callback API.