Installation Guide

This guide provides instructions for installing and setting up Book Reader on your system.

Prerequisites

Before installing Book Reader, ensure you have the following:

Python 3.13.3 or higher
pip (Python package installer)
An OpenAI API key with access to the TTS API

Installation Methods

Book Reader can be installed in several ways:

Using pip (recommended for most users)
From source (for developers or latest features)
Using Docker (for containerized deployment)

Using pip

The simplest way to install Book Reader is via pip:

pip install book-reader

To install a specific version:

pip install book-reader==1.2.0

To upgrade to the latest version:

pip install --upgrade book-reader

From Source

For the latest development version or to contribute to Book Reader:

# Clone the repository
git clone https://github.com/juanfkurucz/book-reader.git
cd book-reader

# Install in development mode
pip install -e .

This creates an editable installation, where changes to the source code will be immediately available without reinstalling.

Using Docker

Book Reader is available as a Docker image, which is useful for isolated environments or deployment:

# Pull the latest image
docker pull juanfkurucz/book-reader:latest

# Test the installation
docker run --rm juanfkurucz/book-reader:latest --help

Verifying Installation

After installation, verify that Book Reader is correctly installed:

book-reader --version

You should see the current version number of Book Reader displayed.

Setting Up Your API Key

Book Reader requires an OpenAI API key to function. You can set it in several ways:

Environment variable (recommended):

export OPENAI_API_KEY="your-api-key-here"

Configuration file: Create a config.yaml file in your home directory or current working directory:
```
openai_api_key: "your-api-key-here"
```

Command line (not recommended for security reasons):

book-reader --api-key "your-api-key-here" convert document.pdf

Installation Options

Virtual Environment

It's recommended to install Book Reader within a virtual environment to avoid dependency conflicts:

# Create a virtual environment
python -m venv book-reader-env

# Activate the virtual environment
# On Windows:
book-reader-env\Scripts\activate
# On macOS/Linux:
source book-reader-env/bin/activate

# Install Book Reader
pip install book-reader

Installing Optional Dependencies

Book Reader has optional dependencies for enhanced functionality:

# Install with all optional dependencies
pip install book-reader[all]

# Install with specific optional dependencies
pip install book-reader[dev]  # Development tools
pip install book-reader[test]  # Testing tools

Troubleshooting

Common Installation Issues

Dependency Conflicts:

pip install --upgrade pip
pip install book-reader --force-reinstall

Permission Issues:
```
pip install --user book-reader
```
OpenAI API Key Not Found: Ensure your API key is correctly set as an environment variable or in the configuration file.
Module Not Found Errors:
```
pip install book-reader[all]
```

Docker Permission Issues:

# On Linux, if you get permission errors:
sudo docker pull juanfkurucz/book-reader:latest
sudo docker run --rm juanfkurucz/book-reader:latest --help

Getting Help

If you encounter issues not covered here:

Check the GitHub Issues for similar problems
Create a new issue with details about your problem
Join our community Discord for real-time help

Next Steps

After installation:

Set up your configuration file following the Configuration Guide
Try converting your first PDF to audiobook following the Usage Guide
Explore the API Documentation if you're a developer

Upgrading

To upgrade Book Reader to the latest version:

pip install --upgrade book-reader

For Docker:

docker pull juanfkurucz/book-reader:latest

Uninstallation

If you need to uninstall Book Reader:

pip uninstall book-reader

For Docker, you can remove the image:

docker rmi juanfkurucz/book-reader:latest