mpv-youtube-queue/docs/plans/2026-03-06-stream-metadata-fix.md

Stream Metadata Fallback Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Stop seek-triggered repeated metadata lookups for external streams while still queueing Jellyfin/custom-extractor items using mpv media-title fallback metadata.

Architecture: Remove queue bootstrap work from the seek-sensitive playback-restart path. Refactor metadata resolution into helpers that can use cached data, yt-dlp, or mpv-derived fallback values, then reuse those helpers during playlist sync and queue insertion.

Tech Stack: Lua, mpv scripting API, yt-dlp, minimal Lua regression test harness if needed

---

Task 1: Add regression test scaffold for metadata resolution

Files:

• Create: tests/metadata_resolution_test.lua
• Test: tests/metadata_resolution_test.lua

Step 1: Write the failing test

Create a small Lua test file that loads the metadata helper surface and asserts:

local result = subject.build_fallback_video_info({
  video_url = "https://example.invalid/stream",
  media_title = "Jellyfin Episode 1",
})

assert(result.video_name == "Jellyfin Episode 1")

Add a second test that simulates a failed extractor lookup followed by a second resolution for the same URL and asserts the extractor path is not called twice.

Step 2: Run test to verify it fails

Run: lua tests/metadata_resolution_test.lua Expected: FAIL because helper surface does not exist yet.

Step 3: Write minimal implementation

Extract or add pure helper functions in mpv-youtube-queue.lua for:

build_fallback_video_info(url, props)
resolve_video_info(url, context)

Keep the interface small enough that the test can stub extractor results and mpv properties.

Step 4: Run test to verify it passes

Run: lua tests/metadata_resolution_test.lua Expected: PASS

Step 5: Commit

git add tests/metadata_resolution_test.lua mpv-youtube-queue.lua
git commit -m "test: add stream metadata fallback regression coverage"

Task 2: Remove seek-triggered queue bootstrap

Files:

• Modify: mpv-youtube-queue.lua
• Test: tests/metadata_resolution_test.lua

Step 1: Write the failing test

Add a regression that models the previous bad behavior:

subject.on_playback_restart()
assert(sync_calls == 0)

or equivalent coverage around the listener registration/dispatch split if direct listener export is simpler.

Step 2: Run test to verify it fails

Run: lua tests/metadata_resolution_test.lua Expected: FAIL because playback-restart still triggers sync/bootstrap behavior.

Step 3: Write minimal implementation

Change listener behavior so playback-restart no longer calls sync_with_playlist() for queue bootstrap. Keep startup and file-loaded flows responsible for real import work.

Step 4: Run test to verify it passes

Run: lua tests/metadata_resolution_test.lua Expected: PASS

Step 5: Commit

git add tests/metadata_resolution_test.lua mpv-youtube-queue.lua
git commit -m "fix: avoid seek-triggered queue metadata refresh"

Task 3: Use fallback metadata during playlist sync

Files:

• Modify: mpv-youtube-queue.lua
• Test: tests/metadata_resolution_test.lua

Step 1: Write the failing test

Add a test that simulates sync_with_playlist() for a URL whose extractor metadata fails and asserts the resulting queue entry is still created with:

assert(video.video_name == "Jellyfin Episode 1")
assert(video.video_url == test_url)

Step 2: Run test to verify it fails

Run: lua tests/metadata_resolution_test.lua Expected: FAIL because sync currently drops entries when yt-dlp fails.

Step 3: Write minimal implementation

Refactor playlist import to call the new metadata resolution helper. Cache fallback metadata the same way extractor metadata is cached, and relax the fatal-field check so fallback entries can omit channel URL/uploader.

Step 4: Run test to verify it passes

Run: lua tests/metadata_resolution_test.lua Expected: PASS

Step 5: Commit

git add tests/metadata_resolution_test.lua mpv-youtube-queue.lua
git commit -m "fix: fallback to mpv metadata for external streams"

Task 4: Verify end-to-end behavior and docs

Files:

• Modify: README.md
• Modify: docs/plans/2026-03-06-stream-metadata-design.md
• Modify: docs/plans/2026-03-06-stream-metadata-fix.md

Step 1: Write the failing test

Document the expected behavior change before code handoff:

External streams should stay queued and should not re-fetch metadata on seek.

Step 2: Run test to verify it fails

Run: lua tests/metadata_resolution_test.lua Expected: Existing coverage should fail if the final behavior regresses.

Step 3: Write minimal implementation

Update README.md with a short note that unsupported extractor sources fall back to mpv metadata such as media-title.

Step 4: Run test to verify it passes

Run: lua tests/metadata_resolution_test.lua Expected: PASS

If practical, also run a syntax check:

lua -e 'assert(loadfile("mpv-youtube-queue.lua"))'

Step 5: Commit

git add README.md docs/plans/2026-03-06-stream-metadata-design.md docs/plans/2026-03-06-stream-metadata-fix.md tests/metadata_resolution_test.lua mpv-youtube-queue.lua
git commit -m "docs: document stream metadata fallback behavior"