# elmatthe/audiobook-creation-tool architecture

> Architecture diagram of the GitHub repository elmatthe/audiobook-creation-tool, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/elmatthe/audiobook-creation-tool
- Repository: https://github.com/elmatthe/audiobook-creation-tool

## Overview

Audiobook Creation Tool is a Windows/macOS desktop app for turning PDF/TXT books into narrated audio, then preparing audiobook files and cover art. The main user journey is launch the app, choose a voice and source, synthesize speech, and export audio; users can also combine, convert, and tag existing audio. Voice installation and platform-specific engine availability are distinct setup stages. The graph includes major README capabilities and a shared runtime layer. Several implementation links are unverified because the relevant source was not excerpted, so they are dashed rather than asserted as observed calls.

Main entry points: [`scripts/tts/epub2tts_gui.py`](https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/tts/epub2tts_gui.py) (TTS Audiobook), [`scripts/tts/speech/pipeline.py`](https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/tts/speech/pipeline.py) (Speech preparation), [`scripts/launcher.py`](https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/launcher.py) (App launcher), [`scripts/tts/kokoro_synth.py`](https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/tts/kokoro_synth.py) (Kokoro synthesis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Desktop app"]
  node_launcher["App launcher<br/>[launcher.py]"]
  node_tts_ui["TTS Audiobook<br/>[epub2tts_gui.py]"]
end

subgraph group_speech["Narration"]
  node_extract["PDF extraction<br/>[pdf_extractor.py]"]
  node_speech_doc["Speech document<br/>[document.py]"]
  node_speech_prep["Speech preparation<br/>[pipeline.py]"]
  node_voices[("Voice registry<br/>[voice_registry.py]")]
  node_engine_policy["Engine policy<br/>[engine_policy.py]"]
  node_kokoro["Kokoro synthesis<br/>[kokoro_synth.py]"]
  node_chatterbox["Chatterbox synthesis"]
  node_qwen["Qwen3 runtime<br/>[qwen3_runtime.py]"]
  node_omnivoice["OmniVoice synthesis<br/>[omnivoice_synth.py]"]
  node_publication["Audio publication<br/>[publication.py]"]
end

subgraph group_setup["Voice setup"]
  node_voice_setup["Optional voice setup<br/>[optional_setup.py]"]
end

subgraph group_audio["Audiobook tools"]
  node_mp3["MP3 tools<br/>[mp3_tool.py]"]
  node_m4b_maker["M4B maker<br/>[m4b_maker.py]"]
  node_m4b_convert["M4B converter<br/>[m4b_converter.py]"]
  node_metadata["Metadata editor"]
  node_artwork["Cover artwork<br/>[m4b_artwork_ui.py]"]
end

subgraph group_runtime["Shared runtime"]
  node_ffmpeg["FFmpeg integration<br/>[ffmpeg_utils.py]"]
  node_workspace["Book workspace<br/>[book_workspace.py]"]
  node_config["Configuration<br/>[config.py]"]
end

node_user(("Reader"))

node_user -->|"starts"| node_launcher
node_launcher -.->|"opens"| node_tts_ui
node_user -->|"chooses source"| node_tts_ui
node_tts_ui -.->|"loads PDF"| node_extract
node_extract -.->|"provides text"| node_speech_doc
node_speech_doc -->|"prepares text"| node_speech_prep
node_tts_ui -.->|"selects voice"| node_voices
node_tts_ui -.->|"checks availability"| node_engine_policy
node_speech_prep -.->|"prepares route text"| node_kokoro
node_speech_prep -.->|"prepares route text"| node_chatterbox
node_speech_prep -.->|"prepares route text"| node_qwen
node_speech_prep -.->|"prepares route text"| node_omnivoice
node_tts_ui -->|"installs on demand"| node_voice_setup
node_kokoro -.->|"exports audio"| node_publication
node_chatterbox -.->|"exports audio"| node_publication
node_user -->|"combines audio"| node_m4b_maker
node_user -->|"converts audio"| node_m4b_convert
node_user -->|"edits tags"| node_metadata
node_user -->|"prepares covers"| node_artwork
node_user -.->|"works with MP3"| node_mp3
node_kokoro -->|"exports via"| node_ffmpeg
node_chatterbox -->|"uses audio tools"| node_ffmpeg
node_tts_ui -.->|"uses workspace"| node_workspace
node_launcher -.->|"loads settings"| node_config

click node_launcher "https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/launcher.py"
click node_tts_ui "https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/tts/epub2tts_gui.py"
click node_extract "https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/tts/pdf_extractor.py"
click node_speech_doc "https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/tts/speech/document.py"
click node_speech_prep "https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/tts/speech/pipeline.py"
click node_voices "https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/tts/voice_registry.py"
click node_engine_policy "https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/shared/engine_policy.py"
click node_kokoro "https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/tts/kokoro_synth.py"
click node_chatterbox "https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/tts/chatterbox_synth.py"
click node_qwen "https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/tts/qwen3_runtime.py"
click node_omnivoice "https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/tts/omnivoice_synth.py"
click node_voice_setup "https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/tts/optional_setup.py"
click node_mp3 "https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/mp3/mp3_tool.py"
click node_m4b_maker "https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/m4b/maker/m4b_maker.py"
click node_m4b_convert "https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/m4b/converter/m4b_converter.py"
click node_metadata "https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/m4b/metadata/m4b_metadata_editor.py"
click node_artwork "https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/artwork/m4b_artwork_ui.py"
click node_publication "https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/tts/publication.py"
click node_ffmpeg "https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/shared/ffmpeg_utils.py"
click node_workspace "https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/shared/book_workspace.py"
click node_config "https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/shared/config.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_launcher,node_tts_ui toneBlue
class node_extract,node_speech_doc,node_speech_prep,node_voices,node_engine_policy,node_kokoro,node_chatterbox,node_qwen,node_omnivoice,node_publication toneAmber
class node_voice_setup toneMint
class node_mp3,node_m4b_maker,node_m4b_convert,node_metadata,node_artwork toneRose
class node_ffmpeg,node_workspace,node_config,node_user toneIndigo
```

## Components

### Desktop app

- [App launcher](https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/launcher.py): `scripts/launcher.py`
- [TTS Audiobook](https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/tts/epub2tts_gui.py): `scripts/tts/epub2tts_gui.py`

### Narration

- [PDF extraction](https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/tts/pdf_extractor.py): `scripts/tts/pdf_extractor.py`
- [Speech document](https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/tts/speech/document.py): `scripts/tts/speech/document.py`
- [Speech preparation](https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/tts/speech/pipeline.py): `scripts/tts/speech/pipeline.py`
- [Voice registry](https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/tts/voice_registry.py): `scripts/tts/voice_registry.py`
- [Engine policy](https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/shared/engine_policy.py): `scripts/shared/engine_policy.py`
- [Kokoro synthesis](https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/tts/kokoro_synth.py): `scripts/tts/kokoro_synth.py`
- [Chatterbox synthesis](https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/tts/chatterbox_synth.py): `scripts/tts/chatterbox_synth.py`
- [Qwen3 runtime](https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/tts/qwen3_runtime.py): `scripts/tts/qwen3_runtime.py`
- [OmniVoice synthesis](https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/tts/omnivoice_synth.py): `scripts/tts/omnivoice_synth.py`
- [Audio publication](https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/tts/publication.py): `scripts/tts/publication.py`

### Voice setup

- [Optional voice setup](https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/tts/optional_setup.py): `scripts/tts/optional_setup.py`

### Audiobook tools

- [MP3 tools](https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/mp3/mp3_tool.py): `scripts/mp3/mp3_tool.py`
- [M4B maker](https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/m4b/maker/m4b_maker.py): `scripts/m4b/maker/m4b_maker.py`
- [M4B converter](https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/m4b/converter/m4b_converter.py): `scripts/m4b/converter/m4b_converter.py`
- [Metadata editor](https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/m4b/metadata/m4b_metadata_editor.py): `scripts/m4b/metadata/m4b_metadata_editor.py`
- [Cover artwork](https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/artwork/m4b_artwork_ui.py): `scripts/artwork/m4b_artwork_ui.py`

### Shared runtime

- [FFmpeg integration](https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/shared/ffmpeg_utils.py): `scripts/shared/ffmpeg_utils.py`
- [Book workspace](https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/shared/book_workspace.py): `scripts/shared/book_workspace.py`
- [Configuration](https://github.com/elmatthe/audiobook-creation-tool/blob/master/scripts/shared/config.py): `scripts/shared/config.py`

### Other components

- **Reader**

## Connections

- Reader → App launcher: starts (evidence: `README.md`)
- App launcher → TTS Audiobook: opens
- Reader → TTS Audiobook: chooses source (evidence: `README.md`)
- TTS Audiobook → PDF extraction: loads PDF
- PDF extraction → Speech document: provides text
- Speech document → Speech preparation: prepares text (evidence: `scripts/tts/speech/pipeline.py`)
- TTS Audiobook → Voice registry: selects voice
- TTS Audiobook → Engine policy: checks availability
- Speech preparation → Kokoro synthesis: prepares route text (evidence: `scripts/tts/kokoro_synth.py`)
- Speech preparation → Chatterbox synthesis: prepares route text (evidence: `scripts/tts/chatterbox_synth.py`)
- Speech preparation → Qwen3 runtime: prepares route text
- Speech preparation → OmniVoice synthesis: prepares route text
- TTS Audiobook → Optional voice setup: installs on demand (evidence: `README.md`)
- Kokoro synthesis → Audio publication: exports audio
- Chatterbox synthesis → Audio publication: exports audio
- Reader → M4B maker: combines audio (evidence: `README.md`)
- Reader → M4B converter: converts audio (evidence: `README.md`)
- Reader → Metadata editor: edits tags (evidence: `README.md`)
- Reader → Cover artwork: prepares covers (evidence: `README.md`)
- Reader → MP3 tools: works with MP3
- Kokoro synthesis → FFmpeg integration: exports via (evidence: `scripts/tts/kokoro_synth.py`)
- Chatterbox synthesis → FFmpeg integration: uses audio tools (evidence: `scripts/tts/chatterbox_synth.py`)
- TTS Audiobook → Book workspace: uses workspace
- App launcher → Configuration: loads settings
