文档概述本文介绍大牛直播SDKSmartMediaKit在 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 丢包等现场问题。产品概述大牛直播SDKSmartMediaKitWindows 播放器 SDK 是面向专业级实时音视频场景设计的低延迟直播播放组件适用于 RTSP 摄像头/NVR 预览、RTMP 直播拉流、工业视觉、安防监控、远程教育、应急指挥、无人机回传、低空经济等需要稳定、超低延迟100~200ms播放能力的 Windows 客户端系统。Windows 播放模块基于SmartPlayerSDK.dll提供统一的播放器能力支持 RTMP、RTSP 等常见直播协议并提供低延迟播放、首屏秒开、软硬解切换、音视频控制、实时快照、播放端录像、事件回调、视频帧回调、下载速度回调、丢包率展示等能力。其核心定位不是通用播放器外壳而是面向系统集成场景的实时流媒体播放内核适合嵌入到行业客户端、监控平台、调度系统、设备管理平台和实时音视频业务系统中。适用场景场景说明RTSP 实时预览对接 IPC、NVR、编码器、无人机、执法记录仪、机器人等 RTSP 源RTMP 直播播放对接 RTMP Server、CDN、直播平台或自建流媒体服务多路实时播放Windows 客户端多画面预览、轮巡、监控大屏低延迟播放用于远程控制、工业视觉、应急调度、无人机回传等低延迟场景播放端录像拉流播放同时进行本地 MP4 录像实时截图播放过程中截取当前画面并保存为 PNG 图片网络质量监测展示下载速度、丢包率、缓冲状态辅助现场问题排查音视频数据回调获取 PCM、RGB/YUV 视频帧用于分析、识别或二次处理能力概览能力项说明协议支持支持 RTMP、RTSP 等直播流播放RTSP 传输模式支持 RTSP TCP、UDP 以及 TCP/UDP 自动切换视频编码支持 H.264、H.265 等常见视频编码格式音频编码支持 AAC、PCMA、PCMU 等常见音频格式低延迟播放支持低延迟模式、缓冲时间配置、首屏秒开解码模式支持软解码Windows 平台可根据环境检测并启用硬解渲染控制支持等比例缩放、拉伸填充、旋转、水平翻转、垂直翻转音频控制支持静音、取消静音、音量调节截图支持播放过程中实时快照保存为 PNG 图片录像支持播放端录像支持录像目录、文件大小、文件名规则配置下载速度上报支持按配置间隔上报实时下载速度丢包率展示支持通过网络质量指标解析丢包率辅助弱网排查事件回调支持连接状态、缓冲状态、RTSP 状态码、播放结束、录像状态等回调音视频帧回调支持 PCM 音频帧、视频帧、自定义数据回调多实例播放支持多个播放器实例同时播放适合多画面监控场景开发环境建议使用如下环境进行 Windows C# Demo 集成项目建议配置操作系统Windows 7 及以上开发工具Visual Studio 2013平台架构x86 或 x64与 SDK 库目录保持一致UI 框架Windows Forms / WPF 均可Demo 以 WinForms 为例注意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其中文件说明SmartPlayerSDK.dll播放器核心动态库SmartLog.dll日志模块动态库smart_player_sdk.csC# P/Invoke 接口声明smart_player_define.cs播放器事件、结构体、枚举定义nt_base_code_define.cs基础错误码定义smart_log.cs日志接口声明smart_log_define.cs日志级别与参数定义NTPlayerWrapper.csC# 播放器封装层NTWrapperRenderWindow.cs外层渲染窗口封装NTRenderWindow.cs内层真实渲染窗口VideoEffectProcessor.csGDI 模式下的视频滤镜处理示例推荐工程分层为了降低业务层接入复杂度建议采用如下分层结构业务层 Form / Page ↓ NTPlayerWrapper - SDK 初始化与销毁 - player handle 管理 - StartPlay / StopPlay - StartRecord / StopRecord - CaptureImage - 音量、静音、旋转、镜像、缩放 - 下载速度与丢包率状态处理 - SDK 事件统一转发 ↓ NTWrapperRenderWindow - 外层渲染控件 - 全屏切换 - 窗口大小变化 - 键盘 / 鼠标事件 ↓ NTRenderWindow - 实际渲染窗口 - D3D / GDI 绘制承载 - RGB32 帧绘制 - 清屏与重绘管理这种设计方式具备以下优点优点说明业务层更简洁Form/Page 只关心播放、停止、录像、截图、状态显示播放与录像解耦播放参数和录像参数分离便于边播边录、仅录像等场景渲染窗口可复用渲染窗口独立封装便于 WinForms / WPF / 多窗口复用回调统一管理连接、缓冲、下载速度、丢包率、RTSP 401 等事件统一处理易于扩展后续可扩展 AI 分析、视频帧回调、PCM 回调、自定义数据回调集成流程添加 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 };参数说明参数说明IsRtspTcpMode是否强制 RTSP 使用 TCP 模式IsRtspAutoSwitchTcpUdp是否启用 RTSP TCP/UDP 自动切换RtspTimeoutRTSP 连接超时时间BufferTime播放缓冲时间单位毫秒IsFastStartup是否启用秒开模式IsLowLatencyMode是否启用低延迟模式UseHardwareDecoder是否启用硬件解码IsOnlyDecodeKeyFrame是否只解码视频关键帧IsMute是否静音AudioVolume音量建议范围 0~100IsRenderScaleMode是否等比例显示RotateDegrees视频旋转角度IsFlipHorizontal是否水平翻转IsFlipVertical是否垂直翻转EnableReportDownloadSpeed是否启用下载速度与网络质量上报ReportDownloadSpeedIntervalSeconds下载速度上报间隔单位秒RTSP / RTMP 播放开始播放string url textBoxUrl.Text.Trim(); bool ret _player.StartPlay(url, config); if (!ret) { MessageBox.Show(播放失败请检查播放地址、网络连接或 SDK 授权状态。); return; }典型 RTSP URLrtsp://user:password192.168.1.100:554/stream1典型 RTMP URLrtmp://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在轮巡、多路预览、摄像头切换等场景下可以使用快速切换 URLstring url textBox_url.Text.Trim(); if (_player.SwitchUrl(url)) { ShowMessage(正在切换播放地址...); }适用场景场景说明监控轮巡多路摄像头按时间间隔切换码流切换主码流 / 子码流切换设备切换同一播放器窗口切换不同设备故障恢复当前流异常后切换备用流事件回调处理播放器集成时建议至少处理以下事件事件类型说明CONNECTING正在连接CONNECTED已连接CONNECTION_FAILED连接失败DISCONNECTED连接断开START_BUFFERING开始缓冲BUFFERING缓冲进度STOP_BUFFERING缓冲结束DOWNLOAD_SPEED下载速度与网络质量指标回调RTSP_STATUS_CODERTSP 状态码例如 401 鉴权NEED_KEYRTMP 加密流需要 KeyKEY_ERRORRTMP 加密流 Key 错误PLAYBACK_REACH_EOS点播播放结束RECORDER_REACH_EOS点播录像结束PULLSTREAM_REACH_EOS拉流结束DURATION点播时长上报示例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事件上报下载速度和网络质量指标。参数含义param1下载速度单位为 Byte/sparam2网络质量指标可用于解析丢包率状态字段定义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 ;使用建议指标说明下载速度正常丢包率低网络状态较稳定下载速度低频繁缓冲可能存在带宽不足、服务器转发异常或上游推流码率不足下载速度正常丢包率高可能存在 UDP 丢包、无线链路抖动、瞬时拥塞丢包率高且频繁缓冲建议优先尝试 RTSP TCP 模式或 TCP/UDP 自动切换丢包率不显示当前回调未携带有效网络质量指标可结合下载速度和缓冲事件判断该能力非常适合现场排查例如客户反馈“画面卡顿”“播放不流畅”“偶发缓冲”“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;处理建议场景建议URL 已包含用户名密码但仍 401检查用户名、密码是否正确摄像头要求 Digest 鉴权使用 SDK 提供的 RTSP 鉴权接口播放中收到 401停止当前播放设置鉴权信息后重新播放同时录像重新鉴权后恢复播放和录像状态视频渲染与窗口管理Windows 播放器推荐采用独立渲染控件承载视频画面避免业务 UI 直接操作底层窗口句柄。Demo 中采用双层窗口结构层级类职责外层窗口NTWrapperRenderWindow处理全屏切换、窗口大小变化、键盘/鼠标事件、双击全屏内层窗口NTRenderWindow作为实际渲染目标承载 D3D/GDI 渲染输出推荐接入方式_player.RenderControl.Dock DockStyle.Fill; panelPlayer.Controls.Add(_player.RenderControl);窗口大小变化时通知 SDKprivate 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(); } }建议支持操作行为双击播放窗口进入或退出全屏ESC 键退出全屏窗口大小变化通知 SDK 更新渲染区域停止播放禁用全屏按钮并清空画面状态音视频控制静音与音量_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); // 拉伸填充建议模式适用场景等比例显示安防监控、工业视觉、AI 分析、需要保持真实比例的场景拉伸填充大屏展示、窗口铺满、对比例不敏感的业务界面只解码关键帧_player.SetOnlyDecodeKeyFrame(true);适合场景说明多路小窗口预览降低 CPU 占用监控轮巡只需查看大概画面变化弱性能设备降低解码压力非实时细节分析对帧率要求不高的场景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);说明项目说明亮度调整画面整体明暗对比度调整明暗层次饱和度调整色彩浓度生效模式GDI 软件处理模式性能影响多路播放时建议谨慎开启实时截图播放过程中可调用截图接口保存当前画面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(截图失败); } }注意事项项目建议截图路径截图前先设置保存目录播放状态建议仅在播放状态下截图文件格式推荐保存为 PNG截图频率不建议高频连续截图权限确保目录具备写入权限播放端录像播放端录像适用于取证、监控留存、课程回放、无人机巡检存档等场景。建议将录像参数与播放参数分离避免播放逻辑与录像逻辑相互影响。录像配置RecordConfig recordConfig new RecordConfig { IsRecordVideo true, IsRecordAudio true, RecordDirectory D:\\record, RecordFilePrefix smartplayer, MaxRecordFileSize 500 * 1024, IsAppendDate true, IsAppendTime true, IsAudioTranscodeAAC true };参数说明参数说明IsRecordVideo是否录制视频IsRecordAudio是否录制音频RecordDirectory录像保存目录RecordFilePrefix录像文件名前缀MaxRecordFileSize单个录像文件最大大小IsAppendDate文件名是否追加日期IsAppendTime文件名是否追加时间IsAudioTranscodeAAC是否将音频转 AAC播放中启动录像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()); }推荐设计设计点说明播放参数和录像参数分离避免播放配置影响录像配置播放和录像共享 handle支持边播边录、只播不录、只录不播文件路径回调录像开始和结束时上报文件路径文件大小切片按最大文件大小自动生成新录像文件音视频开关支持只录视频、只录音频、音视频同时录制多路播放多路播放时每一路流创建一个独立播放器实例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); }建议配置场景推荐策略4 路以内高清播放可优先软解根据 CPU 占用评估多路 1080P 播放建议检测并启用硬解多窗口小画面预览可考虑只解关键帧大屏轮巡建议使用快速切换 URL低延迟监控缓冲时间尽量小开启秒开和低延迟模式网络质量排查开启下载速度与丢包率状态上报弱网 RTSP优先尝试 TCP 模式或 TCP/UDP 自动切换日志配置调试阶段建议开启 SDK 日志NTSmartLog.NT_SL_SetPath(D:\playerlog);建议项目说明日志路径使用可写目录调用时机建议在 SDK 初始化前设置发布版本可根据需要降低日志级别问题排查客户现场问题建议保留日志网络问题结合下载速度、丢包率、缓冲事件一起分析常见问题排查问题可能原因建议处理SDK 初始化失败DLL 缺失、架构不一致、授权异常检查输出目录、x86/x64、License 设置播放失败URL 错误、网络不通、服务器异常使用测试工具验证流是否可播放RTSP 播放失败认证失败、TCP/UDP 不匹配、设备限制检查用户名密码开启 TCP 模式或自动切换RTSP 401摄像头/NVR 需要鉴权设置用户名密码后重新播放RTMP 播放失败推流未成功、服务地址错误、防火墙限制检查推流端、服务器、防火墙有声音无画面渲染窗口异常、视频编码异常检查 RenderWnd、解码配置、视频流格式有画面无声音流中无音频、静音开启、音量为 0检查音频轨、Mute、Volume延迟偏高缓冲时间过大、服务器缓存、网络波动减小 BufferTime开启 FastStartup 和 LowLatencyMode频繁缓冲网络不稳定、上游码率异常、带宽不足查看下载速度和丢包率丢包率较高UDP 丢包、无线链路质量差、网络抖动尝试 RTSP TCP 或 TCP/UDP 自动切换下载速度低上游码率不足、网络带宽不足、服务器转发异常检查推流端码率、服务端带宽、客户端网络丢包率高但下载速度正常网络突发抖动、UDP 丢包、链路瞬时拥塞结合缓冲事件和日志综合判断丢包率不显示当前回调未携带有效网络质量指标以下载速度、缓冲事件、连接状态辅助判断多路播放 CPU 高全部软解、分辨率过高、滤镜开启尝试硬解、降低窗口刷新、关闭滤镜截图失败非播放状态、路径无权限、请求过频繁确认播放状态、目录权限、降低截图频率录像失败目录不存在、权限不足、音视频录制均未开启检查目录、权限、录像配置全屏异常窗口句柄变化、父窗口关系异常检查渲染窗口封装和窗口大小通知最小可运行示例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 初始化和反初始化必须成对调用架构一致x86/x64 必须与 SDK 库目录一致异常处理播放失败、断开、缓冲、认证失败都应有 UI 提示日志留存客户现场问题建议开启日志网络指标建议展示下载速度、丢包率、缓冲状态RTSP 模式弱网或公网环境优先考虑 TCP 模式多路播放注意 CPU、GPU、内存占用录像路径确保目录存在并具备写入权限回调线程UI 更新需切换到 UI 线程资源释放Form 关闭时停止播放、停止录像、释放播放器实例小结大牛直播SDKSmartMediaKitWindows 平台 RTSP、RTMP 直播播放 SDK适合需要低延迟、高稳定性、可工程化集成的 Windows 实时音视频客户端项目。通过SmartPlayerSDK.dll与 C# 封装开发者可以快速完成 RTSP/RTMP 播放、低延迟参数配置、软硬解切换、事件监听、截图、录像、多路播放、视频帧回调和网络质量监测等能力集成。从工程实践角度看建议将 SDK 接口调用、播放器生命周期、播放参数、录像参数、渲染窗口和事件处理进行模块化封装。当前 C# Demo 已经具备较好的工程分层基础并新增下载速度与丢包率展示能力便于开发者在播放过程中实时观察网络质量状态辅助定位弱网、卡顿、缓冲频繁、RTSP UDP 丢包等现场问题。整体而言该方案不仅适合作为 Windows 平台 RTSP/RTMP 播放 SDK 的标准集成 Demo也适合作为安防监控、工业视觉、远程教育、应急指挥、无人机巡检、低空经济等行业系统的实时视频播放能力基础组件。 CSDN官方博客音视频牛哥-CSDN博客
大牛直播SDK（SmartMediaKit）Windows平台RTSP/RTMP直播播放SDK集成说明（C#版）
文档概述本文介绍大牛直播SDKSmartMediaKit在 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 丢包等现场问题。产品概述大牛直播SDKSmartMediaKitWindows 播放器 SDK 是面向专业级实时音视频场景设计的低延迟直播播放组件适用于 RTSP 摄像头/NVR 预览、RTMP 直播拉流、工业视觉、安防监控、远程教育、应急指挥、无人机回传、低空经济等需要稳定、超低延迟100~200ms播放能力的 Windows 客户端系统。Windows 播放模块基于SmartPlayerSDK.dll提供统一的播放器能力支持 RTMP、RTSP 等常见直播协议并提供低延迟播放、首屏秒开、软硬解切换、音视频控制、实时快照、播放端录像、事件回调、视频帧回调、下载速度回调、丢包率展示等能力。其核心定位不是通用播放器外壳而是面向系统集成场景的实时流媒体播放内核适合嵌入到行业客户端、监控平台、调度系统、设备管理平台和实时音视频业务系统中。适用场景场景说明RTSP 实时预览对接 IPC、NVR、编码器、无人机、执法记录仪、机器人等 RTSP 源RTMP 直播播放对接 RTMP Server、CDN、直播平台或自建流媒体服务多路实时播放Windows 客户端多画面预览、轮巡、监控大屏低延迟播放用于远程控制、工业视觉、应急调度、无人机回传等低延迟场景播放端录像拉流播放同时进行本地 MP4 录像实时截图播放过程中截取当前画面并保存为 PNG 图片网络质量监测展示下载速度、丢包率、缓冲状态辅助现场问题排查音视频数据回调获取 PCM、RGB/YUV 视频帧用于分析、识别或二次处理能力概览能力项说明协议支持支持 RTMP、RTSP 等直播流播放RTSP 传输模式支持 RTSP TCP、UDP 以及 TCP/UDP 自动切换视频编码支持 H.264、H.265 等常见视频编码格式音频编码支持 AAC、PCMA、PCMU 等常见音频格式低延迟播放支持低延迟模式、缓冲时间配置、首屏秒开解码模式支持软解码Windows 平台可根据环境检测并启用硬解渲染控制支持等比例缩放、拉伸填充、旋转、水平翻转、垂直翻转音频控制支持静音、取消静音、音量调节截图支持播放过程中实时快照保存为 PNG 图片录像支持播放端录像支持录像目录、文件大小、文件名规则配置下载速度上报支持按配置间隔上报实时下载速度丢包率展示支持通过网络质量指标解析丢包率辅助弱网排查事件回调支持连接状态、缓冲状态、RTSP 状态码、播放结束、录像状态等回调音视频帧回调支持 PCM 音频帧、视频帧、自定义数据回调多实例播放支持多个播放器实例同时播放适合多画面监控场景开发环境建议使用如下环境进行 Windows C# Demo 集成项目建议配置操作系统Windows 7 及以上开发工具Visual Studio 2013平台架构x86 或 x64与 SDK 库目录保持一致UI 框架Windows Forms / WPF 均可Demo 以 WinForms 为例注意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其中文件说明SmartPlayerSDK.dll播放器核心动态库SmartLog.dll日志模块动态库smart_player_sdk.csC# P/Invoke 接口声明smart_player_define.cs播放器事件、结构体、枚举定义nt_base_code_define.cs基础错误码定义smart_log.cs日志接口声明smart_log_define.cs日志级别与参数定义NTPlayerWrapper.csC# 播放器封装层NTWrapperRenderWindow.cs外层渲染窗口封装NTRenderWindow.cs内层真实渲染窗口VideoEffectProcessor.csGDI 模式下的视频滤镜处理示例推荐工程分层为了降低业务层接入复杂度建议采用如下分层结构业务层 Form / Page ↓ NTPlayerWrapper - SDK 初始化与销毁 - player handle 管理 - StartPlay / StopPlay - StartRecord / StopRecord - CaptureImage - 音量、静音、旋转、镜像、缩放 - 下载速度与丢包率状态处理 - SDK 事件统一转发 ↓ NTWrapperRenderWindow - 外层渲染控件 - 全屏切换 - 窗口大小变化 - 键盘 / 鼠标事件 ↓ NTRenderWindow - 实际渲染窗口 - D3D / GDI 绘制承载 - RGB32 帧绘制 - 清屏与重绘管理这种设计方式具备以下优点优点说明业务层更简洁Form/Page 只关心播放、停止、录像、截图、状态显示播放与录像解耦播放参数和录像参数分离便于边播边录、仅录像等场景渲染窗口可复用渲染窗口独立封装便于 WinForms / WPF / 多窗口复用回调统一管理连接、缓冲、下载速度、丢包率、RTSP 401 等事件统一处理易于扩展后续可扩展 AI 分析、视频帧回调、PCM 回调、自定义数据回调集成流程添加 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 };参数说明参数说明IsRtspTcpMode是否强制 RTSP 使用 TCP 模式IsRtspAutoSwitchTcpUdp是否启用 RTSP TCP/UDP 自动切换RtspTimeoutRTSP 连接超时时间BufferTime播放缓冲时间单位毫秒IsFastStartup是否启用秒开模式IsLowLatencyMode是否启用低延迟模式UseHardwareDecoder是否启用硬件解码IsOnlyDecodeKeyFrame是否只解码视频关键帧IsMute是否静音AudioVolume音量建议范围 0~100IsRenderScaleMode是否等比例显示RotateDegrees视频旋转角度IsFlipHorizontal是否水平翻转IsFlipVertical是否垂直翻转EnableReportDownloadSpeed是否启用下载速度与网络质量上报ReportDownloadSpeedIntervalSeconds下载速度上报间隔单位秒RTSP / RTMP 播放开始播放string url textBoxUrl.Text.Trim(); bool ret _player.StartPlay(url, config); if (!ret) { MessageBox.Show(播放失败请检查播放地址、网络连接或 SDK 授权状态。); return; }典型 RTSP URLrtsp://user:password192.168.1.100:554/stream1典型 RTMP URLrtmp://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在轮巡、多路预览、摄像头切换等场景下可以使用快速切换 URLstring url textBox_url.Text.Trim(); if (_player.SwitchUrl(url)) { ShowMessage(正在切换播放地址...); }适用场景场景说明监控轮巡多路摄像头按时间间隔切换码流切换主码流 / 子码流切换设备切换同一播放器窗口切换不同设备故障恢复当前流异常后切换备用流事件回调处理播放器集成时建议至少处理以下事件事件类型说明CONNECTING正在连接CONNECTED已连接CONNECTION_FAILED连接失败DISCONNECTED连接断开START_BUFFERING开始缓冲BUFFERING缓冲进度STOP_BUFFERING缓冲结束DOWNLOAD_SPEED下载速度与网络质量指标回调RTSP_STATUS_CODERTSP 状态码例如 401 鉴权NEED_KEYRTMP 加密流需要 KeyKEY_ERRORRTMP 加密流 Key 错误PLAYBACK_REACH_EOS点播播放结束RECORDER_REACH_EOS点播录像结束PULLSTREAM_REACH_EOS拉流结束DURATION点播时长上报示例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事件上报下载速度和网络质量指标。参数含义param1下载速度单位为 Byte/sparam2网络质量指标可用于解析丢包率状态字段定义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 ;使用建议指标说明下载速度正常丢包率低网络状态较稳定下载速度低频繁缓冲可能存在带宽不足、服务器转发异常或上游推流码率不足下载速度正常丢包率高可能存在 UDP 丢包、无线链路抖动、瞬时拥塞丢包率高且频繁缓冲建议优先尝试 RTSP TCP 模式或 TCP/UDP 自动切换丢包率不显示当前回调未携带有效网络质量指标可结合下载速度和缓冲事件判断该能力非常适合现场排查例如客户反馈“画面卡顿”“播放不流畅”“偶发缓冲”“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;处理建议场景建议URL 已包含用户名密码但仍 401检查用户名、密码是否正确摄像头要求 Digest 鉴权使用 SDK 提供的 RTSP 鉴权接口播放中收到 401停止当前播放设置鉴权信息后重新播放同时录像重新鉴权后恢复播放和录像状态视频渲染与窗口管理Windows 播放器推荐采用独立渲染控件承载视频画面避免业务 UI 直接操作底层窗口句柄。Demo 中采用双层窗口结构层级类职责外层窗口NTWrapperRenderWindow处理全屏切换、窗口大小变化、键盘/鼠标事件、双击全屏内层窗口NTRenderWindow作为实际渲染目标承载 D3D/GDI 渲染输出推荐接入方式_player.RenderControl.Dock DockStyle.Fill; panelPlayer.Controls.Add(_player.RenderControl);窗口大小变化时通知 SDKprivate 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(); } }建议支持操作行为双击播放窗口进入或退出全屏ESC 键退出全屏窗口大小变化通知 SDK 更新渲染区域停止播放禁用全屏按钮并清空画面状态音视频控制静音与音量_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); // 拉伸填充建议模式适用场景等比例显示安防监控、工业视觉、AI 分析、需要保持真实比例的场景拉伸填充大屏展示、窗口铺满、对比例不敏感的业务界面只解码关键帧_player.SetOnlyDecodeKeyFrame(true);适合场景说明多路小窗口预览降低 CPU 占用监控轮巡只需查看大概画面变化弱性能设备降低解码压力非实时细节分析对帧率要求不高的场景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);说明项目说明亮度调整画面整体明暗对比度调整明暗层次饱和度调整色彩浓度生效模式GDI 软件处理模式性能影响多路播放时建议谨慎开启实时截图播放过程中可调用截图接口保存当前画面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(截图失败); } }注意事项项目建议截图路径截图前先设置保存目录播放状态建议仅在播放状态下截图文件格式推荐保存为 PNG截图频率不建议高频连续截图权限确保目录具备写入权限播放端录像播放端录像适用于取证、监控留存、课程回放、无人机巡检存档等场景。建议将录像参数与播放参数分离避免播放逻辑与录像逻辑相互影响。录像配置RecordConfig recordConfig new RecordConfig { IsRecordVideo true, IsRecordAudio true, RecordDirectory D:\\record, RecordFilePrefix smartplayer, MaxRecordFileSize 500 * 1024, IsAppendDate true, IsAppendTime true, IsAudioTranscodeAAC true };参数说明参数说明IsRecordVideo是否录制视频IsRecordAudio是否录制音频RecordDirectory录像保存目录RecordFilePrefix录像文件名前缀MaxRecordFileSize单个录像文件最大大小IsAppendDate文件名是否追加日期IsAppendTime文件名是否追加时间IsAudioTranscodeAAC是否将音频转 AAC播放中启动录像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()); }推荐设计设计点说明播放参数和录像参数分离避免播放配置影响录像配置播放和录像共享 handle支持边播边录、只播不录、只录不播文件路径回调录像开始和结束时上报文件路径文件大小切片按最大文件大小自动生成新录像文件音视频开关支持只录视频、只录音频、音视频同时录制多路播放多路播放时每一路流创建一个独立播放器实例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); }建议配置场景推荐策略4 路以内高清播放可优先软解根据 CPU 占用评估多路 1080P 播放建议检测并启用硬解多窗口小画面预览可考虑只解关键帧大屏轮巡建议使用快速切换 URL低延迟监控缓冲时间尽量小开启秒开和低延迟模式网络质量排查开启下载速度与丢包率状态上报弱网 RTSP优先尝试 TCP 模式或 TCP/UDP 自动切换日志配置调试阶段建议开启 SDK 日志NTSmartLog.NT_SL_SetPath(D:\playerlog);建议项目说明日志路径使用可写目录调用时机建议在 SDK 初始化前设置发布版本可根据需要降低日志级别问题排查客户现场问题建议保留日志网络问题结合下载速度、丢包率、缓冲事件一起分析常见问题排查问题可能原因建议处理SDK 初始化失败DLL 缺失、架构不一致、授权异常检查输出目录、x86/x64、License 设置播放失败URL 错误、网络不通、服务器异常使用测试工具验证流是否可播放RTSP 播放失败认证失败、TCP/UDP 不匹配、设备限制检查用户名密码开启 TCP 模式或自动切换RTSP 401摄像头/NVR 需要鉴权设置用户名密码后重新播放RTMP 播放失败推流未成功、服务地址错误、防火墙限制检查推流端、服务器、防火墙有声音无画面渲染窗口异常、视频编码异常检查 RenderWnd、解码配置、视频流格式有画面无声音流中无音频、静音开启、音量为 0检查音频轨、Mute、Volume延迟偏高缓冲时间过大、服务器缓存、网络波动减小 BufferTime开启 FastStartup 和 LowLatencyMode频繁缓冲网络不稳定、上游码率异常、带宽不足查看下载速度和丢包率丢包率较高UDP 丢包、无线链路质量差、网络抖动尝试 RTSP TCP 或 TCP/UDP 自动切换下载速度低上游码率不足、网络带宽不足、服务器转发异常检查推流端码率、服务端带宽、客户端网络丢包率高但下载速度正常网络突发抖动、UDP 丢包、链路瞬时拥塞结合缓冲事件和日志综合判断丢包率不显示当前回调未携带有效网络质量指标以下载速度、缓冲事件、连接状态辅助判断多路播放 CPU 高全部软解、分辨率过高、滤镜开启尝试硬解、降低窗口刷新、关闭滤镜截图失败非播放状态、路径无权限、请求过频繁确认播放状态、目录权限、降低截图频率录像失败目录不存在、权限不足、音视频录制均未开启检查目录、权限、录像配置全屏异常窗口句柄变化、父窗口关系异常检查渲染窗口封装和窗口大小通知最小可运行示例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 初始化和反初始化必须成对调用架构一致x86/x64 必须与 SDK 库目录一致异常处理播放失败、断开、缓冲、认证失败都应有 UI 提示日志留存客户现场问题建议开启日志网络指标建议展示下载速度、丢包率、缓冲状态RTSP 模式弱网或公网环境优先考虑 TCP 模式多路播放注意 CPU、GPU、内存占用录像路径确保目录存在并具备写入权限回调线程UI 更新需切换到 UI 线程资源释放Form 关闭时停止播放、停止录像、释放播放器实例小结大牛直播SDKSmartMediaKitWindows 平台 RTSP、RTMP 直播播放 SDK适合需要低延迟、高稳定性、可工程化集成的 Windows 实时音视频客户端项目。通过SmartPlayerSDK.dll与 C# 封装开发者可以快速完成 RTSP/RTMP 播放、低延迟参数配置、软硬解切换、事件监听、截图、录像、多路播放、视频帧回调和网络质量监测等能力集成。从工程实践角度看建议将 SDK 接口调用、播放器生命周期、播放参数、录像参数、渲染窗口和事件处理进行模块化封装。当前 C# Demo 已经具备较好的工程分层基础并新增下载速度与丢包率展示能力便于开发者在播放过程中实时观察网络质量状态辅助定位弱网、卡顿、缓冲频繁、RTSP UDP 丢包等现场问题。整体而言该方案不仅适合作为 Windows 平台 RTSP/RTMP 播放 SDK 的标准集成 Demo也适合作为安防监控、工业视觉、远程教育、应急指挥、无人机巡检、低空经济等行业系统的实时视频播放能力基础组件。 CSDN官方博客音视频牛哥-CSDN博客
