StreamFetch

Cross-platform desktop downloader for YouTube and other platforms, built with Electron + React and powered by yt-dlp. Pre-built release artifacts are published for Windows, macOS, and Linux.

Screenshots

Link & Fetch Workspace

Main dashboard for pasting a link, fetching metadata, picking a format, selecting a clip range, enabling Turbo download, and adding items to the queue.

Queue Overview & Logs

Active queue workspace with download overview, per-job status, and inline logs for the selected item.

History Archive

History dashboard for browsing past downloads with day grouping, status filters and inline details.

Defaults & Updates Settings

Settings workspace for saving defaults, checking system status, and managing app and yt-dlp updates.

Highlights

• Notion-like desktop workspace with dedicated New Download, Active Queue, History, and Settings views
• Queue-based downloads with per-item progress, transfer size and logs
• Format picker listing every stream with resolution, FPS, codec and estimated size
• Open the finished file's folder straight from the queue or history
• Pause, resume, cancel, and retry controls
• Optional clip-range downloads with a two-handle range control
• Smart fallback strategy for format/download failures
• Built-in yt-dlp updater with progress feedback while metadata loads
• In-app app-update notification (checks GitHub latest release)
• Conditional auth handling for age/bot-restricted content
• Clear centered popup when no downloadable formats are available
• Light and dark themes that follow the app, not the OS flash

Keyboard shortcuts

Shortcut	Action
Enter	Inspect the URL in the address field
Ctrl + Enter	Add the current setup to the queue
Ctrl + 1 … 4	Jump between New Download, Active Queue, History and Settings
Ctrl + F	Search history
Ctrl + L	Focus the URL field
Esc	Close the open dialog

Dropping a link anywhere on the window starts a metadata fetch, and the Paste button reads the clipboard through the main process.

Restricted/Age Content Handling

StreamFetch handles restricted content in a guided flow:

1. Try normal fetch/download first.
2. If authentication is required, a popup appears (browser cookies).
3. If browser cookie access fails (DPAPI/locked DB), popup enables cookies.txt import.
4. Retry can be applied both at fetch-time and download-time.
5. If video still has no downloadable streams, StreamFetch shows a dedicated "No Downloadable Formats" popup.

Features

• Single video and playlist support (a playlist URL queues every item)
• Structured workspace shell with sidebar navigation and saved defaults
• Format picker for video+audio, video-only (merged with the best audio track) and audio-only streams
• Clip-range download for single videos (ss, mm:ss, hh:mm:ss)
• Global speed limit (500K, 2M, 1.5M)
• Download history with day grouping, status filters, search and inline logs
• Runtime logs with progress-line filtering, copy and export
• Frameless desktop UI with custom window controls
• Single-instance guard so two windows never share one download queue

Requirements

• yt-dlp is required and is bundled with every release build.
• ffmpeg is strongly recommended and also bundled. Without it StreamFetch cannot merge separate video and audio streams, so quality falls back to single-file formats and clip-range downloads are disabled. Settings → System status reports whether FFmpeg was detected.

Tech Stack

• Electron 34
• React 18 + Vite 6
• Tailwind CSS 3
• yt-dlp + optional ffmpeg

Project Structure

streamfetch/
  electron/        # Main process + preload bridge
  src/             # React renderer
  bin/             # Platform binaries bundled into release builds
  release/         # Build outputs

Quick Start (Development)

npm install
npm run dev

Run Built Renderer + Electron

npm run build:renderer
npm start

Build for macOS or Linux (Source)

Release builds bundle yt-dlp and ffmpeg automatically in CI.

For local source builds, provide binaries in bin/ for your platform (yt-dlp and optional ffmpeg) or install them in your system $PATH, then clone and build:

git clone https://github.com/Shripad735/streamfetch.git
cd streamfetch
npm install
npm run build

Build Windows Setup (Local)

Pre-built Windows setup executables are published with every release. To build locally:

npm run build:win

Artifact is created in release/:

• StreamFetch-Setup-<version>.exe (installer)

Build macOS DMG (Local)

npm run build:mac

Build Linux AppImage (Local)

npm run build:linux

Clip-Range Download (Time Span)

You can download only a specific part of a single video:

1. Fetch video metadata.
2. Turn Clip range on inside Download options.
3. Drag the range handles, or type Start time and End time using ss, mm:ss, or hh:mm:ss.
4. Queue the job.

Notes:

• Clip range is available only for single videos (not playlist jobs).
• ffmpeg is required for clip extraction.

Release Workflow

• GitHub workflow runs on v* tags (for example v1.4.0).
• Workflow validates that tag version (vX.Y.Z) matches package.json version.
• Tagged releases build artifacts for Windows, Linux, and macOS.
• macOS build is configured as non-blocking in CI (to avoid blocking release when mac runners are unavailable).
• Release notes are auto-generated from commits between the previous release tag and the current tag.
• Notes are grouped into Features, Fixes, and Other Changes based on commit message prefix.

Use these commit prefixes to classify notes:

• feat: add app update notification banner
• fix: handle age-restricted download retry
• hotfix: prevent renderer crash on startup

Security Model

• nodeIntegration: false
• contextIsolation: true
• Strict preload bridge for allowed IPC channels only
• Download execution uses validated spawn arguments
• Renderer navigation and window.open are blocked and delegated to the system browser
• Content-Security-Policy set on the app shell
• Local file access limited to the paths the user picks

Required Local Binaries

For source-based development, place these files in bin/ for your target platform:

• yt-dlp or yt-dlp.exe (required)
• ffmpeg or ffmpeg.exe (optional, enables merged best-quality outputs)

These binaries are not committed to git to keep repository size small.

Releases

Install from GitHub Releases for the easiest setup. Each tagged release includes:

• Windows installer (Setup .exe)
• macOS disk image (.dmg)
• Linux AppImage (.AppImage)

License

MIT