DOCSEARCHbyAlgolia
Submit Docs

kokoro-tts

repository·main·Indexed 23 days ago

https://github.com/nazdridoy/kokoro-tts

A CLI text-to-speech tool using the Kokoro model to convert text, EPUB, and PDF files into WAV or MP3 audio. It supports multiple languages, streaming playback, and voice blending to create custom tones. Key features include chapter extraction from PDF and EPUB documents, the ability to split output into chunks, and a flexible CLI for controlling speech speed, language, and voice selection.

Tokens
2.8K
Snippets
7
Records
18
Agent score
83%

What's inside kokoro-tts

  1. Voice blending in Kokoro TTS

    main

    Kokoro TTS allows you to blend multiple voices together using weights to create custom tones. You can specify a single voice or a mix using the --voice option.

    Single voice:

    --voice af_sarah

    Blended voices (with specific weights): Use the format voice1:weight,voice2:weight.

    # 60% af_sarah and 40% am_adam
kokoro-tts input.txt output.wav --voice "af_sarah:60,am_adam:40"

    Equal voice blend: If you provide multiple voices without weights, they are blended equally.

    # 50-50 mix
kokoro-tts input.txt --stream --voice "am_adam,af_sarah"
    kokoro-tts input.txt output.wav --voice "af_sarah:60,am_adam:40"

  2. Download required model files

    main

    After installation, you must download the model and voice data files. These files must be placed in the same directory from which you run the kokoro-tts command.

    # Download voice data (bin format is preferred)
wget https://github.com/nazdridoy/kokoro-tts/releases/download/v1.0.0/voices-v1.0.bin

# Download the model
wget https://github.com/nazdridoy/kokoro-tts/releases/download/v1.0.0/kokoro-v1.0.onnx
    wget https://github.com/nazdridoy/kokoro-tts/releases/download/v1.0.0/voices-v1.0.bin
wget https://github.com/nazdridoy/kokoro-tts/releases/download/v1.0.0/kokoro-v1.0.onnx

  3. Install Kokoro TTS

    main

    Kokoro TTS can be installed using several methods. The recommended approach is via PyPI using uv or pip.

    Prerequisites

    • Python version: 3.11 or 3.12 (Python 3.13+ is not currently supported).

    Method 1: Install from PyPI (Recommended)

    Using uv:

    uv tool install kokoro-tts

    Using pip:

    pip install kokoro-tts

    Method 2: Install from Git

    Using uv:

    uv tool install git+https://github.com/nazdridoy/kokoro-tts

    Using pip:

    pip install git+https://github.com/nazdridoy/kokoro-tts

    Method 3: Clone and Install Locally

    1. Clone the repository:
    git clone https://github.com/nazdridoy/kokoro-tts.git
cd kokoro-tts
    1. Install the package: With uv:
    uv venv
uv pip install -e .

    With pip:

    python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .

    Method 4: Run Without Installation

    1. Clone the repository:
    git clone https://github.com/nazdridoy/kokoro-tts.git
cd kokoro-tts
    1. Install dependencies only: With uv:
    uv venv
