Skip to content

yt-dlp Ops Check

Run a local, monthly integration check for yt-dlp to catch upstream breakage without GitHub Actions noise.

The repo now also includes a freshness-gated status wrapper for active local development:

python scripts/update_health_check.py
make update-health-check
make health-check

make update-health-check is the passive status gate used by make ci-check, make build-all, and make update:

  • warns when the last yt-dlp ops run is older than 10 days
  • fails when the last yt-dlp ops run is older than 30 days
  • fails when the most recent live run has an explicit nonzero exit code, regardless of its age
  • applies the normal age-based freshness rules to legacy records without an exit code
  • does not run the live suite automatically

make health-check explicitly runs the live yt-dlp ops suite now and updates the status file. Thresholds can be configured with TNH_HEALTH_WARN_AFTER_DAYS, TNH_HEALTH_FAIL_AFTER_DAYS, and TNH_YT_DLP_RECOMMENDED_INTERVAL_DAYS. The live check retrieves metadata and a 15-second audio sample from each configured URL.

Follow-up Improvements

The 2026-10-17 local validation used yt-dlp 2026.8.19, Node 22.13.0, configured ejs:github remote components, and the existing ffmpeg path. All five configured URLs passed metadata retrieval and 15-second audio download probes. The older 2026.6.9 release had failed all five audio probes. One initial probe with the updated release still returned HTTP 403; an unchanged-download retry and the subsequent full run succeeded. This is a verified working runtime snapshot, not a guarantee against future CDN failures. No player-client, cookie, or format-selection workaround was added.

  • Replace the plain URL list with typed fixture records describing purpose, expected capabilities, language, and last verification date.
  • Separate metadata, transcript, and audio outcomes so one failure identifies the affected capability.
  • Evaluate an automated PO-token provider if ranged audio downloads still receive playback HTTP 403 responses.
  • Include the yt-dlp version and runtime profile in each saved report.

Script

Use:

python scripts/yt_dlp_ops_check.py

This runs a live ops check and appends logs to logs/yt_dlp_ops_check.log.

The freshness-gated wrapper records status in:

logs/update_health_check_status.json

Optional overrides:

  • TNH_YT_URLS_PATH=/path/to/validation_urls.txt to use a custom URL list.
  • TNH_YT_URL_LIMIT=2 to limit the number of URLs for a quick run.

Cron example

# Weekly on Mondays at 9:00 AM
0 9 * * 1 /usr/bin/env bash -lc "cd /path/to/tnh-scholar && python scripts/yt_dlp_ops_check.py"

URL list

Edit the live test URLs at:

tests/fixtures/yt_dlp/validation_urls.txt

Runtime setup

Use the helper script or Makefile target:

python scripts/setup_ytdlp_runtime.py --yes
make ytdlp-runtime