{"id":28592851,"url":"https://github.com/marcusrprojects/audiobook-generator","last_synced_at":"2025-06-11T10:14:05.565Z","repository":{"id":290116840,"uuid":"973416678","full_name":"marcusrprojects/audiobook-generator","owner":"marcusrprojects","description":"Generate audiobooks from PDFs, EPUBs, and text files using local Piper TTS models.","archived":false,"fork":false,"pushed_at":"2025-05-04T23:00:06.000Z","size":41,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-17T06:11:22.517Z","etag":null,"topics":["audio","audiobooks","ebook","open-source","piper","python","text-to-speech","tts"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marcusrprojects.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-27T00:07:34.000Z","updated_at":"2025-05-04T23:00:09.000Z","dependencies_parsed_at":"2025-04-27T01:33:37.467Z","dependency_job_id":null,"html_url":"https://github.com/marcusrprojects/audiobook-generator","commit_stats":null,"previous_names":["marcusrprojects/audiobook-generator"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcusrprojects%2Faudiobook-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcusrprojects%2Faudiobook-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcusrprojects%2Faudiobook-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcusrprojects%2Faudiobook-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marcusrprojects","download_url":"https://codeload.github.com/marcusrprojects/audiobook-generator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcusrprojects%2Faudiobook-generator/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259244905,"owners_count":22827732,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audio","audiobooks","ebook","open-source","piper","python","text-to-speech","tts"],"created_at":"2025-06-11T10:14:04.871Z","updated_at":"2025-06-11T10:14:05.548Z","avatar_url":"https://github.com/marcusrprojects.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 📖 Audiobook Generator\n\n[![Latest Release](https://img.shields.io/github/v/release/marcusrprojects/audiobook-generator?label=release)](https://github.com/marcusrprojects/audiobook-generator/releases)\n[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue)](https://www.python.org/)\n\nTurn any **PDF**, **EPUB**, or **TXT** file into a natural-sounding **audiobook** using **Piper TTS**.\nEverything runs **locally** — no internet connection or server required after setup.\n\n---\n\n## 🚀 TL;DR Quick Start\n\nFor those familiar with Python development:\n\n```bash\n# 1. Clone the repository\ngit clone https://github.com/marcusrprojects/audiobook-generator.git\ncd audiobook-generator\n\n# 2. Create \u0026 activate virtual environment (macOS/Linux example)\npython3 -m venv .venv \u0026\u0026 source .venv/bin/activate\n\n# 3. Install Piper TTS packages manually first\npip install piper-tts --no-deps\npip install piper-phonemize-cross\n\n# 4. Install the package and its other dependencies\npip install . # Installs audiobook-generator and requirements.txt deps\n\n# 5. Download default English voice models (requires bash/curl)\nbash download_voices.sh\n\n# 6. Generate an audiobook!\naudiobook-gen path/to/your_book.epub path/to/output/audio.mp3\n```\n\n\u003csub\u003eWindows Users: Use PowerShell/CMD for venv activation (see detailed steps below). For `download_voices.sh`, use WSL2, Git Bash, or download models manually.\u003c/sub\u003e\n\n---\n\n## 🚀 Features\n\n- 📚 Supports **PDF**, **EPUB**, and **plain text** formats\n- 🗣️ Multiple **Piper TTS** voices (American and British English)\n- ⏸️ Smart pauses after sentences, commas, and paragraphs\n- 🛠️ Text normalization (expand numbers, abbreviations)\n- 🎵 Outputs standard **WAV** or **MP3** files\n- 🏷️ Add metadata (title, artist) to MP3 files\n- 💻 100% offline — no server, no data collection\n- ⚙️ Simple command-line interface\n\n---\n\n## 🛠 Installation\n\nFollow these steps to set up the project and its dependencies.\n\n1. **Clone the repository**:\n\n    ```bash\n    git clone https://github.com/marcusrprojects/audiobook-generator.git\n    cd audiobook-generator\n    ```\n\n2. **Create and activate a virtual environment** (recommended):\n\n    ```bash\n    # macOS / Linux\n    python3 -m venv .venv\n    source .venv/bin/activate\n\n    # Windows (Command Prompt)\n    python -m venv .venv\n    .venv\\Scripts\\activate.bat\n\n    # Windows (PowerShell)\n    python -m venv .venv\n    .venv\\Scripts\\Activate.ps1\n    ```\n\n3. **Install Piper TTS Packages Manually**:\n  *These specific packages often need manual installation first due to their dependencies or naming conventions.*\n\n    ```bash\n    pip install piper-tts --no-deps\n    pip install piper-phonemize-cross\n    ```\n\n4. **Install the remaining dependencies**:\n\n    ```bash\n    pip install -r requirements.txt\n    ```\n\n5. **Install the `audiobook-generator` package**:\n    *This step reads `setup.py` and makes the `audiobook-gen` command available in your active environment.*\n\n    ```bash\n    pip install .\n    ```\n\n6. **Download voice models**:\n  *See the \"Downloading Voice Models\" section below for details. The easiest way is using the provided script (requires `bash` and `curl`):*\n\n    ```bash\n    bash download_voices.sh\n    ```\n  \n  *(If `bash` is unavailable, see manual download instructions below).*\n\n\u003e **Note:** `requirements.txt` includes all non-Piper dependencies. The two Piper packages must be installed manually due to naming differences.\n\n---\n\n## 📥 Downloading Voice Models\n\nThis tool uses **Piper TTS models** (ONNX format) for speech synthesis.\n\nYou can download free voice models from [HuggingFace Piper Voices](https://huggingface.co/rhasspy/piper-voices).\n\n### Easy method (recommended)\n\nRun the included script:\n\n```bash\nbash download_voices.sh\n```\n\n### Manual method (example for Joe)\n\n```bash\nmkdir -p voices/en_US/joe-medium\ncd voices/en_US/joe-medium\ncurl -L -o en_US-joe-medium.onnx \\\n  https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/joe/medium/en_US-joe-medium.onnx\ncurl -L -o en_US-joe-medium.onnx.json \\\n  https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/joe/medium/en_US-joe-medium.onnx.json\ncd ../../../..\n```\n\nRecommended Voices:\n\n| Voice                          | Path                                              | Notes                           |\n|:-------------------------------|:--------------------------------------------------|:--------------------------------|\n| **LibriTTS R (US, medium)**    | `voices/en_US/libritts_r-medium/`                 | Neutral American narrator       |\n| **Joe (US, medium)**           | `voices/en_US/joe-medium/`                        | Clear American male             |\n| **Cori (UK, high quality)**    | `voices/en_GB/cori-high/`                         | High-quality British female     |\n| **Jenny Dioco (UK, medium)**   | `voices/en_GB/jenny_dioco-medium/`                | Warm British voice              |\n\n---\n\n## 🌟 Usage (After Installation via `pip install .`)\n\nEnsure your virtual environment is active (`source .venv/bin/activate` or `.venv\\Scripts\\activate`). You can then use the audiobook-gen command:\n\n```bash\naudiobook-gen input_file.pdf output_file.mp3\n```\n\nBy default, the **LibriTTS R (US, medium)** voice is used. To specify a different model:\n*(Use the path to the desired `.onnx` model file)*\n\n```bash\naudiobook-gen input_file.epub output_file.wav \\\n  --model voices/en_GB/cori-high/en_GB-cori-high.onnx\n```\n\nSpecify input format (EPUB) and output format (WAV):\n\n```bash\naudiobook-gen path/to/novel.epub final_audio.wav\n```\n\nAdd metadata (MP3 only):\n\n```bash\naudiobook-gen book.txt audiobook.mp3 \\\n  --title \"My Audiobook\" --artist \"Author Name\"\n```\n\nList available bundled voice models:\n*(Lists voices defined in the script's `AVAILABLE_VOICES` list)*\n\n```bash\naudiobook-gen --list-models\n```\n\nShow help message:\n*(Displays all available command-line options)*\n\n```bash\naudiobook-gen --help\n```\n\n---\n\n## 📚 Supported Formats\n\n- `.pdf` (scanned PDFs with selectable text)\n- `.epub` (standard e-book format)\n- `.txt` (plain text files, UTF-8 encoding preferred)\n\n---\n\n## 🧐 How It Works\n\n- Extracts and normalizes text from your document\n- Splits text intelligently by sentences and commas\n- Synthesizes natural-sounding speech with pauses\n- Outputs ready-to-listen WAV or MP3 files\n\n---\n\n## 📝 Requirements\n\n- Python 3.8 or higher\n- ONNX Runtime\n- Piper TTS models\n- Listed in [`requirements.txt`](requirements.txt) (non-Piper dependencies)\n- Manual install for `piper-tts` and `piper-phonemize-cross`\n\n---\n\n## 📦 Creating a Standalone Executable (Optional Alternative)\n\nIf you want to distribute this tool to users who might not have Python installed, you can bundle it into a single executable file using [PyInstaller](https://pyinstaller.org/). This is typically done by the developer for distribution.\n\n**Steps to Create the Executable:**\n\n1. Make sure you have followed the Installation steps 1-4 (you need the dependencies installed).\n2. Install PyInstaller in your virtual environment:\n\n```bash\npip install pyinstaller\n```\n\n3. Run PyInstaller from the project's root directory (`audiobook-generator/`):\n\n```bash\npyinstaller --onefile audiobook_generator.py\n```\n\n*This process can take a significant amount of time and requires substantial disk space. It analyzes dependencies and bundles everything. The final executable will be placed inside a new `dist/` folder.*\n\n**Running the Standalone Executable:**\n\nOnce built, the executable in the `dist` folder can be run directly without needing Python or the virtual environment.\n\n```bash\n# Example on macOS/Linux:\ncd dist\n./audiobook_generator ../path/to/book.pdf output.mp3 --model ../voices/en_US/joe-medium/en_US-joe-medium.onnx\n\n# Example on Windows:\ncd dist\n.\\audiobook_generator.exe ..\\path\\to\\book.pdf output.mp3 --model ..\\voices\\en_US\\joe-medium\\en_US-joe-medium.onnx\n```\n\n*Note: Paths to input files and models are relative to where you run the command.*\n\n---\n\n## ✨ Future Plans\n\n- Batch conversion\n- Desktop GUI version (Tauri or Electron)\n- Additional language support\n\n---\n\n## 📩 Contact\n\nOpen an issue on [GitHub](https://github.com/marcusrprojects/audiobook-generator/issues).\n\n---\n\n## 🏁 Let's turn your books into audiobooks!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcusrprojects%2Faudiobook-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarcusrprojects%2Faudiobook-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcusrprojects%2Faudiobook-generator/lists"}