# Document Reader - Voice Skill Extension

Read documents aloud using local, HIPAA-compliant text-to-speech.

## Overview

The Document Reader extends Familiar's voice capabilities to read documents aloud. It uses **Piper TTS** for high-quality, fully local speech synthesis — no cloud services required, making it safe for PHI and sensitive documents.

## Features

- **Multi-format support**: DOCX, PDF, TXT, Markdown, HTML
- **Section navigation**: Read specific sections or entire documents
- **Adjustable playback**: Speed control (0.5x to 2.0x)
- **Multiple voices**: US English, British English, Spanish
- **Save to audio**: Export documents as MP3/WAV files
- **HIPAA-compliant**: All processing happens locally with Piper

## Quick Start

```python
# Read entire document
read_document({"file": "paper.docx"})

# List sections first
read_document({"file": "paper.pdf", "list_sections": True})

# Read specific section
read_document({"file": "paper.pdf", "section": 3})

# Read faster
read_document({"file": "notes.txt", "speed": 1.5})

# Save to audio file
read_document({"file": "paper.docx", "save": "paper_audio"})

# Use different voice
read_document({"file": "paper.docx", "voice": "en_GB-alba-medium"})
```

## Commands

| Command | Description |
|---------|-------------|
| `read_document` | Read a document aloud |
| `stop_reading` | Stop current playback |
| `reading_status` | Check playback status |
| `list_tts_voices` | List available voices |
| `install_piper` | Get installation instructions |

## Parameters

### read_document

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `file` | string | required | Path to document |
| `section` | int | all | Section number to read |
| `voice` | string | en_US-lessac-medium | Voice ID |
| `speed` | float | 1.0 | Speed (0.5 = slow, 2.0 = fast) |
| `save` | string | none | Filename to save audio |
| `list_sections` | bool | false | List sections only |

## Available Voices

| Voice ID | Description |
|----------|-------------|
| `en_US-lessac-medium` | US English (default) |
| `en_US-amy-medium` | US English (Amy) |
| `en_GB-alba-medium` | British English |
| `es_ES-sharvard-medium` | Spanish |

Voices are downloaded automatically on first use (~50-100MB each).

## Installation

### 1. Install Piper TTS

```bash
# Option A: pip
pip install piper-tts

# Option B: Raspberry Pi
sudo apt install piper-tts

# Option C: Pre-built binary
# Download from https://github.com/rhasspy/piper/releases
```

### 2. Install document parsers (optional but recommended)

```bash
# For DOCX support
pip install python-docx

# For PDF support  
pip install pypdf

# For HTML support
pip install beautifulsoup4
```

### 3. Install audio player

```bash
# Linux (one of these)
sudo apt install aplay      # ALSA
sudo apt install mpg123     # MP3 player
sudo apt install ffmpeg     # FFmpeg (ffplay)

# macOS
# afplay is built-in
```

## HIPAA Compliance

This module is designed for healthcare environments:

- **No cloud transmission**: Piper runs entirely locally
- **No data logging**: Audio is generated and played, not stored (unless you request save)
- **PHI safe**: Patient documents can be read without data leaving the device

For maximum security, use the local Ollama model for document summarization before reading.

## Examples

### Read your IPT papers

```python
# List what's in the paper
read_document({"file": "01_IPT_Teleparallel_Complete.docx", "list_sections": True})

# Read the abstract (usually section 0)
read_document({"file": "01_IPT_Teleparallel_Complete.docx", "section": 0})

# Read section 7 (Mass Predictions)
read_document({"file": "01_IPT_Teleparallel_Complete.docx", "section": 7})
```

### Create audiobook version

```python
# Save entire document as audio
read_document({
    "file": "paper.docx",
    "save": "paper_audiobook",
    "speed": 0.9,  # Slightly slower for comprehension
    "voice": "en_GB-alba-medium"
})
```

### Healthcare use case

```python
# Read patient summary to clinician (hands-free)
read_document({"file": "/var/lib/familiar/hipaa-data/patient_summary.txt"})
```

## Technical Notes

### Text Processing

The reader automatically:
- Converts abbreviations (Dr. → Doctor, e.g. → for example)
- Expands Greek letters (α → alpha, φ → phi)
- Handles mathematical notation (x^2 → x to the power of 2)
- Removes URLs and email addresses
- Cleans whitespace

### Section Detection

- **DOCX**: Detects Heading styles (Heading 1, Heading 2, etc.)
- **Markdown**: Detects # headers
- **Other formats**: Splits into ~500 word chunks

### Performance

| Device | Model | Speed |
|--------|-------|-------|
| Raspberry Pi 4 | Piper medium | ~1.5x realtime |
| Raspberry Pi 5 | Piper medium | ~3x realtime |
| Desktop CPU | Piper medium | ~10x realtime |

## Troubleshooting

### "Piper not installed"
Run `pip install piper-tts` or see `install_piper` command.

### "No audio output"
Install an audio player: `sudo apt install aplay mpg123`

### "Could not extract text"
Install document parsers: `pip install python-docx pypdf beautifulsoup4`

### Voice download fails
Check internet connection. Voices download from HuggingFace (~50-100MB).

## Integration

The document reader integrates with the main voice skill. Import it in your code:

```python
from familiar.skills.voice.document_reader import (
    read_document,
    read_aloud,
    stop_reading,
    DOCUMENT_READER_TOOLS
)

# Direct text reading
read_aloud("The fine structure constant α equals 1/137.")

# Document reading
read_document({"file": "paper.pdf", "section": 0})
```

## Author

George Scott Foley  
ORCID: 0009-0006-4957-0540  
Georgescottfoley@proton.me

Part of the Familiar Self-Hosted AI Companion Platform.
