# santinic/audiblez architecture

> Architecture diagram of the GitHub repository santinic/audiblez, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/santinic/audiblez
- Repository: https://github.com/santinic/audiblez

## Overview

##### Project type and purpose
- Audiblez is a hybrid CLI/GUI desktop tool that converts EPUB e-books into `.m4b` audiobooks.
- It uses a text-to-speech model (Kokoro-82M via Hugging Face + PyTorch) to synthesize audio, plus external tools (`espeak-ng` and `ffmpeg`) for auxiliary tasks.

##### File structure
- Top level:
- `audiblez/` – Python package
– `cli.py` – command-line interface entry point
– `ui.py` – GUI entry point (wxPython + Pillow)
– `core.py` – business logic: EPUB parsing, chapter selection, orchestration
– `voices.py` – registry of available voices
- `samples/` – demo audio clips (not part of runtime)
- `test/` – unit tests for CLI, chapter finding, core
- Configuration: `pyproject.toml`, GitHub Actions workflows, `.gitignore`, `LICENSE`, README, images.

##### Key architectural insights from README
- Two front‐ends (CLI and GUI) share the same core services.
- Core services include: EPUB parsing → optional chapter picking → text chunking → TTS inference → WAV file generation → M4B muxing.
- External dependencies:
- `espeak-ng` (fallback voices or preprocessing)
- `ffmpeg` (to merge WAVs into `.m4b`)
- PyTorch + CUDA (optional GPU acceleration)
- Kokoro-82M model from Hugging Face.

a. Front-end layer
- CLI (`audiblez` command)
- GUI (`audiblez-ui` via `ui.py`)
b. Application / Orchestration layer
- Core module (`core.py`):
- EPUB Parser & Chapter Finder
- Chapter Picker (interactive if `--pick`)
- Audio Pipeline Controller
- Voices Registry (`voices.py`)
c. Domain / Processing layer
- TTS Synthesizer (PyTorch model loader + inference)
- WAV file generator
- Speed adjuster (0.5×–2.0×)
d. Infrastructure / External services
- Hugging Face Kokoro-82M model hub
- PyTorch + CUDA device (optional)
- `espeak-ng` (if used for fallback TTS)
- `ffmpeg` (mux WAV files → `.m4b`)
e. Storage / I/O
- Input: EPUB file
- Temporary: `chapter_N.wav` files in output folder
- Output: final `book.m4b` audiobook

##### Relationships & data flow
1. User invokes CLI or GUI →
2. Front-end calls Core API →
3. Core reads EPUB → identifies chapters → (optional pick) →
4. Core iterates chapters:
- Fetch text chunk →
- Pass to TTS Synthesizer →
- Write `chapter.wav` →
5. After all chapters, Core calls `ffmpeg` to merge WAVs → `.m4b` → returns success.
6. GUI additionally updates progress bars and voice selectors via `ui.py`.

