Transform your PDFs into engaging audiobooks with the power of OCR, LLMs, and TTS in 16 languages.

Table of Contents

• Introduction
• Features
• Demo
• Supported Languages
• Roadmap
• Installation
• Usage
  • Command-Line Interface
  • Streamlit Web Application
• Contributing
  • Style Guidelines
  • Testing
• License

Introduction

🎉 Welcome to NarratorX! 🎉 For the longest time, I found myself saying, "Ah shucks, there's no audiobook for this one… guess I'll have to wait or squeeze in some reading when I have free time." If you’re like me and love listening to audiobooks while doing chores 🧹, commuting 🚶, or just relaxing 😌, then I guess this tool was made for you!

📚 With NarratorX, you can freely convert the PDF of that book that’s been lingering on your to-read list into a beautifully narrated, non-robotic audiobook. Say hello to NarratorX – savior of the busy and the lazy! By harnessing advanced OCR 🔍, powerful LLMs 🤖, and state-of-the-art TTS 🎙️, NarratorX transforms your PDFs into immersive audiobooks, ready to accompany you wherever you go. And all for free, my favorite kinda payment method...

NarratorX is a passion project, specially crafted for my book club 📖💬. With support for 16 languages 🌍, it’s perfect for readers worldwide. I hope it brings you joy too! So go on, read away and listen away! 🎧✨

Features

🚀 Feature	✨ Description
Seamless PDF to Audiobook Conversion 🎧	Effortlessly convert your PDFs into high-quality audiobooks using OCR 🔍, LLMs 🤖, and TTS 🎙️, fully automating the process from text extraction to speech generation.
Multi-Language Support 🌍	Supports 16 languages, including English, Spanish, French, German, Turkish, and more, making NarratorX accessible to a global audience.
Open-Source LLM Integration 🔓	Leverage the Ollama library for local, open-source LLMs. OpenAI is optional, offering flexibility for users with different needs.
User-Friendly Interfaces 🖥️	Use either the command-line interface for quick, scriptable conversions or the Streamlit web app for a visual, interactive experience.
Customizable Settings 🎛️	Fine-tune your experience by adjusting chunk sizes, selecting models, and choosing language preferences to suit each document.
Robust Error Handling and Logging 🛠️	With comprehensive error handling and logging, NarratorX ensures smooth operation and easy troubleshooting if issues arise.

---

Demo

demo.mp4

🎧 Sample Audiobook Conversions Here are some sample audiobook conversions created with NarratorX! (Not cherry-picked – just pure NarratorX magic ✨)

🌐 Language	📚 Book Title	🔊 Sample Audio
🇺🇸 English	"The Little Prince" by Antoine de Saint-Exupéry	Listen 🎶
🇪🇸 Spanish	"Don Quijote" by Miguel de Cervantes	Escuchar 🎶
🇫🇷 French	"Les Misérables" by Victor Hugo	Écouter 🎶
🇹🇷 Turkish	"Tüfek, Mikrop ve Çelik" by Jared Diamond	Dinle 🎶

---

Supported Languages 🌍

NarratorX supports a wide array of languages, making it accessible for many readers around the world! 🌐 The currently supported languages are:

• 🇺🇸 English (en)
• 🇪🇸 Spanish (es)
• 🇫🇷 French (fr)
• 🇩🇪 German (de)
• 🇮🇹 Italian (it)
• 🇵🇹 Portuguese (pt)
• 🇵🇱 Polish (pl)
• 🇹🇷 Turkish (tr)
• 🇷🇺 Russian (ru)
• 🇳🇱 Dutch (nl)
• 🇨🇿 Czech (cs)
• 🇸🇦 Arabic (ar)
• 🇨🇳 Chinese (zh-cn)
• 🇯🇵 Japanese (ja)
• 🇭🇺 Hungarian (hu)
• 🇰🇷 Korean (ko)

With NarratorX, the world of audiobooks is just a language selection away! 🌎📖🎶

Roadmap

Here's what's on the horizon:

• Enhanced LLM Options: Integration with additional open-source LLMs and libraries.
• Custom TTS Voices: Support for custom TTS voices and accents.
• Enhanced Chunking and OCR: I am planning to move to open-parse for better OCR results.
• Support for additional file formats: EPUB, DOCX, Image, and plain text support.
• Automated Chunk Size Optimization: Automatically adjust chunk sizes based on model capabilities and language requirements.
• Improved UI/UX: Enhancements to the Streamlit app for a more intuitive user experience.
  • Add a stopping option.
  • Add step-wise processing - OCR, LLM, TTS.

I welcome all contributions! If you have ideas, suggestions, or want to contribute, feel free to reach out.

---

Installation

Prerequisites

Before you begin, ensure you have the following installed:

• Python 3.8 or higher: Download Python
• Poetry: A tool for dependency management.

  pip install poetry

• CUDA (Optional): For GPU acceleration with CUDA-compatible GPUs. This can significantly speed up processing times.

Steps

1. Clone the Repository

   Start by cloning the NarratorX repository to your local machine:

   git clone https://github.com/bedirt/narratorx.git
   cd narratorx

2. Install Dependencies

   Use Poetry to install all required dependencies:

   poetry install

