Amazon Kinesis Video Streams C WebRTC SDK 详解与实践指南

本指南面向希望快速理解并上手使用 Amazon Kinesis Video Streams WebRTC C SDK 的工程师，聚焦“构建、运行、架构、调试与优化”。文档来自仓库源码与官方 README 的系统梳理，包含分层架构图、关键模块职责、样例运行流程与常用参数对照表。

适用仓库：amazon-kinesis-video-streams-webrtc-sdk-c（当前版本在 CMakeLists.txt 中标注为 1.12.1）

快速索引

• 构建与依赖
• 运行样例与日志
• 总体架构与数据流
• 核心模块详解
• 内存与性能优化
• IoT 凭证与安全
• 调试定位与排障
• 网络端口与连通性
• 常见问题与建议
• 参考与扩展

构建与依赖

获取与初始化

git clone https://github.com/awslabs/amazon-kinesis-video-streams-webrtc-sdk-c.git --single-branch -b main kvs-webrtc-sdk
mkdir -p kvs-webrtc-sdk/build && cd kvs-webrtc-sdk/build
cmake ..
make

依赖说明（如使用系统库）

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

默认构建会自动下载并编译依赖。若需使用系统已安装库，可在 cmake 时关闭依赖构建：

# 使用 OpenSSL
cmake .. -DBUILD_DEPENDENCIES=OFF -DUSE_OPENSSL=ON
# 使用 mbedTLS
cmake .. -DBUILD_DEPENDENCIES=OFF -DUSE_OPENSSL=OFF -DUSE_MBEDTLS=ON

常用 CMake 选项

• -DBUILD_SAMPLE=ON：构建样例程序（默认 ON）
• -DIOT_CORE_ENABLE_CREDENTIALS=ON：样例使用 IoT 凭证（默认 OFF）
• -DENABLE_DATA_CHANNEL=ON：启用 DataChannel（默认 ON）
• -DBUILD_STATIC_LIBS=TRUE：静态构建 KVS 与第三方库（默认 OFF）
• -DADDRESS_SANITIZER / -DMEMORY_SANITIZER / -DTHREAD_SANITIZER / -DUNDEFINED_BEHAVIOR_SANITIZER：启用对应 Sanitizer
• -DCMAKE_BUILD_TYPE=Release|Debug：构建类型（默认 Release）
• -DLINK_PROFILER=ON：链接 gperftools 进行性能分析
• -DENABLE_KVS_THREADPOOL=ON：启用 SDK 线程池（默认 OFF）
• -DKVS_STACK_SIZE=<bytes>：为 SDK 统一设置线程栈大小（透传到 PIC）
• -DENABLE_STATS_CALCULATION_CONTROL=ON：使应用可控制 ICE 统计计算（运行时）

平台提示

• macOS M1：cmake .. -DBUILD_OPENSSL_PLATFORM=darwin64-arm64-cc
• 32 位 Raspbian GNU/Linux 11：cmake .. -DBUILD_OPENSSL_PLATFORM=linux-armv4

运行样例与日志

环境变量（凭证与区域）

export AWS_ACCESS_KEY_ID=<access key>
export AWS_SECRET_ACCESS_KEY=<secret key>
export AWS_SESSION_TOKEN=<session token 可选>
export AWS_DEFAULT_REGION=<region 可选，默认 us-west-2>

日志级别

• 映射：VERBOSE=1、DEBUG=2、INFO=3、WARN=4、ERROR=5、FATAL=6、SILENT=7、PROFILE=8

export AWS_KVS_LOG_LEVEL=2   # DEBUG
export AWS_ENABLE_FILE_LOGGING=TRUE  # 文件日志（build/ 下生成 kvsFileLogFilter.x）

如需更详细的函数进出跟踪，在样例的 CMakeLists.txt 添加：add_definitions(-DLOG_STREAMING) 并将日志级别设为 VERBOSE。

CA 证书路径（可选）

# 环境变量方式（默认指向 ./certs/cert.pem）
export AWS_KVS_CACERT_PATH=../certs/cert.pem
# 或 CMake 方式
cmake .. -DKVS_CA_CERT_PATH=/path/to/cert.pem

样例程序

构建完成后，样例位于 build/samples/。

• Master（发送本地测试帧/设备/RTSP，支持存储）

