Skip to content

Building and Using JNI

Jump to bottom
sirknightj edited this page Sep 9, 2025 · 8 revisions

Pre-built JNI libraries can be found in https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-java/tree/master/src/main/resources/lib and https://github.com/aws-amplify/aws-sdk-android/tree/main/aws-android-sdk-kinesisvideo/src/main/jniLibs.

Note that libraries are platform dependent. If your target machine uses a different CPU architecture than the pre-built JNI libraries, you will need to build it yourself. Follow the instructions below.

Building JNI

The JNI has dependencies:

  • Java (please make sure JAVA_HOME path is set correctly!)
  • PIC -- this dependency gets built automatically in the dependency folder as part of the CMake build process.

You will need to make sure you have the following installed on your system:

  • git
  • CMake
  • A compiler toolchain (e.g. GCC, Clang, or MSVC)

Building on Linux/macOS

If you have a compiler toolchain installed (e.g., GCC or Clang), build with:

git clone https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-java.git
cd amazon-kinesis-video-streams-producer-sdk-java
git checkout develop
mkdir build
cd build
cmake ..
make -j

You can find the output JNI in the build folder. It will be called libKinesisVideoProducerJNI.extension, where extension is either dylib on Mac or so on Linux.

The PIC dependency will be located in the dependency folder. Its file path relative to the build directory is ../dependency/.

Building on Windows

Open a Developer Command Prompt for Visual Studio and run the following commands:

git clone https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-java.git producer
mv producer C:/
cd C:/producer
git checkout develop
mkdir build
cd build
cmake .. -G "Visual Studio 17 2022"
cmake --build . --config Release

Note

There is a file path length limit, so it is recommended to move the project to a short location such as C:/.

The compiled JNI library KinesisVideoProducerJNI.dll will be in the Release directory, which will get created in your build directory.

Note

If there are issues building the JNI, please create an issue in the repo where the JNI is located.

Tip

For more information on how JNI works, see https://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/intro.html.

Using JNI

When running the samples or SDK, you will need to set java.library.path JVM option to the folder containing the JNI library so that the SDK can load it.

Example:

java -classpath target/...-jar-with-dependencies.jar \
  -Daws.accessKeyId=... \
  -Daws.secretKey=... \
  -Djava.library.path=$(pwd)/src/main/resources/lib/mac/ \
  -Dkvs-stream=demo-stream \
  -Dlog4j.configurationFile=log4j2.xml \
  com.amazonaws.kinesisvideo.demoapp.DemoAppMain

Troubleshooting

Unable to find JNI error

If you get an error like this:

CMake Error at /opt/homebrew/share/cmake/Modules/FindPackageHandleStandardArgs.cmake:227 (message):
  Could NOT find JNI (missing: JAVA_INCLUDE_PATH JAVA_INCLUDE_PATH2 AWT)
Call Stack (most recent call first):
  /opt/homebrew/share/cmake/Modules/FindPackageHandleStandardArgs.cmake:591 (_FPHSA_FAILURE_MESSAGE)
  /opt/homebrew/share/cmake/Modules/FindJNI.cmake:590 (find_package_handle_standard_args)
  CMakeLists.txt:204 (find_package)

Make sure that you have Java installed and JAVA_HOME is set correctly.

echo $JAVA_HOME
ls $JAVA_HOME
tree -L 1 $JAVA_HOME
/Library/Java/JavaVirtualMachines/amazon-corretto-11.jdk/Contents/Home
├── ADDITIONAL_LICENSE_INFO
├── ASSEMBLY_EXCEPTION
├── bin
├── commitId.txt
├── conf
├── include
├── jmods
├── legal
├── lib
├── LICENSE
├── man
├── README.md
├── release
└── version.txt

And, make sure that the JNI headers are installed.

tree $JAVA_HOME/include
/Library/Java/JavaVirtualMachines/amazon-corretto-11.jdk/Contents/Home/include
├── classfile_constants.h
├── darwin
│   ├── jawt_md.h
│   └── jni_md.h
├── jawt.h
├── jdwpTransport.h
├── jni.h              # <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
├── jvmti.h
└── jvmticmlr.h

Caution

Perform a Clean build after changing the environment variables by deleting the build and dependency folder since some variables are cached by CMake.

Unsatisfied link error

Check the logs for any additional information. Things to double-check:

  1. The java.library.path should be set to the folder containing JNI, not pointing to the JNI library itself.
  2. Try using absolute file path

The pre-built library might be for a different bit-ness (32 vs 64 bit). Refer to Building JNI for instructions to build the JNI on your system.

You can run the file utility on the library to verify if the file is compatible with your system.

MacOS example:

If you have a Mac with Intel chip, the JNI used should look like:

file libKinesisVideoProducerJNI.dylib
libKinesisVideoProducerJNI.dylib: Mach-O 64-bit dynamically linked shared library x86_64

If you have a Mac with Apple Silicon chip, the JNI used should look like:

file libKinesisVideoProducerJNI.dylib
libKinesisVideoProducerJNI.dylib: Mach-O 64-bit dynamically linked shared library arm64

Note

The JNI used to be part of https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-cpp prior to version 3.5.0.

Clone this wiki locally