W3C Media Capabilities - Amazon Vega Docs

The Media Capabilities API provides key features to help players better decide how to handle media, and determine how well media is being handled. This API replaces and improves upon the MediaSource method, isTypeSupported() method, the HTMLMediaElement method, and the canPlayType() method. Players that use this API can make informed decisions and make sure that High Dynamic Range (HDR) content is not delivered to a Standard Dynamic Range (SDR) screen. The World Wide Web Consortium (W3C) specification defines the decodingInfo method which allows you to query the user agent to determine the audio and video decoding capabilities. The method indicates if the configuration is supported and whether the playback is expected to be smooth and/or power efficient. JavaScript players such as Shaka depend on decodingInfo() method to detect the media capabilities of the device before starting the playback. In such cases, applications can install a polyfill to get the Vega implementation of the decodingInfo() method and let the player take decisions accordingly. More information on how install polyfill, see the Install and setup W3C Media Capabilities section.

W3C Media Capabilities prerequisites

The feature is implemented in the W3C API provided as part of Vega SDK. Apps must add this API to their package.json as dependency to get the required imports.

Install and setup W3C Media Capabilities

Setup a media player project.
Install the polyfill as shown in the How to use W3C Media Capabilities section.

How to use W3C Media Capabilities

Apps that use ShakaPlayer

For apps that use Shaka Player, there is a polyfill that is provided as part of the Shaka Player release. For more information about the Shaka Player release for Vega, see Play adaptive content (HLS/DASH) with Shaka Player. This polyfill provides the decodingInfo() method through navigator. Shaka Player internally uses this decodingInfo() method when it provides the implementation. To apply the new implementation without any additional code changes, update the Shaka Player dist folder.

Apps that use a JavaScript player which uses `decodingInfo()` internally

Apps that use other players which need an implementation of decodingInfo(), must manually install the polyfill.

import {
    decodingInfo as decodingInfoImpl,
} from '@amazon-devices/react-native-w3cmedia';

class W3CMediaPolyfill {
    static install() {
        global.navigator.mediaCapabilities = ({});
        global.navigator.mediaCapabilities.decodingInfo = decodingInfoImpl;
    }
}

export default W3CMediaPolyfill;

// call W3CMediaPolyfill.install(); to install the polyfill.

Note that there are caveats on how HLS.js and DASH.js players use the decodingInfo() method. For more information, see the FAQs section.

Apps that use a JavaScript player which doesn’t depend on `decodingInfo()`

Players such as Theo and Bitmovin use canPlayType or isTypeSupported instead of decodingInfo(). Applications can either continue to use the same methods if they cater to their requirements or call into MediaCapabilities API outside the player and use the information to start the playback.

import {
    decodingInfo as decodingInfoImpl,
} from '@amazon-devices/react-native-w3cmedia';

const contentType = 'video/mp4;codecs=avc1.640028';

const configuration = {
  type: 'media-source',
  video: {
    contentType: contentType,
    width: 640,
    height: 360,
    bitrate: 2000, // should be in bps
    framerate: 29.97
  }
};

decodingInfoImpl(configuration)
  .then((result) => {
    console.log('Decoding of ' + contentType + ' is'
      + (result.supported ? '' : ' NOT') + ' supported,'
      + (result.smooth ? '' : ' NOT') + ' smooth and'
      + (result.powerEfficient ? '' : ' NOT') + ' power efficient');
  })
  .catch((err) => {
    console.error(err, ' caused decodingInfo to reject');
});

FAQs

How to check the Dolby support?

The Vega implementation of the decodingInfo() and isTypeSupported() methods consider the connected TV’s or AVR’s capabilities as well and return the results accordingly. The following code example shows the minimum configuration you can send to use the decodingInfo() method to check the Dolby support.

import {
    decodingInfo as decodingInfoImpl,
} from '@amazon-devices/react-native-w3cmedia';

const contentType = 'audio/mp4;codecs=ec-3';

const configuration = {
  type: 'media-source',
  audio: {
    contentType: contentType,
    channels: 5.1.1,
    sampleRate: 48000,
  }
};

decodingInfoImpl(configuration)
  .then((result) => {
    console.log('Decoding of ' + contentType + ' is'
      + (result.supported ? '' : ' NOT') + ' supported,'
      + (result.smooth ? '' : ' NOT') + ' smooth and'
      + (result.powerEfficient ? '' : ' NOT') + ' power efficient');
  })
  .catch((err) => {
    console.error(err, ' caused decodingInfo to reject');
});

What is the minimum config to check HDR support?

Similar to Dolby support, you can use the Vega implementation to check for the connected TV’s or monitor’s capabilities for HDR support.

import {
    decodingInfo as decodingInfoImpl,
} from '@amazon-devices/react-native-w3cmedia';

// valid codecs parameter is must.
const contentType = 'video/webm;codecs=vp09.2.10.10.0.9.16.10.1';// profile 2, level 1, 10 bit depth, BT2020

const configuration = {
  type: 'media-source',
  video: {
    contentType: contentType,
    width: 640,
    height: 360,
    bitrate: 2000, // should be in bps
    framerate: 29.97,
    hdrMetadataType: "smpteSt2086" // for HDR10 and smpteSt2094-40 for HDR10+
  }
};

decodingInfoImpl(configuration)
  .then((result) => {
    console.log('Decoding of ' + contentType + ' is'
      + (result.supported ? '' : ' NOT') + ' supported,'
      + (result.smooth ? '' : ' NOT') + ' smooth and'
      + (result.powerEfficient ? '' : ' NOT') + ' power efficient');
  })
  .catch((err) => {
    console.error(err, ' caused decodingInfo to reject');
});

How to enable decodingInfo() on Dash.js?

Apps need to install the polyfill to provide the Vega implementation of decodingInfo() to Dash.js Player. The support for MediaCapabilities API is introduced in 4.0.0 release of Dash.js Player.Note: To use the decodingInfo() method instead of the isTypeSupported() method, make sure that the useMediaCapabilitiesApi is set to true.

How to enable on HLS.js player?

Apps need to install the polyfill to provide the Vega implementation of decodingInfo() to HLS.js player. The support for MediaCapabilities was introduced in 1.5.0-alpha release.Make sure that useMediaCapabilities is enabled in the HlsConfig.Note: The decodingInfo() method is used by HLS.js player only in specific scenarios mentioned in the mediacapabilities-helper.ts source file in HLS.js repo on GitHub.

Troubleshooting W3C Media Capabilities

The API depends on the “codecs” parameter of the MIME type to detect the profile, level, codec type, etc. In case of errors, check whether the value is passed appropriately. When players are not able to detect the MIME type, they might pass an invalid MIME (which doesn’t follow the MIME standard). This results in an error even if the actual content is supported by the device. Play adaptive content (HLS/DASH) with Shaka Player.

​W3C Media Capabilities prerequisites

​Install and setup W3C Media Capabilities

​How to use W3C Media Capabilities

​Apps that use ShakaPlayer

​Apps that use a JavaScript player which uses decodingInfo() internally

​Apps that use a JavaScript player which doesn’t depend on decodingInfo()

​FAQs

​Troubleshooting W3C Media Capabilities

​Related topics