Windows 实时音视频应用的媒体输入通常来自两个方向:一类是本机摄像头、麦克风、桌面或业务窗口;另一类是已经部署的 IPC、NVR、编码器及 RTSP/RTMP 流媒体服务。

当业务需要将这些媒体统一接入 WebRTC 平台,或希望在浏览器端实现实时观看、远程巡检和现场视频回传时,除了媒体采集与编码能力,还需要一套稳定、易集成、可管理的媒体发布链路。

大牛直播 SDK(SmartMediaKit)Windows 平台新增 WHIP 推流能力,提供两种典型接入方式:

  • 本地采集直接发布:摄像头、麦克风、桌面或业务窗口采集后,通过 WHIP 发布到媒体服务。
  • 网络流拉取转推:拉取已有 RTSP/RTMP 流,将编码音视频数据送入 Publisher,再通过 WHIP 发布。

两种方式共用 Publisher 的会话管理与 WHIP 配置能力。对于符合目标媒体格式要求的网络流,还可以复用已有编码视频数据,避免不必要的重复解码和编码。

本文以  WIN-PublisherSDK-CPP-Demo 和 WIN-RelaySDK-CPP-Demo 为基础,面向 Windows C++ 开发者,介绍工程接入、公开接口、调用流程、媒体兼容、状态管理及多路部署建议。

本文聚焦 SDK 公开接口与工程集成方式,不涉及 WHIP 信令、媒体传输及底层处理模块的内部实现。接口参数和完整约定请以当前发布包中的 SDK 头文件为准。


1. 能力定位与接入架构

大牛直播SDK(SmartMediaKit)Windows平台WHIP推流SDK、多路RTSP/RTMP转WHIP推流集成说明_windows推送whip

1.1 WHIP 在媒体系统中的作用

WHIP(WebRTC-HTTP Ingestion Protocol)是一种基于 HTTP 的 WebRTC 媒体接入协议,已发布为 IETF RFC 9725。发布端通过 HTTP 信令与媒体服务建立会话,随后通过 WebRTC 媒体链路持续发送音视频。

对于 Windows 应用而言,WHIP 解决的是媒体如何发布到支持 WHIP 的服务端。它并不直接定义观看端的播放方式。浏览器播放、二次分发或其他协议输出,应由媒体服务提供相应的 WHEP、WebRTC 或其他分发能力。

SmartMediaKit 将 WHIP 发布能力封装在 Windows Publisher SDK 中。业务侧主要完成媒体源选择、编码参数配置、WHIP 接入信息设置、会话启停和状态处理,无需自行实现完整的 WHIP 会话及媒体发送流程。

协议参考:IETF RFC 9725 - WebRTC-HTTP Ingestion Protocol (WHIP)。

1.2 本机采集:直接发布 WHIP

适用于桌面客户端、行业终端、工控机和现场作业应用。

该方式沿用 Publisher 已有的采集和编码配置,适合摄像头直播、桌面共享、业务窗口回传,以及摄像头与桌面组合输出等场景。

1.3 网络流输入:多路 RTSP/RTMP 转 WHIP

适用于已经部署摄像头、NVR、编码器或 RTSP/RTMP 流媒体服务的项目。

Relay 工程通过拉流端回调获取编码音视频,再投递给对应 Publisher。对于编码格式、参数及目标服务均兼容的视频,可以复用已有编码数据,减少重复编解码开销。

当前 C++ Relay Demo 展示四路独立转推。每一路分别维护输入地址、WHIP Endpoint、Publisher、配置和运行状态。四路是 Demo 的示例规模,不代表 SDK 的固定路数上限;实际并发能力需要结合设备性能、输入码率、音频处理、网络带宽、授权及是否开启预览进行评估。

1.4 两种接入方式如何选择

业务输入

推荐工程

SDK 组成

典型用途

摄像头、麦克风、桌面、窗口

WIN-PublisherSDK-CPP-Demo

SmartPublisherSDK

本机采集、桌面回传、现场直播

RTSP 摄像头、NVR、RTMP 流

WIN-RelaySDK-CPP-Demo

SmartPlayerSDK + SmartPublisherSDK

存量视频接入、多路转推、边缘汇聚

两种路径的差别主要在媒体输入侧:本地采集由 Publisher 完成采集和编码;网络流转推由 Player 拉取媒体,再通过 Publisher 完成发布。WHIP 接入配置和会话状态管理可以采用统一的业务管理方式。


2. Demo 工程与集成准备

大牛直播SDK(SmartMediaKit)Windows平台WHIP推流SDK、多路RTSP/RTMP转WHIP推流集成说明_whip推流_02

2.1 工程说明

工程

功能

主要 SDK

WIN-PublisherSDK-CPP-Demo

本机采集、编码并发布 WHIP

