Skip to content

A wrapper on whisper.cpp with additional helper features like model management capabilities.

License

Notifications You must be signed in to change notification settings

s-emanuilov/whispercpp_kit

Folders and files

NameName
Last commit message
Last commit date
Dec 11, 2024
Jan 8, 2025
Dec 12, 2024
Dec 11, 2024
Jan 7, 2025
Jan 8, 2025
Dec 11, 2024

Repository files navigation

WhisperCPP Kit πŸŽ™οΈ

PyPI version License: MIT

πŸš€ A Python wrapper around whisper.cpp with model management and helper features.

✨ Features

  • πŸ”„ Automatic building and setup of whisper.cpp
  • 🎯 Simple, intuitive Python API
  • πŸ”§ Built-in model management
  • 🚦 Clear error messages and dependency checks
  • 🎡 Automatic audio format conversion
  • 🧡 Multi-threading support
  • 🐳 Docker support
  • 🎯 Support for custom and fine-tuned models
  • ⚑ Cached builds for faster subsequent inference

πŸ“‹ System Requirements

Before installing whispercpp_kit, ensure you have these system-level dependencies:

Required dependencies πŸ› οΈ

  • git
  • cmake
  • ffmpeg
  • make
  • g++/gcc (C++ compiler)
  • Build essentials

Installation commands πŸ“¦

Ubuntu/Debian
sudo apt update
sudo apt install git cmake ffmpeg build-essential
MacOS
brew install git cmake ffmpeg gcc make
CentOS/RHEL
sudo yum update
sudo yum groupinstall "Development Tools"
sudo yum install git cmake ffmpeg gcc-c++ make

⚠️ Windows is currently not supported. Please use WSL (Windows Subsystem for Linux) with Ubuntu.

πŸš€ Quick start

Installation

pip install whispercpp_kit

Basic usage

from whispercpp_kit import WhisperCPP

# Initialize with default model
whisper = WhisperCPP(model_name="tiny.en")

# First-time setup (automatically done on first transcribe)
whisper.setup()

# Transcribe audio
text = whisper.transcribe("audio.mp3")
print(text)

Advanced configuration

# Using standard models
whisper = WhisperCPP(
    model_name="tiny.en",
    num_threads=8,        # Control threads number
    verbose=True,         # Enable verbose output
    cache_dir="./cache"   # Custom cache directory
)

# Using custom or fine-tuned models
whisper = WhisperCPP(model_path="/path/to/your/fine-tuned-model.bin")

# The library caches the built whisper.cpp source code
# This means subsequent runs will be faster as compilation is skipped

🐳 Troubleshooting

Rebuilding whisper.cpp

If you encounter issues with the whisper.cpp binary, you can force a rebuild:

import shutil
from whispercpp_kit import WhisperCPP

whisper = WhisperCPP(model_name="tiny.en")
# Force rebuild of whisper.cpp
shutil.rmtree(whisper.base_path)
whisper.setup()

Common Issues

  1. Binary Deprecation Warning: If you see a warning about the 'main' binary being deprecated, rebuild whisper.cpp using the steps above. The latest version uses 'whisper-cli' instead.

  2. Transcription Failures: Ensure you have all required dependencies installed and sufficient permissions to execute the binary.

  3. Audio Format Issues: The library automatically converts audio files using ffmpeg. Make sure ffmpeg is properly installed if you encounter audio-related errors.

🐳 Docker support

Docker Instructions
git clone https://github.com/s-emanuilov/whispercpp_kit
cd whispercpp_kit/examples/docker

# Build the image
docker build -t whispercpp_kit .

# Run with default model (base.en)
docker run -v $(pwd):/app/audio whispercpp_kit your_audio.mp3

# Using specific model
docker run -v $(pwd):/app/audio whispercpp_kit your_audio.mp3 tiny.en

See examples/docker/README.md for more details.

πŸ“ License

MIT License - feel free to use in your projects!

🀝 Contributing

Contributions are welcome! Feel free to submit issues and pull requests.

About

A wrapper on whisper.cpp with additional helper features like model management capabilities.

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages