API Reference

This page is generated from the public Python API in rubband.

Configuration

AudioBuffer

Bases: BaseModel

Output audio returned by stretch() and Stretcher.retrieve().

Attributes:

Name	Type	Description
data	object	C-contiguous float32 audio exposed through the Python buffer protocol.

dtype property

dtype: str

Return the public dtype name for this buffer.

frames property

frames: int

Return the number of audio frames.

channels property

channels: int

Return the number of audio channels.

shape property

shape: tuple[int] | tuple[int, int]

Return the audio shape as (frames,) or (frames, channels).

memoryview

memoryview() -> object

Return the underlying zero-copy memoryview.

numpy

numpy() -> object

Return a NumPy view of the audio buffer.

Returns:

Type	Description
object	NumPy array view over the same audio memory.

torch

torch() -> object

Return a PyTorch CPU tensor view of the audio buffer.

Returns:

Type	Description
object	PyTorch tensor view over the same audio memory.

Options

Bases: BaseModel

Rubber Band option flags for constructing a stretcher.

Time and pitch ratios are not options in Rubber Band itself. Pass them to stretch() or to Stretcher as initial_time_ratio and initial_pitch_scale.

Attributes:

Name	Type	Description
preset	PresetOption	Rubber Band preset to apply before explicit option values.
process	ProcessOption	Offline or real-time processing mode.
stretch	StretchOption	Time-stretching algorithm behavior.
transients	TransientsOption	Transient preservation behavior.
detector	DetectorOption	Transient detector tuned for the source material.
phase	PhaseOption	Phase handling behavior.
threading	ThreadingOption	Rubber Band internal threading behavior.
window	WindowOption	Analysis window size.
smoothing	SmoothingOption	Whether Rubber Band smoothing is enabled.
formant	FormantOption	Formant handling while pitch shifting.
pitch	PitchOption	Pitch-shifting quality and consistency preference.
channels	ChannelsOption	Whether channels are processed independently or together.
engine	EngineOption	Rubber Band engine selection.

option_flags property

option_flags: int

Combined Rubber Band option bitmask for the current options.

LiveOptions

Bases: BaseModel

Rubber Band LiveShifter option flags.

Attributes:

Name	Type	Description
preset	LivePresetOption	Rubber Band live preset to apply before explicit option values.
window	LiveWindowOption	Live shifter window size.
formant	LiveFormantOption	Formant handling while pitch shifting.
channels	LiveChannelsOption	Whether channels are processed independently or together.

option_flags property

option_flags: int

Combined Rubber Band LiveShifter option bitmask.

RubberBandMetadata

Bases: BaseModel

Read-only values reported by a configured Rubber Band stretcher.

Attributes:

Name	Type	Description
engine_version	int	Rubber Band engine version.
available	int	Initial available output frame count.
preferred_start_pad	int	Input frames Rubber Band recommends prepending.
start_delay	int	Output frames to discard after start padding.
time_ratio	float	Configured output-to-input duration ratio.
pitch_scale	float	Configured output-to-input pitch ratio.

model_config class-attribute instance-attribute

model_config = ConfigDict(frozen=True)

engine_version class-attribute instance-attribute

engine_version: int = Field(
    description="Rubber Band engine version."
)

available class-attribute instance-attribute

available: int = Field(
    description="Initial available output frame count."
)

preferred_start_pad class-attribute instance-attribute

preferred_start_pad: int = Field(
    description="Input frames Rubber Band recommends prepending before processing."
)

start_delay class-attribute instance-attribute

start_delay: int = Field(
    description="Output frames to discard after start padding."
)

time_ratio class-attribute instance-attribute

time_ratio: float = Field(
    description="Configured output-to-input duration ratio."
)

pitch_scale class-attribute instance-attribute

pitch_scale: float = Field(
    description="Configured output-to-input pitch ratio."
)

Stateful Processing

Stretcher

Bases: BaseModel

Stateful Rubber Band stretcher for offline or real-time processing.

Parameters:

