rx-player

📖 API documentation - ⏯ Demo - 🎓 Getting Started - 🔧 Contributing

The RxPlayer is a library implementing a DASH and Microsoft Smooth Streaming media player on a browser, by relying on the HTML5 Media Source Extensions and Encrypted Media extensions browser APIs.

---

Originally designed to power Canal+ many applications, the RxPlayer is today used in production by several companies in multiple countries and runs on most devices where a browser can run: Computers, phones, set-top-boxes, smart TVs, game consoles and other peculiar environments are all supported and able to profit from its many features.

Its main goals are:

• Stability: The RxPlayer can play live and On Demand DASH and Smooth contents for extended amounts of time, with or without DRM - without any performance, memory or logic issue.

  If you encounter a new issue while using it, we'll be very happy to help fixing it. Any encountered bug is put at high priority.

• Quality of experience: It aims to play the best possible quality without any rebuffering.

  Unsupported codecs and undecipherable qualities (e.g. higher qualities with more drastic DRM conditions on untrusted devices) are automatically filtered out, even if this happens during playback.

  The player is also very resilient: any temporary network issue, fall in bandwidth, poorly-packaged content or platform quirk should be properly handled with the main goal of avoiding playback interruption.

• Portability: The RxPlayer has been ported to a lot of devices, some on the lower-end of performance and memory capabilities and others on the higher end.

  As such, it can adapt to important memory and performance constraints while still being able to retain its many features.

• Configurability: The RxPlayer has a plethora of options to let you tweak its behavior. You should be able to play any content the way you want, on any device.

  You should also be able to integrate complex supplementary logic like Peer-to-Peer solutions.

• Easy to use: We try hard to make this player easy to integrate and to use in various codebases.

  Even for the more advanced options, we aim to make our documentation as legible and as complete as possible.

The RxPlayer has probably already all the features you want :)!

Even if that's not the case, we will be very pleased to exchange with you on it and look forward for external contributions.

How to use it?

The fastest way to use the player directly in your code is to add this repository as a dependency.

You can do it via npm or yarn:

# when using npm:
npm install --save rx-player

# or, when using yarn instead:
yarn add rx-player

You can then directly import and use the RxPlayer in your code:

// import it ES6 style:
import RxPlayer from "rx-player";

// same in CommonJS style:
// const RxPlayer = require("rx-player");

// instantiate it
const player = new RxPlayer({
  videoElement: document.querySelector("video"),
});

// play a video
player.loadVideo({
  url: "http://vm2.dashif.org/livesim-dev/segtimeline_1/testpic_6s/Manifest.mpd",
  transport: "dash",
  autoPlay: true,
});

We've also written short tutorials to help you familiarize with the RxPlayer API:

• Quick start into the API.
• Playing contents with DRMs.
• Selecting a track
• Listening to events contained in the content

To be able to play with the player without needing to perform any setup we also created multiple live-editable demos:

• Playing a clear DASH content
• Playing an encrypted DASH content
• Playing an RxPlayer-specific MetaPlaylist content

Minimal Builds

To reduce the size of the final code, you might also want to import a minimal version of the player and only import the features you need. This is documented here :

For example, to play encrypted DASH contents, you could just write:

import RxPlayer from "rx-player/minimal";
import { DASH, EME } from "rx-player/features";

// Allow to play encrypted DASH contents
RxPlayer.addFeatures([DASH, EME]);

API

We documented the API in every little details in the API documentation.

You can also refer to the documentation of our previous versions here

These documentation pages are automatically generated from the content of the doc/api directory in this repository.

Demo

You can view our online Demo, built from our last version, here.

This demo is a small application written in React demonstrating a simple usage of the player.

Demo pages for our previous versions are also available here.

Contribute

Details on how to contribute is written in the CONTRIBUTING.md file at the root of this repository.

Dependencies

After cloning our repo, you should first install our dependencies via either npm:

npm install

Why a new player?

A need for an advanced media player

Canal+ Group is a media company with many advanced needs when it comes to media playback: it provides both live and VoD stream with multiple encryption requirements, supports a very large panel of devices and has many other specificities (like adult content restrictions, ad-insertion, Peer-To-Peer integration, low-latency live streaming...).

When the time came to switch from a plugin-based web player approach to an HTML5 one back in 2015, no media player had the key features we wanted, and including those needs into an already existing media player would not be straightforward either.

The R&D department of Canal+ Group thus started to work on a new featureful media-player: the RxPlayer. To both help and profit from the community, it also decided to share it to everyone under a permissive open-source licence.

Now, more than 8 years later, the RxPlayer continues to evolve at the same fast pace to include a lot of features and improvements you may not find in other media players. You can look at our API documentation, tutorials and our demo page (an RxPlayer instance is available in the console through the global player variable there) to see if it matches your need.