SmartPublisherSDK

WIN-RelaySDK-CPP-Demo

拉取 RTSP/RTMP 编码数据并转推 WHIP

SmartPlayerSDK、SmartPublisherSDK

两个 Demo 均为 Windows C++/MFC 工程,提供 Win32 与 x64 配置。工程文件使用 v120 工具集;使用其他 Visual Studio 版本时,可根据项目环境安装对应工具集或重定向工程,并检查运行库配置。

采集方式对操作系统能力有不同要求。例如,DXGI 桌面采集与 WinRT 窗口采集的系统适用范围并不完全相同,实际集成时应根据所选采集方式确认目标 Windows 版本。

2.2 关键目录与文件

文件或目录

主要用途

SmartPublisherSDK/nt_smart_publisher_sdk.h

Publisher 函数表及 WHIP、Opus 相关接口声明

SmartPublisherSDK/nt_smart_publisher_define.h

Publisher 输入模式及 WHIP 事件定义

SmartPublisherSDK/nt_common_media_define.h

媒体类型与 Codec ID 定义

SmartPublisherDemo/SmartPublisherDemoDlg.cpp

本地采集 Demo 的参数配置、启停和事件处理

SmartPublisherDemo/nt_whip_demo.h/.cpp

Demo 层 WHIP 配置与事件辅助封装

SmartStreamRelayDemo/SmartStreamRelayDemoDlg.cpp

多路拉流、编码数据投递及 WHIP 控制

Relay 工程的 SmartSDK/include

拉流端、推流端及公共 SDK 头文件

nt_whip_demo 是 Demo 层的辅助封装,便于开发者理解配置顺序和事件处理方式。业务工程既可以参考该封装,也可以直接调用公开 SDK 接口,构建自己的 UI、控制台程序或 Windows 后台服务。

2.3 库文件与运行环境

  • 本地采集推流工程需要链接 SmartPublisherSDK.lib。
  • RTSP/RTMP 转 WHIP 工程还需要链接 SmartPlayerSDK.lib。
  • 运行时应部署与当前 SDK 版本、目标架构相匹配的 DLL 及配套依赖。
  • 本次发布包在相应运行库目录增加了 libNTStreamTransport.dll,升级项目时应同步更新,不能只替换主 SDK DLL。
  • 根据实际使用的功能,保留日志、窗口采集等对应模块及依赖。
  • 头文件、导入库和 DLL 的位数必须一致;Debug、Release 配置应使用发布包中相应版本的文件。
  • HTTPS 使用的 PEM 格式 CA 证书包应放在应用可读取的位置,并通过绝对路径配置。

升级注意: 从旧版本升级时,应将头文件、.lib、SDK DLL 和新增运行时依赖作为一个版本整体更新,避免新旧文件混用导致接口解析或运行时加载异常。


3. 本次版本新增接口与兼容说明

大牛直播SDK(SmartMediaKit)Windows平台WHIP推流SDK、多路RTSP/RTMP转WHIP推流集成说明_whip服务器_03

3.1 新增能力概览

相较于 2026-10-21 版本,本次升级保留 Publisher 原有的基础调用方式,并补充 WHIP 发布所需的会话控制、接入配置、音频适配和传输参数。

能力方向

新增或扩展内容

集成价值

WHIP 会话

Endpoint 配置、启动与停止

将本机采集和已有网络流接入 WHIP 服务

接入鉴权

Bearer Token 配置

对接需要令牌鉴权的发布入口

HTTPS

CA 证书包、证书可信性与主机名校验

适配正式部署中的 HTTPS 证书环境

HTTP 超时

连接超时、单次请求总超时分别配置

为 HTTP 信令阶段设置明确的等待边界

视频传输

RTP NACK 重传响应、Pacing 发送节奏控制

为丢包恢复和发送节奏提供配置能力

外部编码视频

Pacing 参考平均码率

适配摄像头、编码器等外部编码源

音频编码

Opus 编码类型及应用类型配置

满足实时音频发布的编码选择需求

音频适配

G.711 PCMA/PCMU 转 Opus 开关

适配常见监控设备音频输入

状态回调

新增八个 WHIP 事件

区分 HTTP 信令阶段与媒体通道状态

本次公开头文件新增 14 个函数声明:其中 13 个用于 WHIP 参数配置及会话启停,另 1 个用于设置 Opus 编码器应用类型。此外,原有 SetPublisherAudioCodecType 扩展了 Opus 编码类型 5,公共错误码增加 NT_ERC_TIMEOUT。

3.2 新旧接口调用方式的区别

需要特别注意,本次新增 WHIP 接口与原有 Publisher 函数表接口的调用形式不同:

接口类型

调用方式

代表接口

原有 Publisher 函数表接口

通过 NT_GetSmartPublisherSDKAPI 获取函数表后调用

