SkillAgentSearch skills...

WebVideo2NAS

A lightweight browser-to-NAS pipeline for capturing and downloading web videos. It integrates a Chrome Extension with a NAS-hosted Docker backend (FastAPI, workers, FFmpeg) to automatically detect, queue, download, and process web video streams, converting them into playable MP4 files for long-term storage.

GenerateConvertImprove

Install / Use

/learn @asdfghj1237890/WebVideo2NAS
About this skill

Quality Score

0/100

Supported Platforms

Universal

README

WebVideo2NAS

License: MIT Docker Python Chrome Extension Release

Languages: English (README.md) | 繁體中文 (README.zh-TW.md)

Seamlessly capture web video URLs (M3U8 and MP4) from Chrome and download them to your NAS — even when sites disguise streams with non-standard URLs

[!IMPORTANT] This project does not guarantee every video can be downloaded. Some sites use DRM, expiring URLs, anti-hotlinking, IP restrictions, or change their delivery logic at any time.

[!CAUTION] It is not recommended to expose this service directly to the public internet. Prefer accessing your NAS over your LAN or via VPN (e.g. Tailscale).

Table of Contents

Overview

This system enables you to:

  1. 🔍 Detect M3U8 and MP4 video URLs in Chrome (including disguised streams)
  2. 📤 Send URLs to your NAS with one click
  3. ⬇️ Automatically download and convert to MP4
  4. 💾 Store videos on your NAS storage

System Architecture

Chrome Extension → NAS Docker (API + Worker) → Video Storage

Overall System Architecture

Backend Architecture

Backend Architecture

Quick Links

<img align="right" src="docs/extension-screenshot.png" alt="Chrome Extension Screenshot" width="300"> <p align="right"><sub>Chrome Extension Interface (Click to view full size)</sub></p>

Key Features

Chrome Extension

  • ✅ Automatic M3U8 and MP4 URL detection
  • ✅ Deep manifest interception — detects disguised streams (e.g. .jpg-wrapped HLS) via fetch/XHR content inspection
  • ✅ One-click send to NAS
  • ✅ Side panel interface for easy access
  • ✅ Real-time download progress
  • ✅ Cookie & header forwarding for authenticated streams
  • ✅ Context menu integration
  • ✅ Configurable NAS endpoint

NAS Docker Service

  • ✅ RESTful API for job management
  • ✅ Dual-worker architecture for parallel processing
  • ✅ Multi-threaded segment downloader
  • ✅ FFmpeg-based video merging
  • ✅ Job queue with Redis
  • ✅ Progress tracking & notifications
  • ✅ Persistent storage with PostgreSQL

Technology Stack

Frontend:

  • Chrome Extension (Manifest V3)
  • JavaScript ES6+

Backend:

  • Python 3.11+ (FastAPI)
  • FFmpeg
  • Redis
  • PostgreSQL
  • Docker & Docker Compose
<br clear="both">

Project Structure

webvideo2nas/
├── chrome-extension/  # Chrome extension source
├── docs/              # Documentation
├── video-downloader/  # NAS downloader (Docker stack)
│   └── docker/        # Docker services (API + Worker)
├── pics/              # Diagrams used by README
└── README.md          # This file

Requirements

For NAS

  • Docker & Docker Compose
  • 2GB+ RAM available
  • Storage space for videos
  • Network accessibility from Chrome device

For Chrome

  • Chrome browser (v88+)
  • Developer mode enabled (for unpacked extension)

Getting Started

<a id="installation"></a>

📦 Installation

Tip: This README contains the full installation guide. Expand the section below if you need the detailed steps.

<details> <summary><strong>Full Installation Guide (click to expand)</strong></summary>

This section contains the full installation guide.

Prerequisites

Hardware Requirements
  • NAS/Server: 2GB+ RAM, 2+ CPU cores, Docker support
  • Client: Chrome browser (v88+)
Software Requirements
  • Docker 20.10+
  • Docker Compose 2.0+
  • Network connectivity between Chrome and NAS

Installation (Easy Mode)

You will do 3 things:

  1. Deploy the backend on your NAS/server (pick Synology or Non-Synology)
  2. Install + configure the Chrome extension
  3. Verify it works

Step 1: Deploy backend (pick ONE)

<details> <summary><strong>Synology NAS (DSM / Container Manager) — UI-first</strong></summary>
1. Install Container Manager
  1. Open Package Center
  2. Install Container Manager
2. Prepare folders (DSM UI)
  1. Open File Station
  2. Project folder (example): /volume1/docker/video-downloader/
  3. Downloads folder (example): /volume1/<YOUR_SHARED_FOLDER_NAME>/downloads/completed
  4. Ensure the account you use in Container Manager has read/write permissions to both folders
    • If you see permission errors later (can’t write to /downloads), re-check DSM folder permissions and try creating a test file in the downloads folder.
3. Download & extract release (DSM UI)
  1. Download WebVideo2NAS-downloader-docker.zip from GitHub Releases
  2. Upload to /volume1/docker/ with File Station and extract it
  3. You should have: /volume1/docker/video-downloader/docker/
