Skip to content

About

Universal Video, Audio, Playlist & Bulk Media Downloader — Chromium Extension + Local Engine powered by yt-dlp & FFmpeg

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

StreamCatch — Universal Video & Media Studio

StreamCatch Logo

Universal Video, Audio, Playlist & Bulk Media Downloader Studio
A powerful, local-first Chromium extension with a persistent side panel backed by a zero-configuration Python engine.

Version 1.2.1 Manifest V3 npm install Python 3.8+ MIT License CI Status Support Kori Author Facebook Localhost Only


⚡ Overview

StreamCatch bridges the gap between browser convenience and raw downloading power. Unlike sketchy web downloaders crammed with ads, popups, and bandwidth throttling, StreamCatch runs entirely on your machine.

It pairs an elegant, dark-mode Chromium extension (Popup, Chrome Side Panel, and Full-Tab Studio Dashboard) with a lightweight, secure local Python engine powered by yt-dlp and FFmpeg.

  • 🔒 Zero Accounts & Zero Cloud Relays: No sign-ups, no logins, no third-party tracking, and no external servers touching your files.
  • ⚡ Auto-Connect (Zero Pairing Keys): Launch the helper and start downloading instantly. The extension and helper negotiate secure loopback connections automatically.
  • 📌 Fixed Chrome Side Panel (Chrome 116+): The popup doesn't vanish when you click away — pin the persistent side panel while browsing or queuing links.
  • 🎬 Full Resolution & Format Control: Grab up to 4K / 2160p video in MP4, MKV, or WebM, or extract pristine audio to FLAC, WAV, M4A, or MP3.
  • 📑 True Playlists & Channels: Download entire collections or selected ranges with truthful progress and no silent failures.
  • 📦 Bulk URL Batch Manager: Queue up to 100 links at once, grab URLs from all open tabs, and automatically deduplicate.
  • 🔍 Live Media Sniffer: Detects active video and audio streams (direct MP4/WebM files, HLS .m3u8, and DASH .mpd adaptive streams) right from the active tab.
  • 💤 Automatic 5-Minute Inactivity Auto-Close: To conserve your computer's RAM and CPU, the local engine automatically closes itself after 5 minutes of inactivity (when no downloads are running or queued). Whenever you need it again, simply click "🚀 Start Engine" in the extension to wake it up in 1 click!

🏗️ Architecture

flowchart LR
    subgraph Browser [" Chromium Browser (Chrome / Edge / Brave) "]
        direction TB
        Tab["Active Web Tab\n(YouTube, Vimeo, etc.)"]
        ExtUI["StreamCatch Studio UI\n(Side Panel / Popup / Dashboard)"]
        CS["Content Script &\nNetwork Sniffer"]
        Tab -->|Media requests & URLs| CS
        CS -->|Discovered Streams| ExtUI
    end

    subgraph LocalEngine [" Local Machine (127.0.0.1:8735) "]
        direction TB
        Server["StreamCatch Engine (server.py)\nThreading HTTPServer + Worker Pool"]
        YTDL["yt-dlp Extractor Engine"]
        FFMPEG["FFmpeg Remuxer & Transcoder"]
        Disk[("Local Storage\n~/Downloads/StreamCatch")]

        Server -->|Process Jobs| YTDL
        YTDL -->|Transcode / Merge| FFMPEG
        FFMPEG -->|Write Media| Disk
    end

    ExtUI -->|HTTP / JSON via Loopback\n(X-StreamCatch-Client + Origin)| Server
Loading

✨ Features & Capabilities