Init、Open、Close、SetPublisherAudioCodecType

新增 WHIP 独立导出接口

直接调用 NT_PB_ 前缀的 C 函数

NT_PB_SetWhipEndpointURL、NT_PB_StartWhipStream

两类接口使用同一个 Publisher 句柄。因此,已有 Publisher 工程不需要为了 WHIP 另行建立一套完全独立的媒体实例管理体系;在原有初始化、创建和释放流程中,增加 WHIP 配置及启停调用即可。

3.3 集成时需要关注的兼容点

  1. 确认使用的是包含本次 WHIP 声明的 nt_smart_publisher_sdk.h。
  2. 新增 NT_PB_ 接口需要与当前版本 SDK DLL、导入库及运行时依赖配套使用。
  3. SetPublisherAudioCodecType 的 5 表示 Opus;原有 AAC、Speex 类型值保持原有定义。
  4. 新增 NT_ERC_TIMEOUT 后,业务层应将超时与普通配置错误、连接失败等状态区分处理。
  5. 不要仅凭 WHIP 启动接口返回成功就判断发布已经建立,实际连接结果应以 WHIP 事件为准。

4. 本地采集直接 WHIP 推流

大牛直播SDK(SmartMediaKit)Windows平台WHIP推流SDK、多路RTSP/RTMP转WHIP推流集成说明_whip服务器_04

4.1 初始化与媒体源配置

本地采集推流沿用 Publisher 原有生命周期。推荐按以下顺序集成:

  1. 调用 NT_GetSmartPublisherSDKAPI 获取 Publisher 函数表,并检查返回结果。
  2. 调用 publisher_api.Init(0, NULL) 初始化 SDK。
  3. 根据实际输入方式调用 Open,创建 Publisher 实例。
  4. 注册事件回调,配置摄像头、麦克风、桌面或业务窗口等媒体源。
  5. 配置视频编码、音频编码及相关媒体参数。
  6. 设置 WHIP Endpoint、鉴权、HTTPS 和传输参数。
  7. 调用 WHIP 启动接口,并通过事件回调跟踪连接状态。

采集源、视频编码及大部分媒体参数仍使用原有 Publisher 接口配置。对于浏览器实时观看场景,建议先使用媒体服务和观看端均明确支持的编码组合完成互通验证,再根据项目需求调整分辨率、帧率、GOP、码率及软硬件编码方式。

WebRTC 基础视频、音频编解码器要求可分别参考 RFC 7742 和 RFC 7874。

4.2 配置 Opus 音频

当音频由 SDK 编码,并且目标链路采用 Opus 时,可在启动媒体任务前设置音频编码类型及 Opus 应用类型:

// publisher_api:通过 NT_GetSmartPublisherSDKAPI 获取的函数表
// handle:已经创建且有效的 Publisher 句柄NT_UINT32 ret = publisher_api.SetPublisherAudioCodecType(handle, 5);
if (ret != NT_ERC_OK)return ret;// 2049:Audio;2048:VoIP
ret = NT_PB_SetOpusEncoderApplicationType(handle, 2049);
if (ret != NT_ERC_OK)return ret;

参数说明:

参数值

含义

适用方向

5

Opus 编码类型

选择 Opus 音频编码

2049

Audio 模式

通用音频场景,SDK 默认值

2048

VoIP 模式

以实时语音为主的场景

Opus 应用类型用于选择相应的编码器工作模式。外部编码音频则应根据实际 Codec 和目标媒体服务要求选择对应的数据输入及适配路径。

Demo 中预览、推流和录像可能共享 Publisher 的音频配置。若多个媒体任务同时运行,应在任务启动前统一确定音频编码策略,避免运行期间修改共享配置影响其他任务。

4.3 配置并启动 WHIP

下面示例展示 WHIP 发布的主要配置步骤。调用前应完成 SDK 初始化、Publisher 创建、事件回调注册及媒体参数配置。

NT_UINT32 ConfigureAndStartWhip(NT_HANDLE handle,NT_PCSTR endpoint,NT_PCSTR token,NT_PCSTR ca_bundle_path)
{NT_UINT32 ret = NT_PB_SetWhipEndpointURL(handle, endpoint);if (ret != NT_ERC_OK)return ret;ret = NT_PB_SetWhipBearerToken(handle, token);if (ret != NT_ERC_OK)return ret;ret = NT_PB_SetWhipHttpCaBundlePath(handle, ca_bundle_path);if (ret != NT_ERC_OK)return ret;// 生产环境建议开启证书可信性及主机名校验ret = NT_PB_SetWhipHttpSslVerifyPeer(handle, 1);if (ret != NT_ERC_OK)return ret;ret = NT_PB_SetWhipHttpSslVerifyHost(handle, 1);if (ret != NT_ERC_OK)return ret;// HTTP 信令超时,可根据部署网络调整ret = NT_PB_SetWhipHttpConnectTimeoutMs(handle, 8000);if (ret != NT_ERC_OK)return ret;ret = NT_PB_SetWhipHttpTimeoutMs(handle, 10000);if (ret != NT_ERC_OK)return ret;// 保留参数按接口约定传 0return NT_PB_StartWhipStream(handle, 0);
}

