videojs-http-streaming (VHS)

[![Build Status][travis-icon]][travis-link] [![Slack Status][slack-icon]][slack-link] [![Greenkeeper badge][greenkeeper-icon]][greenkeeper-link]

Play HLS, DASH, and future HTTP streaming protocols with video.js, even where they're not natively supported.

Included in video.js 7 by default! See the video.js 7 blog post

Maintenance Status: Stable

Video.js Compatibility: 7.x, 8.x

• Installation
• NPM
• CDN
• Releases
• Manual Build
• Contributing
• Troubleshooting
• Talk to us
• Getting Started
• Compatibility
• Browsers which support MSE
• Native only
• DRM
• Documentation
• Options
  • How to use
  • Initialization
  • Source
  • List
  • withCredentials
  • useCueTags
  • parse708captions
  • overrideNative
  • experimentalUseMMS
  • playlistExclusionDuration
  • maxPlaylistRetries
  • bandwidth
  • useBandwidthFromLocalStorage
  • enableLowInitialPlaylist
  • limitRenditionByPlayerDimensions
  • useDevicePixelRatio
  • usePlayerObjectFit
  • customPixelRatio
  • allowSeeksWithinUnsafeLiveWindow
  • customTagParsers
  • customTagMappers
  • cacheEncryptionKeys
  • handlePartialData
  • liveRangeSafeTimeDelta
  • useNetworkInformationApi
  • useDtsForTimestampOffset
  • useForcedSubtitles
  • captionServices
    • Format
    • Example
• Runtime Properties
  • vhs.playlists.main
  • vhs.playlists.media
  • vhs.systemBandwidth
  • vhs.bandwidth
  • vhs.throughput
  • vhs.selectPlaylist
  • vhs.representations
  • vhs.xhr
  • vhs.stats
• Events
  • loadedmetadata
  • xhr-hooks-ready
• VHS Usage Events
  • Presence Stats
  • Use Stats
• In-Band Metadata
• Segment Metadata
• Object as Source
• Hosting Considerations
• Known Issues and Workarounds
• Fragmented MP4 Support
• Assets with an Audio-Only Rate Get Stuck in Audio-Only
• DASH Assets with $Time Interpolation and SegmentTimelines with No t
• Testing
• Debugging
• Release History
• Building
• Development
• Tools
• Commands

Installation

In most cases it is not necessary to separately install http-streaming, as it has been included in the default build of Video.js since version 7.

Only install if you need a specifc combination of video.js and http-streaming versions. If installing separately, use the "core" version of Video.js without the bundled version of http-streaming.

NPM

To install videojs-http-streaming with npm, run

npm install --save @videojs/http-streaming

CDN

Select a version of VHS from the CDN

Releases

Download a release of videojs-http-streaming

Manual Build

Download a copy of this git repository and then follow the steps in Building

Contributing

See CONTRIBUTING.md

Troubleshooting

See our troubleshooting guide

Talk to us

Drop by the [Video.js slack][slack-link].

Getting Started

This library is included in Video.js 7 by default.

Only if need a specific combination of versions of Video.js and VHS you can get a copy of videojs-http-streaming and include it in your page along with video.js. In this case, you should use the "core" build of Video.js, without a bundled VHS:

<video-js id=vid1 width=600 height=300 class="vjs-default-skin" controls>



</video-js>

<script src="https://github.com/videojs/http-streaming/raw/v3.17.5/video.core.min.js"></script>
<script src="https://github.com/videojs/http-streaming/raw/v3.17.5/videojs-http-streaming.min.js"></script>
<script>
var player = videojs('vid1');
player.play();
</script>

Is it recommended to use the <video-js> element or load a source with player.src(sourceObject) in order to prevent the video element from playing the source natively where HLS is supported.

Compatibility

The Media Source Extensions API is required for http-streaming to play HLS or MPEG-DASH.

Browsers which support MSE

• Chrome
• Firefox
• Internet Explorer 11 Windows 10 or 8.1

These browsers have some level of native HLS support, however by default the overrideNative option is set to true except on Safari, so MSE playback is used:

• Chrome Android
• Firefox Android
• Edge

Native only

• Mac Safari
• iOS Safari

Mac and iPad Safari do have MSE support, but native HLS is recommended

DRM

DRM is supported through videojs-contrib-eme. In order to use DRM, include the videojs-contrib-eme plug, initialize it, and add options to either the plugin or the source.

Detailed option information can be found in the videojs-contrib-eme README.

Documentation

HTTP Live Streaming (HLS) has become a de-facto standard for streaming video on mobile devices thanks to its native support on iOS and Android. There are a number of reasons independent of platform to recommend the format, though:

• Supports (client-driven) adaptive bitrate selection
• Delivered over standard HTTP ports
• Simple, text-based manifest format
• No proprietary streaming servers required

