TextReader

A cross-platform text-to-speech converter that transforms web articles, ebooks, PDFs, and documents into audio files for listening on Linux, Windows, and Android devices.

Features

📄 Multiple Input Sources

• Web URLs - Extract and convert articles from any website
• Documents - PDFs, EPUB, MOBI/Kindle files (with Calibre)
• Direct Input - Plain text, Markdown, HTML
• Batch Processing - Convert multiple URLs concurrently

🎤 Flexible Text-to-Speech

• Local Engines - pyttsx3 for offline use
• Cloud TTS - Google Text-to-Speech (gTTS) for high quality
• Smart Splitting - Automatically handles long texts
• MP3 Output - Configurable bitrate

📚 Audio Library Management

• Automatic Organization - All converted audio saved to library
• Search & Filter - Find items by title, author, or tags
• Statistics - Track your listening habits
• Resume Playback - Pick up where you left off

🎵 Audio Playback

• Built-in Player - Play audio directly from CLI
• Progress Tracking - Automatic position saving
• Queue Support - Play multiple items sequentially

🔄 Batch Operations

• Concurrent Processing - Convert multiple URLs simultaneously
• Error Handling - Continue on failure, track errors
• Progress Display - Real-time status updates

Installation

Prerequisites

• Python 3.8 or higher
• pip (Python package manager)

Setup

# Clone the repository
cd /home/david/Projects/TextReader

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .

Optional: Calibre (for MOBI/Kindle files)

# Install Calibre for MOBI/AZW support
# Ubuntu/Debian:
sudo apt install calibre

# Or download from: https://calibre-ebook.com/download

Quick Start

Convert Text to Audio

# Direct text input
textreader convert --text "Hello! This is a test."

# From a web article
textreader convert https://example.com/article

# From a PDF file
textreader convert document.pdf

# From markdown file
textreader convert article.md --format markdown

# Choose TTS engine
textreader convert --text "Hello world" --engine gtts

# Custom title and output location
textreader convert article.pdf --title "My Article" --output ~/audio

Batch Convert URLs

# From file (one URL per line)
textreader batch urls.txt

# From stdin
cat urls.txt | textreader batch -

# Direct URLs
textreader batch --urls https://example.com/1 --urls https://example.com/2

Example urls.txt:

# My reading list
https://example.com/article1
https://example.com/article2

# More articles
https://example.com/article3

Play Audio

# Play most recent item
textreader play

# Play specific item by ID
textreader play f86f537d

# Search and play
textreader play --search "python"

# Play all items
textreader play --all

# Don't resume from saved position
textreader play --no-resume

Browse Library

# List all items
textreader list

# Search library
textreader list --search "python"

# Filter by tag
textreader list --tag "articles"

# Show statistics
textreader list --stats

Library Management

# Check storage status and cleanup if needed
textreader cleanup

# Force cleanup even if under limit
textreader cleanup --force

# Configure size limit (default: 500MB)
textreader config --set library.max_total_size_mb 1000

Authentication (for Cloud Deployments)

# Enable authentication
textreader auth enable

# Add users
textreader auth add-user admin SecurePassword123
textreader auth add-user alice AlicePass456

# Check status
textreader auth status

# Create API keys
textreader apikey create "My App"

# See AUTHENTICATION.md for full guide

Configuration

# Show current configuration
textreader config --show

# Set configuration values
textreader config --set tts.engine gtts
textreader config --set audio.bitrate 192k

Configuration File

Configuration is stored in ~/.textreader/config.json:

{
  "tts": {
    "engine": "local",
    "local_engine": "gtts",
    "rate": 150,
    "volume": 1.0
  },
  "audio": {
    "format": "mp3",
    "bitrate": "128k",
    "max_file_size_mb": 50
  },
  "library": {
    "storage_path": "~/textreader/library",
    "metadata_path": "~/textreader/metadata.json",
    "max_total_size_mb": 500,
    "auto_cleanup": true
  },
  "batch": {
    "concurrent_downloads": 3,
    "continue_on_error": true
  }
}

Library Size Management

The library automatically manages storage to prevent unlimited growth:

• Default limit: 500MB
• Auto-cleanup: Removes oldest files when limit exceeded
• Manual cleanup: textreader cleanup
• Check status: textreader list --stats

See LIBRARY_SIZE_MANAGEMENT.md for details.

Advanced Usage

Extract Only (No Audio)

textreader convert article.pdf --no-audio

Pipe Content

# From clipboard or other tools
echo "Some text" | textreader convert -

# From file
cat article.md | textreader convert - --format markdown

Supported Formats

Format	Extension	Notes
Web	http://, https://	Auto-detects articles
PDF	.pdf	Text extraction
EPUB	.epub	Ebook format
MOBI	.mobi, .azw	Requires Calibre
Markdown	.md	With --format markdown
HTML	.html	With --format html
Plain Text	.txt	With --format text

File Organization

~/.textreader/
├── config.json           # Configuration
├── textreader.log        # Log file
└── metadata.json         # Library metadata

~/textreader/library/
└── audio/                # Generated audio files
    ├── Article_Title_part001.mp3
    └── Another_Article_part001.mp3

TTS Engines

pyttsx3 (Local, Offline)

• Pros: Offline, fast, no API costs
• Cons: Lower quality, system-dependent voices
• Best for: Quick conversions, offline use

gTTS (Google TTS)

• Pros: High quality, natural voices
• Cons: Requires internet, API rate limits
• Best for: High-quality audio, articles

# Use specific engine
textreader convert article.pdf --engine gtts
textreader convert article.pdf --engine pyttsx3

Troubleshooting

Audio playback issues

If you get audio errors, ensure pygame dependencies are installed:

# Ubuntu/Debian
sudo apt install python3-pygame libsdl2-mixer-2.0-0

# Or reinstall pygame
pip install --upgrade --force-reinstall pygame

SSL Certificate errors

For SSL errors when fetching URLs:

pip install --upgrade certifi

MOBI conversion fails

Install Calibre's command-line tools:

sudo apt install calibre
# or download from https://calibre-ebook.com/download

Library Management

The library tracks:

• ✅ Audio files and metadata
• ✅ Playback position (auto-resume)
• ✅ Play count and statistics
• ✅ Tags and categorization
• ✅ Source information

Coming Soon

• 🌐 Web interface (PWA) for mobile access
• 📡 Cross-device sync (PC to Android)
• 🔌 REST API for external integrations
• 🤖 AI agent integration
• 📱 Android app support

Project Status

🚀 Actively Developed - Phases 1-5 Complete

• ✅ Text extraction (web, PDF, EPUB, MOBI, markdown, HTML)
• ✅ TTS conversion (pyttsx3, gTTS)
• ✅ Library management
• ✅ Audio playback
• ✅ Batch processing
• 🚧 Web interface (coming soon)
• 🚧 Device sync (coming soon)

Contributing

This is a personal project, but suggestions and bug reports are welcome!

License

MIT License

Author

David

---

Made with ❤️ for productive listening