调用注意事项:

  • endpoint 应填写服务端实际提供的完整 HTTP/HTTPS WHIP 接入地址,例如 https://media.example.com/live/camera01/whip。
  • Endpoint 的路径、端口和鉴权规则由服务端决定。Demo 中的本机地址仅用于本地联调,部署时必须替换为实际可达地址。
  • token 不需要鉴权时传空字符串;需要鉴权时传 UTF-8 Token,不要添加 Bearer 前缀。
  • ca_bundle_path 应传 PEM 格式 CA 包的 UTF-8 绝对路径;不使用自定义证书包时按接口约定传空字符串。相关字符串参数不要传 NULL。
  • NT_PB_StartWhipStream(handle, 0) 的保留参数必须传 0。
  • 启动接口返回 NT_ERC_OK 表示本次接口调用成功,不等同于媒体通道已经连接。实际状态应继续观察 WHIP 事件。

4.4 停止发布与释放资源

停止 WHIP 发布调用:

NT_PB_StopWhipStream(handle);

Windows C++ 版本的该接口只需要传入 Publisher 句柄。

停止某一路 WHIP 输出后,不应立即无条件关闭 Publisher。若同一个 Publisher 仍被预览、录像或其他输出任务使用,应先判断其他任务的运行状态。只有在相关任务全部停止、外部数据投递及回调访问得到妥善处理后,才调用原有 Close 释放句柄;所有实例释放后,再调用进程级 UnInit。


5. 多路 RTSP/RTMP 转 WHIP 推流

大牛直播SDK(SmartMediaKit)Windows平台WHIP推流SDK、多路RTSP/RTMP转WHIP推流集成说明_windows whip推流_05

5.1 单路转推的数据流程

WIN-RelaySDK-CPP-Demo 同时使用 SmartPlayerSDK 和 SmartPublisherSDK。Player 负责拉取 RTSP/RTMP 流并通过回调输出编码数据;Publisher 以编码数据输入模式接收媒体,再通过 WHIP 发布。

阶段

主要接口或配置

作用

创建拉流实例

Player Open、SetURL

创建输入会话并设置源地址

注册媒体回调

SetPullStreamVideoDataCallBack、SetPullStreamAudioDataCallBack

获取编码音视频及描述信息

启动拉流

StartPullStream

启动 RTSP/RTMP 输入

创建推流实例

Publisher Open

以编码数据输入模式创建 Publisher

投递视频

PostVideoEncodedDataV2

投递编码视频、关键帧标记及时间戳

投递音频

PostAudioEncodedData

投递编码音频及对应参数信息

WHIP 发布

NT_PB_SetWhip...、NT_PB_StartWhipStream

配置并启动目标发布会话

Publisher 的输入模式对应:

  • NT_PB_E_VIDEO_OPTION_ENCODED_DATA
  • NT_PB_E_AUDIO_OPTION_ENCODED_DATA

从 Player 回调向 Publisher 投递数据时,应保持媒体数据与描述信息一致,尤其要关注 Codec ID、关键帧标记、时间戳及音频参数。不要在业务层随意改写编码类型或媒体描述后直接投递原始编码数据。

5.2 建议的首次联调顺序

建议先完成单路,再逐步增加并发路数:

  1. 初始化 SmartPlayerSDK 和 SmartPublisherSDK,准备本路控制对象。
  2. 设置一路 RTSP/RTMP 源地址并启动拉流。
  3. 确认拉流成功,且视频、音频回调持续收到有效数据。
  4. 根据源音频格式和目标媒体服务能力,确定音频处理策略。
  5. 设置本路 WHIP Endpoint、Token、证书、超时及传输参数。
  6. 使用外部编码视频时,如启用 Pacing,应配置有效的参考平均码率。
  7. 启动本路 WHIP,分别观察 HTTP 信令和媒体通道事件。
  8. 在服务端及实际观看端确认音视频正常,再增加其他路输入。

Demo 中 WHIP 启动操作要求先启动本路拉流。实际业务中也应将以下状态分开管理:

  • 正在拉流;
  • 已收到有效媒体数据;
  • WHIP 正在建立连接;
  • WHIP 媒体通道已连接;
  • WHIP 已断开或关闭。

这样可以避免将“上游拉流成功”误判为“下游 WHIP 发布成功”。

5.3 多路实例管理

