Restructure wiki: index by topic, add Bookmarklets, Reverse proxy configs, Troubleshooting FAQ; fix ModifyChapters remove_sponsor_segments in SponsorBlock recipe

2026-07-23 13:22:48 +00:00 · 2026-07-17 15:37:29 +03:00
parent 9e9591ce37
commit 286efea627
5 changed files with 137 additions and 5 deletions
@@ -0,0 +1,32 @@
+Bookmarklets let you send the currently open webpage to MeTube with one click from your bookmarks bar.
+
+## Prerequisites
+
+* **HTTPS:** if you're on an HTTPS page (e.g. youtube.com), your MeTube instance must be served over HTTPS too — either with `HTTPS=true` in the environment or behind an HTTPS reverse proxy (see [Reverse proxy configurations](Reverse-proxy-configurations)) — otherwise the browser blocks the request as mixed content.
+* **CORS:** bookmarklets run in the context of the current page, so their requests to MeTube are cross-origin. Add the origins of the sites where you use the bookmarklet to the `CORS_ALLOWED_ORIGINS` environment variable, e.g. `CORS_ALLOWED_ORIGINS=https://www.youtube.com,https://www.vimeo.com`.
+
+GitHub doesn't allow embedding JavaScript as a link, so create a new bookmark on your bookmarks bar manually and paste the code below as its URL. Change `metube.domain.com` to point to your MeTube instance.
+
+## Chrome
+
+Contributed by [kushfest](https://github.com/kushfest).
+
+```javascript
+javascript:!function(){xhr=new XMLHttpRequest();xhr.open("POST","https://metube.domain.com/add");xhr.withCredentials=true;xhr.send(JSON.stringify({"url":document.location.href,"quality":"best"}));xhr.onload=function(){if(xhr.status==200){alert("Sent to metube!")}else{alert("Send to metube failed. Check the javascript console for clues.")}}}();
+```
+
+## Firefox
+
+Contributed by [shoonya75](https://github.com/shoonya75).
+
+```javascript
+javascript:(function(){xhr=new XMLHttpRequest();xhr.open("POST","https://metube.domain.com/add");xhr.send(JSON.stringify({"url":document.location.href,"quality":"best"}));xhr.onload=function(){if(xhr.status==200){alert("Sent to metube!")}else{alert("Send to metube failed. Check the javascript console for clues.")}}})();
+```
+
+## Toast notification variant
+
+The above bookmarklets use `alert()` for notifications. This variant shows a toast instead (Chrome — for Firefox, replace the `!function(){...}()` wrapper with `(function(){...})()`):
+
+```javascript
+javascript:!function(){function notify(msg) {var sc = document.scrollingElement.scrollTop; var text = document.createElement('span');text.innerHTML=msg;var ts = text.style;ts.all = 'revert';ts.color = '#000';ts.fontFamily = 'Verdana, sans-serif';ts.fontSize = '15px';ts.backgroundColor = 'white';ts.padding = '15px';ts.border = '1px solid gainsboro';ts.boxShadow = '3px 3px 10px';ts.zIndex = '100';document.body.appendChild(text);ts.position = 'absolute'; ts.top = 50 + sc + 'px'; ts.left = (window.innerWidth / 2)-(text.offsetWidth / 2) + 'px'; setTimeout(function () { text.style.visibility = "hidden"; }, 1500);}xhr=new XMLHttpRequest();xhr.open("POST","https://metube.domain.com/add");xhr.send(JSON.stringify({"url":document.location.href,"quality":"best"}));xhr.onload=function() { if(xhr.status==200){notify("Sent to metube!")}else {notify("Send to metube failed. Check the javascript console for clues.")}}}();
+```
@@ -1,5 +1,17 @@
-Welcome to the MeTube wiki!
+Welcome to the MeTube wiki — the companion to the [README](https://github.com/alexta69/metube#readme). The README holds the versioned reference (setup, environment variables, yt-dlp option concepts); the wiki holds guides, recipes, and contributed configurations.

-### Useful configurations that can be set via environment variables
-* [YTDL_OPTIONS Cookbook](YTDL_OPTIONS-Cookbook) - Example configurations for `YTDL_OPTIONS` and `YTDL_OPTIONS_FILE`.
-* [OUTPUT_TEMPLATE Cookbook](OUTPUT_TEMPLATE-Cookbook) - Example configurations for `OUTPUT_TEMPLATE`.
+### Configuration recipes
+* [YTDL_OPTIONS Cookbook](YTDL_OPTIONS-Cookbook) — example configurations for `YTDL_OPTIONS` and `YTDL_OPTIONS_FILE`.
+* [OUTPUT_TEMPLATE Cookbook](OUTPUT_TEMPLATE-Cookbook) — example configurations for `OUTPUT_TEMPLATE`.
+
+### Integrations
+* [Bookmarklets](Bookmarklets) — send the current browser page to MeTube with one click.
+* [Reverse proxy configurations](Reverse-proxy-configurations) — NGINX, Apache, Caddy, and swag examples.
+
+### Guides
+* [Subscriptions](Subscriptions) — auto-download new uploads from channels and playlists.
+* [Troubleshooting FAQ](Troubleshooting-FAQ) — common issues and how to diagnose them.
+
+---
+
+To contribute a recipe or configuration, [open an issue](https://github.com/alexta69/metube/issues) with the snippet and a short description of what it does — it will be added here with attribution.
@@ -0,0 +1,55 @@
+MeTube can run behind a reverse proxy for HTTPS termination or authentication. When serving under a subdirectory, set `URL_PREFIX` accordingly. MeTube uses WebSocket (Socket.IO) for real-time updates, so the proxy must pass the `Upgrade`/`Connection` headers — the examples below all do.
+
+## NGINX
+
+```nginx
+location /metube/ {
+        proxy_pass http://metube:8081;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+}
+```
+
+## Apache
+
+Contributed by [PIE-yt](https://github.com/PIE-yt). Source [here](https://gist.github.com/PIE-yt/29e7116588379032427f5bd446b2cac4).
+
+```apache
+# For putting in your Apache sites site.conf
+# Serves MeTube under a /metube/ subdir (http://yourdomain.com/metube/)
+<Location /metube/>
+    ProxyPass http://localhost:8081/ retry=0 timeout=30
+    ProxyPassReverse http://localhost:8081/
+</Location>
+
+<Location /metube/socket.io>
+    RewriteEngine On
+    RewriteCond %{QUERY_STRING} transport=websocket    [NC]
+    RewriteRule /(.*) ws://localhost:8081/socket.io/$1 [P,L]
+    ProxyPass http://localhost:8081/socket.io retry=0 timeout=30
+    ProxyPassReverse http://localhost:8081/socket.io
+</Location>
+```
+
+## Caddy
+
+The following example Caddyfile gets a reverse proxy going behind [caddy](https://caddyserver.com).
+
+```caddyfile
+example.com {
+  route /metube/* {
+    uri strip_prefix metube
+    reverse_proxy metube:8081
+  }
+}
+```
+
+## swag (with Authelia)
+
+The [linuxserver/swag](https://docs.linuxserver.io/general/swag) image includes ready-made snippets for MeTube in [subfolder](https://github.com/linuxserver/reverse-proxy-confs/blob/master/metube.subfolder.conf.sample) and [subdomain](https://github.com/linuxserver/reverse-proxy-confs/blob/master/metube.subdomain.conf.sample) modes, plus Authelia for authentication.
+
+---
+
+Have a working config for another proxy (Traefik, nginx-proxy-manager, HAProxy…)? [Open an issue](https://github.com/alexta69/metube/issues) with the snippet and it will be added here with attribution.
@@ -0,0 +1,33 @@
+MeTube is only a UI for [yt-dlp](https://github.com/yt-dlp/yt-dlp): most download problems are yt-dlp problems, and the fastest way to diagnose them is to run yt-dlp directly with the same options. To test inside the container:
+
+```bash
+docker exec -ti metube sh
+cd /downloads
+yt-dlp <url>
+```
+
+Once a set of yt-dlp flags works, translate it into `YTDL_OPTIONS` (see [Configuring yt-dlp options](https://github.com/alexta69/metube#%EF%B8%8F-configuring-yt-dlp-options) in the README).
+
+## "Sign in to confirm you're not a bot" / age-restricted / members-only videos
+
+YouTube increasingly requires an authenticated session. Export your browser cookies and upload them via **Advanced Options → Upload Cookies** — see [Using browser cookies](https://github.com/alexta69/metube#-using-browser-cookies) in the README.
+
+## Downloaded files are owned by root / permission errors
+
+Set `PUID`/`PGID` to the user that should own the files (defaults are `1000`/`1000`), and `UMASK` if you need specific permissions. If you manage ownership yourself, set `CHOWN_DIRS=false`.
+
+## Downloads fail immediately after working for months
+
+Video sites change their layouts constantly; the fix is almost always a yt-dlp update. A new MeTube image is published automatically when a new yt-dlp stable is released — update your container (e.g. with [watchtower](https://github.com/nicholas-fedor/watchtower)). To get fixes earlier, follow the nightly channel via `YTDL_NIGHTLY_UPDATE_TIME`.
+
+## The UI loads but downloads never start / no progress updates
+
+MeTube uses WebSocket (Socket.IO) for real-time updates. If you're behind a reverse proxy, it must forward the `Upgrade`/`Connection` headers — see [Reverse proxy configurations](Reverse-proxy-configurations).
+
+## Browser extension / bookmarklet requests are blocked
+
+Cross-origin requests are denied unless `CORS_ALLOWED_ORIGINS` is configured — see the [Sending links to MeTube](https://github.com/alexta69/metube#-sending-links-to-metube) section in the README.
+
+---
+
+Something missing here? [Open an issue](https://github.com/alexta69/metube/issues).
@@ -40,7 +40,7 @@ NOTE: due to the complex usage of quotes here (both `"` and `'` are used), it's
                     "key": "ModifyChapters",
                     "remove_chapters_patterns": [],
                     "remove_ranges": [],
-                     "remove_sponsor_segments":"set()",
+                     "remove_sponsor_segments": [],
                     "sponsorblock_chapter_title": "'[SponsorBlock]: ''%(category_names)l'"},
                    {"add_chapters": true,
                     "add_infojson": "none",