# Kinesis Video Streams playback Video playback You can view a Kinesis video stream using the following methods: + **GetMedia** – You can use the `GetMedia` API to build your own applications to process Kinesis Video Streams. `GetMedia` is a real-time API with low latency. To create a player that uses `GetMedia`, you must build it yourself. For information about how to develop an application that displays a Kinesis video stream using `GetMedia`, see [Stream using parser library](parser-library.md). + **HLS** – [HTTP Live Streaming (HLS)](https://en.wikipedia.org/wiki/HTTP_Live_Streaming) is an industry standard HTTP-based media streaming communications protocol. You can use HLS to view a Kinesis video stream, either for live playback or to view archived video. You can use HLS for live playback. Latency is typically between 3–5 seconds, but it can be between 1–10 seconds, depending on the use case, player, and network conditions. You can use a third-party player (such as [Video.js](https://github.com/videojs/video.js/) or [Google Shaka Player](https://github.com/google/shaka-player)) to display the video stream by providing the HLS streaming session URL, either programmatically or manually. You can also play back video by entering the HLS streaming session URL in the **Location** bar of the [Apple Safari](https://www.apple.com/safari/) or [Microsoft Edge](https://www.microsoft.com/en-us/edge) browsers. + **MPEG-DASH** – [Dynamic Adaptive Streaming over HTTP (DASH)](https://en.wikipedia.org/wiki/Dynamic_Adaptive_Streaming_over_HTTP), also known as MPEG-DASH, is an adaptive bitrate streaming protocol that enables high quality streaming of media content over the internet delivered from conventional HTTP web servers. You can use MPEG-DASH for live playback. Latency is typically between 3–5 seconds, but it can be between 1–10 seconds, depending on the use case, player, and network conditions. You can use a third-party player (such as [dash.js](https://github.com/Dash-Industry-Forum/dash.js/wiki) or [Google Shaka Player](https://github.com/google/shaka-player)) to display the video stream by providing the MPEG-DASH streaming session URL, either programmatically or manually. + **GetClip** – You can use the `GetClip` API to download a clip (in an MP4 file) containing the archived, on-demand media from the specified video stream over the specified time range. For more information, see the [GetClip](https://docs.aws.amazon.com//kinesisvideostreams/latest/dg/API_reader_GetClip.html) API Reference. **Topics** + [ # Video playback track requirements ](video-playback-requirements.md) + [ # Video playback with HLS ](hls-playback.md) + [ # Video playback with MPEG-DASH ](dash-playback.md) # Video playback track requirements Playback requirements Amazon Kinesis Video Streams supports media encoded in multiple formats. If your Kinesis video stream uses a format not supported by one of the four APIs listed below, use [https://docs.aws.amazon.com//kinesisvideostreams/latest/dg/API_dataplane_GetMedia.html](https://docs.aws.amazon.com//kinesisvideostreams/latest/dg/API_dataplane_GetMedia.html) or [https://docs.aws.amazon.com//kinesisvideostreams/latest/dg/API_reader_GetMediaForFragmentList.html](https://docs.aws.amazon.com//kinesisvideostreams/latest/dg/API_reader_GetMediaForFragmentList.html), as they don't have track-type limitations. **Topics** + [ ## GetClip requirements ](#requirements-getclip) + [ ## GetDASHStreamingSessionURL requirements ](#requirements-getdash) + [ ## GetHLSStreamingSessionURL requirements ](#requirements-gethls) + [ ## GetImages requirements ](#requirements-getimages) ## GetClip requirements GetClip For more information about this API, see [https://docs.aws.amazon.com//kinesisvideostreams/latest/dg/API_reader_GetClip.html](https://docs.aws.amazon.com//kinesisvideostreams/latest/dg/API_reader_GetClip.html). | Track 1 description | Track 1 codec ID | Track 2 description | Track 2 codec ID | | --- | --- | --- | --- | | H.264 video | V\$1MPEG4/ISO/AVC | N/A | N/A | | H.264 video | V\$1MPEG4/ISO/AVC | AAC audio | A\$1AAC | | H.264 video | V\$1MPEG4/ISO/AVC | G.711 audio (A-Law only) | A\$1MS/ACM | | H.265 video | V\$1MPEGH/ISO/HEVC | N/A | N/A | | H.265 video | V\$1MPEGH/ISO/HEVC | AAC audio | A\$1AAC | **Important** The codec private data (CPD) contained in each fragment contains codec-specific initialization information, such as frame rate, resolution, and encoding profile, which are necessary to properly decode the fragment. CPD changes aren't supported between the target fragments of the resulting clip. The CPD must remain consistent through the queried media, otherwise an error will be returned. **Important** Track changes aren't supported. Tracks must remain consistent throughout the queried media. An error is returned if the fragments in the stream change from having only video to having both audio and video, or if an AAC audio track is changed to an A-Law audio track. ## GetDASHStreamingSessionURL requirements GetDASHStreamingSessionURL For more information about this API, see [https://docs.aws.amazon.com//kinesisvideostreams/latest/dg/API_reader_GetDASHStreamingSessionURL.html](https://docs.aws.amazon.com//kinesisvideostreams/latest/dg/API_reader_GetDASHStreamingSessionURL.html). | Track 1 description | Track 1 codec ID | Track 2 description | Track 2 codec ID | | --- | --- | --- | --- | | H.264 video | V\$1MPEG4/ISO/AVC | N/A | N/A | | H.264 video | V\$1MPEG4/ISO/AVC | AAC audio | A\$1AAC | | H.264 video | V\$1MPEG4/ISO/AVC | G.711 audio (A-Law only) | A\$1MS/ACM | | H.264 video | V\$1MPEG4/ISO/AVC | G.711 audio (U-Law only) | A\$1MS/ACM | | AAC audio | A\$1AAC | N/A | N/A | | H.265 video | V\$1MPEGH/ISO/HEVC | N/A | N/A | | H.265 video | V\$1MPEGH/ISO/HEVC | AAC audio | A\$1AAC | **Important** The codec private data (CPD) contained in each fragment contains codec-specific initialization information, such as frame rate, resolution, and encoding profile, which are necessary to properly decode the fragment. CPD changes aren't supported during a streaming session. The CPD must remain consistent through the queried media. **Important** Track changes aren't supported. Tracks must remain consistent throughout the queried media. Streaming will fail if the fragments in the stream change from having only video to having both audio and video, or if an AAC audio track is changed to an A-Law audio track. ## GetHLSStreamingSessionURL requirements GetHLSStreamingSessionURL For more information about this API, see [https://docs.aws.amazon.com//kinesisvideostreams/latest/dg/API_reader_GetHLSStreamingSessionURL.html](https://docs.aws.amazon.com//kinesisvideostreams/latest/dg/API_reader_GetHLSStreamingSessionURL.html). **HLS Mp4** | Track 1 description | Track 1 codec ID | Track 2 description | Track 2 codec ID | | --- | --- | --- | --- | | H.264 video | V\$1MPEG4/ISO/AVC | N/A | N/A | | H.264 video | V\$1MPEG4/ISO/AVC | AAC audio | A\$1AAC | | AAC audio | A\$1AAC | N/A | N/A | | H.265 video | V\$1MPEGH/ISO/HEVC | N/A | N/A | | H.265 video | V\$1MPEGH/ISO/HEVC | AAC audio | A\$1AAC | **HLS TS** | Track 1 description | Track 1 codec ID | Track 2 description | Track 2 codec ID | | --- | --- | --- | --- | | H.264 video | V\$1MPEG4/ISO/AVC | N/A | N/A | | H.264 video | V\$1MPEG4/ISO/AVC | AAC audio | A\$1AAC | | AAC audio | A\$1AAC | N/A | N/A | **Note** The codec private data (CPD) contained in each fragment contains codec-specific initialization information, such as frame rate, resolution, and encoding profile, which are necessary to properly decode the fragment. For both TS and MP4, CPD changes are supported during a streaming session. Therefore, the fragments in a session can have a different information in the CPD without interrupting playback. For each streaming session, only 500 CPD changes are allowed. **Important** Track changes aren't supported. Tracks must remain consistent throughout the queried media. Streaming will fail if the fragments in the stream change from having only video to having both audio and video, or if an AAC audio track is changed to an A-Law audio track. ## GetImages requirements GetImages For more information about this API, see [https://docs.aws.amazon.com//kinesisvideostreams/latest/dg/API_reader_GetImages.html](https://docs.aws.amazon.com//kinesisvideostreams/latest/dg/API_reader_GetImages.html). **Note** The `GetImages` media should contain a video track in track 1. # Video playback with HLS Playback with HLS [HTTP Live Streaming (HLS)](https://en.wikipedia.org/wiki/HTTP_Live_Streaming) is an industry standard HTTP-based media streaming communications protocol. You can use HLS to view a Kinesis video stream, either for live playback or to view archived video. You can use HLS for live playback. Latency is typically between 3–5 seconds, but it can be between 1–10 seconds, depending on the use case, player, and network conditions. You can use a third-party player (such as [Video.js](https://github.com/videojs/video.js/) or [Google Shaka Player](https://github.com/google/shaka-player)) to display the video stream by providing the HLS streaming session URL, either programmatically or manually. You can also play back video by entering the HLS streaming session URL in the Location bar of the [Apple Safari](https://www.apple.com/safari/) or [Microsoft Edge](https://www.microsoft.com/en-us/edge) browsers. To view a Kinesis video stream using HLS, first create a streaming session using [GetHLSStreamingSessionURL](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/API_reader_GetHLSStreamingSessionURL.html). This action returns a URL (containing a session token) for accessing the HLS session. You can then use the URL in a media player or a standalone application to display the stream. **Important** Not all media sent to Kinesis Video Streams can be played back through HLS. See [GetHLSStreamingSessionURL](API_reader_GetHLSStreamingSessionURL.md) for specific uploading requirements. **Topics** + [ ## Use the AWS CLI to retrieve an HLS streaming session URL ](#retrieve-hls-url) + [ ## Example: Use HLS in HTML and JavaScript ](#how-hls-ex1) + [ ## Troubleshooting HLS issues ](#how-hls-ex1-ts) ## Use the AWS CLI to retrieve an HLS streaming session URL The following procedure demonstrates how to use the AWS CLI to generate an HLS streaming session URL for a Kinesis video stream. For installation instructions, see the [AWS Command Line Interface User Guide](https://docs.aws.amazon.com//cli/latest/userguide/getting-started-install.html#getting-started-install-instructions). After installation, [configure the AWS CLI](https://docs.aws.amazon.com//cli/latest/userguide/getting-started-quickstart.html#getting-started-quickstart-new) with credentials and region. Alternatively, open the AWS CloudShell terminal, which has the AWS CLI installed and configured. See the [AWS CloudShell User Guide](https://docs.aws.amazon.com//cloudshell/latest/userguide/welcome.html#how-to-get-started) for more information. **Retrieve the HLS URL endpoint for your Kinesis video stream.** 1. Type the following into the terminal: ``` aws kinesisvideo get-data-endpoint \ --api-name GET_HLS_STREAMING_SESSION_URL \ --stream-name YourStreamName ``` You'll receive a response that looks like this: ``` { "DataEndpoint": "https://b-1234abcd.kinesisvideo.aws-region.amazonaws.com" } ``` 1. Make the HLS streaming session URL request to that returned endpoint. ------ #### [ Live ] For live playback, the HLS media playlist is continually updated with the latest media as it becomes available. When you play this type of session in a media player, the user interface typically displays a "**live**" notification, with no scrubber control for choosing the position in the playback window to display. Make sure that you are uploading media to this stream when you run this command. ``` aws kinesis-video-archived-media get-hls-streaming-session-url \ --endpoint-url https://b-1234abcd.kinesisvideo.aws-region.amazonaws.com \ --stream-name YourStreamName \ --playback-mode LIVE ``` ------ #### [ Live replay ] For live replay, playback starts from a specified start time. The HLS media playlist is also continually updated with the latest media as it becomes available. The session will continue to include newly ingested media until the session expires, or until the specified end time, whichever comes first. This mode is useful to be able to start playback from when an event is detected and continue live streaming media that has not yet been ingested as of the time of the session creation. Determine a start timestamp. For this example, we use the **Unix Epoch time in seconds** format. Refer to the [Timestamps](https://docs.aws.amazon.com//cli/latest/userguide/cli-usage-parameters-types.html#parameter-type-timestamp) section in the AWS Command Line Interface User Guide for more information on timestamp formatting. See [UnixTime.org](https://unixtime.org/) for a conversion tool. + **1708471800** is equal to **February 20, 2024 3:30:00 PM GMT-08:00** In this example, we don't specify an end timestamp, meaning that the session will continue to include newly ingested media until the session expires. Invoke the `GetHLSStreamingSessionURL` API with `LIVE_REPLAY` playback mode and an [HLS Fragment Selector](https://docs.aws.amazon.com//kinesisvideostreams/latest/dg/API_reader_GetHLSStreamingSessionURL.html#KinesisVideo-reader_GetHLSStreamingSessionURL-request-HLSFragmentSelector) specified. ``` aws kinesis-video-archived-media get-hls-streaming-session-url \ --endpoint-url https://b-1234abcd.kinesisvideo.aws-region.amazonaws.com \ --stream-name YourStreamName \ --playback-mode LIVE_REPLAY \ --hls-fragment-selector \ "FragmentSelectorType=SERVER_TIMESTAMP,TimestampRange={StartTimestamp=1708471800}" ``` ------ #### [ On-demand ] For on demand playback, the HLS media playlist contains the media specified by the HLS fragment selector. When this type of session is played in a media player, the user interface typically displays a scrubber control for choosing the position in the playback window to display. To create a URL for a certain section of stream, first determine start and end timestamps. For this example, we use the **Unix Epoch time in seconds** format. Refer to the [Timestamps](https://docs.aws.amazon.com//cli/latest/userguide/cli-usage-parameters-types.html#parameter-type-timestamp) section in the AWS Command Line Interface User Guide for more information on timestamp formatting. See [UnixTime.org](https://unixtime.org/) for a conversion tool. + **1708471800** is equal to **February 20, 2024 3:30:00 PM GMT-08:00** + **1708471860** is equal to **February 20, 2024 3:31:00 PM GMT-08:00** Invoke the `GetHLSStreamingSessionURL` API with `ON_DEMAND` playback mode and an [HLS Fragment Selector](https://docs.aws.amazon.com//kinesisvideostreams/latest/dg/API_reader_GetHLSStreamingSessionURL.html#KinesisVideo-reader_GetHLSStreamingSessionURL-request-HLSFragmentSelector) specified. ``` aws kinesis-video-archived-media get-hls-streaming-session-url \ --endpoint-url https://b-1234abcd.kinesisvideo.aws-region.amazonaws.com \ --stream-name YourStreamName \ --playback-mode ON_DEMAND \ --hls-fragment-selector \ "FragmentSelectorType=SERVER_TIMESTAMP,TimestampRange={StartTimestamp=1708471800,EndTimestamp=1708471860}" ``` **Note** The timestamps must be within 24-hours of each other, as mentioned in the [HLSTimestampRange](API_reader_HLSTimestampRange.md) documentation. ------ You'll receive a response that looks like this: ``` { "HLSStreamingSessionURL": "https://b-1234abcd.kinesisvideo.aws-region.amazonaws.com/hls/v1/getHLSMasterPlaylist.m3u8?SessionToken=CiAz...DkRE6M~" } ``` **Important** Don't share or store this token where an unauthorized entity could access it. The token provides access to the content of the stream. Safeguard the token with the same measures that you would use with your AWS credentials. You can use this URL and any HLS player to view the HLS stream. For example, use VLC media player. You can also play the HLS Stream by entering the HLS streaming session URL in the Location bar of the Apple Safari or Microsoft Edge browsers. ## Example: Use HLS in HTML and JavaScript The following example shows how to use the AWS SDK for JavaScript v2 to retrieve an HLS streaming session for a Kinesis video stream and play it back in a web page. The example shows how to play back video in the following players: + [Video.js](https://github.com/videojs/video.js/) + [Google Shaka Player](https://github.com/google/shaka-player) + [hls.js](https://github.com/video-dev/hls.js/) View the [complete example code](https://github.com/aws-samples/amazon-kinesis-video-streams-media-viewer) and [hosted web page](https://aws-samples.github.io/amazon-kinesis-video-streams-media-viewer/) in GitHub. This static webpage simplifies testing and experimenting with HLS and MPEG-DASH output from Amazon Kinesis video stream. The example page provides input fields for the following parameters: + AWS Region: The Region where your Kinesis video stream is located + Stream name: The name of your Kinesis video stream + Playback mode: The HLS playback mode (LIVE, LIVE\$1REPLAY, or ON\$1DEMAND) + Fragment selector type: The method used to select fragments (SERVER\$1TIMESTAMP or PRODUCER\$1TIMESTAMP) + Fragment number: The starting fragment number (when applicable) + Container format: The format of the media container (FRAGMENTED\$1MP4 or MPEG\$1TS) The application retrieves these values from the input boxes on the HTML page and uses them to construct the request for an HLS streaming session that displays on the page. **Topics** + [ ### Import the AWS SDK for JavaScript for browsers ](#how-hls-ex1-import) + [ ### Set up the Kinesis Video Streams client ](#how-hls-ex1-setup) + [ ### Retrieve the endpoint for HLS playback ](#how-hls-ex1-endpoint) + [ ### Set up the Kinesis Video Streams archived media client ](#how-hls-ex1-session) + [ ### Retrieve the HLS streaming session URL ](#how-hls-ex1-retrieve-url) + [ ### Display the HLS stream on the web page ](#how-hls-ex1-display) ### Import the AWS SDK for JavaScript for browsers In the web page, include the following script tag to import the AWS SDK for JavaScript v2 into the project. ``` ``` For more information, refer to the [AWS SDK for JavaScript](https://docs.aws.amazon.com//sdk-for-javascript/v2/developer-guide/loading-the-jssdk.html) documentation. ### Set up the Kinesis Video Streams client To access streaming video with HLS, first create and configure the Kinesis Video Streams client. See [Setting Credentials in a Web Browser](https://docs.aws.amazon.com//sdk-for-javascript/v2/developer-guide/setting-credentials-browser.html) for other authentication methods. ``` const clientConfig = { accessKeyId: 'YourAccessKey', secretAccessKey: 'YourSecretKey', region: 'us-west-2' }; const kinesisVideoClient = new AWS.KinesisVideo(clientConfig); ``` The application retrieves the necessary values from input boxes on the HTML page. ### Retrieve the endpoint for HLS playback Use the Kinesis Video Streams client to invoke the [GetDataEndpoint](API_GetDataEndpoint.md) API to retrieve the endpoint. ``` const getDataEndpointOptions = { StreamName: 'YourStreamName', APIName: 'GET_HLS_STREAMING_SESSION_URL' }; const getDataEndpointResponse = await kinesisVideoClient .getDataEndpoint(getDataEndpointOptions) .promise(); const hlsDataEndpoint = getDataEndpointResponse.DataEndpoint; ``` This code stores the endpoint in the `hlsDataEndpoint` variable. ### Set up the Kinesis Video Streams archived media client In the client configuration for the Kinesis Video Streams archived media client, specify the endpoint that you obtained in the previous step. ``` const archivedMediaClientConfig = { accessKeyId: 'YourAccessKey', secretAccessKey: 'YourSecretKey', region: 'us-west-2', endpoint: hlsDataEndpoint }; const kinesisVideoArchivedMediaClient = new AWS.KinesisVideoArchivedMedia(archivedMediaClientConfig); ``` ### Retrieve the HLS streaming session URL Use the Kinesis Video Streams archived media client to invoke the [GetHLSStreamingSessionURL](API_reader_GetHLSStreamingSessionURL.md) API to retrieve the HLS playback URL. ``` const getHLSStreamingSessionURLOptions = { StreamName: 'YourStreamName', PlaybackMode: 'LIVE' }; const getHLSStreamingSessionURLResponse = await kinesisVideoArchivedMediaClient .getHLSStreamingSessionURL(getHLSStreamingSessionURLOptions) .promise(); const hlsUrl = getHLSStreamingSessionURLResponse.HLSStreamingSessionURL; ``` ### Display the HLS stream on the web page When you have the HLS streaming session URL, provide it to the video player. The method for providing the URL to the video player is specific to the player used. ------ #### [ Video.js ] Do the following to import [Video.js](https://github.com/videojs/video.js/) and its CSS classes into our browser script: ``` ``` Create a `video` HTML element to display the video: ``` ``` Set the HLS URL as the HTML video element source: ``` const playerElement = document.getElementById('videojs'); const player = videojs(playerElement); player.src({ src: hlsUrl, type: 'application/x-mpegURL' }); player.play(); ``` ------ #### [ Shaka ] Do the following to import the [Google Shaka player](https://github.com/shaka-project/shaka-player) into our browser script: ``` ``` Create a `video` HTML element to display the video: ``` ``` Create a Shaka player specifying the video element and call the load method: ``` const playerElement = document.getElementById('shaka'); const player = new shaka.Player(playerElement); player.load(hlsUrl); ``` ------ #### [ hls.js ] Do the following to import [hls.js](https://github.com/video-dev/hls.js/) into our browser script: ``` ``` Create a `video` HTML element to display the video: ``` ``` Create an hls.js player, give it the HLS URL, and tell it to play: ``` const playerElement = document.getElementById('hlsjs'); const player = new Hls(); player.loadSource(hlsUrl); player.attachMedia(playerElement); player.on(Hls.Events.MANIFEST_PARSED, function() { video.play(); }); ``` ------ ## Troubleshooting HLS issues This section describes issues that you might encounter when using HTTP Live Streaming (HLS) with Kinesis Video Streams. **Topics** + [ ### Retrieving HLS streaming session URL succeeds, but playback fails in video player ](#troubleshooting-hls-playback) + [ ### Latency too high between producer and player ](#troubleshooting-hls-latency) ### Retrieving HLS streaming session URL succeeds, but playback fails in video player This situation occurs when you can successfully retrieve an HLS streaming session URL using `GetHLSStreamingSessionURL`, but the video fails to play back when the URL is provided to a video player. To troubleshoot this situation, try the following: + Determine whether the video stream plays back in the Kinesis Video Streams console. Consider any errors that the console shows. + If the fragment duration is less than one second, increase it to one second. If the fragment duration is too short, the service might throttle the player because it's making requests for video fragments too frequently. + Verify that each HLS streaming session URL is being used by only one player. If more than one player is using a single HLS streaming session URL, the service might receive too many requests and throttle them. + Verify that your player supports all of the options that you're specifying for the HLS streaming session. Try different combinations of values for the following parameters: + `ContainerFormat` + `PlaybackMode` + `FragmentSelectorType` + `DiscontinuityMode` + `MaxMediaPlaylistFragmentResults` Some media players (like HTML5 and mobile players) typically only support HLS with the fMP4 container format. Other media players (like Flash and custom players) might only support HLS with the MPEG TS container format. We recommend experimenting with the `ContainerFormat` parameter to start troubleshooting. + Verify that each fragment has a consistent number of tracks. Verify that fragments in the stream are not changing between having both an audio and video track and only a video track. Also verify that the encoder settings (resolution and frame rate) are not changing between fragments in each track. ### Latency too high between producer and player This situation occurs when the latency is too high from when the video is captured to when it is played in the video player. Video is played back through HLS on a per-fragment basis. Therefore, latency can't be less than fragment duration. Latency also includes the time needed for buffering and transferring data. If your solution requires latency of less than one second, consider using the `GetMedia` API instead. You can adjust the following parameters to reduce the overall latency, but adjusting these parameters might also reduce the video quality or increase the rebuffering rate. + **Fragment duration** – The fragment duration is the amount of video between divisions in the stream as controlled by the frequency of keyframes generated by the video encoder. The recommended value is one second. Having a shorter fragment duration means that less time is spent waiting for the fragment to complete before transmitting the video data to the service. Shorter fragments are also faster for the service to process. However, if the fragment duration is too short, the probability increases that the player will run out of content and have to stop and buffer content. If the fragment duration is less than 500 milliseconds, the producer might create too many requests, causing the service to throttle them. + **Bitrate** – A video stream with a lower bitrate takes less time to read, write, and transmit. However, a video stream with a lower bitrate usually has a lower video quality. + **Fragment count in media playlists** – A latency-sensitive player should only load the newest fragments in a media playlist. Most players start at the earliest fragment instead. By reducing the number of fragments in the playlist, you reduce the time separation between the previous and new fragments. With a smaller playlist size, it's possible for a fragment to be skipped during playback if there's a delay in adding new fragments to the playlist, or if there's a delay in the player getting an updated playlist. We recommend using 3–5 fragments, and to use a player that's configured to load only the newest fragments from a playlist. + **Player buffer size** – Most video players have a configurable minimum buffer duration, usually with a 10-second default. For the lowest latency, you can set this value to 0 seconds. However, doing so means that the player rebuffers if there's any delay producing fragments because the player will have no buffer for absorbing the delay. + **Player "catch up"** – Video players typically don't automatically catch playback up to the front of the video buffer if the buffer fills up, like when a delayed fragment causes a backlog of fragments to play. A custom player can avoid this by either dropping frames, or increasing the playback speed (for example, to 1.1x) to catch up to the front of the buffer. This causes playback to be choppy or increase in speed as the player catches up, and rebuffering might be more frequent as the buffer size is kept short. # Video playback with MPEG-DASH Playback with MPEG-DASH To view a Kinesis video stream using MPEG-DASH, you first create a streaming session using [GetDASHStreamingSessionURL](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/API_reader_GetDASHStreamingSessionURL.html). This action returns a URL (containing a session token) for accessing the MPEG-DASH session. You can then use the URL in a media player or a standalone application to display the stream. An Amazon Kinesis video stream has the following requirements for providing video through MPEG-DASH: + For streaming video playback track requirements, see [GetDASHStreamingSessionURL requirements](video-playback-requirements.md#requirements-getdash). + Data retention must be greater than 0. + The video track of each fragment must contain codec private data in the Advanced Video Coding (AVC) for H.264 format and HEVC for H.265 format. For more information, see [MPEG-4 specification ISO/IEC 14496-15](https://www.iso.org/standard/55980.html). For information about adapting stream data to a given format, see [NAL Adaptation Flags](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/producer-reference-nal.html). + The audio track (if present) of each fragment must contain codec private data in the AAC format ([AAC specification ISO/IEC 13818-7](https://www.iso.org/standard/43345.html)) or the [MS Wave format](https://www-mmsp.ece.mcgill.ca/Documents/AudioFormats/WAVE/WAVE.html). ## Example: Using MPEG-DASH in HTML and JavaScript The following example shows how to retrieve an MPEG-DASH streaming session for a Kinesis video stream and play it back in a webpage. The example shows how to play back video in the following players: + [Google Shaka Player](https://github.com/google/shaka-player) + [dash.js](https://github.com/Dash-Industry-Forum/dash.js/wiki) **Topics** + [ ### Set up the Kinesis Video Streams client for MPEG-DASH playback ](#dash-example-setup) + [ ### Retrieve the Kinesis Video Streams archived content endpoint for MPEG-DASH playback ](#dash-example-endpoint) + [ ### Retrieve the MPEG-DASH streaming session URL ](#dash-example-session) + [ ### Display the streaming video with MPEG-DASH playback ](#dash-example-display) + [ ### Completed example ](#dash-example-complete) ### Set up the Kinesis Video Streams client for MPEG-DASH playback To access streaming video with MPEG-DASH, first create and configure the Kinesis Video Streams client (to retrieve the service endpoint) and archived media client (to retrieve the MPEG-DASH streaming session). The application retrieves the necessary values from input boxes on the HTML page. ``` var streamName = $('#streamName').val(); // Step 1: Configure SDK Clients var options = { accessKeyId: $('#accessKeyId').val(), secretAccessKey: $('#secretAccessKey').val(), sessionToken: $('#sessionToken').val() || undefined, region: $('#region').val(), endpoint: $('#endpoint').val() || undefined } var kinesisVideo = new AWS.KinesisVideo(options); var kinesisVideoArchivedContent = new AWS.KinesisVideoArchivedMedia(options); ``` ### Retrieve the Kinesis Video Streams archived content endpoint for MPEG-DASH playback After the clients are initiated, retrieve the Kinesis Video Streams archived content endpoint so that you can retrieve the MPEG-DASH streaming session URL as follows: ``` // Step 2: Get a data endpoint for the stream console.log('Fetching data endpoint'); kinesisVideo.getDataEndpoint({ StreamName: streamName, APIName: "GET_DASH_STREAMING_SESSION_URL" }, function(err, response) { if (err) { return console.error(err); } console.log('Data endpoint: ' + response.DataEndpoint); kinesisVideoArchivedContent.endpoint = new AWS.Endpoint(response.DataEndpoint); ``` ### Retrieve the MPEG-DASH streaming session URL When you have the archived content endpoint, call the [GetDASHStreamingSessionURL](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/API_reader_GetDASHStreamingSessionURL.html) API to retrieve the MPEG-DASH streaming session URL as follows: ``` // Step 3: Get a Streaming Session URL var consoleInfo = 'Fetching ' + protocol + ' Streaming Session URL'; console.log(consoleInfo); if (protocol === 'DASH') { kinesisVideoArchivedContent.getDASHStreamingSessionURL({ StreamName: streamName, PlaybackMode: $('#playbackMode').val(), DASHFragmentSelector: { FragmentSelectorType: $('#fragmentSelectorType').val(), TimestampRange: $('#playbackMode').val() === "LIVE" ? undefined : { StartTimestamp: new Date($('#startTimestamp').val()), EndTimestamp: new Date($('#endTimestamp').val()) } }, DisplayFragmentTimestamp: $('#displayFragmentTimestamp').val(), DisplayFragmentNumber: $('#displayFragmentNumber').val(), MaxManifestFragmentResults: parseInt($('#maxResults').val()), Expires: parseInt($('#expires').val()) }, function(err, response) { if (err) { return console.error(err); } console.log('DASH Streaming Session URL: ' + response.DASHStreamingSessionURL); ``` ### Display the streaming video with MPEG-DASH playback When you have the MPEG-DASH streaming session URL, provide it to the video player. The method for providing the URL to the video player is specific to the player that you use. The following code example shows how to provide the streaming session URL to a [Google Shaka](https://github.com/google/shaka-player) player: ``` // Step 4: Give the URL to the video player. //Shaka Player elements ... var playerName = $('#player').val(); if (playerName === 'Shaka Player') { var playerElement = $('#shaka'); playerElement.show(); var player = new shaka.Player(playerElement[0]); console.log('Created Shaka Player'); player.load(response.DASHStreamingSessionURL).then(function() { console.log('Starting playback'); }); console.log('Set player source'); } ``` The following code example shows how to provide the streaming session URL to an [dash.js](https://github.com/Dash-Industry-Forum/dash.js/wiki) player: ``` ... var playerElement = $('#dashjs'); playerElement.show(); var player = dashjs.MediaPlayer().create(); console.log('Created DASH.js Player'); player.initialize(document.querySelector('#dashjs'), response.DASHStreamingSessionURL, true); console.log('Starting playback'); console.log('Set player source'); } ``` ### Completed example You can [download or view the completed example code](https://github.com/aws-samples/amazon-kinesis-video-streams-hls-viewer/blob/master/index.html) on GitHub.