A featureful player

With the help of a carefully-crafted and well-documented architecture, we were able to quickly support avanced features when we - or the community - needed them. Amongst those:

• support for live and VoD DASH / Smooth / HLS* / Downloaded contents / MP4* / WebM* contents and more

• support of advanced encryption configuration, such as multiple keys in a single or separate licences for a given content (with automatic fallbacks when we found an un-decipherable content), persistent licenses, and other device-specific restrictions.

• support for low-latency DASH streams

• support of TTML, WebVTT, SAMI and SRT subtitles

• an available WebAssembly-based MPD parser for DASH contents, allowing to drastically reduce the loading time and memory usage of larger contents.

• advanced APIs for advanced use-cases (audio-only mode, video track selection, manual garbage collection of segments, Peer-To-Peer integration, quality filtering...)

• advanced adaptive streaming algorithms making use of both a network-based approach (for quick start-up) and a buffer-based one (to provide the best quality possible).

• advanced optimizations for devices with low memory constraints

• a complex segment scheduling logic, prioritizing closer media segments while making sure that the bandwidth usage is always optimal and the rebuffering risks always low.

* In "directfile" mode, on compatible browsers

Changelog

v4.2.0 (2024-10-17)

Features

• Add cmcd object to loadVideo options to enable CMCD (Common Media Client Data) [#1461, #1518]
• Add checkManifestIntegrity loadVideo option as a temporary work-around when you suspect your packager or CDN to sometimes deliver corrupted data [#1471]
• Add contentProtections to the representations of the tracks API to know if they're considered encrypted [#1505]
• Add filterPlayableRepresentations property to audio and video tracks API to get information on ALL representations, even those that won't be played [#1501]
• Add LogFormat static property to the RxPlayer to try improving on bug reports [#1469]
• Experimentally re-export config in v4 (only intended for debugging matters) [#1510]
• Add keySystems[].reuseMediaKeys option to loadVideo [#1520]

Bug fixes

• Detect cases where an encrypted media's codec is not supported specifically when the media is encrypted and prevent the playback of such contents [#1484]
• Work-around the "hulu issue" seen on firefox 129 and 130 (1911283 and 1912238 on bugzilla) which also impacted the RxPlayer [#1495, #1498]
• Fix rare cases where the active Period would not be advertised by the RxPlayer [#1502]
• Actually trigger a BUFFER_FULL_ERROR when QuotaExceededError mitigations after appendBuffer MSE calls don't work #1546
• Fix issues when handling a QuotaExceededError after an appendBuffer MSE call [#1546, #1559]
• Directfile/Compat: Fix startAt.fromLastPosition handling on Safari when playing directfile contents [#1548]
• DRM/Compat: Re-create MediaKeys for each content on Philips' NETTV, and KSTB40XX set-top boxes [#1515]
• DRM/Compat: fix content not starting on Safari because key are never considered usable for a track [#1479, #1512]
• DASH_WASM: fix Label element never being parsed [#1541, #1540]
• Fix RxPlayer not being exposed in release bundles [#1542]
• Consider stpp.ttml codec for text format [#1557]
• Prevent very rare cases of infinite rebuffering after getting errors from calling the SourceBuffer.prototype.appendBuffer and SourceBuffer.prototype.remove MSE API [#1560, #1561]
• MULTI_THREAD: Fix rare CancellationError error happening when reloading while a reload is pending. [#1528]
• MULTI_THREAD: fix wrong Period considered as current in multi-Period DASH contents with the multi-thread feature [#1527]
• MULTI_THREAD: Fix rare occurrences of infinite loading on constrained devices [#1556]
• MediaCapabilitiesProber checks generateRequest like the RxPlayer DRM selection algorithm [#1575]
• Fixes a MultiThread debug element memory leak [#1564]
• Fix the SyncOrAsync util syncValue transfer [#1568]
• Fix off by one issue in when relying on keySystems[].maxSessionCacheSize [#1565]

Other improvements

• DASH: provide a more precize calculation for the timeshift buffer depth [#1483]
• Handle hev1 codec and hvc1 codecs as part of the same family of codecs when trying to check for compatibility between the two [#1499]
• Better handle QuotaExceededError issue after appendBuffer MSE calls when wantedBufferAhead is set to Infinity [#1546]
• Code: Forbid the direct usage of MSE and HTML5 media TypeScript type in profit of our own compatible ones to facilitate testing and the addition of platform-specific differences [#1397].
• Demo: Remove standalone demo as we never relied on it [#1473]
• Scripts: Automatize official releases and CHANGELOG.md updating through a script [#1524]
• Add version of the RxPlayer in the debug element [#1573]