uv sync

    With pip:

    python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
    uv tool install kokoro-tts

  4. Use Kokoro TTS CLI

    main

    The CLI follows this basic usage pattern:

    kokoro-tts <input_text_file> [<output_audio_file>] [options]

    Note on execution commands based on installation method:

    • PyPI/Git install: Use kokoro-tts.
    • Local install (Method 3): Use uv run kokoro-tts or activate your venv.
    • No install (Method 4): Use uv run -m kokoro_tts or python -m kokoro_tts with an activated venv.

    Input Formats

    • .txt: Text file.
    • .epub: EPUB book (processes chapters).
    • .pdf: PDF document (extracts chapters from TOC or content).
    • - or /dev/stdin (Linux/macOS) or CONIN$ (Windows): Standard input (stdin).

    Basic Examples

    Generate audio from a text file:

    kokoro-tts input.txt output.wav --speed 1.2 --lang en-us --voice af_sarah

    Stream audio from stdin:

    echo "Hello World" | kokoro-tts - --stream

    Process an EPUB and split into MP3 chunks:

    kokoro-tts input.epub --split-output ./chunks/ --format mp3

    Merge existing chunks back into files:

    kokoro-tts --merge-chunks --split-output ./chunks/ --format wav
    kokoro-tts input.txt output.wav --speed 1.2 --lang en-us --voice af_sarah

  5. Blend multiple voices

    main

    Kokoro TTS supports blending two voices to create a unique voice profile. This is achieved by passing a comma-separated string to the voice parameter in the format voice1:weight,voice2:weight.

    Examples:

    • af_sarah,am_adam: Equal 50/50 blend.
    • af_sarah:60,am_adam:40: 60% Sarah, 40% Adam.

    Internally, the validate_voice function calculates the weighted average of the voice styles using numpy.add.

  6. Configure Kokoro TTS CLI options

    main

    Use the following flags to customize the text-to-speech output:

    OptionDescription
    --help, -hShow help message
    --help-languagesList supported languages
    --help-voicesList available voices
    --merge-chunksMerge existing chunks into chapter files
    --streamStream audio instead of saving to file
    --speed <float>Set speech speed (default: 1.0)
    --lang <str>Set language (default: en-us)
    --voice <str>Set voice or blend voices (default: interactive selection). Use name (e.g. af_sarah) or blend format voice1:weight,voice2:weight
    --split-output <dir>Save each chunk as a separate file in the specified directory
    --format <str>Audio format: wav or mp3 (default: wav)
    --debugShow detailed debug information during processing

  7. Reference supported voices and languages

    main

    The following voices and language codes are supported:

    CategoryVoicesLanguage Code
    🇺🇸 👩af_alloy, af_aoede, af_bella, af_heart, af_jessica, af_kore, af_nicole, af_nova, af_river, af_sarahen-us
    🇺🇸 👨am_adam, am_echo, am_eric, am_fenrir, am_liam, am_michael, am_onyx, am_pucken-us
    🇬🇧bf_alice, bf_emma, bf_isabella, bf_lily, bm_daniel, bm_fable, bm_george, bm_lewisen-gb
    🇫🇷ff_siwisfr-fr
    🇮🇹if_sara, im_nicolait
    🇯🇵jf_alpha, jf_gongitsune, jf_nezumi, jf_tebukuro, jm_kumoja
    🇨🇳zf_xiaobei, zf_xiaoni, zf_xiaoxiao, zf_xiaoyi, zm_yunjian, zm_yunxi, zm_yunxia, zm_yunyangcmn

  9. Extract chapters from EPUB files

    main

    The extract_chapters_from_epub(epub_file, debug=False) function parses an EPUB file's Table of Contents (TOC) to extract content organized by chapters. It returns a list of dictionaries, where each dictionary contains:

    • title: The chapter title.
    • content: The extracted text content.
    • order: The sequence order of the chapter.

  10. List available Kokoro voices

    main

    Use list_available_voices(kokoro) to retrieve a list of all available voice names from a Kokoro instance. This is useful for interactive selection or verifying voice availability.

    voices = list_available_voices(kokoro)
for idx, voice in enumerate(voices):
    print(f"{idx + 1}. {voice}")

  11. Stream audio with stream_audio()

    main

    The stream_audio function provides an asynchronous way to stream audio chunks directly to the speakers. It uses kokoro.create_stream to iterate over audio samples and sounddevice (sd.play) to play them. This is useful for real-time playback of long texts.

    Parameters:

    • kokoro: The Kokoro model instance.
    • text: The input string to synthesize.
    • voice: The selected voice identifier.
    • speed: Synthesis speed (float).
    • lang: Language code (e.g., en-us).
    • debug: Boolean to enable debug logging.

  12. Merge audio chunks with merge_chunks_to_chapters()

    main

    If you have previously used the --split-output feature to save audio in chunks, you can reconstruct complete chapter files using merge_chunks_to_chapters. This function scans a directory for chapter_XXX subdirectories, reads the info.txt file within each to find the original title, and merges all chunk_XXX.format files into a single audio file named after the chapter.

    Parameters:

    • split_output_dir: The directory containing the chapter subdirectories.
    • format: The audio format used (default is "wav").
    merge_chunks_to_chapters(split_output_dir, format="wav")