LBRY-Downloader/LINUX_SETUP.md

Linux Setup Guide (Debian/Ubuntu/Mint)

Complete instructions for setting up LBRY Downloader on Debian-based Linux distributions.

One-Line Install (Easiest)

Install with a single command using curl:

curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/LBRY-Downloader/main/remote-install.sh | bash

Requirements: Git and Python 3.8+ must be installed.

What this does:

1. Downloads the repository
2. Runs the interactive setup script
3. Configures everything automatically

Interactive Setup

If you prefer to clone manually, use the interactive setup script:

# Clone the repository
git clone https://github.com/PR0M3TH3AN/LBRY-Downloader.git
cd LBRY-Downloader

# Run the interactive installer
./setup.py

This script will:

1. Check and install system dependencies
2. Download and install LBRY SDK (lbrynet) - No blockchain sync required!
3. Set up a Python virtual environment
4. Install Python packages
5. Ask for your download location
6. Configure channels to download from
7. Set download limits
8. Create launcher scripts

Want to uninstall later? Just run ./uninstall.py

About LBRY SDK (lbrynet) - IMPORTANT

Q: Does this download the LBRY blockchain?

A: The LBRY SDK downloads blockchain headers (not full blocks), which is required to function:

First-time setup (one-time):

• Downloads ~1.7 million block headers
• Takes approximately 5-10 minutes
• Uses minimal storage space (headers only, not full blocks)
• Shows progress like: lbc_mainnet: added BlockHeightEvent(height=1663209, change=2001)

Subsequent use:

• Near-instant startup after initial sync
• Only downloads new headers since last run

What this means:

• The LBRY SDK needs this data to verify which content claims are valid
• This is lighter than Bitcoin's full blockchain sync
• But it IS required and will take time on first launch
• You can stop it with Ctrl+C or lbrynet stop

Privacy note: This connects to LBRY's network and syncs blockchain data to verify content. This is how the LBRY protocol works.

---

Manual Installation

If you prefer to set things up manually, follow the steps below.

Prerequisites

1. System Packages

# Update system
sudo apt update && sudo apt upgrade -y

# Install Python and required system packages
sudo apt install -y \
    python3 \
    python3-pip \
    python3-venv \
    git \
    curl \
    wget

# Verify Python installation
python3 --version  # Should be 3.8 or higher
pip3 --version

2. Install LBRY SDK (lbrynet daemon)

The LBRY SDK is required to communicate with the LBRY network.

Option A: Download Pre-built Binary (Recommended)

# Create directory for lbrynet
mkdir -p ~/.local/bin
cd ~/.local/bin

# Download latest release (check https://github.com/lbryio/lbry-sdk/releases for latest)
# For x86_64 systems:
LBRY_VERSION="0.113.0"  # Check for latest version
wget "https://github.com/lbryio/lbry-sdk/releases/download/v${LBRY_VERSION}/lbry-sdk-linux.zip"

# Extract
unzip lbry-sdk-linux.zip
rm lbry-sdk-linux.zip

# Make executable
chmod +x lbrynet

# Add to PATH if not already there
if ! echo $PATH | grep -q "$HOME/.local/bin"; then
    echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
    source ~/.bashrc
fi

# Verify installation
lbrynet --version

Option B: Build from Source (Advanced)

# Install build dependencies
sudo apt install -y \
    build-essential \
    libssl-dev \
    libffi-dev \
    python3-dev \
    python3-venv

# Clone and build (not recommended for most users)
git clone https://github.com/lbryio/lbry-sdk.git
cd lbry-sdk
python3 -m venv venv
source venv/bin/activate
pip install -e .

Installation

1. Clone the Repository

# Navigate to where you want to install
cd ~/Documents  # or wherever you prefer

# Clone (if you have git access) or extract the zip
git clone https://github.com/yourusername/LBRY-Downloader.git
# OR if you downloaded a zip:
# unzip LBRY-Downloader.zip -d LBRY-Downloader

cd LBRY-Downloader

2. Set Up Python Environment

# Option A: Using system Python (simpler)
pip3 install --user -r requirements.txt

# Option B: Using virtual environment (recommended for developers)
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

3. Verify Installation

# Test Python imports
python3 -c "from main import run_sync; print('✓ Imports OK')"

# Test CLI
python3 main.py --help

Configuration

1. Initialize Configuration

# Run initialization script
python3 init.py

# This creates:
# ~/Documents/lbry-downloads/config.yaml
# ~/Documents/lbry-downloads/state/
# ~/Documents/lbry-downloads/channels/

2. Edit Configuration

# Open config in your preferred editor
nano ~/Documents/lbry-downloads/config.yaml
# OR
gedit ~/Documents/lbry-downloads/config.yaml
# OR
vim ~/Documents/lbry-downloads/config.yaml