##### Architectural patterns & principles
- Layered Architecture: clear separation of Presentation (CLI/GUI), Application (core orchestration), Domain (TTS logic), Infrastructure (external tools).
- Single Source of Truth for voices (`voices.py` registry plugin).
- Dependency Injection: Core module calls external CLI tools (`ffmpeg`, `espeak-ng`) rather than embedding them.
- Reuse: both front-ends share the same core.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        CLI["CLI Front-end\naudiblez CLI"]:::frontend
        GUI["GUI Front-end\naudiblez-UI"]:::frontend
    end

    %% Application / Orchestration Layer
    subgraph "Application Layer"
        direction TB
        Core["Core Orchestration\ncore.py"]:::core
        Voices["Voices Registry\nvoices.py"]:::core
        Init["Package Init\n__init__.py"]:::core
    end

    %% Domain / Processing Layer
    subgraph "Domain Processing"
        direction TB
        TTS["TTS Synthesizer\n(PyTorch Model)"]:::domain
        WAVGen["WAV Generator"]:::domain
        Speed["Speed Adjuster\n(0.5×–2.0×)"]:::domain
    end

    %% External Infrastructure
    subgraph "External Services"
        direction TB
        HF["Hugging Face Model Hub\nKokoro-82M"]:::external
        PT["PyTorch + CUDA"]:::external
        ES["espeak-ng"]:::external
        FF["ffmpeg"]:::external
    end

    %% Storage / I/O
    subgraph "Storage / I/O"
        direction TB
        EPUB["EPUB File\nInput"]:::storage
        WAVs["chapter_N.wav Files\nTemporary"]:::storage
        M4B["book.m4b\nOutput"]:::storage
    end

    %% Configuration & Documentation
    subgraph "Config & Docs"
        direction TB
        PyProj["pyproject.toml"]:::storage
        CI1[".github/workflows/pip-install.yaml"]:::storage
        CI2[".github/workflows/git-clone-and-run.yml"]:::storage
        README["README.md"]:::storage
        LICENSE["LICENSE"]:::storage
        Samples["Demo Audio Samples\nsamples/"]:::storage
    end

    %% Testing
    subgraph "Tests"
        direction TB
        TestCLI["test_cli.py"]:::storage
        TestFind["test_find_chapters.py"]:::storage
        TestMain["test_main.py"]:::storage
    end

    %% Flows
    CLI -->|"invoke"| Core
    GUI -->|"invoke & UI updates"| Core
    Core -->|"reads"| EPUB
    Core -->|"uses"| Voices
    Core -->|"orchestrates"| TTS
    TTS -->|"synthesizes"| WAVGen
    WAVGen -->|"writes"| WAVs
    WAVs -->|"speed adjust"| Speed
    WAVs -->|"merge"| FF
    FF -->|"outputs"| M4B
    TTS -->|"fetch model from"| HF
    TTS -->|"runs on"| PT
    TTS -->|"fallback to"| ES

    %% Documentation & CI links
    Core -.-> PyProj
    Core -.-> CI1
    Core -.-> CI2
    Core -.-> README
    Core -.-> LICENSE
    Core -.-> Samples

    %% Testing interactions
    CLI -.-> TestCLI
    Core -.-> TestFind
    Core -.-> TestMain

    %% Click Events
    click CLI "https://github.com/santinic/audiblez/blob/main/audiblez/cli.py"
    click GUI "https://github.com/santinic/audiblez/blob/main/audiblez/ui.py"
    click Core "https://github.com/santinic/audiblez/blob/main/audiblez/core.py"
    click Voices "https://github.com/santinic/audiblez/blob/main/audiblez/voices.py"
    click Init "https://github.com/santinic/audiblez/blob/main/audiblez/__init__.py"
    click TestCLI "https://github.com/santinic/audiblez/blob/main/test/test_cli.py"
    click TestFind "https://github.com/santinic/audiblez/blob/main/test/test_find_chapters.py"
    click TestMain "https://github.com/santinic/audiblez/blob/main/test/test_main.py"
    click Samples "https://github.com/santinic/audiblez/tree/main/samples/"
    click PyProj "https://github.com/santinic/audiblez/blob/main/pyproject.toml"
    click CI1 "https://github.com/santinic/audiblez/blob/main/.github/workflows/pip-install.yaml"
    click CI2 "https://github.com/santinic/audiblez/blob/main/.github/workflows/git-clone-and-run.yml"
    click README "https://github.com/santinic/audiblez/blob/main/README.md"
    click LICENSE "https://github.com/santinic/audiblez/tree/main/LICENSE"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000, color:#000
    classDef core fill:#FFA500,stroke:#000, color:#000
    classDef domain fill:#FFFF00,stroke:#000, color:#000
    classDef external fill:#90EE90,stroke:#000, color:#000
    classDef storage fill:#D3D3D3,stroke:#000, color:#000
```
