ssstretch

https://docs.rs/ssstretch/0.1.0/ssstretch/
Admin
ssstretch is a Rust crate providing idiomatic bindings for the Signalsmith Stretch C++ library,...
Tokens:3,966
Snippets:24
Trust Score:9.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### Initialize and process audio with Stretch

Source: https://docs.rs/ssstretch/0.1.0/ssstretch/struct.Stretch.html

Demonstrates creating a Stretch instance, configuring it with default presets, applying a pitch shift, and processing audio buffers.

```rust
3fn main() {
4    // Create a simple input buffer with two channels of a sine wave
5    let sample_rate = 44100.0;
6    let frequency = 440.0; // A4 note
7    let duration_seconds = 2.0;
8    let sample_count = (sample_rate * duration_seconds) as usize;
9    
10    // Generate two channels of audio
11    let mut input = vec![vec![0.0f32; sample_count], vec![0.0f32; sample_count]];
12    for i in 0..sample_count {
13        let t = i as f32 / sample_rate;
14        let value = (t * frequency * 2.0 * std::f32::consts::PI).sin();
15        
16        // Channel 1 - original sine wave
17        input[0][i] = value;
18        
19        // Channel 2 - phase-shifted version
20        input[1][i] = ((t + 0.25) * frequency * 2.0 * std::f32::consts::PI).sin();
21    }
22    
23    // Create a Stretch instance with 2 channels
24    let mut stretch = Stretch::new();
25    stretch.preset_default(2, sample_rate as f32);
26    
27    // Set pitch shift of 1 octave up (12 semitones)
28    stretch.set_transpose_semitones(12.0, None);
29    
30    // Create output buffer that's half the length (2x speed)
31    let output_samples = sample_count / 2;
32    let mut output = vec![vec![0.0f32; output_samples], vec![0.0f32; output_samples]];
33    
34    // Process audio
35    println!("Processing {} input samples into {} output samples...", sample_count, output_samples);
36    
37    stretch.process_vec(
38        &input,
39        sample_count as i32,
40        &mut output,
41        output_samples as i32,
42    );
43    
44    // We'd normally write this to a file or audio device
45    // For this example, we'll just report some statistics
46    
47    println!("Processing complete!");
48    println!("Input amplitude: {:.4}", input[0].iter().map(|x| x.abs()).fold(0.0f32, |a, b| a.max(b)));
49    println!("Output amplitude: {:.4}", output[0].iter().map(|x| x.abs()).fold(0.0f32, |a, b| a.max(b)));
50    let latency = stretch.input_latency() as usize;
51    println!("Input latency: {} samples", latency);
52    println!("Output latency: {} samples", stretch.output_latency());
53    println!("First few samples of output channel 1: {:?}", &output[0][0..10]);
54    println!("Samples after latency: {:?}", &output[0][latency.min(output[0].len() - 1)..latency.min(output[0].len()) + 10.min(output[0].len() - latency)]);
55}
```

--------------------------------

### Configuration Methods

Source: https://docs.rs/ssstretch/0.1.0/ssstretch/struct.Stretch.html

Methods for initializing and configuring the audio stretcher instance.

```APIDOC
## preset_cheaper

### Description
Configure the stretcher with cheaper presets based on sample rate, which is less CPU intensive.

### Parameters
- **channels** (i32) - Required - Number of audio channels.
- **sample_rate** (f32) - Required - The sample rate of the audio.

## configure

### Description
Manually configure the stretcher with specific block and interval settings.

### Parameters
- **channels** (i32) - Required - Number of audio channels.
- **block_samples** (i32) - Required - The block size in samples.
- **interval_samples** (i32) - Required - The interval size in samples.
```

--------------------------------

### Seek Audio (Raw Pointers)

Source: https://docs.rs/ssstretch/0.1.0/ssstretch/struct.Stretch.html

Provides previous input ('pre-roll') without affecting speed calculation, using raw pointers. This is an unsafe operation.

```APIDOC
## POST /api/stretch/seek

### Description
Provides previous input ('pre-roll') without affecting speed calculation, using raw pointers. This method is unsafe.

### Method
POST

### Endpoint
/api/stretch/seek

### Parameters
#### Request Body
- **inputs** (array of pointers to f32) - Required - Pointers to input channel data.
- **input_samples** (i32) - Required - The number of samples per input channel.
- **playback_rate** (f64) - Required - The playback rate.

### Safety
This method is unsafe. The caller must ensure that `inputs` points to a valid array of channel pointers, and that each channel has sufficient allocated memory for `input_samples`.

### Response
#### Success Response (200)
- **status** (string) - Indicates success.

#### Response Example
{
  "status": "success"
}
```

