Kokoro TTS Local

A local implementation of the Kokoro Text-to-Speech model, featuring dynamic module loading, automatic dependency management, and a web interface.

Current Status

✅ WORKING - READY TO USE ✅

The project has been updated with:

• Automatic espeak-ng installation and configuration
• Dynamic module loading from Hugging Face
• Improved error handling and debugging
• Interactive CLI interface
• Cross-platform setup scripts
• Web interface with Gradio

Features

• Local text-to-speech synthesis using the Kokoro model
• Automatic espeak-ng setup using espeakng-loader
• Multiple voice support with easy voice selection
• Phoneme output support and visualization
• Interactive CLI for custom text input
• Voice listing functionality
• Dynamic module loading from Hugging Face
• Comprehensive error handling and logging
• Cross-platform support (Windows, Linux, macOS)
• NEW: Web Interface Features
  • Modern, user-friendly UI
  • Real-time generation progress
  • Multiple output formats (WAV, MP3, AAC)
  • Network sharing capabilities
  • Audio playback and download
  • Voice selection dropdown
  • Detailed process logging

Prerequisites

• Python 3.8 or higher
• Git (for cloning the repository)
• Internet connection (for initial model download)
• FFmpeg (required for MP3/AAC conversion):
  • Windows: Automatically installed with pydub
  • Linux: sudo apt-get install ffmpeg
  • macOS: brew install ffmpeg

Windows-Specific Requirements

For optimal performance on Windows, you should either:

1. Enable Developer Mode:
   • Open Windows Settings
   • Navigate to System > Developer settings
   • Turn on Developer Mode

OR

2. Run Python as Administrator:
   • Right-click your terminal (PowerShell/Command Prompt)
   • Select "Run as administrator"
   • Run the commands from there

This is needed for proper symlink support in the Hugging Face cache system. If you skip this, the system will still work but may use more disk space.

Dependencies

torch
phonemizer-fork
transformers
scipy
munch
soundfile
huggingface-hub
espeakng-loader
gradio>=4.0.0
pydub  # For audio format conversion

Setup

Windows

# Clone the repository
git clone https://github.com/PierrunoYT/Kokoro-TTS-Local.git
cd Kokoro-TTS-Local

# Run the setup script
.\setup.ps1

# Download initial model and voices
python tts_demo.py --list-voices

Linux/macOS

# Clone the repository
git clone https://github.com/PierrunoYT/Kokoro-TTS-Local.git
cd Kokoro-TTS-Local

# Run the setup script
chmod +x setup.sh
./setup.sh

# Install FFmpeg (if needed)
# Linux:
sudo apt-get install ffmpeg
# macOS:
brew install ffmpeg

# Download initial model and voices
python tts_demo.py --list-voices

Manual Setup

If you prefer to set up manually:

1. Create a virtual environment:

# Windows
python -m venv venv
.\venv\Scripts\activate

# Linux/macOS
python3 -m venv venv
source venv/bin/activate

2. Install dependencies:

python -m pip install --upgrade pip
pip install -r requirements.txt

3. Install system dependencies:

# Windows
# FFmpeg is automatically installed with pydub

# Linux
sudo apt-get update
sudo apt-get install espeak-ng ffmpeg

# macOS
brew install espeak ffmpeg

4. Download initial model and voices:

# This will download the model and voices from Hugging Face
python tts_demo.py --list-voices

Usage

Web Interface

# Start the web interface
python gradio_interface.py

After running the command:

1. Open your web browser and visit: http://localhost:7860
2. The interface will also create a public share link (optional)
3. You can now:
   • Input text to synthesize
   • Select from available voices
   • Choose output format (WAV/MP3/AAC)
   • Monitor generation progress
   • Play or download generated audio

Note: If port 7860 is already in use, Gradio will automatically try the next available port (7861, 7862, etc.). Check the terminal output for the correct URL.

Command Line Interface

python tts_demo.py

The script will:

1. Download necessary model files from Hugging Face
2. Set up espeak-ng automatically using espeakng-loader
3. Import required modules dynamically
4. Test the phonemizer functionality
5. Generate speech from your text with phoneme visualization
6. Save the output as 'output.wav' (22050Hz sample rate)

Project Structure

.
├── .cache/                 # Cache directory for downloaded models
│   └── huggingface/       # Hugging Face model cache
├── .git/                   # Git repository data
├── .gitignore             # Git ignore rules
├── .gradio/               # Gradio cache and configuration
│   ├── certificate.pem    # SSL certificate for Gradio
│   └── ...               # Other Gradio config files
├── __pycache__/           # Python cache files
├── outputs/               # Generated audio output files
│   ├── output.wav        # Default output file
│   ├── output.mp3        # MP3 converted files
│   └── output.aac        # AAC converted files
├── voices/                # Voice model files
│   ├── af_bella/         # American Female - Bella voice
│   ├── af_nicole/        # American Female - Nicole voice
│   ├── af_sarah/         # American Female - Sarah voice
│   ├── af_sky/           # American Female - Sky voice
│   ├── am_adam/          # American Male - Adam voice
│   ├── am_michael/       # American Male - Michael voice
│   ├── bf_emma/          # British Female - Emma voice
│   ├── bf_isabella/      # British Female - Isabella voice
│   ├── bm_george/        # British Male - George voice
│   └── bm_lewis/         # British Male - Lewis voice
├── venv/                  # Python virtual environment
├── LICENSE                # Apache 2.0 License file
├── README.md             # Project documentation
├── gradio_interface.py    # Web interface implementation
├── models.py             # Core TTS model implementation
├── requirements.txt      # Python dependencies
├── setup.ps1             # Windows setup script
├── setup.sh              # Linux/macOS setup script
└── tts_demo.py          # CLI demo implementation

Model Information

The project uses the Kokoro-82M model from Hugging Face:

• Repository: hexgrad/Kokoro-82M
• Model file: kokoro-v0_19.pth
• Voice files: Located in the voices/ directory
• Available voices:
  • American Female: af_bella, af_nicole, af_sarah, af_sky
  • American Male: am_adam, am_michael
  • British Female: bf_emma, bf_isabella
  • British Male: bm_george, bm_lewis
• Automatically downloads required files from Hugging Face

Technical Details

• Sample rate: 22050Hz
• Input: Text in any language (English recommended)
• Output: WAV/MP3/AAC audio file
• Dependencies are automatically managed
• Modules are dynamically loaded from Hugging Face
• Error handling includes stack traces for debugging
• Cross-platform compatibility through setup scripts

Contributing

Feel free to contribute by:

1. Opening issues for bugs or feature requests
2. Submitting pull requests with improvements
3. Helping with documentation
4. Testing different voices and reporting issues
5. Suggesting new features or optimizations
6. Testing on different platforms and reporting results

License

This project is licensed under the Apache 2.0 License.