./samples/kvsWebrtcClientMaster <channelName> <storage-option> <audio-codec> <video-codec>
# 启用 “Storage for WebRTC”
./samples/kvsWebrtcClientMaster <channelName> 1 <audio-codec> <video-codec>
# 允许编解码：audio=opus（默认），video=h264（默认）| h265

• Master（GStreamer 管道）

./samples/kvsWebrtcClientMasterGstSample <channelName> <mediaType> <sourceType>
# RTSP 示例
./samples/kvsWebrtcClientMasterGstSample <channelName> <mediaType> rtspsrc rtsp://<rtspUri>
# 指定编解码（例）
./samples/kvsWebrtcClientMasterGstSample <channelName> audio-video testsrc opus h264

• Viewer（接收媒体，默认仅记录到日志；写文件请用 Gst 版）

./samples/kvsWebrtcClientViewer <channelName> <audio-codec> <video-codec>

• Viewer（GStreamer 文件输出）

./samples/kvsWebrtcClientViewerGstSample <channelName> <mediaType> <audio-codec> <video-codec>

• 观看方式：KVS 控制台 WebRTC Viewer 或 WebRTC SDK Test Page

使用 GStreamer 生成测试帧

# H264
gst-launch-1.0 videotestsrc pattern=ball num-buffers=1500 ! timeoverlay ! videoconvert ! video/x-raw,format=I420,width=1280,height=720,framerate=25/1 ! queue ! x264enc bframes=0 speed-preset=veryfast bitrate=512 byte-stream=TRUE tune=zerolatency ! video/x-h264,stream-format=byte-stream,alignment=au,profile=baseline ! multifilesink location="frame-%04d.h264" index=1
# H265
gst-launch-1.0 videotestsrc pattern=ball num-buffers=1500 ! timeoverlay ! videoconvert ! video/x-raw,format=I420,width=1280,height=720,framerate=25/1 ! queue ! x265enc speed-preset=veryfast bitrate=512 tune=zerolatency ! video/x-h265,stream-format=byte-stream,alignment=au,profile=main ! multifilesink location="frame-%04d.h265" index=1
# Opus
gst-launch-1.0 audiotestsrc num-buffers=618 wave=sine volume=0.4 ! audioconvert ! audioresample ! opusenc ! audio/x-opus,rate=48000,channels=2 ! multifilesink location="sample-%03d.opus" index=1

总体架构与数据流

组件关系图（Mermaid）

呼叫流程时序（Offer/Answer）

sequenceDiagram
  participant M as Master (C SDK)
  participant K as KVS Signaling
  participant V as Viewer (JS/iOS/Android)
  M->>K: Create/Connect channel; Get ICE servers
  M->>M: createPeerConnection; addTransceiver; setLocalDescription(offer)
  M->>K: Send SDP offer + trickle ICE
  V->>K: Connect; receive offer; setRemoteDescription
  V->>V: createAnswer; setLocalDescription(answer)
  K-->>M: Deliver SDP answer
  M->>M: setRemoteDescription(answer)
  M<->>V: ICE candidate exchange (trickle)
  M<->>V: DTLS handshake; SRTP keying
  M->>V: RTP/RTCP media流; SCTP DataChannel（可选）

核心模块详解（src/source/）

• Signaling/（信令客户端）

  • 负责与 KVS 信令服务交互：获取端点、ICE 服务器配置、连接、消息发送/接收（Offer/Answer/Candidate）。
  • 重要文件：Signaling.c、Signaling.h，包含丰富的诊断指标（如 getEndpointCallTime、connectCallTime 等）。

• PeerConnection/（点对点连接）

  • 统一协调：SDP、ICE、DTLS、SRTP、SCTP、Transceiver 与轨道、TWCC 拥塞控制回调、RTCP 报告计划等。
  • PeerConnection.c/.h：管理生命周期（创建/释放）、完成 DTLS/SRTP 会话、DataChannel 哈希表/状态、TWCC 扩展 ID、MTU 设置等。
  • Rtp.c/.h：RTP 媒体发送/接收、转接到 JitterBuffer、SSRC 管理。
  • Rtcp.c/.h：RTCP Receiver/Sender Report、NACK/PLI/FIR 处理；rtcpReportsCallback 定时发送。

• Ice/（ICE Agent）

  • 候选收集与连通性检测，支持 Host/Srflx/Prflx/Relay；解析 SDP candidate 行，执行绑定与提名。
  • 重要文件：IceAgent.c/.h；含候选解析器、连接检查、优先级计算、候选对诊断统计对象。

