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:
-
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">
-
Once
amazon-ivs-player.min.js
is loaded, it adds anIVSPlayer
variable to the global context. This is the library you will use to create a player instance. First, checkisPlayerSupported
to determine if the browser supports the IVS player:if (IVSPlayer.isPlayerSupported) { ... }
Then, to create a player instance, call the
create
function on theIVSPlayer
object.const player = IVSPlayer.create();
The Amazon IVS Player SDK for Web uses web workers to optimize video playback.
-
Load and play a stream using the
load
andplay
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 | Yes |
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 theloadeddata
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() } }) }