4. Create .env (only 2 values are required)

Create /volume1/docker/video-downloader/docker/.env (DSM text editor or upload from PC):

DB_PASSWORD=your_secure_password_here
API_KEY=your_api_key_minimum_32_chars
MAX_DOWNLOAD_WORKERS=20
MAX_RETRY_ATTEMPTS=3
FFMPEG_THREADS=2
LOG_LEVEL=INFO
ALLOWED_ORIGINS=chrome-extension://*
CORS_ALLOW_CREDENTIALS=false
RATE_LIMIT_PER_MINUTE=10
ALLOWED_CLIENT_CIDRS=
SSRF_GUARD=false
5. Deploy with Projects (DSM UI)
  1. In /volume1/docker/video-downloader/docker/, rename docker-compose.synology.yml → docker-compose.yml
  2. Open Container Manager → Projects → Create
  3. Select project folder: /volume1/docker/video-downloader/docker
  4. Finish the wizard and start the project
6. Verify

Open http://YOUR_SYNOLOGY_IP:52052/api/health → should return {"status":"healthy"}

</details> <details> <summary><strong>Non-Synology / Standard Docker — command line</strong></summary>
1. Download & extract release
wget https://github.com/asdfghj1237890/WebVideo2NAS/releases/latest/download/WebVideo2NAS-downloader-docker.zip
mkdir -p docker
cd docker
unzip ../WebVideo2NAS-downloader-docker.zip
cd video-downloader/docker
mkdir -p ../logs ../downloads/completed
2. Create .env (only 2 values are required)
API_KEY=$(openssl rand -base64 32)
DB_PASSWORD=$(openssl rand -base64 24)

## If you don't have openssl, set API_KEY/DB_PASSWORD manually (any strong random strings)
cat > .env << EOF
DB_PASSWORD=${DB_PASSWORD}
API_KEY=${API_KEY}
MAX_DOWNLOAD_WORKERS=20
MAX_RETRY_ATTEMPTS=3
FFMPEG_THREADS=2
LOG_LEVEL=INFO
ALLOWED_ORIGINS=chrome-extension://*
CORS_ALLOW_CREDENTIALS=false
RATE_LIMIT_PER_MINUTE=10
ALLOWED_CLIENT_CIDRS=
SSRF_GUARD=false
EOF

echo "Your API Key: ${API_KEY}"
3. Deploy & verify
docker-compose up -d
curl http://localhost:52052/api/health
</details>

Step 2: Install + configure Chrome extension

  1. Open chrome://extensions/
  2. Enable Developer mode
  3. Click Load unpacked
  4. Select the chrome-extension folder
  5. Open extension Settings:
    • NAS Endpoint: http://YOUR_NAS_IP:52052 (use your NAS/server LAN IP; not localhost)
    • API Key: your API_KEY from .env
  6. Click Test Connection → should show connected
<details> <summary><strong>(Optional) Custom icons</strong></summary>

Icons should already exist in chrome-extension/icons/ (icon16.png, icon48.png, icon128.png). If you want to replace them, create PNGs with those names and overwrite the files.

</details>

Step 3: What to do if something doesn't work

</details>

Current Status: Core Features Complete ✅

You can now:

  • ✅ Deploy Docker stack on Synology NAS or any Docker host
  • ✅ Download M3U8 video streams to MP4
  • ✅ Download MP4 videos directly
  • ✅ Detect disguised manifests via JS-level content interception
  • ✅ Use Chrome extension for automatic detection (M3U8 & MP4)
  • ✅ Forward cookies & headers for authenticated streams
  • ✅ Monitor download progress in side panel
  • ✅ Manage downloads via REST API

Usage

  1. Browse to any video streaming site
  2. When video URL (M3U8/MP4) is detected, extension badge shows notification
  3. Click extension icon to open side panel, or right-click → "Send to NAS"
  4. Video downloads automatically to your NAS (with cookies for authenticated streams)
  5. Monitor progress in the side panel
  6. Access completed videos in /downloads/completed/

Configuration

Environment Variables (.env)

API_KEY=change-this-to-a-very-long-secure-key-minimum-32-chars
DB_PASSWORD=ChangeThisPassword123!

# Logging
LOG_LEVEL=INFO

# CORS (API)
ALLOWED_ORIGINS=chrome-extension://*
# Optional: allow credentials (requires explicit origins; wildcard will be rejected)
CORS_ALLOW_CREDENTIALS=false

# Worker tuning (per-video parallelism)
MAX_DOWNLOAD_WORKERS=20
MAX_RETRY_ATTEMPTS=3
FFMPEG_THREADS=2

# DB cleanup (db_clea

asdfghj1237890

View profile

View on GitHub
GitHub Stars1.1k
CategoryContent
Updated1d ago
Forks66
asdfghj1237890/WebVideo2NAS

Languages

JavaScript

Security Score

85/100

Audited on Mar 26, 2026

No findings