Amazon Kinesis Video Streams C++ Producer, kvssink GStreamer Plugin, and Java Native Interface

Amazon Kinesis Video Streams | Secure Video Ingestion for Analysis & Storage

Table of Contents

• Key Features
• Quick Start
• Build Options
• Configuring kvssink
• Troubleshooting
• Development
• Related
• License

Key Features

• C++ SDK with sample programs
• GStreamer plugin (kvssink) and samples
• Java Native Interface (JNI)

Note

If the GStreamer plugin and samples, and the JNI are not needed for your use case, you may consider instead using the KVS Producer C SDK.

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 (KVS). 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. The SDK includes a GStreamer plugin to stream directly to a custom GStreamer element kvssink, and includes a JNI for use with Java applications and the KVS Java Producer SDK.

For more info on KVS please see AWS KVS Documentation and Amazon Kinesis Video Streams FAQs.

Quick Start

The following instructions describe the SDK and samples setup for Mac, Linux, and Windows platforms. For dedicated Raspberry Pi instructions, see Use the C++ producer SDK on Raspberry Pi

Required Tools

The following packages are required to build the SDK libraries. Using a package manager such as Homebrew (Mac), APT (Linux), and Chocolatey (Windows) is the prefered method of installation.

• C++ Compiler (GNU or Clang recommended)
• git
• CMake
• pkg-config for Mac/Linux, pkgconfiglite for Windows
• m4
• Windows only: nasm and strawberryperl

Mac

brew install git cmake pkgconf m4

Linux

sudo apt update
sudo apt install git cmake pkgconf m4

Windows

choco install git cmake pkgconfiglite nasm strawberryperl

Install GStreamer

If building the samples or the kvssink GStreamer plugin, GStreamer libraries are required.

Mac

brew install gstreamer gst-plugins-base gst-plugins-good gst-plugins-bad gst-plugins-ugly gst-libav

Linux

sudo apt install 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

Windows

choco install gstreamer --version=1.22.8 gstreamer-devel --version=1.22.8

Verify GStreamer Installation

Run the following command to display the GStreamer version to confirm the installation was successful:

gst-launch-1.0 --gst-version

GStreamer Core Library version 1.24.9

Download

git clone https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-cpp.git --single-branch -b master kvs-producer-cpp-sdk

Build

Prepare a build directory in the newly checked out repository:

mkdir -p kvs-producer-cpp-sdk/build
cd kvs-producer-cpp-sdk/build

Configure the build:

Mac and Linux

cmake -DBUILD_GSTREAMER_PLUGIN=ON ..

Windows (may need to run twice)

cmake -G "NMake Makefiles -DBUILD_GSTREAMER_PLUGIN=ON" ..

Note

For more build configuration options, see CMake Arguments.

Compile:

Mac and Linux

make

Windows

nmake

Run the Samples

Included are sample applications for streaming and ingesting to a KVS stream. To stream to KVS, the GStreamer samples use an implemented appsink sink element, and the "kvssink" samples use the custom kvssink sink element.

Tip

More on GStreamer elements.

AWS Authentication

In your terminal, export AWS credentials for your IAM user or role and the region your stream is located in. The samples will default to us-west-2 if the region is not specified. The sample applications do not support IMDS credentials.

export AWS_ACCESS_KEY_ID=YourAccessKey
export AWS_SECRET_ACCESS_KEY=YourSecretKey

export AWS_DEFAULT_REGION=YourAWSRegion

If you're using temporary AWS credentials, also export your session token:

export AWS_SESSION_TOKEN=YourSessionToken

GStreamer appsink Samples

To stream media from the device's camera and microphone sources, create a stream in the AWS KVS console and run the following sample:

./kvs_gstreamer_audio_video_sample <your-stream-name>

kvssink Samples

The SDK comes with two programmatic GStreamer samples: kvssink_gstreamer_sample and kvssink_intermittent_sample. For more use cases, see the CLI pipeline examples at Example: Kinesis Video Streams Producer SDK GStreamer Plugin.

The programmatic samples require the AWS region to be set with the AWS_DEFAULT_REGION environment variable. For example:

export AWS_DEFAULT_REGION=us-west-2

To load the kvssink plugin into GStreamer, set the following environment variable from the build directory.

Mac and Linux

export GST_PLUGIN_PATH=`pwd`/.

Windows

set GST_PLUGIN_PATH=%CD%\.

