Metadata-Version: 2.4
Name: wavesurfer
Version: 0.3.2
Summary: TorchAudio Forced Aligner
Author-email: Zhendong Peng <pzd17@tsinghua.org.cn>
License-Expression: MIT
Project-URL: Homepage, https://github.com/pengzhendong/wavesurfer
Project-URL: Documentation, https://github.com/pengzhendong/wavesurfer#readme
Project-URL: BugTracker, https://github.com/pengzhendong/wavesurfer/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: audiolab
Requires-Dist: jinja2
Requires-Dist: lhotse
Dynamic: license-file

# wavesurfer

[![PyPI](https://img.shields.io/pypi/v/wavesurfer)](https://pypi.org/project/wavesurfer/)
[![License](https://img.shields.io/github/license/pengzhendong/wavesurfer)](LICENSE)

A Python package for audio visualization and playback in Jupyter notebooks.

## Features

- Visualize audio waveforms in Jupyter notebooks
- Support for various audio formats (WAV, MP3, FLAC, etc.)
- Streaming audio playback for real-time applications
- Programmatic control with play/pause functionality
- Performance monitoring with latency and RTF metrics

## Installation

```bash
pip install wavesurfer
```

## Usage

### Basic Playback

Play a wave file directly:

```python
from wavesurfer import play

play("assets/test_16k.wav")
```

![](assets/test_16k.png)

Play waveform data:

```python
from audiolab import load_audio
from wavesurfer import play

audio, rate = load_audio("assets/test_16k.wav")
play(audio, rate)
```

### Streaming Playback

Play streaming waveform data:

```python
import time
from audiolab import load_audio
from wavesurfer import play

def audio_generator():
    for frame, rate in load_audio("assets/test_16k.wav", frame_size_ms=300):
        time.sleep(0.1)  # RTF: 0.1 / 0.3 < 1
        yield frame

play(audio_generator(), 16000)
```

### Programmatic Control

For more advanced usage, you can use the `Player` class directly to have programmatic control over playback:

```python
from wavesurfer import Player

# Create a player instance
player = Player()

# Load audio
player.load("assets/test_16k.wav")

# Programmatically control playback
player.play()   # Start playback
player.pause()  # Pause playback
```

The `Player` class also supports all the audio formats that the `play` function supports, including file paths, waveform data, and streaming generators.

## License

[BSD 2-Clause License](LICENSE)
