### Real-time Audio Playback using StreamWriter

Source: https://context7.com/muges/audiotsm/llms.txt

This example demonstrates real-time audio playback of TSM output using StreamWriter and the sounddevice library. It requires installing audiotsm with the 'stream' extra. The snippet shows playing an input WAV file at half speed in real-time.

```python
from audiotsm import phasevocoder
from audiotsm.io.wav import WavReader
from audiotsm.io.stream import StreamWriter

# Play audio at half speed in real-time
with WavReader("input.wav") as reader:
    with StreamWriter(reader.channels, reader.samplerate) as writer:
        tsm = phasevocoder(reader.channels, speed=0.5)
        tsm.run(reader, writer)
```

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

### Create stereo output at 44.1kHz using WavReader and WavWriter

Source: https://context7.com/muges/audiotsm/llms.txt

This example shows how to read a mono WAV file and write a stereo WAV file with a specified samplerate (44.1kHz) after applying time-scale modification with wsola. It highlights setting specific output parameters like channels and samplerate.

```python
from audiotsm import wsola
from audiotsm.io.wav import WavReader, WavWriter

with WavReader("mono_input.wav") as reader:
    with WavWriter("stereo_output.wav", channels=2, samplerate=44100) as writer:
        tsm = wsola(writer.channels, speed=1.5)
        tsm.run(reader, writer)
```

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

### Install AudioTSM with Pip

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/index.md

Installs the AudioTSM library using pip. Optional dependencies for GStreamer plugins or real-time streaming can be included.

```bash
pip install audiotsm
```

```bash
pip install audiotsm[gstreamer]
```

```bash
pip install audiotsm[stream]
```

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

### GStreamer Phase Vocoder Filter Integration (Python)

Source: https://context7.com/muges/audiotsm/llms.txt

Shows how to import and register the audiotsm-phase-vocoder GStreamer plugin and then use it within a GStreamer pipeline for real-time audio processing. This example constructs a basic pipeline, links elements, and dynamically connects pads, demonstrating playback speed control via seek events.

```python
import gi
gi.require_version('Gst', '1.0')
from gi.repository import Gst, GObject
import sys

Gst.init(sys.argv)
import audiotsm.gstreamer.phasevocoder  # Register the plugin

# Create a simple pipeline
pipeline = Gst.Pipeline.new("tsm-pipeline")

# Create elements
source = Gst.ElementFactory.make("filesrc", "source")
decoder = Gst.ElementFactory.make("decodebin", "decoder")
ts = Gst.ElementFactory.make("audiotsm-phase-vocoder", "tsm")
converter = Gst.ElementFactory.make("audioconvert", "converter")
sink = Gst.ElementFactory.make("autoaudiosink", "sink")

source.set_property("location", "input.wav")

# Add elements to pipeline
for element in [source, decoder, ts, converter, sink]:
    pipeline.add(element)

# Link elements
source.link(decoder)
ts.link(converter)
converter.link(sink)

# Connect decoder to ts dynamically
def on_pad_added(element, pad):
    sink_pad = ts.get_static_pad("sink")
    if not sink_pad.is_linked():
        pad.link(sink_pad)

decoder.connect("pad-added", on_pad_added)

# Set playback speed via seek event
pipeline.set_state(Gst.State.PAUSED)
pipeline.get_state(Gst.CLOCK_TIME_NONE)

speed = 0.5
pipeline.seek(speed, Gst.Format.TIME, Gst.SeekFlags.FLUSH,
              Gst.SeekType.SET, 0, Gst.SeekType.NONE, -1)

pipeline.set_state(Gst.State.PLAYING)

# Run main loop
loop = GObject.MainLoop()
loop.run()
```

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

### Change Speed Dynamically with TSM.set_speed

Source: https://context7.com/muges/audiotsm/llms.txt

This example demonstrates how to dynamically change the speed ratio during TSM processing using the TSM.set_speed method. This is useful for applications requiring variable-speed playback. The snippet shows processing audio at normal speed, then changing to half speed for subsequent processing.

```python
from audiotsm import phasevocoder
from audiotsm.io.wav import WavReader, WavWriter

with WavReader("input.wav") as reader:
    with WavWriter("output.wav", reader.channels, reader.samplerate) as writer:
        tsm = phasevocoder(reader.channels, speed=1.0)

        # Process some audio at normal speed, then change
        tsm.read_from(reader)
        tsm.write_to(writer)

        # Change to half speed
        tsm.set_speed(0.5)

        # Continue processing at new speed
        tsm.run(reader, writer)
```

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

### Write to NumPy Arrays using ArrayWriter for TSM

Source: https://context7.com/muges/audiotsm/llms.txt

This example shows how to use ArrayWriter to accumulate TSM output into a NumPy array. The processed audio data is accessible via the `data` property after the `run` method completes. It demonstrates processing a mono signal with wsola and accessing the result.