Running the following command should now display information on the kvssink plugin:

gst-inspect-1.0 kvssink

If the build failed or GST_PLUGIN_PATH is not properly set, you may instead see the following output:
No such element or plugin kvssink

After building the SDK, loading kvssink into the GStreamer plugin path, and setting a region, the sample executables, which are located in the build directory, can be run. For example:

./kvssink_gstreamer_sample MyStreamName

To stream from file with this sample, you can download a test video file and append the file name after the stream name in the sample run command:

wget https://awsj-iot-handson.s3-ap-northeast-1.amazonaws.com/kvs-workshop/sample.mp4

./kvssink_gstreamer_sample MyStreamName ./sample.mp4

Running the kvssink Intermittent Sample

The intermittent kvssink sample will stream video for 20 seconds, then pause for 40 seconds, and repeat until an interrupt signal is received. To manually adjust the streaming and paused intervals, you can change the KVS_INTERMITTENT_PLAYING_INTERVAL_SECONDS and KVS_INTERMITTENT_PAUSED_INTERVAL_SECONDS values in the kvssink_intermittent_sample.cpp file.

./kvssink_intermittent_sample <stream-name> <testsrc or devicesrc (optional)>

Setting the source to testsrc will use videotestsrc and to devicesrc will use autovideosrc. By default, kvssink uses "DEFAULT_STREAM" as the stream name, and the sample uses videotestsrc as the source. If a KVS stream with the provided or default name does not exist, the stream will automatically be created.

Viewing the Sample Footage

Check the ingested video stream to confirm successful streaming using either the AWS KVS Console or the KVS Media Viewer.

If playback issues are encountered, pleaser refer to the playback requirements under GetHLSStreamingSessionURL or GetDASHStreamingSessionURL and to the Troubleshooting HLS Issues guide.

Build Options

Considerations

• The kvssink GStreamer plugin and samples, and the JNI are not built by default. To build them, use their corresponding cmake command options: -DBUILD_GSTREAMER_PLUGIN=ON and -DBUILD_JNI=ON.
• By default, the dependency libraries (Curl, OpenSSL, and Log4Cplus) are installed from GitHub and built locally. To instead link to pre-installed libraries on the device, include the following cmake command argument: cmake .. -DBUILD_DEPENDENCIES=OFF

CMake Arguments

You can pass the following additional CMake options:

Option	Default	Description
BUILD_GSTREAMER_PLUGIN	OFF	Build the kvssink GStreamer plugin
PARALLEL_BUILD	ON	When building dependencies, use multiple CPU cores in parallel (speeds up the build). Not available in Windows.
BUILD_JNI	OFF	Build C++ wrapper for JNI to expose the functionality to Java/Android
BUILD_JNI_ONLY	OFF	Build only the JNI. C++ Producer will not be built. Requires Java installed.
BUILD_DEPENDENCIES	ON	Build depending libraries from source
BUILD_TEST	OFF	Build unit/integration tests, may be useful to confirm support for your device, to run tests: ./tst/producerTest
CODE_COVERAGE	OFF	Enable coverage reporting
COMPILER_WARNINGS	OFF	Enable all compiler warnings
ADDRESS_SANITIZER	OFF	Build with AddressSanitizer
MEMORY_SANITIZER	OFF	Build with MemorySanitizer
THREAD_SANITIZER	OFF	Build with ThreadSanitizer
UNDEFINED_BEHAVIOR_SANITIZER	OFF	Build with UndefinedBehaviorSanitizer
ALIGNED_MEMORY_MODEL	OFF	Build for aligned memory model only devices
BUILD_LOG4CPLUS_HOST	OFF	Specify host-name for log4cplus for cross-compilation
CONSTRAINED_DEVICE	OFF	Set the thread stack size to 0.5MB, needed for Alpine builds

These options can be set as arguments to the cmake command, for example:

cmake .. -DBUILD_GSTREAMER_PLUGIN=ON -DBUILD_DEPENDENCIES=OFF

Setting the Log Level

To set a log level, update the log level value here.

The log levels currently available with log4cplus are:

1. TRACE
2. DEBUG
3. INFO
4. WARN
5. ERROR
6. FATAL

Note: The default log level is DEBUG.

The SDK also tracks entry and exit of functions which increases the verbosity of the logs. This will be useful when you want to track the transitions within the codebase. To do so, you need to set log level to TRACE and add the following to the cmake file: add_definitions(-DLOG_STREAMING) Note: This log level is extremely VERBOSE and could flood the files if using file based logging strategy.