--------------------------------

### Stretch Struct Initialization

Source: https://docs.rs/ssstretch/0.1.0/ssstretch/struct.Stretch.html

Methods for creating and initializing the Stretch struct.

```APIDOC
## Stretch Struct

Main struct for time-stretching and pitch-shifting audio. This struct wraps the C++ SignalsmithStretch class and provides an idiomatic Rust interface.

### `Stretch::new()`

Create a new Stretch instance with default parameters.

### `Stretch::with_seed(seed: i64)`

Create a new Stretch instance with a specified random seed.

### `Stretch::reset()`

Reset the instance to its initial state.

### `Stretch::preset_default(channels: i32, sample_rate: f32)`

Configure with default presets based on sample rate.
```

--------------------------------

### Status and Latency Methods

Source: https://docs.rs/ssstretch/0.1.0/ssstretch/struct.Stretch.html

Methods to retrieve current configuration and latency information from the stretcher.

```APIDOC
## channels

### Description
Get the number of channels currently configured.

### Response
- **return** (i32) - Number of channels.

## block_samples

### Description
Get the block size in samples.

### Response
- **return** (i32) - Block size in samples.

## interval_samples

### Description
Get the interval size in samples.

### Response
- **return** (i32) - Interval size in samples.

## input_latency

### Description
Get the input latency in samples.

### Response
- **return** (i32) - Input latency in samples.
```

--------------------------------

### Process Audio (Raw Pointers)

Source: https://docs.rs/ssstretch/0.1.0/ssstretch/struct.Stretch.html

Processes audio data using raw pointers for input and output channels. This is an unsafe operation.

```APIDOC
## POST /api/stretch/process

### Description
Processes audio data, stretching time and/or shifting pitch using raw pointers. This method is unsafe.

### Method
POST

### Endpoint
/api/stretch/process

### Parameters
#### Request Body
- **inputs** (array of pointers to f32) - Required - Pointers to input channel data.
- **input_samples** (i32) - Required - The number of samples per input channel.
- **outputs** (array of mutable pointers to f32) - Required - Pointers to output channel buffers.
- **output_samples** (i32) - Required - The number of samples per output channel.

### Safety
This method is unsafe. The caller must ensure that `inputs` and `outputs` point to valid, correctly sized arrays of channel pointers, and that each channel has sufficient allocated memory.

### Response
#### Success Response (200)
- **status** (string) - Indicates success.

#### Response Example
{
  "status": "success"
}
```

--------------------------------

### Flush Audio (Raw Pointers)

Source: https://docs.rs/ssstretch/0.1.0/ssstretch/struct.Stretch.html

Flushes any remaining output data using raw pointers. This is an unsafe operation.

```APIDOC
## POST /api/stretch/flush

### Description
Flushes any remaining output data using raw pointers. This method is unsafe.

### Method
POST

### Endpoint
/api/stretch/flush

### Parameters
#### Request Body
- **outputs** (array of mutable pointers to f32) - Required - Pointers to output channel buffers.
- **output_samples** (i32) - Required - The number of samples per output channel.

### Safety
This method is unsafe. The caller must ensure that `outputs` points to a valid array of channel pointers, and that each output channel has sufficient allocated memory for `output_samples`.

### Response
#### Success Response (200)
- **status** (string) - Indicates success.

#### Response Example
{
  "status": "success"
}
```

--------------------------------

### Process Audio Data with Raw Pointers

Source: https://docs.rs/ssstretch/0.1.0/ssstretch/struct.Stretch.html

Processes audio data using raw pointers for input and output buffers. This method is unsafe and requires careful management of memory and buffer sizes.

```rust
stretch.process(
    &input,
    sample_count as i32,
    &mut output,
    output_samples as i32,
);
```

--------------------------------

### Generate Sine Wave Audio Buffer

Source: https://docs.rs/ssstretch/0.1.0/ssstretch/struct.Stretch.html

Creates a stereo audio buffer containing sine waves for testing audio processing functions. It generates two channels, one with a direct sine wave and another phase-shifted.