• Crypto/（加密）

  • DTLS 会话与证书处理；可使用预生成证书降低嵌入式设备握手耗时。

• Srtp/（安全 RTP）

  • 在 DTLS 握手完成后建立 SRTP 会话，保护音视频媒体传输。

• Sctp/（数据通道）

  • 实现 WebRTC DataChannel 的 SCTP 层，支持可靠/不可靠通道、优先级等。

• Sdp/（会话描述）

  • SDP Offer/Answer 生成与解析，处理 setup 属性（DTLS 客户端/服务器角色）、ice-ufrag/pwd 等。

• Stun/ / Turn/（NAT 穿越）

  • STUN：反射地址探测；TURN：中继传输，改善受限网络下的连通性。

• Metrics/（统计）

  • ICE Server、Local/Remote Candidate、Candidate Pair 等统计；可通过 CMake 开关控制是否计算以节省内存。

• Threadpool/（线程池）

  • 可选的线程池优化：在连接建立阶段降低延迟；通过环境变量控制最小/最大线程数。

内存与性能优化

RTP 滚动缓冲（NACK/JitterBuffer）

SDK 维护 RTP Rolling Buffer，用于应对 NACK 与 JitterBuffer 回读。容量由以下参数决定：

• MTU（默认 1200 bytes）
• 缓冲时长（默认 3s）
• 期望码率（默认 Video 5 Mibps、Audio 1 Mibps）

容量计算：

Capacity = BufferDurationSec * Bitrate(bps) / 8 / MTU

通过 configureTransceiverRollingBuffer(...) 设置，示例：

RtcMediaStreamTrack videoTrack;
videoTrack.kind = MEDIA_STREAM_TRACK_KIND_VIDEO;
videoTrack.codec = RTC_CODEC_H264_PROFILE_42E01F_LEVEL_ASYMMETRY_ALLOWED_PACKETIZATION_MODE;
CHK_STATUS(configureTransceiverRollingBuffer(pVideoRtcRtpTransceiver, &videoTrack, 0.2 /* 200ms */, 150 * 1024 /* 150 kibps */));

注意：过小的容量在弱网+多次重传下可能导致卡顿或丢帧。

TWCC（Transport-Wide Congestion Control）

• 样例默认开启：pSampleConfiguration->enableTwcc = TRUE
• 应用集成：
  • configuration.kvsRtcConfiguration.disableSenderSideBandwidthEstimation = FALSE;
  • 注册回调 peerConnectionOnSenderBandwidthEstimation(..., sampleSenderBandwidthEstimationHandler) 根据丢包/延时动态调码率。

线程池

cmake .. -DENABLE_KVS_THREADPOOL=ON
export AWS_KVS_WEBRTC_THREADPOOL_MIN_THREADS=3
export AWS_KVS_WEBRTC_THREADPOOL_MAX_THREADS=10

MTU 与分片

若能建连但媒体不通，请检查实际网络 MTU 是否高于源码中设置（参考 PeerConnection/Rtp.h）。

IoT 凭证与安全

• 建议遵循最小权限原则（IAM Best Practices）。典型 IoT Role 权限（示例）：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "kinesisvideo:DescribeSignalingChannel",
        "kinesisvideo:CreateSignalingChannel",
        "kinesisvideo:GetSignalingChannelEndpoint",
        "kinesisvideo:GetIceServerConfig",
        "kinesisvideo:ConnectAsMaster"
      ],
      "Resource": "arn:aws:kinesisvideo:*:*:channel/${credentials-iot:ThingName}/*"
    }
  ]
}

• 样例切换到 IoT 模式：

cmake .. -DIOT_CORE_ENABLE_CREDENTIALS=ON
make
export AWS_IOT_CORE_CREDENTIAL_ENDPOINT=xxxxx.credentials.iot.xxxxx.amazonaws.com
export AWS_IOT_CORE_PRIVATE_KEY=xxxxxxxx-private.pem.key
export AWS_IOT_CORE_ROLE_ALIAS=xxxxxx
export AWS_IOT_CORE_THING_NAME=xxxxxx
export AWS_IOT_CORE_CERT=xxxxx-certificate.pem.crt

• 预生成证书（降低嵌入式设备握手耗时）：在 Samples.h 引入 RtcCertificate certificates[]，在 Common.c 的 initializePeerConnection() 给 configuration.certificates[...] 赋值，避免运行时调用 createCertificateAndKey()。

