Amazon Kinesis Video Streams C WebRTC SDK

Pure C WebRTC Client for Amazon Kinesis Video Streams

Key Features • Build • Run • Documentation • Setup IoT • Use Pre-generated Certificates • Related • License

[!NOTE] We have switched from using the 'master' branch to the 'main' branch. Please update your references accordingly.

New feature announcements

Please refer to the release notes in Releases page

Key Features

• Audio/Video Support
• VP8
• H264
• Opus
• G.711 PCM (A-law)
• G.711 PCM (µ-law)
• Developer Controlled Media Pipeline
• Raw Media for Input/Output
• Callbacks for Congestion Control, FIR and PLI (set on RtcRtpTransceiver)
• DataChannels
• NACKs
• STUN/TURN Support
• IPv4/IPv6
• Signaling Client Included
• KVS Provides STUN/TURN and Signaling Backend
• Connect with Android/iOS/Web using pre-made samples
• Storage for WebRTC [NEW]
• Ingest media into a Kinesis Video Stream.
• Portable
• Tested on Linux/MacOS
• Tested on x64, ARMv5
• Build system designed for pleasant cross-compilation
• Small Install Size
• Sub 200k library size
• OpenSSL, libsrtp, libjsmn, libusrsctp and libwebsockets dependencies.

Build

Download

To download run the following command:

git clone https://github.com/awslabs/amazon-kinesis-video-streams-webrtc-sdk-c.git --single-branch -b main kvs-webrtc-sdk

You will also need to install pkg-config and CMake (requires 3.x, CMake 4.x is not yet supported) and a build environment

Configuring on Ubuntu / Unix

Create a build directory in the newly checked out repository, and execute CMake from it.

mkdir -p kvs-webrtc-sdk/build; cd kvs-webrtc-sdk/build; cmake ..

We have provided an example of using GStreamer to capture/encode video, and then send via this library. This is only built if pkg-config finds GStreamer is installed on your system.

On Ubuntu and Raspberry Pi OS you can get the libraries by running

sudo apt-get install cmake m4 pkg-config 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 

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 use the following flags to customize your build.

Configuring on Windows

Install MS Visual Studio Community / Enterprise, Strawberry perl, and Chocolatey if not installed already

Get the libraries by running the following in powershell

choco install gstreamer
choco install gstreamer-devel
curl.exe -o C:\tools\pthreads-w32-2-9-1-release.zip ftp://sourceware.org/pub/pthreads-win32/pthreads-w32-2-9-1-release.zip
mkdir C:\tools\pthreads-w32-2-9-1-release\
Expand-Archive -Path C:\tools\pthreads-w32-2-9-1-release.zip -DestinationPath C:\tools\pthreads-w32-2-9-1-release

Modify the path to the downloaded and unzipped PThreads in cmake in build_windows_openssl.bat if needed / unzipped at a path other than the one mentioned above

cmake -G "NMake Makefiles" -DBUILD_TEST=TRUE -DEXT_PTHREAD_INCLUDE_DIR="C:/tools/pthreads-w32-2-9-1-release/Pre-built.2/include/" -DEXT_PTHREAD_LIBRARIES="C:/tools/pthreads-w32-2-9-1-release/Pre-built.2/lib/x64/libpthreadGC2.a" ..

Modify the path to MSVC as well in the build_windows_openssl.bat if needed / installed a different version / location

call "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Auxiliary\Build\vcvarsall.bat" x86_amd64

Allow long paths before we start the build

git config --system core.longpaths true

Note that if the paths are still too long (which can cause the build to fail unfortunately), we recommend renaming the folders to use shorter names and moving them to C:/

Build the SDK

.github\build_windows_openssl.bat

To run the sample application, make sure that you've exported the following paths and appended them to env:Path for powershell

$env:Path += ';C:\webrtc\open-source\bin;C:\tools\pthreads-w32-2-9-1-release\Pre-built.2\dll\x64;C:\webrtc\build'

Dependency requirements

These would be applicable if the SDK is being linked with system dependencies instead of building from source by the SDK. libmbedtls: >= 2.25.0 & < 4.x.x libopenssl: = 1.1.1x libsrtp2 : <= 2.5.0 libusrsctp : <= 0.9.5.0 libwebsockets : >= 4.2.0

