whisperpipe 0.1.3

Real-time speech-to-text streaming with OpenAI Whisper

whisperpipe

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

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. If you use whisperpipe in your research, please cite our paper as described in the Citation section.

---

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

pip install whisperpipe

Or for the latest version directly from GitHub:

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

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:

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:

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.

---

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()

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

Authors

Erfan Ramezani
Mohammad Mahdi Giahi

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:

@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:

@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}
}