```python
import numpy as np
from audiotsm import wsola
from audiotsm.io.array import ArrayReader, ArrayWriter

# Generate mono audio signal
samplerate = 44100
t = np.linspace(0, 1.0, samplerate)
mono_audio = np.sin(2 * np.pi * 440 * t).reshape(1, -1).astype(np.float32)

reader = ArrayReader(mono_audio)
writer = ArrayWriter(channels=1)

tsm = wsola(channels=1, speed=2.0)
tsm.run(reader, writer)

# Access the processed audio
processed = writer.data
print(f"Original length: {mono_audio.shape[1]} samples")
print(f"Processed length: {processed.shape[1]} samples")  # ~half as many
```

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

### Configure Synthesis Hop Property

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/gstreamer.md

Sets the synthesis_hop property for the audiotsm-phase-vocoder. Note that this is a write-only attribute that requires a filter setup reset to take effect.

```python
plugin.set_property('synthesis-hop', 256)
```

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

### Instantiate Audiotsm Plugin

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/gstreamer.md

Demonstrates how to initialize the audiotsm-phase-vocoder element using the GStreamer factory pattern.

```python
import gi
gi.require_version('Gst', '1.0')
from gi.repository import Gst

Gst.init(None)
plugin = Gst.ElementFactory.make('audiotsm-phase-vocoder', 'my-plugin')
```

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

### Write WAV file matching input properties using WavReader and WavWriter

Source: https://context7.com/muges/audiotsm/llms.txt

This snippet demonstrates how to read an input WAV file and write an output WAV file with the same properties (channels, samplerate) after applying a time-scale modification using the wsola algorithm. It utilizes context managers for WavReader and WavWriter.

```python
from audiotsm import wsola
from audiotsm.io.wav import WavReader, WavWriter

with WavReader("input.wav") as reader:
    with WavWriter("output.wav", reader.channels, reader.samplerate) as writer:
        tsm = wsola(reader.channels, speed=0.75)
        tsm.run(reader, writer)
```

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

### GStreamer WSOLA Filter Configuration (Python)

Source: https://context7.com/muges/audiotsm/llms.txt

Illustrates how to import and register the audiotsm-wsola GStreamer plugin. It shows the creation of the WSOLA element and the configuration of its specific properties such as frame length, synthesis hop, and tolerance, which are crucial for WSOLA's performance characteristics.

```python
import gi
gi.require_version('Gst', '1.0')
from gi.repository import Gst
import sys

Gst.init(sys.argv)
import audiotsm.gstreamer.wsola  # Register the plugin

# Create WSOLA element
ts = Gst.ElementFactory.make("audiotsm-wsola", "tsm")

# Configure WSOLA-specific properties
ts.set_property("frame-length", 1024)
ts.set_property("synthesis-hop", 512)
ts.set_property("tolerance", 256)

# Use in pipeline (see phase vocoder example for full pipeline setup)
```

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

### Read and Write WAV Files for TSM

Source: https://context7.com/muges/audiotsm/llms.txt

Demonstrates how to use WavReader and WavWriter to process audio files. These classes handle file I/O and provide metadata access for TSM procedures.

```python
from audiotsm import phasevocoder
from audiotsm.io.wav import WavReader, WavWriter

with WavReader("input.wav") as reader:
    # Access audio file properties
    print(f"Channels: {reader.channels}")
    print(f"Sample rate: {reader.samplerate}")
    print(f"Sample width: {reader.samplewidth} bytes")
    print(f"Empty: {reader.empty}")

    # Use with a TSM procedure
    with WavWriter("output.wav", reader.channels, reader.samplerate) as writer:
        tsm = phasevocoder(reader.channels, speed=0.5)
        tsm.run(reader, writer)
```

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

### GStreamer Plugin Initialization

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/gstreamer.md

How to initialize and configure an audiotsm filter within a GStreamer pipeline.

```APIDOC
## GStreamer Plugin Setup

### Description
Initialize an audiotsm filter using Gst.ElementFactory and control playback speed via seek events.

### Usage
1. Import the desired module (e.g., `audiotsm.gstreamer.phasevocoder`).
2. Create the element using `Gst.ElementFactory.make("plugin-name")`.
3. Send a seek event to the pipeline to adjust playback speed.

### Example
```python
import audiotsm.gstreamer.phasevocoder
tsm = Gst.ElementFactory.make("audiotsm-phase-vocoder")

# Adjust speed
speed = 0.5
pipeline.seek(speed, Gst.Format.BYTES, Gst.SeekFlags.FLUSH, Gst.SeekType.NONE, -1, Gst.SeekType.NONE, -1)
```
```

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

### Import audiotsm Gstreamer Module

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/gstreamer.md

Demonstrates how to import a specific audiotsm Gstreamer module for use in a pipeline. This is the initial step before creating the audio filter element.

```python
import audiotsm.gstreamer.phasevocoder
```

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

### GStreamer Plugin Configuration

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/gstreamer.md

Details on how to initialize and configure the audiotsm-phase-vocoder plugin within a GStreamer pipeline.

```APIDOC
## GET/SET GStreamer Plugin Properties

### Description
This section describes the properties available for the audiotsm-phase-vocoder GStreamer element.

### Plugin Name
- **plugin_name**: 'audiotsm-phase-vocoder'
- **Usage**: Used in `Gst.ElementFactory.make` to instantiate the element.

### Synthesis Hop
- **synthesis_hop**: (Integer)
- **Description**: The number of samples between two consecutive synthesis frames.
- **Note**: This is a write-only attribute. Changes will take effect upon the next audio filter setup (typically on the next song).

### Implementation Example
```python
import gi
gi.require_version('Gst', '1.0')
from gi.repository import Gst

