@videojs/spf 10.0.0-beta.30 → 10.0.0-beta.32

package/dist/default/playback/behaviors/track-switching.js

@@ -2,89 +2,76 @@ import { computed, peek } from "../../core/signals/primitives.js";
 import { defineBehavior } from "../../core/composition/create-composition.js";
 import { createMachineReactor } from "../../core/reactors/create-machine-reactor.js";
 import { isResolvedPresentation } from "../../media/types/index.js";
-import { getTracksByType } from "../../media/utils/tracks.js";
+import { getCodecFamilies, getTracksByType } from "../../media/utils/tracks.js";
 import { SVTA_NO_SUPPORTED_AUDIO_TRACK, SVTA_NO_SUPPORTED_VIDEO_TRACK } from "../../media/errors.js";
 import { matchesPartialTrack, pickTextTrackFromTracks, smallestCoveringPixelArea, tracksUnderPixelArea } from "../../media/primitives/select-tracks.js";
-import { applyConstraints, applyRules, excludeUnplayableTracks, sameCandidateSet } from "../primitives/selection-rules.js";
-import { emitError } from "./collect-errors.js";
+import { applyConstraints, applyRules, excludeUnplayableTracks, preferCodecFamilies, sameCandidateSet } from "../primitives/selection-rules.js";
+import { DEFAULT_QUALITY_CONFIG, resolutionArea } from "../../media/abr/quality-selection.js";
 import { getCdnId } from "../../media/utils/cdn.js";
 import { DEFAULT_BANDWIDTH_CONFIG, getBandwidthEstimate } from "../../network/bandwidth-estimator.js";