```rust
fn main() {
    // Create a simple input buffer with two channels of a sine wave
    let sample_rate = 44100.0;
    let frequency = 440.0; // A4 note
    let duration_seconds = 2.0;
    let sample_count = (sample_rate * duration_seconds) as usize;
    
    // Generate two channels of audio
    let mut input = vec![vec![0.0f32; sample_count], vec![0.0f32; sample_count]];
    for i in 0..sample_count {
        let t = i as f32 / sample_rate;
        let value = (t * frequency * 2.0 * std::f32::consts::PI).sin();
        
        // Channel 1 - original sine wave
        input[0][i] = value;
        
        // Channel 2 - phase-shifted version
        input[1][i] = ((t + 0.25) * frequency * 2.0 * std::f32::consts::PI).sin();
    }
    
    // Create a Stretch instance with 2 channels
    let mut stretch = Stretch::new();
    stretch.preset_default(2, sample_rate as f32);
    
    // Set pitch shift of 1 octave up (12 semitones)
    stretch.set_transpose_semitones(12.0, None);
    
    // Create output buffer that's half the length (2x speed)
    let output_samples = sample_count / 2;
    let mut output = vec![vec![0.0f32; output_samples], vec![0.0f32; output_samples]];
    
    // Process audio
    println!("Processing {} input samples into {} output samples...", sample_count, output_samples);
    
    stretch.process_vec(
        &input,
        sample_count as i32,
        &mut output,
        output_samples as i32,
    );
    
    // We'd normally write this to a file or audio device
    // For this example, we'll just report some statistics
    
    println!("Processing complete!");
    println!("Input amplitude: {:.4}", input[0].iter().map(|x| x.abs()).fold(0.0f32, |a, b| a.max(b)));
    println!("Output amplitude: {:.4}", output[0].iter().map(|x| x.abs()).fold(0.0f32, |a, b| a.max(b)));
    let latency = stretch.input_latency() as usize;
    println!("Input latency: {} samples", latency);
    println!("Output latency: {} samples", stretch.output_latency());
    println!("First few samples of output channel 1: {:?}", &output[0][0..10]);
    println!("Samples after latency: {:?}", &output[0][latency.min(output[0].len() - 1)..latency.min(output[0].len()) + 10.min(output[0].len() - latency)]);
}
```

--------------------------------

### Process Audio Data with Vec<Vec> Format

Source: https://docs.rs/ssstretch/0.1.0/ssstretch/struct.Stretch.html

Processes audio data using a Vec<Vec<f32>> format, where each inner Vec represents an audio channel. The time stretch ratio is determined by the ratio of input_samples to output_samples.

```rust
stretch.process_vec(
    &input,
    sample_count as i32,
    &mut output,
    output_samples as i32,
);
```

--------------------------------

### Process Audio (Vec<Vec>)

Source: https://docs.rs/ssstretch/0.1.0/ssstretch/struct.Stretch.html

Processes audio data where each channel is represented by a `Vec<f32>`. The time stretch ratio is determined by the ratio of input to output samples.

```APIDOC
## POST /api/stretch/process_vec

### Description
Processes audio data using `Vec<Vec<f32>>` format. The time stretch ratio is determined by the ratio of `input_samples` to `output_samples`.

### Method
POST

### Endpoint
/api/stretch/process_vec

### Parameters
#### Request Body
- **inputs** (array of Vec<f32>) - Required - Input audio data, where each inner Vec is a channel.
- **input_samples** (i32) - Required - The number of samples per input channel.
- **outputs** (array of mutable Vec<f32>) - Required - Output audio data buffers, where each inner Vec is a channel.
- **output_samples** (i32) - Required - The number of samples per output channel.

### Request Example
{
  "inputs": [
    [0.1, 0.2, 0.3],
    [0.4, 0.5, 0.6]
  ],
  "input_samples": 3,
  "outputs": [
    [],
    []
  ],
  "output_samples": 3
}

### Response
#### Success Response (200)
- **status** (string) - Indicates success.

#### Response Example
{
  "status": "success"
}
```

--------------------------------

### Stretch Struct

Source: https://docs.rs/ssstretch

The primary interface for performing time-stretching and pitch-shifting operations on audio data.

```APIDOC
## Struct: Stretch

### Description
Main struct for time-stretching and pitch-shifting audio. This struct serves as the primary entry point for interacting with the underlying Signalsmith Stretch C++ library functionality within Rust.
```

--------------------------------

