# System Requirements

This document lists the **server-level** (OS-level) packages that must be
installed in addition to the Python packages in `requirements.txt`.

## Always required

| Package | Install command (Ubuntu/Debian) | Purpose |
|---------|--------------------------------|---------|
| `ffmpeg` | `sudo apt install ffmpeg` | Audio and video conversion |

## Required for PDF server-side tools

The following tools power **Word/PowerPoint/Excel → PDF** and
**PDF → Word/PowerPoint** conversions.

| Package | Install command | Purpose |
|---------|----------------|---------|
| `libreoffice` | `sudo apt install libreoffice` | Office format conversion (Word↔PDF, PPT↔PDF, Excel↔PDF) |

> If LibreOffice is not installed, these five tools will show a clear error
> message on the output page rather than silently failing.
>
> **pdf-to-word** has a pure-Python fallback (PyMuPDF + python-docx) that
> works even without LibreOffice — text content only, no images or layout.

## Required for OCR (Image/PDF → Text)

| Package | Install command | Purpose |
|---------|----------------|---------|
| `tesseract-ocr` | `sudo apt install tesseract-ocr` | OCR engine |
| `poppler-utils` | `sudo apt install poppler-utils` | Render PDF pages to images for OCR |

Additional language packs (optional):
```
sudo apt install tesseract-ocr-deu   # German
sudo apt install tesseract-ocr-fra   # French
sudo apt install tesseract-ocr-spa   # Spanish
# Full list: apt-cache search tesseract-ocr
```

## Required for AI Speech-to-Text Transcription

No additional **system** packages are needed beyond `ffmpeg` (already listed
above). The **Python** package `openai-whisper` (listed in `requirements.txt`)
downloads model weights automatically on first use.

| Model | RAM needed | Disk | Speed | Accuracy |
|-------|-----------|------|-------|----------|
| `tiny` (default) | ~1 GB | ~75 MB | Very fast | Good |
| `base` | ~1 GB | ~145 MB | Fast | Better |
| `small` | ~2 GB | ~465 MB | Medium | Good |
| `medium` | ~5 GB | ~1.5 GB | Slow | Very good |
| `large` | ~10 GB | ~2.9 GB | Slowest | Best |

Set the model via environment variable (default is `tiny`):
```
WHISPER_MODEL=small
```

## Required for Text-to-Speech (TTS)

| Package | Install command | Purpose |
|---------|----------------|---------|
| `espeak-ng` | `sudo apt install espeak-ng` | Text-to-speech engine used by the TTS converter |
| `ffmpeg` | Already required above | Encode espeak WAV output to MP3/OGG/FLAC |

The TTS converter uses espeak-ng to synthesise speech from documents and ebooks,
then optionally re-encodes the raw WAV to MP3, OGG, or FLAC via ffmpeg.

Additional language voices for espeak-ng are bundled with the package — no extra
installs needed for common languages (English, German, French, Spanish, etc.).

## Quick-install all system dependencies

```bash
sudo apt update
sudo apt install -y ffmpeg libreoffice tesseract-ocr poppler-utils espeak-ng
```

## Fedora / RHEL

```bash
sudo dnf install ffmpeg libreoffice tesseract poppler-utils espeak-ng
```

## macOS (Homebrew)

```bash
brew install ffmpeg libreoffice tesseract poppler espeak-ng
```