yt-dlp Bridge
On this page
yt-dlp Bridge connects the site to yt-dlp, the free command-line program that reads videos from YouTube and many other sites. The script itself installs yt-dlp and keeps it new (see YouTube and yt-dlp); this plugin is what runs it. It is free and works with every licence.
What it does
The plugin has two jobs:
- Private YouTube videos. A visitor who switches on Private video under the download box pastes the cookies of their own browser. yt-dlp reads the video with those cookies, for that one download.
- A second chance. When a platform module cannot read a link, yt-dlp is asked before the visitor gets an error.
When it is asked
The plugin answers the media_fallback hook. Five modules call it when they give up: YouTube, Facebook, Instagram, TikTok and X. For YouTube that is after all four YouTube app clients have failed. The other modules handle their failures themselves, and a link from a site that no module knows is answered "This website is not supported yet." before any plugin is asked.
When External API Fallback is on as well, yt-dlp is asked first and the external API only when yt-dlp found nothing.
yt-dlp runs as --dump-json --no-warnings --no-playlist --no-check-certificates plus your Extra arguments, and its list of formats becomes the formats of the results page. Storyboard pictures and DASH segment lists are left out; HLS streams are kept.
Switching it on
- Open Admin → Downloads → yt-dlp and press Install yt-dlp. As soon as yt-dlp answers, the plugin is switched on by itself.
- Or switch it on yourself: Admin → Plugins → yt-dlp Bridge → Enable.
Without yt-dlp, or on a server where PHP may not start programs (the function proc_open), the plugin is on but does nothing. The yt-dlp page shows Installed, plugin off when yt-dlp is there and the plugin is not.
Settings
Admin → Plugins → yt-dlp Bridge → Settings:
| Setting | Default | What it does |
|---|---|---|
| Timeout (seconds) | 40 | How long one run may take (10 at least). |
| Extra arguments | empty | Added to every yt-dlp command, for example --cookies /path/cookies.txt. |
| Also try yt-dlp first for sites that have no plugin | off | In version 1.7.0 this switch does not change anything yet. |
Where yt-dlp lies, how it is kept new and which JavaScript runtime it uses are set on the yt-dlp page itself: A yt-dlp of your own (optional), JavaScript runtime (optional) and Install yt-dlp and keep it new automatically. Settings → Advanced only carries a link to that page.
Private YouTube videos
Who may use them is Private videos (YouTube, Facebook) on Settings → Users (members by default; see Member accounts). When a visitor sends a private YouTube link:
- the cookies are written to a temporary
cookies.txtinstorage/tmpthat only the site can read; - yt-dlp reads the video with
--cookies(a--cookiesin Extra arguments is left out of that run, so the visitor's account is the one asked); - the file is deleted as soon as yt-dlp has finished. A file left by a run that was cut off is removed by a later one after ten minutes.
The cookies never reach the database, the cache or a log. The result has no share buttons, a note above its formats says it was read with the visitor's cookies, and its title stays out of "Recently downloaded".
When yt-dlp is not ready, the visitor reads "Private YouTube videos need yt-dlp on this site." Private Facebook videos do not need yt-dlp.
What the visitor sees
Nothing new: the usual results page, with the formats yt-dlp found under the names yt-dlp gives them. Only you can tell where a result came from: Platforms → Test a link shows the raw result, and one from yt-dlp says "via": "yt-dlp".
Performance and server notes
- Every run starts a separate program, so a link read this way takes longer and more memory than one read by a module. Keep the timeout short enough that visitors do not wait for nothing.
- yt-dlp leaves from the server's own address; the proxies of a platform are not used for it. A server that YouTube refuses may be refused to yt-dlp too. yt-dlp's own options, such as
--proxy, can go into Extra arguments. - A YouTube file found through yt-dlp is downloaded in one request, not in pieces, so it can arrive more slowly than one found by the module.
- A run that timed out writes "yt-dlp timed out for ..." into the Application log on System check; a run that returned nothing writes what yt-dlp complained about.
Tips
- Leave Install yt-dlp and keep it new automatically on. An old yt-dlp is the most common reason a video is not read.
- After a change, press Read it with yt-dlp on the yt-dlp page, then try the same link on Platforms → Test a link.
- Install a JavaScript runtime (Deno, or Node 20 or newer): without one YouTube formats may be missing, and videos read with a visitor's cookies can fail.
- Give private videos to members only: it is a good reason to create an account, and it keeps the number of yt-dlp runs down.