How to use the Shaka player with Azure Media Services

  • Artikel
  • 4 minit untuk dibaca

media services logo v3

Looking for Media Services v2 documentation?
Having trouble? See the Troubleshooting guide for solutions to issues with using Media Services.
Code samples can be found on the Samples page.

Overview

Shaka Player is an open-source JavaScript library for adaptive media. It plays adaptive media formats (such as DASH and HLS) in a browser, without using plugins or Flash. Instead, the Shaka Player uses the open web standards Media Source Extensions and Encrypted Media Extensions.

Official documentation can be found at Shaka player documentation.

Sample code

Sample code for this article is available at Azure-Samples/media-services-3rdparty-player-samples.

Implementing the player

Follow these instructions if you need to implement your own instance of the player:

  1. Create an index.html file where you'll host the player. You should check to confirm that the latest version of the CDN hosted Shaka player is being used or compile your own version from the Github repo (as of this publishing we are using version 3.3.2). Add the following lines of code (you can replace the versions for newer if applicable):

    <html>
  <head>
    <script src="//cdn.jsdelivr.net/npm/shaka-player@3.3.2/dist/shaka-player.compiled.min.js"></script>
    <script type="module" src="index.js"></script>
  </head>
  <body>
    <video id="video" controls></video>
  </body>
</html>

  2. Add a JavaScript file with the following code:

    // myScript.js
shaka.polyfill.installAll();

var video = document.getElementById('video');
var player = new shaka.Player(video);
window.player = player;

var manifestUrl = '//amssamples.streaming.mediaservices.windows.net/55034fb3-11af-43e4-a4de-d1b3ca56c5aa/ElephantsDream_MultiAudio.ism/manifest(format=m3u8-cmaf)';    

player.load(manifestUrl);

  3. Replace manifestUrl with the HLS CMAF or DASH CMAF URL from the streaming locator of your asset, which can be found on the streaming locator page in the Azure portal. For HLS, use the format=m3u8-cmaf manifest.

  4. Run a server (for example with npm http-server) and your player should be working...

Set up captions

Set up VOD captions

Run the following lines of code, and replace captionUrl with your .vtt directory (vtt file needs to be in the same host to avoid CORS error), lang with the two letter code for language, and type with either caption or subtitle:

player.configure('streaming.alwaysStreamText', true)
player.load(manifestUrl).then(function(){
        player.addTextTrack(captionUrl, lang, type, 'text/vtt');
        var tracks = player.getTextTracks();
        player.selectTextTrack(tracks[0]);
});

Set up live stream captions

Enable captions in live stream is configured adding the following line of code:

player.setTextTrackVisibility(true)

Set up token authentication

Run the following lines of code, and replace token with your token string:

player.getNetworkingEngine().registerRequestFilter(function (type, request) {
  if (type === shaka.net.NetworkingEngine.RequestType.LICENSE) {
    request.headers['Authorization'] = 'Bearer ' + token;
  }
});

Set up AES-128 encryption

Shaka Player doesn't currently support the format of AES-128 encryption that is delivered by Azure Media Services. Check back on updates as there is ongoing work to support the Common Encryption Clear-key format with both CTR and CBC encryption modes to allow for playback of AES-128 ClearKey content in the Shaka player.

A link to a GitHub issue to follow the status of this feature. It is currently closed as resolved, but work is ongoing to support this format in the future on both Media Services and Shaka player.

Set up DRM protection

Shaka Player uses Encrypted Media Extensions (EME), which requires a secure URL to use. So, for testing any DRM protected content it's necessary to use https. If the site is using https, then the manifest and every segment will also need to use https. This is because of mixed content requirements.

The order of preference for Shaka management of the URL(s) of its license server(s):

  1. ClearKey config, used for debugging, should override everything else. (The application can still specify a ClearKey license server.)
  2. Application-configured servers, if any are present, should override anything from the manifest.
  3. Manifest-provided license servers are only used if nothing else is specified.

To specify the license server URL for Widevine or PlayReady, we can use the following code:

player.configure({
  drm: {
    servers: {
      "com.widevine.alpha": "YOUR WIDEVINE LICENSE URL",
      "com.microsoft.playready": "YOUR PLAYREADY LICENSE URL"
    }
  }
});

All FairPlay content requires setting a server certificate. It is set in the Player configuration:

const req = await fetch("YOUR FAIRPLAY CERTIFICATE URL");
const cert = await req.arrayBuffer();
player.configure('drm.advanced.com\\.apple\\.fps\\.1_0.serverCertificate', new Uint8Array(cert));

For more information, see Shaka player DRM protection documentation.

Security considerations for closed captions, subtitles, and timed-metadata delivery

The dynamic encryption and DRM features of Azure Media Services has limits to consider when attempting to secure content delivery that includes live transcriptions, captions, subtitles, or timed-metadata. The DRM subsystems, including PlayReady, FairPlay, and Widevine do not support the encryption and licensing of text tracks. The lack of DRM encryption for text tracks limits your ability to secure the contents of live transcriptions, manual inserted captions, uploaded subtitles, or timed-metadata signals that may be inserted as separate tracks.

To secure your captions, subtitles, or timed-metadata tracks, it is recommended to follow one of the guidelines:

  1. Use AES-128 Clear Key encryption. When enabling AES-128 clear key encryption, the text tracks can be configured to be encrypted using a full "envelope" encryption technique that follows the same encryption pattern as the audio and video segments. These segments can then be decrypted by a client application after requesting the decryption key from the Media Services Key Delivery service using an authenticated JWT token. This method is supported by the Azure Media Player, but may not be supported on all devices and can require some client-side development work to make sure it succeeds on all platforms.
  2. Use CDN token authentication to protect the text (subtitle, captions, metadata) tracks being delivered with short form tokenized URLs that are restricted to geo, IP, or other configurable settings in the CDN portal. Enable the CDN security features using Verizon Premium CDN or other 3rd-party CDN configured to connect to your Media Services streaming endpoints.

Warning

If you do not follow one of the guidelines above, your subtitles, captions, or timed-metadata text will be accessible as un-encrypted content that could be intercepted or shared outside of your intended client delivery path. This can result in leaked information. If you are concerned about the contents of the captions or subtitles being leaked in a secure delivery scenario, reach out to the Media Services support team for more information on the above guidelines for securing your content delivery.