v1.5.0

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)

Typescript Improvements

• Correcting usage of extended generic type LoaderContext in type Loader (#5494) @lvnam96
• Make loader context nullable and cleanup loader cleanup (#5552) @robwalch

Demo Page Enhancements

• Added playsInline to video elements on demo pages (#5556) @tjenkinson

Documentation

• Added additional documentation for workerPath config (#5765) @mogzol

Project and CI

• Store deployments in JSON file, and generate md and txt file from that (#6044) @tjenkinson
• Upgrade to Rollup 4 (#5886)
• Configure typescript, eslint and prettier caches (#5990)
• Update karma-rollup-preprocessor to version that works in watch mode (#5991)
• Update question.yaml template description (#5591) @robwalch
• Added Visual Studio Exclusions to .gitignore (#5635) @softworkz

Demo Page

https://d977f407.hls-js-dev.pages.dev/demo/

API and Breaking Changes

If you are upgrading from version v0.14.17 or lower, see the MIGRATING guide for API changes between v0.14.x and v1.x.

Feedback

Please provide feedback via Issues in GitHub. For more details on how to contribute to HLS.js, see our CONTRIBUTING guide.