Unfortunately, all the major desktop browsers except for Safari are missing HLS support. That leaves web developers in the unfortunate position of having to maintain alternate renditions of the same video and potentially having to forego HTML-based video entirely to provide the best desktop viewing experience.

This project addresses that situation by providing a polyfill for HLS on browsers that have support for Media Source Extensions. You can deploy a single HLS stream, code against the regular HTML5 video APIs, and create a fast, high-quality video experience across all the big web device categories.

Check out the full documentation for details on how HLS works and advanced configuration. A description of the adaptive switching behavior is available, too.

videojs-http-streaming supports a bunch of HLS features. Here are some highlights:

• video-on-demand and live playback modes
• backup or redundant streams
• mid-segment quality switching
• AES-128 segment encryption
• CEA-608 captions are automatically translated into standard HTML5 caption text tracks
• In-Manifest WebVTT subtitles are automatically translated into standard HTML5 subtitle tracks
• Timed ID3 Metadata is automatically translated into HTML5 metedata text tracks
• Highly customizable adaptive bitrate selection
• Automatic bandwidth tracking
• Cross-domain credentials support with CORS
• Tight integration with video.js and a philosophy of exposing as much as possible with standard HTML APIs
• Stream with multiple audio tracks and switching to those audio tracks (see the docs folder) for info
• Media content in fragmented MP4s instead of the MPEG2-TS container format.

For a more complete list of supported and missing features, refer to this doc.

Options

How to use

Initialization

You may pass in an options object to the hls source handler at player initialization. You can pass in options just like you would for other parts of video.js:

// html5 for html hls
videojs(video, {
  html5: {
    vhs: {
      withCredentials: true
    }
  }
});

Source

Some options, such as withCredentials can be passed in to vhs during player.src

var player = videojs('some-video-id');

player.src({
  src: 'https://d2zihajmogu5jn.cloudfront.net/bipbop-advanced/bipbop_16x9_variant.m3u8',
  type: 'application/x-mpegURL',
  withCredentials: true
});

List

withCredentials

• Type: boolean
• can be used as a source option
• can be used as an initialization option

When the withCredentials property is set to true, all XHR requests for manifests and segments would have withCredentials set to true as well. This enables storing and passing cookies from the server that the manifests and segments live on. This has some implications on CORS because when set, the Access-Control-Allow-Origin header cannot be set to *, also, the response headers require the addition of Access-Control-Allow-Credentials header which is set to true. See html5rocks's article for more info.

useCueTags

• Type: boolean
• can be used as an initialization option

When the useCueTags property is set to true, a text track is created with label 'ad-cues' and kind 'metadata'. The track is then added to player.textTracks(). Changes in active cue may be tracked by following the Video.js cue points API for text tracks. For example:

let textTracks = player.textTracks();
let cuesTrack;

for (let i = 0; i < textTracks.length; i++) {
  if (textTracks[i].label === 'ad-cues') {
    cuesTrack = textTracks[i];
  }
}

cuesTrack.addEventListener('cuechange', function() {
  let activeCues = cuesTrack.activeCues;

  for (let i = 0; i < activeCues.length; i++) {
    let activeCue = activeCues[i];

    console.log('Cue runs from ' + activeCue.startTime +
                ' to ' + activeCue.endTime);
  }
});

parse708captions

• Type: boolean
• Default: true
• can be used as an initialization option

When set to false, 708 captions in the stream are not parsed and will not show up in text track lists or the captions menu.

overrideNative

• Type: boolean
• can be used as an initialization option

Try to use videojs-http-streaming even on platforms that provide some level of HLS support natively. There are a number of platforms that technically play back HLS content but aren't very reliable or are missing features like CEA-608 captions support. When overrideNative is true, if the platform supports Media Source Extensions videojs-http-streaming will take over HLS playback to provide a more consistent experience.

// via the constructor
var player = videojs('playerId', {
  html5: {
    vhs: {
      overrideNative: true
    },
    nativeAudioTracks: false,
    nativeVideoTracks: false
  }
});

Since MSE playback may be desirable on all browsers with some native support other than Safari, overrideNative: !videojs.browser.IS_SAFARI could be used.

experimentalUseMMS

• Type: boolean
• can be used as an initialization option

Use ManagedMediaSource when available. If both ManagedMediaSource and MediaSource are present, ManagedMediaSource would be used. This will only be effective if ovrerideNative is true, because currently the only browsers that implement ManagedMediaSource also have native support. Safari on iPhone 17.1 has ManagedMediaSource, as does Safari 17 on desktop and iPad.

Currently, using this option will disable AirPlay.

playlistExclusionDuration

• Type: number
• can be used as an initialization option

When the playlistExclusionDuration property is set to a time duration in seconds, if a playlist is excluded, it will be excluded for a period of that customized duration. This enables the exclusion duration to be configured by the user.

maxPlaylistRetries

• Type: number
• Default: Infinity
• can be used as an initialization option

The max number of times that a playlist will retry loading following an error before being indefinitely excluded from the rendition select