Name	Type	Description	Default
sample_rate	int	Input sample rate in Hz.	required
channels	int	Number of audio channels.	required
options	Options | None	Rubber Band option flags used to construct the stretcher.	None
initial_time_ratio	float	Initial output-to-input duration ratio.	1.0
initial_pitch_scale	float	Initial output-to-input pitch ratio.	1.0
logger	Callable[..., object] | None	Optional callback for Rubber Band debug log messages.	None

study

study(audio: object, final: bool = False) -> None

Analyze audio before offline processing.

Parameters:

Name	Type	Description	Default
audio	object	Contiguous CPU float32 audio with shape (frames,) or (frames, channels).	required
final	bool	Whether this is the last audio block to study.	False

process

process(audio: object, final: bool = False) -> None

Process audio and make output available through retrieve().

Parameters:

Name	Type	Description	Default
audio	object	Contiguous CPU float32 audio with shape (frames,) or (frames, channels).	required
final	bool	Whether this is the last audio block to process.	False

reset

reset() -> None

Reset Rubber Band's internal buffers while retaining current ratios.

set_time_ratio

set_time_ratio(ratio: float) -> None

Set the stretched-to-unstretched duration ratio.

Parameters:

Name	Type	Description	Default
ratio	float	Positive output-to-input duration ratio.	required

set_pitch_scale

set_pitch_scale(scale: float) -> None

Set the target-to-source frequency ratio.

Parameters:

Name	Type	Description	Default
scale	float	Positive output-to-input pitch ratio.	required

set_formant_scale

set_formant_scale(scale: float) -> None

Set Rubber Band's formant scale.

Parameters:

Name	Type	Description	Default
scale	float	Non-negative formant scale.	required

set_transients_option

set_transients_option(option: TransientsOption) -> None

Set transient handling for a real-time stretcher.

Parameters:

Name	Type	Description	Default
option	TransientsOption	Transient preservation behavior.	required

set_detector_option

set_detector_option(option: DetectorOption) -> None

Set transient detector behavior for a real-time stretcher.

Parameters:

Name	Type	Description	Default
option	DetectorOption	Transient detector tuned for the source material.	required

set_phase_option

set_phase_option(option: PhaseOption) -> None

Set phase handling behavior.

Parameters:

Name	Type	Description	Default
option	PhaseOption	Phase handling behavior.	required

set_formant_option

set_formant_option(option: FormantOption) -> None

Set formant handling behavior.

Parameters:

Name	Type	Description	Default
option	FormantOption	Formant handling while pitch shifting.	required

set_pitch_option

set_pitch_option(option: PitchOption) -> None

Set pitch processing behavior for a real-time stretcher.

Parameters:

Name	Type	Description	Default
option	PitchOption	Pitch-shifting quality and consistency preference.	required

get_time_ratio

get_time_ratio() -> float

Return the current stretched-to-unstretched duration ratio.

get_pitch_scale

get_pitch_scale() -> float

Return the current target-to-source pitch ratio.

get_formant_scale

get_formant_scale() -> float

Return the current Rubber Band formant scale.

get_preferred_start_pad

get_preferred_start_pad() -> int

Return the input frames Rubber Band recommends prepending.

get_start_delay

get_start_delay() -> int

Return the output frames to discard after start padding.

get_latency

get_latency() -> int

Return the processing latency in frames.

get_channel_count

get_channel_count() -> int

Return the configured channel count.

set_expected_input_duration

set_expected_input_duration(samples: int) -> None

Set the expected input duration for offline processing.

Parameters:

Name	Type	Description	Default
samples	int	Non-negative expected input frame count.	required

set_max_process_size

set_max_process_size(samples: int) -> None

Set the maximum block size accepted by process().

Parameters:

Name	Type	Description	Default
samples	int	Non-negative maximum input frame count per process call.	required

get_process_size_limit

get_process_size_limit() -> int

Return the current maximum process block size in frames.

get_samples_required

get_samples_required() -> int

Return the input frames required before more output can be produced.

available

available() -> int

Return the number of output frames currently available.

retrieve

retrieve() -> AudioBuffer

Return available output audio.

Returns:

Type	Description
AudioBuffer	AudioBuffer with shape (frames, channels).

get_engine_version

get_engine_version() -> int

Return the active Rubber Band engine version.

