yapit-tts/yapit

yapit: Open-source TTS for documents and web pages.

Website | CLI | Self-Host | Architecture

Paste a URL or upload a PDF. Yapit renders the document and reads it aloud.

• Handles the documents other TTS tools can't: academic papers with math, citations, figures, tables, messy formatting. Math is rendered visually but gets spoken alt text. Citations and figure labels are silently displayed or naturalized for speech. Page numbers and headers are removed. All driven by a customizable prompt.
• 58 Kokoro voices across 9 languages. Runs locally in your browser (WebGPU), on CPU, or on GPU. Any OpenAI-compatible TTS server also supported.
• Vim-style keyboard shortcuts, document outliner, media key support, adjustable speed, dark mode, share by link.
• Markdown export: append /md to any document URL to get clean markdown via curl. /md-annotated includes TTS annotations.

Self-hosting

git clone --depth 1 https://github.com/yapit-tts/yapit.git && cd yapit
cp .env.selfhost.example .env.selfhost # edit to enable optional features (AI-extraction, custom TTS models)
make self-host

Open http://localhost. Data persists across restarts. To stop: make self-host-down.

Multi-user mode

By default, yapit runs in single-user mode — no login required, all features unlocked. .env.selfhost is self-documenting — see the comments for optional features (AI extraction, custom TTS models).

Note: in single-user mode, all requests share one user — everyone on the network sees the same document library.

If you want user accounts with login (e.g., for a family or small team), set AUTH_ENABLED=true in .env.selfhost and follow the comments below it. People sign in with an emailed link or code, so fill in APP_URL and SMTP_* (with SMTP_HOST empty, the gateway writes the sign-in emails to its log). Google and GitHub sign-in are optional: fill in a provider's *_CLIENT_ID and *_CLIENT_SECRET to offer it. docs/auth.md has the steps, and how to give the CLI an API token.

Custom TTS voices

Use any server implementing the OpenAI /v1/audio/speech API (vLLM-Omni, Kokoro-FastAPI, AllTalk, Chatterbox TTS, etc.).

Add to .env.selfhost:

OPENAI_TTS_BASE_URL=http://your-tts-server:8091/v1
OPENAI_TTS_API_KEY=your-key-or-empty
OPENAI_TTS_MODEL=your-model-name

Voices are auto-discovered if the server supports GET /v1/audio/voices. Otherwise set OPENAI_TTS_VOICES=voice1,voice2,....

OPENAI_TTS_BASE_URL=https://api.openai.com/v1
OPENAI_TTS_API_KEY=sk-...
OPENAI_TTS_MODEL=tts-1
OPENAI_TTS_VOICES=alloy,echo,fable,nova,onyx,shimmer

pip install vllm-omni
vllm-omni serve Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice \
    --omni --port 8091 --trust-remote-code --enforce-eager \
    --stage-configs-path /path/to/stage_configs.yaml # if you have low VRAM. `max_model_len: 1024` should work on 8GB

OPENAI_TTS_BASE_URL=http://your-gpu-host:8091/v1
OPENAI_TTS_API_KEY=EMPTY
OPENAI_TTS_MODEL=Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice

AI document extraction

Vision-based PDF/image processing works with any OpenAI-compatible API.

Add to .env.selfhost:

AI_PROCESSOR=openai
AI_PROCESSOR_BASE_URL=https://openrouter.ai/api/v1  # or your vLLM/Ollama endpoint
AI_PROCESSOR_API_KEY=your-key
AI_PROCESSOR_MODEL=qwen/qwen3-vl-235b-a22b-instruct  # any vision-capable model

Or use Google Gemini directly (with batch-mode support): AI_PROCESSOR=gemini + GOOGLE_API_KEY=your-key.

GPU workers for Kokoro TTS & YOLO figure detection

# One-time GPU setup: generate CDI spec + enable CDI in Docker
sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml
# Add {"features": {"cdi": true}} to /etc/docker/daemon.json, then:
sudo systemctl restart docker

git clone --depth 1 https://github.com/yapit-tts/yapit.git && cd yapit

# Pull only the images you need
docker compose -f docker-compose.worker.yml pull kokoro-gpu yolo-gpu

# Start 2 Kokoro + 1 YOLO worker
REDIS_URL=redis://<host>:6379/0 docker compose -f docker-compose.worker.yml up -d \
  --scale kokoro-gpu=2 --scale yolo-gpu=1 kokoro-gpu yolo-gpu

sudo tee /etc/systemd/system/nvidia-mps.service > /dev/null <<'EOF'
[Unit]
Description=NVIDIA Multi-Process Service (MPS)
After=nvidia-persistenced.service

[Service]
Type=forking
ExecStart=/usr/bin/nvidia-cuda-mps-control -d
ExecStop=/bin/sh -c 'echo quit | /usr/bin/nvidia-cuda-mps-control'
Restart=on-failure

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now nvidia-mps

Roadmap

Next:

• Support exporting audio as MP3.

Later:

• Support thinking parameter for AI extraction

Development

uv sync                              # install Python dependencies
npm install --prefix frontend        # install frontend dependencies
make dev-env 2>/dev/null || touch .env  # decrypt secrets, or create empty .env
make dev-cpu                         # start backend services (Docker Compose)
cd frontend && npm run dev           # start frontend
make test-local                      # run tests

See docs/dev-setup.md for full setup instructions.

The docs/ directory is the project's in-depth knowledge base, maintained jointly with Claude during development.

Built with Kokoro, defuddle, DocLayout-YOLO. The hosted version at yapit.md also uses Gemini.