多路转推建议将每一路封装为独立业务对象,至少维护以下信息:

管理项

内容

路编号

唯一标识,便于日志、状态和界面关联

输入配置

RTSP/RTMP 地址及拉流参数

输出配置

WHIP Endpoint、Token 和证书配置

媒体策略

视频编码复用策略、音频适配策略

传输参数

NACK、Pacing、参考码率和超时

运行状态

拉流状态、媒体数据状态、WHIP 状态

生命周期

启动、停止、异常恢复及资源释放

这种管理方式便于单独启停某一路、更新单路配置和执行故障恢复,避免某一路异常影响其他正常任务。

Relay Demo 还保留原有 RTMP 推送与轻量级 RTSP 服务入口。需要组合输出时,可以沿用已有拉流和编码数据投递链路,统一管理 Publisher 的使用状态。停止某个输出任务时,应确认同一 Publisher 是否仍被其他任务使用。

需要注意,同一个 Publisher 的媒体输入及部分编码设置属于共享资源。如果不同输出目标需要不同的音频编码或媒体处理策略,应按目标规划独立实例及相应适配路径。


6. 媒体兼容与音频适配

大牛直播SDK(SmartMediaKit)Windows平台WHIP推流SDK、多路RTSP/RTMP转WHIP推流集成说明_whip推流_06

6.1 视频编码数据复用的适用条件

多路转推的一个重要优势,是在输入编码与目标接收能力匹配时,可以直接复用源端视频编码数据,减少重复解码、编码带来的 CPU/GPU 开销和额外处理延迟。

但编码数据复用并不意味着任意视频流都能直接发布。集成时应重点确认:

  • 视频 Codec 是否为目标媒体服务及观看端支持的格式;
  • Profile、分辨率、帧率和编码参数是否满足目标要求;
  • 关键帧间隔是否适合实时观看及连接后的画面恢复;
  • 时间戳是否连续、有效;
  • 源端码率和网络上行能力是否匹配。

当输入视频与目标不兼容时,可以优先调整摄像头或编码器配置;如果业务要求改变编码格式、分辨率或叠加内容,则需要规划相应的视频处理链路。

H.265 等格式必须结合目标媒体服务和最终观看端进行端到端验证。 SDK 具备外部编码数据输入能力,并不代表所有媒体服务和浏览器环境都支持任意编码格式。

6.2 音频输入与处理策略

不同监控设备和流媒体源的音频编码并不统一。WHIP 转推时,应根据输入格式和目标服务支持情况选择处理方式。

音频输入

建议策略

本机麦克风、外部 PCM

由 SDK 编码时,选择目标支持的音频格式;使用 Opus 时设置编码类型 5

G.711 PCMA/PCMU

目标支持时可保留原编码;需要 Opus 时启用 G.711 转 Opus

外部已编码 Opus

按编码音频输入方式接入,确认媒体描述与目标协商要求一致

AAC 或其他编码音频

单独确认目标服务和观看端的接收能力,必要时规划音频适配

G.711 转 Opus 通过以下接口配置:

NT_PB_SetWhipG711ToOpus(handle, 1);

该接口默认值为 0:

  • 0:保持 G.711 编码;
  • 1:将 PCMA/PCMU 转换为 Opus。

这项能力适合视频编码可以直接复用、但监控设备音频需要适配的场景。它针对 PCMA/PCMU,不应理解为可以自动处理所有音频编码格式。

Relay Demo 原有的“拉流音频转 AAC”选项服务于相应 AAC 输出需求。转推 WHIP 时,应根据目标服务能力决定是否开启。如果使用 G.711 转 Opus 路径,应确保 WHIP 侧接收到的是对应的 G.711 输入数据;AAC 输入则需要单独确认处理方案。


7. WHIP 传输配置与延迟优化

大牛直播SDK(SmartMediaKit)Windows平台WHIP推流SDK、多路RTSP/RTMP转WHIP推流集成说明_windows推送whip_07

7.1 RTP NACK 重传响应

NT_PB_SetWhipRtpNackEnabled(handle, 1);

该接口用于开启视频 RTP NACK 丢包重传响应,SDK 默认开启。

接收端反馈丢包后,发送侧可根据反馈对相应视频数据进行恢复处理。实际效果取决于网络往返时延、可用上行带宽、丢包情况及接收端处理能力。对于一般网络环境,建议先保留默认配置,再结合目标网络观察播放连续性和延迟表现。

NACK 有助于改善部分网络丢包情况下的视频连续性,但不能替代稳定的网络链路,也不能保证所有丢包都能恢复。

7.2 RTP Pacing 与参考码率

NT_PB_SetWhipRtpPacingEnabled(handle, 1);

