kentui 0.2.0

Interactive CLI for kenkui — convert ebooks to audiobooks locally

kentui

Freaky fast audiobook generation from ebooks. No GPU. No nonsense.

kentui is the interactive CLI for kenkui — an ebook-to-audiobook converter powered by Kyutai's pocket-tts, running entirely on CPU.

kentui handles the interactive parts: configuration wizard, voice management, chapter selection, and progress display. The actual conversion engine is kenkui, which kentui depends on.

---

✨ Features

• Freaky fast audiobook generation
• No GPU needed, 100% CPU
• Super high-quality text-to-speech
• Interactive hub with live status panel and Escape to go back
• Multi-voice narration — different voices for different characters, powered by an LLM
• Chapter-voice mode — assign a distinct voice to each chapter
• Voice pool template — persistent global defaults for automatic voice assignment
• Credits chapter — synthesized audio appended to every m4b
• Three tiers of voices: compiled, built-in, and custom
• Flexible chapter selection with presets and manual override
• Broadcast-quality audio post-processing chain
• Supports EPUB, MOBI/AZW, and FB2

---

🚀 Quick Start

Requirements

• Python 3.12+

Install

pip install kentui

Or with uv / pipx:

uv tool install kentui
pipx install kentui

Compiled voices (~36 MB) are downloaded automatically the first time you run a conversion. Voice and cache maintenance live in kentui system.

Run

kentui book.epub

That's it. An interactive wizard walks you through the setup, then kentui runs the job and shows a live progress bar. You'll get a book.m4b alongside your ebook when it's done.

---

📚 Usage

Interactive wizard (default)

kentui book.epub

Opens a configuration hub showing a live status panel of your current settings, then a menu:

┌─ Current Settings ───────────────────────────────────────────┐
│  Mode:          Multi-voice                                   │
│  NLP:           Anthropic · claude-haiku-4-5                 │
│  TTS Provider:  pocket-tts · local                           │
│  Narrator:      sarah                                         │
│  Chapters:      content-only (42 selected)                   │
│  Quality:       temp 0.8 · 30 LSD steps · 96k               │
└───────────────────────────────────────────────────────────────┘

  > Submit Job
    Narrator Voice →
    Chapters →
    Narration Mode →
    Series →
    Advanced Options →
    Cancel

Press Escape at any step to go back. All settings persist to ~/.config/kenkui/last_job_profile.toml and pre-load on the next run.

Headless mode

Pass a config file with -c to skip the wizard entirely:

kentui book.epub -c my-config.toml

Exits 0 on success, 1 on failure.

System manager

kentui system

Opens the maintenance hub for voice and cache management. This keeps the public CLI small while preserving advanced workflows inside the app.

---

🎙️ Narration Modes

Single voice

The default. One voice narrates everything.

Multi-voice (character narration)

kenkui uses an NLP pipeline to identify characters and assigns each a distinct voice. The narrator gets its own voice too.

Two NLP backend families are available: Ollama (local, default) and cloud providers (Anthropic, OpenAI, Google, OpenRouter, or LiteLLM).

Ollama (default)

Requirements:

• Ollama running locally (ollama serve)
• NLP model pulled (default: llama3.2) — ollama pull llama3.2
• spaCy model — downloaded automatically if missing

Cloud providers

Run kentui config and answer yes to "Configure a cloud NLP provider API key?" to set up credentials.

Default models:

Provider	Default model
anthropic	claude-sonnet-4-6
openai	gpt-4o
google	gemini/gemini-2.0-flash
openrouter	anthropic/claude-sonnet-4-6
litellm	anthropic/claude-sonnet-4-6

How voice assignment works:

After the scan completes, voices are assigned using a three-tier priority system:

1. Series record — named character → pinned voice (highest priority)
2. Voice pool template — role + gender + rank → voice
3. Round-robin pool — any remaining characters

Chapter-voice mode

Assign a distinct voice to each chapter. The wizard presents each chapter title and lets you pick a voice.

---

🗂️ Voice Pool Template

