Amazon Kinesis Video Streams Producer SDK Java

Build • Run • Troubleshooting • Resources • Development • Release Notes • License

Introduction

Amazon Kinesis Video Streams makes it easy to securely stream video from connected devices to AWS for analytics, machine learning (ML), and other processing.

The Amazon Kinesis Video Streams Producer SDK Java 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.

Resources

• Developer Guide - For in-depth getting started and usage information.
• Release Notes - To see the latest features, bug fixes, and changes in the SDK
• Issues - Report issues and submit pull requests
• SDK Documentation JavaDoc (master branch)
• SDK Documentation JavaDoc (develop branch)

Prerequisites

• Java 11, 17, or 21
• maven
• JNI libraries

Using pre-built JNI libraries

• You can find available pre-built KinesisVideoProducerJNI library in src/main/resources/lib/ for Mac (x64), Ubuntu (x64) and Raspbian (x86) and Windows 10.

Building JNI libraries

• If pre-built libraries did not work for you, KinesisVideoProducerJNI native library needs to be built first before running the Java demo application. Please follow the steps here.

Building the Java Producer SDK and Demo Applications from Source

In an IDE

Import the Maven project (pom.xml) to your IDE, it will find dependency packages from Maven and build.

Using command-line

Make sure you have Java and Maven installed on your system.

git clone https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-java.git
cd amazon-kinesis-video-streams-producer-sdk-java
mvn clean compile assembly:single

Run Examples

Preparing a stream

AWS Management Console

You can create a stream using the AWS management console using the instructions here.

You can also edit the data retention in the AWS management console in the section under the media player.

AWS CLI

If you have AWS CLI and jq installed and configured, you can also run the prepareStream.sh.

This script will create a stream with the given name if the stream doesn't exist.

[!NOTE] The script will increase the data retention of your stream to 2 hours if it's 0.

./scripts/prepareStream.sh <YourKinesisVideoStreamName>

Launching Demoapp sample application

Demo app will start running and putting sample video frames in a loop into Kinesis Video Streams. You can change your stream settings in DemoAppMain.java before you run the app.

To run DemoAppMain.java in ./src/main/demo with JVM arguments:

1. Credentials: aws.accessKeyId, aws.secretKey, aws.sessionToken (optional)
2. Stream name: kvs-stream
3. Path to JNI library directory: java.library.path
4. Log4j configuration file: log4j.configurationFile

