How santinic/audiblez works
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.