chatterbook 0.1.0__tar.gz

chatterbook-0.1.0/.github/workflows/workflow.yml

@@ -0,0 +1,37 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Test
+        run: uv run --extra dev pytest
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

chatterbook-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+.pytest_cache/
+__pycache__/
+*.py[cod]
+dist/
+build/
+*.egg-info/

chatterbook-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Small Turtle 2
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chatterbook-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: chatterbook
+Version: 0.1.0
+Summary: Convert EPUB books into chapter WAV audio with Chatterbox Multilingual TTS.
+Author: Small Turtle 2
+License: MIT License
+        
+        Copyright (c) 2026 Small Turtle 2
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: chatterbox-tts<0.2,>=0.1.7
+Requires-Dist: ebooklib>=0.18
+Requires-Dist: torch>=2
+Requires-Dist: torchaudio>=2
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# chatterbook
+
+Convert EPUB books into chapter WAV audio with Chatterbox Multilingual TTS.
+
+```python
+from chatterbook import convert_epub
+
+convert_epub(
+    "book.epub",
+    output_dir="audio",
+    language="ko",
+    voice_path="voices/narrator.wav",
+    style="warm",
+)
+```
+
+`voice_path` is an optional short WAV reference clip for voice cloning. If it is
+omitted, Chatterbox's bundled default conditionals are used.
+
+## Styles
+
+- `neutral`: balanced default
+- `warm`: slightly softer narration
+- `dramatic`: more expressive narration
+
+You can override a style with explicit generation values:
+
+```python
+convert_epub(
+    "book.epub",
+    output_dir="audio",
+    language="ko",
+    exaggeration=0.7,
+    cfg_weight=0.3,
+)
+```

chatterbook-0.1.0/README.md

@@ -0,0 +1,36 @@
+# chatterbook
+
+Convert EPUB books into chapter WAV audio with Chatterbox Multilingual TTS.
+
+```python
+from chatterbook import convert_epub
+
+convert_epub(
+    "book.epub",
+    output_dir="audio",
+    language="ko",
+    voice_path="voices/narrator.wav",
+    style="warm",
+)
+```
+
+`voice_path` is an optional short WAV reference clip for voice cloning. If it is
+omitted, Chatterbox's bundled default conditionals are used.
+
+## Styles
+
+- `neutral`: balanced default
+- `warm`: slightly softer narration
+- `dramatic`: more expressive narration
+
+You can override a style with explicit generation values:
+
+```python
+convert_epub(
+    "book.epub",
+    output_dir="audio",
+    language="ko",
+    exaggeration=0.7,
+    cfg_weight=0.3,
+)
+```

chatterbook-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "chatterbook"
+version = "0.1.0"
+description = "Convert EPUB books into chapter WAV audio with Chatterbox Multilingual TTS."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [
+  { name = "Small Turtle 2" },
+]
+dependencies = [
+  "beautifulsoup4>=4.12",
+  "chatterbox-tts>=0.1.7,<0.2",
+  "ebooklib>=0.18",
+  "torch>=2",
+  "torchaudio>=2",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/chatterbook"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

chatterbook-0.1.0/src/chatterbook/__init__.py

@@ -0,0 +1,17 @@
+from .converter import convert_epub
+from .exceptions import (
+    ChatterbookError,
+    OutputExistsError,
+    UnsupportedLanguageError,
+    UnknownStyleError,
+)
+from .styles import STYLE_PRESETS
+
+__all__ = [
+    "ChatterbookError",
+    "OutputExistsError",
+    "STYLE_PRESETS",
+    "UnknownStyleError",
+    "UnsupportedLanguageError",
+    "convert_epub",
+]

chatterbook-0.1.0/src/chatterbook/converter.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .epub import extract_chapters
+from .exceptions import OutputExistsError, UnsupportedLanguageError
+from .styles import resolve_style
+
+SUPPORTED_LANGUAGES = {
+    "ar",
+    "da",
+    "de",
+    "el",
+    "en",
+    "es",
+    "fi",
+    "fr",
+    "he",
+    "hi",
+    "it",
+    "ja",
+    "ko",
+    "ms",
+    "nl",
+    "no",
+    "pl",
+    "pt",
+    "ru",
+    "sv",
+    "sw",
+    "tr",
+    "zh",
+}
+
+
+def convert_epub(
+    epub_path: str | Path,
+    output_dir: str | Path,
+    *,
+    language: str,
+    voice_path: str | Path | None = None,
+    style: str = "neutral",
+    device: str | None = None,
+    t3_model: str | None = None,
+    overwrite: bool = False,
+    exaggeration: float | None = None,
+    cfg_weight: float | None = None,
+    temperature: float = 0.8,
+    repetition_penalty: float = 1.2,
+    min_p: float = 0.05,
+    top_p: float = 1.0,
+) -> list[Path]:
+    """Convert an EPUB into chapter WAV files.
+
+    The Chatterbox model is loaded lazily so importing chatterbook stays cheap.
+    """
+    language_id = language.lower()
+    if language_id not in SUPPORTED_LANGUAGES:
+        raise UnsupportedLanguageError(language, sorted(SUPPORTED_LANGUAGES))
+
+    epub_path = Path(epub_path)
+    output_dir = Path(output_dir)
+    voice_prompt_path = _resolve_voice_path(voice_path)
+    generation_style = resolve_style(
+        style,
+        exaggeration=exaggeration,
+        cfg_weight=cfg_weight,
+    )
+
+    chapters = extract_chapters(epub_path)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    output_paths = [output_dir / chapter.filename for chapter in chapters]
+    existing_paths = [path for path in output_paths if path.exists()]
+    if existing_paths and not overwrite:
+        raise OutputExistsError(existing_paths)
+
+    model = _load_model(device=device, t3_model=t3_model)
+    torchaudio = _import_torchaudio()
+
+    written_paths: list[Path] = []
+    for chapter, output_path in zip(chapters, output_paths, strict=True):
+        wav = model.generate(
+            chapter.text,
+            language_id=language_id,
+            audio_prompt_path=str(voice_prompt_path) if voice_prompt_path else None,
+            exaggeration=generation_style.exaggeration,
+            cfg_weight=generation_style.cfg_weight,
+            temperature=temperature,
+            repetition_penalty=repetition_penalty,
+            min_p=min_p,
+            top_p=top_p,
+        )
+        torchaudio.save(str(output_path), wav, model.sr)
+        written_paths.append(output_path)
+
+    return written_paths
+
+
+def _resolve_voice_path(voice_path: str | Path | None) -> Path | None:
+    if voice_path is None:
+        return None
+
+    path = Path(voice_path)
+    if not path.is_file():
+        raise FileNotFoundError(f"voice_path does not exist: {path}")
+    return path
+
+
+def _load_model(*, device: str | None, t3_model: str | None) -> Any:
+    from chatterbox.mtl_tts import ChatterboxMultilingualTTS
+
+    selected_device = device or _default_device()
+    return ChatterboxMultilingualTTS.from_pretrained(
+        device=selected_device,
+        t3_model=t3_model,
+    )
+
+
+def _default_device() -> str:
+    import torch
+
+    if torch.cuda.is_available():
+        return "cuda"
+    if hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+        return "mps"
+    return "cpu"
+
+
+def _import_torchaudio() -> Any:
+    import torchaudio
+
+    return torchaudio

chatterbook-0.1.0/src/chatterbook/epub.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import re
+import unicodedata
+from dataclasses import dataclass
+from pathlib import Path
+
+from bs4 import BeautifulSoup
+from ebooklib import epub
+
+
+@dataclass(frozen=True)
+class Chapter:
+    title: str
+    text: str
+    filename: str
+
+
+def extract_chapters(epub_path: str | Path) -> list[Chapter]:
+    book = epub.read_epub(str(epub_path))
+    chapters: list[Chapter] = []
+
+    for itemref in book.spine:
+        item_id = itemref[0]
+        item = book.get_item_with_id(item_id)
+        if item is None:
+            continue
+        if isinstance(item, epub.EpubNav):
+            continue
+
+        html = item.get_content()
+        title, text = _extract_html_text(html)
+        if not text:
+            continue
+
+        chapter_number = len(chapters) + 1
+        title = title or f"Chapter {chapter_number}"
+        filename = f"{chapter_number:03d}-{_slugify(title)}.wav"
+        chapters.append(Chapter(title=title, text=text, filename=filename))
+
+    return chapters
+
+
+def _extract_html_text(html: bytes) -> tuple[str, str]:
+    soup = BeautifulSoup(html, "html.parser")
+
+    for tag in soup(["script", "style", "nav"]):
+        tag.decompose()
+
+    heading = soup.find(["h1", "h2", "h3"])
+    title = heading.get_text(" ", strip=True) if heading else ""
+    text = soup.get_text(" ", strip=True)
+    text = re.sub(r"\s+", " ", text).strip()
+    return title, text
+
+
+def _slugify(value: str) -> str:
+    value = unicodedata.normalize("NFKD", value)
+    value = value.encode("ascii", "ignore").decode("ascii")
+    value = re.sub(r"[^a-zA-Z0-9]+", "-", value).strip("-").lower()
+    return value or "chapter"

chatterbook-0.1.0/src/chatterbook/exceptions.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from pathlib import Path
+from collections.abc import Sequence
+
+
+class ChatterbookError(Exception):
+    """Base exception for chatterbook errors."""
+
+
+class UnsupportedLanguageError(ChatterbookError, ValueError):
+    def __init__(self, language: str, supported_languages: Sequence[str]) -> None:
+        supported = ", ".join(supported_languages)
+        super().__init__(
+            f"Unsupported language '{language}'. Supported languages: {supported}"
+        )
+
+
+class UnknownStyleError(ChatterbookError, ValueError):
+    def __init__(self, style: str, supported_styles: Sequence[str]) -> None:
+        supported = ", ".join(supported_styles)
+        super().__init__(f"Unknown style '{style}'. Supported styles: {supported}")
+
+
+class OutputExistsError(ChatterbookError, FileExistsError):
+    def __init__(self, paths: Sequence[Path]) -> None:
+        joined = ", ".join(str(path) for path in paths)
+        super().__init__(f"Output file already exists: {joined}")

chatterbook-0.1.0/src/chatterbook/styles.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .exceptions import UnknownStyleError
+
+
+@dataclass(frozen=True)
+class GenerationStyle:
+    exaggeration: float
+    cfg_weight: float
+
+
+STYLE_PRESETS = {
+    "neutral": GenerationStyle(exaggeration=0.5, cfg_weight=0.5),
+    "warm": GenerationStyle(exaggeration=0.6, cfg_weight=0.45),
+    "dramatic": GenerationStyle(exaggeration=0.8, cfg_weight=0.55),
+}
+
+
+def resolve_style(
+    style: str,
+    *,
+    exaggeration: float | None = None,
+    cfg_weight: float | None = None,
+) -> GenerationStyle:
+    try:
+        preset = STYLE_PRESETS[style]
+    except KeyError as exc:
+        raise UnknownStyleError(style, sorted(STYLE_PRESETS)) from exc
+
+    return GenerationStyle(
+        exaggeration=preset.exaggeration if exaggeration is None else exaggeration,
+        cfg_weight=preset.cfg_weight if cfg_weight is None else cfg_weight,
+    )

chatterbook-0.1.0/tests/test_converter.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+import chatterbook.converter as converter
+from chatterbook import convert_epub
+
+
+class FakeModel:
+    sr = 24000
+
+    def __init__(self) -> None:
+        self.calls = []
+
+    def generate(self, text, **kwargs):
+        self.calls.append((text, kwargs))
+        return [[0.0]]
+
+
+class FakeTorchaudio:
+    def __init__(self) -> None:
+        self.saved = []
+
+    def save(self, path, wav, sample_rate):
+        self.saved.append((path, wav, sample_rate))
+        Path(path).write_bytes(b"wav")
+
+
+def test_convert_epub_passes_voice_path_and_style(monkeypatch, tmp_path):
+    fake_model = FakeModel()
+    fake_torchaudio = FakeTorchaudio()
+    voice_path = tmp_path / "voice.wav"
+    voice_path.write_bytes(b"voice")
+
+    monkeypatch.setattr(
+        converter,
+        "extract_chapters",
+        lambda _: [
+            SimpleNamespace(text="hello", filename="001-intro.wav"),
+            SimpleNamespace(text="world", filename="002-next.wav"),
+        ],
+    )
+    monkeypatch.setattr(converter, "_load_model", lambda **_: fake_model)
+    monkeypatch.setattr(converter, "_import_torchaudio", lambda: fake_torchaudio)
+
+    paths = convert_epub(
+        tmp_path / "book.epub",
+        tmp_path / "audio",
+        language="ko",
+        voice_path=voice_path,
+        style="warm",
+    )
+
+    assert [path.name for path in paths] == ["001-intro.wav", "002-next.wav"]
+    assert fake_model.calls[0][1]["audio_prompt_path"] == str(voice_path)
+    assert fake_model.calls[0][1]["language_id"] == "ko"
+    assert fake_model.calls[0][1]["exaggeration"] == 0.6
+    assert fake_model.calls[0][1]["cfg_weight"] == 0.45
+    assert len(fake_torchaudio.saved) == 2
+
+
+def test_explicit_generation_values_override_style(monkeypatch, tmp_path):
+    fake_model = FakeModel()
+    monkeypatch.setattr(
+        converter,
+        "extract_chapters",
+        lambda _: [SimpleNamespace(text="hello", filename="001-intro.wav")],
+    )
+    monkeypatch.setattr(converter, "_load_model", lambda **_: fake_model)
+    monkeypatch.setattr(converter, "_import_torchaudio", lambda: FakeTorchaudio())
+
+    convert_epub(
+        tmp_path / "book.epub",
+        tmp_path / "audio",
+        language="en",
+        style="dramatic",
+        exaggeration=0.7,
+        cfg_weight=0.3,
+    )
+
+    call = fake_model.calls[0][1]
+    assert call["exaggeration"] == 0.7
+    assert call["cfg_weight"] == 0.3
+
+
+def test_convert_epub_rejects_missing_voice_path(tmp_path):
+    with pytest.raises(FileNotFoundError):
+        convert_epub(
+            tmp_path / "book.epub",
+            tmp_path / "audio",
+            language="ko",
+            voice_path=tmp_path / "missing.wav",
+        )
+
+
+def test_convert_epub_rejects_existing_output(monkeypatch, tmp_path):
+    monkeypatch.setattr(
+        converter,
+        "extract_chapters",
+        lambda _: [SimpleNamespace(text="hello", filename="001-intro.wav")],
+    )
+    output_dir = tmp_path / "audio"
+    output_dir.mkdir()
+    (output_dir / "001-intro.wav").write_bytes(b"exists")
+
+    with pytest.raises(FileExistsError):
+        convert_epub(tmp_path / "book.epub", output_dir, language="ko")

chatterbook-0.1.0/tests/test_epub.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from ebooklib import epub
+
+from chatterbook.epub import extract_chapters
+
+
+def test_extract_chapters_uses_spine_order(tmp_path):
+    book = epub.EpubBook()
+    book.set_identifier("fixture")
+    book.set_title("Fixture")
+    book.set_language("en")
+
+    first = epub.EpubHtml(title="First", file_name="first.xhtml", lang="en")
+    first.content = "<html><body><h1>First Title</h1><p>Hello first.</p></body></html>"
+    second = epub.EpubHtml(title="Second", file_name="second.xhtml", lang="en")
+    second.content = "<html><body><h1>Second Title</h1><p>Hello second.</p></body></html>"
+
+    book.add_item(first)
+    book.add_item(second)
+    book.add_item(epub.EpubNcx())
+    book.add_item(epub.EpubNav())
+    book.spine = ["nav", first, second]
+
+    path = tmp_path / "fixture.epub"
+    epub.write_epub(str(path), book)
+
+    chapters = extract_chapters(path)
+
+    assert [chapter.title for chapter in chapters] == ["First Title", "Second Title"]
+    assert [chapter.filename for chapter in chapters] == [
+        "001-first-title.wav",
+        "002-second-title.wav",
+    ]
+    assert chapters[0].text == "First Title Hello first."