set_key_frame_map

set_key_frame_map(key_frames: Mapping[int, int]) -> None

Set a pre-planned offline source-to-target frame mapping.

Parameters:

Name	Type	Description	Default
key_frames	Mapping[int, int]	Mapping from source frame positions to target frame positions.	required

get_frequency_cutoff

get_frequency_cutoff(n: int) -> float

Return Rubber Band's frequency cutoff for the given band index.

Parameters:

Name	Type	Description	Default
n	int	Frequency cutoff index.	required

set_frequency_cutoff

set_frequency_cutoff(n: int, frequency: float) -> None

Set Rubber Band's frequency cutoff for the given band index.

Parameters:

Name	Type	Description	Default
n	int	Frequency cutoff index.	required
frequency	float	Non-negative finite cutoff frequency.	required

get_input_increment

get_input_increment() -> int

Return Rubber Band's internal input increment.

get_output_increments

get_output_increments() -> list[int]

Return accumulated internal output increments.

get_phase_reset_curve

get_phase_reset_curve() -> list[float]

Return accumulated phase reset curve points.

get_exact_time_points

get_exact_time_points() -> list[int]

Return accumulated exact time points.

set_debug_level

set_debug_level(level: int) -> None

Set Rubber Band debug output level for this stretcher.

Parameters:

Name	Type	Description	Default
level	int	Non-negative Rubber Band debug level.	required

set_default_debug_level staticmethod

set_default_debug_level(level: int) -> None

Set the Rubber Band default debug level for future stretchers.

Parameters:

Name	Type	Description	Default
level	int	Non-negative Rubber Band debug level.	required

Live Pitch Shifting

LiveShifter

Bases: BaseModel

Rubber Band 4.x live pitch shifter.

Parameters:

Name	Type	Description	Default
sample_rate	int	Input sample rate in Hz.	required
channels	int	Number of audio channels.	required
options	LiveOptions | None	Rubber Band LiveShifter option flags.	None
logger	Callable[..., object] | None	Optional callback for Rubber Band debug log messages.	None

reset

reset() -> None

Reset internal buffers while retaining current pitch ratio.

set_pitch_scale

set_pitch_scale(scale: float) -> None

Set the target-to-source frequency ratio.

Parameters:

Name	Type	Description	Default
scale	float	Positive output-to-input pitch ratio.	required

set_formant_scale

set_formant_scale(scale: float) -> None

Set Rubber Band's live formant scale.

Parameters:

Name	Type	Description	Default
scale	float	Non-negative formant scale.	required

get_pitch_scale

get_pitch_scale() -> float

Return the current target-to-source pitch ratio.

get_formant_scale

get_formant_scale() -> float

Return the current Rubber Band formant scale.

get_start_delay

get_start_delay() -> int

Return the output frames to discard for time alignment.

get_channel_count

get_channel_count() -> int

Return the configured channel count.

set_formant_option

set_formant_option(option: LiveFormantOption) -> None

Set live formant handling behavior.

Parameters:

Name	Type	Description	Default
option	LiveFormantOption	Live formant handling while pitch shifting.	required

get_block_size

get_block_size() -> int

Return the exact frame count required by each shift() call.

shift

shift(audio: object) -> AudioBuffer

Pitch-shift one fixed-size live audio block.

Parameters:

Name	Type	Description	Default
audio	object	Contiguous CPU float32 audio with exactly get_block_size() frames and the configured channel count.	required

Returns:

Type	Description
AudioBuffer	AudioBuffer with the same shape as the input block.

shift_into

shift_into(audio: object, output: object) -> None

Pitch-shift one live audio block into caller-provided output memory.

Parameters:

Name	Type	Description	Default
audio	object	Contiguous CPU float32 input audio with exactly get_block_size() frames and the configured channel count.	required
output	object	Writable contiguous CPU float32 output audio with matching shape.	required

set_debug_level

set_debug_level(level: int) -> None

Set Rubber Band debug output level for this live shifter.

Parameters:

Name	Type	Description	Default
level	int	Non-negative Rubber Band debug level.	required

set_default_debug_level staticmethod

set_default_debug_level(level: int) -> None

