概述
XPlayer 是基于 Qt 6 与 FFmpeg 的视频播放器，面向码流分析与 IPC 设备调试。支持本地文件、RTSP/RTMP/HTTP(S) 网络流，以及 ipc:// 设备复用流（视频与 JSON 命令共用一条 TCP）。
主要能力包括：NALU 帧分析、H.264/H.265 编码结构叠加、SEI AI 检测框、多窗口独立预览、Audition 风格音频分析、YOLO26 目标检测、PID / LQR / MPC 仿真与 SEI 曲线、云台控制与设备 JSON 命令、图片 / YUV 查看等。
主标签页
主工作区顶部有多个标签。部分标签默认隐藏，需通过 算法 菜单显示。切换标签时会自动清理上一标签内容（停止播放、关闭输入、停止仿真等）。
| 标签 | 说明 |
|---|---|
| 单视频 | 单路播放 + NALU 分析 + 编码叠加 |
| 多视频 | 1 / 2 / 4 分屏，每路独立播放与分析 |
| 音频 | Audition 风格波形 / 频谱分析 |
| 图片 | 静态图片查看与像素拾取 |
| YUV | 原始 YUV 文件查看与分析 |
| YOLO | YOLO26 目标检测（默认隐藏，算法 → 检测器 → YOLO） |
| PID | PID 仿真与 SEI 实时曲线（默认隐藏，算法 → 控制器 → PID） |
| LQR | LQR 仿真与 SEI 实时曲线（默认隐藏，算法 → 控制器 → LQR） |
| MPC | MPC 仿真与 SEI 实时曲线（默认隐藏，算法 → 控制器 → MPC） |
打开媒体
| 方式 | 说明 |
|---|---|
| File → Open... (Ctrl+O) | 打开本地媒体文件，支持多选 |
| File → Open Stream... / 打开网络串流 | 输入 RTSP/RTMP/HTTP/HTTPS/ipc:// 等地址 |
| File → 打开音频 (Ctrl+Shift+O) | 切到音频标签并打开音轨分析 |
| File → 打开图片 (Ctrl+I) | 打开静态图片 |
| File → 打开 YUV... | 打开原始 YUV（指定宽高与格式） |
| 拖拽 | 将文件或 URL 拖入主窗口 |
| 空界面点击 | 未加载时点击中间提示区域打开文件 |
| 命令行 | XPlayer.exe <文件路径或 URL> |
| File → Recent Files | 最近打开的本地文件（网络流不记录） |
地址示例
| 协议 | 示例 | 说明 |
|---|---|---|
| RTSP | rtsp://192.168.1.10/stream | 常规网络流 |
| TCP 裸流 | tcp://192.168.1.10:5000?format=h264 | 无帧头的裸 H264/HEVC |
| IPC 复用 | ipc://192.168.0.165 | 设备调试端口，默认 9558 |
本地文件 vs 网络流
| 类型 | 行为 |
|---|---|
| 本地文件 | 进入分析模式：分批扫描帧/NALU（默认每批 50 帧），自动预览首个 I 帧，不自动播放 |
| RTSP / RTMP / HTTP(S) | 打开后直接播放 |
| ipc:// 设备复用流 | 直接播放，同时建立设备命令通道，可在命令 Tab 发送 JSON |
打开失败：对话框会显示 FFmpeg 具体原因。若提示
moov atom not found，通常表示 MP4 未完整写入（录制未结束、复制中断等），请使用完整文件。
Open Stream 对话框
- 自动去除首尾空格并校验 URL 格式
- RTSP 在后台线程连接，界面显示
Connecting: ... - RTSP 先尝试 TCP，失败再尝试 UDP；连接超时约 5 秒
界面布局
- 主区域 8:2 水平分割：左侧视频，右侧 NALU 分析面板
- 深色主题（Fusion + 自定义
UiTheme） - 单视频标签下顶部工具栏：Open、叠加、量化、柱状图、AI 及算法、云台 下拉菜单
- 算法 菜单：
- 检测器 → YOLO（显示/隐藏 YOLO 标签）
- 控制器 → PID / LQR / MPC（显示/隐藏对应标签）
- Tools 菜单：重置视图、保存截图、媒体信息、打开串流录制目录
- 帮助 菜单：关于 XPlayer（版本、Qt/FFmpeg 版本、功能简介）
- 状态栏左侧：当前状态 / 帧号 / 像素坐标；右侧：当前时间 / 总时长
视频区域
标尺与缩放
- 顶部水平像素标尺，右侧垂直像素标尺（宽 52px）
- 滚轮：以鼠标位置为中心缩放（0.1×～20×）
- 放大后：左键拖拽平移画面
像素拾取
- 左键点击画面显示红色十字准星与圆点
- 坐标格式：
(x, y) [nx, ny]（源像素 + 归一化 0～1） - 状态栏同步显示
Pixel: (x, y) Norm: (nx, ny)
SEI AI 检测叠加
播放带用户数据 SEI 容器的 H.264/H.265 码流时，可在柱状图菜单中勾选 SEI叠加 后绘制 AI 检测框（默认不勾选）。单视频与多视频均支持。
| 功能 | 说明 |
|---|---|
| 触发条件 | SEI NALU 含 magic 0x13377331 |
| 检测框 | 按参考分辨率映射，显示类别 + 置信度% |
| 跟踪高亮 | AI_TRACK.track_id 与 AI_OBJ.track_id 一致时加粗高亮 |
| 双路竖拼 | 如 2880×3240 机型，默认只画上路广角目标 |
| 类别 | 0 人、1 车、2 bus、3 truck、7 猫、8 狗（其余显示 objN） |
码流分析柱状图（单视频）
工具栏 柱状图 下拉中至少勾选一项时显示 Elecard 风格帧大小/同步分析条。
- 滚轮缩放时间轴；放大后可左键拖拽；Shift + 滚轮平移
- 悬停显示帧详情（stream/display 序号、PTS、QP 等）
- 左侧面板 headers Tab：当前帧 H.264/H.265 语法头树
- 左侧面板 stream Tab：整路码流统计
空状态
无媒体时居中显示图标与提示：打开文件、网络串流，或将媒体拖到此处。右键可打开文件/串流；已加载时可关闭、查看详情。
播放控制
单视频
控件叠加在视频底部黑边区域。
| 控件 | 说明 |
|---|---|
| 播放/暂停 | 底部居中圆形按钮 |
| 进度条 | 拖动可 seek；暂停时拖动会实时更新画面预览 |
| 时间 | 进度条左右为当前/总时长 |
- 分析模式下点 ▶ 退出帧预览并开始正常播放
- 暂停后再播放从当前位置继续，不会从头重播
- 播放中 Frame List 持续收集新帧，进度条自动跟随
- 无音轨视频用视频 PTS 驱动进度条
多视频
- 每个分屏窗口底部有独立播放/暂停按钮
- 点击窗口画面可切换音频输出（同时仅一路有声音）
- 多视频标签下不显示单视频的全局进度条
多视频
分屏布局
在面板空白处或任意窗口 右键 → 分屏：
| 选项 | 布局 |
|---|---|
| 1 分屏 | 单窗口全屏 |
| 2 分屏（上下） | 上下两路 |
| 2 分屏（左右） | 左右两路 |
| 4 分屏 | 2×2 四路（默认） |
与 NALU 面板联动
- 选中窗口后，右侧 Frame List / 十六进制显示该窗口数据
- 暂停后可用 ↑/↓ 选帧预览；滚到底部加载下一批（每批 50 帧）
- 本地文件打开后直接播放（与单视频「先分析再播」不同）
音频
标签 音频 提供 Adobe Audition 风格的本地音频分析。切换时右侧 NALU 面板自动隐藏。
打开方式
- 文件 → 打开音频（Ctrl+Shift+O）或拖放音视频文件 / 网络流 URL
- 支持从 MP4 / MKV / AVI 等容器提取音轨；网络流最多截取约 120 秒做波形与频谱预览
界面要点
| 区域 | 说明 |
|---|---|
| 左侧 | 文件列表、属性树、可选视频预览 |
| 中央波形 | 立体声波形、概览条、时间标尺、播放头 |
| 中央频谱 | STFT 热力图，可开关显示 |
| 底部 | 播放控制与实时 L/R 电平表 |
空状态为居中图标 + 标题「音频分析」+ 打开提示（与图片 / YUV 空状态风格一致）。
图片与 YUV
图片
- 文件 → 打开图片（Ctrl+I）、空状态点击、右键打开、拖放
- 标尺、滚轮缩放、左键拖拽平移、像素拾取（RGB/BGR 等）
- 空状态：居中「图片查看」标题 + 打开提示（与音频分析同风格）
YUV
- 文件 → 打开 YUV...，指定宽高与像素格式；文件名含宽高与格式时可自动解析
- 支持标尺、缩放平移、像素拾取、直方图等
- 空状态：居中「YUV 查看」标题 + 打开提示；例
name_1920x1080_nv12.yuv - 切换至其他主标签时会清空 YUV 视图
YOLO 检测
标签 YOLO 默认隐藏，通过菜单 算法 → 检测器 → YOLO 显示。用于 YOLO26 目标检测；切换时右侧 NALU 面板自动隐藏，工作区全宽显示。
输入源
| 方式 | 说明 |
|---|---|
| 打开图片 | PNG / JPEG / BMP / WebP 等 |
| 打开视频 | MP4 / MKV / AVI 等 |
| RTSP/串流 | rtsp://、http://、rtmp:// |
操作
| 按钮 | 说明 |
|---|---|
| 检测当前帧 | 对当前图片或视频/流的一帧运行检测 |
| 实时检测 | 视频或 RTSP 上连续检测（约 30 fps） |
| 关闭 | 停止检测并释放输入 |
启动时自动从可执行文件目录向上查找 models/ 下的默认 ONNX（优先 yolo26n.onnx / yolo26n_quantized.onnx）。可调置信度阈值与输入尺寸（默认 640）。类别按 COCO 80 类显示；推理基于 OpenCV DNN（CPU）。
控制器 PID / LQR / MPC
三个标签默认隐藏，通过 算法 → 控制器 勾选显示。布局统一为左侧响应曲线、右侧参数与数据面板；均可连接本地视频或 ipc:// / RTSP，从 SEI PTZ_POS 绘制方位角 / 俯仰角曲线。
共用曲线
| 曲线 | 说明 |
|---|---|
| 设定值 | 白虚线：仿真目标或 SEI 目标角 |
| 实际值 | 红实线：过程值或 SEI 当前角 |
| 输出 % | 绿实线（右轴 0～100%）：控制量；SEI 模式下为 PTZ_POS.speed |
Pan / Tilt 可同时勾选；滚轮缩放时间轴，双击还原全量范围。连接串流期间本地仿真禁用。
PID
- 参数：Kp / Ki / Kd、设定值；高级：过程增益、时间常数（一阶惯性植物）
- 实时读数：设定值、实际值、输出 %、P / I / D 分项
- Brett Beauregard 风格，derivative-on-measurement
LQR
- 权重：Q 位置 / Q 速度 / R 控制；应用后重算增益 K
- 实时读数：设定值、实际值、输出 %、K0、K1、误差 e
- 离散 2 状态 LQR（位置误差 + 误差变化率），DARE 求增益
MPC
- 权重：Q 跟踪 / R 控制；预测时域 N（2～60）
- 实时读数：设定值、实际值、输出 %、时域 N、代价 J、误差 e
- 有限时域滚动优化（move-blocking，时域内常值 u）
NALU 分析面板（右侧）
上方 Tab
| Tab | 说明 |
|---|---|
| 十六进制 | 选中帧或 NALU 后的 hex dump |
| 云台控制 | PTZ 方向控制与标定；工具栏「云台 → 云台控制」显示/隐藏 |
下方 Tab
| Tab | 说明 |
|---|---|
| 帧列表 | 树形帧/NALU 列表，父节点 [I]/[P]/[B]，子节点为 NALU |
| 标定坐标 | 手动标定后显示标定点表格 |
| 命令 | JSON 命令控制台（ipc:// 串流后自动建立通道） |
Frame #N为列表连续显示序号；pkt=N为 demux 包序号（含义不同）- 按批加载（默认 50 帧/批），选中最后一帧或按 ↓ 继续加载
- 选中帧：左侧预览图像；选中 NALU：hex 区显示单个 NALU
- 切换到 YOLO / 音频 / PID / LQR / MPC 等标签时，NALU 面板会自动隐藏
编码叠加（单视频）
仅在 单视频 标签时，顶部工具栏 叠加 / 量化 可用。
叠加（编码结构）
| 选项 | 说明 |
|---|---|
| 编码树单元 | 按 CU/CTU 类型着色 |
| 编码单元 | CU/CTU 划分网格 |
| 预测单元 / 变换单元 | PU/TU 划分线 |
| 索引编号 | 块内序号 |
量化
| 选项 | 说明 |
|---|---|
| 量化热力图 | 按 QP 着色块填充 |
| 量化数值 | StreamEye 风格黄色 QP 数字；悬停显示白色边框与子划分 |
| 样本自适应偏移 | SAO 类型标签 |
| 运动矢量 | 粉色箭头（P/B 帧更明显） |
4K 提示：分辨率 > 1080p 时跳过全帧 HEVC CABAC，显示 CTU 级 slice QP，属正常行为。
媒体信息
通过 Tools → 媒体信息，或已加载媒体时 右键 → 详情 打开。
| Tab | 内容 |
|---|---|
| 常规 | 容器格式、文件大小、时长、播放状态、分辨率、平均 GOP |
| 编解码器 | 各流类型、编解码器、码率、分辨率、帧率、采样率等 |
| 统计 | 已解码/显示帧数、丢帧、已读字节、容器码率（每 0.5s 刷新） |
云台与 JSON 命令
云台面板
- 位于右侧 云台控制 Tab；工具栏 云台 → 云台控制 可显示/隐藏
- 速度滑块 1～100（默认 8）；方向键 3×3 支持长按连续发送
ipc://设备通过 TCP 发送{"module":"ptz","cmd":"set",...}- 工具栏 云台 → 云台：视频上浮动视场示意图（可拖动）
- 手动标定：画面上拾取坐标，显示在标定坐标 Tab
命令 Tab
打开 ipc:// 串流后命令通道自动就绪，无需单独连接。上方显示 设备命令通道：host:port。
预设命令
| 分类 | 示例 |
|---|---|
| 设备 | sys ping/help、ptz get/set/calib、osd 1/0 |
| 本地 | ptz action、get ptz_position、get ptz_calibration |
IPC 复用 TCP 帧格式
[1 字节 type][4 字节 length][payload]
type=1 双向 JSON（命令/应答）
type=2 设备→客户端 编码裸流（H264/HEVC）请求与响应
// 请求
{"module":"ptz","cmd":"get"}
// 响应
{"result":0,"data":{...}}发送快捷键：Ctrl+Enter。输出区以 模块 / 命令 标签 + 格式化 JSON 显示应答，并带时间戳。
普通
tcp:// 裸流没有 IPC 帧头，不能用于设备命令；请使用 ipc://。
常用设备命令
| 命令 | 说明 |
|---|---|
{"module":"sys","cmd":"ping"} | 连通性测试 |
{"module":"sys","cmd":"help"} | 列出可用 module/cmd |
{"module":"ptz","cmd":"get"} | 读取云台位置 |
{"module":"ptz","cmd":"set","params":{"pan":1,"tilt":0}} | 手动转动 |
{"module":"ptz","cmd":"calib"} | 自动校准 |
{"module":"osd","cmd":"1"} / "0" | 开启/关闭 AI 目标框 OSD |
使用提示
- RTSP 地址需以
rtsp://开头；设备命令请用ipc:// - 本地 MP4/MKV 适合帧列表码流分析；直播流无总时长时不显示进度条
- 单视频：Frame List 滚到底选中最后一帧或按 ↓ 继续加载
- 单视频：暂停时可拖动进度条预览任意位置，松手后仍保持暂停
- 多视频：先点击要分析的窗口再使用 Frame List；仅一路有声音
- 编码叠加 仅在单视频标签可用；4K 为 CTU 级 QP
- YOLO / PID / LQR / MPC：默认隐藏，从 算法 菜单勾选后显示
- 控制器：可连本地/网络流读 SEI
PTZ_POS画曲线；连接期间本地仿真禁用 - SEI 检测框：勾选柱状图「SEI叠加」后才会画框