Feature Description
Single Video Downloads Paste any URL or click Use link from the current active tab. Select exact resolution caps (4K, 1440p, 1080p, 720p, etc.) and format.
Playlist & Channel Mirroring Toggle Playlist / channel to download entire series or choose ranges (First 25, 50, 100, 250, 500). Playlists are automatically sorted into organized subdirectories (Playlists/<Playlist Title>/001 - Title.mp4).
Bulk URL Queue Paste batches up to 100 links or click + Open tabs to pull video URLs from all tabs currently open in your browser window. Duplicates are filtered automatically.
Audio Extraction Convert videos into high-quality audio files: Lossless FLAC, uncompressed WAV, pristine M4A, or MP3 (192 kbps).
Persistent Side Panel Take advantage of the modern Chrome Side Panel API (sidePanel). The downloader stays open alongside your tabs without disappearing when you click the webpage.
Dual Download Managers Choose your preferred download mechanism: ⚡ Local Engine (yt-dlp + FFmpeg) for full 4K quality, audio merging, MP3 conversion, and playlists, or 🌐 Browser Downloader (Chrome native) to download streams directly through Chrome's native download shelf and chrome://downloads. Configure your default in Settings or switch on the fly from the main Download tab!
Live Media Sniffer Actively sniffs network requests and video elements on webpages. Direct MP4/WebM files download via Chrome, while segmented HLS (.m3u8) and DASH (.mpd) streams route through the local engine.
Queue & Transfer Manager Inspect queued, analyzing, active, partial, and completed downloads. Cancel running transfers, retry partial or failed jobs, and open your output folder in one click.
Truthful Error Diagnostics Clear classification of network timeouts (Curl error 28), DNS resolution failures, HTTP 403 access limitations, and conversion faults instead of confusing technical traces.
Optional Authenticated Sessions Opt-in ability to pass authorized browser session cookies for personal content you own or have permission to access. Disabled by default.
Auto-Idle Shutdown (5 Min) When no downloads are actively processing or queued, the local Python service automatically shuts down after 5 minutes of inactivity to keep your PC fast and free of idle memory footprint. Restart anytime directly with 1 click from the extension's 🚀 Start Engine button.

⚡ Local Engine vs. 🌐 Browser Downloader

StreamCatch gives you full flexibility over how your files are downloaded and saved:

Capability ⚡ Local Engine (yt-dlp + FFmpeg) 🌐 Browser Downloader (Chrome Native)
Download Interface StreamCatch Queue & Activity Tab Chrome Native Download Shelf & chrome://downloads
Default Save Directory Downloads/StreamCatch Chrome's Default Download Folder / Prompt
Quality & 4K Merging Full 4K/1080p video + audio merging via FFmpeg Progressive direct streams (up to 720p/1080p)
Audio Extraction MP3, M4A, FLAC, WAV transcoded locally Direct audio stream downloads
Playlist Support Full playlist queueing & auto-numbering Direct single stream downloads
Direct Media Files Downloaded & organized to disk Downloaded instantly in browser without engine
Best For Maximum quality, 4K, playlists, batch downloads Quick single downloads in Chrome's download bar

Switch download providers instantly with the [ ⚡ Local Engine ] / [ 🌐 Browser Downloader ] toggle on the home tab, or set your persistent default in the Settings view.


🚀 Quick Start Guide

Prerequisites

  1. Python 3.8 or higher installed. (Ensure "Add python.exe to PATH" was selected during install).
  2. Google Chrome 116+, Microsoft Edge, Brave, or any Chromium browser supporting Manifest V3.

📦 Option 1: One-Command Global NPM Install (Recommended)

You can install and run StreamCatch anywhere with one npm command:

# Install globally via npm
npm install -g soahimrahman/StreamCatch

Or run it on-demand with npx without even installing:

npx github:soahimrahman/StreamCatch

Running the CLI

Once installed, start the local engine simply by running:

streamcatch

Handy CLI Commands

Command Action
streamcatch Starts the download engine on http://127.0.0.1:8735
streamcatch --open (or -o) Opens the extension/ folder in your file explorer
streamcatch --path (or -p) Prints the exact path to the extension directory
streamcatch --setup Verifies and updates yt-dlp and imageio-ffmpeg
streamcatch --test Runs the automated test suite

💻 Option 2: Local Git Clone + NPM Setup

If you prefer cloning the repository directly:

# 1. Clone repository
git clone https://github.com/soahimrahman/StreamCatch.git
cd StreamCatch

# 2. Automatically install all dependencies
npm install

# 3. Start the engine
npm start

Available npm Scripts

  • npm install (or npm run setup) — Installs and checks yt-dlp & imageio-ffmpeg.
  • npm start — Boots the local engine on 127.0.0.1:8735.
  • npm test — Executes the 8-point automated test suite.
  • npm run build — Recompiles the UI HTML templates from build_ui.py.
  • npm run troubleshoot — Runs the connection, DNS & TLS reachability probe.

🖱️ Option 3: Native One-Click Launchers (No Node.js Required)

If you don't have Node.js or npm installed, use the native launchers:

⚡ Silent Background Auto-Start & In-Extension 1-Click Launch (Recommended for Windows)

To run StreamCatch completely seamlessly without keeping a command prompt window open:

  1. Double-click:
    SETUP_AUTO_START_WINDOWS.bat
  2. What this does:
    • Zero-Fuss Boot: StreamCatch starts silently in the background whenever your PC turns on.
    • In-Extension 1-Click Launch: Adds a 🚀 Start Engine button right inside the Chrome/Edge extension. If the helper is ever stopped, you can wake it up directly from the browser!
    • Completely Invisible: Runs via silent background VBScript, so no black terminal window stays open on your taskbar.
  3. To stop the engine anytime: Double-click STOP_STREAMCATCH_WINDOWS.bat.
  4. To disable auto-start anytime: Double-click DISABLE_AUTO_START_WINDOWS.bat.

Normal Console Mode on Windows

If you prefer seeing real-time download logs in a terminal window:

START_STREAMCATCH_WINDOWS.bat

On macOS & Linux

Run:

chmod +x START_STREAMCATCH_MAC_LINUX.sh helper/START_MAC_LINUX.sh
./START_STREAMCATCH_MAC_LINUX.sh

🧩 Adding the Extension to Chrome / Edge

Note

Why is loading the extension in Developer Mode required? Due to Chromium security safeguards, Google Chrome and Microsoft Edge do not permit any command-line tool (including npm) to inject extensions directly into a browser profile without user consent (to protect against rogue spyware). Loading it takes under 10 seconds:

  1. In your browser, open:
    • Google Chrome / Brave: chrome://extensions
    • Microsoft Edge: edge://extensions
  2. Turn on Developer mode (toggle in the top-right corner).
  3. Click Load unpacked.
  4. Select the extension/ folder (or run streamcatch --open to reveal it in your file explorer).
  5. Pin StreamCatch to your browser toolbar!

🎬 Start Downloading

  1. Click the StreamCatch icon in your toolbar.
  2. The indicator will show Engine online with a green pulse.
  3. Paste a link or click Use link, choose your format and quality, and click Download now!
  4. (Optional) Click ▣ Fixed panel at the top to open the persistent side panel that stays open as you browse.

🎯 Supported Formats & Resolutions

Type Format / Container Notes
Video Best original (Auto) Downloads highest quality native streams without lossy re-encoding
Video MP4 Industry-standard compatibility (H.264/AAC or best matching streams)
Video MKV Robust container supporting multi-audio tracks and subtitles
Video WebM Modern web format (VP9/AV1 + Opus)
Audio MP3 Universal MP3 format encoded at 192 kbps
Audio M4A High-efficiency AAC audio stream
Audio WAV Uncompressed PCM audio
Audio FLAC Lossless compressed audio extraction

Resolution Caps: Best available, 4K (2160p), 1440p (2K), 1080p (Full HD), 720p (HD), 480p, 360p.


📁 Project Directory Structure

StreamCatch/
├── .github/
│   └── workflows/
│       └── ci.yml                     # Multi-OS CI workflow (Ubuntu, Windows, macOS)
├── bin/
│   └── cli.js                         # Global CLI entry point (npm install -g streamcatch)
├── scripts/                           # Cross-platform Node / npm automation
│   ├── setup.js                       # Auto-detects Python & installs pip requirements
│   └── start.js                       # Cross-platform engine runner
├── extension/                         # Chromium Extension (Manifest V3)
│   ├── manifest.json                  # Extension metadata, permissions & fixed key
│   ├── background.js                  # Background service worker & network request sniffer
│   ├── content.js                     # DOM media scanner for embedded video elements
│   ├── popup.html                     # Standard dropdown popup interface
│   ├── sidepanel.html                 # Chrome Side Panel interface
│   ├── dashboard.html                 # Full-tab workspace dashboard
│   ├── popup.js                       # UI controller, state manager & API client
│   ├── styles.css                     # Dark-mode design system & animations
│   └── icons/                         # Extension icons (16, 32, 48, 128px)
├── helper/                            # Local Python Download Engine
│   ├── server.py                      # Multi-threaded HTTP loopback server (yt-dlp/FFmpeg)
│   ├── extension_origin.py            # Extension ID & Origin integrity binding
│   ├── requirements.txt               # Engine dependencies (yt-dlp, imageio-ffmpeg)
│   ├── check_connection.py            # User-friendly network & TLS reachability probe
│   ├── CHECK_SITE_CONNECTION_WINDOWS.bat # One-click network diagnostic tool
│   ├── START_WINDOWS.bat              # Windows dependency bootstrap & server runner
│   ├── START_MAC_LINUX.sh             # POSIX bootstrap & server runner
│   ├── TROUBLESHOOT_WINDOWS.bat       # Port & HTTP diagnostic tool
│   └── UPDATE_ENGINE_WINDOWS.bat      # One-click updater for yt-dlp & FFmpeg
├── tests/
│   └── test_local_api.py              # Mocked integration test suite for engine endpoints
├── build_ui.py                        # Single-source HTML generator for extension views
├── package.json                       # npm automated scripts, CLI & package metadata
├── START_STREAMCATCH_WINDOWS.bat      # Root Windows launcher
├── START_STREAMCATCH_MAC_LINUX.sh     # Root macOS/Linux launcher
├── .gitignore                         # Complete Git ignore definitions
├── LICENSE                            # MIT License
└── README.md                          # Project documentation

