Summary

HLS.js v1.5.0 includes playback and API enhancements that support HLS assets containing multiple codec variants, HDR video variants, and multi-channel audio renditions. Support for MediaCapabilities and ManagedMediaSource has also been adopted.

Media segment codec parsing is available for direct playback of media playlists as well as proper setup of MediaSource buffers for AV1, HEVC, HEVC with DolbyVision, AVC, AC3, EC3, Apple Lossless (ALAC), AAC, FLAC and Opus.

MediaCapabilities decodeInfo checks are performed after the initial start before switching to UHD, HDR, and Multi-channel audio options.

Note that auto-switching between codec families is not supported. HLS.js will attempt to start on the most efficient supported codec set available within the initial bandwidth estimate range (up to 500kbps). However, switching between variants with incompatible codecs requires manual intervention by the user or application. Constraining playback to compatible codecs maintains maximum compatibility and stable playback. changeType is used when necessary but avoided for auto-switching because it is not always stable or smooth between all combinations or on all platforms.

ManagedMediaSource support adds the ability to run HLS.js on iOS 17.1 and up. HLS.js in Safari on iOS, iPadOS, and MacOS leverages ManagedMediaSource to start and stop streaming for power-efficient use of wireless connections.

Changes Since The Last Release

v1.4.14...v1.5.0

API Enhancements

