Installation, operations, and mobile sharing guides for youtube-dl-nas
The authenticated dashboard manages individual video, audio, and subtitle downloads on your NAS.
Use the language selector before sign-in or in the dashboard header to choose English, Korean, Simplified Chinese, or Polish. The app detects a supported browser language on first use, falls back to English, and remembers your selection.
Release 26.0906 keeps Downloads, Collections, and AI Connect in one
navigation bar on both desktop and mobile. Keep the existing download and
metadata volumes mounted when upgrading.
In Collections, choose Collect URLs, enter a name and purpose, and paste one direct media URL per line. Publication-date bounds are optional; the default batch limit is 25. Preview candidates checks metadata, date policy, existing files, and queued work without starting downloads or creating a media folder. Out-of-range candidates cannot be selected. Unknown publication dates start unchecked and need your explicit selection.
Choose a suggested existing collection or create a new one, then Approve and collect once. A preview lasts 30 minutes. Retrying an approved commit returns the same batch. Existing files are linked, not copied, and matching queued jobs gain collection membership rather than being submitted again.
A collection shows its purpose, publication-date criteria, immutable folder, item count, stored size, and live batch states. List and grid views share the dashboard’s preview and download behavior; Details → Manage in Downloads opens the existing history actions. Files removed outside the app are shown as missing rather than being silently dropped from the collection.
Edit collection changes its display name and purpose, not the physical folder. Remove collection removes only organization metadata: files, folders, and approved downloads are not deleted or canceled. Clear Rows in Downloads also preserves collections, memberships, and batches.
In AI Connect, name a connection, copy the token shown once, and choose a client’s setup instructions. Revoke each connection independently when no longer needed. AI clients search the web; this server receives direct URLs and does validation, duplicate detection, grouping, and queueing. See MCP setup and security boundaries.
Choose Compatible MP4 (H.264/AAC) for clients that need broadly playable codecs. This profile fails honestly when the source does not offer that combination; it does not transcode media or change the meaning of Best.
After a request is queued successfully, the dashboard remembers that profile on the current device. A new or invalid preference falls back to Best, and URLs are never submitted automatically.
Open Options to save a JPG thumbnail beside the media file, choose the profile used by PWA mobile sharing on this device, or manage a Netscape cookies file for restricted sources. Ask every time prefills the shared URL in this form so you can review its output profile.
Cookies are sensitive account credentials. Upload only a file exported for a site you are authorized to access. An app-managed file is validated, limited to 1 MiB, stored in the persistent metadata volume with owner-only permissions, and can be replaced or removed here. If YTDLP_COOKIES_FILE points to an external mount, Options reports its readiness but cannot modify it.
When a URL points to a playlist or channel, Playlist Guard shows a scope selector. A video URL that also carries a playlist defaults to Current video only. Pure playlist and channel URLs require First 10 or All items before they can be queued. Each completed item receives its own Files & History row.
Under Options → Filename, choose original title, channel + title, or request date + title. An optional custom title replaces only the title portion. The extractor/media ID and extension remain in every filename. Custom titles are limited to 80 characters and 160 UTF-8 bytes and cannot contain path separators, control characters, or reserved filename punctuation. Naming applies to new requests only; existing files are not renamed and duplicate checks still apply. The request date follows the NAS timezone and stays the same on retry.
A failed item’s details offer Open cookies settings for authentication failures and Retry with another profile for unavailable formats. Retrying keeps the original collection, date policy, and filename choices. Copy safe diagnostics shows only app/yt-dlp versions, status, failure category, profile, and storage state. URLs, titles, filenames, paths, cookies, and raw output are excluded. When the browser blocks clipboard access, select and copy the shown text manually.
The activity panel shows the active title, channel, thumbnail, progress, transfer speed, ETA, and free space on the download volume. Up next lists waiting requests in processing order with their source and selected quality.
When a request becomes active, Smart Preflight checks its metadata and existing NAS files while a three-second start window runs. The remove control undoes the request during this phase without adding a canceled history row. The transfer starts automatically as soon as both checks are ready; slow metadata does not incur another three-second delay. After transfer begins, the control changes to the square Stop action and retains compatible partial data.
If the stable media identity already exists, the transfer is skipped and an Already on NAS receipt offers Preview, Download File, and Details. The receipt remains available briefly even if a WebSocket update was missed. A metadata warning does not block the actual yt-dlp attempt.
The storage indicator warns at 10 GiB free and pauses new queue additions at 2 GiB free by default. Failed items show a safe reason and a concrete next action in the detail panel without saving credentials, cookie contents, private URLs, or mounted paths as diagnostics.
The queue is saved in the persistent metadata volume without a database. If the container restarts, the interrupted active request returns first, followed by the remaining jobs. Restored jobs are labeled Restored after restart. Compatible partial files continue through yt-dlp; exact byte-range resume support depends on the source.
The same normalized URL, download profile, and options cannot be queued twice accidentally. A second check uses the extracted media ID to detect an existing NAS file. Repeated completion signals reuse the existing history row and its original download date. Failed history items remain retryable because no completed file is present.
On desktop, the detail area opens with Library Overview. On compact and mobile layouts, use the statistics button in Files & History to open the same layer. It summarizes stored-file count and size, completed downloads from the last 7 days, a 14-day activity chart, media-type distribution, and recorded failures from the current history. Mounted files count toward stored-library totals but not download activity. Selecting a media type or failure group applies the existing history filters.
Use Preview to play an existing video or audio file without downloading it again. Saved thumbnail sidecars are used in the grid and listed in item details. Other actions can retry a failed job, download the saved file, remove only its history row, or delete the physical file and its thumbnail sidecar.
List and grid rows keep Preview and Download directly accessible. More opens the remaining named actions; deletion still asks for confirmation. Idle mobile activity is compact, but an Already on NAS receipt remains visible.
When a mobile browser returns from the background, Files & History and Current Activity refresh automatically without resetting the selected view, filters, page, or detail item.
For an available SRT, VTT, ASS, or SSA file, select Subtitle QA from the item actions. Paste the verified reference transcript and optionally add comma- or line-separated keywords, then select Analyze.
The result reports character accuracy (CRR), character error rate (CER), word error rate (WER), character edit counts, and keyword preservation. The selected file and reference text remain inside the NAS container. nlptutti is installed or upgraded when a new container starts so the analyzer follows current package releases.
Files already present in /downfolder are discovered automatically. When no saved download record exists, the dashboard labels the item Mounted and No metadata. The file remains available for preview, browser download, and deletion, but its original source URL and quality cannot be reconstructed.
Clearing history rows does not delete physical files. Kept files are discovered again as mounted files.
docker compose pull
docker compose up -d
The latest and 26.1012 images support linux/amd64 and linux/arm64.
Keep both existing mounts. No manual migration is required; existing filenames,
history dates, and collections are preserved. Tightening private-source policy
no longer prevents saved collections from loading, while transfers and retries
still check the current policy.
For phone sharing, continue to the Mobile Share Setup.