Gst.init(None)
# Instantiate the plugin
element = Gst.ElementFactory.make('audiotsm-phase-vocoder', 'vocoder')

# Set the synthesis hop property
element.set_property('synthesis_hop', 256)
```
```

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

### Method: write(buffer)

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/io.md

Writes audio samples from a numpy buffer to the Writer object.

```APIDOC
## write(buffer)

### Description
Writes as many samples from the Writer as possible from the provided buffer and returns the count of samples successfully written.

### Method
N/A (Class Method)

### Endpoint
audiotsm.io.base.Writer.write

### Parameters
#### Path Parameters
- **buffer** (numpy.ndarray) - Required - A matrix of shape (m, n) where m is the number of channels and n is the length of the buffer.

### Response
- **Returns** (int) - The number of samples written. Should equal the buffer length unless the Writer is full.

### Errors
- **ValueError** - Raised if the Writer and the buffer do not have the same number of channels.
```

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

### Execute Complete Processing with TSM.run

Source: https://context7.com/muges/audiotsm/llms.txt

This snippet shows the primary method for processing entire audio files at once using the TSM.run method. It demonstrates processing an input WAV file to an output WAV file using the phasevocoder algorithm with flush=True, indicating that all data is processed in this call.

```python
from audiotsm import phasevocoder
from audiotsm.io.wav import WavReader, WavWriter

with WavReader("input.wav") as reader:
    with WavWriter("output.wav", reader.channels, reader.samplerate) as writer:
        tsm = phasevocoder(reader.channels, speed=0.75)

        # Process entire file at once
        tsm.run(reader, writer, flush=True)

        # flush=False if more data will be added later
        # tsm.run(reader, writer, flush=False)
```

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

### GStreamer OLA Filter Configuration (Python)

Source: https://context7.com/muges/audiotsm/llms.txt

Details the process of importing and registering the audiotsm-ola GStreamer plugin. This snippet focuses on creating the OLA element and setting its configuration properties, specifically frame length and synthesis hop, which are optimized for processing percussive audio signals.

```python
import gi
gi.require_version('Gst', '1.0')
from gi.repository import Gst
import sys

Gst.init(sys.argv)
import audiotsm.gstreamer.ola  # Register the plugin

# Create OLA element
ts = Gst.ElementFactory.make("audiotsm-ola", "tsm")

# Configure OLA properties
ts.set_property("frame-length", 256)
ts.set_property("synthesis-hop", 128)

# Use in pipeline for percussive audio processing
```

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

### Initialize Phase Vocoder TSM

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/tsm.md

Demonstrates how to instantiate a phase vocoder object for time-scale modification. This function configures the number of channels and speed ratio for the audio signal.

```python
import audiotsm

# Initialize a phase vocoder for 2 channels at 1.5x speed
tsm_processor = audiotsm.phasevocoder(channels=2, speed=1.5)
```

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

### CBuffer Class Initialization

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/internalapi.md

Initializes a new circular buffer with a specified number of channels and maximum length.

```APIDOC
## Constructor: CBuffer(channels, max_length)

### Description
Creates a circular buffer instance to store multichannel audio data with a fixed maximum capacity.

### Parameters
#### Path Parameters
- **channels** (int) - Required - The number of audio channels.
- **max_length** (int) - Required - The maximum number of samples per channel.

### Request Example
{
  "channels": 2,
  "max_length": 1024
}
```

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

### WavWriter for Writing WAV Files

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/io.md

The WavWriter class enables writing audio data to WAV files, serving as an output for TSM objects. It requires the filename, number of channels, and samplerate during initialization. The WAV file will be overwritten if it already exists. It also supports usage within a 'with' statement for automatic closing.

```python
class WavWriter(Writer):
    def __init__(self, filename, channels, samplerate):
        # filename: str
        # channels: int
        # samplerate: int
        pass

    def close(self):
        pass
```

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

### Perform WSOLA Time-Scale Modification

Source: https://context7.com/muges/audiotsm/llms.txt

Implements the Waveform Similarity-based Overlap-Add (WSOLA) algorithm. It improves upon basic OLA by shifting analysis frames to minimize discontinuities, making it suitable for general audio signals.

```python
from audiotsm import wsola
from audiotsm.io.wav import WavReader, WavWriter

# Basic WSOLA time-stretching
with WavReader("input.wav") as reader:
    with WavWriter("output.wav", reader.channels, reader.samplerate) as writer:
        tsm = wsola(reader.channels, speed=0.5)
        tsm.run(reader, writer)

# WSOLA with custom tolerance for frame shifting
with WavReader("input.wav") as reader:
    with WavWriter("output.wav", reader.channels, reader.samplerate) as writer:
        tsm = wsola(
            channels=reader.channels,
            speed=0.75,
            frame_length=1024,
            tolerance=512  # Max samples the analysis frame can shift
        )
        tsm.run(reader, writer)
```

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

### WavReader for Reading WAV Files

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/io.md

