Amazon Kinesis Video Streams WebRTC SDK for C

Transport-Wide Congestion Control (TWCC) is a mechanism used to prevent video quality degradation and network stalls during congestion. It creates a feedback loop where the receiver reports when specific packets arrive, allowing the sender to detect growing delays and adjust the video/audio bitrate accordingly.

How it works:

1. Sender: Numbers each outgoing packet sequentially.
2. Receiver: Notes arrival times for these numbered packets and periodically sends feedback.
3. Sender: Compares send times vs. receive times to detect congestion via increasing delays.
4. Sender: Adjusts the encoder bitrate up or down based on this analysis.

Generating certificates via createDtlsSession() can take 5-15 seconds on low-performance embedded devices. To avoid this latency during peer connection creation, you can pre-generate certificates and dequeue them from a pool.

Best Practice: Rotate certificates often (preferably for every peer connection) to maintain security.

Configuration: Use the following environment variables to control pre-generation behavior:

• KVS_PRE_GENERATE_CERT_ENABLED: Enable/disable (TRUE/FALSE).
• KVS_PRE_GENERATE_CERT_PERIOD_MS: Interval to check/generate (100-60000 ms).
• KVS_PRE_GENERATE_CERT_MAX: Max certificates to keep in queue (0-10).

retStatus = stackQueueDequeue(pSampleConfiguration->pregeneratedCertificates, &data);
if (retStatus == STATUS_SUCCESS) {
    pRtcCertificate = (PRtcCertificate) data;
    configuration.certificates[0] = *pRtcCertificate;
}

You can adjust ICE timeout values in KvsRtcConfiguration to handle poor network conditions.

Key parameters include:

• iceCandidateNominationTimeout: Increase this if you need more time to gather relay (TURN) candidates before nomination begins.
• iceLocalCandidateGatheringTimeout: Increase this to allow more time for gathering all potential candidates (host, srflx, relay) on slow networks.
• iceConnectionCheckTimeout: Increase this for unstable/slow networks to allow more time for binding request/response exchanges.
• iceConnectionCheckPollingInterval: Controls the frequency of connectivity checks. While decreasing this can speed up connection in high-performance networks, it is generally recommended to stick to the default (50 ms) to remain compliant with RFC 8445.

Before running the SDK or its samples, you must set up your environment with your AWS account credentials and the target AWS region. If you are using temporary credentials, you must also set the AWS_SESSION_TOKEN.

To connect to Kinesis Video Streams (KVS), set the following environment variables:

export AWS_ACCESS_KEY_ID=<AWS account access key>
export AWS_SECRET_ACCESS_KEY=<AWS account secret key>
# Optional: for temporary credentials
export AWS_SESSION_TOKEN=<session token>
# Optional: defaults to us-west-2 if not set
export AWS_DEFAULT_REGION=<AWS region>

To use TWCC, you must enable it in your configuration. In the provided GStreamer samples, TWCC is enabled by default.

To ensure TWCC is active, ensure the following configuration settings are applied:

• pSampleConfiguration->enableTwcc = TRUE
• KvsRtcConfiguration.disableSenderSideBandwidthEstimation = FALSE

Note: TWCC bitrate adaptation is only implemented in GStreamer-based samples. Non-GStreamer samples (like kvsWebrtcClientMaster) do not include encoder bitrate control because they send pre-encoded frames from a file rather than a live stream.

// TWCC is enabled by default in samples:
pSampleConfiguration->enableTwcc = TRUE;

// Ensure sender-side bandwidth estimation is NOT disabled:
KvsRtcConfiguration.disableSenderSideBandwidthEstimation = FALSE;

The aggregate.py script aggregates PROFILE log metrics from Kinesis Video Streams WebRTC logs. You can provide a single file, multiple specific files, or use wildcards to target all logs in a directory.

Supported usage patterns:

• Single file: Pass the path to one log file.
• Multiple files: Pass multiple paths as arguments.
• Directory pattern: Use shell wildcards (e.g., *) to include all matching log files in a directory.

# Single file
python3 ./scripts/profile-stats/aggregate.py /path/to/log.txt

# Multiple files
python3 ./scripts/profile-stats/aggregate.py /path/to/log1.txt /path/to/log2.txt

# All logs in directory
python3 ./scripts/profile-stats/aggregate.py ./build/kvsFileLogFilter.*

If you want to use libraries already installed on your system (e.g., via apt or brew) instead of having the SDK build them from source, use -DBUILD_DEPENDENCIES=OFF.

Required Versions:

• libmbedtls: >= 2.25.0 & < 4.x.x
• libopenssl: = 1.1.1x
• libsrtp2: <= 2.5.0
• libusrsctp: <= 0.9.5.0
• libwebsockets: >= 4.2.0

Usage Examples:

To use OpenSSL:

cmake .. -DBUILD_DEPENDENCIES=OFF -DUSE_OPENSSL=ON

To use MBedTLS:

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

CAUTION

System-installed libwebsockets and libsrtp are typically built against OpenSSL. If you use -DUSE_MBEDTLS=ON with system packages, you may encounter linker/runtime errors. To ensure compatibility with mbedTLS, it is recommended to build these dependencies from source (-DBUILD_DEPENDENCIES=ON).

To identify code paths causing high resource usage, recompile the SDK with the LINK_PROFILER flag:

cmake .. -DLINK_PROFILER=ON

This links the SDK with gperftools. Once compiled, use the following environment variables to generate profiles:

Heap Profile:

HEAPPROFILE=/tmp/heap.prof /path/to/your/binary

CPU Profile:

CPUPROFILE=/tmp/cpu.prof /path/to/your/binary