3. Add Your Channels

Where to find channel URLs: From Odysee.com (the main LBRY frontend)

Finding Channel URLs on Odysee

Method 1: Direct from Channel Page (Easiest)

1. Open your web browser and go to https://odysee.com
2. Use the search bar to find the channel you want (e.g., "Technology", "Documentaries", "Music")
3. Click on the channel name or logo to go to the channel page
4. Look at your browser's address bar - you'll see something like:
   • https://odysee.com/@TechChannel:1
   • https://odysee.com/@DocumentaryFilms:2
   • https://odysee.com/@MusicChannel:5
5. Copy this entire URL
6. Paste it into your config.yaml file

Method 2: From a Video Page

1. Watch any video from the channel you want to download
2. Click on the channel name below the video title
3. This takes you to the channel page
4. Copy the URL from the address bar

Method 3: From Search Results

1. Search for content on Odysee
2. Look at the channel name next to each video
3. Click on the channel name
4. Copy the URL from the address bar

Example Channel URLs

Popular channels you might want to download:

channels:
  # Technology channels
  - input: "https://odysee.com/@LinusTechTips:1"
    enabled: true
  
  # Educational content  
  - input: "https://odysee.com/@veritasium:1"
    enabled: true
  
  # News/Commentary
  - input: "https://odysee.com/@Timcast:1"
    enabled: true
  
  # Documentaries
  - input: "https://odysee.com/@DocumentaryLab:1"
    enabled: true

URL Formats Supported

You can use any of these formats in your config:

channels:
  # Full Odysee URL (recommended - easiest to copy from browser)
  - input: "https://odysee.com/@ChannelName:1"
    enabled: true
  
  # LBRY URI format
  - input: "lbry://@ChannelName#1"
    enabled: true
  
  # Short form (without protocol)
  - input: "@ChannelName:1"
    enabled: true

Recommendation: Just copy-paste the full Odysee URL from your browser - it's the easiest and most reliable method!

Edit the Config File

Once you have your channel URLs, add them to the config:

# Open the config file
nano ~/Documents/lbry-downloads/config.yaml

Add your channels under the channels: section:

channels:
  - input: "https://odysee.com/@YourFavoriteChannel:1"
    enabled: true
    tags_include: []
    tags_exclude: []
  
  - input: "https://odysee.com/@AnotherChannel:5"
    enabled: true
    tags_include: []
    tags_exclude: []

4. Configure Per-Channel Download Locations (Optional)

By default, all downloads go to ~/Documents/lbry-downloads/channels/. You can specify custom locations for each channel:

channels:
  # Downloads to default location
  - input: "https://odysee.com/@RegularChannel:1"
    enabled: true
  
  # Downloads to custom location (external drive)
  - input: "https://odysee.com/@LargeVideos:1"
    enabled: true
    download_path: "/mnt/media/videos"
  
  # Downloads to custom location (home directory)
  - input: "https://odysee.com/@Music:1"
    enabled: true
    download_path: "~/Music/LBRY"

Why use custom locations?

• Store large channels on external drives
• Organize content by type (videos, music, etc.)
• Manage disk space across multiple drives
• Keep important channels on fast SSD, archive on slow HDD

Note: Make sure the custom path exists and you have write permissions:

mkdir -p /mnt/media/videos
# Check permissions
ls -la /mnt/media/

5. Configure Download Limits (Optional)

Limit how many new items to download per channel. This is especially useful for:

• Testing - Download just a few files first
• Large channels - Channels with thousands of videos
• Bandwidth control - Limit data usage per run

general:
  # Default: download 10 most recent items per channel
  download_limit: 10
  
  # To download everything (use with caution!):
  # download_limit: 0
  
  # For testing, download only 2-3 items:
  # download_limit: 3

The tool downloads most recent items first (sorted by publish date), so:

• download_limit: 10 = Download the 10 newest videos
• Older items remain in the channel but won't be downloaded yet
• On next run, it will download the next 10 (if new items were published)

Recommended approach for large channels:

general:
  download_limit: 10  # Start with a small number

channels:
  - input: "https://odysee.com/@HugeArchive:1"
    enabled: true
    # Downloads only 10 most recent to test

Once you're happy with how it works, increase the limit or set to 0.

Running the Daemon

The LBRY daemon (lbrynet) must be running before using the downloader.

Start the Daemon

# Start lbrynet
lbrynet start

# Check status
lbrynet status

# You should see JSON output with daemon information

Running as a Systemd Service (Optional)

Create a systemd service to auto-start lbrynet:

# Create service file
sudo tee /etc/systemd/system/lbrynet.service > /dev/null <<EOF
[Unit]
Description=LBRY SDK Daemon
After=network.target