该接口用于开启视频 RTP 平滑发送,SDK 默认开启。对于关键帧较大、瞬时发送数据量较高的输入,Pacing 可帮助控制发送节奏,减少集中发送造成的网络突发。

对于外部编码视频,Pacing 需要合理的参考平均码率:

视频来源

参考码率来源

SDK 自身采集并编码

使用 Windows 视频编码码率配置

RTSP/RTMP 转推或外部编码视频

调用 NT_PB_SetWhipEncodedVideoKbitrate 设置

例如,源端视频平均码率约为 6 Mbps,可在启动前设置:

NT_PB_SetWhipEncodedVideoKbitrate(handle, 6000);

单位为 kbps,参数为非负值;0 表示不提供参考码率。

该接口设置的是发送节奏参考,不会重新编码视频,也不会将输入视频压缩到指定码率。 应根据源端实际平均编码码率设置。如果参考值长期明显低于输入码率,可能造成发送积压;当输入码率发生较大变化时,应重新评估该参数。

7.3 从端到端链路优化延迟

实时视频延迟不是由 WHIP 单一环节决定的。完整链路通常包括采集、编码、源端 GOP、拉流缓冲、转推处理、网络传输以及接收端缓冲和播放。

建议从以下方面进行评估:

  1. 采集与编码:根据画质要求设置分辨率、帧率、GOP 和码率,评估硬件编码能力。
  2. 输入拉流:转推场景优先复用兼容的视频编码数据,并结合源端稳定性配置拉流缓冲。
  3. 音频适配:只对确实需要转换的音频格式启用适配,避免引入不必要的处理环节。
  4. 发送节奏:合理设置 Pacing 参考码率,并持续观察输入码率与输出状态。
  5. 多路资源分配:按需开启预览,区分转推与解码显示带来的额外资源消耗。
  6. 接收端验证:同时观察服务端接收状态和最终观看端表现,不以发送端单侧状态代替端到端测试。

Relay Demo 使用 SetBuffer(0) 和快速启动配置,侧重减少实时转推链路中的额外缓存。实际部署仍应结合源端稳定性、网络抖动和目标延迟要求进行验证。


8. WHIP 事件回调与异常定位

大牛直播SDK(SmartMediaKit)Windows平台WHIP推流SDK、多路RTSP/RTMP转WHIP推流集成说明_whip推流_08

8.1 注册与理解 WHIP 事件

WHIP 事件通过 Publisher 原有事件回调机制返回,使用 SetEventCallBack 注册。本次新增八个事件:

事件

含义

NT_PB_E_EVENT_ID_WHIP_HTTP_POST_SENDING

正在发送 HTTP POST 请求

NT_PB_E_EVENT_ID_WHIP_HTTP_POST_SUCCESS

HTTP POST 请求成功

NT_PB_E_EVENT_ID_WHIP_HTTP_POST_FAILED

HTTP POST 请求失败

NT_PB_E_EVENT_ID_WHIP_CHANNEL_CONNECTING

媒体通道连接中

NT_PB_E_EVENT_ID_WHIP_CHANNEL_CONNECTED

媒体通道已连接

NT_PB_E_EVENT_ID_WHIP_CHANNEL_CONNECT_FAILED

媒体通道连接失败

NT_PB_E_EVENT_ID_WHIP_CHANNEL_DISCONNECTED

媒体通道断开

NT_PB_E_EVENT_ID_WHIP_CHANNEL_CLOSED

媒体通道关闭

建议将 WHIP 状态按两个层次理解:

  • HTTP 信令状态:请求是否发出、是否成功、是否失败;
  • 媒体通道状态:媒体连接是否建立、是否断开、是否关闭。

HTTP POST 成功不等于媒体通道已经建立。媒体通道连接后,还需要通过服务端接收情况和最终观看效果确认音视频持续可用。

8.2 回调处理建议

Demo 将 SDK 事件投递到窗口消息,再由界面线程更新状态。实际业务也可以使用自己的消息队列或任务调度机制,将状态处理集中到管理线程。

建议遵循以下原则:

  • 回调中只做必要的状态采集和事件投递,避免执行耗时操作。
  • 每一路维护独立状态,不要用一个全局布尔值代表所有 WHIP 会话。
  • 日志至少包含路编号、事件类型、返回值、时间和目标标识。
  • 对 Endpoint 中的敏感信息及 Token 做脱敏处理。
  • 对断开和连接失败设置单路恢复策略,避免多个控制入口重复启动同一会话。

8.3 常见问题定位

现象

优先检查项

SDK DLL 加载或新增接口解析失败

DLL 位数、导入库版本、运行库及配套依赖,尤其检查 libNTStreamTransport.dll

配置接口立即返回错误

Publisher 句柄是否有效、参数范围是否正确、字符串是否符合接口约定

HTTP POST 失败

