docs: multi-audio-track API design#1636
Conversation
👷 Deploy request for vjs10-site pending review.Visit the deploys page to approve it
|
|
@ronald-urbina is attempting to deploy a commit to the Mux Team on Vercel. A member of the Team first needs to authorize it. |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 2 potential issues.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit a697759. Configure here.
| **Adapter (`SimpleHlsMedia`, in core).** `SimpleHlsMedia` is the boundary where SPF internals meet the rest of the stack. It gains an `audioTracks` read-only property (returning a list of track objects with `id`, `label`, `language`, `kind`, and `enabled`), a `selectAudioTrack(id)` method, and fires an `audiotrackschange` event whenever the track list or active selection changes. | ||
|
|
||
| Internally it uses SPF's `effect()` to watch `presentation` and `selectedAudioTrackId` signals and dispatch the event when either changes. The effect is created fresh on each `src` assignment and torn down on `destroy()`, matching the engine lifecycle. | ||
|
|
There was a problem hiding this comment.
Effect cleanup missing on src
Medium Severity
The adapter effect() is only described as torn down on destroy(), but SimpleHlsMediaMixin recreates the engine on every src assignment via #engine.destroy() without calling adapter destroy(). Implementations that follow the doc literally would leave prior effects subscribed and leak watchers plus duplicate audiotrackschange dispatches after each source change.
Reviewed by Cursor Bugbot for commit a697759. Configure here.
|
|
||
| Internally it uses SPF's `effect()` to watch `presentation` and `selectedAudioTrackId` signals and dispatch the event when either changes. The effect is created fresh on each `src` assignment and torn down on `destroy()`, matching the engine lifecycle. | ||
|
|
||
| The track shape maps SPF's `AudioTrack` fields to a clean public surface: `name` becomes `label`, `language` carries over, and `enabled` is derived by comparing each track's `id` to `selectedAudioTrackId`. SPF's `AudioTrack` has no `kind` field — the property defaults to `'main'`, appropriate for HLS audio renditions today. |
There was a problem hiding this comment.
Unresolved presentation track enumeration
Medium Severity
The design has the adapter effect() react to presentation changes to build audioTracks, but presentation is often only { url } until parsing finishes. Enumerating selectionSets without narrowing to a resolved presentation (as existing SPF helpers do) can throw at runtime and leaves the doc silent on returning an empty list while unresolved.
Reviewed by Cursor Bugbot for commit a697759. Configure here.
|
|
||
| ## Proposed Architecture | ||
|
|
||
| **Adapter (`SimpleHlsMedia`, in core).** `SimpleHlsMedia` is the boundary where SPF internals meet the rest of the stack. It gains an `audioTracks` read-only property (returning a list of track objects with `id`, `label`, `language`, `kind`, and `enabled`), a `selectAudioTrack(id)` method, and fires an `audiotrackschange` event whenever the track list or active selection changes. |
There was a problem hiding this comment.
There is no need for new API's on the media, they're covered by
https://github.com/muxinc/media-elements/tree/main/packages/media-tracks
Look for the hls.js implementation at #1609
2 participants
Adds a design doc for the multi-audio-track consumer API (issue #1261). SPF already handles audio renditions internally — this doc covers how to surface them through the existing feature/predicate/selector pattern used by
streamTypeandtextTrack, and explains why the text track DOM path doesn't apply to audio (MSE vs elements). Meant as a team read before we start coding.start to resolve 1261
Note
Low Risk
Documentation-only change with no runtime or API surface modifications.
Overview
Adds
internal/design/audio-track-api.md, a draft design for exposing SPF’s internal HLS audio renditions as a stable consumer API (issue #1261).The doc proposes mirroring
textTrackFeature/streamType:MediaTracksLayeronSimpleHlsMedia, aSimpleHlsMediaTracksextension syncing SPFpresentation/selectedAudioTrackIdwith DOMaudioTracks, a newaudioTrackFeaturewithselectAudioTrack, and inclusion in all four feature presets—without changing SPF internals or scopingHlsJsMedia/NativeHlsMediain this effort.Reviewed by Cursor Bugbot for commit 72a33b2. Bugbot is set up for automated code reviews on this repo. Configure here.