OffStream

A resilient, local media downloader and browser companion built with strict Hexagonal Architecture.

Online converters (y2mate, savefrom) are plagued with malicious redirects, spam ads, and aggressive CDN bandwidth throttling (~50 KB/s). Standard scripts and CLI tools, on the other hand, frequently lock up, leave zombie FFmpeg processes consuming CPU, flash unwanted CMD windows, and lack real-time visibility.

OffStream runs completely on your own machine as an asynchronous companion service:

• Unthrottled parallel streaming: Downloads 4 concurrent chunk streams to max out your connection line speed (completing downloads in 2–3 seconds).
• Server-Sent Events (SSE): Delivers 60 FPS real-time progress updates directly from the download engine to the UI without network-saturating polling.
• Embedded SQLite History: Tracks video ID, title, channel, duration, timestamps, and destination paths via standard library sqlite3.
• Searchable Desktop Library: Instant search across your download history with live file integrity checks (✓ En disco vs. ⚠️ Archivo movido o eliminado) and one-click playback (os.startfile).
• Resilient Cookies Bypass: Injects active local browser sessions (Chrome, Firefox, Edge, Brave) or cookies.txt to bypass bot challenges, age gates, and download high-bitrate YouTube Music audio—featuring automated fallback if Windows locks the cookie database.
• Windows-Defensive Engineering: Suppresses black console flashes via CREATE_NO_WINDOW and purges process trees on exit using taskkill.exe /F /T /PID.

No Python installation or command-line required.

1. Download OffStream-Windows-Portable.zip from Releases.
2. Extract the folder anywhere on your computer.
3. Double-click OffStream.exe to start.

Requires Python 3.11+ on Windows 10/11 (FFmpeg is automatically bundled via imageio-ffmpeg).

git clone https://github.com/ismaelUML/OffStream.git
cd OffStream

python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt

python main.py
# Runs on http://127.0.0.1:8765

1. Open chrome://extensions/ and enable Developer mode.
2. Click Load unpacked and select the clients/browser-extension/ directory.
3. Pin OffStream to your toolbar.
4. On any YouTube or YouTube Music video, click the toolbar icon: the active URL is detected automatically. Click Video or Audio (MP3). Progress streams live via SSE.

python main.py --gui
# or: python -m adapters.in_bound.gui

Or simply double-click Start_OffStream.bat (or Launch_Dashboard.bat).

• Tab "⬇ Descargas": Paste any URL, select quality (1080p+, MP3, 720p), view live progress, and manage the daemon lifecycle.
• Tab "📚 Biblioteca / Historial": Type to search through past downloads in real time. Click ▶ Reproducir to launch in your default media player, or 📁 Carpeta to highlight the file in Windows Explorer.

# Download 1080p video with lossless remux
python main.py "https://www.youtube.com/watch?v=VIDEO_ID" -q 1080p

# Download audio converted directly to MP3 with embedded album art
python main.py -a "https://www.youtube.com/watch?v=VIDEO_ID"

# Use browser cookies to bypass age-gating or access YouTube Music bitrate
python main.py -a "https://music.youtube.com/watch?v=VIDEO_ID" --cookies-from-browser chrome

# Inspect stream metadata without downloading
python main.py -i "https://www.youtube.com/watch?v=VIDEO_ID"

All downloads are automatically sorted and organized in Downloads/yt-global-dl/:

• music/: Configured with Windows Explorer Music view template (desktop.ini), displaying artist, title, duration, and bitrates.
• videos/: Configured with Windows Explorer Videos view template (desktop.ini), displaying video resolution, duration, and dimensions.
• Embedded metadata tags (Title, Artist/Uploader) are injected into MP3/MP4 files for immediate playback compatibility in car stereos, iTunes, and mobile players.

OffStream follows strict Hexagonal Architecture (Ports and Adapters) principles to maintain high cohesion and absolute testability:

yt-global-dl/
├── .github/
│   └── workflows/ci.yml           # Automated Windows CI (Pytest + Radon Rank A audit)
├── domain/                        # Pure models (dataclasses) & business exceptions (Zero deps)
├── ports/                         # Abstract Protocol interfaces (in_bound, out_bound)
├── core/                          # Domain orchestrators (DownloadManager, circuit breaker, etc.)
├── adapters/                      # Concrete technology drivers & driven components
│   ├── in_bound/                  # Driving adapters: cli.py, server.py, gui.py
│   └── out_bound/                 # Driven adapters: ytdlp, ffmpeg, sqlite, cookies, etc.
├── clients/
│   └── browser-extension/         # Manifest V3 extension (Chrome / Edge / Brave)
├── scripts/
│   ├── build_windows_exe.py       # Deterministic PyInstaller standalone bundler
│   ├── install_deps.py            # Hardened binary dependency installer
│   └── windows/                   # Platform background daemons & autostart automation
├── tests/                         # Pytest test suite (100% pass rate)
├── main.py                        # Unified CLI / Daemon / GUI bootstrapper
├── Build_Release.bat              # 1-Click compiler for standalone OffStream.exe
├── Start_OffStream.bat            # Fail-safe 1-Click desktop launcher (auto-healing & Python detect)
└── Launch_Dashboard.bat           # Desktop dashboard launcher

graph TD
    subgraph Driving Adapters
        Ext[Chrome / Edge Extension] -->|SSE / REST| Srv[FastAPI Daemon]
        GUI[CustomTkinter GUI] -->|REST / SQLite| Srv
        CLI[Terminal CLI] --> Core
    end

    subgraph Core
        Srv --> Core[DownloadManager]
        Core --> CB[Circuit Breaker Router]
        Core --> TS[Title Cleaner]
        Core --> SS[Stream Selector]
    end

    subgraph Domain
        Core -.-> Models[Pure Dataclasses & Exceptions]
    end

    subgraph Driven Adapters
        CB --> YTDLP[YtDlpResolver]
        CB --> InnerTube[InnerTubeResolver]
        Core --> FastDL[FastMediaDownloader]
        Core --> FFmpeg[FFmpegProcessor]
        Core --> SQLite[SqliteHistoryAdapter]
        Core --> Disk[LocalStorageAdapter]
    end

• Domain (domain/): Pure Python standard library dataclasses (DownloadJob, DownloadRecord, StreamFormat). Zero external imports.
• Ports (ports/): Interfaces defined using typing.Protocol (StreamResolverPort, MediaDownloaderPort, MediaProcessorPort, StoragePort, HistoryRepositoryPort).
• Core (core/): Orchestration services. Enforces Little's Law with bounded concurrency (3 parallel workers, max 25 queue capacity), socket cancellation hooks, and circuit-breaker failover.
• Adapters (adapters/): Concrete implementations (FastAPI server, CLI parser, Desktop GUI, SQLite history database, yt-dlp direct downloader, imageio FFmpeg wrapper).
• Clients (clients/): Browser companion extensions interacting through the local HTTP/SSE interface.

Code quality is monitored using Radon:

Run the full automated test suite (44 unit and integration tests):

python -m pytest tests/ -v

Run static complexity and maintainability audits:

python -m radon cc domain ports core adapters main.py -s -a
python -m radon mi domain ports core adapters main.py -s

This software is designed for personal media backup, local caching, and educational analysis only. Users are responsible for complying with local copyright laws and third-party terms of service.

Released under the MIT License.