Web Article to Audio CLI

A command-line tool that extracts article text from web pages, converts it to speech using various text-to-speech engines, and saves the audio for later listening.

Features

• Extracts main article content from web URLs (excludes menus, ads, and sidebars)
• Converts text to natural-sounding speech using multiple TTS engines:
  • Google TTS (gtts)
  • Microsoft Edge TTS (edge)
  • System TTS (system) - macOS only
• Saves both audio files (.mp3) and text transcripts to a configurable folder
• Provides playback options:
  • Open containing folder
  • Play with QuickTime (macOS only)
• Simple configuration system with command-line interface

Setup Instructions for macOS

Prerequisites

• macOS
• Python 3.7+
• Terminal access

Setup Steps

1. Clone the repository

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

2. Create a Python virtual environment

   # Create a virtual environment
   python3 -m venv venv
   
   # Activate the virtual environment
   source venv/bin/activate

3. Install dependencies

   # Install required packages
   pip install -r requirements.txt

4. Initial configuration

   Run the application once to create the initial configuration:

   python reader.py config

   This will prompt you to set the save folder for audio files and other preferences.

Usage

Basic Commands

# Interactive mode (prompts for URL and options)
python reader.py

# Convert an article to audio
python reader.py https://example.com/article-url

# View or update configuration
python reader.py config

# View available TTS engines
python reader.py config engines

# Set TTS engine
python reader.py config tts_engine=edge

# Set custom save folder
python reader.py config save_folder=~/Documents/AudioArticles

# Display help
python reader.py --help

Command-Line Options

# Set custom save folder for this conversion
python reader.py --output ~/Documents/AudioArticles https://example.com/article-url

# Use a specific TTS engine for this conversion
python reader.py --engine edge https://example.com/article-url

# Open folder containing the file when done
python reader.py --open https://example.com/article-url

# Play audio with QuickTime when done (macOS only)
python reader.py --play https://example.com/article-url

# Enable verbose output
python reader.py --verbose https://example.com/article-url

# Suppress non-error output
python reader.py --quiet https://example.com/article-url

Project Structure

|-- config.ini                # Configuration file
|-- reader.py                 # Main entry point
|-- requirements.txt          # Python dependencies
|-- scripts
|   |-- web2audio.scpt        # AppleScript for quick app integration
|-- docs
|   |-- Web Article to Audio CLI Program.md  # Program specification
|   |-- Development Steps.md  # Development notes
|-- src
    |-- __init__.py
    |-- config.py             # Configuration management
    |-- extractor.py          # Article extraction
    |-- player.py             # Audio playback
    |-- tts.py                # Text-to-speech conversion
    |-- utils.py              # Utility functions

AppleScript Integration

The project includes an AppleScript (scripts/web2audio.scpt) that you can use to create a quick macOS application:

1. Open the script in Script Editor (right-click and "Open With Script Editor")
2. Choose "Export..." from the File menu
3. Select "Application" from the File Format dropdown
4. Save the application to your Applications folder or Desktop
5. Run the application to quickly convert web pages to audio

The script will prompt you for the following information when first run:

• The web2audio project folder location
• Where to save audio files
• The article URL you want to convert

These settings are saved for future use. You can also choose whether to play the file automatically, open the containing folder, or just save the file.

Troubleshooting

If you encounter issues:

1. Ensure your virtual environment is activated (source venv/bin/activate)
2. Verify all dependencies are installed (pip install -r requirements.txt)
3. Check the configuration file (cat config.ini)
4. For permission issues with save folders, ensure you have write access
5. For online TTS engines (Google TTS, Edge TTS), ensure you have an internet connection

License

MIT