大牛直播SDK（SmartMediaKit）Windows平台RTSP/RTMP直播播放SDK集成说明（C#版）

文档概述

本文介绍大牛直播SDK（SmartMediaKit）在 Windows 平台下 RTSP、RTMP 直播播放模块的集成方法，面向 Windows Forms、WPF 等 C# 客户端应用场景，重点说明 SDK 集成准备、播放器初始化、RTSP/RTMP 播放、播放参数配置、事件回调、下载速度与丢包率展示、截图、录像、窗口渲染、多路播放以及常见问题排查。

本文以 Windows C# Demo 为基础进行说明。Demo 采用NTPlayerWrapper + NTWrapperRenderWindow + NTRenderWindow的封装结构，将播放器生命周期、播放控制、录像控制、事件回调、渲染窗口和业务 UI 进行分层，便于开发者快速集成到企业级 Windows 客户端系统中。新版本 Demo 已在DOWNLOAD_SPEED事件处理中增加网络质量指标解析，通过param2获取丢包率并展示到状态栏，便于排查弱网、卡顿、RTSP UDP 丢包等现场问题。

产品概述

大牛直播SDK（SmartMediaKit）Windows 播放器 SDK 是面向专业级实时音视频场景设计的低延迟直播播放组件，适用于 RTSP 摄像头/NVR 预览、RTMP 直播拉流、工业视觉、安防监控、远程教育、应急指挥、无人机回传、低空经济等需要稳定、超低延迟（100~200ms）播放能力的 Windows 客户端系统。

Windows 播放模块基于SmartPlayerSDK.dll提供统一的播放器能力，支持 RTMP、RTSP 等常见直播协议，并提供低延迟播放、首屏秒开、软硬解切换、音视频控制、实时快照、播放端录像、事件回调、视频帧回调、下载速度回调、丢包率展示等能力。

其核心定位不是通用播放器外壳，而是面向系统集成场景的实时流媒体播放内核，适合嵌入到行业客户端、监控平台、调度系统、设备管理平台和实时音视频业务系统中。

适用场景

能力概览

开发环境

建议使用如下环境进行 Windows C# Demo 集成：

注意：C# 工程的平台架构必须与 SDK 动态库保持一致。例如使用 x64 版本 SDK 时，项目平台建议明确设置为 x64，不建议使用 Any CPU，避免运行时加载 DLL 失败。

SDK 文件结构

建议在项目中按以下方式组织 SDK 文件：

YourApp/ ├── bin/ │ └── x64/ │ └── Release/ │ ├── YourApp.exe │ ├── SmartPlayerSDK.dll │ ├── SmartLog.dll │ └── 其他依赖库 ├── SDK/ │ ├── smart_player_sdk.cs │ ├── smart_player_define.cs │ ├── nt_base_code_define.cs │ ├── smart_log.cs │ └── smart_log_define.cs └── Player/ ├── NTPlayerWrapper.cs ├── NTWrapperRenderWindow.cs ├── NTRenderWindow.cs └── VideoEffectProcessor.cs

其中：

推荐工程分层

为了降低业务层接入复杂度，建议采用如下分层结构：

业务层 Form / Page ↓ NTPlayerWrapper - SDK 初始化与销毁 - player handle 管理 - StartPlay / StopPlay - StartRecord / StopRecord - CaptureImage - 音量、静音、旋转、镜像、缩放 - 下载速度与丢包率状态处理 - SDK 事件统一转发 ↓ NTWrapperRenderWindow - 外层渲染控件 - 全屏切换 - 窗口大小变化 - 键盘 / 鼠标事件 ↓ NTRenderWindow - 实际渲染窗口 - D3D / GDI 绘制承载 - RGB32 帧绘制 - 清屏与重绘管理

这种设计方式具备以下优点：

集成流程

添加 SDK 依赖

在 C# 工程中添加以下接口文件：

smart_player_sdk.cs smart_player_define.cs nt_base_code_define.cs smart_log.cs smart_log_define.cs

并确保运行目录包含：

SmartPlayerSDK.dll SmartLog.dll 相关运行时依赖库

如果 SDK 包区分 Debug/Release、x86/x64，请确保当前工程配置与 DLL 版本一致。

