ytstream/FINDINGS.md

ytstream — results on susan

Date: 2026-08-12. Answers every open question in the ytstream handover: §3, §6, and §7 steps 1–4. Both Jellyfin gates pass (§6 below). §7 step 5 (integrating with youtube-automate) is not done and /opt/youtube-automate is unmodified.

Environment note that matters: the PoC calls bare yt-dlp. On susan, PATH resolves that to /usr/local/bin/yt-dlp, which is 2023.11.16 and has no POT plugin. The working install is the automation's venv:

export PATH=/var/lib/youtube-automate/venv/bin:$PATH   # yt-dlp 2026.07.04
                                                       # + bgutil-ytdlp-pot-provider 1.3.1

That venv's plugin matches the running bgutil-provider container (1.3.1) and retrieves gvs PO tokens correctly. Before this was noticed the container had been up 15 hours with nothing able to talk to it — no yt-dlp plugin directory existed.

---

1. Verified against real videos

Four videos, 2 to 46 minutes. Two are from the live subs.db, so they are representative of what the automation actually handles.

video	length	TTFB (--growing)	ready (default mode)	duration served	truth
D6ocsyQLKy8	2 min	7.1s	~7s	120.62s	121s
dQw4w9WgXcQ	3.5 min	7.1s	~9s	213.13s	213s
J9O3sxoMs5U	21 min	6.9s	20s measured	1259.47s	1259s
NH2MhBFQm9w	46 min	6.5s	~50s	2789.45s	2789s

Full ffmpeg -f null - decode exits 0 in every case, with both system ffmpeg 5.1.7 and Jellyfin's bundled 7.1.3. Codecs are always h264 1280x720 + aac. "ready" figures other than the 21-minute one are derived from the measured ~8 MB/s pull rate, not separately timed.

--load-info-json reuses the extraction. This was the load-bearing unknown. Verbose output shows zero re-extraction markers and no second POT fetch — it goes straight to [info] Downloading 1 format(s): 136. The one-extraction design holds.

Concurrency is not a problem. 5/5 clean trials of the exact PoC pattern (one fresh extraction, two concurrent fetches). §3's worry about the POT provider under concurrent access looks unfounded.

Throughput ~8 MB/s, roughly 60× realtime. 368 MB for 46 minutes of 720p avc1 ≈ 480 MB/hour, about half the handover's 1 GB/hour estimate.

---

2. Two bugs found in the format picker — both would have shipped

Both came from the same root cause: YouTube advertises variants with identical abr, so max() tie-broke on list order.

video	picked	consequence
NH2MhBFQm9w	140-drc	HTTP 403 — DRC variants are advertised but not served
J9O3sxoMs5U	140-0	German audio on an English podcast (9-language upload)

The second is the dangerous one: silent, and it would have played.

Fixed by ranking language_preference first (original track = 10, dubs = -1), then non-DRC, then codec, then bitrate. Language correctness deliberately outranks the DRC check: a 403 is a loud failure, wrong-language audio is a silent one. pick_formats now also logs the chosen language and warns if a non-original track is selected on a multi-language upload.

Verified: 140-drc and 140-0 reproducibly 403 while 140, 140-7, 139, 251 and 136 all download fine from the same info.json.

Later correction — both bugs had a common upstream cause. The DRC and dubbed variants existed only because mweb was in player_client. With player_client=default alone, extraction returns four audio formats (139, 249, 140, 251), no DRC variants and no language variants at all — even on the nine-language video. So "DRC formats 403" was really "mweb formats 403", and the German-audio bug could only ever have happened via mweb. mweb is now dropped (§9). The language_preference and DRC rules stay in the picker as cheap insurance if a yt-dlp update changes what default returns.

---

3. Two defects not mentioned in the handover — both now fixed

Duration collapses while the file grows

Jellyfin's own ffprobe 7.1.3 on the 46-minute video:

during growth : format.duration = 5.92        <- wrong
after complete: format.duration = 2789.45     <- correct

§5 says scrubbing won't work while growing. It is worse than that: the duration itself is wrong, which would break Jellyfin's runtime display, seek bar, resume point and watched state.

This cannot be fixed at the container level. Both attempts failed:

• Patching mvhd.duration in place — ignored.
• Inserting an mehd box with the correct fragment_duration — the box is written correctly (mehd v0 fragment_duration=60000, file still decodes clean), and ffmpeg still ignores it and recomputes from the fragments present.

Also confirmed: ffmpeg writes mvhd.duration=0 and no mehd regardless of whether it knows the input duration — a mux from regular files and one from FIFOs produce byte-identical headers. mp4boxes.py and mehd_patch.py in this directory reproduce both results.