The WavReader class provides functionality to read audio data from WAV files. It can be used as an input for TSM objects and supports reading samples into a numpy.ndarray buffer. It exposes properties like channels, samplerate, and samplewidth, and requires closing after use.

```python
class WavReader(Reader):
    def __init__(self, filename):
        # filename: str
        pass

    def close(self):
        pass

    def read(self, buffer):
        # buffer: numpy.ndarray
        # Returns: number of samples read
        pass

    def skip(self, n):
        # n: int
        # Returns: number of samples skipped
        pass
```

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

### AudioTSM Utilities

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/internalapi.md

Utility functions and classes for AudioTSM implementation.

```APIDOC
## Circular buffers

### Description
The `audiotsm.utils` module provides utility functions and classes used in the implementation of time-scale modification procedures, including circular buffers.

### Method
GET

### Endpoint
/utils/circular_buffers

### Parameters
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **description** (string) - Information about the circular buffer utilities.

#### Response Example
```json
{
  "description": "Provides efficient circular buffer implementations for audio processing."
}
```
```

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

### WSOLA Gstreamer Plugin Properties

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/gstreamer.md

Details the configurable properties for the WSOLA (Waveform Similarity Overlap-Add) Gstreamer audio filter. These include frame_length, synthesis_hop, and tolerance, which influence the time-scale modification.

```python
tsm.frame_length = 2048 # Example value
tsm.synthesis_hop = 512 # Example value
tsm.tolerance = 128 # Example value
```

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

### Manage TSM State

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/tsm.md

Illustrates how to clear the state of a TSM object to prepare for processing a new audio file or segment.

```python
tsm_object.clear()
```

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

### CBuffer.write_to

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/internalapi.md

Writes ready samples from the CBuffer to a specified writer and returns the count of written samples.

```APIDOC
## write_to(writer)

### Description
Writes as many samples as possible to the provided writer, removes them from the CBuffer, and returns the total number of samples written.

### Parameters
- **writer** (audiotsm.io.base.Writer) - Required - The destination object for the audio samples.

### Response
- **Returns** (int) - The number of samples successfully written.

### Errors
- **ValueError** - Raised if the CBuffer and writer do not share the same number of channels.
```

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

### Python API: Phase Vocoder Time-Scale Modification

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/index.md

Demonstrates basic usage of the AudioTSM Python API to reduce the speed of a WAV file by half using the phase vocoder procedure. It reads from a WAV file and writes to another, applying the time-scale modification.

```python
from audiotsm import phasevocoder
from audiotsm.io.wav import WavReader, WavWriter

with WavReader(input_filename) as reader:
    with WavWriter(output_filename, reader.channels, reader.samplerate) as writer:
        tsm = phasevocoder(reader.channels, speed=0.5)
        tsm.run(reader, writer)
```

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

### audiotsm.utils.windows

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/internalapi.md

Utility functions for applying and generating window functions for digital signal processing.

```APIDOC
## audiotsm.utils.windows.hanning(length)

### Description
Generates a periodic Hanning window, which is optimized for spectral analysis tasks.

### Parameters
- **length** (int) - Required - The number of points in the window.

### Response
- **Returns** (numpy.ndarray) - An array of shape (length,) containing the Hanning window values.
```

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

### audiotsm.io.base.Writer

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/io.md

An abstract base class for writing audio data from a TSM object.

```APIDOC
## Class audiotsm.io.base.Writer

### Description
An abstract class for the output of a `TSM` object.

### Properties
* **channels** (int) - The number of channels of the `Writer`.

### Methods
#### close()
Close the wav file.

#### write(buffer)
Write as many samples from the `Writer` as possible from `buffer`, and returns the number of samples that were written.

* **Parameters:**
  **buffer** (numpy.ndarray) – a matrix of shape (m, n), where m is the number of channels and n is the length of the buffer.
* **Returns:**
  The number of samples that were written.
* **Raises:**
  ValueError – if the `Writer` and the buffer do not have the same number of channels.
```

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

### Run TSM Procedure

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/tsm.md

Shows how to execute a time-scale modification procedure using a reader and writer interface. The run method processes input data and outputs the modified signal.

```python
tsm_object.run(reader, writer, flush=True)
```

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

### CBuffer Arithmetic Operations

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/internalapi.md

Methods for performing element-wise addition and division on the buffer data.

```APIDOC
## Method: add(buffer)

### Description
Adds a numpy array element-wise to the current buffer contents.

### Parameters
- **buffer** (numpy.ndarray) - Required - Matrix of shape (m, n) where m is channels and n is length.

## Method: divide(array)

### Description
Divides each channel of the buffer element-wise by the provided array.

### Parameters
- **array** (numpy.ndarray) - Required - Array of shape (n,).
```

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

### audiotsm.io.base.Reader

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/io.md

An abstract base class for reading audio data into a TSM object.

```APIDOC
## Class audiotsm.io.base.Reader

### Description
An abstract class for the input of a `TSM` object.

### Properties
* **channels** (int) - The number of channels of the `Reader`.
* **empty** (bool) - True if there is no more data to read.

### Methods
#### read(buffer)
Reads as many samples from the `Reader` as possible, writes them to `buffer`, and returns the number of samples that were read.

* **Parameters:**
  **buffer** (numpy.ndarray) – a matrix of shape (m, n), where m is the number of channels and n is the length of the buffer, where the samples will be written.
* **Returns:**
  The number of samples that were read.
* **Raises:**
  ValueError – if the `Reader` and the buffer do not have the same number of channels.

#### skip(n)
Try to skip `n` samples, and returns the number of samples that were actually skipped.
```

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