3. Set Up Environment Variables

   NarratorX can work with both OpenAI's GPT models and local open-source LLMs via the Ollama library.

   • If you want to use OpenAI Models:

     Obtain your OpenAI API key and set it as an environment variable:

     export OPENAI_API_KEY='your-openai-api-key'

4. (Optional - Just for Contributing) Install Pre-commit Hooks

   If you plan to contribute to NarratorX, set up pre-commit hooks to maintain code quality:

   pre-commit install

---

Usage

I implemented two ways to use NarratorX. You can choose between the command-line interface for quick operations or the Streamlit web app for a more interactive experience.

Command-Line Interface

Convert your PDF to an audiobook directly from the terminal:

narratorx path/to/yourfile.pdf --output output.wav --language en --model gpt-4o --log-level INFO

Parameters Explained:

• path/to/yourfile.pdf: The path to the PDF you wish to convert.
• --output, -o: (Optional) The path where the output audio file will be saved. Defaults to output.wav.
• --language, -l: (Optional) The language code of your PDF content (e.g., en for English, tr for Turkish).
• --model, -m: (Optional) The LLM model to use. Options include gpt-4o, gpt-4o-mini, or any model supported by the Ollama library like llama3.1. You can see ollama models here. Do not forget to use ollama/ prefix for ollama models.
• --max-characters-llm: (Optional) Maximum characters per LLM chunk. Adjust based on model capabilities. 2-4k is a good starting point.
• --max-tokens: (Optional) Maximum tokens per LLM call. Adjust based on model capabilities. 2-4k is a good starting point again.
• --max-characters-tts: (Optional) Maximum characters per TTS chunk. This value should be changed based on the language you are using, if you get a warning Warning: The text length exceeds the character limit of 239 for language 'es', this might cause truncated audio. you should decrese this value to be the same as the warning message. (I will automate this soon, lazy at the moment :))
• --log-level: (Optional) Set the logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL).

Example:

Using an open-source LLM with Ollama:

narratorx path/to/yourfile.pdf --output output.wav --language en --model ollama/llama3.1 --log-level INFO

Streamlit Web Application

For a more user-friendly interface, use the Streamlit app:

streamlit run streamlit_app.py

Open your web browser and navigate to http://localhost:8501. Here, you can:

• Upload your PDF file (up to 200MB).
• Select the language and preferred LLM model.
• Adjust advanced settings such as chunk sizes (optional).
• Monitor the progress of each processing step.
• Listen to a preview and download the final audiobook.

---

Contributing

Love contributions! Whether it's bug fixes, new features, or documentation improvements, your help is invaluable, and I appreciate it.

Style Guidelines

To maintain code quality and consistency, please adhere to the following guidelines:

• Code Formatting: Use black for code formatting with a line length of 100 characters. This ensures that all code follows a consistent style.

  black --line-length 100 .

• Import Sorting: Use isort with the black profile to sort imports correctly.

  isort --profile black .

• Linting: Use flake8 to lint your code and catch potential issues.

  flake8

• Pre-commit Hooks: We have pre-commit hooks set up to automate these checks before each commit. Install them with:

  pre-commit install

  Pre-commit Configuration:

  repos:
    - repo: local
      hooks:
        - id: black
          name: black
          entry: poetry run black --line-length 100 --exclude '.venv/*'
          language: system
          types: [python]
        - id: flake8
          name: flake8
          entry: poetry run flake8 --exclude .venv --config .flake8
          language: system
          types: [python]
        - id: isort
          name: isort
          entry: poetry run isort --profile black --skip .venv
          language: system
          types: [python]

  You can ignore all others, and just install pre-commit hooks with the command above, and (since I already have the configuration file) you can use pre-commit run --all-files to run all checks.

Testing

Ensure your changes don't break existing functionality by running tests:

1. Install Test Dependencies

   poetry install --with dev

2. Run Tests

   python -m unittest discover tests/

3. Test Specific Modules

   python -m unittest tests/test_llm.py

How to Contribute

1. Fork the Repository

   Click the "Fork" button at the top right corner of the repository page.

2. Clone Your Fork

   git clone https://github.com/yourusername/narratorx.git
   cd narratorx

3. Create a New Branch

   git checkout -b feature/your-feature-name

4. Make Your Changes

   Write code, fix bugs, or improve documentation.

5. Format and Lint Your Code

   black --line-length 100 .
   isort --profile black .
   flake8

   or simply:

   pre-commit run --all-files

6. Commit Your Changes

   git add .
   git commit -m "Add your descriptive commit message here"

7. Push to Your Fork

   git push origin feature/your-feature-name

8. Open a Pull Request

   Go to the original repository and open a pull request. Provide a clear description of your changes.

---

License

NarratorX is licensed under the GNU General Public License v3.0. By contributing to this project, you agree that your contributions will be licensed under its GPLv3.

See the LICENSE file for more details.

---

Acknowledgements

I made use of the following libraries and tools to build NarratorX and am grateful for all their contributions:

• OpenAI
• Ollama
• Coqui/TTS
• Streamlit
• Surya-OCR
• Unstructured
• LiteLLM

---

Thank you for using NarratorX! I am excited to see how you transform your reading experience. If you have any questions, suggestions, or need assistance, feel free to open an issue or reach out.

You can add me on goodreads here.

Happy listening! 🎧📖