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 the media is 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 they don’t deliver High Dynamic Range (HDR) content to a Standard Dynamic Range (SDR) screen. The World Wide Web Consortium (W3C) specification defines the decodingInfo method method that allows you to query the user agent to determine the audio and video decoding capabilities. The method allows you to determine whether the player supports the configuration and whether it expects the playback 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. For more information on how to install polyfill, see the Install and set up W3C Media Capabilities section.

W3C Media Capabilities prerequisites

The W3C API implements Media Capabilities as part of Vega SDK. Apps must add this API to their package.json as dependency to get the required imports.

Install and set up W3C Media Capabilities

Set up 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

Shaka Player provides a polyfill as part of the 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 that use `decodingInfo()` internally

Apps that use other players that 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 that doesn’t depend on `decodingInfo()`

Players such as Theo and Bitmovin use canPlayType or isTypeSupported instead of decodingInfo(). Apps 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';

// You must provide a valid codecs parameter.
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?

To use the Vega implementation of decodingInfo() to Dash.js Player, apps must install the polyfill. The 4.0.0 release of Dash.js Player introduces support for MediaCapabilities API.Note: To use the decodingInfo() method instead of the isTypeSupported() method, set useMediaCapabilitiesApi value to true.

How to enable on HLS.js player?

To use the Vega implementation of decodingInfo() to HLS.js player, apps must install the polyfill. The 1.5.0-alpha release of HLS.js player introduces support for the MediaCapabilities API.Make sure to enable useMediaCapabilities in HlsConfig.Note: HLS.js player uses the decodingInfo() method in the specific scenarios mentioned in the mediacapabilities-helper.ts source file in the 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 you passed the value 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 device supports the actual content. Play adaptive content (HLS/DASH) with Shaka Player.

​W3C Media Capabilities prerequisites

​Install and set up W3C Media Capabilities

​How to use W3C Media Capabilities

​Apps that use ShakaPlayer

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

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

​FAQs

​Troubleshooting W3C Media Capabilities

​Related topics