Fix: waiting for the mux is now the default. Correct duration, Accept-Ranges and working seeks on the very first request. Costs TTFB — 20s for a 21-minute video instead of 6.9s. --growing keeps the old low-latency behaviour and now prints a warning. Given yt-dlp runs at ~60× realtime the wait is bounded and predictable, and it is the same order of magnitude as the 30-second non-seekable window §5 already accepted.

The Jellyfin gate has since settled this: Jellyfin takes its runtime only from its own probe of the stream, never from the NFO (§6). So --growing would hand it ~6 seconds and there is no way to claw the TTFB back. Wait-for-complete is mandatory, not a preference.

Range end was ignored

bytes=1000000-1000999 returned 367 MB instead of 1000 bytes — the server parsed only the start offset and always streamed to EOF. This directly undermines §6's mitigation #2, which depends on serving small bounded probe ranges.

Now parses both ends, honours bytes=N-M, bytes=N- and the suffix form bytes=-N, clamps an end past EOF, and returns 416 with Content-Range: */total for an unsatisfiable start. test_range.py covers all of it — 25 assertions, no network required.

---

4. One correction to §6's premise

The <fileinfo><streamdetails> blocks in the existing episode NFOs were written by Jellyfin, not by the automation — <lockdata>, <dateadded>, micodec and absolute-path <art> are Jellyfin's own NFO output, produced after it probed the real .mp4 files.

So there was no evidence that pre-seeding streamdetails suppresses probing — mitigation #1 was untested, not partly proven. It has since been tested with a control group and it does nothing at all (§6).

---

5. Intermittent 403s — found, and now retried

Two 403s were observed across roughly ten real runs, and they moved between formats — once on video 136, once on audio 140, on the same video that had succeeded minutes earlier.

The first guess was transient rate limiting, because the failures clustered after ~1.5 GB had been pulled from one video. That guess is wrong. A retry two seconds later with a fresh extraction succeeded every single time, and no rate limit clears in two seconds. See §9 for what was actually measured.

What matters is the consequence: a single 403 on either stream killed the whole playback with no recovery. It then struck again during the Jellyfin test itself, so it is now fixed in ytstream.py: up to --max-retries attempts (default 2), each with a fresh extraction, retried only while nothing has been served yet. That recovered every occurrence seen — including the one during the gate, where attempt 1 failed and attempt 2 succeeded.

Retry is a mitigation, not a root-cause fix. ytstream_poc.py still has no retry; it is kept as the record of what was originally verified.

---

6. Jellyfin: both gates PASS

§7 step 3 (playback) and §6 (scan probing) are now answered against the live Jellyfin 10.11.4 on susan, using the two channels already subscribed in subs.db — 7 episodes, 2 shows, real metadata.

Library YouTube (stream) → /disks/Plex/_ytstream, built by make_strm_tree.py. SaveLocalMetadata=False on purpose: the real YouTube library has it True, which is why Jellyfin rewrote those NFOs, and leaving it on here would have overwritten the test NFOs and destroyed the control group.

§6 scan-time probing — the open risk does not materialise on a normal scan

operation	probes	pipelines started
first scan of a new library	0	0
repeat scan, replaceAllMetadata=false	0	0
refresh with replaceAllMetadata=true	yes, immediately	would be all of them

A normal scan ingests all 7 .strm episodes — correct show, season, episode numbers, aired dates — without a single request to the proxy. No scan storm. Episode RunTimeTicks stays null until something plays the item.

The dangerous path is a full metadata replace, which a user can trigger from the UI. Jellyfin probes the .strm target immediately. Two corrections to §6's assumptions while doing so:

• Probes are open-ended Range: bytes=0-, not the "small ranges from offset 0" §6 assumed. You cannot identify a probe from its Range header, so mitigation #2 cannot key off request shape. It can still work by serving the first few MB from a permanent cache — the probe takes what it needs and hangs up — but the discriminator has to be something else.
• Refusing a probe causes a retry storm. Returning 503 produced 9 retries in ~2 seconds from Lavf/61.7.100, after which the refresh aborted and left six of seven episodes with their episode numbers wiped. Whatever the mitigation is, it must answer, not refuse.

--max-pipelines (default 2) is the backstop: a full replace throttles to two concurrent fetches instead of seven.

§6 mitigation #1 — pre-seeded streamdetails do nothing

The alternate control group settles it. Episodes carrying full <fileinfo><streamdetails> with <durationinseconds> behaved identically to those without: RunTimeTicks null after a scan in both groups. Jellyfin took ProviderIds and PremiereDate from the same NFOs, so they were definitely being read — it simply does not use NFO stream details or runtime for a .strm item. Mitigation #1 is a dead end, and it is also unnecessary given a normal scan does not probe at all.

This also settles the --growing question from §3: Jellyfin has no duration until it probes the stream itself, so a growing file would hand it ~6 seconds. Stay in the default wait-for-complete mode.

§7 step 3 playback — passes, and direct-plays

