[RFC] Mux Source & URL DX

[R-Delfino95]

Refs #1432
Refs #1431
Refs #977

Summary

Light RFC to align on how <mux-video> should take a source — and sign, refresh, and derive URLs from it — without the surface changing when the playback engine does. Motivated by signed-token refresh (#1432), under the Mux Media Elements epic (#977). The recommendation is a proposal to react to, not a settled decision.

Problem

<mux-video> in v10 has no token surface today: it accepts src plus standard HTML5 attributes, and the Mux Data mixin only reads the playback-id out of src for analytics. So signed playback (JWTs with TTLs) hard-fails mid-session when a token lapses — there's nothing to refresh.

Adding that surface forces a DX question with two goals pulling in opposite directions:

• A — Convenience. mux-video / media-chrome parity: playback-id + signed tokens, and we build the stream.mux.com and thumbnail/poster URLs.
• B — Lean on URLs. Fewer Mux-specific attributes; the user passes the full URL in src.

…under one hard constraint: the surface must stay engine-agnostic (native HLS → hls.js → SPF engine must not change component config).

Recommendation

Option 3 — pluggable source-resolver with optional convenience inputs. Make the middle layer (config → played URL) the contract: raw src is the identity base case, playback-id + tokens resolve through the same seam, and that seam is where engine-agnostic re-resolution on token expiry lives. This makes A and B coexist instead of either/or, and gives #1432's refresh a stable home. The recommended default shape is the leanest one — a src plus an optional token-refresher (no playback-id), with playback-id + tokens as heavier opt-in convenience inputs. Options 1 and 2 are just the two ends of Option 3, so it's also the least-committal choice.

What I'm looking for

Reactions on the direction, and input on the open questions — chiefly the refresh surface (per-token refresher fn vs onTokenExpiring event; reactive vs proactive), src / playback-id precedence, where the resolver lives, and whether to ship a minimal playback-token pass-through first.

Scope notes

• This is a draft RFC for direction-setting, not an implementation design — if accepted, the resolver seam and refresh mechanism get a full design doc.
• Engine context: <mux-video> runs on hls.js today and is planned to move onto the SPF engine, where Tier-2 refreshPlaybackToken (network-resilience.md) will live. The engine-agnostic layering is what keeps that migration invisible to the user.
• Related secure-playback work: Feature: mux-video Playback Restriction Error Handling #1431 (expired-token error path), Feature: DRM Support #1411–Feature: FairPlay DRM Support #1414 (DRM).

---

Note

Low Risk
Documentation-only RFC with no production code, config, or behavior changes.

Overview
Adds draft RFC rfc/mux-source-dx.md to align on how <mux-video> should accept sources, sign URLs, and refresh signed JWTs without changing the public API when the playback engine switches (hls.js → SPF).

The doc frames today’s gap (no token surface; src goes straight to the engine; analytics only derives playback-id from src) and the tension between convenience (playback-id + tokens) vs lean src, under an engine-agnostic constraint. It recommends Option 3: a pluggable source-resolver middle layer with raw src as the base case and optional Mux convenience inputs, plus engine-side refresh (e.g. SPF Tier-2 refreshPlaybackToken). Default DX is src + optional token refresher; playback-id / tokens stay opt-in.

It also outlines follow-ons if accepted (minimal playback-token pass-through, full resolver design, #1432 refresh), reactive vs proactive refresh, thumbnails/poster derivation, and open questions (precedence, refresh API shape, resolver placement). No runtime or API code changes in this PR—documentation only.

^{Reviewed by Cursor Bugbot for commit b526cdd. Bugbot is set up for automated code reviews on this repo. Configure here.}

[netlify]

👷 Deploy request for vjs10-site pending review.

Visit the deploys page to approve it

Name	Link
🔨 Latest commit	b526cdd

[vercel]

@R-Delfino95 is attempting to deploy a commit to the Mux Team on Vercel.

A member of the Team first needs to authorize it.