大牛直播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 等常见直播协议，并提供低延迟播放、首屏秒开、软硬解切换、音视频控制、实时快照、播放端录像、事件回调、视频帧回调、下载速度回调、丢包率展示等能力。

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

---

适用场景

场景	说明
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.cs	C# P/Invoke 接口声明
smart_player_define.cs	播放器事件、结构体、枚举定义
nt_base_code_define.cs	基础错误码定义
smart_log.cs	日志接口声明
smart_log_define.cs	日志级别与参数定义
NTPlayerWrapper.cs	C# 播放器封装层
NTWrapperRenderWindow.cs	外层渲染窗口封装
NTRenderWindow.cs	内层真实渲染窗口
VideoEffectProcessor.cs	GDI 模式下的视频滤镜处理示例

---

推荐工程分层

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

业务层 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 自动切换
RtspTimeout	RTSP 连接超时时间
BufferTime	播放缓冲时间，单位毫秒
IsFastStartup	是否启用秒开模式
IsLowLatencyMode	是否启用低延迟模式
UseHardwareDecoder	是否启用硬件解码
IsOnlyDecodeKeyFrame	是否只解码视频关键帧
IsMute	是否静音
AudioVolume	音量，建议范围 0~100
IsRenderScaleMode	是否等比例显示
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 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("正在切换播放地址...");
}

适用场景：

场景	说明
监控轮巡	多路摄像头按时间间隔切换
码流切换	主码流 / 子码流切换
设备切换	同一播放器窗口切换不同设备
故障恢复	当前流异常后切换备用流

---

事件回调处理

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

事件类型	说明
CONNECTING	正在连接
CONNECTED	已连接
CONNECTION_FAILED	连接失败
DISCONNECTED	连接断开
START_BUFFERING	开始缓冲
BUFFERING	缓冲进度
STOP_BUFFERING	缓冲结束
DOWNLOAD_SPEED	下载速度与网络质量指标回调
RTSP_STATUS_CODE	RTSP 状态码，例如 401 鉴权
NEED_KEY	RTMP 加密流需要 Key
KEY_ERROR	RTMP 加密流 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/s
param2	网络质量指标，可用于解析丢包率

状态字段定义

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);

窗口大小变化时通知 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();
    }
}

建议支持：

操作	行为
双击播放窗口	进入或退出全屏
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 关闭时停止播放、停止录像、释放播放器实例

---

小结

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

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

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

---

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