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.

Issues that we've seen in our testing so far:

The error message you can see when playing YouTube content in 240-MP can represent different failures. Below are some example failures that were encountered in issue #203, PR #239, and discussion #247 but the list is not exhaustive (as there are many things that can occur on the connection end between YouTube and YT-DLP). The easiest one is a missing or non-executable yt-dlp installation so for that simply use the install/update instructions above.

1. 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.
2. 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 the prerequisite, but it does not prove that every bot-check response has the same cause. For example: in the route-specific case below, Deno was detected and the YouTube response still differed by network route.
3. 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.
4. 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.