Amazon Kinesis Video Streams Developer Guide 2.Dev Stream

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 226 [warning: Documents this large are best viewed by clicking the View PDF Link!]

Amazon Kinesis Video Streams
Developer Guide
Amazon Kinesis Video Streams Developer Guide
Amazon Kinesis Video Streams: Developer Guide
Copyright © 2019 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner
that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not
owned by Amazon are the property of their respective owners, who may or may not be affiliated with, connected to, or sponsored by
Amazon.
Amazon Kinesis Video Streams Developer Guide
Table of Contents
What Is Amazon Kinesis Video Streams? ............................................................................................... 1
Are You a First-Time User of Kinesis Video Streams? ....................................................................... 2
System Requirements ......................................................................................................................... 3
Camera Requirements ................................................................................................................. 3
Tested Cameras ................................................................................................................. 3
Tested Operating Systems ................................................................................................... 4
SDK Storage Requirements .......................................................................................................... 4
How It Works .................................................................................................................................... 5
API and Producer Libraries .......................................................................................................... 6
Kinesis Video Streams API ................................................................................................... 6
Producer Libraries .............................................................................................................. 8
Video Playback Using HLS ........................................................................................................... 9
Example: Using HLS in HTML and JavaScript ......................................................................... 9
Using Streaming Metadata ........................................................................................................ 12
Adding Metadata to a Kinesis Video Stream ......................................................................... 12
Consuming Metadata Embedded in a Kinesis Video Stream .................................................... 13
Streaming Metadata Limitations ......................................................................................... 14
Controlling Access .................................................................................................................... 15
Policy Syntax ................................................................................................................... 15
Actions for Kinesis Video Streams ...................................................................................... 16
Amazon Resource Names (ARNs) for Kinesis Video Streams .................................................... 16
Granting Other IAM Accounts Access to a Kinesis Video Stream .............................................. 16
Example Policies ............................................................................................................... 17
Using Server-Side Encryption ..................................................................................................... 18
What Is Server-Side Encryption for Kinesis Video Streams? .................................................... 18
Costs, Regions, and Performance Considerations .................................................................. 19
How Do I Get Started with Server-Side Encryption? .............................................................. 19
Creating and Using User-Generated AWS KMS Master Keys .................................................... 20
Permissions to Use User-Generated AWS KMS Master Keys .................................................... 20
Data Model .............................................................................................................................. 21
Stream Header Elements ................................................................................................... 22
Frame Header Elements .................................................................................................... 25
MKV Frame Data .............................................................................................................. 25
Getting Started ................................................................................................................................ 26
Step 1: Set Up an Account ........................................................................................................ 26
Sign Up for AWS .............................................................................................................. 26
Create an Administrator IAM User ...................................................................................... 27
Next Step ........................................................................................................................ 27
Step 2: Create a Kinesis Video Stream ......................................................................................... 27
Create a Video Stream Using the Console ............................................................................ 28
Create a Video Stream Using the AWS CLI ........................................................................... 30
Next Step ........................................................................................................................ 30
What's Next? ............................................................................................................................ 30
Producer Libraries ............................................................................................................................ 31
Kinesis Video Streams Producer Client ........................................................................................ 31
Kinesis Video Streams Producer Library ....................................................................................... 32
Related Topics ......................................................................................................................... 32
Java Producer Library ............................................................................................................... 32
Procedure: Using the Java Producer SDK ............................................................................. 33
Step 1: Download and Configure the Code .......................................................................... 33
Step 2: Write and Examine the Code .................................................................................. 34
Step 3: Run and Verify the Code ........................................................................................ 35
Android Producer Library .......................................................................................................... 36
Procedure: Using the Android Producer SDK ........................................................................ 36
iii
Amazon Kinesis Video Streams Developer Guide
Step 1: Download and Configure the Code .......................................................................... 37
Step 2: Examine the Code ................................................................................................. 38
Step 3: Run and Verify the Code ........................................................................................ 40
C++ Producer Library ................................................................................................................ 41
Object Model ................................................................................................................... 41
Putting Media into the Stream ........................................................................................... 41
Callback Interfaces ........................................................................................................... 41
Procedure: Using the C++ Producer SDK .............................................................................. 41
Step 1: Download and Configure the Code .......................................................................... 43
Step 2: Write and Examine the Code .................................................................................. 44
Step 3: Run and Verify the Code ........................................................................................ 48
Using the C++ Producer SDK as a GStreamer Plugin .............................................................. 48
Using the C++ Producer SDK as a GStreamer Plugin in a Docker Container ............................... 48
Using the C++ Producer SDK on Windows ........................................................................... 49
Using the C++ Producer SDK on Raspberry Pi ...................................................................... 53
Using Logging .................................................................................................................. 58
Reference ................................................................................................................................ 59
Producer SDK Limits ......................................................................................................... 59
Error Code Reference ........................................................................................................ 61
NAL Adaptation Flags ....................................................................................................... 81
Producer Structures .......................................................................................................... 82
Stream Structures ............................................................................................................ 83
Callbacks ......................................................................................................................... 95
Stream Parser Library ..................................................................................................................... 100
Procedure: Using the Kinesis Video Stream Parser Library ............................................................ 100
Prerequisites .......................................................................................................................... 100
Step 1: Download and Configure the Code ................................................................................ 101
Next Step ...................................................................................................................... 101
Step 2: Write and Examine the Code ......................................................................................... 101
StreamingMkvReader ...................................................................................................... 101
FragmentMetadataVisitor ................................................................................................. 102
OutputSegmentMerger .................................................................................................... 103
KinesisVideoExample ....................................................................................................... 104
Next Step ...................................................................................................................... 106
Step 3: Run and Verify the Code .............................................................................................. 106
Examples ....................................................................................................................................... 107
Examples: Sending Data to Kinesis Video Streams ...................................................................... 107
Examples: Retrieving Data from Kinesis Video Streams ................................................................ 107
Examples: Playing Back Video Data ........................................................................................... 107
Prerequisites .......................................................................................................................... 107
GStreamer ............................................................................................................................. 108
Download, Build, and Configure the GStreamer Element ...................................................... 109
Run the GStreamer Element ............................................................................................ 109
Launch Commands ......................................................................................................... 110
Run the GStreamer Element in a Docker Container ............................................................. 111
Parameter Reference ....................................................................................................... 113
PutMedia API ......................................................................................................................... 116
Step 1: Download and Configure the Code ........................................................................ 116
Step 2: Write and Examine the Code ................................................................................. 117
Step 3: Run and Verify the Code ...................................................................................... 118
RTSP and Docker .................................................................................................................... 119
Prerequisites .................................................................................................................. 119
Build the Docker Image ................................................................................................... 119
Run the RTSP Example Application ................................................................................... 120
Renderer ................................................................................................................................ 120
Prerequisites .................................................................................................................. 120
Running the Renderer Example ........................................................................................ 121
iv
Amazon Kinesis Video Streams Developer Guide
How It Works ................................................................................................................. 121
Amazon SageMaker ................................................................................................................ 122
Prerequisites .................................................................................................................. 123
Creating the Application .................................................................................................. 124
Monitoring the Application .............................................................................................. 124
Extending the Application ............................................................................................... 126
Cleaning up the Application ............................................................................................. 126
Monitoring ..................................................................................................................................... 128
Monitoring Metrics with CloudWatch ......................................................................................... 128
CloudWatch Metrics Guidance .......................................................................................... 132
Logging API Calls with CloudTrail ............................................................................................. 135
Kinesis Video Streams and CloudTrail ................................................................................ 135
Example: Amazon Kinesis Video Streams Log File Entries ..................................................... 136
Limits ............................................................................................................................................ 139
Control Plane API limits .......................................................................................................... 139
Media and Archived Media API limits ........................................................................................ 139
Troubleshooting ............................................................................................................................. 142
Troubleshooting General Issues ................................................................................................ 142
Latency too high ............................................................................................................ 142
Troubleshooting API Issues ...................................................................................................... 142
Error: "Unknown options" ................................................................................................ 143
Error: "Unable to determine service/operation name to be authorized" .................................. 143
Error: "Failed to put a frame in the stream" ....................................................................... 143
Error: "Service closed connection before final AckEvent was received" .................................... 143
Error: "STATUS_STORE_OUT_OF_MEMORY" ....................................................................... 144
Troubleshooting HLS Issues ..................................................................................................... 144
Retrieving HLS streaming session URL succeeds, but playback fails in video player ................... 144
Latency too high between producer and player .................................................................. 144
Troubleshooting Java Issues ..................................................................................................... 145
Enabling Java logs .......................................................................................................... 145
Troubleshooting Producer Library Issues .................................................................................... 146
Cannot compile the Producer SDK .................................................................................... 146
Video stream does not appear in the console ..................................................................... 147
Error: "Security token included in the request is invalid" when streaming data using the
GStreamer demo application ............................................................................................ 147
Error: "Failed to submit frame to Kinesis Video client" ......................................................... 147
GStreamer application stops with "streaming stopped, reason not-negotiated" message on OS
X .................................................................................................................................. 147
Error: "Failed to allocate heap" when creating Kinesis Video Client in GStreamer demo on
Raspberry Pi .................................................................................................................. 148
Error: "Illegal Instruction" when running GStreamer demo on Raspberry Pi ............................. 148
Camera fails to load on Raspberry Pi ................................................................................ 148
Camera can't be found on macOS High Sierra .................................................................... 149
jni.h file not found when compiling on macOS High Sierra ................................................... 149
Curl errors when running the GStreamer demo application .................................................. 149
Timestamp/range assertion at runtime on Raspberry Pi ....................................................... 149
Assertion on gst_value_set_fraction_range_full on Raspberry Pi ............................................ 149
STATUS_MKV_INVALID_ANNEXB_NALU_IN_FRAME_DATA (0x3200000d) error on Android ........ 150
Troubleshooting Stream Parser Library Issues ............................................................................. 150
Cannot access a single frame from the stream ................................................................... 150
Fragment decoding error ................................................................................................. 150
Document History .......................................................................................................................... 151
API Reference ................................................................................................................................. 154
Actions .................................................................................................................................. 154
Amazon Kinesis Video Streams ......................................................................................... 154
Amazon Kinesis Video Streams Media ............................................................................... 184
Amazon Kinesis Video Streams Archived Media .................................................................. 194
v
Amazon Kinesis Video Streams Developer Guide
Data Types ............................................................................................................................ 206
Amazon Kinesis Video Streams ......................................................................................... 207
Amazon Kinesis Video Streams Media ............................................................................... 210
Amazon Kinesis Video Streams Archived Media .................................................................. 212
Common Errors ...................................................................................................................... 217
Common Parameters .............................................................................................................. 219
vi
Amazon Kinesis Video Streams Developer Guide
What Is Amazon Kinesis Video
Streams?
Amazon Kinesis Video Streams is a fully managed AWS service that you can use to stream live video from
devices to the AWS Cloud, or build applications for real-time video processing or batch-oriented video
analytics.
Kinesis Video Streams isn't just storage for video data. You can use it to watch your video streams in real
time as they are received in the cloud. You can either monitor your live streams in the AWS Management
Console, or develop your own monitoring application that uses the Kinesis Video Streams API library to
display live video.
You can use Kinesis Video Streams to capture massive amounts of live video data from millions of
sources, including smartphones, security cameras, webcams, cameras embedded in cars, drones, and
other sources. You can also send non-video time-serialized data such as audio data, thermal imagery,
depth data, RADAR data, and more. As live video streams from these sources into a Kinesis video
stream, you can build applications that can access the data, frame-by-frame, in real time for low-latency
processing. Kinesis Video Streams is source-agnostic; you can stream video from a computer's webcam
using the GStreamer (p. 108) library, or from a camera on your network using RTSP.
You can also configure your Kinesis video stream to durably store media data for the specified retention
period. Kinesis Video Streams automatically stores this data and encrypts it at rest. Additionally, Kinesis
Video Streams time-indexes stored data based on both the producer time stamps and ingestion time
stamps. You can build applications that periodically batch-process the video data, or you can create
applications that require ad hoc access to historical data for different use cases.
Your custom applications, real-time or batch-oriented, can run on Amazon EC2 instances. These
applications might process data using open source deep-learning algorithms, or use third-party
applications that integrate with Kinesis Video Streams.
Benefits of using Kinesis Video Streams include the following:
•Connect and stream from millions of devices – Kinesis Video Streams enables you to connect and
stream video, audio, and other data from millions of devices ranging from consumer smartphones,
drones, dash cams, and more. You can use the Kinesis Video Streams producer libraries to configure
your devices and reliably stream in real time, or as after-the-fact media uploads.
•Durably store, encrypt, and index data – You can configure your Kinesis video stream to durably
store media data for custom retention periods. Kinesis Video Streams also generates an index over
the stored data based on producer-generated or service-side time stamps. Your applications can easily
retrieve specified data in a stream using the time-index.
•Focus on managing applications instead of infrastructure – Kinesis Video Streams is serverless,
so there is no infrastructure to set up or manage. You don't need to worry about the deployment,
configuration, or elastic scaling of the underlying infrastructure as your data streams and number
of consuming applications grow and shrink. Kinesis Video Streams automatically does all the
administration and maintenance required to manage streams, so you can focus on the applications,
not the infrastructure.
•Build real-time and batch applications on data streams – You can use Kinesis Video Streams to
build custom real-time applications that operate on live data streams, and create batch or ad hoc
applications that operate on durably persisted data without strict latency requirements. You can build,
deploy, and manage custom applications: open source (Apache MXNet, OpenCV), homegrown, or third-
party solutions via the AWS Marketplace to process and analyze your streams. Kinesis Video Streams
1
Amazon Kinesis Video Streams Developer Guide
Are You a First-Time User of Kinesis Video Streams?
Get APIs enable you to build multiple concurrent applications processing data in a real-time or batch-
oriented basis.
•Stream data more securely – Kinesis Video Streams encrypts all data as it flows through the service
and when it persists the data. Kinesis Video Streams enforces Transport Layer Security (TLS)-based
encryption on data streaming from devices, and encrypts all data at rest using AWS Key Management
Service (AWS KMS). Additionally, you can manage access to your data using AWS Identity and Access
Management (IAM).
•Pay as you go – For more information, see AWS Pricing.
Kinesis Video Streams is suitable for a variety of industry scenarios. For example:
• Smart city initiatives – Push video streams from traffic cameras to Kinesis video streams, and write
consumer applications that can track real-time traffic patterns. You can also batch process the
historical data to understand changes that result from new construction or traffic routing changes.
• Home scenarios – Connect home security cameras, baby monitors, and other cameras embedded in
appliances to build experiences that keep consumers safe and make their lives more productive and
fun.
• Intelligent retail features – Capture video from multiple in-store cameras to automate people-
counting, generate store heat maps to understand in-store customer activity, optimize layout and
merchandise display, and other actions to help drive customer satisfaction.
• Industrial automation – Use license plate readers that automatically detect when trucks enter and
leave the warehouse. Count pallets and track movement of material and goods on the shop floor. Use
thermal cameras to notify when industrial machinery is overheating to drive preventative maintenance
and keep workers safe.
Are You a First-Time User of Kinesis Video
Streams?
If you're a first-time user of Kinesis Video Streams, we recommend that you read the following sections
in order:
1. Amazon Kinesis Video Streams: How It Works (p. 5) – To learn about Kinesis Video Streams
concepts.
2. Getting Started with Kinesis Video Streams (p. 26) – To set up your account and test Kinesis
Video Streams.
3. Kinesis Video Streams Producer Libraries (p. 31) – To learn about creating a Kinesis Video
Streams producer application.
4. Kinesis Video Stream Parser Library (p. 100) – To learn about processing incoming data frames in a
Kinesis Video Streams consumer application.
5. Amazon Kinesis Video Streams Examples (p. 107) – To see more examples of what you can do with
Kinesis Video Streams.
2
Amazon Kinesis Video Streams Developer Guide
Camera Requirements
Kinesis Video Streams System
Requirements
The following sections contain hardware, software, and storage requirements for Amazon Kinesis Video
Streams.
Topics
•Camera Requirements (p. 3)
•SDK Storage Requirements (p. 4)
Camera Requirements
Cameras that are used for running the Kinesis Video Streams Producer SDK and samples have the
following memory requirements:
• The SDK content view requires 16 MB of memory.
• The sample application default configuration is 512 MB. This value is appropriate for producers
that have good network connectivity and no requirements for additional buffering. If the network
connectivity is poor and more buffering is required, you can calculate the memory requirement per
second of buffering by multiplying the frame rate per second by the frame memory size. For more
information about allocating memory, see StorageInfo (p. 82).
We recommend using USB or RTSP (Real Time Streaming Protocol) cameras that encode data using
H.264 because this removes the encoding workload from the CPU.
Currently, the demo application does not support the User Datagram Protocol (UDP) for RTSP streaming.
This capability will be added in the future.
The Producer SDK supports the following types of cameras:
• Web cameras.
• USB cameras.
• Cameras with H.264 encoding (preferred).
• Cameras without H.264 encoding.
• Raspberry Pi camera module. This is preferred for Raspberry Pi devices because it connects to the GPU
for video data transfer, so there is no overhead for CPU processing.
• RTSP (network) cameras. These cameras are preferred because the video streams are already encoded
with H.264.
Tested Cameras
We have tested the following USB cameras with Kinesis Video Streams:
• Logitech 1080p
• Logitech C930
• Logitech C920 (H.264)
3
Amazon Kinesis Video Streams Developer Guide
Tested Operating Systems
• Logitech Brio (4K)
• SVPRO USB Camera 170degree Fisheye Lens Wide Angle 1080P 2mp Sony IMX322 HD H.264 30fps
Mini Aluminum USB Webcam Camera
We have tested the following IP cameras with Kinesis Video Streams:
• Vivotek FD9371 – HTV/EHTV
• Vivotek IB9371 – HT
• Hikvision 3MP IP Camera DS-2CD2035FWD-I
• Sricam SP012 IP
• VStarcam 720P WiFi IP Camera (TCP)
• Ipccam Security Surveillance IP Camera 1080P
• AXIS P3354 Fixed Dome Network Camera
Of the cameras that were tested with Kinesis Video Streams, the Vivotek cameras have the most
consistent RTSP stream. The Sricam camera has the least consistent RTSP stream.
Tested Operating Systems
We have tested web cameras and RTSP cameras with the following devices and operating systems:
• Mac mini
• High Sierra
• MacBook Pro laptops
• Sierra (10.12)
• El Capitan (10.11)
• HP laptops running Ubuntu 16.04
• Ubuntu 17.10 (Docker container)
• Raspberry Pi 3
SDK Storage Requirements
Installing the Kinesis Video Streams Producer Libraries (p. 31) has a minimum storage requirement of
170 MB and a recommended storage requirement of 512 MB.
4
Amazon Kinesis Video Streams Developer Guide
Amazon Kinesis Video Streams: How
It Works
Topics
•Kinesis Video Streams API and Producer Libraries Support (p. 6)
•Kinesis Video Streams Playback with HLS (p. 9)
•Using Streaming Metadata with Kinesis Video Streams (p. 12)
•Controlling Access to Kinesis Video Streams Resources Using IAM (p. 15)
•Using Server-Side Encryption with Kinesis Video Streams (p. 18)
•Kinesis Video Streams Data Model (p. 21)
Amazon Kinesis Video Streams is a fully managed AWS service that enables you to stream live video from
devices to the AWS Cloud and durably store it. You can then build your own applications for real-time
video processing or perform batch-oriented video analytics.
The following diagram provides an overview of how Kinesis Video Streams works.
5
Amazon Kinesis Video Streams Developer Guide
API and Producer Libraries
The diagram demonstrates the interaction among the following components:
•Producer – Any source that puts data into a Kinesis video stream. A producer can be any video-
generating device, such as a security camera, a body-worn camera, a smartphone camera, or a
dashboard camera. A producer can also send non-video data, such as audio feeds, images, or RADAR
data.
A single producer can generate one or more video streams. For example, a video camera can push
video data to one Kinesis video stream and audio data to another.
•Kinesis Video Streams Producer libraries – A set of easy-to-use software and libraries that you can
install and configure on your devices. These libraries make it easy to securely connect and reliably
stream video in different ways, including in real time, after buffering it for a few seconds, or as after-
the-fact media uploads.
•Kinesis video stream – A resource that enables you to transport live video data, optionally store it, and
make the data available for consumption both in real time and on a batch or ad hoc basis. In a typical
configuration, a Kinesis video stream has only one producer publishing data into it.
The stream can carry audio, video, and similar time-encoded data streams, such as depth sensing
feeds, RADAR feeds, and more. You create a Kinesis video stream using the AWS Management Console
or programmatically using the AWS SDKs.
Multiple independent applications can consume a Kinesis video stream in parallel.
•Consumer – Gets data, such as fragments and frames, from a Kinesis video stream to view, process,
or analyze it. Generally these consumers are called Kinesis Video Streams applications. You can write
applications that consume and process data in Kinesis video streams in real time, or after the data is
durably stored and time-indexed when low latency processing is not required. You can create these
consumer applications to run on Amazon EC2 instances.
•Kinesis Video Stream Parser Library (p. 100) – Enables Kinesis Video Streams applications to
reliably get media from Kinesis video streams in a low-latency manner. Additionally, it parses the
frame boundaries in the media so that applications can focus on processing and analyzing the
frames themselves.
Kinesis Video Streams API and Producer Libraries
Support
Kinesis Video Streams provides APIs for you to create and manage streams and read or write media data
to and from a stream. The Kinesis Video Streams console, in addition to administration functionality,
also supports live and video-on-demand playback. Kinesis Video Streams also provides a set of producer
libraries that you can use in your application code to extract data from your media sources and upload to
your Kinesis video stream.
Topics
•Kinesis Video Streams API (p. 6)
•Producer Libraries (p. 8)
Kinesis Video Streams API
Kinesis Video Streams provides APIs for creating and managing Kinesis video streams. It also provides
APIs for reading and writing media data to a stream, as follows:
•Producer API – Kinesis Video Streams provides a PutMedia API to write media data to a Kinesis video
stream. In a PutMedia request, the producer sends a stream of media fragments. A fragment is a self-
6
Amazon Kinesis Video Streams Developer Guide
Kinesis Video Streams API
contained sequence of frames. The frames belonging to a fragment should have no dependency on
any frames from other fragments. For more information, see PutMedia (p. 189).
As fragments arrive, Kinesis Video Streams assigns a unique fragment number, in increasing order. It
also stores producer-side and server-side time stamps for each fragment, as Kinesis Video Streams-
specific metadata.
•Consumer APIs –The following APIs enable consumers to get data from a stream:
•GetMedia - When using this API, consumers must identify the starting fragment. The API then
returns fragments in the order in which they were added to the stream (in increasing order by
fragment number). The media data in the fragments is packed into a structured format such as
Matroska (MKV). For more information, see GetMedia (p. 185).
Note
GetMedia knows where the fragments are (archived in the data store or available in real
time). For example, if GetMedia determines that the starting fragment is archived, it starts
returning fragments from the data store. When it needs to return newer fragments that
are not archived yet, GetMedia switches to reading fragments from an in-memory stream
buffer.
This is an example of a continuous consumer, which processes fragments in the order that they are
ingested by the stream.
GetMedia enables video-processing applications to fail or fall behind, and then catch up with no
additional effort. Using GetMedia, applications can process data that's archived in the data store,
and as the application catches up, GetMedia continues to feed media data in real time as it arrives.
•GetMediaFromFragmentList (and ListFragments) - Batch processing applications
are considered offline consumers. Offline consumers might choose to explicitly fetch
particular media fragments or ranges of video by combining the ListFragments and
GetMediaFromFragmentList APIs. ListFragments and GetMediaFromFragmentList enable
an application to identify segments of video for a particular time range or fragment range, and then
fetch those fragments either sequentially or in parallel for processing. This approach is suitable for
MapReduce application suites, which must quickly process large amounts of data in parallel.
For example, suppose that a consumer wants to process one day's worth of video fragments. The
consumer would do the following:
1. Get a list of fragments by calling the ListFragments API and specifying a time range to select
the desired collection of fragments.
The API returns metadata from all the fragments in the specified time range. The metadata
provides information such as fragment number, producer-side/server-side time stamps, and so
on.
2. Take the fragment metadata list and retrieve fragments, in any order. For example, to process
all the fragments for the day, the consumer might choose to split the list into sub-lists and have
workers (for example, multiple Amazon EC2 instances) fetch the fragments in parallel using the
GetMediaFromFragmentList, and process them in parallel.
The following diagram shows the data flow for fragments and chunks during these API calls.
7
Amazon Kinesis Video Streams Developer Guide
Producer Libraries
When a producer sends a PutMedia request, it sends media metadata in the payload, and then sends
a sequence of media data fragments. Upon receiving the data, Kinesis Video Streams stores incoming
media data as Kinesis Video Streams chunks. Each chunk consists of the following:
• A copy of the media metadata
• A fragment
• Kinesis Video Streams-specific metadata; for example, the fragment number and server-side and
producer-side time stamps
When a consumer requests media metadata, Kinesis Video Streams returns a stream of chunks, starting
with the fragment number that you specify in the request.
If you enable data persistence for the stream, after receiving a fragment on the stream, Kinesis Video
Streams also saves a copy of the fragment to the data store.
Producer Libraries
After you create a Kinesis video stream, you can start sending data to the stream. In your application
code, you can use these libraries to extract data from your media sources and upload to your Kinesis
video stream. For more information about the available producer libraries, see Kinesis Video Streams
Producer Libraries (p. 31).
8
Amazon Kinesis Video Streams Developer Guide
Video Playback Using HLS
Kinesis Video Streams Playback with HLS
HTTP Live Streaming (HLS) is an industry-standard HTTP-based media streaming communications
protocol. You can use HLS to view an Amazon Kinesis video stream, either for live playback or to view
archived video.
You can view a Kinesis video stream using either HLS or the GetMedia API. The differences between these
methods are as follows:
•GetMedia: You use the GetMedia API to build your own applications to process Kinesis video streams.
GetMedia is a real-time API with low latency. If you want to create a player that uses GetMedia, you
have to build it yourself. For information about how to develop an application that displays a Kinesis
video stream using GetMedia, see Stream Parser Library (p. 100).
•HLS: You can use HLS for live playback. Latency is typically between 3 and 5 seconds, but it can be
between 1 and 10 seconds, depending on the use case, player, and network conditions. You can use a
third-party player (such as Video.js or 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 typing the HLS streaming session URL in the Location bar of the Apple Safari or Microsoft Edge
browsers.
To view a Kinesis video stream using HLS, you first create a streaming session using
GetHLSStreamingSessionURL. 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.
An Amazon Kinesis video stream has the following requirements for providing video through HLS:
• The media type must be video/h264.
• Data retention must be greater than 0.
• The fragments must contain codec private data in the AVC (Advanced Video Coding) for H.264 format
(MPEG-4 specification ISO/IEC 14496-15). For information about adapting stream data to a given
format, see NAL Adaptation Flags (p. 81).
Example: Using HLS in HTML and JavaScript
The following example shows how to retrieve an HLS 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:
•Video.js
•Google Shaka Player
Topics
•Set Up the Kinesis Video Streams Client (p. 10)
•Retrieve the Kinesis Video Streams Archived Content Endpoint (p. 10)
•Retrieve the HLS Streaming Session URL (p. 10)
•Display the Streaming Video (p. 11)
•Troubleshooting (p. 11)
•Completed Example (p. 11)
9
Amazon Kinesis Video Streams Developer Guide
Example: Using HLS in HTML and JavaScript
Set Up the Kinesis Video Streams Client
To access streaming video with HLS, first create and configure the Kinesis Video Streams client (to
retrieve the service endpoint) and archived media client (to retrieve the HLS streaming session). The
application retrieves the necessary values from input boxes on the HTML page.
<script src="https://cdnjs.cloudflare.com/ajax/libs/aws-sdk/2.278.1/aws-sdk.min.js"></
script>
...
var streamName = $('#streamName').val();
// Step 1: Configure SDK Clients
var options = {
accessKeyId: 'ACCESS_KEY_ID',
secretAccessKey: 'SECRET_KEY',
sessionToken: $('#sessionToken').val() || undefined,
region: 'REGION',
endpoint: $('#endpoint').val() || undefined
}
var kinesisVideo = new AWS.KinesisVideo(options);
var kinesisVideoArchivedContent = new AWS.KinesisVideoArchivedMedia(options);
Retrieve the Kinesis Video Streams Archived Content Endpoint
After the clients are initiated, retrieve the Kinesis Video Streams archived content endpoint to retrieve
the HLS streaming session URL:
// Step 2: Get a data endpoint for the stream
kinesisVideo.getDataEndpoint({
StreamName: streamName,
APIName: "GET_HLS_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 HLS Streaming Session URL
When you have the archived content endpoint, call the GetHLSStreamingSessionURL API to retrieve the
HLS streaming session URL:
// Step 3: Get an HLS Streaming Session URL
console.log('Fetching HLS Streaming Session URL');
kinesisVideoArchivedContent.getHLSStreamingSessionURL({
StreamName: streamName,
PlaybackMode: $('#playbackMode').val(),
HLSFragmentSelector: {
FragmentSelectorType: $('#fragmentSelectorType').val(),
TimestampRange: $('#playbackMode').val() === "LIVE" ? undefined : {
StartTimestamp: new Date($('#startTimestamp').val()),
EndTimestamp: new Date($('#endTimestamp').val())
}
},
DiscontinuityMode: $('#discontinuityMode').val(),
MaxMediaPlaylistFragmentResults: parseInt($('#maxMediaPlaylistFragmentResults').val()),
Expires: parseInt($('#expires').val())
}, function(err, response) {
if (err) { return console.error(err); }
10
Amazon Kinesis Video Streams Developer Guide
Example: Using HLS in HTML and JavaScript
console.log('HLS Streaming Session URL: ' + response.HLSStreamingSessionURL);
Display the Streaming Video
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.
The following code example shows how to provide the streaming session URL to a Video.js player:
<!-- VideoJS elements -->
<video id="videojs" class="video-js vjs-default-skin" controls autoplay></video>
<script src="https://vjs.zencdn.net/6.6.3/video.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/videojs-contrib-hls/5.14.1/videojs-
contrib-hls.js"></script>
...
// Step 4: Give the URL to the video player.
var playerName = $('#player').val();
if (playerName === 'VideoJS') {
var playerElement = $('#videojs');
playerElement.show();
var player = videojs('videojs');
console.log('Created VideoJS Player');
player.src({
src: response.HLSStreamingSessionURL,
type: 'application/x-mpegURL'
});
console.log('Set player source');
player.play();
console.log('Starting playback');
}
The following code example shows how to provide the streaming session URL to a Google Shaka player:
<!-- Shaka Player elements -->
<video id="shaka" controls autoplay></video>
<script src="https://cdnjs.cloudflare.com/ajax/libs/shaka-player/2.4.1/shaka-
player.compiled.js"></script>
...
if (playerName === 'Shaka Player') {
var playerElement = $('#shaka');
playerElement.show();
var player = new shaka.Player(playerElement[0]);
console.log('Created Shaka Player');
player.load(response.HLSStreamingSessionURL).then(function() {
console.log('Starting playback');
});
console.log('Set player source');
Troubleshooting
If the video stream does not play back correctly, see Troubleshooting HLS Issues (p. 144).
Completed Example
You can download or view the completed example code here.
11
Amazon Kinesis Video Streams Developer Guide
Using Streaming Metadata
Using Streaming Metadata with Kinesis Video
Streams
You can use the Amazon Kinesis Video Streams Producer SDK to embed metadata at the individual
fragment level in a Kinesis video stream. Metadata in Kinesis Video Streams is a mutable key-value
pair. You can use it to describe the content of the fragment, embed associated sensor readings
that need to be transferred along with the actual fragment, or meet other custom needs. The
metadata is made available as part of the the section called “GetMedia” (p. 185) or the section called
“GetMediaForFragmentList” (p. 201) API operations. It is stored along with the fragments for the entire
duration of the stream's retention period. Your consuming applications can read, process, and take action
based on the metadata using the Kinesis Video Stream Parser Library (p. 100).
There are two modes in which the metadata can be embedded with fragments in a stream:
•Nonpersistent: You can affix metadata on an ad hoc basis to fragments in a stream, based on
business-specific criteria that have occurred. An example is a smart camera that detects motion and
adds metadata to the corresponding fragments that contain the motion before sending the fragments
to its Kinesis video stream. You might apply metadata to the fragment in the following format:
Motion = true.
•Persistent: You can affix metadata to successive, consecutive fragments in a stream based on
a continuing need. An example is a smart camera that sends the current latitude and longitude
coordinates associated with all fragments that it sends to its Kinesis video stream. You might
apply metadata to all the fragments in the following format: Lat = 47.608013N , Long =
-122.335167W
You can affix metadata in both of these modes to the same fragment simultaneously, based on your
application's needs. The embedded metadata might include objects detected, activity tracked, GPS
coordinates, or any other custom data that you want to associate with the fragments in the stream.
Metadata is encoded as key-value string pairs.
Topics
•Adding Metadata to a Kinesis Video Stream (p. 12)
•Consuming Metadata Embedded in a Kinesis Video Stream (p. 13)
•Streaming Metadata Limitations (p. 14)
Adding Metadata to a Kinesis Video Stream
Metadata that you add to a Kinesis video stream is modeled as MKV tags, which are implemented as key-
value pairs.
Metadata can either be transient, such as to mark an event within the stream, or persistent, such as
to identify fragments where a given event is taking place. A persistent metadata item remains, and is
applied to each consecutive fragment, until it is canceled.
Note
The metadata items added using the Producer Libraries (p. 31) are distinct from the stream-
level tagging APIs implemented with the section called “TagStream” (p. 174), the section
called “UntagStream” (p. 177), and the section called “ListTagsForStream” (p. 171).
Streaming Metadata API
You can use the following operations in the Producer SDK to implement streaming metadata.
12
Amazon Kinesis Video Streams Developer Guide
Consuming Metadata Embedded in a Kinesis Video Stream
PIC
PUBLIC_API STATUS putKinesisVideoFragmentMetadata(STREAM_HANDLE streamHandle,
PCHAR name,
PCHAR value,
BOOL persistent);
C++ Producer SDK
/**
* Appends a "tag" or metadata - a key/value string pair into the stream.
*/
bool putFragmentMetadata(const std::string& name, const std::string& value, bool persistent
= true);
Java Producer SDK
Using the Java Producer SDK, you add metadata to a MediaSource using
MediaSourceSink.onCodecPrivateData:
void onFragmentMetadata(final @Nonnull String metadataName, final @Nonnull String
metadataValue, final boolean persistent)
throws KinesisVideoException;
Persistent and Nonpersistent Metadata
For nonpersistent metadata, you can add multiple metadata items with the same name. The Producer
SDK collects the metadata items in the metadata queue until they are prepended to the next fragment.
The metadata queue is cleared as the metadata items are applied to the stream. To repeat the metadata,
call putKinesisVideoFragmentMetadata or putFragmentMetadata again.
For persistent metadata, the Producer SDK collects the metadata items in the metadata queue in the
same way as for nonpersistent metadata. However, the metadata items are not removed from the queue
when they are prepended to the next fragment.
Calling putKinesisVideoFragmentMetadata or putFragmentMetadata with persistent set to
true has the following behavior:
• Calling the API puts the metadata item in the queue. The metadata is added as an MKV tag to every
fragment while the item is in the queue.
• Calling the API with the same name and a different value as a previously added metadata item
overwrites the item.
• Calling the API with an empty value removes (cancels) the metadata item from the metadata queue.
Consuming Metadata Embedded in a Kinesis Video
Stream
To consume the metadata in a Kinesis video stream, use an implementation of MkvTagProcessor:
public interface MkvTagProcessor {
default void process(MkvTag mkvTag, Optional<FragmentMetadata>
currentFragmentMetadata) {
13
Amazon Kinesis Video Streams Developer Guide
Streaming Metadata Limitations
throw new NotImplementedException("Default
FragmentMetadataVisitor.MkvTagProcessor");
}
default void clear() {
throw new NotImplementedException("Default
FragmentMetadataVisitor.MkvTagProcessor");
}
}
}
This interface is found in the FragmentMetadataVisitor (p. 102) class in the Kinesis Video Stream Parser
Library (p. 100).
The FragmentMetadataVisitor class contains an implementation of MkvTagProcessor:
public static final class BasicMkvTagProcessor implements
FragmentMetadataVisitor.MkvTagProcessor {
@Getter
private List<MkvTag> tags = new ArrayList<>();
@Override
public void process(MkvTag mkvTag, Optional<FragmentMetadata> currentFragmentMetadata)
{
tags.add(mkvTag);
}
@Override
public void clear() {
tags.clear();
}
}
The KinesisVideoRendererExample class contains an example of how to use a
BasicMkvTagProcessor. In the following example, a BasicMkvTagProcessor is added to the
MediaProcessingArguments of an application:
if (renderFragmentMetadata) {
getMediaProcessingArguments =
KinesisVideoRendererExample.GetMediaProcessingArguments.create(
Optional.of(new FragmentMetadataVisitor.BasicMkvTagProcessor()));
The BasicMkvTagProcessor.process method is called when fragment metadata arrives. You can
retrieve the accumulated metadata with GetTags. If you want to retrieve a single metadata item, first
call clear to clear the collected metadata, and then retrieve the metadata items again.
Streaming Metadata Limitations
The following limitations apply to adding streaming metadata to a Kinesis video stream:
• You can prepend up to 10 metadata items to a fragment.
• A fragment metadata name can be up to 128 bytes in length.
• A fragment metadata value can be up to 256 bytes in length.
• A fragment metadata name cannot begin with the string "AWS". If such a metadata item is added,
the putFragmentMetadata method in the PIC returns a STATUS_INVALID_METADATA_NAME error
(error code 0x52000077). Your application can then either ignore the error (the PIC doesn't add the
metadata item), or respond to the error.
14
Amazon Kinesis Video Streams Developer Guide
Controlling Access
Controlling Access to Kinesis Video Streams
Resources Using IAM
By using AWS Identity and Access Management (IAM) with Amazon Kinesis Video Streams, you can
control whether users in your organization can perform a task using specific Kinesis Video Streams API
operations and whether they can use specific AWS resources.
For more information about IAM, see the following:
•AWS Identity and Access Management (IAM)
•Getting Started
•IAM User Guide
Contents
•Policy Syntax (p. 15)
•Actions for Kinesis Video Streams (p. 16)
•Amazon Resource Names (ARNs) for Kinesis Video Streams (p. 16)
•Granting Other IAM Accounts Access to a Kinesis Video Stream (p. 16)
•Example Policies for Kinesis Video Streams (p. 17)
Policy Syntax
An IAM policy is a JSON document that consists of one or more statements. Each statement is structured
as follows:
{
"Statement":[{
"Effect":"effect",
"Action":"action",
"Resource":"arn",
"Condition":{
"condition":{
"key":"value"
}
}
}
]
}
There are various elements that make up a statement:
•Effect: The effect can be Allow or Deny. By default, IAM users don't have permission to use resources
and API actions, so all requests are denied. An explicit allow overrides the default. An explicit deny
overrides any allows.
•Action: The action is the specific API action for which you are granting or denying permission.
•Resource: The resource that's affected by the action. To specify a resource in the statement, you need
to use its Amazon Resource Name (ARN).
•Condition: Conditions are optional. They can be used to control when your policy is in effect.
As you create and manage IAM policies, you might want to use the IAM Policy Generator and the IAM
Policy Simulator.
15
Amazon Kinesis Video Streams Developer Guide
Actions for Kinesis Video Streams
Actions for Kinesis Video Streams
In an IAM policy statement, you can specify any API action from any service that supports
IAM. For Kinesis Video Streams, use the following prefix with the name of the API action:
kinesisvideo:. For example: kinesisvideo:CreateStream, kinesisvideo:ListStreams, and
kinesisvideo:DescribeStream.
To specify multiple actions in a single statement, separate them with commas as follows:
"Action": ["kinesisvideo:action1", "kinesisvideo:action2"]
You can also specify multiple actions using wildcards. For example, you can specify all actions whose
name begins with the word "Get" as follows:
"Action": "kinesisvideo:Get*"
To specify all Kinesis Video Streams operations, use the asterisk (*) wildcard as follows:
"Action": "kinesisvideo:*"
For the complete list of Kinesis Video Streams API actions, see the Kinesis Video Streams API reference.
Amazon Resource Names (ARNs) for Kinesis Video
Streams
Each IAM policy statement applies to the resources that you specify using their ARNs.
Use the following ARN resource format for Kinesis Video Streams:
arn:aws:kinesisvideo:region:account-id:stream/stream-name/code
For example:
"Resource": arn:aws:kinesisvideo::*:111122223333:stream/my-stream/0123456789012
You can get the ARN of a stream using DescribeStream.
Granting Other IAM Accounts Access to a Kinesis
Video Stream
You might need to grant permission to other IAM accounts to perform operations on Kinesis video
streams. The following overview describes the general steps to grant access to video streams across
accounts:
1. Get the 12-digit account ID of the account that you want to grant permissions to perform operations
on your stream (for example, 111111111111).
2. Create a managed policy on the account that owns the stream that allows the level of access
that you want to grant. For example policies for Kinesis Video Streams resources, see Example
Policies (p. 17) in the next section.
3. Create a role, specifying the account to which you are granting permissions, and attach the policy
that you created in the previous step.
16
Amazon Kinesis Video Streams Developer Guide
Example Policies
4. Create a managed policy that allows the AssumeRole action on the role you created in the previous
step. For example, the role might look like the following:
{
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": "arn:aws:iam::123456789012:role/CustomRole"
}
}
For step-by-step instructions on granting cross-account access, see Delegate Access Across AWS Accounts
Using IAM Roles.
Example Policies for Kinesis Video Streams
The following example policies demonstrate how you can control user access to your Kinesis video
streams.
Example 1: Allow users to get data from any Kinesis video stream
This policy allows a user or group to perform the DescribeStream, GetDataEndpoint, GetMedia,
ListStreams, and ListTagsForStream operations on any Kinesis video stream. This policy is
appropriate for users who can get data from any video stream.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"kinesisvideo:Describe*",
"kinesisvideo:Get*",
"kinesisvideo:List*"
],
"Resource": "*"
}
]
}
Example 2: Allow a user to create a Kinesis video stream and write data to it
This policy allows a user or group to perform the CreateStream and PutMedia operations. This policy
is appropriate for a security camera that can create a video stream and send data to it.
{
"Statement": [
{
"Effect": "Allow",
"Action": [
"kinesisvideo:CreateStream",
"kinesisvideo:PutMedia"
],
"Resource": "*"
}
]
}
17
Amazon Kinesis Video Streams Developer Guide
Using Server-Side Encryption
Example 3: Allow a user full access to all Kinesis Video Streams resources
This policy allows a user or group to perform any Kinesis Video Streams operation on any resource. This
policy is appropriate for administrators.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "kinesisvideo:*",
"Resource": "*"
}
]
}
Example 4: Allow a user to write data to a specific Kinesis video stream
This policy allows a user or group to write data to a specific video stream. This policy is appropriate for a
device that can send data to a single stream.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "kinesisvideo:PutMedia",
"Resource": "arn:aws:kinesisvideo:us-west-2:123456789012:stream/
your_stream/0123456789012"
}
]
}
Using Server-Side Encryption with Kinesis Video
Streams
Server-side encryption using AWS Key Management Service (AWS KMS) keys makes it easier for you to
meet strict data management requirements by encrypting your data at rest in Amazon Kinesis Video
Streams.
Topics
•What Is Server-Side Encryption for Kinesis Video Streams? (p. 18)
•Costs, Regions, and Performance Considerations (p. 19)
•How Do I Get Started with Server-Side Encryption? (p. 19)
•Creating and Using User-Generated AWS KMS Master Keys (p. 20)
•Permissions to Use User-Generated AWS KMS Master Keys (p. 20)
What Is Server-Side Encryption for Kinesis Video
Streams?
Server-side encryption is a feature in Kinesis Video Streams that automatically encrypts data before it's
at rest by using an AWS KMS customer master key (CMK) that you specify. Data is encrypted before it is
18
Amazon Kinesis Video Streams Developer Guide
Costs, Regions, and Performance Considerations
written to the Kinesis Video Streams stream storage layer, and it is decrypted after it is retrieved from
storage. As a result, your data is always encrypted at rest within the Kinesis Video Streams service.
With server-side encryption, your Kinesis video stream producers and consumers don't need to manage
master keys or cryptographic operations. If data retention is enabled, your data is automatically
encrypted as it enters and leaves Kinesis Video Streams, so your data at rest is encrypted. AWS KMS
provides all the master keys that are used by the server-side encryption feature. AWS KMS makes it
easier to use a CMK for Kinesis Video Streams that is managed by AWS, a user-specified AWS KMS CMK,
or a master key imported into the AWS KMS service.
Costs, Regions, and Performance Considerations
When you apply server-side encryption, you are subject to AWS KMS API usage and key costs. Unlike
custom AWS KMS master keys, the (Default) aws/kinesis-video customer master key (CMK) is
offered free of charge. However, you still must pay for the API usage costs that Kinesis Video Streams
incurs on your behalf.
API usage costs apply for every CMK, including custom ones. The KMS costs scale with the number
of user credentials that you use on your data producers and consumers because each user credential
requires a unique API call to AWS KMS.
The following describes the costs by resource:
Keys
• The CMK for Kinesis Video Streams that's managed by AWS (alias = aws/kinesis-video) is free.
• User-generated AWS KMS keys are subject to AWS KMS key costs. For more information, see AWS Key
Management Service Pricing.
AWS KMS API Usage
API requests to generate new data encryption keys or to retrieve existing encryption keys increase
as traffic increases, and are subject to AWS KMS usage costs. For more information, see AWS Key
Management Service Pricing: Usage.
Kinesis Video Streams generates key requests even when retention is set to 0 (no retention).
Availability of Server-Side Encryption by Region
Server-side encryption of Kinesis video streams is available in all the AWS Regions where Kinesis Video
Streams is available.
How Do I Get Started with Server-Side Encryption?
Server-side encryption is always enabled on Kinesis video streams. If a user-provided key is not specified
when the stream is created, the default key (provided by Kinesis Video Streams) is used.
A user-provided AWS KMS master key must be assigned to a Kinesis video stream when it is created. You
can't later assign a different key to a stream using the UpdateStream API.
You can assign a user-provided AWS KMS master key to a Kinesis video stream in two ways:
• When creating a Kinesis video stream in the AWS Management Console, specify the AWS KMS master
key in the Encryption section on the Create new Kinesis Video stream page.
• When creating a Kinesis video stream using the CreateStream API, specify the key ID in the KmsKeyId
parameter.
19
Amazon Kinesis Video Streams Developer Guide
Creating and Using User-Generated AWS KMS Master Keys
Creating and Using User-Generated AWS KMS Master
Keys
This section describes how to create and use your own AWS KMS master keys instead of using the master
key administered by Amazon Kinesis Video Streams.
Creating User-Generated AWS KMS Master Keys
For information about how to create your own master keys, see Creating Keys in the AWS Key
Management Service Developer Guide. After you create keys for your account, the Kinesis Video Streams
service returns these keys in the KMS master key list.
Using User-Generated AWS KMS Master Keys
After the correct permissions are applied to your consumers, producers, and administrators, you can use
custom AWS KMS master keys in your own AWS account or another AWS account. All AWS KMS master
keys in your account appear in the KMS Master Key list on the console.
To use custom AWS KMS master keys that are located in another account, you must have permissions to
use those keys. You must also create the stream using the CreateStream API. You can't use AWS KMS
master keys from different accounts in streams created in the console.
Note
The AWS KMS key is not accessed until the PutMedia or GetMedia operation is executed. This
has the following results:
• If the key you specify doesn't exist, the CreateStream operation succeeds, but PutMedia
and GetMedia operations on the stream fail.
• If you use the provided master key (aws/kinesis-video), the key is not present in your
account until the first PutMedia or GetMedia operation is performed.
Permissions to Use User-Generated AWS KMS Master
Keys
Before you can use server-side encryption with a user-generated AWS KMS master key, you must
configure AWS KMS key policies to allow encryption of streams and encryption and decryption of stream
records. For examples and more information about AWS KMS permissions, see AWS KMS API Permissions:
Actions and Resources Reference.
Note
The use of the default service key for encryption does not require application of custom IAM
permissions.
Before you use user-generated AWS KMS master keys, ensure that your Kinesis video stream producers
and consumers (IAM principals) are users in the AWS KMS master key policy. Otherwise, writes and
reads from a stream will fail, which could ultimately result in data loss, delayed processing, or hung
applications. You can manage permissions for AWS KMS keys using IAM policies. For more information,
see Using IAM Policies with AWS KMS.
Example Producer Permissions
Your Kinesis video stream producers must have the kms:GenerateDataKey permission:
{
"Version": "2012-10-17",
20
Amazon Kinesis Video Streams Developer Guide
Data Model
"Statement": [
{
"Effect": "Allow",
"Action": [
"kms:GenerateDataKey"
],
"Resource": "arn:aws:kms:us-
west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab"
},
{
"Effect": "Allow",
"Action": [
"kinesis-video:PutMedia",
],
"Resource": "arn:aws:kinesis-video:*:123456789012:MyStream"
}
]
}
Example Consumer Permissions
Your Kinesis video stream consumers must have the kms:Decrypt permission:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": "arn:aws:kms:us-
west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab"
},
{
"Effect": "Allow",
"Action": [
"kinesis-video:GetMedia",
],
"Resource": "arn:aws:kinesis-video:*:123456789012:MyStream"
}
]
}
Kinesis Video Streams Data Model
The Producer Libraries (p. 31) and Stream Parser Library (p. 100) send and receive video data in a
format that supports embedding information alongside video data. This format is based on the Matroska
(MKV) specification.
The MKV format is an open specification for media data. All the libraries and code examples in the
Amazon Kinesis Video Streams Developer Guide send or receive data in the MKV format.
The Kinesis Video Streams Producer Libraries (p. 31) use the StreamDefinition and Frame types to
produce MKV stream headers, frame headers, and frame data.
For information about the full MKV specification, see Matroska Specifications.
The following sections describe the components of MKV-formatted data produced by the C++ Producer
Library (p. 41).
21
Amazon Kinesis Video Streams Developer Guide
Stream Header Elements
Topics
•Stream Header Elements (p. 22)
•Frame Header Elements (p. 25)
•MKV Frame Data (p. 25)
Stream Header Elements
The following MKV header elements are used by StreamDefinition (defined in
StreamDefinition.h).
Element Description Typical Values
stream_name Corresponds to the name of the
Kinesis video stream.
my-stream
retention_period The duration that stream data
is persisted by Kinesis Video
Streams. Specify 0 for a stream
that does not retain data.
24
tags A key-value collection of user
data. This data is displayed in
the AWS Management Console
and can be read by client
applications to filter or get
information about a stream.
kms_key_id If present, the user-defined AWS
KMS master key that is used to
encrypt data on the stream. If it
is absent, the data is encrypted
by the Kinesis-supplied master
key (aws/kinesis-video).
01234567-89ab-
cdef-0123-456789ab
streaming_type Currently, the only
valid streaming type is
STREAMING_TYPE_REALTIME.
STREAMING_TYPE_REALTIME
content_type The user-defined content type.
For streaming video data to play
in the console, the content type
must be video/h264.
video/h264
max_latency This value is not currently used
and should be set to 0.
0
fragment_duration The estimate of how long your
fragments should be, which
is used for optimization. The
actual fragment duration is
determined by the streaming
data.
2
timecode_scale Indicates the scale used by
frame time stamps. The default
is 1 millisecond. Specifying 0
22
Amazon Kinesis Video Streams Developer Guide
Stream Header Elements
Element Description Typical Values
also assigns the default value of
1 millisecond. This value can be
between 100 nanoseconds and 1
second.
For more information, see
TimecodeScale in the Matroska
documentation.
key_frame_fragmentation If true, the stream starts a
new cluster when a keyframe is
received.
true
frame_timecodes If true, Kinesis Video Streams
stamps the frames when they
are received. If false, Kinesis
Video Streams uses the decode
time of the received frames.
true
absolute_fragment_time If true, the cluster timecodes
are interpreted as using absolute
time (for example, from the
producer's system clock). If
false, the cluster timecodes are
interpreted as being relative to
the start time of the stream.
true
fragment_acks If true, acknowledgements
(ACKs) are sent when Kinesis
Video Streams receives
the data. The ACKs can
be received using the
KinesisVideoStreamFragmentAck
or
KinesisVideoStreamParseFragmentAck
callbacks.
true
restart_on_error Indicates whether the stream
should resume transmission
after a stream error is raised.
true
nal_adaptation_flags Indicates whether NAL (Network
Abstraction Layer) adaptation or
codec private data is present in
the content. Valid flags include
NAL_ADAPTATION_ANNEXB_NALS
and
NAL_ADAPTATION_ANNEXB_CPD_NALS.
NAL_ADAPTATION_ANNEXB_NALS
frame_rate An estimate of the content
frame rate. This value is used for
optimization; the actual frame
rate is determined by the rate
of incoming data. Specifying 0
assigns the default of 24.
24
23
Amazon Kinesis Video Streams Developer Guide
Stream Header Elements
Element Description Typical Values
avg_bandwith_bps An estimate of the content
bandwidth. This value is used for
optimization; the actual rate is
determined by the bandwidth of
incoming data. For example, for
a 720 p resolution video stream
running at 25 FPS, you can
expect the average bandwidth to
be 5 Mbps.
5
buffer_duration The duration that content is to
be buffered on the producer. If
there is low network latency, this
value can be reduced; if network
latency is high, increasing this
value prevents frames from
being dropped before they can
be sent, due to allocation failing
to put frames into the smaller
buffer.
replay_duration The amount of time the video
data stream is "rewound" in
the case of connection loss.
This value can be zero if lost
frames due to connection loss
are not a concern; the value can
be increased if the consuming
application can eliminate
redundant frames. This value
should be less than the buffer
duration; otherwise the buffer
duration is used.
connection_staleness The duration that a connection
is maintained when no data is
received.
codec_id The codec used by the content.
For more information, see
CodecID in the Matroska
specification.
V_MPEG2
track_name The user-defined name of the
track.
my_track
24
Amazon Kinesis Video Streams Developer Guide
Frame Header Elements
Element Description Typical Values
codecPrivateData Data provided by the encoder
used to decode the frame
data, such as the frame
width and height in pixels,
which is needed by many
downstream consumers. In the
C++ Producer Library (p. 41),
the gMkvTrackVideoBits
array in MkvStatics.cpp
includes pixel width and height
for the frame.
codecPrivateDataSize The size of the data in the
codecPrivateData parameter.
Frame Header Elements
The following MKV header elements are used by Frame (defined in the KinesisVideoPic package, in
mkvgen/Include.h):
•Frame Index: A monotonically increasing value.
•Flags: The type of frame. Valid values include the following:
•FRAME_FLAGS_NONE
•FRAME_FLAG_KEY_FRAME: If key_frame_fragmentation is set on the stream, key frames start a
new fragment.
•FRAME_FLAG_DISCARDABLE_FRAME: Tells the decoder that it can discard this frame if decoding is
slow.
•FRAME_FLAG_INVISIBLE_FRAME: Duration of this block is 0.
•Decoding Timestamp: The time stamp of when this frame was decoded. If previous frames depend
on this frame for decoding, this time stamp might be earlier than that of earlier frames. This value is
relative to the start of the fragment.
•Presentation Timestamp: The time stamp of when this frame is displayed. This value is relative to the
start of the fragment.
•Duration: The playback duration of the frame.
•Size: The size of the frame data in bytes
MKV Frame Data
The data in frame.frameData might contain only media data for the frame, or it might contain further
nested header information, depending on the encoding schema used. To be displayed in the AWS
Management Console, the data must be encoded in the H.264 codec, but Kinesis Video Streams can
receive time-serialized data streams in any format.
25
Amazon Kinesis Video Streams Developer Guide
Step 1: Set Up an Account
Getting Started with Kinesis Video
Streams
This section describes how to perform the following tasks in Amazon Kinesis Video Streams:
• Set up your AWS account and create an administrator, if you haven't already done so.
• Create a Kinesis video stream.
Other sections in this guide describe how to send data to the stream and view data on the stream.
If you are new to Amazon Kinesis Video Streams, we recommend that you read Amazon Kinesis Video
Streams: How It Works (p. 5) first.
Note
Following the Getting Started sample will not incur any charges to your AWS account. See
Amazon Kinesis Video Streams Pricing for data costs in your region.
Topics
•Step 1: Set Up an AWS Account and Create an Administrator (p. 26)
•Step 2: Create a Kinesis Video Stream (p. 27)
•What's Next? (p. 30)
Step 1: Set Up an AWS Account and Create an
Administrator
Before you use Kinesis Video Streams for the first time, complete the following tasks:
1. Sign Up for AWS (p. 26) (unless you already have an account)
2. Create an Administrator IAM User (p. 27)
Sign Up for AWS
If you already have an AWS account, you can skip this step.
When you sign up for Amazon Web Services (AWS), your AWS account is automatically signed up for all
services in AWS, including Kinesis Video Streams. When you use Kinesis Video Streams, you are charged
based on the amount of data ingested into, stored by, and consumed from the service. If you are a new
AWS customer, you can get started with Kinesis Video Streams for free. For more information, see AWS
Free Usage Tier.
To create an AWS account
1. Open https://aws.amazon.com/, and then choose Create an AWS Account.
Note
If you previously signed in to the AWS Management Console using AWS account root user
credentials, choose Sign in to a different account. If you previously signed in to the console
26
Amazon Kinesis Video Streams Developer Guide
Create an Administrator IAM User
using IAM credentials, choose Sign-in using root account credentials. Then choose Create
a new AWS account.
2. Follow the online instructions.
Part of the sign-up procedure involves receiving a phone call and entering a verification code using
the phone keypad.
Write down your AWS account ID because you need it for the next task.
Create an Administrator IAM User
When you sign up for AWS, you provide an email address and password that is associated with your AWS
account. This is your AWS account root user. Its credentials provide complete access to all of your AWS
resources.
Note
For security reasons, we recommend that you use the root user only to create an administrator,
which is an IAM user with full permissions to your AWS account. You can then use this
administrator to create other IAM users and roles with limited permissions. For more
information, see IAM Best Practices and Creating an Admin User and Group in the IAM User
Guide.
To create an administrator and sign into the console
1. Create an administrator in your AWS account. For instructions, see Creating Your First IAM User and
Administrators Group in the IAM User Guide.
2. As an administrator, you can sign in to the console using a special URL. For more information, see
How Users Sign in to Your Account in the IAM User Guide.
The administrator can create more users in the account. IAM users by default don't have any permissions.
The administrator can create users and manage their permissions. For more information, see Creating
Your First IAM User and Administrators Group.
For more information about IAM, see the following:
•AWS Identity and Access Management (IAM)
•Getting Started
•IAM User Guide
Next Step
Step 2: Create a Kinesis Video Stream (p. 27)
Step 2: Create a Kinesis Video Stream
This section describes how to create a Kinesis video stream.
This section contains the following procedures:
•the section called “Create a Video Stream Using the Console” (p. 28)
•the section called “Create a Video Stream Using the AWS CLI” (p. 30)
27
Amazon Kinesis Video Streams Developer Guide
Create a Video Stream Using the Console
Create a Video Stream Using the Console
1. Sign in to the AWS Management Console and open the Kinesis console at https://
console.aws.amazon.com/kinesis.
2. On the Manage streams page, choose Create.
3. On the Create new KinesisVideo Stream page, type ExampleStream for the stream name. Leave
the Use default settings check box selected.
28
Amazon Kinesis Video Streams Developer Guide
Create a Video Stream Using the Console
4. Choose Create stream.
5. After Kinesis Video Streams creates the stream, review the details on the ExampleStream page.
29
Amazon Kinesis Video Streams Developer Guide
Create a Video Stream Using the AWS CLI
Create a Video Stream Using the AWS CLI
1. Ensure that you have the AWS CLI installed and configured. For more information, see the AWS
Command Line Interface documentation.
2. Run the following Create-Stream command in the AWS CLI:
$ aws kinesisvideo create-stream --stream-name "MyKinesisVideoStream" --data-retention-
in-hours "24"
Next Step
What's Next? (p. 30)
What's Next?
After you have a video stream, you can start sending data to it from a Java application. In your code, use
Kinesis Video Streams options to configure your application to extract data from your media sources and
upload to your stream. For more information, see Using the Java Producer Library (p. 32).
30
Amazon Kinesis Video Streams Developer Guide
Kinesis Video Streams Producer Client
Kinesis Video Streams Producer
Libraries
The Amazon Kinesis Video Streams Producer libraries are a set of easy-to-use libraries that are part of
the Kinesis Video Streams Producer SDK. The client uses the libraries and SDK to build the on-device
application for securely connecting to Kinesis Video Streams and streaming video and other media data
that can be viewed in the console or client applications in real time.
Data can be streamed media in the following ways:
• Streaming media data in real time
• Streaming media data after buffering it for a few seconds
• Streaming after-the-fact media uploads
After you create a Kinesis Video Streams stream, you can start sending data to the stream. You can use
the SDK to create application code that extracts the video data (frames) from the media source and
uploads it to Kinesis Video Streams. These applications are also referred to as producer applications.
The Producer libraries contain the following components:
•Kinesis Video Streams Producer Client (p. 31)
•Kinesis Video Streams Producer Library (p. 32)
Kinesis Video Streams Producer Client
The Kinesis Video Streams Producer Client includes a single KinesisVideoClient class. This class
manages media sources, receives data from the sources, and manages the stream lifecycle as data flows
from a media source to Kinesis Video Streams. Furthermore, it provides a MediaSource interface for
defining the interaction between Kinesis Video Streams and your proprietary hardware and software.
A media source can be almost anything. For example, you can use a camera media source or a
microphone media source. Media sources are not limited to audio and video sources only. For example,
data logs might be text files, but they can still be sent as a stream of data. You could also have multiple
cameras on your phone that stream data simultaneously.
To get data from any of these sources, you can implement the MediaSource interface. This interface
enables additional scenarios for which we don’t provide built-in support. For example, you might choose
to send the following to Kinesis Video Streams:
• A diagnostic data stream (for example, application logs and events)
• Data from infrared cameras, RADARs, or depth cameras
Kinesis Video Streams does not provide built-in implementations for media-producing devices such
as cameras. To extract data from these devices, you must implement code, thus creating your own
31
Amazon Kinesis Video Streams Developer Guide
Kinesis Video Streams Producer Library
custom media source implementation. You can then explicitly register your custom media sources with
KinesisVideoClient, which uploads the data to Kinesis Video Streams.
The Kinesis Video Streams Producer Client is available for Java and Android applications. For
more information, see Using the Java Producer Library (p. 32) and Using the Android Producer
Library (p. 36).
Kinesis Video Streams Producer Library
The Kinesis Video Streams Producer Library is contained within the Kinesis Video Streams Producer
Client. The library is also available to use directly for those who want a deeper integration with Kinesis
Video Streams. It enables integration from devices with proprietary operating systems, network stacks,
or limited on-device resources.
The Kinesis Video Streams Producer Library implements the state machine for streaming to Kinesis Video
Streams. It provides callback hooks, which require that you provide your own transport implementation
and explicitly handle each message going to and from the service.
You might choose to use the Kinesis Video Streams Producer Library directly for the following reasons:
• The device on which you want to run the application doesn't have a Java virtual machine.
• You want to write application code in languages other than Java.
• You might have Java on the device, but you want to reduce the amount of overhead in your code and
limit it to the bare minimum level of abstraction, due to limitations such as memory and processing
power.
Currently, the Kinesis Video Streams Producer Library is available for C++ applications. For more
information, see Using the C++ Producer Library (p. 41).
Related Topics
Using the Java Producer Library (p. 32)
Using the Android Producer Library (p. 36)
Using the C++ Producer Library (p. 41)
Using the Java Producer Library
Amazon Kinesis Video Streams provides the Java Producer Library, which you can use to write application
code, with minimal configuration, to send media data from a device to a Kinesis video stream.
You must perform the following steps to integrate your code with Kinesis Video Streams, so that your
application can start streaming data to your Kinesis video stream:
1. Create an instance of the KinesisVideoClient object.
2. Create a MediaSource object by providing media source information. For example, when creating
a camera media source, you provide information such as identifying the camera and specifying the
encoding the camera uses.
When you want to start streaming, you must create a custom media source.
32
Amazon Kinesis Video Streams Developer Guide
Procedure: Using the Java Producer SDK
3. Register the media source with KinesisVideoClient.
After you register the media source with KinesisVideoClient, whenever the data becomes
available with the media source, it calls KinesisVideoClient with the data.
Procedure: Using the Java Producer SDK
This procedure demonstrates how to use the Kinesis Video Streams Java Producer Client in your Java
application to send data to your Kinesis video stream.
These steps don't require you to have a media source, such as a camera or microphone. Instead, for
testing purposes, the code generates sample frames that consist of a series of bytes. You can use the
same coding pattern when you send media data from real sources such as cameras and microphones.
The procedure includes the following steps:
•Download and Configure the Code
•Write and Examine the Code
•Run and Verify the Code
Prerequisites
• In the sample code, you provide credentials by specifying a profile that you set up in your AWS
credentials profile file. If you haven't already done so, first set up your credentials profile. For more
information, see Set up AWS Credentials and Region for Development in the AWS SDK for Java.
Note
The Java example uses a SystemPropertiesCredentialsProvider object to obtain
your AWS credentials. The provider retrieves these credentials from the aws.accessKeyId
and aws.secretKey Java system properties. You set these system properties in your Java
development environment. For information about how to set Java system properties, see the
documentation for your particular integrated development environment (IDE).
• Your NativeLibraryPath must contain your KinesisVideoProducerJNI file, available at https://
github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-cpp. The file name extension for
this file depends on your operating system:
•KinesisVideoProducerJNI.so for Linux
•KinesisVideoProducerJNI.dylib for macOS
•KinesisVideoProducerJNI.dll for Windows
Note
Pre-built libraries for macOS, Ubuntu, Windows, and Raspbian are available in src/main/
resources/lib. For other environments, compile the C++ Producer Library (p. 41).
Step 1: Download and Configure the Java Producer
Library Code
In this section of the Java Producer Library procedure, you download the Java example code, import the
project into your Java IDE, and configure the library locations.
For prerequisites and other details about this example, see Using the Java Producer Library.
1. Create a directory, and then clone the example source code from the GitHub repository.
33
Amazon Kinesis Video Streams Developer Guide
Step 2: Write and Examine the Code
$ git clone https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-java
2. Open the Java integrated development environment (IDE) that you use (for example, Eclipse or
JetBrains IntelliJ IDEA), and import the Apache Maven project that you downloaded:
•In IntelliJ IDEA: Choose Import. Navigate to the pom.xml file in the root of the downloaded
package.
•In Eclipse: Choose File, Import, Maven, Existing Maven Projects. Then navigate to the kinesis-
video-java-demo directory.
For more information, see the documentation for your IDE.
3. The Java example code uses the current AWS credentials. To use a different credentials profile,
locate the following code in DemoAppMain.java:
final KinesisVideoClient kinesisVideoClient = KinesisVideoJavaClientFactory
.createKinesisVideoClient(
Regions.US_WEST_2,
AuthHelper.getSystemPropertiesCredentialsProvider());
Change the code to the following:
final KinesisVideoClient kinesisVideoClient = KinesisVideoJavaClientFactory
.createKinesisVideoClient(
Regions.US_WEST_2,
new ProfileCredentialsProvider("credentials-profile-name"););
For more information, see ProfileCredentialsProvider in the AWS SDK for Java reference.
Next Step
the section called “Step 2: Write and Examine the Code” (p. 34)
Step 2: Write and Examine the Code
In this section of the Java Producer Library procedure, you write and examine the Java example code you
downloaded in the previous section.
The Java test application (DemoAppMain) shows the following coding pattern:
• Create an instance of KinesisVideoClient.
• Create an instance of MediaSource.
• Register the MediaSource with the client.
• Start streaming. That is, start the MediaSource, and it starts sending data to the client.
The following sections provide details.
Creating an Instance of KinesisVideoClient
You create the KinesisVideoClient object by calling the createKinesisVideoClient operation.
final KinesisVideoClient kinesisVideoClient = KinesisVideoJavaClientFactory
.createKinesisVideoClient(
34
Amazon Kinesis Video Streams Developer Guide
Step 3: Run and Verify the Code
Regions.US_WEST_2,
AuthHelper.getSystemPropertiesCredentialsProvider());
For KinesisVideoClient to make network calls, it needs credentials to authenticate. You pass in an
instance of SystemPropertiesCredentialsProvider, which reads AWSCredentials for the default
profile in the credentials file:
[default]
aws_access_key_id = ABCDEFGHIJKLMOPQRSTU
aws_secret_access_key = AbCd1234EfGh5678IjKl9012MnOp3456QrSt7890
Creating an Instance of MediaSource
To send bytes to your Kinesis video stream, you need to produce the data. Amazon Kinesis Video Streams
provides the MediaSource interface, which represents the data source.
For example, the Kinesis Video Streams Java library provides the ImageFileMediaSource
implementation of the MediaSource interface. This class only reads data from a series of media files
rather than a Kinesis video stream, but you can use it for testing the code.
final MediaSource bytesMediaSource = createImageFileMediaSource();
Registering the MediaSource with the Client
Register the media source that you created with the KinesisVideoClient so that it knows about the
client (and can then send data to the client).
kinesisVideoClient.registerMediaSource(STREAM_NAME, bytesMediaSource);
Starting the Media Source
Start the media source so that it can begin generating data and sending it to the client.
bytesMediaSource.start();
Next Step
the section called “Step 3: Run and Verify the Code” (p. 35)
Step 3: Run and Verify the Code
To run the Java test harness for the Java Producer library, do the following.
1. Choose DemoAppMain.
2. Choose Run, Run 'DemoAppMain'.
3. Add your credentials to the JVM arguments for the application:
•For non-temporary AWS credentials: "-Daws.accessKeyId={YourAwsAccessKey} -
Daws.secretKey={YourAwsSecretKey} -Djava.library.path={NativeLibraryPath}"
•For temporary AWS credentials: "-Daws.accessKeyId={YourAwsAccessKey} -
Daws.secretKey={YourAwsSecretKey} -Daws.sessionToken={YourAwsSessionToken}
-Djava.library.path={NativeLibraryPath}"
4. Sign in to the AWS Management Console and open the Kinesis Video Streams console.
35
Amazon Kinesis Video Streams Developer Guide
Android Producer Library
On the Manage Streams page, choose your stream.
5. The sample video will play in the embedded player. You might need to wait a short time (up to ten
seconds under typical bandwidth and processor conditions) while the frames accumulate before the
video appears.
The code example creates a stream. As the MediaSource in the code starts, it begins sending sample
frames to the KinesisVideoClient. The client then sends the data to your Kinesis video stream.
Using the Android Producer Library
Amazon Kinesis Video Streams provides the Android Producer Library, which you can use to write
application code, with minimal configuration, to send media data from an Android device to a Kinesis
video stream.
You must perform the following steps to integrate your code with Kinesis Video Streams so that your
application can start streaming data to your Kinesis video stream:
1. Create an instance of the KinesisVideoClient object.
2. Create a MediaSource object by providing media source information. For example, when creating
a camera media source, you provide information such as identifying the camera and specifying the
encoding the camera uses.
When you want to start streaming, you must create a custom media source.
Procedure: Using the Android Producer SDK
This procedure demonstrates how to use the Kinesis Video Streams Android Producer Client in your
Android application to send data to your Kinesis video stream.
The procedure includes the following steps:
•Download and Configure the Code
•Examine the Code
•Run and Verify the Code
Prerequisites
• We recommend Android Studio for examining, editing, and running the application code. We
recommend at least version 3.0.0, released October 2017.
• In the sample code, you provide Amazon Cognito credentials. Follow these procedures to set up an
Amazon Cognito user pool and identity pool:
To set up a user pool
1. Sign in to the Amazon Cognito console.
2. Choose Manage your User Pools.
3. Choose Create a user pool.
4. Type a value for Pool name; for example, <username>_android_user_pool.
5. Choose Review defaults.
6. Choose Create pool.
36
Amazon Kinesis Video Streams Developer Guide
Step 1: Download and Configure the Code
7. Copy and save the Pool Id value. You will need this value when you configure the example
application.
8. On the page for your pool, choose App clients.
9. Choose Add an app client.
10. Type a value for App client name; for example, <username>_android_app_client.
11. Choose Create app client.
12. Choose Show Details, and copy and save the App client ID and App client secret. You will need
these values when you configure the example application.
To set up an identity pool
1. Open the Amazon Cognito console.
2. Choose Manage Identity Pools.
3. Choose Create new identity pool.
4. Type a value for Identity pool name; for example, <username>_android_identity_pool.
5. Expand the Authentication providers section. On the Cognito tab, add the values for the User
Pool ID and App client ID from the previous procedure.
6. Choose Create pool.
7. On the next page, expand the Show Details section.
8. In the section that has a value for Role name that ends in Auth_Role, choose View Policy
Document.
9. Choose Edit, and confirm the Edit Policy dialog box that appears. Then copy the following JSON
and paste it into the editor:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"cognito-identity:*",
"kinesisvideo:*"
],
"Resource": [
"*"
]
}
]
}
10. Choose Allow.
11. On the next page, copy and save the Identity pool ID value from the Get AWS Credentials code
snippet. You will need this value when you configure the example application.
Step 1: Download and Configure the Android
Producer Library Code
In this section of the Android Producer Library procedure, you download the Android example code and
open the project in Android Studio.
For prerequisites and other details about this example, see Using the Android Producer Library.
1. Create a directory, and then clone the AWS Android SDK from the GitHub repository.
37
Amazon Kinesis Video Streams Developer Guide
Step 2: Examine the Code
$ git clone https://github.com/awslabs/aws-sdk-android-samples
2. Open Android Studio.
3. In the opening screen, choose Open an existing Android Studio project.
4. Navigate to the aws-sdk-android-samples/AmazonKinesisVideoDemoApp directory, and
choose OK.
5. Open the AmazonKinesisVideoDemoApp/src/main/res/raw/awsconfiguration.json file.
In the CredentialsProvider node, provide the identity pool ID from the To set up an identity
pool procedure in the Prerequisites section, and provide your AWS Region (for example, us-
west-2).
In the CognitoUserPool node, provide the App client secret, App client ID, and Pool ID from the
To set up a user pool procedure in the Prerequisites section, and provide your AWS Region (for
example, us-west-2).
6. Your awsconfiguration.json file will look similar to the following:
{
"Version": "1.0",
"CredentialsProvider": {
"CognitoIdentity": {
"Default": {
"PoolId": "us-west-2:01234567-89ab-cdef-0123-456789abcdef",
"Region": "us-west-2"
}
}
},
"IdentityManager": {
"Default": {}
},
"CognitoUserPool": {
"Default": {
"AppClientSecret": "abcdefghijklmnopqrstuvwxyz0123456789abcdefghijklmno",
"AppClientId": "0123456789abcdefghijklmnop",
"PoolId": "us-west-2_qRsTuVwXy",
"Region": "us-west-2"
}
}
}
7. Update the StreamingFragment.java file with your region:
try {
mKinesisVideoClient = KinesisVideoAndroidClientFactory.createKinesisVideoClient(
getActivity(),
KinesisVideoDemoApp.KINESIS_VIDEO_REGION,
KinesisVideoDemoApp.getCredentialsProvider());
For AWS region constants, see Regions.
Next Step
the section called “Step 2: Examine the Code” (p. 38)
Step 2: Examine the Code
In this section of the Android Producer Library procedure, you examine the example code.
38
Amazon Kinesis Video Streams Developer Guide
Step 2: Examine the Code
The Android test application (AmazonKinesisVideoDemoApp) shows the following coding pattern:
• Create an instance of KinesisVideoClient.
• Create an instance of MediaSource.
• Start streaming—that is, start the MediaSource, and it starts sending data to the client.
The following sections provide details.
Creating an Instance of KinesisVideoClient
You create the KinesisVideoClient object by calling the createKinesisVideoClient operation.
mKinesisVideoClient = KinesisVideoAndroidClientFactory.createKinesisVideoClient(
getActivity(),
KinesisVideoDemoApp.KINESIS_VIDEO_REGION,
KinesisVideoDemoApp.getCredentialsProvider());
For KinesisVideoClient to make network calls, it needs credentials to authenticate. You pass in
an instance of AWSCredentialsProvider, which reads your Amazon Cognito credentials from the
awsconfiguration.json file that you modified in the previous section.
Creating an Instance of MediaSource
To send bytes to your Kinesis video stream, you must produce the data. Amazon Kinesis Video Streams
provides the MediaSource interface, which represents the data source.
For example, the Kinesis Video Streams Android library provides the AndroidCameraMediaSource
implementation of the MediaSource interface. This class reads data from one of the device's cameras.
In the following code example (from the fragment/StreamConfigurationFragment.java file), the
configuration for the media source is created:
private AndroidCameraMediaSourceConfiguration getCurrentConfiguration() {
return new AndroidCameraMediaSourceConfiguration(
AndroidCameraMediaSourceConfiguration.builder()
.withCameraId(mCamerasDropdown.getSelectedItem().getCameraId())
.withEncodingMimeType(mMimeTypeDropdown.getSelectedItem().getMimeType())
.withHorizontalResolution(mResolutionDropdown.getSelectedItem().getWidth())
.withVerticalResolution(mResolutionDropdown.getSelectedItem().getHeight())
.withCameraFacing(mCamerasDropdown.getSelectedItem().getCameraFacing())
.withIsEncoderHardwareAccelerated(
mCamerasDropdown.getSelectedItem().isEndcoderHardwareAccelerated())
.withFrameRate(FRAMERATE_20)
.withRetentionPeriodInHours(RETENTION_PERIOD_48_HOURS)
.withEncodingBitRate(BITRATE_384_KBPS)
.withCameraOrientation(-
mCamerasDropdown.getSelectedItem().getCameraOrientation())
.withNalAdaptationFlags(StreamInfo.NalAdaptationFlags.NAL_ADAPTATION_ANNEXB_CPD_AND_FRAME_NALS)
.withIsAbsoluteTimecode(false));
}
In the following code example (from the fragment/StreamingFragment.java file), the media source
is created:
mCameraMediaSource = (AndroidCameraMediaSource) mKinesisVideoClient
39
Amazon Kinesis Video Streams Developer Guide
Step 3: Run and Verify the Code
.createMediaSource(mStreamName, mConfiguration);
Starting the Media Source
Start the media source so that it can begin generating data and sending it to the client. The following
code example is from the fragment/StreamingFragment.java file:
mCameraMediaSource.start();
Next Step
the section called “Step 3: Run and Verify the Code” (p. 40)
Step 3: Run and Verify the Code
To run the Android example application for the Android Producer Library, do the following.
1. Connect to an Android device.
2. Choose Run, Run..., and choose Edit configurations....
3. Choose +, Android App. In the Name field, enter AmazonKinesisVideoDemoApp. In the Module
pulldown, choose AmazonKinesisVideoDemoApp. Choose OK.
4. Choose Run, Run.
5. In the Select Deployment Target screen, choose your connected device, and choose OK.
6. In the AWSKinesisVideoDemoApp application on the device, choose Create new account.
7. Enter values for USERNAME, Password, Given name, Email address, and Phone number, and then
choose Sign up.
Note
These values have the following constraints:
•Password: Must contain uppercase and lowercase letters, numbers, and special
characters. You can change these constraints in your User pool page on the Amazon
Cognito console.
•Email address: Must be a valid address so that you can receive a confirmation code.
•Phone number: Must be in the following format: +<Country code><Number>, for
example, +12065551212 .
8. Enter the code you receive by email, and choose Confirm. Choose Ok.
9. On the next page, leave the default values, and choose Stream.
10. Sign in to the AWS Management Console and open the Kinesis Video Streams console at https://
console.aws.amazon.com/kinesisvideo/ in the US West (Oregon) Region.
On the Manage Streams page, choose demo-stream.
11. The streaming video plays in the embedded player. You might need to wait a short time (up to ten
seconds under typical bandwidth and processor conditions) while the frames accumulate before the
video appears.
Note
If the device's screen rotates (for example, from portrait to landscape), the application stops
streaming video.
The code example creates a stream. As the MediaSource in the code starts, it begins sending frames
from the camera to the KinesisVideoClient. The client then sends the data to a Kinesis video stream
named demo-stream.
40
Amazon Kinesis Video Streams Developer Guide
C++ Producer Library
Using the C++ Producer Library
Amazon Kinesis Video Streams provides the C++ Producer Library, which you can use to write application
code to send media data from a device to a Kinesis video stream.
Object Model
The C++ library provides the following objects to manage sending data to a Kinesis video stream:
•KinesisVideoProducer: Contains information about your media source and AWS credentials, and
maintains callbacks to report on Kinesis Video Streams events.
•KinesisVideoStream: Represents the Kinesis video stream. Contains information about the video
stream's parameters, such as name, data retention period, media content type, and so on.
Putting Media into the Stream
The C++ library provides methods (for example, PutFrame) that you can use to put data into the
KinesisVideoStream object. The library then manages the internal state of the data, which can
include the following tasks:
• Performing authentication.
• Watching for network latency. If the latency is too high, the library might choose to drop frames.
• Tracking status of streaming in progress.
Callback Interfaces
This layer exposes a set of callback interfaces, which enable it to talk to the application layer. These
callback interfaces include the following:
• Service callbacks interface (CallbackProvider): The library invokes events obtained through this
interface when it creates a stream, obtains a stream description, deletes a stream, and so on.
• Client-ready state or low storage events interface (ClientCallbackProvider): The library invokes
events on this interface when the client is ready, or when it detects that it might run out of available
storage or memory.
• Stream events callback interface (StreamCallbackProvider): The library invokes events on this
interface when stream events occur, such as the stream entering the ready state, dropped frames, or
stream errors.
Kinesis Video Streams provides default implementations for these interfaces. You can also provide your
own custom implementation—for example, if you need custom networking logic or you want to expose a
low storage condition to the user interface.
For more information about callbacks in the Producer Libraries, see Producer SDK Callbacks (p. 95).
Procedure: Using the C++ Producer SDK
This procedure demonstrates how to use the Kinesis Video Streams client and media sources in a C++
application to send data to your Kinesis video stream.
Note
The C++ library includes a sample build script for macOS. To use the C++ Producer Library on
Microsoft Windows, see Using the C++ Producer SDK on Windows (p. 49).
41
Amazon Kinesis Video Streams Developer Guide
Procedure: Using the C++ Producer SDK
To use the C++ Producer Library on a Raspberry Pi device, see Using the C++ Producer SDK on
Raspberry Pi (p. 53).
The procedure includes the following steps:
•Step 1: Download and Configure the Code
•Step 2: Write and Examine the Code
•Step 3: Run and Verify the Code
Prerequisites
•Credentials: In the sample code, you provide credentials by specifying a profile that you set up in your
AWS credentials profile file. If you haven't already done so, first set up your credentials profile.
For more information, see Set up AWS Credentials and Region for Development.
•Certificate store integration: The Kinesis Video Streams Producer Library must establish trust with
the service it calls. This is done through validating the certification authorities (CAs) in the public
certificate store. On Linux-based models, this store is located in the /etc/ssl/ directory.
Download the certificate from the following location to your certificate store:
https://www.amazontrust.com/repository/SFSRootCAG2.pem
• Install the following build dependencies for macOS:
•Autoconf 2.69 (License GPLv3+/Autoconf: GNU GPL version 3 or later)
•CMake 3.7 or 3.8
•Pkg-Config
•Flex 2.5.35 Apple (flex-31) or later
•Bison 2.4 (GNU License)
•Automake 1.15.1 (GNU License)
• GNU Libtool (Apple Inc. version cctools-898)
• xCode (macOS) / clang / gcc (xcode-select version 2347)
• Java Development Kit (JDK) (for Java JNI compilation)
•Lib-Pkg
• Install the following build dependencies for Ubuntu (responses to version commands are truncated):
• Install Git: sudo apt-get install git
$ git --version
git version 2.14.1
• Install CMake: sudo apt-get install cmake
$ cmake --version
cmake version 3.9.1
• Install Libtool: sudo apt-get install libtool
2.4.6-2
• Install libtool-bin: sudo apt-get install libtool-bin
$ libtool --version
libtool (GNU libtool) 2.4.6 42
Amazon Kinesis Video Streams Developer Guide
Step 1: Download and Configure the Code
Written by Gordon Matzigkeit, 1996
• Install GNU Automake: sudo apt-get install automake
$ automake --version
automake (GNU automake) 1.15
• Install GNU Bison: sudo apt-get install bison
$ bison -V
bison (GNU Bison) 3.0.4
• Install G++: sudo apt-get install g++
g++ --version
g++ (Ubuntu 7.2.0-8ubuntu3) 7.2.0
• Install curl: sudo apt-get install curl
$ curl --version
curl 7.55.1 (x86_64-pc-linux-gnu) libcurl/7.55.1 OpenSSL/1.0.2g zlib/1.2.11
libidn2/2.0.2 libpsl/0.18.0 (+libidn2/2.0.2) librtmp/2.3
• Install pkg-config: sudo apt-get install pkg-config
$ pkg-config --version
0.29.1
• Install Flex: sudo apt-get install flex
$ flex --version
flex 2.6.1
• Install OpenJDK: sudo apt-get install openjdk-8-jdk
$ java -version
openjdk version "1.8.0_171"
• Set the JAVA_HOME environment variable: export JAVA_HOME=/usr/lib/jvm/java-8-
openjdk-amd64/
• Run the build script: ./install-script
Next Step
Step 1: Download and Configure the C++ Producer Library Code
Step 1: Download and Configure the C++ Producer
Library Code
In this section, you download the low-level libraries and configure the application to use your AWS
credentials.
For prerequisites and other details about this example, see Using the C++ Producer Library.
1. Create a directory, and then clone the example source code from the GitHub repository.
43
Amazon Kinesis Video Streams Developer Guide
Step 2: Write and Examine the Code
$ git clone https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-cpp
2. Open the code in the integrated development environment (IDE) of your choice (for example,
Eclipse).
3. At the command line, set the ACCESS_KEY_ENV_VAR and SECRET_KEY_ENV_VAR environment
variables to your AWS credentials. Alternatively, you can hardcode your AWS credentials in the
following lines of ProducerTestFixture.h:
if (nullptr == (accessKey = getenv(ACCESS_KEY_ENV_VAR))) {
accessKey = "AccessKey";
}
if (nullptr == (secretKey = getenv(SECRET_KEY_ENV_VAR))) {
secretKey = "SecretKey";
}
4. In tst/ProducerTestFixture.h, find the call to CreateStream. Change the name of the stream
definition from ScaryTestStream2 to a unique name:
shared_ptr<KinesisVideoStream> CreateTestStream(int index) {
char stream_name[MAX_STREAM_NAME_LEN];
sprintf(stream_name, "ScaryTestStream_%d", index);
Next Step
Step 2: Write and Examine the Code (p. 44)
Step 2: Write and Examine the Code
In this section of the C++ Producer Library procedure, you examine the code in the C++ test harness
(tst/ProducerTestFixture.h and other files). You downloaded this code in the previous section.
The Platform Independent C++ example shows the following coding pattern:
• Create an instance of KinesisVideoProducer to access Kinesis Video Streams.
• Create an instance of KinesisVideoStream. This creates a Kinesis video stream in your AWS account
if a stream of the same name doesn't already exist.
• Call putFrame on the KinesisVideoStream for every frame of data, as it becomes available, to send
it to the stream.
The following sections provide details:
Creating an Instance of KinesisVideoProducer
You create the KinesisVideoProducer object by calling the
KinesisVideoProducer::createSync method. The following example creates the
KinesisVideoProducer in the ProducerTestFixture.h file:
kinesis_video_producer_ = KinesisVideoProducer::createSync(move(device_provider_),
move(client_callback_provider_),
move(stream_callback_provider_),
move(credential_provider_),
defaultRegion_);
44
Amazon Kinesis Video Streams Developer Guide
Step 2: Write and Examine the Code
The createSync method takes the following parameters:
• A DeviceInfoProvider object, which returns a DeviceInfo object containing information about
the device or storage configuration.
Note
You configure your content store size using the deviceInfo.storageInfo.storageSize
parameter. Your content streams share the content store. To determine your storage size
requirement, multiply the average frame size by the number of frames stored for the max
duration for all the streams. Then multiply by 1.2 to account for defragmentation. For
example, suppose that your application has the following configuration:
• Three streams
• 3 minutes of maximum duration
• Each stream is 30 frames per second (FPS)
• Each frame is 10,000 KB in size
The content store requirement for this application is 3 (streams) * 3 (minutes) * 60 (seconds
in a minute) * 10000 (kb) * 1.2 (defragmentation allowance) = 194.4 Mb ~ 200Mb.
• A ClientCallbackProvider object, which returns function pointers that report client-specific
events.
• A StreamCallbackProvider object, which returns function pointers that are called back when
stream-specific events occur.
• A CredentialProvider object, which provides access to AWS credential environment variables.
• The AWS Region ("us-west-2"). The service endpoint is determined from the Region.
Creating an Instance of KinesisVideoStream
You create the KinesisVideoStream object by calling the
KinesisVideoProducer::CreateStream method with a StreamDefinition parameter. The
example creates the KinesisVideoStream in the ProducerTestFixture.h file:
auto stream_definition = make_unique<StreamDefinition>(stream_name,
hours(2),
tags,
"",
STREAMING_TYPE_REALTIME,
"video/h264",
milliseconds::zero(),
seconds(2),
milliseconds(1),
true,
true,
true);
return kinesis_video_producer_->createStream(move(stream_definition));
The StreamDefinition object has the following fields:
• Stream name.
• Data retention period.
• Tags for the stream. These tags can be used by consumer applications to find the correct stream, or to
get more information about the stream. The tags can also be viewed in the AWS Management Console.
• AWS KMS encryption key for the stream. For more information, see Using Server-Side Encryption with
Kinesis Video Streams.
• Streaming type. Currently, the only valid value is STREAMING_TYPE_REALTIME.
• Media content type. To view the stream in the console viewer, set this value to "video/h264".
• Media latency. This value is not currently used, and should be set to 0.
45
Amazon Kinesis Video Streams Developer Guide
Step 2: Write and Examine the Code
• Playback duration of each fragment.
• Media timecode scale.
• Whether the media uses key frame fragmentation.
• Whether the media uses timecodes.
• Whether the media uses absolute fragment times.
Putting a Frame into the Kinesis Video Stream
You put media into the Kinesis video stream using KinesisVideoStream::putFrame, passing
in a Frame object that contains the header and media data. The example calls putFrame in the
ProducerApiTest.cpp file:
frame.duration = FRAME_DURATION_IN_MICROS * HUNDREDS_OF_NANOS_IN_A_MICROSECOND;
frame.size = SIZEOF(frameBuffer_);
frame.frameData = frameBuffer_;
MEMSET(frame.frameData, 0x55, frame.size);
while (!stop_producer_) {
// Produce frames
timestamp = std::chrono::duration_cast<std::chrono::nanoseconds>(
std::chrono::system_clock::now().time_since_epoch()).count() /
DEFAULT_TIME_UNIT_IN_NANOS;
frame.index = index++;
frame.decodingTs = timestamp;
frame.presentationTs = timestamp;
// Key frame every 50th
frame.flags = (frame.index % 50 == 0) ? FRAME_FLAG_KEY_FRAME : FRAME_FLAG_NONE;
...
EXPECT_TRUE(kinesis_video_stream->putFrame(frame));
Note
The preceding C++ Producer example sends a buffer of test data. In a real-world application,
you should obtain the frame buffer and size from the frame data from a media source (such as a
camera).
The Frame object has the following fields:
• Frame index. This should be a monotonically incrementing value.
• Flags associated with the frame. For example, if the encoder were configured to produce a key frame,
this frame would be assigned the FRAME_FLAG_KEY_FRAME flag.
• Decoding time stamp.
• Presentation time stamp.
• Duration of the frame (to 100 ns units).
• Size of the frame in bytes.
• Frame data.
For more information about the format of the frame, see Kinesis Video Streams Data Model.
Metrics and Metric Logging
The C++ Producer SDK includes functionality for metrics and metric logging.
You can use the getKinesisVideoMetrics and getKinesisVideoStreamMetrics API operations
to retrieve information about Kinesis Video Streams and your active streams.
46
Amazon Kinesis Video Streams Developer Guide
Step 2: Write and Examine the Code
The following code is from the kinesis-video-pic/src/client/include/com/amazonaws/
kinesis/video/client/Include.h file.
/**
* Gets information about the storage availability.
*
* @param 1 CLIENT_HANDLE - the client object handle.
* @param 2 PKinesisVideoMetrics - OUT - Kinesis Video metrics to be filled.
*
* @return Status of the function call.
*/
PUBLIC_API STATUS getKinesisVideoMetrics(CLIENT_HANDLE, PKinesisVideoMetrics);
/**
* Gets information about the stream content view.
*
* @param 1 STREAM_HANDLE - the stream object handle.
* @param 2 PStreamMetrics - Stream metrics to fill.
*
* @return Status of the function call.
*/
PUBLIC_API STATUS getKinesisVideoStreamMetrics(STREAM_HANDLE, PStreamMetrics);
The PClientMetrics object filled by getKinesisVideoMetrics contains the following information:
•contentStoreSize: The overall size in bytes of the content store (the memory used to store streaming
data).
•contentStoreAvailableSize: The free memory in the content store, in bytes.
•contentStoreAllocatedSize: The allocated memory in the content store.
•totalContentViewsSize: The total memory used for the content view. (The content view is a series of
indices of information in the content store.)
•totalFrameRate: The aggregate number of frames per second across all active streams.
•totalTransferRate: The total bits per second (bps) being sent in all streams.
The PStreamMetrics object filled by getKinesisVideoStreamMetrics contains the following
information:
•currentViewDuration: The difference in 100 ns units between the head of the content view (when
frames are encoded) and the current position (when frame data is being sent to Kinesis Video
Streams).
•overallViewDuration: The difference in 100 ns units between the head of the content view (when
frames are encoded) to the tail (when frames are flushed from memory, either because the total
allocated space for the content view is exceeded, or because a PersistedAck message is received
from Kinesis Video Streams, and frames known to be persisted are flushed).
•currentViewSize: The size in bytes of the content view from the head (when frames are encoded) to
the current position (when frames are sent to Kinesis Video Streams).
•overallViewSize: The total size in bytes of the content view.
•currentFrameRate: The last measured rate of the stream, in frames per second.
•currentTransferRate: The last measured rate of the stream, in bytes per second.
Next Step
the section called “Step 3: Run and Verify the Code” (p. 48)
47
Amazon Kinesis Video Streams Developer Guide
Step 3: Run and Verify the Code
Step 3: Run and Verify the Code
To run and verify the code for the C++ Producer Library procedure, do the following:
1. See Prerequisites for credential, certificate, and build requirements.
2. Build the project by using the /kinesis-video-native-build/install-script script.
Running the install script installs the following open source dependencies:
•curl lib
•openssl (crypto and ssl)
•log4cplus
•jsoncpp
Note
To configure log4cplus, set the following value in PlatformUtils.h to point to your
logging function:
#define __LOG(p1, p2, p3, ...) printf(p3, ##__VA_ARGS__)
3. The executable is built in kinesis-video-native-build/start. Launch it to run the unit test
and kick off dummy frame streaming.
4. To enable verbose logs, define the HEAP_DEBUG and LOG_STREAMING C-defines by uncommenting
the appropriate lines in CMakeList.txt.
You can monitor the progress of the test suite in the debug output in your IDE. You can also monitor
the traffic on your stream by watching the metrics that are associated with your stream in the Amazon
CloudWatch console, such as PutMedia.IncomingBytes.
Note
Because the test harness only sends frames of empty bytes, the console doesn't display the data
as a video stream.
Using the C++ Producer SDK as a GStreamer Plugin
GStreamer is a popular media framework used by a multitude of cameras and video sources to create
custom media pipelines by combining modular plugins. The Kinesis Video Streams GStreamer plugin
greatly simplifies the integration of your existing GStreamer media pipeline with Kinesis Video Streams.
For information about using the C++ Producer SDK as a GStreamer plugin, see Example: Kinesis Video
Streams Producer SDK GStreamer Plugin (p. 108).
Using the C++ Producer SDK as a GStreamer Plugin in
a Docker Container
GStreamer is a popular media framework used by a multitude of cameras and video sources to create
custom media pipelines by combining modular plugins. The Kinesis Video Streams GStreamer plugin
greatly simplifies the integration of your existing GStreamer media pipeline with Kinesis Video Streams.
In addition, using Docker to create the GStreamer pipeline standardizes the operating environment for
Kinesis Video Streams, which greatly simplifies building and executing the application.
For information about using the C++ Producer SDK as a GStreamer plugin in a Docker container, see Run
the GStreamer Element in a Docker Container (p. 111).
48
Amazon Kinesis Video Streams Developer Guide
Using the C++ Producer SDK on Windows
Using the C++ Producer SDK on Windows
This tutorial demonstrates how to build and run the Producer Libraries (p. 31) on Microsoft Windows.
You can then stream video to Kinesis Video Streams from sources such as webcams, USB cameras, or
RTSP (Real Time Streaming Protocol) cameras. When you start streaming from your media source to a
Kinesis video stream, you can view the video in the Kinesis Video Streams console. You can also build
applications that operate on the streaming video that is available in your Kinesis video stream.
Topics
•Building and Running the Producer SDK: Minimalist GNU for Windows (MinGW) (p. 49)
•Building and Running the Producer SDK: Microsoft Visual C++ Compiler (MSVC) (p. 51)
Building and Running the Producer SDK: Minimalist GNU for
Windows (MinGW)
Minimalist GNU for Windows (MinGW) is an open-source programming toolchain for developing native
Windows applications. You can use MinGW to build the Kinesis Video Streams Producer SDK for Windows
and then run one of the sample applications to start streaming video.
This section describes prerequisites and steps needed to build the Amazon Kinesis Video Streams
Producer SDK using the MinGW compiler.
Prerequisites
Before you start, ensure that you have the following:
• Download and install the MSYS2 version for your specific Windows platform. MSYS2 provides all the
tools to build native Windows applications using MinGW toolchains.
Building the Producer SDK Using MinGW
Follow these steps to use the MinGW runtime environment to compile the Kinesis Video
StreamsProducer SDK on Windows.
1. Launch the MinGW shell (mingw64.exe) from the C:\msys32 or C:\msys64 directory. Make
sure that you are opening the mingw64.exe or mingw32.exe based on your platform, and not the
MSYS2 application. The MSYS2 application is the default application that is opened after you finish
installing MSYS2.
2. Install Git by running the following command in the MinGW shell:
pacman -S git
3. Download the Kinesis Video Streams Producer SDK from GitHub:
git clone https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-cpp.git
4. Navigate to the amazon-kinesis-video-streams-producer-sdk-cpp/kinesis-video-
native-build directory, and run the following install script to build the Producer SDK:
./msys2-install-script -a
Note
• Accept all of the prompts when the script runs.
49
Amazon Kinesis Video Streams Developer Guide
Using the C++ Producer SDK on Windows
• Log4cplus is compiled from source, but all other components are downloaded as pre-built
binaries.
Running the Producer SDK to Send Video to Kinesis Video Streams
After compiling the Kinesis Video Streams Producer SDK using MinGW, follow these steps to run it:
Step 1: Set Environment Variables
• In the MinGW shell, set the following environment variables:
export AWS_ACCESS_KEY_ID=YOUR_ACCESS_KEY
export AWS_SECRET_ACCESS_KEY=YOUR_SECRET_ACCESS_KEY
export GST_PLUGIN_PATH=$PWD
Note
YOUR_ACCESS_KEY and YOUR_SECRET_ACCESS_KEY are the access keys for your
AWS account used for signing programmatic requests that you make to AWS. For more
information, see Managing Access Keys for IAM Users.
Step 2: Run the Sample Application for Your Media Source
1. To stream video from your PC webcam, run the sample application from the kinesis-video-
native-build directory using the following command:
kinesis_video_gstreamer_sample_app.exe my-stream-name
2. To stream video from your PC webcam using a custom configuration, such as a specific bitrate
or resolution, run the Kinesis Video Streams Producer SDK GStreamer plugin using the gst-
launch-1.0 command:
gst-launch-1.0 ksvideosrc do-timestamp=TRUE ! video/x-
raw,width=640,height=480,framerate=30/1 ! videoconvert ! x264enc bframes=0
key-int-max=45 bitrate=512 ! video/x-h264,profile=baseline,stream-
format=avc,alignment=au,width=640,height=480,framerate=30/1 ! kvssink stream-
name="your-stream-name" access-key=your_accesskey_id secret-key=your_secret_access_key
For information about how to determine the parameters for the gst-launch-1.0 command, see
GStreamer Element Parameter Reference (p. 113).
Note
If you are using IoT credentials instead of your access key and secret key to authenticate,
you can supply IoT credentials as parameters to the gst-launch-1.0 command.
The following example demonstrates using IoT parameters to stream video from an RTSP
camera:
gst-launch-1.0 rtspsrc location=rtsp://YourCameraRtspUrl short-header=TRUE !
rtph264depay ! video/x-h264, format=avc,alignment=au ! kvssink stream-
name="your-iot-stream" iot-certificate="iot-certificate,endpoint=endpoint,cert-
path=/path/to/certificate,key-path=/path/to/private/key,ca-path=/path/to/ca-
cert,role-aliases=role-aliases"
3. To stream video from an RTSP (network) camera, run the sample application from the kinesis-
video-native-build directory using the following command:
kinesis_video_gstreamer_sample_rtsp_app.exe RTSP-camera-URL my-test-rtsp-stream
50
Amazon Kinesis Video Streams Developer Guide
Using the C++ Producer SDK on Windows
Building and Running the Producer SDK: Microsoft Visual C++
Compiler (MSVC)
The Microsoft Visual C++ Compiler (MSVC) is the compiler for Microsoft Visual Studio. The following
sections include the prerequisites and steps that are required to build the Kinesis Video Streams Producer
SDK using MSVC.
Prerequisites
Before you start, ensure that you have the following:
• Microsoft Windows version 7 or later.
•Microsoft .NET Framework version 4.6.1 or later.
• Windows PowerShell version 5.1 (included in Windows 10). On Windows 7, update Windows
PowerShell.
•Git. In the Adjusting your PATH environment installation step, choose Use Git from the Windows
Command Prompt.
Building the Producer SDK Using MSVC
Follow these steps to use MSVC to compile the Producer SDK on Windows.
Note
If you previously installed the Producer SDK for Windows using MinGW, do the following
cleanup steps before building the SDK using MSVC:
• Delete the files in the kinesis-video-native-build/downloads directory.
• Remove the CMakeFiles directory and the CMakeCachedList.txt file in the kinesis-
video-native-build directory.
1. Open a Windows command prompt as an administrator.
2. Download the Producer SDK:
git clone https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-cpp.git
3. After the download is complete, change to the kinesis-video-native-build directory within
the downloaded project.
4. Run the Visual Studio build tools install script:
vs-buildtools-install.bat
5. After the install script completes, if you are using Windows 10 or Windows 7, reboot your computer.
Then re-open a Windows command prompt as an administrator.
6. In the kinesis-video-native-build directory, run windows-install.bat, specifying your
system's bit width (32 or 64):
windows-install.bat 32
or
windows-install.bat 64
Note
This script builds the following components:
• The C++ Producer Library (p. 41) libraries.
51
Amazon Kinesis Video Streams Developer Guide
Using the C++ Producer SDK on Windows
• The C++ Producer SDK GStreamer (p. 108) (kvssink).
• The ??? (p. 119) demo, which shows how to stream data from an RTSP (network)
camera.
Running the Producer SDK to Send Video to Kinesis Video Streams
After compiling the Kinesis Video Streams Producer SDK using MSVC, follow these steps to run it as a
GStreamer plugin.
You have several options for starting the SDK. We recommend that you use the GStreamer (p. 108),
which you can run using the example executables available in the kinesis-video-native-build/
start directory.
1. Add the following directories to your path (specify the location for the Producer SDK, including the
drive):
set PATH=%PATH%;install directory\amazon-kinesis-video-streams-producer-sdk-cpp
\kinesis-video-native-build\downloads\gstreamer\1.0\x86_64\bin;
2. Set the following environment variables (replace install directory with the location for the
Producer SDK, including the drive):
set GST_PLUGIN_PATH=install directory\amazon-kinesis-video-streams-producer-sdk-cpp
\kinesis-video-native-build\Release
set GST_PLUGIN_SYSTEM_PATH=install directory\amazon-kinesis-video-streams-producer-sdk-
cpp\kinesis-video-native-build\downloads\gstreamer\1.0\x86_64\lib\gstreamer-1.0
3. Stream video from the webcam on the PC to the Kinesis Video Streams service using the gst-
launch-1.0 command:
gst-launch-1.0 ksvideosrc do-timestamp=TRUE ! video/x-
raw,width=640,height=480,framerate=30/1 ! videoconvert ! x264enc bframes=0
key-int-max=45 bitrate=512 ! video/x-h264,profile=baseline,stream-
format=avc,alignment=au,width=640,height=480,framerate=30/1 ! kvssink stream-
name="your-stream-name" access-key=your_accesskey_id secret-key=your_secret_access_key
For information about how to determine the parameters for the gst-launch-1.0 command, see
GStreamer Element Parameter Reference (p. 113).
Note
If you are using IoT credentials instead of your access key and secret key, you can
supply them as parameters to the gst-launch-1.0 command. The following example
demonstrates using IoT parameters to stream video from an RTSP camera:
gst-launch-1.0 rtspsrc location=rtsp://YourCameraRtspUrl short-header=TRUE !
rtph264depay ! video/x-h264, format=avc,alignment=au ! kvssink stream-
name="your-iot-stream" iot-certificate="iot-certificate,endpoint=endpoint,cert-
path=/path/to/certificate,key-path=/path/to/private/key,ca-path=/path/to/ca-
cert,role-aliases=role-aliases"
4. Alternatively, you can set the following environment variables and use one of our pre-build sample
applications.
export AWS_ACCESS_KEY_ID=YOUR_ACCESS_KEY
export AWS_SECRET_ACCESS_KEY=YOUR_SECRET_ACCESS_KEY
5. To stream video from a PC webcam, run the sample application from the kinesis-video-
native-build\Release directory using the following command:
52
Amazon Kinesis Video Streams Developer Guide
Using the C++ Producer SDK on Raspberry Pi
kinesis_video_gstreamer_sample_app.exe my-stream-name
6. To stream video from an RTSP (network) camera, run the sample application from the kinesis-
video-native-build\Release directory using the following command:
kinesis_video_gstreamer_sample_rtsp_app.exe RTSP-camera-URL my-test-rtsp-stream
Using the C++ Producer SDK on Raspberry Pi
The Raspberry Pi is a small, inexpensive computer that can be used to teach and learn basic computer
programming skills. This tutorial describes how you can set up and use the Amazon Kinesis Video
Streams C++ Producer SDK on a Raspberry Pi device. The steps also include how to verify the installation
using the GStreamer demo application.
Topics
•Prerequisites (p. 53)
•Create an IAM User with Permission to Write to Kinesis Video Streams (p. 54)
•Join Your Raspberry Pi to Your Wi-Fi Network (p. 55)
•Connect Remotely to Your Raspberry Pi (p. 55)
•Configure the Raspberry Pi Camera (p. 56)
•Install Software Prerequisites (p. 56)
•Download and Build the Kinesis Video Streams C++ Producer SDK (p. 57)
•Stream Video to Your Kinesis Video Stream and View the Live Stream (p. 57)
Prerequisites
Before you set up the C++ Producer SDK on your Raspberry Pi, ensure that you have the following
prerequisites:
• A Raspberry Pi device with the following configuration:
• Board version: 3 Model B or later.
• A connected camera module.
• An SD card with a capacity of at least 8 GB.
• The Raspbian operating system (kernel version 4.9 or later) installed. You can download the latest
Raspbian image from the Raspberry Pi Foundation website. Follow the Raspberry Pi instructions to
install the downloaded image on an SD card.
• An AWS account with a Kinesis video stream. For more information, see Getting Started with Kinesis
Video Streams.
Note
The C++ Producer SDK uses the US West (Oregon) (us-west-2) Region by default. To use the
default AWS Region, create your Kinesis video stream in the US West (Oregon) Region.
To use a different Region for your Kinesis video stream, do one of the following:
• Set the following environment variable to your Region (for example, us-east-1):
export AWS_DEFAULT_REGION=us-east-1
• After downloading the source code (see the section called “Download and Build the
Kinesis Video Streams C++ Producer SDK” (p. 57)), change the following values in the
53
Amazon Kinesis Video Streams Developer Guide
Using the C++ Producer SDK on Raspberry Pi
amazon-kinesis-video-streams-producer-sdk-cpp/kinesis-video-producer/
DefaultCallbackProvider.h file to your Region:
const std::string DEFAULT_AWS_REGION = "us-east-1";
const std::string KINESIS_VIDEO_SERVICE_NAME = "kinesisvideo";
const std::string DEFAULT_CONTROL_PLANE_URI = "https://kinesisvideo.us-
east-1.amazonaws.com";
Create an IAM User with Permission to Write to Kinesis Video
Streams
If you haven't already done so, set up an AWS Identity and Access Management (IAM) user with
permissions to write to a Kinesis video stream.
1. Sign in to the AWS Management Console and open the IAM console at https://
console.aws.amazon.com/iam/.
2. In the navigation menu on the left, choose Users.
3. To create a new user, choose Add user.
4. Provide a descriptive User name for the user, such as kinesis-video-raspberry-pi-producer.
5. Under Access type, choose Programmatic access.
6. Choose Next: Permissions.
7. Under Set permissions for kinesis-video-raspberry-pi-producer, choose Attach existing policies
directly.
8. Choose Create policy. The Create policy page opens in a new web browser tab.
9. Choose the JSON tab.
10. Copy the following JSON policy and paste it into the text area. This policy gives your user permission
to create and write data to Kinesis video streams.
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"kinesisvideo:DescribeStream",
"kinesisvideo:CreateStream",
"kinesisvideo:GetDataEndpoint",
"kinesisvideo:PutMedia"
],
"Resource": [
"*"
]
}]
}
11. Choose Review policy.
12. Provide a Name for your policy, such as kinesis-video-stream-write-policy.
13. Choose Create policy.
14. Return to the Add user tab in your browser, and choose Refresh.
15. In the search box, type the name of the policy you created.
16. Select the check box next to your new policy in the list.
17. Choose Next: Review.
18. Choose Create user.
54
Amazon Kinesis Video Streams Developer Guide
Using the C++ Producer SDK on Raspberry Pi
19. The console displays the Access key ID for your new user. Choose Show to display the Secret access
key. Record these values; they are required when you configure the application.
Join Your Raspberry Pi to Your Wi-Fi Network
You can use the Raspberry Pi in headless mode, that is, without an attached keyboard, monitor, or
network cable. If you are using an attached monitor and keyboard, proceed to Configure the Raspberry
Pi Camera (p. 56).
1. On your computer, create a file named wpa_supplicant.conf.
2. Copy the following text and paste it into the wpa_supplicant.conf file:
country=US
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
network={
ssid="<YOUR_WIFI_SSID>"
scan_ssid=1
key_mgmt=WPA-PSK
psk="<YOUR_WIFI_PASSWORD>"
}
Replace the ssid and psk values with the information for your Wi-Fi network.
3. Copy the wpa_supplicant.conf file to the SD card. It must be copied to the root of the boot
volume.
4. Insert the SD card into the Raspberry Pi, and power the device. It joins your Wi-Fi network, and SSH
is enabled.
Connect Remotely to Your Raspberry Pi
You can connect remotely to your Raspberry Pi in headless mode. If you are using your Raspberry Pi with
a connected monitor and keyboard, proceed to Configure the Raspberry Pi Camera (p. 56).
1. Before connecting to your Raspberry Pi device remotely, do one of the following to determine its IP
address:
• If you have access to your network's Wi-Fi router, look at the connected Wi-Fi devices. Find the
device named Raspberry Pi to find your device's IP address.
• If you don't have access to your network's Wi-Fi router, you can use other software to find devices
on your network. Fing is a popular application that is available for both Android and iOS devices.
You can use the free version of this application to find the IP addresses of devices on your
network.
2. When you know the IP address of the Raspberry Pi device, you can use any terminal application to
connect.
• On macOS or Linux, use ssh:
$ ssh pi@<IP address>
• On Windows, use PuTTY, a free SSH client for Windows.
For a new installation of Raspbian, the user name is pi, and the password is raspberry. We
recommend that you change the default password.
55
Amazon Kinesis Video Streams Developer Guide
Using the C++ Producer SDK on Raspberry Pi
Configure the Raspberry Pi Camera
Follow these steps to configure the Raspberry Pi camera to send video from the device to a Kinesis video
stream.
1. Open an editor to update the modules file with the following command:
$ sudo nano /etc/modules
2. Add the following line to the end of the file, if it's not already there:
bcm2835-v4l2
3. Save the file and exit the editor (Ctrl-X).
4. Reboot the Raspberry Pi:
$ sudo reboot
5. When the device reboots, connect to it again through your terminal application if you are connecting
remotely.
6. Open raspi-config:
$ sudo raspi-config
7. Choose Interfacing Options, Camera. Enable the camera if it's not already enabled, and reboot if
prompted.
8. Verify that the camera is working by typing the following command:
$ raspistill -v -o test.jpg
The display shows a five-second preview from the camera, takes a picture (saved to test.jpg), and
displays informational messages.
Install Software Prerequisites
The C++ Producer SDK requires that you install the following software prerequisites on Raspberry Pi.
1. Install Git:
$ sudo apt-get update
$ sudo apt-get install git
2. Install Yacc, Lex, and OpenJDK (Open Java Development Kit):
$ sudo apt-get install byacc flex
$ sudo apt-get install openjdk-8-jdk
3. Set the JAVA_HOME environment variable:
$ export JAVA_HOME=/usr/lib/jvm/java-1.8.0-openjdk-armhf/
Note
If you reboot the device before building the SDK, you must repeat this step. You can also set
this environment variable in your ~/.profile file.
56
Amazon Kinesis Video Streams Developer Guide
Using the C++ Producer SDK on Raspberry Pi
4. CMake is used to build the SDK. Install CMake with the following command:
$ sudo apt-get install cmake
5. Copy the following PEM file to /etc/ssl/cert.pem:
https://www.amazontrust.com/repository/SFSRootCAG2.pem
Download and Build the Kinesis Video Streams C++ Producer
SDK
1. Install the C++ Producer SDK:
$ git clone https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-cpp
2. Change your current working directory to the install directory:
$ cd amazon-kinesis-video-stream-producer-sdk-cpp/kinesis-video-native-build
3. Make the install script executable:
$ chmod +x install-script
4. Run the install script. The script downloads the source and builds several open-source projects. It
might take several hours to run the first time it is executed:
$ ./install-script
5. Type Y to verify. Then the build script runs.
Stream Video to Your Kinesis Video Stream and View the Live
Stream
1. To run the sample application, you need the following information:
• The name of the stream you created in the Prerequisites (p. 53) section.
• The account credentials (access key ID and secret access key) that you created in Create an IAM
User with Permission to Write to Kinesis Video Streams (p. 54).
2. Run the sample application using the following command:
$ export AWS_ACCESS_KEY_ID=<Access Key ID>
export AWS_SECRET_ACCESS_KEY=<Secret Access Key>
./kinesis_video_gstreamer_sample_app Stream Name
3. You can specify the image size, framerate, and bitrate as follows:
$ export AWS_ACCESS_KEY_ID=<Access Key ID>
export AWS_SECRET_ACCESS_KEY=<Secret Access Key>
./kinesis_video_gstreamer_sample_app -w <width> -h <height> -f <framerate>
-b <bitrateInKBPS> Stream Name
4. If the sample application exits with a library not found error, type the following commands to
verify that the project is correctly linked to its open-source dependencies:
57
Amazon Kinesis Video Streams Developer Guide
Using Logging
$ rm -rf ./kinesis-video-native-build/CMakeCache.txt ./kinesis-video-native-build/
CMakeFiles
$ ./kinesis-video-native-build/install-script
5. Open the Kinesis Video Streams console at https://console.aws.amazon.com/kinesisvideo/.
6. Choose the Stream name of the stream you created.
The video stream that is sent from the Raspberry Pi appears in the console.
When the stream is playing, you can experiment with the following features of the Kinesis Video Streams
console:
• In the Video preview section, use the navigation controls to rewind or fast-forward the stream.
• In the Stream info section, notice the codec, resolution, and bitrate of the stream. The resolution
and bitrate values are set purposefully low on the Raspberry Pi to minimize bandwidth usage for this
tutorial. To view the Amazon CloudWatch metrics that are being created for your stream, choose View
stream metrics in CloudWatch.
• Under Data retention period, notice that the video stream is retained for one day. You can edit this
value and set it to No data retention, or set a value from one day to several years.
Under server-side encryption, notice that your data is being encrypted at rest using a key maintained
by the AWS Key Management Service (AWS KMS).
Using Logging with the C++ Producer SDK
You configure logging for C++ Producer SDK applications in the kvs_log_configuration file in the
kinesis-video-native-build folder.
The following example shows the first line of the default configuration file, which configures the
application to write DEBUG-level log entries to the AWS Management Console:
log4cplus.rootLogger=DEBUG, KvsConsoleAppender
You can set the logging level to INFO for less verbose logging.
To configure the application to also write log entries to a log file, update the first line in the file to the
following:
log4cplus.rootLogger=DEBUG, KvsConsoleAppender, KvsFileAppender
This configures the application to write log entries to kvs.log in the kinesis-video-native-
build/log folder.
To change the log file location, update the following line with the new path:
log4cplus.appender.KvsFileAppender.File=./log/kvs.log
Note
If DEBUG-level logging is written to a file, the log file can use up the available storage space on
the device quickly.
58
Amazon Kinesis Video Streams Developer Guide
Reference
Producer SDK Reference
This section contains limits, error codes, and other reference information for the Kinesis Video Streams
Producer Libraries (p. 31).
Topics
•Producer SDK Limits (p. 59)
•Error Code Reference (p. 61)
•Network Abstraction Layer (NAL) Adaptation Flag Reference (p. 81)
•Producer SDK Structures (p. 82)
•Kinesis Video Stream Structures (p. 83)
•Producer SDK Callbacks (p. 95)
Producer SDK Limits
The following table contains the current limits for values in the Producer Libraries (p. 31).
Note
Before setting these values, you must validate your inputs. The SDK doesn't validate these
limits, and a runtime error occurs if the limits are exceeded.
Value Limit Notes
Max stream count 128 The maximum number of
streams that a producer object
can create. This is a soft limit
(you can request an increase).
It ensures that the producer
doesn't accidentally create
streams recursively.
Max device name length 128 characters
Max tag count 50 per stream
Max stream name length 256 characters
Min storage size 10 MiB = 10 * 1024 * 1024 bytes
Max storage size 10 GiB = 10 * 1024 * 1024 *
1024 bytes
Max root directory path length 4,096 characters
Max auth info length 10,000 bytes
Max URI string length 10,000 characters
Max tag name length 128 characters
Max tag value length 1,024 characters
Min security token period 30 seconds
Security token grace period 40 minutes If the specified duration is
longer, it is limited to this value.
59
Amazon Kinesis Video Streams Developer Guide
Producer SDK Limits
Value Limit Notes
Retention period 0 or greater than one hour 0 indicates no retention.
Min cluster duration 1 second The value is specified in 100 ns
units, which is the SDK standard.
Max cluster duration 30 seconds The value is specified in 100 ns
units, which is the SDK standard.
The backend API may enforce a
shorter cluster duration.
Max fragment size 50 MB For more information,
see Kinesis Video Streams
Limits (p. 139).
Max fragment duration 10 seconds For more information,
see Kinesis Video Streams
Limits (p. 139).
Max connection duration 45 minutes The backend closes the
connection after this time.
The SDK rotates the token and
establishes a new connection
within this time.
Max ACK segment length 1,024 characters Maximum segment length of the
acknowledgement sent to the
ACK parser function.
Max content type string length 128 characters
Max codec ID string length 32 characters
Max track name string length 32 characters
Max codec private data length 1 MiB = 1 * 1024 * 1024 bytes
Min timecode scale value length 100 ns The minimum timecode scale
value to represent the frame
timestamps in the resulting MKV
cluster. The value is specified in
increments of 100 ns, which is
the SDK standard.
Max timecode scale value length 1 second The maximum timecode scale
value to represent the frame
timestamps in the resulting MKV
cluster. The value is specified in
increments of 100 ns, which is
the SDK standard.
Min content view item count 10
Min buffer duration 20 seconds The value is specified in
increments of 100 ns, which is
the SDK standard.
Max update version length 128 characters
60
Amazon Kinesis Video Streams Developer Guide
Error Code Reference
Value Limit Notes
Max ARN length 1024 characters
Max fragment sequence length 128 characters
Max retention period 10 years
Error Code Reference
This section contains error and status code information for the Producer Libraries (p. 31).
For information about solutions to common issues, see Troubleshooting Kinesis Video Streams (p. 142).
Errors and Status Codes Returned by PutFrame Callbacks
The following sections contain error and status information that is returned by callbacks for the
PutFrame operation.
Topics
•Error and Status Codes Returned by the Client Library (p. 61)
•Error and Status Codes Returned by the Duration Library (p. 74)
•Error and Status Codes Returned by the Common Library (p. 74)
•Error and Status Codes Returned by the Heap Library (p. 75)
•Error and Status Codes Returned by the MKVGen Library (p. 76)
•Error and Status Codes Returned by the Trace Library (p. 79)
•Error and Status Codes Returned by the Utils Library (p. 79)
•Error and Status Codes Returned by the View Library (p. 80)
Error and Status Codes Returned by the Client Library
The following table contains error and status information that is returned by methods in the Kinesis
Video Streams Client library.
Code Message Description Recommended Action
0x52000001 STATUS_MAX_STREAM_COUNTThe maximum stream
count was reached.
Specify a larger max stream
count in DeviceInfo as
specified in Producer SDK
Limits (p. 59).
0x52000002 STATUS_MIN_STREAM_COUNTMinimum stream
count error.
Specify the max number of
streams greater than 0 in
DeviceInfo.
0x52000003 STATUS_INVALID_DEVICE_NAME_LENGTHInvalid device name
length.
Refer to the max device
name length in characters
that is specified in Producer
SDK Limits (p. 59).
0x52000004 STATUS_INVALID_DEVICE_INFO_VERSIONInvalid DeviceInfo
structure version.
Specify the correct current
version of the structure.
61
Amazon Kinesis Video Streams Developer Guide
Error Code Reference
Code Message Description Recommended Action
0x52000005 STATUS_MAX_TAG_COUNT The maximum tag
count was reached.
Refer to the current
max tag count that is
specified in Producer SDK
Limits (p. 59).
0x52000006 STATUS_DEVICE_FINGERPRINT_LENGTH
0x52000007 STATUS_INVALID_CALLBACKS_VERSIONInvalid Callbacks
structure version.
Specify the correct current
version of the structure.
0x52000008 STATUS_INVALID_STREAM_INFO_VERSIONInvalid StreamInfo
structure version.
Specify the correct current
version of the structure.
0x52000009 STATUS_INVALID_STREAM_NAME_LENGTHInvalid stream name
length.
Refer to the max stream
name length in characters
that is specified in Producer
SDK Limits (p. 59).
0x5200000a STATUS_INVALID_STORAGE_SIZEAn invalid storage
size was specified.
The storage size in bytes
must be within the limits
specified in Producer SDK
Limits (p. 59).
0x5200000b STATUS_INVALID_ROOT_DIRECTORY_LENGTHInvalid root directory
string length.
Refer to the max root
directory path length that
is specified in Producer SDK
Limits (p. 59).
0x5200000c STATUS_INVALID_SPILL_RATIOInvalid spill ratio. Express the spill ratio as a
percentage from 0 to 100.
0x5200000d STATUS_INVALID_STORAGE_INFO_VERSIONInvalid StorageInfo
structure version.
Specify the correct current
version of the structure.
0x5200000e STATUS_INVALID_STREAM_STATEThe stream is in a
state that doesn't
permit the current
operation.
Most commonly, this error
occurs when the SDK fails
to reach the state that
it needs to perform the
requested operation. For
example, it occurs if the
GetStreamingEndpoint
API call fails, and the client
application ignores it and
continues putting frames
into the stream.
0x5200000f STATUS_SERVICE_CALL_CALLBACKS_MISSINGThe Callbacks
structure has missing
function entry points
for some mandatory
functions.
Ensure that the mandatory
callbacks are implemented
in the client application.
This error is exposed only to
PIC (Platform Independent
Code) clients. C++ and
other higher-level wrappers
satisfy these calls.
62
Amazon Kinesis Video Streams Developer Guide
Error Code Reference
Code Message Description Recommended Action
0x52000010 STATUS_SERVICE_CALL_NOT_AUTHORIZED_ERRORNot authorized. Verify the security token/
certificate/security token
integration/expiration.
Ensure that the token has
the correct associated rights
with it. For the Kinesis
Video Streams sample
applications, ensure that the
environment variable is set
correctly.
0x52000011 STATUS_DESCRIBE_STREAM_CALL_FAILEDDescribeStream
API failure.
This error is returned after
the DescribeStream API
retry failure. The PIC client
returns this error after it
gives up retrying.
0x52000012 STATUS_INVALID_DESCRIBE_STREAM_RESPONSEInvalid
DescribeStreamResponse
structure.
The structure that
was passed to the
DescribeStreamResultEvent
is either null or contains
invalid items like a null
Amazon Resource Name
(ARN).
0x52000013 STATUS_STREAM_IS_BEING_DELETED_ERRORThe stream is being
deleted.
An API failure was caused by
the stream being deleted.
Ensure that no other
processes are trying to
delete the stream while the
stream is in use.
0x52000014 STATUS_SERVICE_CALL_INVALID_ARG_ERRORInvalid arguments
were specified for the
service call.
The backend returns this
error when a service call
argument is not valid or
when the SDK encounters
an error that it can't
interpret.
0x52000015 STATUS_SERVICE_CALL_DEVICE_NOT_FOUND_ERRORThe device was not
found.
Ensure that the device is not
deleted while in use.
0x52000016 STATUS_SERVICE_CALL_DEVICE_NOT_PROVISIONED_ERRORThe device was not
provisioned.
Ensure that the device has
been provisioned.
0x52000017 STATUS_SERVICE_CALL_RESOURCE_NOT_FOUND_ERRORGeneric resource not
found returned from
the service.
This error occurs when the
service can't locate the
resource (for example, a
stream). It might mean
different things in different
contexts, but the likely
cause is the usage of APIs
before the stream is created.
Using the SDK ensures that
the stream is created first.
63
Amazon Kinesis Video Streams Developer Guide
Error Code Reference
Code Message Description Recommended Action
0x52000018 STATUS_INVALID_AUTH_LENInvalid auth info
length.
Refer to the current
values that are specified
in Producer SDK
Limits (p. 59).
0x52000019 STATUS_CREATE_STREAM_CALL_FAILEDThe CreateStream
API call failed.
Refer to the error string for
more detailed information
about why the operation
failed.
0x5200002a STATUS_GET_STREAMING_TOKEN_CALL_FAILEDThe
GetStreamingToken
call failed.
Refer to the error string for
more detailed information
about why the operation
failed.
0x5200002b STATUS_GET_STREAMING_ENDPOINT_CALL_FAILEDThe
GetStreamingEndpoint
API call failed.
Refer to the error string for
more detailed information
about why the operation
failed.
0x5200002c STATUS_INVALID_URI_LEN An invalid URI
string length was
returned from the
GetStreamingEndpoint
API.
Refer to the current
maximum values that are
specified in Producer SDK
Limits (p. 59).
0x5200002d STATUS_PUT_STREAM_CALL_FAILEDThe PutMedia API
call failed.
Refer to the error string for
more detailed information
about why the operation
failed.
64
Amazon Kinesis Video Streams Developer Guide
Error Code Reference
Code Message Description Recommended Action
0x5200002e STATUS_STORE_OUT_OF_MEMORYThe content store is
out of memory.
The content store is shared
between the streams
and should have enough
capacity to store the
maximum durations
for all the streams +
~20% (accounting for
the defragmentation). It's
important to not overflow
the storage. Choose values
for the maximum duration
per stream that correspond
to the cumulative storage
size and the latency
tolerances. It's better to
drop the frames as they
fall out of the content view
window versus just being
put (content store memory
pressure). This is because
dropping the frames
triggers the stream pressure
notification callbacks.
Then the application
can adjust the upstream
media components (like
the encoder) to thin the
bitrate, drop frames, or act
accordingly.
0x5200002f STATUS_NO_MORE_DATA_AVAILABLENo more data is
available currently for
a stream.
This is a potential valid
result when the media
pipeline produces more
slowly than the networking
thread consumes the
frames to be sent to the
service. Higher-level clients
(for example, C++, Java,
or Android) do not see
this warning because it's
handled internally.
0x52000030 STATUS_INVALID_TAG_VERSIONInvalid Tag structure
version.
Specify the correct current
version of the structure.
0x52000031 STATUS_SERVICE_CALL_UNKOWN_ERRORAn unknown or
generic error was
returned from the
networking stack.
See the logs for more
detailed information.
0x52000032 STATUS_SERVICE_CALL_RESOURCE_IN_USE_ERRORResource in use. Returned from the service.
For more information, see
the Kinesis Video Streams
API Reference.
65
Amazon Kinesis Video Streams Developer Guide
Error Code Reference
Code Message Description Recommended Action
0x52000033 STATUS_SERVICE_CALL_CLIENT_LIMIT_ERRORClient limit. Returned from the service.
For more information, see
the Kinesis Video Streams
API Reference.
0x52000034 STATUS_SERVICE_CALL_DEVICE_LIMIT_ERRORDevice limit. Returned from the service.
For more information, see
the Kinesis Video Streams
API Reference.
0x52000035 STATUS_SERVICE_CALL_STREAM_LIMIT_ERRORStream limit. Returned from the service.
For more information, see
the Kinesis Video Streams
API Reference.
0x52000036 STATUS_SERVICE_CALL_RESOURCE_DELETED_ERRORThe resource was
deleted or is being
deleted.
Returned from the service.
For more information, see
the Kinesis Video Streams
API Reference.
0x52000037 STATUS_SERVICE_CALL_TIMEOUT_ERRORThe service call timed
out.
Calling a particular service
API resulted in a timeout.
Ensure that you have a valid
network connection. The
PIC will retry the operation
automatically.
0x52000038 STATUS_STREAM_READY_CALLBACK_FAILEDStream ready
notification.
This notification is sent
from the PIC to the client
indicating that the async
stream has been created.
0x52000039 STATUS_DEVICE_TAGS_COUNT_NON_ZERO_TAGS_NULLInvalid tags were
specified.
The tag count is not zero,
but the tags are empty.
Ensure that the tags are
specified or the count is
zero.
0x5200003a STATUS_INVALID_STREAM_DESCRIPTION_VERSIONInvalid
StreamDescription
structure version.
Specify the correct current
version of the structure.
0x5200003b STATUS_INVALID_TAG_NAME_LENInvalid tag name
length.
Refer to the limits for
the tag name that are
specified in Producer SDK
Limits (p. 59).
0x5200003c STATUS_INVALID_TAG_VALUE_LENInvalid tag value
length.
Refer to the limits for
the tag value that are
specified in Producer SDK
Limits (p. 59).
0x5200003d STATUS_TAG_STREAM_CALL_FAILEDThe TagResource
API failed.
The TagResource API call
failed. Check for a valid
network connection. See the
logs for more information
about the failure.
66
Amazon Kinesis Video Streams Developer Guide
Error Code Reference
Code Message Description Recommended Action
0x5200003e STATUS_INVALID_CUSTOM_DATAInvalid custom data
calling PIC APIs.
Invalid custom data has
been specified in a call to
the PIC APIs. This can occur
only in the clients that
directly use PIC.
0x5200003f STATUS_INVALID_CREATE_STREAM_RESPONSEInvalid
CreateStreamResponse
structure.
The structure or its member
fields are invalid (that is, the
ARN is null or larger than
what's specified in Producer
SDK Limits (p. 59)).
0x52000040 STATUS_CLIENT_AUTH_CALL_FAILEDClient auth failed. The PIC failed to get
proper auth information
(that is, AccessKeyId or
SecretAccessKey) after a
number of retries. Check the
authentication integration.
The sample applications
use environment variables
to pass in credential
information to the C++
Producer Library.
0x52000041 STATUS_GET_CLIENT_TOKEN_CALL_FAILEDGetting the security
token call failed.
This situation can occur for
clients that use PIC directly.
After a number of retries,
the call fails with this error.
0x52000042 STATUS_CLIENT_PROVISION_CALL_FAILEDProvisioning error. Provisioning is not
implemented.
0x52000043 STATUS_CREATE_CLIENT_CALL_FAILEDFailed to create the
producer client.
A generic error returned
by the PIC after a number
of retries when the client
creation fails.
0x52000044 STATUS_CLIENT_READY_CALLBACK_FAILEDFailed to get the
producer client to a
READY state.
Returned by the PIC state
machine if the PIC fails
to move to the READY
state. See the logs for more
information about the root
cause.
0x52000045 STATUS_TAG_CLIENT_CALL_FAILEDThe TagResource
for the producer
client failed.
The TagResource API
call failed for the producer
client. See the logs for more
information about the root
cause.
67
Amazon Kinesis Video Streams Developer Guide
Error Code Reference
Code Message Description Recommended Action
0x52000046 STATUS_INVALID_CREATE_DEVICE_RESPONSEDevice/Producer
creation failed.
The higher-level SDKs (for
example, C++ or Java) don't
implement the device/
producer creation API yet.
Clients that use PIC directly
can indicate a failure using
the result notification.
0x52000047 STATUS_ACK_TIMESTAMP_NOT_IN_VIEW_WINDOWThe timestamp of the
received ACK is not in
the view.
This error occurs if the
frame corresponding to the
received ACK falls out of
the content view window.
Generally, this occurs if the
ACK delivery is slow. It can
be interpreted as a warning
and an indication that the
downlink is slow.
0x52000048 STATUS_INVALID_FRAGMENT_ACK_VERSIONInvalid FragmentAck
structure version.
Specify the correct
current version of the
FragmentAck structure.
0x52000049 STATUS_INVALID_TOKEN_EXPIRATIONInvalid security token
expiration.
The security token
expiration should have an
absolute timestamp in the
future that is greater than
the current timestamp,
with a grace period. For
the limits for the grace
period, see the Producer
SDK Limits (p. 59).
0x5200004a STATUS_END_OF_STREAM End of stream (EOS)
indicator.
In the GetStreamData
API call, indicates that the
current upload handle
session has ended. This
occurs if the session ends
or errors, or if the session
token has expired and the
session is being rotated.
0x5200004b STATUS_DUPLICATE_STREAM_NAMEDuplicate stream
name.
Multiple streams can't have
the same stream name.
Choose a unique name for
the stream.
0x5200004c STATUS_INVALID_RETENTION_PERIODInvalid retention
period.
An invalid retention
period is specified in the
StreamInfo structure.
For information about
the valid range of
values for the retention
period, see Producer SDK
Limits (p. 59).
68
Amazon Kinesis Video Streams Developer Guide
Error Code Reference
Code Message Description Recommended Action
0x5200004d STATUS_INVALID_ACK_KEY_STARTInvalid
FragmentAck.
Failed to parse the fragment
ACK string. Invalid key start
indicator. The fragment ACK
string might be damaged.
It can self-correct and this
error can be treated as a
warning.
0x5200004e STATUS_INVALID_ACK_DUPLICATE_KEY_NAMEInvalid
FragmentAck.
Failed to parse the fragment
ACK string. Multiple keys
have the same name. The
fragment ACK string might
be damaged. It can self-
correct and this error can be
treated as a warning.
0x5200004f STATUS_INVALID_ACK_INVALID_VALUE_STARTInvalid
FragmentAck.
Failed to parse the fragment
ACK string because of an
invalid key value start
indicator. The fragment ACK
string might be damaged.
It can self-correct, and this
error can be treated as a
warning.
0x52000050 STATUS_INVALID_ACK_INVALID_VALUE_ENDInvalid
FragmentAck.
Failed to parse the fragment
ACK string because of
an invalid key value end
indicator. The fragment ACK
string might be damaged.
It can self-correct and this
error can be treated as a
warning.
0x52000051 STATUS_INVALID_PARSED_ACK_TYPEInvalid
FragmentAck.
Failed to parse the fragment
ACK string because an
invalid ACK type was
specified.
0x52000052 STATUS_STREAM_HAS_BEEN_STOPPEDStream was stopped. The stream has been
stopped, but a frame is still
being put into the stream.
0x52000053 STATUS_INVALID_STREAM_METRICS_VERSIONInvalid
StreamMetrics
structure version.
Specify the correct
current version of the
StreamMetrics structure.
0x52000054 STATUS_INVALID_CLIENT_METRICS_VERSIONInvalid
ClientMetrics
structure version.
Specify the correct
current version of the
ClientMetrics structure.
0x52000055 STATUS_INVALID_CLIENT_READY_STATEProducer initialization
failed to reach a
READY state.
Failed to reach the READY
state during the producer
client initialization. See the
logs for more information.
69
Amazon Kinesis Video Streams Developer Guide
Error Code Reference
Code Message Description Recommended Action
0x52000056 STATUS_STATE_MACHINE_STATE_NOT_FOUNDInternal state
machine error.
Not a publicly visible error.
0x52000057 STATUS_INVALID_FRAGMENT_ACK_TYPEInvalid ACK type
is specified in the
FragmentAck
structure.
The FragmentAck structure
should contain ACK types
defined in the public header.
0x52000058 STATUS_INVALID_STREAM_READY_STATEInternal state
machine transition
error.
Not a publicly visible error.
0x52000059 STATUS_CLIENT_FREED_BEFORE_STREAMThe stream object
was freed after the
producer was freed.
There was an attempt to
free a stream object after
the producer object was
freed. This can only occur in
clients that directly use PIC.
0x5200005a STATUS_ALLOCATION_SIZE_SMALLER_THAN_REQUESTEDInternal storage error. An internal error indicating
that the actual allocation
size from the content store
is smaller than the size
of the packaged frame/
fragment.
0x5200005b STATUS_VIEW_ITEM_SIZE_GREATER_THAN_ALLOCATIONInternal storage error. The stored size of the
allocation in the content
view is greater than the
allocation size in the
content store.
0x5200005c STATUS_ACK_ERR_STREAM_READ_ERRORStream read error
ACK.
An error that the ACK
returned from the backend
indicating a stream read/
parsing error. This generally
occurs when the backend
fails to retrieve the stream.
Auto-restreaming can
usually correct this error.
70
Amazon Kinesis Video Streams Developer Guide
Error Code Reference
Code Message Description Recommended Action
0x5200005d STATUS_ACK_ERR_FRAGMENT_SIZE_REACHEDThe maximum
fragment size was
reached.
The max fragment size in
bytes is defined in Producer
SDK Limits (p. 59). This
error indicates that there
are either very large frames,
or there are no key frames
to create manageable
size fragments. Check the
encoder settings and ensure
that key frames are being
produced properly. For
streams that have very
high density, configure
the encoder to produce
fragments at smaller
durations to manage the
maximum size.
0x5200005e STATUS_ACK_ERR_FRAGMENT_DURATION_REACHEDThe maximum
fragment duration
was reached.
The max fragment duration
is defined in Producer SDK
Limits (p. 59). This error
indicates that there are
either very low frames
per second or there are
no key frames to create
manageable duration
fragments. Check the
encoder settings and ensure
that key frames are being
produced properly at the
regular intervals.
0x5200005f STATUS_ACK_ERR_CONNECTION_DURATION_REACHEDThe maximum
connection duration
was reached.
Kinesis Video Streams
enforces the max
connection duration as
specified in the Producer
SDK Limits (p. 59). The
Producer SDK automatically
rotates the stream/token
before the maximum is
reached, and so clients using
the SDK should not receive
this error.
0x52000060 STATUS_ACK_ERR_FRAGMENT_TIMECODE_NOT_MONOTONICTimecodes are not
monotonically
increasing.
The Producer SDK enforces
timestamps, so clients using
the SDK should not receive
this error.
0x52000061 STATUS_ACK_ERR_MULTI_TRACK_MKVMultiple tracks in the
MKV.
The Producer SDK enforces
single track streams, so
clients using the SDK should
not receive this error.
71
Amazon Kinesis Video Streams Developer Guide
Error Code Reference
Code Message Description Recommended Action
0x52000062 STATUS_ACK_ERR_INVALID_MKV_DATAInvalid MKV data. The backend MKV parser
encountered an error
parsing the stream. Clients
using the SDK might
encounter this error if the
stream is corrupted in the
transition or if the buffer
pressures force the SDK to
drop tail frames that are
partially transmitted. In the
latter case, we recommend
that you either reduce the
FPS/resolution, increase the
compression ratio, or (in the
case of a "bursty" network)
allow for larger content
store and buffer duration
to accommodate for the
temporary pressures.
0x52000063 STATUS_ACK_ERR_INVALID_PRODUCER_TIMESTAMPInvalid producer
timestamp.
The service returns this error
ACK if the producer clock
has a large drift into the
future. Higher-level SDKs
(for example, Java or C+
+) use some version of the
system clock to satisfy the
current time callback from
PIC. Ensure that the system
clock is set properly. Clients
using the PIC directly should
ensure that their callback
functions return the correct
timestamp.
0x52000064 STATUS_ACK_ERR_STREAM_NOT_ACTIVEInactive stream. A call to a backend API was
made while the stream was
not in an "Active" state.
This occurs when the client
creates the stream and
immediately continues to
push frames into it. The
SDK handles this scenario
through the state machine
and recovery mechanism.
0x52000065 STATUS_ACK_ERR_KMS_KEY_ACCESS_DENIEDAWS KMS access
denied error.
Returned when the account
has no access to the
specified key.
0x52000066 STATUS_ACK_ERR_KMS_KEY_DISABLEDAWS KMS key is
disabled
The specified key has been
disabled.
72
Amazon Kinesis Video Streams Developer Guide
Error Code Reference
Code Message Description Recommended Action
0x52000067 STATUS_ACK_ERR_KMS_KEY_VALIDATION_ERRORAWS KMS key
validation error.
Generic validation error.
For more information, see
the AWS Key Management
Service API Reference.
0x52000068 STATUS_ACK_ERR_KMS_KEY_UNAVAILABLEAWS KMS key
unavailable.
The key is unavailable.
For more information, see
the AWS Key Management
Service API Reference.
0x52000069 STATUS_ACK_ERR_KMS_KEY_INVALID_USAGEInvalid use of AWS
KMS key.
The AWS KMS key is not
configured to be used in
this context. For more
information, see the AWS
Key Management Service API
Reference.
0x5200006a STATUS_ACK_ERR_KMS_KEY_INVALID_STATEAWS KMS invalid
state.
For more information, see
the AWS Key Management
Service API Reference.
0x5200006b STATUS_ACK_ERR_KMS_KEY_NOT_FOUNDAWS KMS key not
found.
The key was not found.
For more information, see
the AWS Key Management
Service API Reference.
0x5200006c STATUS_ACK_ERR_STREAM_DELETEDThe stream has been
or is being deleted.
The stream is being deleted
by another application
or through the AWS
Management Console.
0x5200006d STATUS_ACK_ERR_ACK_INTERNAL_ERRORInternal error. Generic service internal
error.
0x5200006e STATUS_ACK_ERR_FRAGMENT_ARCHIVAL_ERRORFragment archival
error.
Returned when the service
fails to durably persist
and index the fragment.
Although it's rare, it can
occur for various reasons.
By default, the SDK retries
sending the fragment.
0x5200006f STATUS_ACK_ERR_UNKNOWN_ACK_ERRORUnknown error. The service returned an
unknown error.
0x52000070 STATUS_MISSING_ERR_ACK_IDMissing ACK
information.
The ACK parser completed
parsing, but the
FragmentAck information
is missing.
0x52000071 STATUS_INVALID_ACK_SEGMENT_LENInvalid ACK segment
length.
An ACK segment string
with an invalid length
was specified to the
ACK parser. For more
information, see Producer
SDK Limits (p. 59).
73
Amazon Kinesis Video Streams Developer Guide
Error Code Reference
Code Message Description Recommended Action
0x52000074 STATUS_MAX_FRAGMENT_METADATA_COUNTThe maximum
number of metadata
items has been added
to a fragment.
A Kinesis video stream can
add up to 10 metadata
items to a fragment, either
by adding a nonpersistent
item to a fragment, or by
adding a persistent item
to the metadata queue.
For more information,
see Using Streaming
Metadata with Kinesis Video
Streams (p. 12).
0x52000075 STATUS_ACK_ERR_FRAGMENT_METADATA_LIMIT_REACHEDA limit (maximum
metadata count,
metadata name
length, or metadata
value length) has
been reached.
The Producer SDK limits
the number and size of
metadata items. This error
does not occur unless
the limits in the Producer
SDK code are changed.
For more information,
see Using Streaming
Metadata with Kinesis Video
Streams (p. 12).
0x52000076 STATUS_BLOCKING_PUT_INTERRUPTED_STREAM_TERMINATEDNot implemented.
0x52000077 STATUS_INVALID_METADATA_NAMEThe metadata name
is not valid.
The metadata name cannot
start with the string "AWS".
If this error occurs, the
metadata item is not
added to the fragment
or metadata queue.
For more information,
see Using Streaming
Metadata with Kinesis Video
Streams (p. 12).
Error and Status Codes Returned by the Duration Library
The following table contains error and status information that is returned by methods in the Duration
library.
Code Message
0xFFFFFFFFFFFFFFFF INVALID_DURATION_VALUE
Error and Status Codes Returned by the Common Library
The following table contains error and status information that is returned by methods in the Common
library.
Note
These error and status information codes are common to many APIs.
74
Amazon Kinesis Video Streams Developer Guide
Error Code Reference
Code Message Description
0x00000001 STATUS_NULL_ARG NULL was passed for a
mandatory argument.
0x00000002 STATUS_INVALID_ARG An invalid value was specified
for an argument.
0x00000003 STATUS_INVALID_ARG_LEN An invalid argument length was
specified.
0x00000004 STATUS_NOT_ENOUGH_MEMORY Could not allocate enough
memory.
0x00000005 STATUS_BUFFER_TOO_SMALL The specified buffer size is too
small.
0x00000006 STATUS_UNEXPECTED_EOF An unexpected end of file was
reached.
0x00000007 STATUS_FORMAT_ERROR An invalid format was
encountered.
0x00000008 STATUS_INVALID_HANDLE_ERRORInvalid handle value.
0x00000009 STATUS_OPEN_FILE_FAILED Failed to open a file.
0x0000000a STATUS_READ_FILE_FAILED Failed to read from a file.
0x0000000b STATUS_WRITE_TO_FILE_FAILEDFailed to write to a file.
0x0000000c STATUS_INTERNAL_ERROR An internal error that normally
doesn't occur and might indicate
an SDK or service API bug.
0x0000000d STATUS_INVALID_OPERATION There was an invalid operation,
or the operation is not
permitted.
0x0000000e STATUS_NOT_IMPLEMENTED The feature is not implemented.
0x0000000f STATUS_OPERATION_TIMED_OUT The operation timed out.
0x00000010 STATUS_NOT_FOUND A required resource was not
found.
Error and Status Codes Returned by the Heap Library
The following table contains error and status information that is returned by methods in the Heap
library.
Code Message Description
0x01000001 STATUS_HEAP_FLAGS_ERROR An invalid combination of flags
was specified.
0x01000002 STATUS_HEAP_NOT_INITIALIZEDAn operation was attempted
before the heap was initialized.
75
Amazon Kinesis Video Streams Developer Guide
Error Code Reference
Code Message Description
0x01000003 STATUS_HEAP_CORRUPTED The heap was corrupted or the
guard band (in debug mode) was
overwritten. A buffer overflow in
the client code might lead to a
heap corruption.
0x01000004 STATUS_HEAP_VRAM_LIB_MISSINGThe VRAM (video RAM) user or
kernel mode library cannot be
loaded or is missing. Check if the
underlying platform supports
VRAM allocations.
0x01000005 STATUS_HEAP_VRAM_LIB_REOPENFailed to open the VRAM library.
0x01000006 STATUS_HEAP_VRAM_INIT_FUNC_SYMBOLFailed to load the INIT function
export.
0x01000007 STATUS_HEAP_VRAM_ALLOC_FUNC_SYMBOLFailed to load the ALLOC
function export.
0x01000008 STATUS_HEAP_VRAM_FREE_FUNC_SYMBOLFailed to load the FREE function
export.
0x01000009 STATUS_HEAP_VRAM_LOCK_FUNC_SYMBOLFailed to load the LOCK function
export.
0x0100000a STATUS_HEAP_VRAM_UNLOCK_FUNC_SYMBOLFailed to load the UNLOCK
function export.
0x0100000b STATUS_HEAP_VRAM_UNINIT_FUNC_SYMBOLFailed to load the UNINIT
function export.
0x0100000c STATUS_HEAP_VRAM_GETMAX_FUNC_SYMBOLFailed to load the GETMAX
function export.
0x0100000d STATUS_HEAP_DIRECT_MEM_INITFailed to initialize the main heap
pool in the hybrid heap.
0x0100000e STATUS_HEAP_VRAM_INIT_FAILEDThe VRAM dynamic initialization
failed.
0x0100000f STATUS_HEAP_LIBRARY_FREE_FAILEDFailed to de-allocate and free
the VRAM library.
0x01000010 STATUS_HEAP_VRAM_ALLOC_FAILEDThe VRAM allocation failed.
0x01000011 STATUS_HEAP_VRAM_FREE_FAILEDThe VRAM free failed.
0x01000012 STATUS_HEAP_VRAM_MAP_FAILEDThe VRAM map failed.
0x01000013 STATUS_HEAP_VRAM_UNMAP_FAILEDThe VRAM unmap failed.
0x01000014 STATUS_HEAP_VRAM_UNINIT_FAILEDThe VRAM deinitialization failed.
Error and Status Codes Returned by the MKVGen Library
The following table contains error and status information that is returned by methods in the MKVGen
library.
76
Amazon Kinesis Video Streams Developer Guide
Error Code Reference
Code Message Description / Recommended
Action
0x32000001 STATUS_MKV_INVALID_FRAME_DATAInvalid members of the Frame
data structure. Ensure that the
duration, size, and frame data
are valid and are within the
limits specified in Producer SDK
Limits (p. 59).
0x32000002 STATUS_MKV_INVALID_FRAME_TIMESTAMPInvalid frame timestamp. The
calculated PTS (presentation
timestamp) and DTS (decoding
timestamp) are greater or
equal to the timestamp of the
start frame of the fragment.
This is an indication of a
potential media pipeline
restart or an encoder stability
issue. For troubleshooting
information, see Error: "Failed to
submit frame to Kinesis Video
client" (p. 147)
0x32000003 STATUS_MKV_INVALID_CLUSTER_DURATIONAn invalid fragment duration
was specified. For more
information, see Producer SDK
Limits (p. 59).
0x32000004 STATUS_MKV_INVALID_CONTENT_TYPE_LENGTHInvalid content type
string length. For more
information, see Producer SDK
Limits (p. 59).
0x32000005 STATUS_MKV_NUMBER_TOO_BIG There was an attempt to encode
a number that's too large to be
represented in EBML (Extensible
Binary Meta Language) format.
This should not be exposed to
the SDK clients.
0x32000006 STATUS_MKV_INVALID_CODEC_ID_LENGTHInvalid codec ID string length.
For more information, see
Producer SDK Limits (p. 59).
0x32000007 STATUS_MKV_INVALID_TRACK_NAME_LENGTHInvalid track name string length.
For more information, see
Producer SDK Limits (p. 59).
0x32000008 STATUS_MKV_INVALID_CODEC_PRIVATE_LENGTHInvalid codec private
data length. For more
information, see Producer SDK
Limits (p. 59).
0x32000009 STATUS_MKV_CODEC_PRIVATE_NULLThe codec private data (CPD) is
NULL, whereas the CPD size is
greater than 0.
77
Amazon Kinesis Video Streams Developer Guide
Error Code Reference
Code Message Description / Recommended
Action
0x3200000a STATUS_MKV_INVALID_TIMECODE_SCALEInvalid timecode scale value. For
more information, see Producer
SDK Limits (p. 59).
0x3200000b STATUS_MKV_MAX_FRAME_TIMECODEThe frame timecode is greater
than the maximum. For more
information, see Producer SDK
Limits (p. 59).
0x3200000c STATUS_MKV_LARGE_FRAME_TIMECODEThe max frame timecode was
reached. The MKV format uses
signed 16 bits to represent
the relative timecode of the
frame to the beginning of the
cluster. The error is generated if
the frame timecode cannot be
represented. This error indicates
either a bad timecode scale
selection or the cluster duration
is too long, so representing the
frame timecode overflows the
signed 16-bit space.
0x3200000d STATUS_MKV_INVALID_ANNEXB_NALU_IN_FRAME_DATAAn invalid Annex-B start code
was encountered. For example,
the Annex-B adaptation flag
was specified and the code
encounters an invalid start
sequence of more than three
zeroes. A valid Annex-B format
should have an "emulation
prevention" sequence to escape
a sequence of three or more
zeroes in the bytestream. For
more information, see the MPEG
specification. For information
about this error on Android, see
STATUS_MKV_INVALID_ANNEXB_NALU_IN_FRAME_DATA
(0x3200000d) error on
Android (p. 150).
0x3200000e STATUS_MKV_INVALID_AVCC_NALU_IN_FRAME_DATAInvalid AVCC NALu packaging
when the adapting AVCC flag
is specified. Ensure that the
bytestream is in a valid AVCC
format. For more information,
see the MPEG specification.
0x3200000f STATUS_MKV_BOTH_ANNEXB_AND_AVCC_SPECIFIEDBoth adapting AVCC and Annex-
B NALs were specified. Specify
either one, or specify none.
78
Amazon Kinesis Video Streams Developer Guide
Error Code Reference
Code Message Description / Recommended
Action
0x32000010 STATUS_MKV_INVALID_ANNEXB_NALU_IN_CPDInvalid Annex-B format of CPD
when the adapting Annex-B flag
is specified. Ensure that the CPD
is in valid Annex-B format. If
it is not, then remove the CPD
Annex-B adaptation flag.
0x32000011 STATUS_MKV_PTS_DTS_ARE_NOT_SAMEKinesis Video Streams
enforces the PTS (presentation
timestamp) and DTS (decoding
timestamp) to be the same
for the fragment start frames.
These are the key frames that
start the fragment.
0x32000012 STATUS_MKV_INVALID_H264_H265_CPDFailed to parse H264/H265
codec private data.
0x32000013 STATUS_MKV_INVALID_H264_H265_SPS_WIDTHFailed to extract the width from
the codec private data.
0x32000014 STATUS_MKV_INVALID_H264_H265_SPS_HEIGHTFailed to extract the height from
codec private data.
0x32000015 STATUS_MKV_INVALID_H264_H265_SPS_NALUInvalid H264/H265 SPS NALu.
0x32000016 STATUS_MKV_INVALID_BIH_CPD Invalid bitmap info header
format in the codec private data.
Error and Status Codes Returned by the Trace Library
The following table contains error and status information that is returned by methods in the Trace
library.
Code Message
0x10100001 STATUS_MIN_PROFILER_BUFFER
Error and Status Codes Returned by the Utils Library
The following table contains error and status information that is returned by methods in the Utils
library.
Code Message
0x40000001 STATUS_INVALID_BASE64_ENCODE
0x40000002 STATUS_INVALID_BASE
0x40000003 STATUS_INVALID_DIGIT
0x40000004 STATUS_INT_OVERFLOW
79
Amazon Kinesis Video Streams Developer Guide
Error Code Reference
Code Message
0x40000005 STATUS_EMPTY_STRING
0x40000006 STATUS_DIRECTORY_OPEN_FAILED
0x40000007 STATUS_PATH_TOO_LONG
0x40000008 STATUS_UNKNOWN_DIR_ENTRY_TYPE
0x40000009 STATUS_REMOVE_DIRECTORY_FAILED
0x4000000a STATUS_REMOVE_FILE_FAILED
0x4000000b STATUS_REMOVE_LINK_FAILED
0x4000000c STATUS_DIRECTORY_ACCESS_DENIED
0x4000000d STATUS_DIRECTORY_MISSING_PATH
0x4000000e STATUS_DIRECTORY_ENTRY_STAT_ERROR
Error and Status Codes Returned by the View Library
The following table contains error and status information that is returned by methods in the View
library.
Code Message Description
0x30000001 STATUS_MIN_CONTENT_VIEW_ITEMSAn invalid content view item
count was specified. For more
information, see Producer SDK
Limits (p. 59).
0x30000002 STATUS_INVALID_CONTENT_VIEW_DURATIONAn invalid content view duration
was specified. For more
information, see Producer SDK
Limits (p. 59).
0x30000003 STATUS_CONTENT_VIEW_NO_MORE_ITEMSAn attempt was made to get
past the head position.
0x30000004 STATUS_CONTENT_VIEW_INVALID_INDEXAn invalid index is specified.
0x30000005 STATUS_CONTENT_VIEW_INVALID_TIMESTAMPThere was an invalid
timestamp or a timestamp
overlap. The frame decoding
timestamp should be greater
or equal to the previous
frame timestamp, plus the
previous frame duration:
`DTS(n) >= DTS(n-1) +
Duration(n-1)`. This error
often indicates an "unstable"
encoder. The encoder produces
a burst of encoded frames, and
their timestamps are smaller
than the intra-frame durations.
80
Amazon Kinesis Video Streams Developer Guide
NAL Adaptation Flags
Code Message Description
Or the stream is configured
to use SDK timestamps, and
the frames are sent faster
than the frame durations.
To help with some "jitter"
in the encoder, specify a
smaller frame duration in the
StreamInfo.StreamCaps
structure. For example, if the
stream is 25FPS, each frame's
duration is 40 ms. However, to
handle the encoder jitter, we
recommend that you use half
of that frame duration (20 ms).
Some streams require more
precise control over the timing
for error detection.
0x30000006 STATUS_INVALID_CONTENT_VIEW_LENGTHAn invalid content view item
data length was specified.
Network Abstraction Layer (NAL) Adaptation Flag
Reference
This section contains information about available flags for the StreamInfo.NalAdaptationFlags
enumeration.
The elementary stream in an application can be in either Annex-B or AVCC format:
• The Annex-B format delimits NALUs (Network Abstraction Layer units) with two bytes of zeroes,
followed by one or three bytes of zeroes, followed by the number 1 (called a start code, for example,
00000001).
• The AVCC format also wraps NALUs, but each NALU is preceded by a value that indicates the size of
the NALU (usually four bytes).
Many encoders produce the Annex-B bitstream format. Some higher-level bitstream processors (such as
a playback engine or the Media Source Extensions (MSE) player in the AWS Management Console) use
the AVCC format for their frames.
The codec private data (CPD), which is SPS/PPS (Sequence Parameter Set/Picture Parameter Set) for the
H.264 codec, can also be in Annex-B or AVCC format. However, for the CPD, the formats are different
from those described previously.
The flags tell the SDK to adapt the NALUs to AVCC or Annex-B for frame data and CPD as follows:
Flag Adaptation
NAL_ADAPTATION_FLAG_NONE No adaptation
NAL_ADAPTATION_ANNEXB_NALS Adapt Annex-B NALUs to AVCC
NALUs
81
Amazon Kinesis Video Streams Developer Guide
Producer Structures
Flag Adaptation
NAL_ADAPTATION_AVCC_NALS Adapt AVCC NALUs to Annex-B
NALUs
NAL_ADAPTATION_ANNEXB_CPD_NALSAdapt Annex-B NALUs for the
codec private data to AVCC
format NALUs
NAL_ADAPTATION_ANNEXB_CPD_AND_FRAME_NALSAdapt Annex-B NALUs for the
codec and frame private data to
AVCC format NALUs
For more information about NALU types, see Section 1.3: Network Abstraction Layer Unit Types in RFC
3984.
Producer SDK Structures
This section includes information about structures that you can use to provide data to the Kinesis Video
Streams Producer object.
Topics
•DeviceInfo/DefaultDeviceInfoProvider (p. 82)
•StorageInfo (p. 82)
DeviceInfo/DefaultDeviceInfoProvider
The DeviceInfo and DefaultDeviceInfoProvider objects control the behavior of the Kinesis Video
Streams Producer object.
Member Fields
•version: An integer value used to ensure that the correct version of the structure is used
with the current version of the code base. The current version is specified using the
DEVICE_INFO_CURRENT_VERSION macro.
•name: The human-readable name for the device.
•tagCount/tags: Not currently used.
•streamCount: The maximum number of streams that the device can handle. This pre-allocates the
storage for pointers to the stream objects initially, but the actual stream objects are created later. The
default is 16 streams, but you can change this number in the DefaultDeviceInfoProvider.cpp
file.
•storageInfo: An object that describes the main storage configuration. For more information, see
StorageInfo (p. 82).
StorageInfo
Specifies the configuration of the main storage for Kinesis Video Streams.
The default implementation is based on a low-fragmentation fast heap implementation, which is
optimized for streaming. It uses the MEMALLOC allocator, which can be overwritten on a given platform.
Some platforms have virtual memory allocation without backing the allocation with physical pages.
As the memory is used, the virtual pages are backed by the physical pages. This results in low-memory
pressure on the overall system when storage is underused.
82
Amazon Kinesis Video Streams Developer Guide
Stream Structures
Calculate the default storage size based on the following formula. The DefragmentationFactor
should be set to 1.2 (20 percent).
Size = NumberOfStreams * AverageFrameSize * FramesPerSecond * BufferDurationInSeconds *
DefragmentationFactor
In the following example, a device has audio and video streams. The audio stream has 512 samples
per second, with an average sample of 100 bytes. The video stream has 25 frames per second, with an
average of 10,000 bytes. Each stream has 3 minutes of buffer duration.
Size = (512 * 100 * (3 * 60) + 25 * 10000 * (3 * 60)) * 1.2 = (9216000 + 45000000) * 1.2 =
65059200 = ~ 66MB.
If the device has more available memory, it is recommended that you add more memory to storage to
avoid severe fragmentation.
Ensure that the storage size is adequate to accommodate the full buffers for all streams at
high encoding complexity (when the frame size is larger due to high motion) or when the
bandwidth is low. If the producer hits memory pressure, it emits storage overflow pressure
callbacks (StorageOverflowPressureFunc). However, when no memory is available in the
content store, it drops the frame that’s being pushed into Kinesis Video Streams with an error
(STATUS_STORE_OUT_OF_MEMORY = 0x5200002e). For more information, see Error and Status Codes
Returned by the Client Library (p. 61). This can also happen if the application acknowledgements
(ACKs) are not available, or the persisted ACKs are delayed. In this case, the buffers fill to the "buffer
duration" capacity before the older frames start dropping out.
Member Fields
•version: An integer value used to ensure that the correct version of the structure is used with the
current version of the code base.
•storageType: A DEVICE_STORAGE_TYPE enumeration that specifies the underlying
backing/implementation of the storage. Currently the only supported value
is DEVICE_STORAGE_TYPE_IN_MEM. A future implementation will support
DEVICE_STORAGE_TYPE_HYBRID_FILE, indicating that storage falls back to the file-backed content
store.
•storageSize: The storage size in bytes to preallocate. The minimum allocation is 10 MB, and the
maximum allocation is 10 GB. (This will change with the future implementation of the file-backed
content store.)
•spillRatio: An integer value that represents the percentage of the storage to be allocated from the
direct memory storage type (RAM), as opposed to the secondary overflow storage (file storage). Not
currently used.
•rootDirectory: The path to the directory where the file-backed content store is located. Not currently
used.
Kinesis Video Stream Structures
You can use the following structures to provide data to an instance of a Kinesis video stream.
Topics
•StreamDefinition/ StreamInfo (p. 84)
•ClientMetrics (p. 93)
•StreamMetrics (p. 94)
83
Amazon Kinesis Video Streams Developer Guide
Stream Structures
StreamDefinition/ StreamInfo
The StreamDefinition object in the C++ layer wraps the StreamInfo object in the platform-
independent code, and provides some default values in the constructor.
Member Fields
Field Data Type Description Default Value
stream_name string An optional stream
name. For more
information about the
length of the stream
name, see Producer
SDK Limits (p. 59)
. Each stream should
have a unique name.
If no name is specified,
a name is generated
randomly.
retention_period duration<uint64_t,
ratio<3600>>
The retention period for
the stream, in seconds.
Specifying 0 indicates
no retention.
3600 (One hour)
tags const map<string,