Driven through Jellyfin's own API (PlaybackInfo, then /Videos/{id}/stream):

	warm cache	cold, 46-minute episode
PlaybackInfo latency	0s	55s — Jellyfin waited, no timeout
Container	mp4	mp4
RunTimeTicks	120.62s (truth 120.62)	2789.45s (truth 2789)
SupportsDirectPlay	True	True
streams	h264 1280x720 + aac	h264 1280x720 + aac

Fetching the episode through Jellyfin's streaming endpoint returned 10,654,544 bytes byte-identical to what the proxy produced, decoding cleanly. So Jellyfin direct-plays it with no transcode — which was the whole point of preferring avc1+mp4a.

Two things worth knowing:

• A cold 46-minute episode makes the user wait ~55s at the play button. That is the price of correct duration and seeking. It is bounded and predictable.
• One ffprobe of a 368 MB file generated 481 range requests to the proxy. All local and cheap, but it makes the access log noisy and is worth a look if throughput ever matters.

Artwork works, and costs nothing extra

Episode thumbnails need no API call: the URL is derivable from the video id, which is already in the filename. add_thumbnails.py fetches i.ytimg.com/vi/<id>/maxresdefault.jpg (~200 KB, 1280x720) with hqdefault.jpg (~22 KB) as a fallback, writing <basename>-thumb.jpg. Channel avatar and banner become poster.jpg / fanart.jpg and do need one yt-dlp call per channel.

Verified in Jellyfin: all 7 episodes carry a 16:9 Primary image, both series have a poster and a backdrop, and an image refresh triggers 0 probes. Artwork is entirely independent of the streaming path.

Two things learned while doing it:

• Jellyfin re-reads an NFO when its mtime changes. Episode names were filename-derived until the NFOs were rewritten, after which they picked up the real titles from <title> — full parity with the .mp4 library. So correcting metadata does not need a full replace (which would probe); just rewrite the NFO and run a Default refresh.
• A title collision bug shipped briefly: the tree generator joins video and channel, both of which have a title column, so row["title"] was the video title and both shows got renamed after whichever episode sorted first. Fixed by passing show fields explicitly. Worth remembering for §7 step 5, where the same join exists.

Catalogue size — the current library is small only because of retention

The 7 episodes are not a limit of the design, they are what subs.db holds: backfill_days = 7 and retention_days = 9, both driven by disk. A streaming library has no such constraint, so it should carry the whole back catalogue.

Actual sizes, from one --flat-playlist call per channel:

channel	videos in catalogue	in subs.db
Pitch Side	1249	15
The Pyramid Podcast	3	3

At 1249 episodes the cost is trivial for .strm + .nfo (a few MB) and ~250 MB of thumbnails at maxres. But two things get harder:

1. upload_date is not in a flat listing. Season and episode numbers are year and MMDD*10 + ordinal, so dates are required. --extractor-args youtubetab:approximate_date supplies timestamps in the same single request, but they are wrong by up to 2 days (measured against subs.db: J9O3sxoMs5U reported 08-12, actually 08-10). That yields wrong episode numbers and, worse, unstable ones — a regeneration would renumber episodes and Jellyfin would lose watched state. If approximate dates are used they must be persisted on first sight and never recomputed, exactly as specs.md already mandates for dir_name. Accurate dates cost one metadata extraction per video: ~1249 requests per channel, one-time.
2. The full-metadata-replace footgun scales with the catalogue. At 7 episodes it is an annoyance; at 1249 it would try to fetch every video in the channel. --max-pipelines 2 turns a stampede into a slow grind but does not stop it. A cold-start rate limit should land before any full catalogue does.

Running it for real

The proxy must outlive a shell. ytstream.service is written but not installed — that needs sudo:

sudo cp /home/susan/ytstream/ytstream.service /etc/systemd/system/
sudo systemctl daemon-reload && sudo systemctl enable --now ytstream

The unit pins PATH to the automation venv, which is load-bearing: bare yt-dlp would otherwise resolve to the 2023.11.16 binary in /usr/local/bin.

To remove everything: delete the YouTube (stream) library in the Jellyfin UI, then rm -rf /disks/Plex/_ytstream.

---

7. Files

file	purpose
ytstream.py	the proxy. Multi-video: /watch/<video_id>, /healthz. Retry, pipeline cap, LRU cache, --no-fetch
ytstream.service	systemd unit, not installed (needs sudo)
make_strm_tree.py	builds the .strm/.nfo library from subs.db
add_thumbnails.py	episode thumbnails + channel poster/fanart, idempotent
ytstream_poc.py	the original single-video PoC, kept as the record of what was verified
test_range.py	25 range-server assertions, no network
test_limits.py	18 assertions for the rate limiter, pipeline cap and --no-fetch
run_test.sh	one end-to-end acceptance run; prints TTFB, codecs, duration
trial_403.sh	measures the intermittent-403 rate for the PoC's access pattern
mp4boxes.py	dumps fMP4 boxes and the duration fields
mehd_patch.py	the mehd insertion — kept because the negative result matters

