软件介绍

每个软件做什么，适合什么现场

1. 它是什么

FoxPlayer 是一个面向大屏终端的本地媒体播放器。它运行在终端电脑上，把节目单里的图片和视频按顺序放到屏幕上：启动即全屏、无边框、隐藏鼠标，播放期间阻止系统休眠；关闭窗口只收进系统托盘，不退出播放。

它由三部分组成，但只以一个程序交付：

• 播放内核：基于 Flutter + FVP（libmpv），默认解码优先级 MFT,D3D11,FFmpeg，负责视频/图片解码、进度、音量、缩放与循环。
• 节目单调度：读取数据库中的节目单，决定从哪一项开始、下一项是谁、图片停多久、循环方式；视频之间尽量无缝衔接，失败自动跳过。
• 本机 Web 管理后台：Vue 3 构建，随程序内置在 58000 端口，提供仪表盘、节目单、操作日志、授权管理、系统设置与 API 文档六个页面。

除此之外，它还开放四个控制通道：HTTP（58000）、TCP（58001）、UDP（58002）、WebSocket（58003）。四条通道共用同一套指令契约，中控或第三方系统可以用任意一种方式切换内容、查询状态。

2. 能力边界

能做什么

• 播放本地图片与视频，支持图片/视频混合节目单
• 全屏、无边框、隐藏鼠标；播放期间防休眠；关机重启后自动回到播放
• 开机自启（可在设置中开关）；关闭窗口最小化到托盘
• 节目单：拖拽排序、单项启停、设默认起始项、单曲/列表循环、图片停留时长、拉伸/原始比例
• 素材：网页上传、自动识别图片/视频、读取时长、生成缩略图、MD5 命名防重名、删除时联动停播与软禁用
• 本机触控手势：左/右区双击切上/下一项、左右区上下滑调音量、底部横滑调进度、中央单击暂停/继续、右下角连点五下打开调试面板
• 自动转码：对浏览器不友好的视频生成 *.transcoded.*，监视页优先使用转码文件
• 四通道控制：切歌、播放、暂停、恢复、重播、跳转、音量、上/下一项、状态查询、节目单查询
• 认证与授权：JWT 登录、PBKDF2 密码、登录限流、机器码绑定授权、授权到期提醒与暂停
• 操作日志：记录指令、通道、参数、结果，后台可筛选最近 500 条

明确不做什么

• 不做云端内容分发：没有中心内容库、没有远程下发节目单、没有多终端同步。每台终端的内容各自管理；需要统一管控时由上层系统调用四通道实现。
• 不展示网页/信息页：这是 FoxDisplay 的职责。
• 不管理系统电源、键鼠、进程：这是 FoxAgent 的职责。FoxPlayer 只提供关机/重启/退出三个系统指令。
• 不做直播流与 DRM：定位是本地文件播放，不承担 RTMP/HLS 拉流、版权加密、广告插播。
• 不做多用户权限体系：只有一个管理员账号，没有角色与按人分权。
• 不保证所有编码格式都能播：能否播放取决于本机解码器；遇到不兼容视频应使用转码功能或先转成 H.264/AAC MP4。

3. 与其他 Fox 软件的关系

需要「让屏幕播一段视频」用 Player，需要「让机器自己重启」用 Agent，需要「展示一个网页」用 Display。它们可以装在同一台机器上，各司其职、互不越界；同机部署时注意四个端口不要与其它软件冲突。

4. 适用与不适用

适合

• 展厅、门店、酒店大堂、会议室门口等需要「开机就有画面」的固定大屏
• 内容以本地图片/视频为主，更新频率不高、可由现场或运维通过浏览器上传
• 局域网内需要中控/信息发布系统按指令切换内容的场景
• 单机离线运行、不希望依赖公网的场景
• 需要按机器授权、能控制部署范围的交付项目

不适合

• 需要中心化内容库、几百台终端统一排期与远程下发的场景（应加一层内容管理/信息发布系统）
• 主要展示网页、H5、仪表盘（应使用 FoxDisplay 或 FoxKiosk）
• 需要直播拉流、DRM、广告精准投放的场景
• 需要多用户、多角色、审计分权的场景
• 希望「装上就能被公网任意控制」的场景：默认控制通道是开放的，正式部署必须配置 control_secret 并改默认密码

5. 常见误解澄清

1. 「Web 后台是云平台」 —— 不是。后台随程序内置在本机 58000 端口，数据存在本机数据库与 media/ 目录；断网照常使用，换一台电脑访问不到另一台的内容。
2. 「同一局域网谁都能控制」 —— 默认确实开放，这是为了现场快速联调；一旦在系统设置里填写 control_secret，TCP/UDP/WebSocket 与公开 HTTP 控制接口都必须携带匹配 token，否则返回 unauthorized。正式交付必须配置。
3. 「节目单删了，文件也没了」 —— 删除节目单项只删编排记录；删除素材才会删物理文件，并先把节目单中对应项软禁用（enabled=0），不会留下指向空文件的条目。
4. 「授权码可以复制到另一台机器」 —— 不行。授权码内含机器码，机器码由网卡名、主机名、系统版本与 CPU 核数计算得出，换机即失效。
5. 「改了端口马上生效」 —— 不会。端口类配置保存后需重启应用；音量、播放模式、按钮显示等配置即时生效。
6. 「播放卡顿就是软件坏了」 —— 先看素材编码与码率。4K 高码率、HEVC 10bit 等格式在低配终端上可能解码吃力；可先转码为 H.264/AAC 再播，或调整解码优先级。

事实依据：main.dart、playlist_service.dart、command_service.dart、upload_routes.dart、license_service.dart

分享