Endpoint、Token、DNS、证书、HTTP 超时及服务端日志

HTTP 成功但媒体通道连接失败

服务端公布的媒体地址、媒体端口、防火墙、NAT 和网络可达性

通道已连接但没有画面

上游是否持续输出、Codec 与参数是否匹配、关键帧及时间戳是否正常

有画面但没有声音

源音频格式、音频回调参数、G.711 转 Opus 配置及目标音频支持情况

长时间运行后延迟增加

输入与上行带宽、参考码率、发送积压、源端抖动及接收端缓冲

停止某一路后其他输出异常

是否提前关闭了仍被其他任务使用的 Publisher 或数据输入

特别注意:WHIP 的 HTTP/HTTPS 接口可访问,不代表 WebRTC 媒体通道所需的网络地址和端口也已经连通。若 HTTP 请求成功但媒体通道连接失败,应继续检查媒体服务的网络公布地址、端口映射、防火墙和 NAT 配置。


9. 部署验证与多路运行建议

大牛直播SDK(SmartMediaKit)Windows平台WHIP推流SDK、多路RTSP/RTMP转WHIP推流集成说明_whip服务器_09

9.1 HTTPS 证书与超时配置

生产环境建议配置可信 CA,并显式开启证书可信性与主机名校验:

NT_PB_SetWhipHttpSslVerifyPeer(handle, 1);
NT_PB_SetWhipHttpSslVerifyHost(handle, 1);

需要注意:

  • SDK 头文件约定证书可信性校验和主机名校验默认均为开启。
  • 当前 Demo 的配置项初始化值中,证书可信性校验默认开启,主机名校验默认关闭;Demo 会显式应用界面配置。
  • 因此,生产工程不要依赖 Demo 界面默认值,应根据实际证书环境明确设置两项参数。正式部署建议均开启。
  • CA 路径应指向 PEM 格式证书包的 UTF-8 绝对路径。
  • Demo 将 CA 路径初始化为 EXE 同目录下的 cacert.pem。部署时需提供该文件,或通过配置指定其他可信 CA 包。
  • 使用 IP 地址访问 HTTPS 时,应确认服务端证书包含对应 IP,避免主机名校验失败。

Demo 中 HTTP 连接超时为 8000 毫秒,单次请求总超时为 10000 毫秒,可作为联调起点。这两个参数约束 HTTP 信令请求;媒体通道建立及运行状态应通过对应事件管理。

9.2 多路容量评估

Demo 展示四路独立转推,实际项目应使用接近现场的分辨率、帧率、平均码率和音频组合进行压力测试。建议分别测试纯转推、开启预览及组合输出等运行模式。

评估维度

重点关注

网络带宽

多路输入与输出总量、关键帧突发、重传开销及带宽余量

CPU / GPU

编码、音频转换、解码预览及合成处理开销

内存

长期运行、反复启停、断流恢复过程中的占用趋势

连接恢复

上游中断、服务端重启和网络切换后的单路恢复行为

资源释放

停止任务、终止外部投递、释放句柄和清理待处理事件

对于无人值守的边缘节点,建议在业务控制层增加启动间隔、重试退避、状态上报和日志轮转。批量恢复时可错开重试时间,避免多个会话同时发起连接。

9.3 推荐联调检查清单

  • SDK 头文件、导入库、DLL 和运行时依赖来自同一发布版本。
  • Win32/x64 与 DLL、.lib 位数一致。
  • 单路 RTSP/RTMP 输入能够稳定拉流并持续收到编码数据。
  • 单路 WHIP Endpoint、Token 和 HTTPS 证书配置正确。
  • HTTP 信令成功后,媒体通道能够建立。
  • 视频 Codec、关键帧、时间戳及音频格式满足目标服务要求。
  • 服务端和最终观看端均能正常接收音视频。
  • 单路停止和重启不会影响其他仍在运行的输出。
  • 多路压力、长时间运行及异常恢复均完成验证。

10. 技术优势与典型应用场景

大牛直播SDK(SmartMediaKit)Windows平台WHIP推流SDK、多路RTSP/RTMP转WHIP推流集成说明_windows推送whip_10

10.1 面向实际项目的工程优势

一套 SDK 覆盖本地采集与既有网络流接入。

Windows 应用既可以直接采集摄像头、麦克风、桌面和窗口,也可以通过 Player 拉取 RTSP/RTMP 源,再交给 Publisher 发布。两条路径覆盖了新建终端和存量视频系统接入两类常见需求。

兼容时优先复用视频编码,降低重复处理成本。

对于编码格式和参数匹配的网络视频,可以复用源端编码数据;对于常见 G.711 音频,则提供按需转 Opus 的适配能力。视频与音频可以根据实际兼容情况分别处理,避免为了适配音频而不必要地重复处理视频。

