How much yt-dlp troubleshooting should live in 240-MP’s documentation?

[snkinard]

@anthonycaccese, before proposing another documentation change, I wanted to ask how you would prefer recurring yt-dlp breakage to be handled.

On August 18, YouTube playback stopped working on my Raspberry Pi 3B+ while 240-MP was using yt-dlp 2026.07.04, which was still the current stable release. This happened after the Deno setup and earlier route-specific investigation documented in #239. In this instance, changing only yt-dlp to the official nightly build 2026.08.18.122307 restored playback immediately, without restarting 240-MP.

I’m unblocked now. yt-dlp’s own update and release-channel guidance explains that stable releases can become stale when sites change, recommends nightly for regular users, and directs users experiencing a problem on stable to try nightly.

My concern is where that guidance belongs. Issue #203 and the documentation merged in #239 already cover other causes of the same generic playback error. If each new YouTube/yt-dlp failure produces another workaround in BUILDING.md, the documentation could become an ever-growing list that quickly goes stale.

What would you prefer?

• Add one short note linking to yt-dlp’s official release-channel guidance, without documenting additional incident-specific workarounds.
• Keep 240-MP’s documentation focused on installation and leave ongoing troubleshooting entirely to the yt-dlp project.
• Some other approach.

I’m not suggesting that 240-MP bundle or automatically update yt-dlp, and I haven’t prepared another PR. I wanted your input before proposing anything.

[anthonycaccese]

@snkinard great question and timing (i've been thinking about this with the new scripts module from #227)

With the scripts module we have the ability now to write and run scripts directly from within 240-MP's UI so we can use it for things like installing/updating YT-DLP

Because of that i've been thinking to revisit the YT-DLP documentation to point to a Wiki page so that we can have a simple entry in the source docs along the lines of "YT-DLP is required to use YouTube functionality in the YouTube and NFC Reader modules, check out details here to install the latest version of it" (and have that point to a wiki page)

Then on that wiki page document the how to use the Scripts module as an option to update YT-DLP and then any other troubleshooting details such as the deno approach.

Related... I worked up a script to use in the scripts module that will work on each of 240-MP's current device targets and have a gist of it here to try out: https://gist.github.com/anthonycaccese/214020bfbf0abee596d256ecb7efc54f

It leverages the new /bin override method I added as part of the linux appimage work (basically a local APPROOT /bin location that 240-MP will look at first before checking for it on path)

Thinking to update the following locations:

• https://github.com/anthonycaccese/240-MP/blob/main/INSTALL.md#youtube-yt-dlp
• https://github.com/anthonycaccese/240-MP/blob/main/BUILDING.md
• https://github.com/anthonycaccese/240-MP/wiki/Module%3A-NFC-Reader#youtube-url-support
• https://github.com/anthonycaccese/240-MP/wiki/Module%3A-YouTube#to-enable

And point details on each to this new wiki page:
https://github.com/anthonycaccese/240-MP/wiki/YT%E2%80%90DLP

Long way of answering your question =)

What would you prefer?

Thinking... Add one short note linking to yt-dlp’s official release-channel guidance, without documenting additional incident-specific workarounds on the new Wiki page above and then updating existing documentation to point to that wiki page.

[snkinard]

see this is what I mean. what if it's some other different issue every single day and only reproducible on 40% of the 240MP user base and blah blah blah blah. Could be a full time job just finding and fixing every little hiccup.

I still maintain your above proposal is the best approach at this point

[snkinard]

I JUST LOVE THE YOUTUBE module so every time mine stops working I have to go and fix it lol

[anthonycaccese]

i am with you, I thought i would be using plex more but find myself in the youtube module often enough now too. I have a unlisted watch later playlist i add things to on my regular account and then just queue up things to watch through that via 240-MP

see this is what I mean. what if it's some other different issue every single day and only reproducible on 40% of the 240MP user base and blah blah blah blah. Could be a full time job just finding and fixing every little hiccup.

I agree, so thinking a shift to a "here's what we've found and what you can try" wiki approach fits well into the tinkerers mindset i'd like to continue fostering. There is no way we'll be able to account for each set up, network env etc... so the expectation i think we try to set is "here's what we've found and what you can try"

hmm, if you're interested i can whats involved in giving you wiki access. But if that's a weird hurdle would you be down to collaborate on ideas for a wiki page for this here?

[snkinard]

gimme wiki access!

[snkinard]

I'll post what I have for a proposed wiki page below

[snkinard]

YT‐DLP

yt-dlp is required for YouTube playback in the YouTube module and for YouTube URLs used by the NFC Reader module. It is not bundled with 240-MP because it needs to be updated independently as YouTube changes.

Install or update from 240-MP

The YT-DLP updater gist can be run from 240-MP's Scripts module:

1. Download both yt-dlp.sh and yt-dlp.txt from the gist.
2. Put both files in the scripts directory:
   • Raspberry Pi OS, SteamOS, or Linux: ~/.local/share/240-MP/user_scripts
   • macOS: ~/Library/Application Support/240-MP/user_scripts
3. In 240-MP, open Settings > Scripts, run Rescan Scripts, and set Enabled to On.
4. Open the Scripts module and run YT-DLP. A successful run ends with EXIT 0 and prints the installed version and path.

