Beacon DL

Download BeaconTV videos with all subtitle tracks. Outputs properly formatted files for media libraries.

Installation

Quick Run (No Install)

Run directly without installing using uv:

# From PyPI
uvx beacon-dl --help

# From GitHub (latest)
uvx --from git+https://github.com/Postmodum37/beacon-dl.git beacon-dl --help

Permanent Install

# Install as a tool with uv
uv tool install beacon-dl

# Or with pip
pip install beacon-dl

# Or from GitHub
pip install git+https://github.com/Postmodum37/beacon-dl.git

Development Install

git clone https://github.com/Postmodum37/beacon-dl.git
cd beacon-dl
uv pip install -e .

Requirements:

• Python 3.10+
• ffmpeg (brew install ffmpeg on macOS, apt install ffmpeg on Linux)
• Chromium browser (auto-installed on first run)

Quick Start

# Download latest episode (requires auth)
beacon-dl --username user@example.com --password yourpassword

# Or with uvx
uvx beacon-dl -u user@example.com -p yourpassword

# Download specific episode
beacon-dl https://beacon.tv/content/c4-e007-episode-title -u user@example.com -p pass

Commands

Examples

# Browse content
beacon-dl list-series
beacon-dl list-episodes campaign-4
beacon-dl search "dragon" --series campaign-4
beacon-dl info c4-e007-episode-title

# Download
beacon-dl --series exu-calamity              # Latest from specific series
beacon-dl batch-download campaign-4 --start 1 --end 5   # Episodes 1-5

# Maintenance
beacon-dl config                             # Show current settings
beacon-dl history --limit 50
beacon-dl verify --full                      # SHA256 verification
beacon-dl rename --execute                   # Apply naming updates
beacon-dl clear-history --force              # Clear history database

Authentication

# Command line
beacon-dl -u user@example.com -p yourpassword

# Environment variables
export BEACON_USERNAME=user@example.com
export BEACON_PASSWORD=yourpassword
beacon-dl

Configuration

Output Format

Critical.Role.S04E07.Episode.Title.1080p.WEB-DL.AAC2.0.H.264.mkv

Docker

docker build -t beacon-dl .
docker run --rm -e BEACON_USERNAME=... -e BEACON_PASSWORD=... -v $(pwd):/app beacon-dl

Development

# Install dev dependencies
uv sync --extra dev

# Run tests
uv run pytest                    # All 427 tests
uv run pytest -m unit            # Unit tests only
uv run pytest -m security        # Security tests
uv run pytest --cov              # With coverage (~74%)

# Lint
uv run ruff check src/ tests/
uv run ruff format src/ tests/

Troubleshooting

License

MIT