gibigbig/kokoro-api repository overview

⁠kokoro.tts

A minimal, self-hosted text-to-speech player that connects to a local Kokoro⁠ server. Type or paste text, pick a voice, and play it back instantly — all in your browser.

⁠Features

• 26 voices — American & British, male & female, grouped by accent
• Speed control — 0.25× to 4.0×
• Audio scrubber — jump to any point in the playback
• Volume control
• Preferences saved to localStorage — voice, speed, and volume persist across sessions
• Server URL stored server-side — survives container restarts via Docker volume
• No npm installs — pure Node.js, zero dependencies

⁠Requirements

• Node.js⁠ 18+ (or Docker)
• A running Kokoro TTS server⁠ accessible on your network

⁠Quick Start

⁠Without Docker

node server.js

Opens at http://localhost:7755 automatically.

⁠With Docker Compose

docker compose -f docker-compose-kokoro-tts-player.yml up -d --build

Then open http://YOUR-SERVER-IP:7755 in your browser.

⁠File Structure

.
├── server.js                          # Node.js server + embedded UI
├── Dockerfile                         # Docker image definition
└── docker-compose-kokoro-tts-player.yml  # Docker Compose config

⁠Configuration

⁠Server URL

Click ⚙ server in the top right to set your Kokoro server URL.

http://192.168.x.x:8880

This is saved server-side to ~/.kokoro-tts-config.json and persists across restarts.

⁠Voice & Speed

Select your preferred voice and speed directly from the main UI. These are saved to browser localStorage and restored automatically on your next visit.

⁠Available Voices

⁠API

The server exposes three endpoints used by the UI.

⁠GET /config

Returns the current server configuration.

⁠POST /config

Saves server configuration.

{ "kokoroUrl": "http://192.168.x.x:8880" }

⁠POST /synthesize

Sends text to Kokoro and streams back the MP3 audio.

{ "text": "Hello world", "voice": "af_heart", "speed": 1.0 }

⁠Running Alongside Kokoro

If you're running Kokoro in Docker too, here's the minimal Kokoro setup to pair with this:

services:
  kokoro:
    image: hwdsl2/kokoro-server:cuda
    container_name: kokoro
    restart: always
    ports:
      - "8880:8880"
    volumes:
      - kokoro-data:/var/lib/kokoro
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

volumes:
  kokoro-data:

Set the server URL in kokoro.tts to http://YOUR-HOST-IP:8880.

⁠License

MIT