Installing the Library

If the SDK library needs to be installed on your system rather than the local build directory, run make install. This will install in the default directory such as usr/local/lib/, based on the system. To install in another directory, run cmake with the -DCMAKE_INSTALL_PREFIX option with the desired directory before running make install

Cross-Compilation

If you wish to cross-compile CC and CXX are respected when building the library and all its dependencies. See the ci.yml for an example. Every commit is tested for cross compilation. Please note that GStreamer is not cross-compiled as a part of the cross-compilation of the KVS-SDK, you will have to cross-compile it separately.

Docker Scripts

The sample docker scripts for RTSP plugin, Raspberry Pi and Linux can be found in the Kinesis demos repository.

Configuring kvssink

The kvssink GStreamer element includes the following parameters:

Parameter	Default	Description
stream‑name	'DEFAULT_STREAM'	The name of the destination Kinesis video stream. If a KVS stream with the provided or default name does not exist, the stream will automatically be created.
aws‑region	'us-west-2'	The region specified by this parameter will be used if the AWS_DEFAULT_REGION environment variable is not set.
storage‑size	128	The storage size of the device in mebibytes (MiB). For information about configuring device storage, see StorageInfo.
access‑key	N/A	The AWS access key that is used to access Kinesis Video Streams. You must provide either this parameter or credential-path, or set the AWS_ACCESS_KEY_ID environment variable.
secret‑key	N/A	The AWS secret key that is used to access Kinesis Video Streams. You must provide either this parameter or credential-path, or set the AWS_SECRET_ACCESS_KEY environment variable.
credential‑path	'.kvs/credential'	A path to a file containing your credentials for accessing Kinesis Video Streams. For example credential files and more information, see Provide credentials to kvssink. You must provide either this parameter or access-key and secret-key, or set the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables.

To see all kvssink parameters, see AWS Docs - kvssink Paramters.

For examples of common use cases, see Example: Kinesis Video Streams Producer SDK GStreamer Plugin.

Troubleshooting

Additional Platform-Specific Instructions

We have FAQs and platform specific instructions for Windows, MacOS and Linux.

Debugging

Build Issues

• Clean Build: When modifying the build configuration between builds, ensure the appropriate files from the previous build are removed before running cmake for the next build. A simple way to ensure all the previous build's files are removed is to delete all the directories created during the build. To do so, run the following in the project's root folder:

rm -rf build dependency open-source

• If you are running into issues building libcurl on M1 Mac, you can try brew unlink openssl.
• 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 Java (version 8 or 11) is installed and your environment variables are set correctly:
  export JAVA_INCLUDE_PATH2=/Library/Java/JavaVirtualMachines/<YOUR_JDK_VERSION>/Contents/Home/include or export JAVA_INCLUDE_PATH2=$JAVA_HOME/include for Mac OS.
  export JAVA_INCLUDE_PATH2='/usr/java/<JDK_VERSION>/include' for Linux.

Playback Issues

• If you are successfully streaming but run into issue with playback. You can do export KVS_DEBUG_DUMP_DATA_FILE_DIR=/path/to/directory before 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.
• See AWS Docs - Playback issues for more troubleshooting guidance.

GStreamer Issues

• If you would like to visualize the GStreamer pipeline being constructed in a GStreamer application, include the following after the elements have been linked: GST_DEBUG_BIN_TO_DOT_FILE(<gst-bin-object>, GST_DEBUG_GRAPH_SHOW_ALL, <file-name>); For example, if the application created a pipeline object GstPipeline* pipeline = gst_pipeline_new("test-pipeline"), and you would like to see the visualized pipeline with filename pipeline, add: GST_DEBUG_BIN_TO_DOT_FILE((GstBin*) pipeline, GST_DEBUG_GRAPH_SHOW_ALL, "pipeline");. Also, ensure to set the path to where you would like the file to be stored. export GST_DEBUG_DUMP_DOT_DIR=.. The file generated would be a .dot format. Convert to PDF to check the visualized pipeline. This requires graphviz to be installed.

Development

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.

Release

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.

Versioning

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.

Related

• What Is Amazon Kinesis Video Streams
• C SDK
• Example: Kinesis Video Streams Producer SDK GStreamer Plugin

License

This library is licensed under the Apache 2.0 License.