Crate timestretch 

Pure Rust audio time stretching library optimized for electronic dance music.

timestretch changes the tempo of audio without altering its pitch. The core is a pull-based real-time engine (varispeed head plus a two-band SOLA keylock stage); batch stretch() renders run offline on the same graph, and pitch_shift() adds formant-corrected pitch shifting.

Quick Start

use timestretch::StretchParams;

// 1 second of 440 Hz sine at 44.1 kHz
let input: Vec<f32> = (0..44100)
    .map(|i| (2.0 * std::f32::consts::PI * 440.0 * i as f32 / 44100.0).sin())
    .collect();

let params = StretchParams::new(1.5)
    .with_sample_rate(44100)
    .with_channels(1);

let output = timestretch::stretch(&input, &params).unwrap();
assert!(output.len() > input.len()); // ~1.5x longer

Real-time engine

For real-time use, build the engine and let the audio callback fill exactly the frames it needs:

use timestretch::engine::{Engine, EngineConfig, EngineProfile};

let handles = Engine::build(EngineConfig {
    channels: 2,
    profile: EngineProfile::Keylock,
    ..EngineConfig::default()
}).unwrap();
let (controller, mut processor, mut source) =
    (handles.controller, handles.processor, handles.source);

// Feed thread: push interleaved source audio as it becomes available.
source.push(&vec![0.0f32; 8_192 * 2]);
// Control thread (lock-free): retarget tempo any time.
controller.set_tempo_rate(1.02);
// Audio callback: infallible, allocation-free.
let mut out = vec![0.0f32; 256 * 2];
processor.process(&mut out);

Re-exports

pub use analysis::beat::BeatGrid;

pub use analysis::beat::TempoCandidate;

pub use analysis::beat::TempoSegment;

pub use analysis::key::detect_key;

pub use analysis::loudness::MomentaryLoudness;

pub use analysis::loudness::measure_loudness;

pub use analysis::preanalysis::AnalysisReport;

pub use analysis::preanalysis::analyze_for_dj;

pub use analysis::preanalysis::analyze_for_dj_with_report;

pub use analysis::preanalysis::downmix_to_mid;

pub use analysis::rigid_grid::RigidGridFit;

pub use analysis::rigid_grid::fit_rigid_grid;

pub use analysis::rigid_grid::refine_grid_rigid;

pub use analysis::tempogram::TempoTrackingOptions;

pub use analysis::waveform::BandPeaks;

pub use analysis::waveform::NUM_BANDS;

pub use analysis::waveform::PeakLevel;

pub use core::preanalysis::KeyEstimate;

pub use core::preanalysis::KeyMode;

pub use core::preanalysis::LoudnessMeasurement;

pub use core::preanalysis::PREANALYSIS_VERSION;

pub use core::preanalysis::PreAnalysisArtifact;

pub use core::preanalysis::hash_samples;

pub use core::preanalysis::read_preanalysis_json;Deprecated

pub use core::preanalysis::write_preanalysis_json;Deprecated

pub use core::types::AudioBuffer;

pub use core::types::Channels;

pub use core::types::EnvelopePreset;

pub use core::types::FrameIter;

pub use core::types::QualityMode;

pub use core::types::Sample;

pub use core::types::StretchParams;

pub use core::types::TransientThresholdPolicy;

pub use core::window::WindowType;

pub use error::StretchError;

pub use io::tsa::AnalysisFile;

pub use io::tsa::TSA_CONTAINER_VERSION;

pub use io::tsa::analysis_file_path;

pub use io::tsa::read_analysis_file;

pub use io::tsa::read_analysis_file_validated;

pub use io::tsa::write_analysis_file;

pub use stretch::phase_locking::PhaseLockingMode;

Modules

analysis

Audio analysis: transient detection, beat tracking, frequency analysis, and HPSS.

core

Core types, window functions, and resampling utilities.

engine

Real-time-first engine.

error

Error types for the timestretch crate.

io

File I/O: WAV audio and the .tsa analysis container.

stretch

Batch time-stretching DSP retained by the engine: the phase vocoder (the offline wide-ratio path and analysis tooling) and its support modules. The hybrid combiner, multi-resolution stretcher, WSOLA driver and stereo mid/side wrapper were deleted with the old engine at ROADMAP Stage 9.

Functions

bpm_ratio

Returns the stretch ratio needed to change from one BPM to another.

detect_beat_grid

Detects beats and returns a BeatGrid: tracked beat positions, downbeats, and a piecewise-constant tempo model.

detect_beat_grid_buffer

Detects beats in an AudioBuffer and returns a BeatGrid.

detect_beat_grid_with_options

detect_beat_grid with explicit TempoTrackingOptions — narrow the BPM search range, move the octave prior, or add a soft genre hint (the DJ analysis path uses a 100–160 hint).

detect_bpm

Detects the BPM of a mono audio signal.

detect_bpm_buffer

Detects the BPM of an AudioBuffer.

pitch_shift

Shifts the pitch of audio without changing its duration.

pitch_shift_buffer

Shifts the pitch of an AudioBuffer without changing its duration.

pitch_shift_wav_file

Reads a WAV file, pitch-shifts it, and writes the result to another WAV file.

stretch

Stretches audio samples by the given parameters.

stretch_bpm_buffer

Stretches an AudioBuffer from one BPM to another.

stretch_bpm_buffer_auto

Stretches an AudioBuffer to a target BPM, auto-detecting the source BPM.

stretch_buffer

Stretches an AudioBuffer and returns a new AudioBuffer.

stretch_into

Stretches audio samples, appending the result to a caller-provided buffer.

stretch_to_bpm

Stretches audio from one BPM to another.

stretch_to_bpm_auto

Stretches audio to a target BPM, auto-detecting the source BPM.

stretch_to_bpm_auto_wav_file

Reads a WAV file, auto-detects its BPM, stretches to the target BPM, and writes the result.

stretch_to_bpm_wav_file

Reads a WAV file, stretches it from one BPM to another, and writes the result.

stretch_wav_file

Reads a WAV file, stretches it, and writes the result to another WAV file.