modenaf360/youtube-dl-nas repository overview

⁠youtube-dl-nas

An authenticated, NAS-friendly yt-dlp download queue for video, audio, and subtitles. Run it on Synology, another NAS, or any Docker host and manage downloads from a responsive web dashboard.

Current release: 26.1012 · Architectures: linux/amd64, linux/arm64

New in this release: safe filename choices for new downloads, less crowded mobile controls, and direct cookies/profile recovery with privacy-safe diagnostic copying. Existing files keep their names and duplicate detection stays enabled. Keep both volumes when upgrading; no new configuration or database is required.

Captured from 26.1012 with synthetic demo media.

⁠Quick Start

docker run -d \
  --name youtube-dl-nas \
  --restart unless-stopped \
  -e MY_ID=nas-user \
  -e MY_PW=change-this-password \
  -e TZ=Asia/Seoul \
  -v /volume2/youtube-dl:/downfolder \
  -v /volume2/docker/youtube-dl-nas:/usr/src/app/metadata \
  -p 8080:8080 \
  modenaf360/youtube-dl-nas:latest

Open http://YOUR_NAS:8080, sign in with MY_ID and MY_PW, accept the Terms of Use on first launch, and submit a URL.

The second volume is strongly recommended. It preserves the restart-safe queue, download history, terms acceptance, and signed-session state across container recreation.

⁠What You Get

• Video up to 2160p, an explicit H.264/AAC Compatible MP4 profile, audio-only M4A/MP3/Opus, and SRT/VTT subtitle downloads.
• English, Korean, Simplified Chinese, and Polish UI with automatic browser-language detection and a saved preference.
• Authenticated queue with live progress, transfer speed, ETA, and the ordered list of waiting jobs.
• Download-volume capacity status, a safe active-job stop control, retained partial data, and actionable failure guidance.
• Database-free queue recovery across container restarts, compatible partial-download continuation, duplicate guards, and removable waiting jobs.
• One-submit Smart Preflight with a three-second undo window, media-identity duplicate checks, and actionable Already on NAS receipts.
• Searchable download history with compact list and thumbnail grid views, filters, newest-first sorting, 20-item pages, and a lightweight library overview.
• Mounted-file discovery for existing files in /downfolder, including files without saved metadata.
• Inline video/audio preview, retry, browser download, history-only delete, and physical-file delete actions.
• Subtitle QA for SRT/VTT/ASS/SSA files with nlptutti CER/WER/CRR metrics and keyword preservation.
• Android PWA sharing, Android local-HTTP Shortcuts, and an installable iOS Shortcut.
• Per-device PWA share profiles, including Ask every time for review before queueing.
• Authenticated, size-bounded Netscape cookies management for restricted sources, while external mounted files remain read-only.
• Playlist Guard with explicit Current video, First 10, and All items scopes.
• Optional JPG thumbnail sidecars with local grid previews and sidecar-aware deletion.
• New-download naming: original title, channel + title, or request date + title, plus an optional custom title; IDs and extensions are retained.
• Mobile search with collapsible filters and direct playback/download actions; named destructive actions live under More with confirmation.
• REST API with normal ID/password authentication and an optional Bearer token.
• yt-dlp, yt-dlp-ejs, and Deno updates at startup and every hour by default.
• Current nlptutti installation or upgrade whenever a new container starts.
• Container health check plus PUID, PGID, and UMASK support.

⁠Dashboard

⁠MCP Collections

Release 26.0906 adds topic collections and AI Connect alongside the existing Downloads screen. Preview researched direct URLs, check dates and duplicates, and approve one idempotent batch. New media is grouped in safe nested collection folders; existing files can be linked without copying or moving them.

Create and revoke named connection tokens from the dashboard. The official Python MCP SDK runs in the normal container behind nginx at /youtube-dl/mcp, sharing the existing external port and preserving WebSocket and PWA routes. No companion image or MCP enable flag is required.

Follow the MCP guide and compatibility notes⁠ for client setup and the actual validation scope. Six native-client end-to-end certification is not claimed. Use HTTPS or a VPN for remote MCP access; bearer tokens are not encrypted by plain HTTP.

The 26.0906 Linux/AMD64 preflight measured about 157 MB total idle process RSS, including the always-on MCP service. Allow additional memory for downloads and Subtitle QA. The footprint review⁠ documents the increase over 26.0830; it is not a claim that ARM64 or download-time memory was measured. See the 26.0922 validation record⁠ for the previous release's checks and native-client coverage.

⁠Persistent Paths

⁠Main Environment Variables

See the complete Docker options⁠ for updater controls and deployment examples.

⁠Docker Compose

git clone https://github.com/hyeonsangjeon/youtube-dl-nas.git
cd youtube-dl-nas
cp .env.example .env
# Set MY_ID and MY_PW in .env
docker compose up -d

⁠Mobile Sharing

• Android + HTTPS: install the dashboard as a PWA and share links to youtube-dl NAS.
• Android + local HTTP: import the HTTP Shortcuts template and run 1. Configure NAS once.
• iPhone / iPad: install the signed Download to NAS Shortcut.

Open the English/Korean mobile setup guide⁠ for direct installation links. GitHub Pages hosts only the guide and import files; shared URLs and credentials travel directly between the phone and the NAS.

⁠Image Tags

Both current tags publish OCI manifests for AMD64 and ARM64. Pin 26.1012 when reproducibility matters; use latest to follow the current stable release.

docker pull modenaf360/youtube-dl-nas:26.1012

⁠Health Check

curl http://YOUR_NAS:8080/health

A healthy container returns HTTP 200 with queue, updater, and path-free storage-capacity status. The image also includes a Docker HEALTHCHECK, and every published build must first pass a live container smoke test.

⁠Project Links

• Source and full documentation⁠
• Installation and mobile manual⁠
• Releases⁠
• Changelog⁠
• Security policy⁠
• Issue tracker⁠

⁠Responsible Use

Use this project only for content you are authorized to download. Users are responsible for following applicable laws and the terms of the source service. See the project's legal disclaimer⁠.

MIT License · Maintained since 2018