yakbox

Yakbox is a local-first audiobook build system. It turns Markdown manuscripts into generated narration, mastered WAV chapters, delivery MP3 chapters, and verified releases.

It supports local Chatterbox and hosted Resemble.ai synthesis. The same speech backends also power direct text-to-speech commands.

Install

Yakbox supports macOS and Linux with Python 3.14. Install the CLI from PyPI with uv:

uv tool install --python 3.14 yakbox
yakbox --version
yakbox doctor

To upgrade, run uv tool upgrade yakbox.

For local Chatterbox synthesis, install the local extra with the matching security overrides:

uv tool install --python 3.14 "yakbox[local]==0.4.0" \
  --overrides https://raw.githubusercontent.com/pbsladek/yakbox/v0.4.0/constraints/chatterbox-security-overrides.txt

FFmpeg and FFprobe are required to master, encode, inspect, and assemble audio. Alternatively, install a wheel downloaded from the GitHub Releases page:

uv tool install --python 3.14 ./yakbox-*.whl

GitHub Releases include SHA256SUMS. See the installation and release guide for checksum verification and the automated GitHub and PyPI release process.

Build an audiobook

yakbox init my-book
cd my-book
yakbox validate
yakbox audition --profile default --text "A short voice check."
yakbox build
yakbox release check --write-manifest

New projects use the fast offline fake backend. Change the profile in yakbox.toml to use local Chatterbox or Resemble.ai for real narration. For a new local project, use yakbox init my-book --backend chatterbox-local. Add --play to preview or audition to listen, and use yakbox status --watch in another terminal to follow a build. See the operations guide.

Examples

The examples cover a tiny offline book, local Chatterbox, Resemble.ai, multiple voice editions, pronunciations, selective rebuilding, and M4B assembly. Start with the tiny book:

cp -R examples/tiny-book my-tiny-book
cd my-tiny-book
yakbox validate
yakbox plan
yakbox build

Direct text to speech

yakbox tts "A short local test." --backend chatterbox-local --out local.wav
RESEMBLE_API_KEY=... yakbox cloud tts "A hosted test." \
  --voice-uuid VOICE_UUID --out hosted.wav

Use only voices and reference audio for which you have the necessary rights and consent.

The local Chatterbox example includes four public-domain LibriVox prompts with verified provenance and checksums. See the third-party notices and licensing policy.

For one- to three-word dialogue, Yakbox can generate longer carrier sentences, use local Whisper to crop and verify the target, and stop for a hash-bound listening review. See Whisper inspection and short-audio QA.

Documentation

See the documentation for manifests, backends, hosted budgets, cleanup, releases, troubleshooting, and the Python API.