[Service]
Type=simple
User=$USER
ExecStart=$HOME/.local/bin/lbrynet start
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# Reload systemd
sudo systemctl daemon-reload

# Enable and start service
sudo systemctl enable lbrynet
sudo systemctl start lbrynet

# Check status
sudo systemctl status lbrynet

# View logs
sudo journalctl -u lbrynet -f

Stop the Daemon

# If running manually
lbrynet stop

# If running as systemd service
sudo systemctl stop lbrynet

Using the Downloader

First Run (Dry Run)

Always test with dry-run first:

cd ~/Documents/LBRY-Downloader  # or wherever you installed it

python3 main.py --dry-run

This shows what would be downloaded without actually downloading anything.

Normal Run

# Make sure lbrynet is running
lbrynet status

# Run the downloader
python3 main.py

Custom Config Location

python3 main.py --config /path/to/custom/config.yaml

Viewing Progress

The tool outputs progress to the console:

2024-03-15 14:30:00 - INFO - LBRY Downloader starting
2024-03-15 14:30:01 - INFO - Daemon is healthy
2024-03-15 14:30:02 - INFO - Resolved channel: @SomeChannel (abc123...)
2024-03-15 14:30:05 - INFO -   Total claims found: 150
2024-03-15 14:30:06 - INFO - New claim: interesting-video (download_new)
...

Run complete.
Channels scanned: 2
Claims examined: 150
New downloads: 3
New versions: 1
Skipped existing: 146
Failures: 0

Directory Structure

After running, your downloads will be organized as:

~/Documents/lbry-downloads/
├── config.yaml                    # Your configuration
├── state/
│   ├── database.json             # State database (don't edit)
│   └── run-history.jsonl         # Audit log
└── channels/
    └── SomeChannel__abc123/      # Channel folder
        ├── channel.json          # Channel metadata
        └── claims/
            └── interesting-video__def456/
                ├── claim.json    # Claim metadata
                └── versions/
                    └── sd_abc789/
                        ├── interesting-video.mp4
                        ├── metadata.json
                        ├── download.json
                        └── checksums.txt

Automation (Optional)

Create a Wrapper Script

# Create convenient wrapper
tee ~/bin/lbry-sync > /dev/null <<'EOF'
#!/bin/bash
cd ~/Documents/LBRY-Downloader
source venv/bin/activate 2>/dev/null || true

# Check if lbrynet is running
if ! curl -s http://127.0.0.1:5279 > /dev/null 2>&1; then
    echo "Starting lbrynet daemon..."
    lbrynet start &
    sleep 5
fi

# Run downloader
python3 main.py "$@"
EOF

chmod +x ~/bin/lbry-sync

# Now you can just run:
# lbry-sync
# lbry-sync --dry-run

Cron Job for Regular Syncs

# Edit crontab
crontab -e

# Add line to run daily at 3 AM:
0 3 * * * cd ~/Documents/LBRY-Downloader && python3 main.py >> ~/lbry-sync.log 2>&1

# Or weekly on Sundays at 2 AM:
0 2 * * 0 cd ~/Documents/LBRY-Downloader && python3 main.py >> ~/lbry-sync.log 2>&1

Troubleshooting

"Could not connect to LBRY daemon"

# Check if lbrynet is running
lbrynet status

# If not running, start it
lbrynet start

# Check if it's listening on the expected port
netstat -tlnp | grep 5279
# OR
ss -tlnp | grep 5279

# Check daemon logs (if running as systemd)
sudo journalctl -u lbrynet -n 50

"lbc_mainnet: added BlockHeightEvent" - What's happening?

This is normal! On first run, lbrynet syncs blockchain headers:

lbc_mainnet: added BlockHeightEvent(height=1663209, change=2001)
lbc_mainnet: added BlockHeightEvent(height=1665210, change=2001)

What this means:

• The LBRY SDK is downloading blockchain headers (not full blocks)
• This is required to verify content claims
• Takes 5-10 minutes on first run
• Subsequent runs are instant

To stop it:

# Stop the daemon
lbrynet stop

# Or kill the process
pkill -f lbrynet

To check sync progress:

lbrynet status

Note: This is a one-time process. Once complete, the daemon starts instantly.

"Permission denied" when running lbrynet

# Ensure lbrynet is executable
chmod +x ~/.local/bin/lbrynet

# Check PATH
echo $PATH
# Should include /home/YOURUSERNAME/.local/bin

"ModuleNotFoundError" for Python packages

# Reinstall dependencies
cd ~/Documents/LBRY-Downloader

# If using system Python:
pip3 install --user --force-reinstall -r requirements.txt

# If using venv:
source venv/bin/activate
pip install --force-reinstall -r requirements.txt

"Config file not found"

# Run initialization again
python3 init.py