java -classpath target/*jar-with-dependencies.jar \
  -Daws.accessKeyId=<YourAwsAccessKey> \
  -Daws.secretKey=<YourAwsSecretKey> \
  -Dkvs-stream=<YourKinesisVideoStreamName> \
  -Djava.library.path=<NativeLibraryPath ex. src/main/lib/mac> \
  -Dlog4j.configurationFile=log4j2.xml \
  com.amazonaws.kinesisvideo.demoapp.DemoAppMain

[!NOTE] On Windows command prompt, the newline separator is ^ instead of \.

[!NOTE] NativeLibraryPath must contain path to the folder containing your "KinesisVideoProducerJNI" library (not to the file itself). File name depends on your operating system: * libKinesisVideoProducerJNI.so for Linux * libKinesisVideoProducerJNI.dylib for Mac OS * KinesisVideoProducerJNI.dll for Windows

[!TIP] Pre-built JNI libraries for some systems can be found in src/resources/lib.

[!NOTE] If your system isn't part of the pre-built JNI libraries, you will need to build the JNI yourself. You can find instructions here.

Changing the log level

Locate the log4j configuration file log4j2.xml, and change the level (currently WARN) to something else like INFO or DEBUG. For a full list of levels, see the log4j documentation.

<Loggers>
    <Root level="WARN">
        <AppenderRef ref="ConsoleAppender"/>
        <AppenderRef ref="RollingFile"/>
    </Root>
</Loggers>

To change log level for a single class

To change the log level for a single class, add a <Logger> element inside the <Loggers> section.

<Logger name="com.amazonaws.kinesisvideo.java.client.KinesisVideoJavaClientFactory" level="TRACE" additivity="false">
    <AppenderRef ref="ConsoleAppender"/>
    <AppenderRef ref="RollingFile"/>
</Logger>

In the example above, we set the JNI logs to TRACE.

Log levels to PIC equivalents: * TRACE = 1 -- LOG_LEVEL_VERBOSE * DEBUG = 2 -- LOG_LEVEL_DEBUG * INFO = 3 -- LOG_LEVEL_INFO * WARN = 4 -- LOG_LEVEL_WARN * ERROR = 5+ -- LOG_LEVEL_ERROR

Run API and functionality tests

mvn clean test -DargLine="\
  -Daws.accessKeyId=<YourAwsAccessKey> \
  -Daws.secretKey=<YourAwsSecretKey> \
  -Daws.sessionToken=<YourAwsSessionToken> \
  -Djava.library.path=<NativeLibraryPath> \
  -Dlog4j.configurationFile=log4j2.xml"

[!NOTE] The tests require pre-provisioned streams and require data retention enabled. If either or both conditions are not met, the tests will attempt to fix them before starting. Make sure this is OK in your account before running. Set the TEST_STREAMS_PREFIX environment variable to add a prefix to the streams used in the integration tests.

Generate code coverage report

mvn clean verify -DargLine="-Daws.accessKeyId=<YourAwsAccessKey> -Daws.secretKey=<YourAwsSecretKey> -Daws.sessionToken=<YourAwsSessionToken> -Djava.library.path=<NativeLibraryPath> -Dlog4j.configurationFile=log4j2.xml"

This will run the tests and generate a code coverage report. It will get output in target/site/jacoco. You can open target/site/jacoco/index.html in a web browser of your choice.

Run the demo application from Docker

Refer the README.md file in the dockerscripts folder for running the build and demo app within Docker container.

Launching PutMediaDemo sample application

Run PutMediaDemo.java to send sample mkv stream to Kinesis Video Streams. Note: ACCESS_KEY, SECRET_KEY, and a KINESIS_VIDEO_STREAM are required for running this sample application as well. However, this demo application does not require JNI.

-Daws.accessKeyId=<YourAwsAccessKey> -Daws.secretKey=<YourAwsSecretKey> -Dkvs-stream=<YourKinesisVideoStreamName>

for non-temporary AWS credential.

-Daws.accessKeyId=<YourAwsAccessKey> -Daws.secretKey=<YourAwsSecretKey> -Daws.sessionToken=<YourAwsSessionToken> -Dkvs-stream=<YourKinesisVideoStreamName>

Pre-built KinesisVideoProducerJNI library supported platforms

• Mac OS X (El capitan 10.11 or above)
• Ubuntu (14.04 or above)
• Raspbian (9 stretch or above)

Additional Examples

For additional examples on using Kinesis Video Streams Java SDK and Kinesis Video Streams Parsing Library refer:

Kinesis Video Streams Producer SDK CPP

Kinesis Video Streams Parser Library

Kinesis Video Streams Android

JavaDoc

Use the following command to build the JavaDoc locally:

mvn clean compile javadoc:javadoc

You can then open target/site/apidocs/index.html in a browser of your choice.

Troubleshooting

Class not found

If you receive an error like this:

Error: Could not find or load main class com.amazonaws.kinesisvideo.demoapp.DemoAppMain
Caused by: java.lang.ClassNotFoundException: com.amazonaws.kinesisvideo.demoapp.DemoAppMain

Check the file path to the .jar is correct, and that the class name is correct.

Unsatisfied link error - no KinesisVideoProducerJNI in java.library.path

Provide the path to the folder containing the KinesisVideoProducerJNI library (not the file itself) as part of java.library.path JVM argument.

Other Unsatisfied link error

If you notice error in loading the native library (JNI), it may be due to CPU architecture mismatch. Check the error in the logging output.

Sample output

20:49:47.747 [main] ERROR com.amazonaws.kinesisvideo.java.client.KinesisVideoJavaClientFactory - Unsatisfied link error.
java.lang.UnsatisfiedLinkError: /Users/me/Desktop/libKinesisVideoProducerJNI.dylib: dlopen(/Users/me/Desktop/libKinesisVideoProducerJNI.dylib, 0x0001): tried: '/Users/me/Desktop/libKinesisVideoProducerJNI.dylib' (mach-o file, but is an incompatible architecture (have 'x86_64', need 'arm64e' or 'arm64')), '/System/Volumes/Preboot/Cryptexes/OS/Users/me/Desktop/libKinesisVideoProducerJNI.dylib' (no such file), '/Users/me/Desktop/libKinesisVideoProducerJNI.dylib' (mach-o file, but is an incompatible architecture (have 'x86_64', need 'arm64e' or 'arm64'))
    at jdk.internal.loader.NativeLibraries.load(Native Method) ~[?:?]
    at jdk.internal.loader.NativeLibraries$NativeLibraryImpl.open(NativeLibraries.java:331) ~[?:?]
    at jdk.internal.loader.NativeLibraries.loadLibrary(NativeLibraries.java:197) ~[?:?]
    at jdk.internal.loader.NativeLibraries.loadLibrary(NativeLibraries.java:139) ~[?:?]
    at jdk.internal.loader.NativeLibraries.findFromPaths(NativeLibraries.java:259) ~[?:?]
    at jdk.internal.loader.NativeLibraries.loadLibrary(NativeLibraries.java:251) ~[?:?]
    at java.lang.ClassLoader.loadLibrary(ClassLoader.java:2451) ~[?:?]
    at java.lang.Runtime.loadLibrary0(Runtime.java:916) ~[?:?]
    at java.lang.System.loadLibrary(System.java:2063) ~[?:?]
    at com.amazonaws.kinesisvideo.internal.producer.jni.NativeLibraryLoader.loadNativeLibraryIndirect(NativeLibraryLoader.java:76) [classes/:?]
    at com.amazonaws.kinesisvideo.internal.producer.jni.NativeLibraryLoader.loadNativeLibrary(NativeLibraryLoader.java:44) [classes/:?]
    at com.amazonaws.kinesisvideo.internal.producer.jni.NativeKinesisVideoProducerJni.initializeLibrary(NativeKinesisVideoProducerJni.java:1175) [classes/:?]
    at com.amazonaws.kinesisvideo.internal.producer.jni.NativeKinesisVideoProducerJni.create(NativeKinesisVideoProducerJni.java:228) [classes/:?]
    at com.amazonaws.kinesisvideo.internal.producer.jni.NativeKinesisVideoProducerJni.createSync(NativeKinesisVideoProducerJni.java:246) [classes/:?]
    at com.amazonaws.kinesisvideo.internal.producer.jni.NativeKinesisVideoProducerJni.createSync(NativeKinesisVideoProducerJni.java:211) [classes/:?]
    at com.amazonaws.kinesisvideo.internal.client.NativeKinesisVideoClient.initializeNewKinesisVideoProducer(NativeKinesisVideoClient.java:239) [classes/:?]
    at com.amazonaws.kinesisvideo.internal.client.NativeKinesisVideoClient.initialize(NativeKinesisVideoClient.java:119) [classes/:?]
    at com.amazonaws.kinesisvideo.java.client.KinesisVideoJavaClientFactory.createKinesisVideoClient(KinesisVideoJavaClientFactory.java:154) [classes/:?]
    at com.amazonaws.kinesisvideo.java.client.KinesisVideoJavaClientFactory.createKinesisVideoClient(KinesisVideoJavaClientFactory.java:127) [classes/:?]
    at com.amazonaws.kinesisvideo.demoapp.DemoAppMain.main(DemoAppMain.java:65) [classes/:?]
Exception in thread "main" java.lang.RuntimeException: com.amazonaws.kinesisvideo.producer.ProducerException: Failed loading native library StatusCode: 0xd
    at com.amazonaws.kinesisvideo.demoapp.DemoAppMain.main(DemoAppMain.java:93)
Caused by: com.amazonaws.kinesisvideo.producer.ProducerException: Failed loading native library StatusCode: 0xd

If using the pre-built JNI libraries located in src/main/resources/lib, make sure you are using the one that matches your CPU architecture.

If your architecture isn't provided as one of the pre-built libraries, you will need to build the JNI yourself. Building the JNI on your local system will make sure the correct architecture and bit-ness are used. See instructions here.

[!NOTE] If you run into issues building the JNI on your system, please raise an