初始化 SDK

推荐在应用启动阶段初始化 SDK，在应用退出阶段释放 SDK：

// 程序启动时调用一次 bool ok = NTPlayerWrapper.ForceInitSDK(); if (!ok) { MessageBox.Show("SmartPlayerSDK 初始化失败，请检查 DLL 是否完整。"); return; } // 程序退出时调用 NTPlayerWrapper.ForceUninitSDK();

在 Demo 封装中，NTPlayerWrapper已经实现引用计数管理。创建播放器实例时可以自动初始化 SDK，最后一个实例释放时自动反初始化。对于大型客户端系统，也可以在程序启动阶段显式调用ForceInitSDK()，在程序退出阶段调用ForceUninitSDK()。

创建播放器实例

private NTPlayerWrapper _player; private void InitPlayer() { _player = new NTPlayerWrapper(); // 将播放器渲染控件添加到界面容器 _player.RenderControl.Dock = DockStyle.Fill; panelPlayer.Controls.Add(_player.RenderControl); // 绑定事件 _player.SDKEvent += Player_SDKEvent; _player.VideoSizeChanged += Player_VideoSizeChanged; _player.CaptureImageCompleted += Player_CaptureImageCompleted; _player.RecordStatusChanged += Player_RecordStatusChanged; _player.UserDataReceived += Player_UserDataReceived; }

一个NTPlayerWrapper对应一路播放实例。多路播放时，每一路创建独立播放器实例，并绑定独立渲染窗口。

播放参数配置

建议通过PlayConfig统一管理播放参数：

PlayConfig config = new PlayConfig { // RTSP 参数 IsRtspTcpMode = false, IsRtspAutoSwitchTcpUdp = true, RtspTimeout = 10, // 播放体验 BufferTime = 0, IsFastStartup = true, IsLowLatencyMode = true, // 解码 UseHardwareDecoder = false, IsOnlyDecodeKeyFrame = false, // 音频 IsMute = false, AudioVolume = 100, // 渲染 IsRenderScaleMode = true, RotateDegrees = 0, IsFlipHorizontal = false, IsFlipVertical = false, // 下载速度与网络质量上报 EnableReportDownloadSpeed = true, ReportDownloadSpeedIntervalSeconds = 1 };

参数说明：

RTSP / RTMP 播放

开始播放

string url = textBoxUrl.Text.Trim(); bool ret = _player.StartPlay(url, config); if (!ret) { MessageBox.Show("播放失败，请检查播放地址、网络连接或 SDK 授权状态。"); return; }

典型 RTSP URL：

rtsp://user:password@192.168.1.100:554/stream1

典型 RTMP URL：

rtmp://192.168.1.100:1935/live/stream

推荐播放调用链：

NT_SP_Open → NT_SP_SetEventCallBack → NT_SP_SetVideoSizeCallBack → NT_SP_SetURL → 设置播放参数 → NT_SP_StartPlay

建议使用新接口NT_SP_StartPlay()/NT_SP_StopPlay()，不要与老接口NT_SP_Start()/NT_SP_Stop()混用。

停止播放

_player.StopPlay();

停止播放时建议同步处理 UI 状态：

btn_play.Text = "播放"; btn_capture_image.Enabled = false; btn_full_screen_.Enabled = false; lable_cur_status_txt.Text = ""; textBox_resolution.Text = "";

如果当前仍在录像，停止播放不应直接关闭底层 handle，避免影响正在进行的录像任务。Demo 中采用“播放和录像共享同一 player handle”的设计，只有当播放和录像都停止后才关闭底层播放器句柄。

快速切换 URL

在轮巡、多路预览、摄像头切换等场景下，可以使用快速切换 URL：

string url = textBox_url.Text.Trim(); if (_player.SwitchUrl(url)) { ShowMessage("正在切换播放地址..."); }

适用场景：

事件回调处理

播放器集成时建议至少处理以下事件：

示例：

private void Player_SDKEvent(object sender, SDKEventArgs e) { HandleSDKEvent( e.EventId, e.Param1, e.Param2, e.Param3, e.Param4, e.Param5, e.Param6); }

private void HandleSDKEvent( uint eventId, long param1, long param2, ulong param3, string param4, string param5, IntPtr param6) { switch ((NTSmartPlayerDefine.NT_SP_E_EVENT_ID)eventId) { case NTSmartPlayerDefine.NT_SP_E_EVENT_ID.NT_SP_E_EVENT_ID_CONNECTING: _connectionStatus = eventId; break; case NTSmartPlayerDefine.NT_SP_E_EVENT_ID.NT_SP_E_EVENT_ID_CONNECTED: _connectionStatus = eventId; break; case NTSmartPlayerDefine.NT_SP_E_EVENT_ID.NT_SP_E_EVENT_ID_CONNECTION_FAILED: _connectionStatus = eventId; break; case NTSmartPlayerDefine.NT_SP_E_EVENT_ID.NT_SP_E_EVENT_ID_DISCONNECTED: _connectionStatus = eventId; break; case NTSmartPlayerDefine.NT_SP_E_EVENT_ID.NT_SP_E_EVENT_ID_RTSP_STATUS_CODE: if ((int)param1 == 401) { _lastTip = "RTSP 401：需要认证"; HandleVerification(); } break; } UpdateStatusLabel(); }

下载速度与丢包率展示

新版本 Demo 已增加下载速度与丢包率状态展示。播放过程中，SDK 会通过DOWNLOAD_SPEED事件上报下载速度和网络质量指标。

状态字段定义

private long _downloadSpeedBytes = -1; // Byte/s private long _netQualityMetrics = 0; // DOWNLOAD_SPEED 事件的 param2

回调中保存下载速度与网络质量指标

if (eventId == (uint)NTSmartPlayerDefine.NT_SP_E_EVENT_ID.NT_SP_E_EVENT_ID_DOWNLOAD_SPEED) { Interlocked.Exchange(ref _downloadSpeedBytes, param1); Interlocked.Exchange(ref _netQualityMetrics, param2); }

丢包率解析规则

bit15 置位时表示丢包率有效； 低 15 位为丢包率原始值； 丢包率百分比 = (param2 & 0x7FFF) / 256.0

状态栏展示示例

private void UpdateStatusLabel() { StringBuilder showStr = new StringBuilder(); // 下载速度 long speedBytes = Interlocked.Read(ref _downloadSpeedBytes); if (speedBytes >= 0) { int speedKbps = (int)(speedBytes * 8 / 1000); int speedKBps = (int)(speedBytes / 1024); showStr.Append(" 下载速度: ") .Append(speedKbps) .Append("kbps ") .Append(speedKBps) .Append("KB/s"); } // 丢包率 long metrics = Interlocked.Read(ref _netQualityMetrics); if (metrics != 0 && ((metrics >> 15) & 1L) != 0) { float lossRate = (float)(metrics & 0x7FFFL) / 256.0f; showStr.Append(" 丢包率: ") .Append(lossRate.ToString("F2")) .Append("%"); } lable_cur_status_txt.Text = showStr.ToString(); }

播放开始和停止时重置状态

_connectionStatus = 0; _bufferStatus = 0; _bufferPercent = 0; Interlocked.Exchange(ref _downloadSpeedBytes, -1); Interlocked.Exchange(ref _netQualityMetrics, 0); _lastTip = "";

使用建议

该能力非常适合现场排查，例如客户反馈“画面卡顿”“播放不流畅”“偶发缓冲”“RTSP UDP 播放不稳定”时，可以直接通过状态栏观察下载速度和丢包率，快速判断是播放器问题、网络问题，还是上游流媒体源问题。

RTSP 401 鉴权处理

部分 RTSP 摄像头或 NVR 开启了用户名密码认证。当播放过程中收到 RTSP 401 状态码时，业务层可以弹出鉴权对话框，让用户输入用户名和密码后重新播放。

示例逻辑：

case NTSmartPlayerDefine.NT_SP_E_EVENT_ID.NT_SP_E_EVENT_ID_RTSP_STATUS_CODE: int statusCode = (int)param1; if (statusCode == 401) { _lastTip = "RTSP 401：需要认证"; UpdateStatusLabel(); HandleVerification(); return; } break;

处理建议：

视频渲染与窗口管理

Windows 播放器推荐采用独立渲染控件承载视频画面，避免业务 UI 直接操作底层窗口句柄。

Demo 中采用双层窗口结构：

推荐接入方式：

_player.RenderControl.Dock = DockStyle.Fill; panelPlayer.Controls.Add(_player.RenderControl);

窗口大小变化时通知 SDK：

private void SmartPlayerForm_ResizeEnd(object sender, EventArgs e) { if (_player != null && _player.IsPlaying) { _player.RenderControl.NotifyWindowSizeChanged(); } }

全屏切换

private void btn_full_screen__Click(object sender, EventArgs e) { if (_player != null) { _player.FullScreenSwitch(); } }

建议支持：

音视频控制

静音与音量

_player.SetMute(true); // 静音 _player.SetMute(false); // 取消静音 _player.SetVolume(80); // 设置音量

UI 示例：

private void checkBox_mute_CheckedChanged(object sender, EventArgs e) { if (_player != null) _player.SetMute(checkBox_mute.Checked); } private void slider_audio_volume_ValueChanged(object sender, EventArgs e) { cur_audio_volume.Text = slider_audio_volume.Value.ToString(); if (_player != null) _player.SetVolume(slider_audio_volume.Value); }

旋转与镜像

_player.SetRotation(90); _player.SetFlipHorizontal(true); _player.SetFlipVertical(false);

适用场景：

等比例缩放

_player.SetRenderScaleMode(true); // 等比例显示 _player.SetRenderScaleMode(false); // 拉伸填充

建议：

只解码关键帧

_player.SetOnlyDecodeKeyFrame(true);

适合：

GDI 滤镜处理

Demo 中提供了 GDI 模式下的亮度、对比度、饱和度调节示例。该功能主要用于 C# 层软件滤镜演示，仅在启用 GDI 渲染/视频帧处理模式时生效。

_effectProcessor.UpdateParameters( trackBar_brightness.Value, trackBar_contrast.Value, trackBar_saturation.Value);

重置滤镜：

trackBar_brightness.Value = 0; trackBar_contrast.Value = 0; trackBar_saturation.Value = 0; _effectProcessor.UpdateParameters(0, 0, 0);

说明：

实时截图

播放过程中可调用截图接口保存当前画面：

string filename = Path.Combine( _captureImagePath, DateTime.Now.ToString("yyyy-MM-dd_HH-mm-ss") + ".png"); _player.CaptureImage(filename);

截图完成后通过回调获取结果：

private void Player_CaptureImageCompleted(object sender, CaptureImageEventArgs e) { if (e.Success && !string.IsNullOrEmpty(e.FileName)) { MessageBox.Show(e.FileName, "截图成功"); } else { ShowMessage("截图失败"); } }

注意事项：

播放端录像

播放端录像适用于取证、监控留存、课程回放、无人机巡检存档等场景。建议将录像参数与播放参数分离，避免播放逻辑与录像逻辑相互影响。

录像配置

RecordConfig recordConfig = new RecordConfig { IsRecordVideo = true, IsRecordAudio = true, RecordDirectory = @"D:\\record", RecordFilePrefix = "smartplayer", MaxRecordFileSize = 500 * 1024, IsAppendDate = true, IsAppendTime = true, IsAudioTranscodeAAC = true };

参数说明：

播放中启动录像

bool success = _player.StartRecord(_recordConfig); if (success) { btn_record.Text = "停止录像"; } else { MessageBox.Show("录像失败！"); }

未播放时直接录像

如果当前没有启动播放，也可以传入 URL、播放基础配置和录像配置，直接启动拉流录像：

PlayConfig playConfig = new PlayConfig(); playConfig.IsRtspTcpMode = checkBox_rtsp_tcp.Checked; playConfig.BufferTime = GetBufferTime(); playConfig.IsFastStartup = checkBox_fast_startup.Checked; playConfig.RtspTimeout = 10; playConfig.IsRtspAutoSwitchTcpUdp = true; playConfig.EnableReportDownloadSpeed = true; playConfig.ReportDownloadSpeedIntervalSeconds = 1; bool success = _player.StartRecord(url, playConfig, _recordConfig);

停止录像

_player.StopRecord(); btn_record.Text = "录像";

录像状态回调

private void Player_RecordStatusChanged(object sender, RecordEventArgs e) { StringBuilder sb = new StringBuilder(); sb.Append("录像状态："); if (e.IsStarted) { sb.Append("new file: "); } else if (e.IsFinished) { sb.Append("finished file: "); } if (!string.IsNullOrEmpty(e.FilePath)) sb.Append(e.FilePath); MessageBox.Show(sb.ToString()); }

推荐设计：

多路播放

多路播放时，每一路流创建一个独立播放器实例：

for (int i = 0; i < urls.Length; i++) { NTPlayerWrapper player = new NTPlayerWrapper(); player.RenderControl.Dock = DockStyle.Fill; gridPanels[i].Controls.Add(player.RenderControl); PlayConfig config = new PlayConfig { IsFastStartup = true, IsRtspAutoSwitchTcpUdp = true, UseHardwareDecoder = true, IsRenderScaleMode = true, EnableReportDownloadSpeed = true, ReportDownloadSpeedIntervalSeconds = 1 }; player.StartPlay(urls[i], config); }

建议配置：

日志配置

调试阶段建议开启 SDK 日志：

NTSmartLog.NT_SL_SetPath(@"D:\playerlog");

建议：

常见问题排查

最小可运行示例

public partial class MainForm : Form { private NTPlayerWrapper _player; public MainForm() { InitializeComponent(); NTPlayerWrapper.ForceInitSDK(); _player = new NTPlayerWrapper(); _player.RenderControl.Dock = DockStyle.Fill; panelPlayer.Controls.Add(_player.RenderControl); _player.SDKEvent += Player_SDKEvent; _player.VideoSizeChanged += Player_VideoSizeChanged; } private void btnPlay_Click(object sender, EventArgs e) { PlayConfig config = new PlayConfig { IsFastStartup = true, IsLowLatencyMode = true, IsRtspAutoSwitchTcpUdp = true, RtspTimeout = 10, BufferTime = 0, IsRenderScaleMode = true, AudioVolume = 100, EnableReportDownloadSpeed = true, ReportDownloadSpeedIntervalSeconds = 1 }; bool ok = _player.StartPlay(textBoxUrl.Text.Trim(), config); if (!ok) { MessageBox.Show("播放失败"); } } private void btnStop_Click(object sender, EventArgs e) { _player.StopPlay(); } private void Player_VideoSizeChanged(object sender, VideoSizeEventArgs e) { BeginInvoke((Action)(() => { labelResolution.Text = $"{e.Width} x {e.Height}"; })); } private void Player_SDKEvent(object sender, SDKEventArgs e) { BeginInvoke((Action)(() => { labelStatus.Text = $"Event: {e.EventId}, Param1: {e.Param1}, Param2: {e.Param2}"; })); } protected override void OnFormClosed(FormClosedEventArgs e) { if (_player != null) { _player.StopPlay(); _player.Dispose(); _player = null; } NTPlayerWrapper.ForceUninitSDK(); base.OnFormClosed(e); } }

生产环境建议

在正式项目中，建议重点关注以下方面：

小结

大牛直播SDK（SmartMediaKit）Windows 平台 RTSP、RTMP 直播播放 SDK，适合需要低延迟、高稳定性、可工程化集成的 Windows 实时音视频客户端项目。通过SmartPlayerSDK.dll与 C# 封装，开发者可以快速完成 RTSP/RTMP 播放、低延迟参数配置、软硬解切换、事件监听、截图、录像、多路播放、视频帧回调和网络质量监测等能力集成。

从工程实践角度看，建议将 SDK 接口调用、播放器生命周期、播放参数、录像参数、渲染窗口和事件处理进行模块化封装。当前 C# Demo 已经具备较好的工程分层基础，并新增下载速度与丢包率展示能力，便于开发者在播放过程中实时观察网络质量状态，辅助定位弱网、卡顿、缓冲频繁、RTSP UDP 丢包等现场问题。

整体而言，该方案不仅适合作为 Windows 平台 RTSP/RTMP 播放 SDK 的标准集成 Demo，也适合作为安防监控、工业视觉、远程教育、应急指挥、无人机巡检、低空经济等行业系统的实时视频播放能力基础组件。

📎 CSDN官方博客：音视频牛哥-CSDN博客