### StreamWriter for Real-time Audio Playback

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/io.md

The StreamWriter class allows real-time playback of TSM object output. It utilizes sounddevice.OutputStream and can be managed with a 'with' statement. It requires the number of channels and samplerate during initialization.

```python
from audiotsm.io.stream import StreamWriter

# Example usage with a 'with' statement
with StreamWriter(channels=2, samplerate=44100) as writer:
    # Use the writer object here
    pass

# Or manually start and stop
writer = StreamWriter(channels=2, samplerate=44100)
# ... use writer ...
writer.stop()
```

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

### Create Gstreamer TSM Filter Element

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/gstreamer.md

Shows how to create an instance of an audiotsm Gstreamer audio filter using Gst.ElementFactory.make. This filter can then be added to a Gstreamer pipeline.

```python
tsm = Gst.ElementFactory.make("audiotsm-phase-vocoder")
```

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

### WSOLA Plugin Properties

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/gstreamer.md

Configuration properties for the WSOLA (Waveform Similarity Overlap-Add) GStreamer filter.

```APIDOC
## WSOLA Filter (audiotsm-wsola)

### Description
Implements the WSOLA procedure for time-scale modification.

### Properties
- **frame_length** (int) - Write-only: The length of the frames.
- **synthesis_hop** (int) - Write-only: The number of samples between two consecutive synthesis frames.
- **tolerance** (int) - Write-only: The maximum number of samples that the analysis frame can be shifted.

### Plugin Name
`audiotsm-wsola`
```

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

### audiotsm.gstreamer.base.GstTSM

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/internalapi.md

Base class for implementing Gstreamer plugins using TSM objects.

```APIDOC
## class GstTSM

### Description
Base class for creating custom Gstreamer audio filters. Subclasses must implement `create_tsm()` and define `__gstmetadata__` and `plugin_name`.

### Methods
- **register()** - Class method to register the plugin with Gstreamer, allowing instantiation via `Gst.ElementFactory.make(plugin_name)`.
```

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

### Reset TSM State for Batch File Processing (Python)

Source: https://context7.com/muges/audiotsm/llms.txt

Demonstrates how to clear the internal state of a TSM object before processing multiple audio files sequentially. This ensures that each file is processed independently, preventing state leakage between operations. It utilizes WavReader and WavWriter for file input/output.

```python
from audiotsm import wsola
from audiotsm.io.wav import WavReader, WavWriter

# Process multiple files with the same TSM object
ts = wsola(channels=2, speed=0.5)

for filename in ["file1.wav", "file2.wav", "file3.wav"]:
    with WavReader(filename) as reader:
        with WavWriter(f"slow_{filename}", reader.channels, reader.samplerate) as writer:
            ts.clear()  # Reset state for each new file
            ts.run(reader, writer)
```

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

### Phase Vocoder Plugin Properties

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/gstreamer.md

Configuration properties for the Phase Vocoder GStreamer filter.

```APIDOC
## Phase Vocoder Filter (audiotsm-phase-vocoder)

### Description
Implements the phase vocoder procedure for time-scale modification.

### Properties
- **frame_length** (int) - Write-only: The length of the frames.
- **phase_locking** (str) - Write-only: The phase locking strategy.

### Plugin Name
`audiotsm-phase-vocoder`
```

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

### OLA Gstreamer Plugin Properties

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/gstreamer.md

Details the configurable properties for the OLA (Overlap-Add) Gstreamer audio filter. These include frame_length and synthesis_hop, which affect the audio processing quality and performance.

```python
tsm.frame_length = 1024 # Example value
tsm.synthesis_hop = 256 # Example value
```

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

### Abstract Base Class for Audio Writers

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/io.md

The Writer class is an abstract base class for audio output from TSM objects. It defines properties for the number of channels and methods for closing the writer and writing data from a buffer. It raises a ValueError if channel counts mismatch.

```python
from audiotsm.io.base import Writer
import numpy as np

class MyWriter(Writer):
    def __init__(self, channels, samplerate):
        self._channels = channels
        self._samplerate = samplerate

    @property
    def channels(self):
        return self._channels

    def close(self):
        # Implementation to close the writer
        pass

    def write(self, buffer):
        # Implementation to write buffer to output
        # Return number of samples written
        pass
```

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

### Perform Phase Vocoder Time-Scale Modification

Source: https://context7.com/muges/audiotsm/llms.txt

Implements the phase vocoder algorithm to adjust audio speed while preserving phase coherence. This is the recommended default method for high-quality results across various audio types.