The updater selects a suitable nightly release for the current system and installs it in 240-MP's data-directory bin folder. Run the same script again whenever you need to update. 240-MP will use the installed copy on the next playback attempt; no restart is needed.

Other installation methods

If you prefer to manage yt-dlp outside 240-MP, follow yt-dlp's official installation instructions. 240-MP checks its data-directory bin folder before looking for yt-dlp elsewhere on the system.

Release channel

The updater uses yt-dlp's nightly channel. yt-dlp currently recommends nightly for regular users because site changes can break an older stable release. See yt-dlp's official release-channel guidance.

Investigating a PLAYBACK FAILED message

The message shown by 240-MP is intentionally general. It means mpv could not begin playing the item; it does not by itself prove that yt-dlp is missing or outdated.

Before starting another video, inspect the log from the failed attempt. Each new playback replaces this file:

# Raspberry Pi OS, SteamOS, and Linux
less /tmp/240mp-mpv.log

# macOS
less "$TMPDIR/240mp-mpv.log"

On a Raspberry Pi using the 240mp systemd service, the application log may provide additional context:

journalctl -u 240mp -b --no-pager | tail -n 200

In the mpv log, look near the end for yt-dlp warnings or errors. If the logged options contain ytdl_hook-ytdl_path=, its value is the exact yt-dlp executable 240-MP asked mpv to use. The updater installs that executable at one of these paths:

Raspberry Pi OS, SteamOS, or Linux: ~/.local/share/240-MP/bin/yt-dlp
macOS: ~/Library/Application Support/240-MP/bin/yt-dlp

Replace the example path below with the path from the log and check its version:

"/path/from/the/log/yt-dlp" --version

Then test the same URL directly with that same executable. --simulate resolves the video without downloading it:

"/path/from/the/log/yt-dlp" --verbose --simulate 'VIDEO_URL'

• If the direct check reports the same error, the failure is occurring while yt-dlp resolves the YouTube URL.
• If the direct check succeeds but playback in 240-MP still fails, the mpv and service-log lines from the same attempt can help distinguish an mpv or integration problem from a yt-dlp extraction problem.

When asking for help, include the 240-MP version, device and operating system, architecture, yt-dlp path and version, whether the failure affects one or multiple videos, and the relevant error lines. Review logs before sharing them: they can contain URLs, unlisted video IDs, local paths, or authentication values.

Issue patterns encountered so far

The same 240-MP message can represent different failures. These are cases encountered in issue #203, PR #239, and discussion #247; the list is not exhaustive. For a missing or non-executable yt-dlp installation, use the install/update instructions above.

The stable yt-dlp release has become stale

What it looks like: yt-dlp is installed and reports the latest stable version, but YouTube extraction has recently stopped working. In the August 18 report, changing only from stable 2026.07.04 to nightly 2026.08.18.122307 restored playback.

What to try: Run the Scripts-module updater, which installs the current nightly build. yt-dlp recommends nightly for regular users and asks users with a stable-release problem to try nightly before reporting it; see its release-channel guidance.

No supported JavaScript runtime is detected

What it looks like: yt-dlp --verbose reports JS runtimes: none or warns that no supported JavaScript runtime is available.

What to try: Follow yt-dlp's EJS setup guide. Deno is the recommended runtime. Make sure it is available on the PATH of the user or systemd service that runs 240-MP, then repeat the direct --verbose --simulate check.

Installing Deno satisfies that prerequisite, but it does not prove that every bot-check response has the same cause. In the route-specific case below, Deno was detected and the YouTube response still differed by network route.

The failure is intermittent or limited to particular videos or channels

What it looks like: One attempt, video, or channel fails while another succeeds, or the same item works on a later attempt without a system change. This has included Sign in to confirm you're not a bot responses that disappeared on a later retry.

What to try: Retry the same item once or try it again later. There is no guaranteed 240-MP-side fix for an intermittent stream or YouTube response.

A bot-check response is tied to the network route

What it looks like: yt-dlp is current and a supported JavaScript runtime is detected, but the same URL fails with Sign in to confirm you're not a bot over IPv4 and succeeds over IPv6.

On a system that already has working IPv6, compare the same URL and the same yt-dlp executable:

"/path/from/the/log/yt-dlp" --verbose --simulate --force-ipv4 'VIDEO_URL'
"/path/from/the/log/yt-dlp" --verbose --simulate --force-ipv6 'VIDEO_URL'

What to try: If the comparison confirms a route-specific response, an already-working IPv6 route may allow playback to proceed. IPv6 is not a 240-MP requirement, and enabling or repairing it is a device and network configuration task outside 240-MP; the commands above are only a diagnostic.

[anthonycaccese]

Thank you @snkinard, adding this now. also added you as a collaborator this morning so you should have access to make changes on the wiki now too (along with other things) your help has been amazing and I appreciate the care you've taken with your contributions.

[anthonycaccese]

added: https://github.com/anthonycaccese/240-MP/wiki/YT%E2%80%90DLP

and updated references so far on:
https://github.com/anthonycaccese/240-MP/wiki/Module%3A-NFC-Reader#youtube-url-support
https://github.com/anthonycaccese/240-MP/wiki/Module%3A-YouTube#to-enable
https://github.com/anthonycaccese/240-MP/wiki/Module%3A-YouTube#playback-errors

[snkinard]

Thank you ant! Honored to take part in this project