🩺 Diagnostics & Troubleshooting

StreamCatch includes built-in diagnostic tools to help identify problems quickly:

1. "Curl (28) Connection Timed Out"

  • Meaning: Your computer could not establish a TCP connection to the website's media server within 25 seconds.
  • Cause: Network firewalls, DNS blocks, ISP filtering, VPN conflicts, or temporary outage on the destination server.
  • Fix: Run npm run troubleshoot (or helper/CHECK_SITE_CONNECTION_WINDOWS.bat), enter the domain, and review the DNS and TCP 443 handshake report.

2. "HTTP 403 Forbidden" When Opening http://127.0.0.1:8735/health in a Tab

  • This is expected and normal!
  • The helper enforces strict Origin and Header verification (X-StreamCatch-Client). Ordinary web pages and browser tabs cannot access the engine. An HTTP 403 proves that the local engine is online and secured against unauthorized local web scripts.

3. Port 8735 Already in Use

  • If an older instance of the helper is already running, close its terminal window or run helper/TROUBLESHOOT_WINDOWS.bat to see which Process ID (PID) owns port 8735.

4. Updating Extractor Engines

Websites frequently modify their streaming formats. Keep yt-dlp current by running:

streamcatch --setup
# or: npm run setup

(or on Windows: helper\UPDATE_ENGINE_WINDOWS.bat)


🔒 Security & Privacy Guarantees

  • Loopback Binding Only: The helper binds exclusively to 127.0.0.1. It never listens on public interfaces or your local area network (LAN).
  • Origin Validation: The local server validates that all incoming requests originate from the designated Chrome Extension ID (fhhkhlchlohgbnokeheoamkpifoiflgb).
  • No External Telemetry: StreamCatch contains zero analytics, trackers, pingbacks, or third-party tracking scripts.
  • Strict URL Sanitization: Public HTTP/HTTPS URLs are strictly validated before being submitted to the downloader pool to mitigate SSRF and local network traversal.
  • Cookie Security: Browser cookie inspection (cookiesfrombrowser) is strictly opt-in and disabled by default.

🧪 Development & Testing

Run the automated test suite via npm:

npm test

(or directly with Python: python -m unittest discover -s tests -v)

If you modify the UI in build_ui.py, recompile the template across popup.html, sidepanel.html, and dashboard.html:

npm run build

📜 Legal & Ethical Usage

StreamCatch is provided for personal archiving, educational research, and downloading media content that you own or have explicit permission to save.

  • StreamCatch does not circumvent DRM, bypass paywalls, or decrypt encrypted content.
  • Always respect copyright laws and the terms of service of any website you interact with.

👨‍💻 Creator & Support

StreamCatch is designed and engineered by Soahim Rahman Tasin.

  • 🌐 Facebook Profile: soahim.rahman.tasin17
  • ☕ Support & Donation: If StreamCatch simplifies your media downloads and saves your time, support ongoing open-source development at Support Kori.

📄 License

This project is licensed under the terms of the MIT License.


Crafted with care by Soahim Rahman Tasin.

About

Universal Video, Audio, Playlist & Bulk Media Downloader — Chromium Extension + Local Engine powered by yt-dlp & FFmpeg

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages