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 hand les 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 --recursive https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-cpp.git
Note: If you miss running git clone with --recursive, run
git submodule update --init in the amazon-kinesis-video-streams-producer-sdk-cpp/open-source directory
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.
Create a build directory in the newly checked out repository, and execute CMake from it.
mkdir -p amazon-kinesis-video-streams-producer-sdk-cpp/build; cd amazon-kinesis-video-streams-producer-sdk-cpp/build; cmake ..
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
If you wish to cross-compile
CXX are respected when building the library and all its dependencies. See our .travis.yml for an example of this. Every commit is cross compiled to ensure that it continues to work.
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.
To build the library run make in the build directory you executed CMake.
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 <firstname.lastname@example.org> 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 kilobytes. 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
- 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 master 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 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.