Amazon Kinesis Video Streams | Secure Video Ingestion for Analysis & Storage
- C++ SDK
- GStreamer Plugin (kvssink)
Amazon Kinesis Video Streams Producer SDK for C/C++ makes it easy to build an on-device application that securely connects to a video stream, and reliably publishes video and other media data to Kinesis Video Streams. It takes care of all the underlying tasks required to package the frames and fragments generated by the device's media pipeline. The SDK also handles stream creation, token rotation for secure and uninterrupted streaming, processing acknowledgements returned by Kinesis Video Streams, and other tasks.
To download run the following command:
git clone https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-cpp.git
Note: You will also need to install
m4 and a build enviroment. If you are building the GStreamer plugin you will also need GStreamer and GStreamer (Development Libraries).
Refer to the FAQ for platform specific instructions.
Prepare a build directory in the newly checked out repository:
mkdir -p amazon-kinesis-video-streams-producer-sdk-cpp/build cd amazon-kinesis-video-streams-producer-sdk-cpp/build
If you are building on Windows you need to generate
NMake Makefiles, you should run
cmake .. -G "NMake Makefiles"
GStreamer and JNI is NOT built by default, if you wish to build both you MUST execute
cmake .. -DBUILD_GSTREAMER_PLUGIN=ON -DBUILD_JNI=TRUE
By default we download all the libraries from GitHub and build them locally, so should require nothing to be installed ahead of time.
If you do wish to link to existing libraries you can do
cmake .. -DBUILD_DEPENDENCIES=OFF
Libraries needed to build producer are: Curl, Openssl and Log4cplus. If you want to build the gstreamer plugin you will need to have gstreamer in your system.
On Mac OS you can get the libraries using homebrew
$ brew install pkg-config openssl cmake gstreamer gst-plugins-base gst-plugins-good gst-plugins-bad gst-plugins-ugly log4cplus gst-libav
On Ubuntu and Raspberry Pi OS you can get the libraries by running
$ sudo apt-get install libssl-dev libcurl4-openssl-dev liblog4cplus-dev libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev gstreamer1.0-plugins-base-apps gstreamer1.0-plugins-bad gstreamer1.0-plugins-good gstreamer1.0-plugins-ugly gstreamer1.0-tools
Setup desired log level:
Set up the desired log level. The log levels currently available with
To set a log level, update the log level value here
Note: The default log level is
If you wish to cross-compile
CXX are respected when building the library and all its dependencies. See our ci.yml for an example of this. Every commit is cross compiled to ensure that it continues to work.
Please note that GStreamer is not cross-compiled as a part of the cross-compilation of the KVS-SDK, customers will have to cross-compile it separately.
You can pass the following options to
-DBUILD_GSTREAMER_PLUGIN-- Build kvssink GStreamer plugin
-DBUILD_JNI-- Build C++ wrapper for JNI to expose the functionality to Java/Android
-DBUILD_DEPENDENCIES-- Build depending libraries from source
-DBUILD_TEST=TRUE-- Build unit/integration tests, may be useful for confirm support for your device.
-DCODE_COVERAGE-- Enable coverage reporting
-DCOMPILER_WARNINGS-- Enable all compiler warnings
-DADDRESS_SANITIZER-- Build with AddressSanitizer
-DMEMORY_SANITIZER-- Build with MemorySanitizer
-DTHREAD_SANITIZER-- Build with ThreadSanitizer
-DUNDEFINED_BEHAVIOR_SANITIZERBuild with UndefinedBehaviorSanitizer
-DALIGNED_MEMORY_MODELBuild for aligned memory model only devices. Default is OFF.
-DBUILD_LOG4CPLUS_HOSTSpecify host-name for log4cplus for cross-compilation. Default is OFF.
To Include JNI
JNI examples are NOT built by default. If you wish to build JNI you MUST add
-DBUILD_JNI=TRUE when running
To Include Building GStreamer Sample Programs
The GStreamer plugin and samples are NOT built by default. If you wish to build them you MUST add
-DBUILD_GSTREAMER_PLUGIN=TRUE when running cmake:
cmake -DBUILD_GSTREAMER_PLUGIN=TRUE ..
After running cmake, in the same build directory run
On Windows you should run
nmake instead of
In your build directory you will now have shared objects for all the targets you have selected.
GStreamer Plugin (kvssink)
The GStreamer plugin is located in your
To load this plugin set the following environment variables. This should be run from the root of the repo, NOT the
export GST_PLUGIN_PATH=`pwd`/build export LD_LIBRARY_PATH=`pwd`/open-source/local/lib
The equivalent for Windows is
set GST_PLUGIN_PATH=%CD%\build set PATH=%PATH%;%CD%\open-source\local\bin;%CD%\open-source\local\lib
Now if you execute
gst-inspect-1.0 kvssink you should get information on the plugin like
Factory Details: Rank primary + 10 (266) Long-name KVS Sink Klass Sink/Video/Network Description GStreamer AWS KVS plugin Author AWS KVS <email@example.com> Plugin Details: Name kvssink Description GStreamer AWS KVS plugin Filename /Users/seaduboi/workspaces/amazon-kinesis-video-streams-producer-sdk-cpp/build/libgstkvssink.so Version 1.0 License Proprietary Source module kvssinkpackage Binary package GStreamer Origin URL http://gstreamer.net
If the build failed, or
GST_PLUGIN_PATH is not properly set you will get output like
No such element or plugin 'kvssink'
The kvssink element has the following required parameters:
stream-name-- The name of the destination Kinesis video stream.
storage-size-- The storage size of the device in megabytes. For information about configuring device storage, see StorageInfo.
access-key-- The AWS access key that is used to access Kinesis Video Streams. You must provide either this parameter or credential-path.
secret-key-- The AWS secret key that is used to access Kinesis Video Streams. You must provide either this parameter or credential-path.
credential-path-- A path to a file containing your credentials for accessing Kinesis Video Streams. For example credential files, see Sample Static Credential and Sample Rotating Credential. For more information on rotating credentials, see Managing Access Keys for IAM Users. You must provide either this parameter or access-key and secret-key.
For examples of common use cases you can look at Example: Kinesis Video Streams Producer SDK GStreamer Plugin
To Include Images/Events feature
The images feature is available in the sample kvs_gstreamer_audio_video_sample.cpp . To enable it include the argument "-e <event_option>" event option is a string that can be:
notification -- for a notification event image -- for an image event both -- for both
The events will start on the 2nd key frame, and will reoccur every 200 key frames. If you would to change this frequence you can edit the sample.
To run from a file
in the kvs_gstreamer_audio_video_sample.cpp if you would like to upload from a file, include the option flag -f <file_path>
Running in offline mode
By default, the samples run in near realtime mode. To set offline mode, set streamInfo.streamCaps.streamingType to
streamInfo is of type
streamCaps is of type
streamingType is of type
- The sample docker scripts for RTSP plugin, raspberry pi and linux can be found in the Kinesis demos repository.
- When building the JNI, if you run into a cmake error
Could NOT find JNI (missing: JAVA_INCLUDE_PATH JAVA_INCLUDE_PATH2 JAVA_AWT_INCLUDE_PATH), make sure your environment variables are set correctly:
export JAVA_INCLUDE_PATH2=$JAVA_HOME/includefor Mac OS.
export JAVA_INCLUDE_PATH2='/usr/java/<JDK_VERSION>/include'for Linux.
- If you are successfully streaming but run into issue with playback. You can do
export KVS_DEBUG_DUMP_DATA_FILE_DIR=/path/to/directorybefore streaming. Producer will then dump MKV files into that path. The file is exactly what KVS will receive. You can use MKVToolNIX to check that everything looks correct. You can also try to play the MKV file in compatible players.
- Is CPP-SDK and GStreamer supported on Mac/Windows/Linux (Supported Platforms)?
Yes! We have FAQs and platform specific instructions for Windows, MacOS and Linux
The repository is using develop branch as the aggregation and all of the feature development is done in appropriate feature branches. The PRs (Pull Requests) are cut on a feature branch and once approved with all the checks passed they can be merged by a click of a button on the PR tool. The master branch should always be build-able and all the tests should be passing. We are welcoming any contribution to the code base. The master branch contains our most recent release cycle from develop.
The repository is under active development and even with incremental unit test coverage where some of the tests are actually full integration tests, we require more rigorous internal testing in order to 'cut' release versions. The release is cut against a particular commit that gets approved. The general philosophy is to cut a release when a set of commits contribute to a self-containing feature or when we add major internal functionality improvements.
We deploy 3 digit version strings in a form of 'Major.Minor.Revision' scheme.
- Major version update - Major functionality changes. Might not have direct backward compatibility. For example, multiple public API parameter changes.
- Minor version update - Additional features. Major bug fixes. Might have some minor backward compatibility issues. For example, an extra parameter on a callback function.
- Revision version update - Minor features. Bug fixes. Full backward compatibility. For example, an extra fields added to the public structures with version bump.
- What Is Amazon Kinesis Video Streams
- C SDK
- Example: Kinesis Video Streams Producer SDK GStreamer Plugin
This library is licensed under the Apache 2.0 License.