概述
XPlayer 是基于 Qt 6 与 FFmpeg 的视频播放器，面向码流分析与 IPC 设备调试。支持本地文件、RTSP/RTMP/HTTP(S) 网络流，以及 ipc:// 设备复用流（视频与 JSON 命令共用一条 TCP）。
主要能力包括：NALU 帧分析、H.264/H.265 编码结构叠加、SEI AI 检测框绘制、多窗口独立预览、YOLO 目标检测、云台控制与设备 JSON 命令、图片/YUV 查看等。
主标签页
主视频区顶部有五个标签，切换时会自动清理上一标签内容（停止播放、关闭输入等）。
| 标签 | 说明 |
|---|---|
| 单视频 | 单路播放 + NALU 分析 + 编码叠加 |
| 多视频 | 1 / 2 / 4 分屏，每路独立播放与分析 |
| 算法 | YOLO26 目标检测 |
| 图片 | 静态图片查看与像素拾取 |
| YUV | 原始 YUV 文件查看与分析 |
打开媒体
| 方式 | 说明 |
|---|---|
| File → Open... (Ctrl+O) | 打开本地媒体文件，支持多选 |
| File → Open Stream... | 输入 RTSP/RTMP/HTTP/HTTPS/ipc:// 等地址 |
| 拖拽 | 将文件或 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 + 自定义样式）
- 单视频标签下顶部工具栏：Open、叠加、量化、柱状图、AI 及算法、云台 下拉菜单
- Tools 菜单：重置视图、保存截图、云台、PID 调参、媒体信息、打开串流录制目录
- 帮助 菜单：关于 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 帧）
- 本地文件打开后直接播放（与单视频「先分析再播」不同）
算法检测
标签 算法 用于 YOLO26 目标检测。切换时右侧 NALU 面板自动隐藏，工作区全宽显示。
输入源
| 方式 | 说明 |
|---|---|
| 打开图片 | PNG / JPEG / BMP / WebP 等 |
| 打开视频 | MP4 / MKV / AVI 等 |
| RTSP/串流 | rtsp://、http://、rtmp:// |
操作
| 按钮 | 说明 |
|---|---|
| 检测当前帧 | 对当前图片或视频/流的一帧运行检测 |
| 实时检测 | 视频或 RTSP 上连续检测（约 30 fps） |
| 关闭 | 停止检测并释放输入 |
启动时自动从可执行文件目录向上查找 models/ 下的默认 ONNX（优先 yolo26n.onnx）。可调置信度阈值与输入尺寸（默认 640）。推理基于 OpenCV DNN（CPU）。
图片与 YUV
图片
- 文件 → 打开图片（Ctrl+I）或空状态点击
- 标尺、滚轮缩放、左键拖拽平移、像素拾取（RGB/BGR 等）
YUV
- 文件 → 打开 YUV...，需指定宽高与像素格式
- 支持标尺、缩放平移、像素拾取、直方图等
- 切换至其他主标签时会清空 YUV 视图
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
编码叠加（单视频）
仅在 单视频 标签时，顶部工具栏 叠加 / 量化 可用。
叠加（编码结构）
| 选项 | 说明 |
|---|---|
| 编码树单元 | 按 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；Tools → 云台 可快速切换
- 速度滑块 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://开头 - 本地 MP4/MKV 适合帧列表码流分析；直播流无总时长时不显示进度条
- 单视频：Frame List 滚到底选中最后一帧或按 ↓ 继续加载（勿在播放或暂停待恢复时依赖此操作）
- 单视频：暂停时可拖动进度条预览任意位置，松手后仍保持暂停
- 多视频：先点击要分析的窗口再使用 Frame List；仅一路有声音
- 编码叠加 仅在单视频标签可用；4K 为 CTU 级 QP
- IPC 设备：用
ipc://192.168.x.x打开可同时预览视频并发送 JSON 命令 - SEI 检测框：勾选柱状图「SEI叠加」后才会画框