Metadata-Version: 2.4
Name: whisperpipe
Version: 0.1.3
Summary: Real-time speech-to-text streaming with OpenAI Whisper
License: MIT
License-File: LICENSE
Keywords: whisper,openai,speech-to-text,stt,asr,automatic speech recognition,real-time,realtime,audio,microphone,transcription,streaming,live transcription
Author: Erfan Ramezani
Author-email: erfanramezany245@gmail.com
Requires-Python: >=3.9,<3.13
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Environment :: Console
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Multimedia :: Sound/Audio :: Capture/Recording
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: openai-whisper (>=20240930)
Requires-Dist: pyaudio (>=0.2.14)
Requires-Dist: pynput (>=1.7.7)
Requires-Dist: sounddevice (>=0.5.2)
Project-URL: Bug Tracker, https://github.com/Erfan-ram/whisperpipe/issues
Project-URL: Changelog, https://github.com/Erfan-ram/whisperpipe/releases
Project-URL: Documentation, https://github.com/Erfan-ram/whisperpipe/blob/main/README.md
Project-URL: Homepage, https://github.com/Erfan-ram/whisperpipe
Project-URL: Repository, https://github.com/Erfan-ram/whisperpipe
Project-URL: Source, https://github.com/Erfan-ram/whisperpipe
Description-Content-Type: text/markdown

# whisperpipe

> Real-time, offline speech-to-text streaming powered by OpenAI Whisper

