Sonus

Transform your EPUB books into audiobooks with AI-powered text-to-speech

Features • Installation • Quick Start • GUI App • CLI Usage • Documentation

---

📖 About

Sonus converts EPUB books into high-quality spoken audio using Microsoft's VibeVoice Realtime TTS. Choose between a command-line interface for batch processing or a user-friendly desktop GUI with drag-and-drop support.

✨ Features

• 🎙️ High-Quality TTS - Powered by VibeVoice Realtime 0.5B model
• 🖥️ Dual Interface - CLI for automation, GUI for ease of use
• 🎨 Multiple Voices - Carter, Emma, Davis, Frank, Grace, Mike, and more (English, French, German)
• ⚡ GPU Accelerated - CUDA and MPS support for faster generation
• 🎯 Text Selection - Convert only specific sections of your book
• 🔧 Customizable - Adjust DDPM steps, CFG scale, bitrate, and more
• 💾 MP3 Export - Automatic conversion with WAV fallback
• 📊 Progress Tracking - Real-time status updates and time estimates

---

🚀 Quick Start

# 1. Clone the repository
git clone https://github.com/nsbgg/sonus.git
cd sonus

# 2. Install dependencies
pip install -e ./VibeVoice[streamingtts]
pip install pydub torch transformers tkinterdnd2

# 3. Run the GUI
python sonus_gui.py

# OR use the CLI
python epub_to_mp3.py yourbook.epub --output audiobook.mp3

---

📦 Installation

Prerequisites

• Python 3.9 or higher
• PyTorch 2.0+ with CUDA support (optional, for GPU acceleration)
• ffmpeg (optional, for MP3 conversion)

Step 1: Install Core Dependencies

# Install VibeVoice TTS engine
pip install -e ./VibeVoice[streamingtts]

# Install additional dependencies
pip install pydub torch transformers

Step 2: Install GPU Support (Recommended)

For NVIDIA GPUs (CUDA):

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

For Apple Silicon (MPS):

pip install torch torchvision torchaudio

Step 3: Install GUI Dependencies (Optional)

pip install tkinterdnd2

Step 4: Install ffmpeg (Optional, for MP3)

Windows (Chocolatey):

choco install ffmpeg -y

Windows (winget):

winget install --id=Gyan.FFmpeg -e

macOS (Homebrew):

brew install ffmpeg

Linux (apt):

sudo apt update && sudo apt install ffmpeg

Verify installation:

ffmpeg -version

Note: Without ffmpeg, Sonus will save audio as .wav files instead of .mp3.

---

🖥️ GUI App

Launch the graphical interface for an intuitive audiobook creation experience:

python sonus_gui.py

Interface Overview

The GUI provides a complete workflow:

1. 📂 Load EPUB - Drag-and-drop or browse for your book
2. 📝 Extract Text - Preview and edit the extracted content
3. ✂️ Select Region (Optional) - Highlight specific text to convert
4. 🎚️ Configure Settings - Choose voice, quality, and device
5. ▶️ Convert - Generate your audiobook with real-time progress

Key Features

Feature	Description
Drag & Drop	Simply drag EPUB files into the window
Text Preview	Edit extracted text before conversion
Selection Mode	Convert only highlighted portions
Voice Library	10+ voices in English, French, German
Device Control	CPU, CUDA (NVIDIA), or MPS (Apple)
Quality Presets	DDPM steps 1-50 for speed/quality balance
Batch Testing	Set word/character limits for quick tests

Settings Guide

DDPM Steps (Quality vs Speed)

• 2-3 steps: ⚡ Fast - Ideal for long books, minor quality trade-off
• 5 steps: ⚖️ Balanced - Default, good quality/speed ratio
• 10-20 steps: 🎨 High Quality - Best output, much slower
• 30-50 steps: 🔬 Maximum - Experimental, very slow

CFG Scale (Speaker Adherence)

• 1.0-1.5: Natural, slight variation
• 2.0-3.0: Stronger voice characteristics
• 3.5+: Maximum adherence (may sound less natural)