Set the Rubber Band default debug level for future live shifters.

Parameters:

Name	Type	Description	Default
level	int	Non-negative Rubber Band debug level.	required

Convenience Functions

stretch

stretch(
    audio: object,
    sample_rate: int,
    time_ratio: float = 1.0,
    pitch_scale: float = 1.0,
    options: Options | None = None,
) -> AudioBuffer

Stretch and pitch-shift CPU float32 audio in one offline call.

Input must be contiguous CPU float32 audio with shape (frames,) for mono or (frames, channels) for multichannel audio. Objects may expose DLPack or the Python buffer protocol.

Parameters:

Name	Type	Description	Default
audio	object	Contiguous CPU float32 input audio.	required
sample_rate	int	Input sample rate in Hz.	required
time_ratio	float	Output-to-input duration ratio.	1.0
pitch_scale	float	Output-to-input pitch ratio.	1.0
options	Options | None	Rubber Band option flags for the one-shot stretcher.	None

Returns:

Type	Description
AudioBuffer	AudioBuffer containing C-contiguous float32 output.

metadata

metadata(
    sample_rate: int,
    channels: int = 1,
    time_ratio: float = 1.0,
    pitch_scale: float = 1.0,
    options: Options | None = None,
) -> RubberBandMetadata

Return metadata for a Rubber Band stretcher configuration.

Parameters:

Name	Type	Description	Default
sample_rate	int	Input sample rate in Hz.	required
channels	int	Number of audio channels.	1
time_ratio	float	Output-to-input duration ratio.	1.0
pitch_scale	float	Output-to-input pitch ratio.	1.0
options	Options | None	Rubber Band option flags for the metadata query.	None

Returns:

Type	Description
RubberBandMetadata	Read-only metadata for the configured stretcher.

Option Enums

The enum values below map directly to Rubber Band option groups.

PresetOption

Value	Meaning
default	Use explicit option values.
percussive	Apply Rubber Band's percussive preset.

ProcessOption

Value	Meaning
offline	Offline processing. Time and pitch ratios are fixed after study() or process() starts.
real_time	Real-time processing. Time and pitch ratios may change while processing.

StretchOption

Value	Meaning
elastic	Standard Rubber Band elastic stretching.
precise	Prefer precise stretching behavior.

TransientsOption

Value	Meaning
crisp	Preserve transients more sharply.
mixed	Balance transient preservation and smoothing.
smooth	Smooth transients more heavily.

DetectorOption

Value	Meaning
compound	Use Rubber Band's compound transient detector.
percussive	Tune detection for percussive material.
soft	Tune detection for softer material.

PhaseOption

Value	Meaning
laminar	Keep phase behavior more coherent.
independent	Allow channels or components to phase independently.

ThreadingOption

Value	Meaning
auto	Let Rubber Band choose threading behavior.
never	Disable Rubber Band's internal threading.
always	Enable Rubber Band's internal threading.

WindowOption

Value	Meaning
standard	Use the standard analysis window.
short	Use a shorter analysis window.
long	Use a longer analysis window.

SmoothingOption

Value	Meaning
off	Disable Rubber Band's smoothing option.
on	Enable Rubber Band's smoothing option.

FormantOption

Value	Meaning
shifted	Shift formants with pitch.
preserved	Preserve formants while shifting pitch.

PitchOption

Value	Meaning
high_speed	Prefer faster pitch processing.
high_quality	Prefer higher quality pitch processing.
high_consistency	Prefer more consistent pitch processing.

ChannelsOption

Value	Meaning
apart	Process channels separately.
together	Process channels together.

EngineOption

Value	Meaning
faster	Use Rubber Band's faster engine.
finer	Use Rubber Band's finer engine.

LivePresetOption

Value	Meaning
default	Use explicit live option values.

LiveWindowOption

Value	Meaning
short	Use the shortest live shifter window.
medium	Use Rubber Band Live's medium window.

LiveFormantOption

Value	Meaning
shifted	Shift formants with pitch.
preserved	Preserve formants while shifting pitch.

LiveChannelsOption

Value	Meaning
apart	Process live channels separately.
together	Process live channels together.