```python
from audiotsm import phasevocoder, PhaseLocking
from audiotsm.io.wav import WavReader, WavWriter

# Basic usage: slow down audio to half speed
with WavReader("input.wav") as reader:
    with WavWriter("output.wav", reader.channels, reader.samplerate) as writer:
        tsm = phasevocoder(reader.channels, speed=0.5)
        tsm.run(reader, writer)

# Speed up audio to 1.5x with identity phase locking
with WavReader("input.wav") as reader:
    with WavWriter("output_fast.wav", reader.channels, reader.samplerate) as writer:
        tsm = phasevocoder(
            channels=reader.channels,
            speed=1.5,
            frame_length=2048,
            phase_locking=PhaseLocking.IDENTITY
        )
        tsm.run(reader, writer)

# Disable phase locking for different sound characteristics
with WavReader("input.wav") as reader:
    with WavWriter("output_no_lock.wav", reader.channels, reader.samplerate) as writer:
        tsm = phasevocoder(
            channels=reader.channels,
            speed=0.75,
            phase_locking=PhaseLocking.NONE
        )
        tsm.run(reader, writer)
```

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

### Adjust Playback Speed with Gstreamer Seek Event

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/gstreamer.md

Illustrates how to change the playback speed of an audio stream processed by an audiotsm Gstreamer filter by sending a seek event to the pipeline. The speed parameter controls the playback rate.

```python
speed = 0.5
pipeline.seek(speed, Gst.Format.BYTES, Gst.SeekFlags.FLUSH,
              Gst.SeekType.NONE, -1, Gst.SeekType.NONE, -1)
```

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

### Read from NumPy Arrays using ArrayReader for TSM

Source: https://context7.com/muges/audiotsm/llms.txt

This snippet demonstrates using ArrayReader to process audio data directly from NumPy arrays. The input array shape should be (channels, samples). It shows how to create a test signal, process it with phasevocoder, and retrieve the output as a NumPy array.

```python
import numpy as np
from audiotsm import phasevocoder
from audiotsm.io.array import ArrayReader, ArrayWriter

# Create a test signal (stereo sine wave)
samplerate = 44100
duration = 2.0  # seconds
t = np.linspace(0, duration, int(samplerate * duration))
left_channel = np.sin(2 * np.pi * 440 * t)   # 440 Hz
right_channel = np.sin(2 * np.pi * 880 * t)  # 880 Hz
audio_data = np.vstack([left_channel, right_channel]).astype(np.float32)

# Process with TSM
reader = ArrayReader(audio_data)
writer = ArrayWriter(reader.channels)

tsm = phasevocoder(reader.channels, speed=0.5)
tsm.run(reader, writer)

# Get the processed output as numpy array
output_data = writer.data
print(f"Input shape: {audio_data.shape}")   # (2, 88200)
print(f"Output shape: {output_data.shape}") # (2, ~176400) - twice as long
```

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

### OLA Plugin Properties

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/gstreamer.md

Configuration properties for the OLA (Overlap-Add) GStreamer filter.

```APIDOC
## OLA Filter (audiotsm-ola)

### Description
Implements the OLA procedure for time-scale modification.

### Properties
- **frame_length** (int) - Write-only: The length of the frames.
- **synthesis_hop** (int) - Write-only: The number of samples between two consecutive synthesis frames.

### Plugin Name
`audiotsm-ola`
```

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

### Abstract Base Class for Audio Readers

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/io.md

The Reader class is an abstract base class for audio input in TSM objects. It defines methods for reading audio data into a buffer and skipping samples. It also provides a property to check if the reader is empty.

```python
from audiotsm.io.base import Reader
import numpy as np

class MyReader(Reader):
    def __init__(self, channels, samplerate):
        self._channels = channels
        self._samplerate = samplerate
        self._is_empty = False

    @property
    def channels(self):
        return self._channels

    @property
    def empty(self):
        return self._is_empty

    def read(self, buffer):
        # Implementation to read audio data into buffer
        # Return number of samples read
        pass

    def skip(self, n):
        # Implementation to skip n samples
        # Return number of samples actually skipped
        pass
```

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

### Converter Class Methods

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/internalapi.md

Methods for the Converter base class, used for converting analysis frames to synthesis frames.