接入配置覆盖实际部署需要。

Endpoint、Bearer Token、CA 证书、TLS 校验、HTTP 超时、NACK、Pacing 和参考码率等配置,使应用可以适配不同的媒体服务、证书环境和网络条件。

状态反馈区分信令与媒体通道。

通过新增 WHIP 事件,业务可以分别判断 HTTP 请求和媒体连接状态,进而建立单路监控、故障定位和恢复机制,而不是只依赖一个启动返回值判断发布是否成功。

能够融入已有媒体业务体系。

WHIP 与 Publisher 原有采集、编码及资源管理方式衔接;在 Relay 场景下,又能与 RTSP/RTMP 拉流、编码数据投递及已有输出能力组合使用,减少业务系统重复建设媒体接入层的工作。

10.2 典型应用场景

场景

接入方式

应用价值

园区、工厂视频汇聚

Windows 边缘节点拉取多路 IPC/NVR 流并转 WHIP

将存量监控视频接入支持 WebRTC 的实时媒体平台

远程巡检与应急指挥

现场摄像头或既有视频流发布 WHIP

为远程业务平台提供实时视频输入

工控机与业务窗口回传

采集指定窗口或桌面并发布

将操作界面、设备状态和现场画面同步到远端

智慧教室与会议系统

摄像头、麦克风和桌面采集

支持实时课堂、会议及远程协作

存量 RTMP 系统扩展

拉取已有 RTMP 源并转 WHIP

在保留既有 RTMP 输入体系的同时接入 WebRTC 服务

无人值守边缘转发

多路独立管理、状态监测和异常恢复

构建可持续运行的边缘视频接入节点

10.3 总结

WHIP 的价值不只是增加一种推流协议,更重要的是为 Windows 端已有的音视频采集能力和存量网络视频资源,提供一条标准化的 WebRTC 媒体接入路径。

SmartMediaKit 本次 Windows WHIP 能力同时覆盖本地采集发布和多路 RTSP/RTMP 转推,并围绕实际工程接入提供鉴权、HTTPS、音频适配、发送节奏控制和状态回调等能力。

对于开发者而言,可以根据媒体来源选择合适的 Demo 和接入路径,在复用现有 SDK 能力的基础上,将 WHIP 发布集成到自己的桌面应用、行业终端或边缘视频系统中。


附录 A:WHIP 公开接口速查

以下接口均作用于当前 Publisher 句柄。接口返回 NT_ERC_OK 表示本次接口调用成功;实际媒体连接状态仍应以事件回调为准。完整参数约定以配套 nt_smart_publisher_sdk.h 为准。

A.1 Endpoint、鉴权与 HTTPS

接口

参数要点

NT_PB_SetWhipEndpointURL

完整 HTTP/HTTPS Endpoint;启动前必须有效且非空,不能传 NULL

NT_PB_SetWhipBearerToken

UTF-8 Token,不含 Bearer 前缀;无需鉴权或清除令牌时传空字符串,不能传 NULL

NT_PB_SetWhipHttpCaBundlePath

PEM 格式 CA 包的 UTF-8 绝对路径;空字符串清除自定义路径,不能传 NULL

NT_PB_SetWhipHttpSslVerifyPeer

1 开启证书可信性校验,0 关闭;SDK 默认 1

NT_PB_SetWhipHttpSslVerifyHost

1 开启证书与主机名或 IP 匹配检查,0 关闭;SDK 默认 1

NT_PB_SetWhipHttpConnectTimeoutMs

单次 HTTP 请求的连接超时,单位毫秒,必须大于 0

NT_PB_SetWhipHttpTimeoutMs

单次 HTTP 请求的总超时,单位毫秒,必须大于 0

A.2 视频传输与音频适配

接口

参数要点

NT_PB_SetWhipRtpNackEnabled

视频 RTP NACK 重传响应;1 开启,SDK 默认开启

NT_PB_SetWhipRtpPacingEnabled

视频 RTP 平滑发送;1 开启,SDK 默认开启;外部编码视频应配置有效参考码率

NT_PB_SetWhipEncodedVideoKbitrate

外部编码视频参考平均码率,单位 kbps;0 表示不提供

NT_PB_SetWhipG711ToOpus

1 将 PCMA/PCMU 转 Opus,0 保留 G.711;默认 0

NT_PB_SetOpusEncoderApplicationType

2048 为 VoIP,2049 为 Audio;默认 2049

原有函数表接口 SetPublisherAudioCodecType 的音频编码类型:

类型值

编码

1

AAC

2

Speex

5

Opus

A.3 WHIP 会话启停

接口

调用方式

NT_PB_StartWhipStream

NT_PB_StartWhipStream(handle, 0)

NT_PB_StopWhipStream

NT_PB_StopWhipStream(handle)