The voice pool template (~/.config/kenkui/voice_pool.toml) pre-assigns voices by character role, gender, and rank. It applies automatically to every multi-voice job.

[protagonist.male]
1 = "david"
2 = "james"
pool = ["oliver", "ethan"]

[protagonist.female]
1 = "sarah"
pool = ["emma", "claire"]

[supporting.male]
pool = ["oliver", "ethan", "marcus"]

[minor]
pool = []  # fallback: any non-excluded voice

---

🎙️ Voice System

Voices come in three tiers:

Tier	Source	Auth required?
Compiled	Downloaded from HuggingFace on first run	No
Built-in	Pocket TTS defaults bundled by kenkui	No
Custom	User-provided prompt sources compiled locally	No

Built-in voices:

alba, marius, javert, cosette, jean, fantine, eponine, azelma,
anna, vera, charles, paul, george, mary, jane, michael, eve,
bill_boerst, caro_davy, peter_yearsley, stuart_bell

Voice manager

kentui system

Launches the interactive system manager. From there you can browse and audition voices, manage the exclusion pool, and inspect cache state.

---

⚙️ Configuration

# Create or edit the default config
kentui config

# Create a named config profile
kentui config fast-mode

# Use a named config
kentui book.epub -c fast-mode

Key settings

Key	Default	Description
workers	cpu_count - 2	Parallel TTS worker processes
m4b_bitrate	96k	Output audio bitrate
temp	0.7	Sampling temperature
lsd_decode_steps	1	LSD decode steps (higher = better quality, slower)
default_voice	alba	Fallback voice
default_chapter_preset	content-only	Default chapter filter preset
pause_line_ms	800	Pause between lines (ms)
pause_chapter_ms	2000	Pause between chapters (ms)
pause_scene_break_ms	4000	Pause at scene breaks (ms)
nlp_provider	ollama	NLP backend
nlp_model	llama3.2	Model for speaker attribution
credits_enabled	true	Append synthesized credits audio

---

📖 Chapter Selection

Preset	Description
content-only	Body chapters only (default)
chapters-only	Titled chapters only
with-parts	Chapters and part headings
all	Every item in the ebook
none	Skip everything

After selecting a preset, the wizard shows a checkbox list of all chapters with the preset's defaults pre-selected.

---

🔊 Audio Post-Processing

kenkui applies a broadcast-quality effects chain: noise reduction → high-pass filter → low shelf EQ → presence boost → de-esser → compressor → limiter → autogain. All parameters are configurable via kentui config.

---

FAQ

Do I need a GPU? No. kenkui is 100% CPU-based.

What ebook formats does it support? EPUB, MOBI/AZW/AZW3/AZW4, and FB2.

What output format does it use? M4B, with chapters, metadata, and embedded covers.

Do I need Ollama for multi-voice? No. You can use Ollama locally or a cloud provider such as Anthropic, OpenAI, Google, OpenRouter, or LiteLLM. Run kentui config to set up provider credentials and defaults.

Does it upload my books anywhere? With the default Ollama backend: no. With a cloud NLP provider, the book text is sent to that provider's API for the character scan. Nothing else is uploaded.

---

🙏 Special Thanks

Thanks to Project Gutenberg for providing some of the public-domain books included with kenkui.

---

Voice Dataset Credits

kenkui's compiled voices are derived from two publicly available speech corpora.

CSTR VCTK Corpus

Veaux, Christoph; Yamagishi, Junichi; MacDonald, Kirsten. (2019). CSTR VCTK Corpus: English Multi-speaker Corpus for CSTR Voice Cloning Toolkit. University of Edinburgh. The Centre for Speech Technology Research (CSTR).

Licensed under Creative Commons Attribution 4.0 (CC BY 4.0). Commercial use is permitted with attribution.

EARS Dataset

Licensed under Creative Commons Attribution-NonCommercial 4.0 (CC BY-NC 4.0).

Note: Compiled voices sourced from EARS (identifiable by EARS in the voice name in the system voice manager) may not be used for commercial purposes. If you are building a commercial product with kenkui, use only VCTK-sourced or built-in voices.