YouTube and yt-dlp
YouTube is the platform most visitors come for, and the one that defends itself hardest against servers. This chapter explains how a YouTube link is read, why a server can be turned away, and the yt-dlp page.
How a YouTube link is read
The YouTube module knows watch links, youtu.be links, Shorts, embed and live links, m.youtube.com and music.youtube.com. It asks YouTube's own player service for the video and presents itself as one of four YouTube apps, in this order: visionOS (Apple Vision Pro), Android VR (Meta Quest), iOS, Android.
The first two need a visitor id, the small token YouTube gives every browser. The site fetches one, keeps it for half an hour and asks for a fresh one when YouTube answers "Sign in to confirm you're not a bot".
An answer is accepted only when one byte near the end of a file can be read. Many app clients hand out addresses that refuse everything after the first minute of a file, so a download would stop early. Such a client is skipped and the next one is asked.
The visitor gets videos with sound, the HD sizes without sound (joined with the sound while downloading when Offer "video with audio" for split streams is on under Settings → Downloads) and the sound alone as M4A and WebM. Every file address names the server address that asked for it, so the download leaves the server the same way the link was read.
Platforms → Test a link lists what was tried: each client, its answer and the result of the check.
Dubbed sound tracks
Many videos carry their sound in several languages: the original, dubbed and auto-dubbed tracks, sometimes an audio description. The results page then shows an Audio language chooser. Who may use it is YouTube audio languages (dubbed sound tracks) on Settings → Downloads (also on the Users tab): Everyone (the default), Members, Members with a confirmed e-mail address, or Switched off, which removes the chooser so every download carries the original sound.
Shorts and playlists
A Shorts link is read like any other video. The link of a whole list (a playlist, the uploads of a channel, an album) opens a page with every video, a tick box for each and Download selected; a "Mix" that YouTube makes up for one viewer cannot be read. Who may open lists and how many videos they show is set on Settings → Downloads (Who may open a playlist, Videos listed of one playlist ...).
When YouTube turns the server away
YouTube distrusts the addresses of data centres. Either every client is answered "Sign in to confirm you're not a bot", or the files can only be read for their first minute. The visitor reads "Download failed. Please try again." and the bell of the admin panel says that YouTube refuses this server. There are three answers, and they work together:
- Routes and proxies. YouTube is set to When the server is refused (automatic) from the start: the same link is asked again through the server's other address family (IPv4 or IPv6), another address of the server or a proxy of the pool. See Proxies and routes.
- Cookies of a YouTube account. Settings → Platform Cookies → YouTube cookies takes the Cookie line of a signed-in browser. Only the iOS and Android clients send it (the other two cannot carry an account), and those mostly get the one-minute addresses; the yt-dlp Bridge does not read it. Do not count on it against a refused server, and use a spare account. (YouTube channel on Settings → Appearance is only a footer link.)
- yt-dlp. When all four clients fail, the module hands the link to the plugins: first the yt-dlp Bridge, which runs yt-dlp on the server, then External API Fallback when one is set up. yt-dlp is also the only way the site reads a private YouTube video with the cookies a visitor pastes. See yt-dlp Bridge and External API Fallback.
The yt-dlp page
Admin → Downloads → yt-dlp. yt-dlp is a free command-line program that knows how YouTube wants to be asked. The site fetches it, keeps it new and runs it. The badge at the top says Ready, Installed, plugin off, Does not run or Not installed.
PHP must be allowed to start programs (the function proc_open). When the host has switched it off, a red box says so: ask the host to allow it, or move the site to a VPS.
Installing with one button
Install yt-dlp fetches the official release from GitHub, compares it with the published checksums (SHA2-256SUMS; a file that does not match is thrown away), runs it once and takes it into use only when it answers. The path is saved and the yt-dlp Bridge is switched on. A yt-dlp already in storage/bin, or installed for the whole server (for example /usr/local/bin/yt-dlp), is taken as it is.
| Server | File |
|---|---|
| Linux, 64-bit | yt-dlp_linux, then yt-dlp_musllinux (the other way round on Alpine) |
| Linux, ARM 64-bit | the same files ending in _aarch64 |
| Windows | yt-dlp.exe (yt-dlp_arm64.exe, yt-dlp_x86.exe) |
| macOS | yt-dlp_macos |
When none of them runs, the small Python edition (yt-dlp, Python 3.10 or newer) is tried last. The file lives in storage/bin, which is closed to the web.
The State card shows the version, the newest release, the file, the JavaScript runtime and the plugin. Below it: Update to ... or Install again, Check (also takes in a file you uploaded by hand) and Remove. Read it with yt-dlp reads a public video and counts its formats, without downloading anything.
The JavaScript runtime
YouTube hides its links behind small JavaScript puzzles that yt-dlp solves with Deno or Node 20 or newer. The site looks for both by itself, cPanel and CloudLinux places included. Install Deno fetches it into storage/bin (about 42 MB, checksum checked); where Deno has no build, use Node. Without a runtime, public videos still work but formats may be missing.
Updates and your own paths
Install yt-dlp and keep it new automatically (on by default) is the cron task ytdlp, every six hours: it installs yt-dlp when it is missing (after a failed try it waits three days) and replaces it when a newer release is out, only after the new one has run. The bell reports both. See Scheduled jobs.
A yt-dlp of your own (optional) (yt_dlp_path) is filled in by the installer. Write a path there only for a yt-dlp installed elsewhere: it is tried before it is saved, and you keep it new yourself. JavaScript runtime (optional) takes the full path of deno or node when the site does not find it.
The guide on the page
The right-hand column explains the other ways step by step: the Terminal of cPanel or SSH (a few curl lines, then Check); the File Manager (upload the file into storage/bin, permissions 755, then Check); a whole VPS (/usr/local/bin/yt-dlp, kept new with sudo yt-dlp -U); and When it does not run ("Permission denied", "GLIBC_2.xx not found", no Python, no way to GitHub).