8. Where this stands

The handover's §8 advice was to build the batch downloader first. That is already done — /opt/youtube-automate is live — so this proxy is the second-phase experiment it was meant to be.

Every unknown in §3 and §7 resolves in the design's favour and both Jellyfin gates pass. The architecture holds: ffmpeg never touches googlevideo, the mux is a pure copy, and Jellyfin direct-plays the result with the correct duration.

Three things are known-imperfect rather than unknown:

1. Cold start costs ~55s on a 46-minute episode (~21s for 22 minutes). Inherent to wait-for-complete, and wait-for-complete is mandatory because Jellyfin takes duration only from its own probe.
2. A full metadata replace probes every episode. Now bounded by --max-starts as well as --max-pipelines (§9), but still don't run one over a large library.
3. The intermittent 403 is still unexplained. Several plausible causes are ruled out (§9) and retry recovers it every time, but that is a mitigation.

Not done, and the honest next steps:

• ytstream.service is written but not installed — that needs sudo. Until then the library only plays while the proxy runs in a shell.
• Nothing writes .strm automatically. make_strm_tree.py is a one-shot from subs.db; §7 step 5 is untouched and /opt/youtube-automate is unmodified.
• The library covers 7 episodes because that is what subs.db holds. A real deployment should carry the full catalogue — see the catalogue section in §6 for the two things that get harder at 1249 episodes.
• Two libraries coexist by choice: YouTube (.mp4) and YouTube (stream) (.strm), same 7 episodes, for comparison.
• tmpfs LRU eviction is implemented but has never fired; the cap was never reached in testing.

---

9. Hardening pass (2026-08-12, after the gates passed)

The 403 investigation — the obvious fix would have made it far worse

player_client was default,mweb. Inspecting the c= and pot= parameters on the chosen format URLs showed something that looked like an open-and-shut cause:

player_client	video/audio served from	PO token in URL
default,mweb	ANDROID_VR	no
mweb	MWEB	yes

The obvious conclusion — "we are using token-less URLs, pin the client that gets a token" — is wrong, and testing it was worth the ten minutes:

player_client=mweb   ->  0 ok / 6 fail      (403 on both streams, every trial)
player_client=default -> works

mweb fails both as a single process and via --load-info-json, so it is not a round-trip problem — mweb URLs are simply rejected right now, PO token and all. ANDROID_VR without a token works; mweb with one does not. Had this been "fixed" by pinning mweb, every playback would have broken.

Full client sweep on the same video:

client	result
default (→ android_vr)	works
android_vr	works
mweb	403, every time
web, ios, web_safari, tv	no usable formats — SABR forced

So there is no client-level fix available: default is the only thing that works, and it is already what was in use. What changed:

• mweb dropped from player_client. It contributed nothing usable, and it was the sole source of the DRC and dubbed-language formats behind both original picker bugs (§2). Removing it eliminates those hazards before the picker sees them, and cut extraction time from ~5s to 2.3s — one fewer client API call, which comes straight off cold-start latency.
• Left as default rather than pinned to android_vr, so a yt-dlp update can follow YouTube if android_vr stops working.

The 403 remains unexplained and still occurs — one retry fired during the post-hardening Jellyfin test (retried: 1, failed: 0). Retry with re-extraction recovers it every time observed, so it stays the mitigation. What is now ruled out: rate limiting (a 2s retry succeeds), --load-info-json (fails identically without it), concurrency (5/5 clean), and PO token absence (token-less URLs are the ones that work).

Cold-start rate limiter

--max-pipelines caps concurrency, which only slows a runaway metadata refresh down — over 1249 episodes it would still fetch the whole catalogue, just two at a time. --max-starts (default 20 per --starts-window, default 3600s) bounds the total instead.

The discriminator is that it counts cold starts only. Cache hits are never limited, so re-watching and resuming keep working with the budget exhausted. A person starts a handful of new videos an hour; a refresh storm hits 20 in seconds.

When the budget is spent the proxy refuses with 503 and logs loudly. From the §6 measurements, a refused probe produces a short libavformat retry burst and then aborts the refresh — which is the point: an aborted refresh costs some re-derivable metadata, a runaway one costs the entire catalogue in YouTube traffic.

test_limits.py covers the limiter, the concurrency cap and --no-fetch with the pipeline runner stubbed out — 18 assertions, no network.

Known gap

Sessions live in memory, so a proxy restart orphans whatever is already on tmpfs and the next request re-fetches. Harmless on this host (tmpfs is cleared on reboot anyway) but worth knowing if a service restart ever looks like a stall.