[![PyPI version](https://img.shields.io/pypi/v/whisperpipe)](https://pypi.org/project/whisperpipe/)
[![Python](https://img.shields.io/pypi/pyversions/whisperpipe)](https://pypi.org/project/whisperpipe/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![arXiv](https://img.shields.io/badge/arXiv-2604.25611-b31b1b.svg)](https://arxiv.org/abs/2604.25611)

**whisperpipe** is a Python library that turns your microphone into a real-time transcription pipeline powered by OpenAI's Whisper model — running entirely on your own machine. No API keys, no cloud services, no subscriptions, and no data ever leaves your device.

whisperpipe uses a dual-buffer architecture with a hybrid Voice Activity Detection (VAD) pipeline to minimize unnecessary inference and keep latency low. It is designed to plug directly into conversational AI systems and any other application that requires real-time speech-to-text: register a callback, start streaming, and every finalized sentence is delivered to your function automatically. Pause and resume control makes it easy to build turn-based interactions where the assistant stops listening while it responds, then picks up exactly where it left off.

> 📖 **Academic Backing:** This repository contains the official implementation of our paper, [**WhisperPipe: A Resource-Efficient Streaming Architecture for Real-Time Automatic Speech Recognition**](https://arxiv.org/abs/2604.25611). If you use **whisperpipe** in your research, please cite our paper as described in the [Citation](#citation) section.

<div align="center">
  <img src="https://github.com/user-attachments/assets/4959804d-da10-4d75-bc06-1ce7e88cd111" alt="whisperpipe architecture" width="70%" />
</div>

---

## Features

- **Real-time transcription** — continuous audio capture and live text output
- **Callback system** — hook any function to receive transcribed text (LLM, logging, UI, etc.)
- **Pause / Resume** — stop listening while your assistant responds, resume on demand
- **Multi-language** — any language supported by Whisper
- **Device selection** — choose which microphone to use
- **Thread-safe** — designed for concurrent use
- **CUDA support** — automatically uses GPU if available

---

## Installation

```bash
pip install whisperpipe
```

Or for the latest version directly from GitHub:

```bash
pip install git+https://github.com/Erfan-ram/whisperpipe.git
```

> **System dependencies:** PyAudio requires PortAudio. On Linux: `sudo apt install portaudio19-dev`, on macOS: `brew install portaudio`.

---

## Quick Start

```python
from whisperpipe import pipeStream
import time

transcriber = pipeStream(model="base", language="en")
transcriber.start_streaming()

print("Listening... Press Ctrl+C to stop")
try:
    while True:
        time.sleep(1)
except KeyboardInterrupt:
    transcriber.stop_streaming()
```

---

## Usage Examples

### With a Callback (LLM Integration)

Register any function to be called each time a sentence is finalized:

```python
from whisperpipe import pipeStream
import time

def my_callback(text):
    print(f"Transcribed: {text}")
    # Send to your LLM, log it, update UI, etc.

transcriber = pipeStream(model="base", language="en")
transcriber.set_def_callback(my_callback)
transcriber.start_streaming()

try:
    while True:
        time.sleep(1)
except KeyboardInterrupt:
    transcriber.stop_streaming()
```

### Turn-based Conversation (Pause / Resume)

Pause listening while your assistant is speaking, then resume:

```python
from whisperpipe import pipeStream
import time

transcriber = pipeStream(model="base", language="en")

def on_speech(text):
    transcriber.pause_streaming()          # Stop listening
    print(f"User: {text}")

    response = f"You said: {text}"         # Replace with your LLM call
    print(f"Assistant: {response}")

    transcriber.resume_streaming()         # Start listening again

transcriber.set_def_callback(on_speech)
transcriber.start_streaming()

try:
    while True:
        time.sleep(1)
except KeyboardInterrupt:
    transcriber.stop_streaming()
```

> For more complete examples including manual control and status checking, see [example_usage.py](example_usage.py).

---

## Model Selection

| Model | Size | Speed | Accuracy | Recommended for |
|-------|------|-------|----------|-----------------|
| `tiny` | 75 MB | Fastest | Low | Testing, prototyping |
| `base` | 145 MB | Fast | Good | General use |
| `small` | 466 MB | Medium | Better | Balanced performance |
| `medium` | 1.5 GB | Slow | High | High accuracy needed |
| `large` | 3 GB | Slowest | Best | Maximum accuracy |

---

## API Reference

### `pipeStream()`

```python
pipeStream(
    model="base",
    language="en",
    finalization_delay=10.0,
    processing_interval=1.0,
    buffer_duration_seconds=5.0,
    debug_mode=False
)
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `model` | str | `"base"` | Whisper model to load |
| `language` | str | `"en"` | Language code (`"en"`, `"fa"`, `"es"`, ...) |
| `finalization_delay` | float | `10.0` | Seconds of silence before finalizing a sentence |
| `processing_interval` | float | `1.0` | How often (seconds) to process buffered audio |
| `buffer_duration_seconds` | float | `5.0` | Audio buffer size in seconds |
| `debug_mode` | bool | `False` | Print internal debug logs |

### Methods

| Method | Description |
|--------|-------------|
| `start_streaming()` | Start microphone capture and transcription |
| `stop_streaming()` | Stop transcription |
| `set_def_callback(fn)` | Register a callback — called with `(text: str)` on each finalized sentence. Pass `None` to clear. |
| `pause_streaming()` | Temporarily pause audio processing |
| `resume_streaming()` | Resume after a pause |
| `is_running()` | Returns `True` if actively running |
| `is_paused()` | Returns `True` if currently paused |
| `input_devices()` | List available microphone devices with their IDs |

---

## Requirements

- Python 3.9 – 3.12
- `openai-whisper`
- `pyaudio`
- `pynput`
- `sounddevice`
- NumPy and PyTorch (installed automatically with Whisper)

---

## License

MIT — see [LICENSE](LICENSE)

## Authors

[**Erfan Ramezani**](mailto:erfanramezany245@gmail.com)  
[**Mohammad Mahdi Giahi**](mailto:giahimahdi@gmail.com)

## Contributing

Pull requests are welcome. For major changes, please open an issue first.

## Citation

If you find this project useful for your research, please consider citing:

```bibtex
@misc{ramezani2026whisperpipe,
  title         = {WhisperPipe: A Resource-Efficient Streaming Architecture for Real-Time Automatic Speech Recognition},
  author        = {Erfan Ramezani and Mohammad Mahdi Giahi and Mohammad Erfan Zarabadipour and Amir Reza Yosefian and Hamid Ghadiri},
  year          = {2026},
  month         = apr,
  publisher     = {arXiv},
  eprint        = {2604.25611},
  archivePrefix = {arXiv},
  primaryClass  = {cs.CL},
  doi           = {10.48550/arXiv.2604.25611},
  url           = {https://doi.org/10.48550/arXiv.2604.25611}
}
```

And the software repository:

```bibtex
@software{whisperpipe_code_2026,
  author       = {Erfan Ramezani and Mohammad Mahdi Giahi},
  title        = {WhisperPipe: Source Code and Implementation},
  month        = apr,
  year         = 2026,
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.19646625},
  url          = {https://doi.org/10.5281/zenodo.19646625}
}
```