Named exports for all classes and enums are available in ESM output (#5930) @robwalch
Rendition selection enhancements (#5704)
- HLS.js will no longer start on the first variant (hls.firstLevel) or any variant of a preferred codec if its BANDWIDTH exceeds abrEwmaDefaultEstimateMax
- Added hls.firstAutoLevel getter, used internally to get the starting level index
  hls.levels are sorted on height, frame rate, preferred codec, and video-range to infer order by quality. Height-first sorting allows cap-level-lontroller to set a max quality index at the maximum allowed resolution
- Added getters for all audio tracks and all subtitle tracks: hls.allAudioTracks and hls.allSubtitleTracks
API enhancements for audio and subtitle selection (#5978)
- hls.setAudioOption() and config.audioPreference have been added to simplify audio selection based on user preferences and playback settings
- hls.setSubtitleOption() and config.subtitlePreference have been added to simplify subtitle selection based on user preferences and playback settings. Only subtitle media options (hls.allSubtitleTracks) are subject to selection criteria. Captions are assigned a TextTrack or emitted through events when native rendering is disabled.
config.videoPreference.preferHDR and preferHDR have been added to override the default SDR/HDR selection behavior
Base initial bandwidth estimate on first level bitrate (#5649)
- Added setter for bandwidthEstimate that resets estimator to a new starting value
Initial selection and level filtering based on preferred codecs and MediaCapabilities (#5704)
- Added config.useMediaCapabilities (defaults to true)
- Set config.useMediaCapabilities to false to disable the use of MediaCapabilities.decodingInfo
isSupported() has been expanded to test alternate baseline codecs (#6006)
- Added isMSESupported(), a subroutine of isSupported(), checks for MediaSource API without isTypeSupported checks.
- Added getMediaSource(), which returns the preferred MSE interface or undefined when unavailable
- Added named exports for isSupported, isMSESupported, and getMediaSource
Fire STEERING_MANIFEST_LOADED event when loading a Content Steering Manifest (#5417) @guillemcabrera
Added config flag for maximum front buffer frontBufferFlushThreshold (#5761) @iamboorrito
Implement event for maxAutoLevel change (#5763) @robwalch
Specify custom shouldRetry predicate in retryConfig (#5658) @PavelFomin90 (completed in #5762)
Default estimate enhancements (#5649) @robwalch
- Added config.abrEwmaDefaultEstimateMax option, which limits how high the initial default value may be adjusted
  Separate peak and average bitrates of Level objects
Level properties
- Level.bitrate uses variant BANDWIDTH (required peak bitrate) before falling back to optional AVERAGE-BANDWIDTH.
- Level.averageBitrate returns parsed AVERAGE-BANDWIDTH. Falls back to runtime average Level.realBitrate (which is only set when config.abrMaxWithRealBitrate is enabled) and finally Level.bitrate (BANDWIDTH).
- Added Level.frameRate returns parsed FRAME-RATE number or 0.
- Added Level.codecs returns parsed CODECS or empty string.
- Added Level.score returns parsed SCORE number or 0.
Added config option preferManagedMediaSource. Set it to false to use MediaSource rather than ManagedMediaSource on platforms with both.
Extended cmcd config option with cmcd.includeKeys. Takes an array of CMCD keys to include in client requests. (#5903) @littlespex

Codec Support

HDR/SDR VIDEO-RANGE selection and priority (#6007) @robwalch
Expand isSupported check to allow alternative codecs (#6006)
Added codec string parsing for h264, h265, and mp4a (#4996) @uvjustin
MP4 Sample Description ("stsd") CODEC Parsing (#5528)
Added HEVC decoder configuration parser (890fae3) @fogarasyroland
Added FLAC support (#4772) @jprjr
Added support for AC-3 codec in MPEG-TS (#5167) @erankor
Added AC3 file support and exclude AC3 parsing from hls.light builds (#5562) @robwalch
Added support for AC-3 audio in DVB streams (#5636) @softworkz
Prepare for Supporting Additional Video Codecs (#5634) @softworkz

iOS 17.1 Support

ManagedMediaSource Support (#5542) @robwalch
Check ManagedMediaSource removedRanges length on "bufferedchange" event (#5915)

Live Streaming Bug Fixes

Fixed Low-Latency HLS directives skipping part 0 (#5714) @jhonalino
Fixed support of skip directive without block reload (#5791) @robwalch
Fixed live frag finding after detaching and re-attaching past live window (#5742)
Handle #EXT-X-ENDLIST appended to live playlist without new segment (#5778)

Captions, Subtitles, and Metadata Bug Fixes

Clear CEA-608 captions on discontinuity (#5557)
Fixed DateRange metadata cue duration with ID3 cues that overlap (#5546)
Use input timescale when remuxing inband captions (#5675)

Bug Fixes (Misc)

Fix regression in emergency switch down (#6082) @robwalch
Fix codec parsing for AVC streams (#6077) by @Qizot
Fix fetch loader abort in progressive mode (#6066) @robwalch
Fix base-stream-controller onHandlerDestroying callback evocation (#6057)
- (Removes circular references left after destroying player)
Fixed ID3 Decoding On Play Station 4 (#6042) @agajassi
Fixed (latency-controller) only sync live stream (#5604) @FredZeng
Use addEventListener for MediaKeySession events (#6030) @robwalch
Fix handling of the DATERANGE END-ON-NEXT attribute (#6038)
Fixed esds box parsing (#6019)
Added polyfill for isSafeInteger (#6022)
ID3 TextTrack Cue fixes for PlayStation4 (#6021)
Fixed issues parsing sei_messages (#5998) @jcekstrom
Fixed issues with long cea608 captions (#5953) @jcekstrom
Fixed regression in dev with CEA608 parser setup (#5986) @robwalch
Fixed detach/attach behavior dropping one of two SourceBuffers (#5974)
Filter variants with any unsupported codecs (#5533)
Fixed two AV1 parsing issues (#5774) @nyanmisaka
Push AUD units to fix decode errors with some TS segments (#5696) @robwalch
Fail MP3 probe if AC3 or EC3 detected (#5695)
Prevent ADTS probe false positives when bytes following ID3 are a match for MPEG audio (#5783)
Reset init segment when M2TS video configuration changes (#5794)
Fixed capLevelToPlayerSize after hiding player and maintain stable selection when aspect ratio changes (#5614)
Fixed handling of segments at the discontinuities that do not start with a keyframe (#5659)
Fixed AC3 PES parsing (#5673) @softworkz
Fixed issue #5632, where missing AUD units for keyframes causes them to be merged with their preceding frame (#5652) @Thulinma
Fixed Safari decode errors with DTS not increasing when PTS decreases (#5710) @robwalch
Fixed PlayReady DRM in Edge browser (#5699) @mikrohard
Do not jump start gaps when paused (#5502) @robwalch
Never back-track on first fragment to avoid loop loading (#5613)
Use last discontinuity bounds when aligning playlists on PDT (#5681)
Load last alt-audio segment even when is starts after the end of the main playlist (#5717)
Do not exit from stall detection when playhead is at or past end of buffer (#5779)
Error and switch on SourceBuffer append requests for non-existing tracks (#5485)
Handle mixed sourcebuffer errors (#5623)
Remove SourceBuffers on "updateend" when MediaSource is closed (#5731)
Resume fragment loading after level switch follows level error (#5537)
Prevent recursion in error event handlers that throw (#5549)
Reset loading start on worker setup error (#5620)

Enhancements

Use Content Steering Pathways to manage Redundant Streams (#5970)
Remove the use of self from enableLogger (#5936)
Refactor CMCD controller and tests to use the common media library utilities (#5903) @littlespex
Updated CMCD dependency @svta/common-media-library to v0.6.0 (#6024)
Lazy init CEA608 parsers (#5689) @robwalch
Improve buffer-controller logging (#5548)
Do not modify fmp4 bytes when there is no offset (#5780)
Ignore #EXT-X-INDEPENDENT-SEGMENTS (#6047)