### Seek in Audio Input

Source: https://docs.rs/ssstretch/0.1.0/ssstretch/struct.Stretch.html

Provides previous input data (pre-roll) without affecting the speed calculation. This method is unsafe and shares the same safety requirements as the `process` method.

```rust
stretch.seek(
    &input,
    input_samples as i32,
    playback_rate: f64,
);
```

--------------------------------

### Stretch Output Latency

Source: https://docs.rs/ssstretch/0.1.0/ssstretch/struct.Stretch.html

Retrieves the output latency of the Stretch audio processor in samples.

```APIDOC
## GET /stretch/output_latency

### Description
Gets the output latency in samples.

### Method
GET

### Endpoint
/stretch/output_latency

### Response
#### Success Response (200)
- **latency** (i32) - The output latency in samples.

#### Response Example
```json
{
  "latency": 1024
}
```
```

--------------------------------

### Flush Remaining Audio Output

Source: https://docs.rs/ssstretch/0.1.0/ssstretch/struct.Stretch.html

Flushes any remaining audio data from the output buffer. This method is unsafe and has the same safety requirements as the `process` method for the output buffers.

```rust
stretch.flush(
    &mut output,
    output_samples as i32,
);
```

--------------------------------

### Stretch Input Latency

Source: https://docs.rs/ssstretch/0.1.0/ssstretch/struct.Stretch.html

Retrieves the input latency of the Stretch audio processor in samples.

```APIDOC
## GET /stretch/input_latency

### Description
Gets the input latency in samples.

### Method
GET

### Endpoint
/stretch/input_latency

### Response
#### Success Response (200)
- **latency** (i32) - The input latency in samples.

#### Response Example
```json
{
  "latency": 512
}
```
```

--------------------------------

### Set Transpose Semitones

Source: https://docs.rs/ssstretch/0.1.0/ssstretch/struct.Stretch.html

Sets the frequency shift in semitones and an optional tonality limit.

```APIDOC
## POST /api/stretch/transpose_semitones

### Description
Sets the frequency shift in semitones and an optional tonality limit.

### Method
POST

### Endpoint
/api/stretch/transpose_semitones

### Parameters
#### Request Body
- **semitones** (f32) - Required - The frequency shift in semitones.
- **tonality_limit** (Option<f32>) - Optional - The tonality limit.

### Request Example
{
  "semitones": 12.0,
  "tonality_limit": null
}

### Response
#### Success Response (200)
- **status** (string) - Indicates success.

#### Response Example
{
  "status": "success"
}
```

--------------------------------

### flush_vec

Source: https://docs.rs/ssstretch/0.1.0/ssstretch/struct.Stretch.html

Flushes the remaining audio samples from the processing buffer into the provided output vectors.

```APIDOC
## flush_vec

### Description
Flushes the internal buffers of the Stretch instance into the provided output vectors.

### Parameters
- **outputs** (&mut [Vec<f32>]) - Required - The output audio buffers to receive flushed samples.
- **output_samples** (i32) - Required - The number of samples to flush.
```

--------------------------------

### seek_vec

Source: https://docs.rs/ssstretch/0.1.0/ssstretch/struct.Stretch.html

Performs a seek operation on the audio stream using a vector-based input format.

```APIDOC
## seek_vec

### Description
Seek within the audio stream using the Vec<Vec<f32>> format.

### Parameters
- **inputs** (&[Vec<f32>]) - Required - The input audio buffers.
- **input_samples** (i32) - Required - The number of samples to process.
- **playback_rate** (f64) - Required - The target playback rate for the seek operation.
```

--------------------------------

### Set Transpose Factor

Source: https://docs.rs/ssstretch/0.1.0/ssstretch/struct.Stretch.html

Sets the frequency multiplier and an optional tonality limit for pitch shifting.

```APIDOC
## POST /api/stretch/transpose_factor

### Description
Sets the frequency multiplier and an optional tonality limit.

### Method
POST

### Endpoint
/api/stretch/transpose_factor

### Parameters
#### Request Body
- **multiplier** (f32) - Required - The frequency multiplier.
- **tonality_limit** (Option<f32>) - Optional - The tonality limit.

### Request Example
{
  "multiplier": 1.5,
  "tonality_limit": 0.8
}

### Response
#### Success Response (200)
- **status** (string) - Indicates success.

#### Response Example
{
  "status": "success"
}
```
Tokens:
Raw