-import { DEFAULT_QUALITY_CONFIG, resolutionArea } from "../../media/abr/quality-selection.js";
+import { emitError } from "./collect-errors.js";
 //#region src/playback/behaviors/track-switching.ts
 /**
-* **Per-type track selection as a rule chain.** While a presentation is
-* resolved, owns that type's `selected{Video,Audio,Text}TrackId` signal: pick a
-* default, react to user intent and algorithmic ranking, and clear it on src
-* unload.
+* **Per-type track selection as a rule chain.** While a presentation is resolved, owns that type's
+* `selected{Video,Audio,Text}TrackId` signal: pick a default, react to user intent and algorithmic ranking, and clear
+* it on src unload.
 *
-* Selection runs in two stages. First a **hard-constraints pre-pass**
-* (`applyConstraints`) prunes the unplayable from the candidate set — the
-* failed-CDN constraint (`excludeFailedCdns`, failover cooldown) and the
-* capability constraint (`excludeUnplayableTracks`, codec support). Then a small
-* ordered chain of rules (`applyRules`) picks among the survivors. Each constraint/rule reads the signals it needs at apply
-* time, so the effect subscribes to exactly what was consulted. The chain runs
-* most authoritative first:
+* Selection runs in two stages. First a **hard-constraints pre-pass** (`applyConstraints`) prunes the unplayable from
+* the candidate set — the failed-CDN constraint (`excludeFailedCdns`, failover cooldown), the capability constraint
+* (`excludeUnplayableTracks`, codec support), and the codec-family sticky constraint (`stickToSelectedCodecs`, no
+* `SourceBuffer.changeType()` — see its note). Then a small ordered chain of rules (`applyRules`) picks among the
+* survivors. Each constraint/rule reads the signals it needs at apply time, so the effect subscribes to exactly what
+* was consulted. The chain runs most authoritative first:
 *
-*   1. **user intent** — a soft filter on `user*TrackSelection`: narrow to the
-*      partial-track match; an empty match falls through to the full set.
-*   2. **active CDN** — a soft filter on `cdnPriority` (`preferActiveCdn`):
-*      narrow to the highest-priority CDN that still has tracks; an empty match
-*      falls through. Shared by video and audio, so every type stays on one CDN
-*      (`deriveCdnPriority` owns the list). No-op for non-redundant sources.
-*   3. **player resolution** — a soft filter on `playerResolution`
-*      (`playerResolutionCap`, video only): narrow to the smallest rendition
-*      tier covering the player element, plus everything below it. No-op
-*      without a measurement. Ahead of the ranker but behind the CDN scope, so
-*      the cap chooses *within* a host rather than between hosts.
-*   4. **ranking** — the terminal sort: `rankByBandwidth`, shared by video and
-*      audio. Fitting tracks (within the throughput threshold) first, highest
-*      bitrate first; over-throughput tracks after, least-over first. Hysteresis
-*      via boosting the current track's sort weight by `upgradeMargin`.
+* 1. **user intent** — a soft filter on `user*TrackSelection`: narrow to the partial-track match; an empty match falls
+*    through to the full set.
+* 2. **codec-family preference** — a soft filter on `preferredCodecs` (`preferCodecFamilies`, default AVC/AAC): on a
+*    mixed-codec source, narrow which family the _initial_ pick — the one the sticky constraint then holds — lands in.
+*    Behind user intent so an explicit initial pick may land anywhere; inert once the constraint narrows to a
+*    non-preferred family.
+* 3. **active CDN** — a soft filter on `cdnPriority` (`preferActiveCdn`): narrow to the highest-priority CDN that still
+*    has tracks; an empty match falls through. Shared by video and audio, so every type stays on one CDN
+*    (`deriveCdnPriority` owns the list). No-op for non-redundant sources.
+* 4. **player resolution** — a soft filter on `playerResolution` (`playerResolutionCap`, video only): narrow to the
+*    smallest rendition tier covering the player element, plus everything below it. No-op without a measurement. Ahead
+*    of the ranker but behind the CDN scope, so the cap chooses _within_ a host rather than between hosts.
+* 5. **ranking** — the terminal sort: `rankByBandwidth`, shared by video and audio. Fitting tracks (within the throughput
+*    threshold) first, highest bitrate first; over-throughput tracks after, least-over first. Hysteresis via boosting
+*    the current track's sort weight by `upgradeMargin`.
 *
-* The composer's early-bail (one survivor → stop) is load-bearing: a user
-* selection that narrows to a single track is the pick without the ranker
-* running, so the bandwidth estimate is never read and the effect doesn't
-* re-fire on bandwidth while that choice holds.
+* The composer's early-bail (one survivor → stop) is load-bearing: a user selection that narrows to a single track is
+* the pick without the ranker running, so the bandwidth estimate is never read and the effect doesn't re-fire on
+* bandwidth while that choice holds.
 *
-* Lifecycle: `'presentation-unresolved'` ↔ `'presentation-resolved'`. The
-* resolved state owns the signal; its entry-returned cleanup clears it on exit
-* (canonical cleanup-binds-to-setup per `reactors.md`).
+* Lifecycle: `'presentation-unresolved'` ↔ `'presentation-resolved'`. The resolved state owns the signal; its
+* entry-returned cleanup clears it on exit (canonical cleanup-binds-to-setup per `reactors.md`).
 *
-* The pick is the chain's result mapped to a slot value by `resolveSelection`
-* (default: the head, `applyRules(...)[0]`). Each variant supplies its
-* **constraints + rule chain (+ optional resolveSelection)** via config;
-* `setupTrackSwitching` owns only the lifecycle and runs what it's given. Video
-* and audio run constraints `[excludeFailedCdns, excludeUnplayableTracks]` then
-* rules `[filterByUserSelection, preferActiveCdn, rankByBandwidth]` and take the
-* head; video inserts `playerResolutionCap` after the active-CDN scope, and
-* `switchVideoTrack` also accepts ABR tuning config, `switchAudioTrack` takes
-* none. `switchTextTrack` differs — selection is *optional* (captions are
-* opt-in / off-able), so it runs `[excludeFailedCdns]` + `[preferActiveCdn]` and
-* supplies a text terminal (`pickResolvedTextTrack`) that resolves standing user
-* intent (`userTextTrackSelection`, incl. `'off'`) and may yield no selection.
-* (The active-CDN *scope* is the sticky-pick half of multi-CDN; the failed-CDN
-* *constraint* is the failover half — prune the cooled-down CDN, the scope falls
-* to the next.)
+* The pick is the chain's result mapped to a slot value by `resolveSelection` (default: the head,
+* `applyRules(...)[0]`). Each variant supplies its **constraints + rule chain (+ optional resolveSelection)** via
+* config; `setupTrackSwitching` owns only the lifecycle and runs what it's given. Video and audio run constraints
+* `[excludeFailedCdns, excludeUnplayableTracks, stickToSelectedCodecs]` then rules `[filterByUserSelection,
+* preferCodecFamilies, preferActiveCdn, rankByBandwidth]` and take the head; video inserts `playerResolutionCap` after
+* the active-CDN scope, and `switchVideoTrack` also accepts ABR tuning config, `switchAudioTrack` takes none.
+* `switchTextTrack` differs — selection is _optional_ (captions are opt-in / off-able), so it runs
+* `[excludeFailedCdns]` + `[preferActiveCdn]` and supplies a text terminal (`pickResolvedTextTrack`) that resolves
+* standing user intent (`userTextTrackSelection`, incl. `'off'`) and may yield no selection. (The active-CDN _scope_ is
+* the sticky-pick half of multi-CDN; the failed-CDN _constraint_ is the failover half — prune the cooled-down CDN, the
+* scope falls to the next.)
 *
-* When the pre-pass prunes a type that *has* tracks to empty, the behavior
-* clears the selection (so a now-unplayable pick can't linger and stall) and
-* reports the type's `noSupportedTrackCode`. Which constraint emptied the set is
-* deliberately not consulted — the behavior reads no constraint's state, so the
-* chain stays composable. A type with no tracks at all is left alone; that's a
-* legitimate source shape, not a failure. The late `createSourceBuffer` check
+* When the pre-pass prunes a type that _has_ tracks to empty, the behavior clears the selection (so a now-unplayable
+* pick can't linger and stall) and reports the type's `noSupportedTrackCode`. Which constraint emptied the set is
+* deliberately not consulted — the behavior reads no constraint's state, so the chain stays composable. A type with no
+* tracks at all is left alone; that's a legitimate source shape, not a failure. The late `createSourceBuffer` check
 * stays as the structural backstop.
 *
-* Deferred: audio's preferred-language / default-track selection as standing
-* soft-filter rules (previously the empty-slot picker, dropped in the move to
-* the rule chain).
+* Deferred: audio's preferred-language / default-track selection as standing soft-filter rules (previously the
+* empty-slot picker, dropped in the move to the rule chain).
 */
 /** Default initial-bandwidth value before bandwidth measurements arrive. */
 const DEFAULT_INITIAL_BANDWIDTH = 5e6;
 /**
-* User intent — a soft filter. Narrows to tracks matching the partial-track
-* selection in `user*TrackSelection`; an empty match falls through (the
-* composer skips it) to the unfiltered set — e.g. a stale id from a previous
-* source.
+* User intent — a soft filter. Narrows to tracks matching the partial-track selection in `user*TrackSelection`; an
+* empty match falls through (the composer skips it) to the unfiltered set — e.g. a stale id from a previous source.
 */
 function filterByUserSelection(tracks, { state, config }) {
 	const key = config.userSelectionKey;
@@ -93,50 +80,42 @@ function filterByUserSelection(tracks, { state, config }) {
 	return filter ? tracks.filter((track) => matchesPartialTrack(track, filter)) : tracks;
 }
 /**
-* Player-resolution cap — a soft filter, video only. Narrows to the renditions
-* worth delivering at the player element's rendered size, so a small embed
-* doesn't pull segments nobody can perceive. The tighter sibling of
+* Player-resolution cap — a soft filter, video only. Narrows to the renditions worth delivering at the player element's
+* rendered size, so a small embed doesn't pull segments nobody can perceive. The tighter sibling of
 * `screenResolutionCap`: the element's box, not the screen behind it.
 *
-* The cap is the *smallest tier that still covers the player*, and everything at
-* or below it survives — not "everything at or below the player's area," which
-* under-serves a player falling between two tiers. Take an 800×450 player
-* against a 360p/720p/1080p ladder: only 360p is below it, so capping at the
-* player's area would hold an 800-px-wide box to a 640-px-wide picture. The
-* honest answer is the tier above, 720p, with 360p left in for the ranker.
-* `smallestCoveringPixelArea` picks that cap; `tracksUnderPixelArea` — the same
-* filter `screenResolutionCap` narrows with — applies it.
+* The cap is the _smallest tier that still covers the player_, and everything at or below it survives — not "everything
+* at or below the player's area," which under-serves a player falling between two tiers. Take an 800×450 player against
+* a 360p/720p/1080p ladder: only 360p is below it, so capping at the player's area would hold an 800-px-wide box to a
+* 640-px-wide picture. The honest answer is the tier above, 720p, with 360p left in for the ranker.
+* `smallestCoveringPixelArea` picks that cap; `tracksUnderPixelArea` — the same filter `screenResolutionCap` narrows
+* with — applies it.
 *
-* Renditions declaring no width or height compare as area `0` and are never capped
-* out — they can't be judged against the player, and dropping them could strand
-* a source whose renditions all omit it.
+* Renditions declaring no width or height compare as area `0` and are never capped out — they can't be judged against
+* the player, and dropping them could strand a source whose renditions all omit it.
 *
-* Runs *after* `preferActiveCdn`, so it narrows within the host already chosen.
-* Ahead of it, a cap that pruned every rendition of the preferred CDN would leave
-* the scope to fall to the next one with survivors — a size preference silently
-* moving playback to another host. Redundant streams normally mirror the same
-* ladder, which makes that a nonstandard-but-legal mismatch across CDNs rather
-* than an everyday case; the ordering costs nothing either way.
+* Runs _after_ `preferActiveCdn`, so it narrows within the host already chosen. Ahead of it, a cap that pruned every
+* rendition of the preferred CDN would leave the scope to fall to the next one with survivors — a size preference
+* silently moving playback to another host. Redundant streams normally mirror the same ladder, which makes that a
+* nonstandard-but-legal mismatch across CDNs rather than an everyday case; the ordering costs nothing either way.
 *
-* Reading `state.playerResolution` through its signal is what subscribes the
-* chain to resizes; `undefined` — no signal composed, or nothing to measure —
-* means "don't cap" rather than a cap of zero, so the chain proceeds unnarrowed.
+* Reading `state.playerResolution` through its signal is what subscribes the chain to resizes; `undefined` — no signal
+* composed, or nothing to measure — means "don't cap" rather than a cap of zero, so the chain proceeds unnarrowed.
 */
 function playerResolutionCap(tracks, { state }) {
 	const playerResolution = state.playerResolution?.get();
 	if (!playerResolution) return tracks;
-	return tracksUnderPixelArea(tracks, smallestCoveringPixelArea(tracks, playerResolution.width * playerResolution.height));
+	const cap = smallestCoveringPixelArea(tracks, playerResolution.width * playerResolution.height);
+	return tracksUnderPixelArea(tracks, cap);
 }
 /**
-* Failed-CDN constraint — a *hard* filter (constraints pre-pass), shared by
-* video and audio. Removes tracks served from a CDN currently in failover
-* cooldown (`failedCdns`, written by the failover monitor). Removed tracks are never
-* attempted; the scope then narrows to the next surviving CDN in `cdnPriority`,
-* and snaps back to the primary once it leaves cooldown.
+* Failed-CDN constraint — a _hard_ filter (constraints pre-pass), shared by video and audio. Removes tracks served from
+* a CDN currently in failover cooldown (`failedCdns`, written by the failover monitor). Removed tracks are never
+* attempted; the scope then narrows to the next surviving CDN in `cdnPriority`, and snaps back to the primary once it
+* leaves cooldown.
 *
-* Passes everything through when there's no `failedCdns` signal/value. When it
-* prunes *every* track (all CDNs cooled down), the empty result is preserved
-* (per `applyConstraints`) — "nothing playable," which clears the selection (no
+* Passes everything through when there's no `failedCdns` signal/value. When it prunes _every_ track (all CDNs cooled
+* down), the empty result is preserved (per `applyConstraints`) — "nothing playable," which clears the selection (no
 * pick); a later CDN recovery refills the candidate set and re-picks.
 */
 function excludeFailedCdns(tracks, { state, config }) {
@@ -147,25 +126,21 @@ function excludeFailedCdns(tracks, { state, config }) {
 	return tracks.filter((track) => !failedSet.has(getCdnId$1(track.url)));
 }
 /**
-* Active-CDN scope — a soft filter, shared by video and audio. Narrows to the
-* highest-priority CDN in `cdnPriority` (owned by `deriveCdnPriority`) that
-* still has tracks, so every track type stays on one CDN. A redundant-streams
-* source lists the same renditions on multiple hosts; this keeps the pick on one
-* host rather than letting the ranker drift across them.
+* Active-CDN scope — a soft filter, shared by video and audio. Narrows to the highest-priority CDN in `cdnPriority`
+* (owned by `deriveCdnPriority`) that still has tracks, so every track type stays on one CDN. A redundant-streams
+* source lists the same renditions on multiple hosts; this keeps the pick on one host rather than letting the ranker
+* drift across them.
 *
-* "Active" is derived, not stored: constraints run before the rule chain, so a
-* failed CDN's tracks are already pruned by the time this runs — "first CDN with
-* survivors" *is* the active CDN, and it falls through to the next on failover
-* (and snaps back to the primary when it recovers). Content steering reorders
-* `cdnPriority`; this rule just honors the order.
+* "Active" is derived, not stored: constraints run before the rule chain, so a failed CDN's tracks are already pruned
+* by the time this runs — "first CDN with survivors" _is_ the active CDN, and it falls through to the next on failover
+* (and snaps back to the primary when it recovers). Content steering reorders `cdnPriority`; this rule just honors the
+* order.
 *
-* Soft-filter semantics: passes through when there's no `cdnPriority` signal/value
-* (no preference) or when nothing matches (`applyRules` skips an empty result).
-* Non-redundant sources have one CDN, so the narrow is a no-op.
+* Soft-filter semantics: passes through when there's no `cdnPriority` signal/value (no preference) or when nothing
+* matches (`applyRules` skips an empty result). Non-redundant sources have one CDN, so the narrow is a no-op.
 *
-* The CDN-id derivation defaults to origin-based `getCdnId`, overridable via the
-* `getCdnId` config — it must match the one `deriveCdnPriority` used to build
-* `cdnPriority`, or no track's CDN would ever equal an entry.
+* The CDN-id derivation defaults to origin-based `getCdnId`, overridable via the `getCdnId` config — it must match the
+* one `deriveCdnPriority` used to build `cdnPriority`, or no track's CDN would ever equal an entry.
 */
 function preferActiveCdn(tracks, { state, config }) {
 	const cdnPriority = state.cdnPriority?.get();
@@ -178,24 +153,63 @@ function preferActiveCdn(tracks, { state, config }) {
 	return tracks;
 }
 /**
-* Bandwidth ranking — the terminal sort, shared by video and audio. Orders by
-* the throughput estimate: tracks within the bandwidth threshold first
-* (fitting), highest bitrate first; then over-threshold tracks, least-over
-* first. The head is the best-quality track that fits, falling back to the
-* smallest over-throughput track when nothing fits.
+* Codec-family sticky constraint — a _hard_ filter for the constraints pre-pass, shared by video and audio, and the
+* reason the re-evaluating variants can run ABR over a mixed-codec source at all: SPF implements no
+* `SourceBuffer.changeType()`, so once segments of the selected track's codec families are what a buffer was created
+* for, a pick outside them could never play — constraint semantics ("can't play here"), not preference. Removes the
+* candidates whose codec-family set doesn't _equal_ the selected track's (set-equality so a muxed `hvc1,mp4a` rendition
+* can't pass as a match for `avc1,mp4a` on its audio half). Purely relational: the lock _is_ the current selection's
+* families, no state of its own. Pruned pre-pass, a cross-family user selection mid-stream never reaches the user
+* filter, which falls through unhonored instead of killing playback. Before any selection exists (the initial pick) it
+* removes nothing, which is what leaves the initial family choice to the rule chain (user intent, then
+* `preferCodecFamilies`).
 *
-* Hysteresis without temporal state: the current track's effective bitrate is
-* boosted by `upgradeMargin` in the fitting sort, so a higher track only
-* outranks it once it clears `current.bitrate * upgradeMargin` (no flapping on
-* marginal bandwidth gains). Downgrades fall out for free — a current track
-* over the threshold isn't in the fitting set to be boosted, so the best fit (a
-* downgrade) wins immediately. Equal-bitrate tracks break by resolution (higher
-* `width × height` first), so an equal-bitrate ladder never picks a lower-
-* quality rendition by manifest order; audio tracks carry no dimensions, so
-* they area-compare equal and a stable sort keeps their candidate order (e.g.
-* same-bitrate language variants). Early-bail skips this rule when a prior one
-* narrowed to a single track, so the estimate is neither read nor subscribed
-* while that holds.
+* The selected track's families come from the _presentation's_ track list, not the already-pruned candidates: a CDN
+* entering cooldown may prune the current track itself while same-family renditions survive on another host, and the
+* lock must carry over to them. Removes nothing when: no selection yet, a selection the presentation no longer carries,
+* or a selected track without codecs (then no candidate's compatibility is decidable — same inertness as
+* `preferCodecFamilies` on a codec-less ladder).
+*
+* When the selected family genuinely vanishes from the playable set, the pre-pass empties: the behavior reports the
+* type's no-supported-track code and clears the selection — an explicable stop instead of a cross-family append
+* surfacing as an opaque decode error. Clearing also releases the lock (it keys on the live selection), so a following
+* pick may land in the surviving family on freshly-created buffer actors; whether the append layer survives that
+* rebuild is the changeType gap, out of this constraint's hands. If `changeType` support ever lands, this constraint is
+* what relaxes.
+*
+* Reading the selection here — a slot the picking effect itself writes, from inside the candidate-set computed — is
+* safe only because the effect scheduler revalidates an effect's sources after each run; see `core/signals/effect.ts`
+* (`revalidateSources`) for the lost-wakeup it prevents.
+*
+* Composed only into the re-evaluating `switch*` variants: the pinned `selectVideoTrack` (background compositions)
+* evaluates once and never re-picks, so it's immune by construction.
+*/
+function stickToSelectedCodecs(tracks, { state, config }) {
+	const currentId = state[config.selectionKey].get();
+	if (!currentId) return tracks;
+	const presentation = state.presentation.get();
+	if (!isResolvedPresentation(presentation)) return tracks;
+	const current = config.getTracks(presentation).find((track) => track.id === currentId);
+	const families = current && getCodecFamilies(current);
+	if (!families) return tracks;
+	return tracks.filter((track) => {
+		const candidateFamilies = getCodecFamilies(track);
+		return !!candidateFamilies && candidateFamilies.length === families.length && candidateFamilies.every((family) => families.includes(family));
+	});
+}
+/**
+* Bandwidth ranking — the terminal sort, shared by video and audio. Orders by the throughput estimate: tracks within
+* the bandwidth threshold first (fitting), highest bitrate first; then over-threshold tracks, least-over first. The
+* head is the best-quality track that fits, falling back to the smallest over-throughput track when nothing fits.
+*
+* Hysteresis without temporal state: the current track's effective bitrate is boosted by `upgradeMargin` in the fitting
+* sort, so a higher track only outranks it once it clears `current.bitrate * upgradeMargin` (no flapping on marginal
+* bandwidth gains). Downgrades fall out for free — a current track over the threshold isn't in the fitting set to be
+* boosted, so the best fit (a downgrade) wins immediately. Equal-bitrate tracks break by resolution (higher `width ×
+* height` first), so an equal-bitrate ladder never picks a lower- quality rendition by manifest order; audio tracks
+* carry no dimensions, so they area-compare equal and a stable sort keeps their candidate order (e.g. same-bitrate
+* language variants). Early-bail skips this rule when a prior one narrowed to a single track, so the estimate is
+* neither read nor subscribed while that holds.
 */
 function rankByBandwidth(tracks, { state, config }) {
 	const safetyMargin = config.quality?.safetyMargin ?? DEFAULT_QUALITY_CONFIG.safetyMargin;
@@ -215,28 +229,25 @@ function rankByBandwidth(tracks, { state, config }) {
 	return [...fitting, ...over];
 }
 /**
-* Default final pick: the chain head. `applyRules` never narrows to nothing and
-* early-bails to a single survivor, so video and audio always converge to a
-* track and the head is the pick.
+* Default final pick: the chain head. `applyRules` never narrows to nothing and early-bails to a single survivor, so
+* video and audio always converge to a track and the head is the pick.
 */
 function selectChainHead(candidates) {
 	return candidates[0].id;
 }
 /**
-* Terminal pick for text — the `resolveSelection` the text variant supplies.
-* Resolves the standing `userTextTrackSelection` intent against the chain's
-* survivors (already CDN-failover-pruned and active-CDN-scoped):
+* Terminal pick for text — the `resolveSelection` the text variant supplies. Resolves the standing
+* `userTextTrackSelection` intent against the chain's survivors (already CDN-failover-pruned and active-CDN-scoped):
 *
-*   - `'off'` → no selection (clear the slot). Sticky through re-evaluation, so a
-*     live refresh or failover re-run can't re-assert a default.
-*   - explicit `Partial<TextTrack>` → narrow to the match (language-based). A
-*     stale pick whose match is gone (e.g. the language dropped on a source
-*     change) falls through to the default policy.
-*   - auto (`undefined`) → the opt-in default policy (`preferredSubtitleLanguage`
-*     → `DEFAULT=YES + AUTOSELECT=YES` → none), via `pickTextTrackFromTracks`.
+* - `'off'` → no selection (clear the slot). Sticky through re-evaluation, so a live refresh or failover re-run can't
+*   re-assert a default.
+* - Explicit `Partial<TextTrack>` → narrow to the match (language-based). A stale pick whose match is gone (e.g. the
+*   language dropped on a source change) falls through to the default policy.
+* - Auto (`undefined`) → the opt-in default policy (`preferredSubtitleLanguage` → `DEFAULT=YES + AUTOSELECT=YES` → none),
+*   via `pickTextTrackFromTracks`.
 *
-* Returning `undefined` is a real outcome (captions are opt-in), which is why the
-* text variant relies on `setupTrackSwitching`'s no-selection seam.
+* Returning `undefined` is a real outcome (captions are opt-in), which is why the text variant relies on
+* `setupTrackSwitching`'s no-selection seam.
 */
 function pickResolvedTextTrack(candidates, { state, config }) {
 	const intent = state.userTextTrackSelection?.get();
@@ -288,13 +299,12 @@ function setupTrackSwitching(deps) {
 	});
 }
 /**
-* Manage `selectedVideoTrackId`: pick a default on src load, dynamically
-* adjust based on bandwidth, clear on src unload. Honors
-* `userVideoTrackSelection` as a partial-track constraint on candidates;
-* short-circuits ABR when the constraint narrows to a single track.
+* Manage `selectedVideoTrackId`: pick a default on src load, dynamically adjust based on bandwidth, clear on src
+* unload. Honors `userVideoTrackSelection` as a partial-track constraint on candidates; short-circuits ABR when the
+* constraint narrows to a single track.
 *
 * @example
-* const reactor = switchVideoTrack.setup({ state });
+*   const reactor = switchVideoTrack.setup({ state });
 */
 const switchVideoTrack = defineBehavior({
 	stateKeys: ["presentation", "selectedVideoTrackId"],
@@ -307,9 +317,14 @@ const switchVideoTrack = defineBehavior({
 			selectionKey: "selectedVideoTrackId",
 			userSelectionKey: "userVideoTrackSelection",
 			getTracks: (presentation) => getTracksByType(presentation, "video"),
-			constraints: [excludeFailedCdns, excludeUnplayableTracks],
+			constraints: [
+				excludeFailedCdns,
+				excludeUnplayableTracks,
+				stickToSelectedCodecs
+			],
 			rules: [
 				filterByUserSelection,
+				preferCodecFamilies,
 				preferActiveCdn,
 				playerResolutionCap,
 				rankByBandwidth
@@ -319,17 +334,15 @@ const switchVideoTrack = defineBehavior({
 	})
 });
 /**
-* Manage `selectedAudioTrackId`: pick a default on src load, narrow by
-* `userAudioTrackSelection` filter, re-pick on filter change, clear on
-* src unload.
+* Manage `selectedAudioTrackId`: pick a default on src load, narrow by `userAudioTrackSelection` filter, re-pick on
+* filter change, clear on src unload.
 *
-* Mid-stream flush on language switch is handled by the segment-loader's
-* `planTasks` (see `playback/actors/dom/segment-loader.ts`) — not this
-* behavior. Same split as the video pipeline: slot owner writes; loader
-* orchestrates segment + flush plans.
+* Mid-stream flush on language switch is handled by the segment-loader's `planTasks` (see
+* `playback/actors/dom/segment-loader.ts`) — not this behavior. Same split as the video pipeline: slot owner writes;
+* loader orchestrates segment + flush plans.
 *
 * @example
-* const reactor = switchAudioTrack.setup({ state });
+*   const reactor = switchAudioTrack.setup({ state });
 */
 const switchAudioTrack = defineBehavior({
 	stateKeys: ["presentation", "selectedAudioTrackId"],
@@ -342,9 +355,14 @@ const switchAudioTrack = defineBehavior({
 			selectionKey: "selectedAudioTrackId",
 			userSelectionKey: "userAudioTrackSelection",
 			getTracks: (presentation) => getTracksByType(presentation, "audio"),
-			constraints: [excludeFailedCdns, excludeUnplayableTracks],
+			constraints: [
+				excludeFailedCdns,
+				excludeUnplayableTracks,
+				stickToSelectedCodecs
+			],
 			rules: [
 				filterByUserSelection,
+				preferCodecFamilies,
 				preferActiveCdn,
 				rankByBandwidth
 			],
@@ -353,21 +371,19 @@ const switchAudioTrack = defineBehavior({
 	})
 });
 /**
-* Manage `selectedTextTrackId` as the single-writer **output** of standing user
-* intent (`userTextTrackSelection`) resolved against the playable, CDN-scoped
-* text renditions: clear on src unload; re-resolve when a CDN fails or recovers.
+* Manage `selectedTextTrackId` as the single-writer **output** of standing user intent (`userTextTrackSelection`)
+* resolved against the playable, CDN-scoped text renditions: clear on src unload; re-resolve when a CDN fails or
+* recovers.
 *
-* Unlike video/audio, the selection is *optional* — captions are opt-in and the
-* user can turn them off — so the chain skips the bandwidth ranker and the shared
-* user-selection filter, and supplies a text-specific terminal
-* (`pickResolvedTextTrack`) that may resolve to no-selection via
-* `setupTrackSwitching`'s `resolveSelection` seam. Constraints are failed-CDN only
-* (`excludeUnplayableTracks`/`canPlayTrack` is MSE-based — the wrong probe for
-* text, whose playability is SPF-parser support); the active-CDN scope co-locates
-* captions with the surviving CDN on failover.
+* Unlike video/audio, the selection is _optional_ — captions are opt-in and the user can turn them off — so the chain
+* skips the bandwidth ranker and the shared user-selection filter, and supplies a text-specific terminal
+* (`pickResolvedTextTrack`) that may resolve to no-selection via `setupTrackSwitching`'s `resolveSelection` seam.
+* Constraints are failed-CDN only (`excludeUnplayableTracks`/`canPlayTrack` is MSE-based — the wrong probe for text,
+* whose playability is SPF-parser support); the active-CDN scope co-locates captions with the surviving CDN on
+* failover.
 *
 * @example
-* const reactor = switchTextTrack.setup({ state, config: { preferredSubtitleLanguage: 'en' } });
+*   const reactor = switchTextTrack.setup({ state, config: { preferredSubtitleLanguage: 'en' } });
 */
 const switchTextTrack = defineBehavior({
 	stateKeys: ["presentation", "selectedTextTrackId"],
@@ -386,6 +402,6 @@ const switchTextTrack = defineBehavior({
 	})
 });
 //#endregion
-export { DEFAULT_INITIAL_BANDWIDTH, setupTrackSwitching, switchAudioTrack, switchTextTrack, switchVideoTrack };
+export { DEFAULT_INITIAL_BANDWIDTH, setupTrackSwitching, stickToSelectedCodecs, switchAudioTrack, switchTextTrack, switchVideoTrack };
 
 //# sourceMappingURL=track-switching.js.map