search

awslabs / amazon-kinesis-video-streams-producer-sdk-java

Allows developers to install and customize their connected camera and other devices to securely stream video, audio, and time-encoded data to Kinesis Video Streams
Apache License 2.0
78 stars 77 forks source link

readme

Amazon Kinesis Video Streams Producer SDK Java

License

This library is licensed under the Apache License, 2.0.

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

Prerequisites

Building from Source

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

Examples

Launching Demoapp sample application

Run DemoAppMain.java in ./src/main/demo with JVM arguments set to

-Daws.accessKeyId=<YourAwsAccessKey> -Daws.secretKey=<YourAwsSecretKey> -Dkvs-stream=<YourKinesisVideoStreamName> -Djava.library.path=<NativeLibraryPath> -Dlog4j.configurationFile=log4j2.xml

for non-temporary AWS credential.

-Daws.accessKeyId=<YourAwsAccessKey> -Daws.secretKey=<YourAwsSecretKey> -Daws.sessionToken=<YourAwsSessionToken> -Dkvs-stream=<YourKinesisVideoStreamName> -Djava.library.path=<NativeLibraryPath> -Dlog4j.configurationFile=log4j2.xml

for temporary AWS credential.

Note: NativeLibraryPath must contain your "KinesisVideoProducerJNI" library. File name depends on your Operating System:

If you are using pre-built libraries, please specify the path of library. Take pre-build library for Mac as example, you can specify src/resources/lib/mac as .

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.

Run the demo application from command line

If you want to run the DemoAppMain, follow the steps below. See Prerequisites to find available native library needed to run DemoAppMain.

Change the current working directory to

$ cd /<YOUR_FOLDER_PATH_WHERE_SDK_IS_DOWNLOADED>/amazon-kinesis-video-streams-producer-sdk-java/

Compile and assemble Java SDK, Java Demoapp and the Maven dependencies

$ mvn clean compile assembly:single

Start the demo app

$ java -classpath target/amazon-kinesis-video-streams-producer-sdk-java-1.12.1-jar-with-dependencies.jar -Daws.accessKeyId=<ACCESS_KEY> -Daws.secretKey=<SECRET_KEY> -Dkvs-stream=<KINESIS_VIDEO_STREAM_NAME> -Djava.library.path=<NativeLibraryPath> -Dlog4j.configurationFile=log4j2.xml com.amazonaws.kinesisvideo.demoapp.DemoAppMain
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"
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

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

Troubleshooting

If you notice error in loading the native library (JNI), then check the output of ldd or otool

$ ldd libKinesisVideoProducerJNI.so

or in MacOS

$ otool -L libKinesisVideoProducerJNI.dylib

This will provide details on missing libraries during linking; If the output shows missing shared libraries, then run the following commands to link:

Run the following from the build directory in CPP producer SDK:

cmake .. -DBUILD_JNI=TRUE 
make

Then, provide the path to the libKinesisVideoProducerJNI.dylib library.

This should resolve native library loading issues.

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 Notes

Release 1.12.1 (May 2022)

Release 1.12.0 (February 2022)

Release 1.11.0 (11 September 2020)

Release 1.10.0 (29 May 2020)

Release 1.9.5 (16 Jan 2020)

Release 1.9.4 (9 July 2019)

Release 1.9.3 (12 March 2019)

Release 1.9.2 (21 Feburary 2019)

Release 1.9.1 (19 Feburary 2019)

Release 1.9.0 (8 Feburary 2019)

Release 1.8.0 (25 January 2019)

Release 1.7.0 (3 December 2018)

Release 1.6.0 (3 December 2018)

Release 1.5.0 (24 August 2018)

Release 1.3.1 (23 July 2018)

Release 1.3.0 (15 March 2018)

Release 1.2.1 (February 2018)

Release 1.2.0 (February 2018)

Release 1.1.0 (December 2017)

Release 1.0.0 (November 2017)