Amazon IVS Player SDK: Web Guide

The Amazon Interactive Video Service (IVS) Player SDK for Web can be integrated with player frameworks like Video.js or used standalone on top of an HTML <video> element.

Latest version of Web player: 1.17.0 (Release Notes)

Reference documentation: For information on the most important methods available in the Amazon IVS Web player, see the reference documentation at https://aws.github.io/amazon-ivs-player-docs/1.17.0/web/.

Getting Started

We provide support through a script tag as well as through an npm module.

Demo

The following live demo shows how to use the Web player with a script tag from our Content Delivery Network: Amazon IVS Player Sample.

Setup With Script Tag

To set up the Amazon IVS player using the script tag:

1. Include the following tag (for the latest version of the player).

   <script src="https://player.live-video.net/1.17.0/amazon-ivs-player.min.js">

2. Once amazon-ivs-player.min.js is loaded, it adds an IVSPlayer variable to the global context. This is the library you will use to create a player instance. First, check isPlayerSupported to determine if the browser supports the IVS player:

   if (IVSPlayer.isPlayerSupported) { ... }

   Then, to create a player instance, call the create function on the IVSPlayer object.

   const player = IVSPlayer.create();

   The Amazon IVS Player SDK for Web uses web workers to optimize video playback.

3. Load and play a stream using the load and play functions on the player instance:

   player.load("PLAYBACK_URL");
   player.play();

   where PLAYBACK_URL is the URL returned from the Amazon IVS API when a stream key is requested.

Sample Code

In this example, replace PLAYBACK_URL with the URL of the source stream you want to load. The example uses the latest version of the Amazon IVS player.

<script src="https://player.live-video.net/1.17.0/amazon-ivs-player.min.js"></script>
<video id="video-player" playsinline></video>
<script>
  if (IVSPlayer.isPlayerSupported) {
    const player = IVSPlayer.create();
    player.attachHTMLVideoElement(document.getElementById('video-player'));
    player.load("PLAYBACK_URL");
    player.play();
  }
</script>

In the <video> tag, playsinline is required for inline playback on iOS Safari. See https://webkit.org/blog/6784/new-video-policies-for-ios/.

Setup With NPM

For guidance, including an example Webpack configuration file, see the following repository: https://github.com/aws-samples/amazon-ivs-player-web-sample.

Note: When hosting player static assets from your own domain, you must set the "Content-Type" response header for the WebAssembly binary (amazon-ivs-wasmworker.min.wasm) to "application/wasm." You also should gzip your assets to reduce bytes downloaded over the wire and improve the player’s time to start playback.

TypeScript

If you’re using TypeScript, the npm package includes types you may want to import and use. For information on these types, see the Amazon IVS Player SDK: Web Reference.

Framework Integrations

The Amazon IVS Player SDK for Web is designed to be easy to integrate with your framework of choice. We offer an official Video.js integration (“tech,” in Video.js jargon).

The following is a brief comparison of the Web players we offer:

Player Type	Description	UI	Plugins
Amazon IVS Player SDK for Web	A lightweight and customizable option for developers who want more control.	No	No
Amazon IVS Player Tech for Video.js	A full-featured option, which may be appropriate if you already use Video.js and want a turnkey solution.	Yes (Video.js Skins)	Yes (Video.js Plugins)
Amazon IVS Player Provider for JW Player	A full-featured option, which may be appropriate if you already use JW Player and want a turnkey solution.	Yes	N/A

Working With Content Security Policy

The Amazon IVS Web player SDK is configured to work on pages that use Content Security Policy (CSP). A few key CSP directives must be in place. Here, we describe a minimal set of directives that are necessary. Additional directives and sources are likely necessary, depending on your specific setup.

The following directives are the minimum required for CSP:

worker-src blob:;
media-src blob:;
connect-src *.live-video.net;
script-src 'wasm-unsafe-eval';

Note: Older versions of browsers may not recognize one or more of those above CSP rules (such as wasm-unsafe-eval) and instead could require a very lenient CSP policy (unsafe-eval). However, that works against the whole point of CSP to limit dangerous JavaScript from running on a page. Instead, as a workaround, we recommend that you host the library assets on the same origin as your page.

Known Issues and Workarounds

Please report all issues to Amazon IVS Support.

• When playing recorded content (also known as VOD) on an iOS mobile browser (e.g. Safari or Chrome), seeking backwards will mute the player.

  Workaround: Call player.setMuted(false) after seeking.

• When playing recorded content on an iOS mobile browser, seeking backwards works intermittently when directly selecting the desired position.

  Workaround: Drag the seek bar to the desired position.

• When playing recorded content on an iOS mobile browser, player.seekTo() calls do not consistently work.

  Workaround: Set currentTime on the video HTML element after the loadeddata event. For example:

  videoEl.addEventListener('loadeddata', () => {
  	videoEl.currentTime = 30; // seek 30s from the beginning
  });

• When playing a live stream or recorded content on an iOS mobile browser, captions may not be rendered in different sizes and may be re-rendered multiple times.

  Workaround: None.

• When playing a live stream or recorded content on an iOS mobile browser, player.getQualities() calls do not return the list of available qualities.

  Workaround: None. The player supports only auto-quality mode on iOS browsers.

• When playing a live stream or recorded content on an iOS mobile browser, player.getLiveLatency() calls return 0.

  Workaround: None.

• When native HTML5 controls are enabled, calls to setQuality() are ignored.

  Workaround: Disable HTML5 controls before calling player.setQuality().

• When playing a muted live stream on an iOS mobile browser, player instability (e.g., black or frozen screen, buffering) may be seen when resuming an inactive player tab (e.g., tab switches or device lock/unlock).

  Workaround: Use the JavaScript Page Visibility API to detect page visibility changes and then take action on the player accordingly. For example:

  //if client platform is iOS
  if (!!navigator.platform && /iPad|iPhone|iPod/.test(navigator.platform)) {
      document.addEventListener(“visibilitychange”, () => {
          if (document.visibilityState === “hidden” && player.isMuted()) {
              player.pause()
          if (document.visibilityState === “visible” &&
              player.getState() != PlayerState.PLAYING) {
              player.play()
          }
      })
  }