From 66d7a0245878b3e6b6951f0281a8912e79868341 Mon Sep 17 00:00:00 2001
From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com>
Date: Mon, 16 Mar 2026 10:56:46 -0400
Subject: [PATCH] docs: Update documentation for streaming fallback feature

- Add streaming endpoint fallback to README.md features
- Add 'How Downloads Work' section explaining P2P + streaming
- Update QUICKSTART.md with download process examples
- Update CHANGELOG.md with v1.1.0 release notes for streaming fix

The tool now automatically falls back to daemon streaming when P2P
peers are unavailable, ensuring reliable downloads.
---
 CHANGELOG.md  |  5 +++++
 QUICKSTART.md | 22 ++++++++++++++++++++++
 README.md     | 12 +++++++++++-
 3 files changed, 38 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b316475..678c860 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [Unreleased]
 
+### Fixed
+- **Streaming Endpoint Fallback**: When P2P peers are unavailable, the tool now automatically falls back to the daemon's streaming endpoint (`http://localhost:5280/stream/{sd_hash}`), enabling reliable downloads even with no P2P peers
+- Reduced P2P wait timeout from 300s to 60s for faster fallback detection
+- Added progress bar display during streaming downloads
+
 ### Added
 - Initial implementation of LBRY Downloader
 - Support for incremental sync of LBRY/Odysee channels
diff --git a/QUICKSTART.md b/QUICKSTART.md
index 8f69ea7..517d67b 100644
--- a/QUICKSTART.md
+++ b/QUICKSTART.md
@@ -112,6 +112,28 @@ Skipped existing: 146
 Failures: 0
 ```
 
+### Download Process
+
+When downloading, you'll see one of these patterns:
+
+**Fast Download (P2P Available):**
+```
+📥 Downloading: ExampleFile
+   File appeared: ExampleFile.zip
+✓ Downloaded: ExampleFile -> ExampleFile.zip
+```
+
+**Streaming Download (No P2P Peers):**
+```
+⏳ P2P download incomplete, trying daemon streaming endpoint...
+📥 Downloading: ExampleFile
+   Size: 28.61 MB
+   [████████████████████████░░░░░░░░░░░░░░░░] 62%
+✓ Download complete: ExampleFile.zip
+```
+
+The tool automatically handles both scenarios - you don't need to do anything special!
+
 ## Directory Structure
 
 Downloads are saved to:
diff --git a/README.md b/README.md
index 25554cf..0a5863a 100644
--- a/README.md
+++ b/README.md
@@ -9,6 +9,7 @@ A Python tool that incrementally syncs downloadable file claims from configured
 - **Robust Identity**: Uses stable LBRY claim IDs, not display names or titles
 - **Atomic State**: Database writes are atomic to prevent corruption
 - **Daemon-Based**: Talks directly to local `lbrynet` daemon via JSON-RPC
+- **Streaming Fallback**: Automatically uses daemon's streaming endpoint when P2P peers are unavailable
 - **Flexible Input**: Accepts Odysee URLs, LBRY URIs, or claim IDs
 - **Audit Trail**: Maintains run history in JSONL format
 - **Dry-Run Mode**: Test what would happen without downloading
@@ -334,10 +335,19 @@ Check that your channels are enabled and have downloadable content (streams, not
 - `config_loader.py` - Configuration parsing
 - `state_db.py` - Persistent state management
 - `planner.py` - Download decision logic
-- `downloader.py` - Download execution
+- `downloader.py` - Download execution with P2P + streaming fallback
 - `models.py` - Data structures
 - `utils.py` - Helper functions
 
+## How Downloads Work
+
+The downloader uses a two-stage approach for maximum reliability:
+
+1. **P2P Attempt**: First tries to download from LBRY's peer-to-peer network
+2. **Streaming Fallback**: If P2P peers are unavailable (common for older content), automatically falls back to the daemon's local streaming endpoint
+
+This ensures content downloads successfully even when the P2P network has no seeders.
+
 ## License
 
 MIT License