# Or manually create the directory
mkdir -p ~/Documents/lbry-downloads/state
mkdir -p ~/Documents/lbry-downloads/channels

# And create a config file from the example
cp config.yaml.example ~/Documents/lbry-downloads/config.yaml

Downloads are slow

LBRY downloads can be slow depending on network conditions. This is normal:

# In config.yaml, reduce max_workers if needed
general:
  max_workers: 1  # Download one at a time
  timeout_seconds: 300  # Increase timeout

Disk space issues

Check the download directory size:

du -sh ~/Documents/lbry-downloads/channels/
du -sh ~/Documents/lbry-downloads/channels/* | sort -hr | head -20

Updating

Update the Downloader

cd ~/Documents/LBRY-Downloader

# If using git:
git pull

# If manual download, re-download and replace files

# Update Python dependencies
pip3 install --user --upgrade -r requirements.txt
# OR if using venv:
source venv/bin/activate
pip install --upgrade -r requirements.txt

Update lbrynet

# Stop current daemon
lbrynet stop

# Download new version (see installation section)
cd ~/.local/bin
# ... download and extract new version ...

# Restart
lbrynet start

Uninstallation

# Stop daemon
lbrynet stop

# Remove downloader
rm -rf ~/Documents/LBRY-Downloader
rm -rf ~/Documents/lbry-downloads

# Remove lbrynet (if installed locally)
rm ~/.local/bin/lbrynet

# Remove systemd service (if created)
sudo systemctl stop lbrynet
sudo systemctl disable lbrynet
sudo rm /etc/systemd/system/lbrynet.service
sudo systemctl daemon-reload

# Remove cron job
crontab -e
# Delete the line with lbry-downloader

Getting Help

1. Check the logs: ~/Documents/lbry-downloads/state/run-history.jsonl
2. Run with debug logging: Set log_level: "DEBUG" in config.yaml
3. Test daemon connectivity:

   curl -X POST http://127.0.0.1:5279 \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","method":"status","params":{},"id":1}'
   

Uninstallation

To remove LBRY Downloader:

# Run the uninstall script
./uninstall.py

This will:

• Find your installation and download directories
• Ask for confirmation before removing
• Show you what's being deleted
• Optionally help clean up PATH entries

Manual uninstall:

# Stop the daemon
lbrynet stop

# Remove installation directory
rm -rf ~/Documents/LBRY-Downloader

# Remove downloads (optional - backup first!)
rm -rf ~/Documents/lbry-downloads

# Remove lbrynet (optional)
rm ~/.local/bin/lbrynet

# Remove from PATH if you added it
# Edit ~/.bashrc and remove the lbry-downloader PATH line

Launching the Application

After installation, there are several ways to launch LBRY Downloader:

Method 1: Launcher Script (Recommended)

The setup script creates launcher scripts in ~/Documents/LBRY-Downloader/bin/:

# Navigate to install directory
cd ~/Documents/LBRY-Downloader

# Run the downloader
./bin/lbry-downloader --dry-run

# Or run without changing directory
~/Documents/LBRY-Downloader/bin/lbry-downloader --dry-run

Method 2: Add to PATH

Add the bin directory to your PATH to run from anywhere:

# Add to PATH (one-time setup)
echo 'export PATH="$HOME/Documents/LBRY-Downloader/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Now run from any directory
lbry-downloader --dry-run
lbry-downloader

Method 3: Using Virtual Environment

cd ~/Documents/LBRY-Downloader
source venv/bin/activate
python main.py --dry-run

Method 4: Quick Test

cd ~/Documents/LBRY-Downloader
./bin/lbry-test  # Automatically runs with --dry-run

Prerequisites: Start the Daemon

Important: Always start the LBRY daemon before running the downloader:

# Check if daemon is running
lbrynet status

# Start if not running
lbrynet start

# Or if using systemd
sudo systemctl start lbrynet

Quick Reference

# Automated Setup (one-time)
curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/LBRY-Downloader/main/remote-install.sh -o install-lbry.sh && bash install-lbry.sh

# Manual Setup (one-time)
sudo apt install python3 python3-pip
pip3 install --user -r requirements.txt
python3 init.py

# Daily use
lbrynet start                                          # Start daemon
~/Documents/LBRY-Downloader/bin/lbry-downloader --dry-run  # Test first
~/Documents/LBRY-Downloader/bin/lbry-downloader            # Run sync
lbrynet stop                                           # Stop daemon (optional)

# Or if in PATH
lbry-downloader --dry-run
lbry-downloader

# Locations
Install:   ~/Documents/LBRY-Downloader/
Config:    ~/Documents/lbry-downloads/config.yaml
Downloads: ~/Documents/lbry-downloads/channels/
State:     ~/Documents/lbry-downloads/state/
Logs:      ~/Documents/lbry-downloads/state/run-history.jsonl