• mbedTLS 硬件熵源：

  • 取消注释 configs/config_mbedtls.h 中 MBEDTLS_ENTROPY_HARDWARE_ALT
  • 实现硬件熵源函数（参考 mbedTLS 文档）并参与链接

调试定位与排障

• 打印 SDP：export DEBUG_LOG_SDP=TRUE
• 文件日志：export AWS_ENABLE_FILE_LOGGING=TRUE（默认生成 build/kvsFileLogFilter.x）
• Clang 格式检查：
  • scripts/check-clang.sh（检测）
  • scripts/clang-format.sh（修复）

gperftools 性能分析

cmake .. -DLINK_PROFILER=ON
HEAPPROFILE=/tmp/heap.prof /path/to/app     # 堆分析
CPUPROFILE=/tmp/cpu.prof /path/to/app       # CPU 分析

过滤网络接口

在 Common.c 提供示例回调；设置：

configuration.kvsRtcConfiguration.iceSetInterfaceFilterFunc = sampleFilterNetworkInterfaces;

减少无效接口的候选收集时间。

网络端口与连通性

• *.kinesisvideo.<region>.amazonaws.com 端口 443
• KVS endpoint：TCP 443
• HTTPS channel endpoint：TCP 443
• WSS channel endpoint：TCP 443
• STUN endpoint：UDP 443
• TURN endpoint：UDP/TCP 443

确保出站访问上述端点与端口。

常见问题与建议

• GStreamer 的 MatroskaMux 不支持 caps changes，若接收端媒体格式动态变化，需替换为能处理动态格式的管线组件。
• 若路径太长导致 Windows 构建失败：启用 git config --system core.longpaths true，或将仓库搬到 C:/ 根目录并缩短路径。
• 构建清理：cmake --build . --target clean（在 build/ 目录执行）。

目录结构速览（选取关键）

root
├── CMake/                    # 构建工具与依赖下载脚本
├── samples/                  # Master/Viewer 样例、GStreamer 案例
├── src/
│   ├── include/com/...       # 公共 API 头文件（Include.h）
│   └── source/
│       ├── Signaling/        # 信令客户端
│       ├── PeerConnection/   # SDP/DTLS/SRTP/SCTP/Transceiver
│       ├── Ice/              # ICE Agent
│       ├── Rtp/ Rtcp/ Srtp/  # 媒体与控制、加密
│       ├── Sdp/              # SDP 处理
│       ├── Stun/ Turn/       # NAT 穿越
│       ├── Sctp/             # 数据通道
│       ├── Metrics/          # 统计导出
│       └── Threadpool/       # 线程池实现
└── tst/                      # 单元/集成测试（GTest）

参考与扩展

• 公共 API 文档：src/include/com/amazonaws/kinesis/video/webrtcclient/Include.h
• 在线 Doxygen 文档：https://awslabs.github.io/amazon-kinesis-video-streams-webrtc-sdk-c/
• WebRTC 统计与 KVS 文档：https://docs.aws.amazon.com/kinesisvideostreams-webrtc-dg/latest/devguide/kvswebrtc-reference.html
• TWCC 规范：https://datatracker.ietf.org/doc/html/draft-holmer-rmcat-transport-wide-cc-extensions-01
• 相关 SDK：
  • JS：https://github.com/awslabs/amazon-kinesis-video-streams-webrtc-sdk-js/
  • iOS：https://github.com/awslabs/amazon-kinesis-video-streams-webrtc-sdk-ios/
  • Android：https://github.com/awslabs/amazon-kinesis-video-streams-webrtc-sdk-android/

附录：常用环境变量表

• AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_SESSION_TOKEN
• AWS_DEFAULT_REGION
• AWS_KVS_LOG_LEVEL / AWS_ENABLE_FILE_LOGGING
• AWS_KVS_CACERT_PATH
• AWS_KVS_WEBRTC_THREADPOOL_MIN_THREADS / AWS_KVS_WEBRTC_THREADPOOL_MAX_THREADS

---

本指南旨在让你“从构建到运行”迅速掌握 KVS WebRTC C SDK 的关键路径，同时在需要深入优化与排障时提供明确抓手。若要在嵌入式或受限网络环境部署，建议优先启用：预生成证书、线程池优化、接口过滤、合理的滚动缓冲容量与 TWCC 回调，以获得更稳定的连接与体验。