Metadata-Version: 2.4
Name: kenkui
Version: 0.6.4
Summary: Convert Ebooks to Audiobooks with [custom] voice samples
Author-email: Sumner MacArthur <spn1kolat3sla@gmail.com>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/D1zzl3D0p/kenkui
Project-URL: Bug Tracker, https://github.com/D1zzl3D0p/kenkui/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: beautifulsoup4>=4.14.0
Requires-Dist: EbookLib>=0.20
Requires-Dist: rich>=14.2.0
Requires-Dist: scipy>=1.17.0
Requires-Dist: huggingface_hub>=1.3.0
Requires-Dist: pydub>=0.25.0
Requires-Dist: pocket-tts>=1.0.0
Requires-Dist: mutagen>=1.45.0
Requires-Dist: imageio-ffmpeg>=0.5.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Dynamic: license-file

# kenkui

![Python](https://img.shields.io/badge/python-3.7+-blue)
![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey)
![License](https://img.shields.io/github/license/D1zzl3D0p/kenkui)
![PyPI](https://img.shields.io/pypi/v/kenkui)

> **Freaky fast audiobook generation from EPUBs. No GPU. No nonsense.**

kenkui turns EPUB ebooks into high-quality M4B audiobooks using state-of-the-art text-to-speech — **entirely on CPU**, and faster than anything else I've used.

It's built on top of [Kyutai's pocket-tts](https://github.com/kyutai-labs/pocket-tts), with all the annoying parts handled for you: chapter parsing, batching, metadata, covers, voices, and sane defaults.

If you have ebooks and want audiobooks, kenkui is for you.

---

## ✨ Features

- Freaky fast audiobook generation
- No GPU needed, 100% CPU
- Super high-quality text-to-speech
- Multithreaded
- EPUB-aware chapter parsing
- **Flexible chapter filtering with regex patterns and presets**
- Custom voices
- Batch processing
- Automatic cover embedding (EPUB → M4B)
- Sensible defaults, minimal configuration

---

## 🚀 Quick Start

kenkui is intentionally easy to install and easy to use.

### Requirements

- Python **3.7+**
- One Python installer:
  - `uv` (recommended): <https://docs.astral.sh/uv/getting-started/installation/>
  - or `pip`
  - or `pipx`

### Install

#### One-line installer (macOS / Linux)

```bash
curl -sSL https://raw.githubusercontent.com/D1zzl3D0p/kenkui/main/install.sh | bash
```

#### One-line installer (Windows)

```powershell
powershell -Command "irm https://raw.githubusercontent.com/D1zzl3D0p/kenkui/main/install.ps1 | iex"
```

#### Manual install

Recommended:

```bash
uv tool install kenkui
```

Alternatives if you prefer:

```bash
pip install kenkui
```

```bash
pipx install kenkui
```

### Run

```bash
kenkui book.epub
```

That's it. You'll get a `book.m4b` alongside your EPUB.

You can also point Kenkui at a directory, and it will recursively convert all EPUBs it finds.

---

## 📚 Usage

You can pass either a single EPUB file or a directory.

```bash
# Convert a single book
kenkui book.epub

# Convert an entire library (interactive book selection)
kenkui library/

# Convert all books without prompting
kenkui library/ --no-select-books

# Specify output directory
kenkui book.epub -o output/

# Log detailed output to file
kenkui book.epub --log conversion.log

# Debug mode with full logging
kenkui book.epub --log debug.log --verbose
```

### 🎙️ Voice Selection

Use `-v` or `--voice` to choose a voice.

Accepted inputs:

- One of pocket-tts's default voices:

  ```
  alba, marius, javert, jean, fantine, cosette, eponine, azelma
  ```

- A local `.wav` file
- A Hugging Face-hosted voice:

  ```
  hf://user/repo/voice.wav
  ```

To see everything Kenkui can currently use:

```bash
kenkui --list-voices
```

### 🎭 Custom Voices

To use your own voice, record a **5–10 second** clip of clean speech with minimal background noise or crosstalk.

Cleaning the audio makes a noticeable difference. Tools like Adobe's Enhance Speech work well:
<https://podcast.adobe.com/en/enhance>

---

## FAQ

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

**Is it actually fast?**  
Yes. That's the entire point of the project.

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

**Can it generate MP3s?**  
No. This is intentional — M4B is a significantly better format for audiobooks.

**Does it support formats other than EPUB?**  
Not currently. EPUB only, for now.

**Why do I need to log in to Hugging Face for custom voices?**  
The pocket-tts model that powers kenkui is hosted on Hugging Face and is "gated," meaning the authors require users to accept their terms of use before downloading it. This is a one-time setup that takes about 2 minutes.

When you first use a custom voice (anything other than the 8 built-in defaults), kenkui will guide you through:
1. Creating a free Hugging Face account (if you don't have one)
2. Generating a read-only access token
3. Accepting the model's terms of use

The process is interactive and will open your browser at the right pages. You only need to do this once.

**Does it upload my books anywhere?**  
No. Everything runs locally. Internet access is only needed if you pull voices from Hugging Face.

---

## Non-Goals

kenkui is not meant to be:

- A general-purpose text-to-speech framework
- A GUI application
- An MP3 audiobook generator
- A pluggable frontend for every TTS backend available

The focus is narrow by design: fast, high-quality audiobook generation from EPUBs, with minimal friction.

---

## 🙏 Special Thanks

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