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. Set up the downloader for direct mode by default
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) - Optional P2P Mode Only

Q: Does this download the LBRY blockchain?

A: Only if you choose to use --p2p. The default direct mode does not require this.

When you do use --p2p, the LBRY SDK downloads blockchain headers (not full blocks):

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 only required for the optional P2P path
• 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. Optional: Install LBRY SDK (lbrynet) for P2P Mode

You only need the LBRY SDK if you want to run the downloader with --p2p. The default direct mode does not require it.

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
    content_mode: "video_only"
  
  # Educational content  
  - input: "https://odysee.com/@veritasium:1"
    enabled: true
    content_mode: "video_only"
  
  # News/Commentary
  - input: "https://odysee.com/@Timcast:1"
    enabled: true
    content_mode: "video_only"
  
  # File / document archives
  - input: "https://odysee.com/@DocumentaryLab:1"
    enabled: true
    content_mode: "non_video_only"

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
    content_mode: "non_video_only"
    tags_include: []
    tags_exclude: []
  
  - input: "https://odysee.com/@AnotherChannel:5"
    enabled: true
    content_mode: "video_only"
    tags_include: []
    tags_exclude: []

content_mode controls what each channel downloads:

• all: video and non-video files
• video_only: only videos such as mp4/webm/mkv
• non_video_only: only file bundles/docs such as zip/pdf

If you omit it, the default is all.

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
    content_mode: "all"
  
  # Downloads only videos to a custom location (external drive)
  - input: "https://odysee.com/@LargeVideos:1"
    enabled: true
    download_path: "/mnt/media/videos"
    content_mode: "video_only"
  
  # Downloads only non-video files to a custom location
  - input: "https://odysee.com/@Music:1"
    enabled: true
    download_path: "~/Music/LBRY"
    content_mode: "non_video_only"

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 matching items for that channel
• 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) is only required if you want to use --p2p. The default direct mode does not require it.

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.

If you mostly want zip/doc/file claims and want to skip videos, the most useful first test is:

python3 main.py --dry-run --non-video-only

Normal Run

# Run the downloader using direct mode (default) and each channel's configured content_mode
python3 main.py

Useful Run Variants

# Recommended default if you mainly want non-video files such as zip bundles
python3 main.py --non-video-only

# Force video-only mode for every channel for this run
python3 main.py --video-only

# Force non-video-only mode for every channel for this run
python3 main.py --non-video-only

# Use the local LBRY daemon and peer-to-peer mode instead of direct mode
python3 main.py --p2p

# Use P2P mode with a run-wide content override
python3 main.py --p2p --non-video-only

CLI flags --video-only and --non-video-only override each channel's content_mode for that run only. --p2p overrides the default direct transport mode for that run only.

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 only required when using --p2p 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 not completing ("stopping inactive download")

If you see folder structure and JSON files but no actual video/content files:

What's happening:

• The tool creates metadata immediately
• But the actual download depends on finding peers with the file
• If no peers are available, the download can't complete

To fix/improve:

1. Wait longer - Downloads can take time to find peers:

# Increase download timeout in config.yaml
general:
  timeout_seconds: 600  # Wait up to 10 minutes per file

2. Use Odysee's web player first - This can help seed the content:

   • Go to https://odysee.com
   • Play the video you want to download
   • This connects you to Odysee's CDN nodes
   • Then run the downloader again

3. Run the LBRY Desktop app - It has better DHT connectivity:

   • Download from: https://lbry.com/get
   • Let it run for a while to build peer connections
   • Then run lbry-downloader

4. Check daemon file list - See if files are partially downloaded:

lbrynet file list

5. Try at different times - Peer availability varies:
   • Some content is only available during peak hours
   • Try downloading during evening hours (US time)

Note: LBRY is a peer-to-peer network. If the original uploader or other users aren't currently online with the file, you won't be able to download it. This is different from centralized platforms like YouTube.

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

Optional Prerequisite: Start the Daemon for P2P Mode

Only do this if you plan to run with --p2p:

# 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
~/Documents/LBRY-Downloader/bin/lbry-downloader --dry-run  # Test first
~/Documents/LBRY-Downloader/bin/lbry-downloader --non-video-only  # Recommended direct-mode run
~/Documents/LBRY-Downloader/bin/lbry-downloader --p2p             # Optional local-node mode

# Or if in PATH
lbry-downloader --dry-run
lbry-downloader --non-video-only
lbry-downloader --p2p

# 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