Cross-Compilation

If you wish to cross-compile CC and CXX are respected when building the library and all its dependencies. You will also need to set BUILD_OPENSSL_PLATFORM, BUILD_LIBSRTP_HOST_PLATFORM and BUILD_LIBSRTP_DESTINATION_PLATFORM. See our codecov.io for an example of this. Every commit is cross compiled to ensure that it continues to work.

Static Builds

If -DBUILD_STATIC_LIBS=TRUE then all dependencies and KVS WebRTC libraries will be built as static libraries.

CMake Arguments

You can pass the following options to cmake ..:

• -DBUILD_SAMPLE -- Build the sample executables. ON by default.
• -DIOT_CORE_ENABLE_CREDENTIALS -- Build the sample applications using IoT credentials. OFF by default.
• -DENABLE_DATA_CHANNEL -- Build SDK & samples with data channel. ON by default.
• -DBUILD_STATIC_LIBS -- Build all KVS WebRTC and third-party libraries as static libraries. Default: OFF (shared build).
• -DADD_MUCLIBC -- Add -muclibc c flag
• -DBUILD_DEPENDENCIES -- Whether or not to build depending libraries from source. ON by default.
• -DBUILD_WEBSOCKETS -- Build libwebsockets from source. Defaults to value of BUILD_DEPENDENCIES.
• -DBUILD_SRTP -- Build libsrtp from source. Defaults to value of BUILD_DEPENDENCIES.
• -DUSE_LIBSRTP3 -- Build and link against libsrtp 3.x (cisco/libsrtp main, renamed to libsrtp3) instead of the long-standing 2.x default. OFF by default. The 3.x line adds PSA Crypto / mbedTLS 4 support but introduces public API breaks (opaque srtp_policy_t, separate src/dst buffers on srtp_protect/srtp_unprotect, separate master key + salt) — these are handled internally by the SDK. Use this if your platform requires mbedTLS 4 (e.g. ESP-IDF v6).
• -DBUILD_USRSCTP -- Build libusrsctp from source. Defaults to value of BUILD_DEPENDENCIES.
• -DBUILD_OPENSSL_PLATFORM -- If building OpenSSL what is the target platform
• -DBUILD_LIBSRTP_HOST_PLATFORM -- If building LibSRTP what is the current platform
• -DBUILD_LIBSRTP_DESTINATION_PLATFORM -- If building LibSRTP what is the destination platform
• -DBUILD_TEST=TRUE -- Build unit/integration tests, may be useful for confirm support for your device. ./tst/webrtc_client_test
• -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_SANITIZER -- Build with UndefinedBehaviorSanitizer
• -DCMAKE_BUILD_TYPE -- Build Release/Debug libraries. By default, the SDK generates Release build. The standard options are listed here
• -DLINK_PROFILER -- Link with gperftools (available profiler options are listed here)
• -DPKG_CONFIG_EXECUTABLE -- Set pkg config path. This might be required to find gstreamer's pkg config specifically on Windows.
• -DENABLE_KVS_THREADPOOL -- Enable the KVS threadpool which is off by default.
• -DENABLE_STATS_CALCULATION_CONTROL -- Enable the runtime control of ICE agent stats calculations.
• -DINCREASE_PRECISION_TIMING_LOGS -- Default ON. ON=Use 2 decimals in PROFILE-logs timing. OFF=Truncates down to whole ms.
• -DPRODUCER_C_VERSION_OVERRIDE -- Override KVS Producer-C version (git tag).
• -DPIC_VERSION_OVERRIDE -- Override KVS PIC version (git tag).
• -DPARALLEL_BUILD -- Build dependencies with multiple cores. OFF by default. Disabled on Windows.

These options get propagated to PIC: * -DKVS_STACK_SIZE -- Default stack size for threads created using THREAD_CREATE(), in bytes.

To clean up the open-source and build folders from previous build, use cmake --build . --target clean from the build folder

For windows builds, you will have to include additional flags for libwebsockets CMake. Add the following flags to your cmake command, or edit the CMake file in ./CMake/Dependencies/libwebsockets-CMakeLists.txt with the following:

cmake .. -DLWS_HAVE_PTHREAD_H=1 -DLWS_EXT_PTHREAD_INCLUDE_DIR="C:\Program Files (x86)\pthreads\include" -DLWS_EXT_PTHREAD_LIBRARIES="C:\Program Files (x86)\pthreads\lib\x64\libpthreadGC2.a" -DLWS_WITH_MINIMAL_EXAMPLES=1

Be sure to edit the path to whatever pthread library you are using, and the proper path for your environment.

Build

To build the library and the provided samples run make in the build directory you executed CMake.

make

Building with dependencies off

In addition to the dependencies already installed, install the dependencies using the appropriate package manager.

On Ubuntu: sudo apt-get install libsrtp2-dev libusrsctp-dev libwebsockets-dev

On MacOS: brew install srtp libusrsctp libwebsockets

To use OpenSSL:

cmake .. -DBUILD_DEPENDENCIES=OFF -DUSE_OPENSSL=ON

To use MBedTLS:

cmake .. -DBUILD_DEPENDENCIES=OFF -DUSE_OPENSSL=OFF -DUSE_MBEDTLS=ON

Note: Please follow the dependency requirements to confirm the version requirements are satisfied to use the SDK with system installed dependencies. If the versions are not satisfied, this option would not work and enabling the SDK to build dependencies for you would be the best option to go ahead with.

[!CAUTION] System-installed libwebsockets and libsrtp packages (from apt, brew, etc.) are typically built against OpenSSL. If you are building the SDK with -DUSE_MBEDTLS=ON and relying on system packages, you might encounter linker or runtime erros. You must also build these dependencies from source (-DBUILD_DEPENDENCIES=ON) to ensure they are compiled against mbedTLS. This does not apply if you have manually built and installed mbedTLS-linked versions of these libraries.

[!TIP] If you are unsure, recommendation is to enable SDK to build dependencies using -DBUILD_DEPENDENCIES=ON

Building selective dependencies from source

If your system has some compatible dependencies but not others, you can selectively build individual libraries from source using the per-dependency flags. Each flag defaults to the value of BUILD_DEPENDENCIES.

To just build libwebsockets from source and use system package for others

cmake .. -DBUILD_DEPENDENCIES=OFF -DBUILD_WEBSOCKETS=ON -DUSE_OPENSSL=ON

To build everything from source except libusrsctp (use system package):

cmake .. -DBUILD_DEPENDENCIES=ON -DBUILD_USRSCTP=OFF

Available per-dependency flags: * -DBUILD_WEBSOCKETS=ON/OFF -- Build libwebsockets from source (default: same as BUILD_DEPENDENCIES) * -DBUILD_SRTP=ON/OFF -- Build libsrtp from source (default: same as BUILD_DEPENDENCIES) * -DBUILD_USRSCTP=ON/OFF -- Build libusrsctp from source (default: same as BUILD_DEPENDENCIES)

Run

Setup your environment with your AWS account credentials and AWS region:

• First set the appropriate environment variables so you can connect to KVS. If you want to use IoT certificate instead, check Setup IoT.

export AWS_ACCESS_KEY_ID=<AWS account access key>
export AWS_SECRET_ACCESS_KEY=<AWS account secret key>

• Optionally, set AWS_SESSION_TOKEN if integrating with temporary token

export AWS_SESSION_TOKEN=<session token>

• Region is optional, if not being set, then us-west-2 will be used as default region.

export AWS_DEFAULT_REGION=<AWS region>

Setup logging:

Set up the desired log level. The log levels and corresponding values currently available are: 1. LOG_LEVEL_VERBOSE ---- 1 2. LOG_LEVEL_DEBUG ---- 2 3. LOG_LEVEL_INFO ---- 3 4. LOG_LEVEL_WARN ---- 4 5. LOG_LEVEL_ERROR ---- 5 6. LOG_LEVEL_FATAL ---- 6 7. LOG_LEVEL_SILENT ---- 7 8. LOG_LEVEL_PROFILE ---- 8

To set a log level, run the following command:

export AWS_KVS_LOG_LEVEL=<LOG_LEVEL>

For example, the follow