---

💻 CLI Usage

Basic Commands

Quick test (first 1200 words):

python epub_to_mp3.py book.epub --max-words 1200 --output test.mp3

Full conversion with default settings:

python epub_to_mp3.py book.epub --output audiobook.mp3

Custom voice and quality:

python epub_to_mp3.py book.epub \
  --speaker-name Emma \
  --ddpm-steps 3 \
  --cfg-scale 1.5 \
  --device cuda \
  --output audiobook.mp3

Save extracted text:

python epub_to_mp3.py book.epub \
  --text-output extracted.txt \
  --max-words 5000 \
  --output sample.mp3

Complete Options Reference

Option	Type	Default	Description
epub_path	positional	required	Path to input EPUB file
--output	path	{name}.mp3	Output MP3/WAV file path
--speaker-name	string	Carter	Voice preset (see Voices)
--device	choice	auto-detect	cpu, cuda, or mps
--ddpm-steps	int	5	Quality/speed balance (1-50)
--cfg-scale	float	1.5	Speaker adherence (0.5-5.0)
--mp3-bitrate	string	192k	128k, 192k, 256k, 320k
--max-words	int	unlimited	Limit by word count
--max-chars	int	unlimited	Limit by character count
--text-output	path	none	Save extracted text to file
--keep-wav	flag	false	Keep intermediate WAV file
--voices-dir	path	auto	Custom voice directory
--model-path	string	auto	Custom model path

Example Workflows

Fast preview for testing:

python epub_to_mp3.py book.epub --max-words 500 --ddpm-steps 2 --output preview.mp3

High-quality production:

python epub_to_mp3.py book.epub \
  --speaker-name Grace \
  --ddpm-steps 10 \
  --mp3-bitrate 320k \
  --device cuda \
  --output audiobook_hq.mp3

Extract text only:

python epub_to_mp3.py book.epub --text-output book.txt --max-words 0

---

🎤 Available Voices

Sonus includes multiple voice presets for different languages and styles:

English Voices

• Carter (Male) - Deep, authoritative
• Davis (Male) - Warm, conversational
• Frank (Male) - Clear, neutral
• Mike (Male) - Energetic, dynamic
• Emma (Female) - Soft, pleasant
• Grace (Female) - Professional, clear

Other Languages

• French: Spk0 (Male), Spk1 (Female)
• German: Spk0 (Male), Spk1 (Female)

Voices are located in VibeVoice/demo/voices/streaming_model/

---

⚡ Performance Benchmarks

Conversion speed depends on your GPU and DDPM steps setting:

Hardware	DDPM Steps	Speed	100k Word Book
RTX 500 Ada (4GB)	5	~3.75 words/sec	~7.7 hours
RTX 500 Ada (4GB)	3	~6 words/sec	~4.6 hours
RTX 4070 Ti Super (16GB)	5	~11-15 words/sec	~2-2.5 hours
RTX 4070 Ti Super (16GB)	3	~18-22 words/sec	~1.5 hours
CPU (i7-12700K)	5	~0.5 words/sec	~55 hours

Tip: For long books (100k+ words), use lower ddpm steps to significantly reduce generation time with minimal quality loss.

Current Limitations

• EPUB only: PDF and TXT input not yet supported
• Single-threaded: One book at a time
• Low GPU usage: 5-15% is normal due to autoregressive architecture
• Long books: 100k+ word books may take several hours even on powerful GPUs

---

📚 Documentation

Understanding DDPM

DDPM (Denoising Diffusion Probabilistic Models) generates audio through iterative refinement:

1. Start: Random noise
2. Process: Gradual denoising over N steps
3. Output: Natural-sounding speech

The Trade-off:

• More steps → Better quality, slower generation
• Fewer steps → Faster generation, slight quality reduction

Most users find 3-5 steps provide excellent quality for audiobooks while maintaining reasonable speed.

GPU Utilization

Low GPU utilization (5-15%) is expected and normal due to the model's architecture:

• Autoregressive generation: Sequential token generation (can't parallelize)
• Streaming model: Optimized for real-time, not batch processing
• Small model size: 0.5B parameters don't fully saturate modern GPUs

This is a limitation of the VibeVoice Realtime architecture, not a configuration issue.

---

🔧 Troubleshooting

Common Issues

🚫 "CUDA is not available" error

Problem: PyTorch is using CPU-only version

Solution:

pip uninstall torch torchvision torchaudio
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

Verify:

import torch
print(torch.cuda.is_available())  # Should return True

🔇 MP3 files won't open / No audio

Problem: Missing ffmpeg or corrupted conversion

Solution:

1. Install ffmpeg (see Installation)
2. Restart terminal/IDE to refresh PATH
3. Try conversion again
4. If still failing, use WAV output: --output file.wav

⏱️ Conversion is too slow

Solutions:

• Lower DDPM steps: --ddpm-steps 2
• Use GPU if available: --device cuda
• Test with small sample first: --max-words 500
• Consider upgrading GPU for long books

📦 "No module named 'vibevoice'" error

Problem: VibeVoice not installed correctly

Solution:

cd /path/to/sonus
pip install -e ./VibeVoice[streamingtts]

🎙️ Voice sounds robotic or unnatural

Solutions:

• Increase DDPM steps: --ddpm-steps 10
• Try different voices: --speaker-name Emma
• Adjust CFG scale: --cfg-scale 2.0

Getting Help

• Check existing issues: GitHub Issues
• Report bugs: Include error messages, OS, GPU model, and command used
• Request features: Describe your use case and expected behavior

---

🛠️ Development

Project Structure

sonus/
├── epub_to_mp3.py          # CLI converter script
├── sonus_gui.py            # Desktop GUI application
├── README.md               # This file
└── VibeVoice/              # TTS engine submodule
    ├── vibevoice/          # Core library
    │   ├── modular/        # Model implementations
    │   ├── processor/      # Audio/text processing
    │   └── schedule/       # Diffusion schedulers
    └── demo/
        └── voices/         # Voice presets
            └── streaming_model/

Adding Custom Voices

1. Place voice files (.pt) in a directory
2. Use --voices-dir /path/to/voices
3. Select with --speaker-name YourVoiceName

Voice file format: {language}-{name}_{gender}.pt (e.g., en-Custom_woman.pt)

---

🤝 Contributing

Contributions are welcome! Here's how you can help:

Ways to Contribute

• 🐛 Report bugs - Open an issue with details
• 💡 Suggest features - Describe your idea and use case
• 📖 Improve docs - Fix typos, add examples, clarify instructions
• 🔧 Submit PRs - Fix bugs, add features, optimize performance

Development Setup

# Clone the repository
git clone https://github.com/nsbgg/sonus.git
cd sonus

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ./VibeVoice[streamingtts]
pip install pydub torch transformers tkinterdnd2

# Make your changes and test
python sonus_gui.py

Pull Request Guidelines

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request with a clear description

---

⚠️ Responsible Use

High-quality speech synthesis can be misused for:

• 🚫 Impersonation and identity theft
• 🚫 Generating misleading content (deepfakes)
• 🚫 Unauthorized voice cloning

Guidelines

✅ DO:

• Use for personal audiobook creation from legally owned books
• Disclose that content is AI-generated when sharing
• Respect copyright and intellectual property laws
• Use voices ethically and transparently

❌ DON'T:

• Impersonate real people without consent
• Create deceptive or misleading content
• Violate copyright by distributing converted books
• Use for harassment, fraud, or illegal activities

You are responsible for how you use this tool. Use it ethically and legally.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Third-Party Licenses

• VibeVoice: Microsoft - VibeVoice License
• PyTorch: BSD-style license
• Transformers: Apache License 2.0

---

🙏 Acknowledgments

• Microsoft - For the excellent VibeVoice TTS model
• Hugging Face - For the Transformers library
• PyTorch Team - For the deep learning framework
• All contributors and users who provide feedback and improvements