```APIDOC
## audiotsm.base.analysis_synthesis.Converter

### Description
A base class for objects implementing the conversion of analysis frames into synthesis frames.

## clear()

### Description
Clears the state of the Converter, making it ready to be used on another signal or part of a signal. It is called by the `clear()` method and the constructor of `AnalysisSynthesisTSM`.

### Method
POST

### Endpoint
/converter/clear

### Parameters
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates that the converter state has been cleared.

#### Response Example
```json
{
  "message": "Converter state cleared."
}
```

## convert_frame(analysis_frame)

### Description
Converts an analysis frame into a synthesis frame.

### Method
POST

### Endpoint
/converter/convert_frame

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **analysis_frame** (numpy.ndarray) - Required - A matrix of shape (`m`, `delta_before + frame_length + delta_after`), with `m` the number of channels, containing the analysis frame and surrounding samples.

### Request Example
```json
{
  "analysis_frame": [[0.1, 0.2, 0.3, 0.4, 0.5], [0.6, 0.7, 0.8, 0.9, 1.0]]
}
```

### Response
#### Success Response (200)
- **synthesis_frame** (numpy.ndarray) - A synthesis frame represented as a numpy array of shape (`m`, `frame_length`).

#### Response Example
```json
{
  "synthesis_frame": [[0.2, 0.3, 0.4], [0.7, 0.8, 0.9]]
}
```

## set_analysis_hop(analysis_hop)

### Description
Changes the value of the analysis hop. This is called by the `set_speed()` method.

### Method
PUT

### Endpoint
/converter/set_analysis_hop

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **analysis_hop** (int) - Required - The new value for the analysis hop.

### Request Example
```json
{
  "analysis_hop": 128
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates that the analysis hop has been successfully set.

#### Response Example
```json
{
  "message": "Analysis hop set to 128."
}
```
```

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

### Perform OLA Time-Scale Modification

Source: https://context7.com/muges/audiotsm/llms.txt

Implements the basic Overlap-Add (OLA) algorithm. This method is specifically optimized for percussive audio signals and may degrade tonal quality in other types of audio.

```python
from audiotsm import ola
from audiotsm.io.wav import WavReader, WavWriter

# OLA for percussive audio (drums, clicks, etc.)
with WavReader("drums.wav") as reader:
    with WavWriter("drums_slow.wav", reader.channels, reader.samplerate) as writer:
        tsm = ola(reader.channels, speed=0.5)
        tsm.run(reader, writer)

# OLA with custom frame parameters
with WavReader("drums.wav") as reader:
    with WavWriter("drums_fast.wav", reader.channels, reader.samplerate) as writer:
        tsm = ola(
            channels=reader.channels,
            speed=2.0,
            frame_length=256,
            synthesis_hop=128
        )
        tsm.run(reader, writer)
```

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

### audiotsm.wsola

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/tsm.md

Initializes a Waveform Similarity-based Overlap-Add (WSOLA) time-scale modification procedure.

```APIDOC
## WSOLA Time-Scale Modification

### Description
Returns a TSM object implementing the WSOLA procedure, which improves upon OLA by allowing slight shifts in analysis frame positions to maintain waveform similarity.

### Method
FUNCTION

### Endpoint
audiotsm.wsola(channels, speed=1.0, frame_length=1024, analysis_hop=None, synthesis_hop=None, tolerance=None)

### Parameters
#### Parameters
- **channels** (int) - Required - The number of channels of the input signal.
- **speed** (float) - Optional - The speed ratio multiplier.
- **frame_length** (int) - Optional - The length of the frames.
- **analysis_hop** (int) - Optional - Number of samples between analysis frames.
- **synthesis_hop** (int) - Optional - Number of samples between synthesis frames.
- **tolerance** (int) - Optional - Maximum number of samples for frame shifting.

### Response
Returns a TSM object.
```

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

### TSM Base Class Methods

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/internalapi.md

Methods for Time-Scale Modification (TSM) base class, handling sample writing and reading.

```APIDOC
## flush_to(writer)

### Description
Writes as many output samples as possible to `writer`, assuming that there are no remaining samples that will be added to the input. Returns the number of samples that were written.

### Method
POST

### Endpoint
/tsm/flush_to

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **writer** (audiotsm.io.base.Writer) - Required - The writer object to which samples will be written.

### Request Example
```json
{
  "writer": "<writer_object_representation>"
}
```

### Response
#### Success Response (200)
- **n** (int) - The number of samples that were written to `writer`.
- **finished** (bool) - True when there are no samples remaining to flush.

#### Response Example
```json
{
  "n": 1024,
  "finished": false
}
```

## get_max_output_length(input_length)

### Description
Returns the maximum number of samples that will be written to the output given the number of samples of the input.

### Method
GET

### Endpoint
/tsm/get_max_output_length

### Parameters
#### Path Parameters
None

#### Query Parameters
- **input_length** (int) - Required - The number of samples of the input.

### Request Example
```json
{
  "input_length": 2048
}
```

### Response
#### Success Response (200)
- **max_length** (int) - The maximum number of samples that will be written to the output.

#### Response Example
```json
{
  "max_length": 4096
}
```

## read_from(reader)

### Description
Reads as many samples as possible from `reader`, processes them, and returns the number of samples that were read.

### Method
POST

### Endpoint
/tsm/read_from

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **reader** (audiotsm.io.base.Reader) - Required - The reader object from which samples will be read.

### Request Example
```json
{
  "reader": "<reader_object_representation>"
}
```

### Response
#### Success Response (200)
- **samples_read** (int) - The number of samples that were read from `reader`.

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

## set_speed(speed)

### Description
Sets the speed ratio for the time-scale modification.

### Method
PUT

### Endpoint
/tsm/set_speed

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **speed** (float) - Required - The speed ratio by which the speed of the signal will be multiplied.

### Request Example
```json
{
  "speed": 0.5
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates that the speed has been successfully set.

#### Response Example
```json
{
  "message": "Speed set to 0.5"
}
```

## write_to(writer)

### Description
Writes as many result samples as possible to `writer`. Returns a tuple indicating the number of samples written and whether the process is finished.

### Method
POST

### Endpoint
/tsm/write_to

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **writer** (audiotsm.io.base.Writer) - Required - The writer object to which samples will be written.

### Request Example
```json
{
  "writer": "<writer_object_representation>"
}
```

### Response
#### Success Response (200)
- **n** (int) - The number of samples that were written to `writer`.
- **finished** (bool) - True when there are no samples remaining to write.

#### Response Example
```json
{
  "n": 1024,
  "finished": false
}
```
```

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

### Phase Vocoder Gstreamer Plugin Properties

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/gstreamer.md

Details the configurable properties for the Phase Vocoder Gstreamer audio filter. Key properties include frame_length and phase_locking, which are crucial for achieving desired time-scale modification effects.

```python
tsm.frame_length = 1024 # Example value
tsm.phase_locking = True # Example value
```

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

### CBuffer Data Access

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/internalapi.md

Methods for reading and peeking at the data stored in the circular buffer.

```APIDOC
## Method: peek(buffer)

### Description
Reads samples from the buffer without removing them. Only samples marked as 'ready' are returned.

### Parameters
- **buffer** (numpy.ndarray) - Required - Destination matrix for the read samples.

### Response
- **read_count** (int) - The number of samples successfully read from the buffer.
```

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

### audiotsm.io.stream.StreamWriter

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/io.md

A StreamWriter allows playing the output of a TSM object in real-time. It can be used with a 'with' statement or stopped manually.

```APIDOC
## Class audiotsm.io.stream.StreamWriter

### Description
A `Writer` allowing to play the output of a `TSM` object directly.

You should stop the `StreamWriter` after using it with the `stop()` method, or use it in a `with` statement.

### Parameters
* **channels** (int) - The number of channels of the signal.
* **samplerate** (int) - The sampling rate of the signal.
* **attrs** - Additional parameters used to create the `sounddevice.OutputStream`.

### Methods
#### stop()
Stop the stream.

#### write(buffer)
Write as many samples from the `Writer` as possible from `buffer`, and returns the number of samples that were written.

* **Parameters:**
  **buffer** (numpy.ndarray) – a matrix of shape (m, n), where m is the number of channels and n is the length of the buffer.
* **Returns:**
  The number of samples that were written.
* **Raises:**
  ValueError – if the `Writer` and the buffer do not have the same number of channels.
```

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

### Write to Pre-allocated NumPy Arrays using FixedArrayWriter

Source: https://context7.com/muges/audiotsm/llms.txt

This snippet illustrates using FixedArrayWriter to write TSM output into a pre-allocated NumPy array. This is useful when the output size is known or can be estimated in advance, providing memory efficiency. It shows processing with phasevocoder and writing to a fixed buffer.

```python
import numpy as np
from audiotsm import phasevocoder
from audiotsm.io.array import ArrayReader, FixedArrayWriter

# Input audio
input_data = np.random.randn(2, 44100).astype(np.float32)  # 1 second stereo

# Pre-allocate output buffer (estimate size based on speed)
speed = 0.5
estimated_output_length = int(input_data.shape[1] / speed * 1.1)  # 10% margin
output_buffer = np.zeros((2, estimated_output_length), dtype=np.float32)

reader = ArrayReader(input_data)
writer = FixedArrayWriter(output_buffer)

tsm = phasevocoder(channels=2, speed=speed)
tsm.run(reader, writer)

# output_buffer now contains the processed audio
```

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

### audiotsm.ola

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/tsm.md

Initializes an Overlap-Add (OLA) time-scale modification procedure.

```APIDOC
## OLA Time-Scale Modification

### Description
Returns a TSM object implementing the OLA (Overlap-Add) time-scale modification procedure, recommended for percussive audio signals.

### Method
FUNCTION

### Endpoint
audiotsm.ola(channels, speed=1.0, frame_length=256, analysis_hop=None, synthesis_hop=None)

### Parameters
#### Parameters
- **channels** (int) - Required - The number of channels of the input signal.
- **speed** (float) - Optional - The speed ratio multiplier.
- **frame_length** (int) - Optional - The length of the frames.
- **analysis_hop** (int) - Optional - Number of samples between analysis frames.
- **synthesis_hop** (int) - Optional - Number of samples between synthesis frames.

### Response
Returns a TSM object.
```

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

### audiotsm.io.array.ArrayWriter

Source: https://github.com/muges/audiotsm/blob/master/docs/sphinx/io.md

A Writer that allows obtaining the output of a TSM object as a numpy.ndarray.

```APIDOC
## Class: audiotsm.io.array.ArrayWriter

### Description
A `Writer` allowing to get the output of a `TSM` object as a `numpy.ndarray`.
Writing to an `ArrayWriter` will append the data to the `data` attribute.

### Parameters
* **channels** (`int`) - Required - The number of channels of the signal.

### Properties
* **channels** (`int`) - The number of channels of the `Writer`.
* **data** (`numpy.ndarray`) - A matrix of shape (m, n), where m is the number of channels and n is the length of the data, to which samples have been written.

### Methods
#### write(buffer)
Writes as many samples as possible from `buffer` to the `Writer` and returns the number of samples written.

* **Parameters:**
  * **buffer** (`numpy.ndarray`) - A matrix of shape (m, n), where m is the number of channels and n is the length of the buffer, from which samples will be read.
* **Returns:**
  The number of samples written. This should always equal the length of the buffer, except when there is no more space in the `Writer`.
* **Raises:**
  * **ValueError** - If the `Writer` and the buffer do not have the same number of channels.
```