使用手册 - FoxPlayer 文档

日常怎么用、常见操作怎么做

1. 界面总览

1.1 播放画面

程序启动后进入全屏无边框播放画面，鼠标自动隐藏。画面本身不显示按钮，操作靠手势、托盘或外部指令。节目单为空时显示提示页；未授权时显示授权页。

1.2 触控手势（桌面触摸屏 / Android）

区域	手势	作用
左侧 20%	双击	上一项
左侧 20%	上下滑	调音量
右侧 20%	双击	下一项
右侧 20%	上下滑	调音量
底部 20%	左右滑	视频调进度（图片无效）
中央区域	单击	暂停 / 继续
右下角	连续点 5 下	打开调试面板（圆环显示剩余点击时间）

调试面板可查看播放状态、进度、音量、日志，并提供播放/暂停、上/下一项、音量、重播等按钮；再次点击关闭。

1.3 遥控器（Android TV / 电视盒子）

使用标准方向键遥控器即可完成日常操作，无需触摸屏：

按键	作用
上 / 下	音量 +5 / -5，长按可连续调节，屏幕显示音量指示器
左 / 右	上一个 / 下一个节目项
OK / 确定	暂停 / 继续
播放 / 暂停、上一曲 / 下一曲	与对应播放动作一致（取决于遥控器是否带媒体键）
菜单	打开 / 关闭调试面板（与 F12 等价）
返回	优先关闭调试面板；未打开面板时，2 秒内连按两次才退出程序

说明：

授权失效或节目单为空时，播放类按键会被屏蔽，避免误操作；音量键仍可用。
调试面板可通过遥控器「菜单」键、外接键盘 F12 或屏幕右下角 5 连击打开。
调试面板打开后，方向键在面板内的按钮之间移动焦点（白色边框为当前焦点），OK / 回车激活当前按钮。
面板底部除 4 个长按系统按钮外，还提供「关闭面板」按钮（单击即可关闭）；Android 终端在其右侧另有「系统设置」按钮，点击直接跳转安卓系统设置页。
遥控器上的音量键由系统处理，调的是设备媒体音量；App 内音量请用上 / 下方向键。

1.4 系统托盘（Windows / Linux）

单击托盘图标：显示/隐藏窗口
右键菜单：显示窗口、退出应用
点击窗口关闭按钮：只收进托盘，不退出播放

1.5 本机 Web 管理后台

浏览器访问 http://127.0.0.1:58000（局域网用 http://<终端IP>:58000）。页面如下：

路径	页面	需要登录	说明
`/login`	登录	-	默认 `admin / admin123`
`/authorize`	设备授权	否	显示机器码、粘贴授权码
`/monitor-play`	全屏监控播放	否	供另一块屏/浏览器观看当前播放
`/monitor`	仪表盘	是	当前播放项、状态、音量、节目单概况
`/playlist`	节目单管理	是	上传素材、排序、启停、默认项、播放模式
`/logs`	操作日志	是	按通道/指令/结果筛选，最多 500 条
`/auth-manage`	授权管理	是	机器码、到期时间、剩余天数、激活/清除
`/settings`	系统设置	是	端口、播放、推送、监视、转码、网络
`/docs`	API 文档	是	内置接口说明与示例

2. 素材管理

2.1 上传

在「节目单管理」页的素材区点击上传，可一次选多个文件。

允许扩展名：mp4、mkv、avi、mov、mp3、jpg、jpeg、png、webp、gif、bmp
单文件默认上限 5120 MB，可由配置项 max_upload_size_mb 调整
上传采用流式落盘，不把整个文件读进内存
文件名以 MD5 命名（如 3f2a….mp4），原始文件名单独记录并用于展示
视频自动读取时长，并在第 3 秒截取缩略图（*_thumb.jpg）；图片直接以自身作为缩略图
上传完成后通过 WebSocket 广播 files_changed，多个后台页面会同步刷新

2.2 删除

在素材列表删除文件时，程序会：

若正在播放该文件，先停止播放；
把节目单中引用该文件的条目设为 enabled=0（软禁用，不删行）；
删除 files_info 记录；
删除 media/ 下的物理文件。

因此删除后节目单不会留下「点了没反应」的坏条目。

3. 节目单管理

3.1 编排

拖拽调整顺序，保存时写入 sort_order
每项可单独启用/停用（enabled）
可指定一个「默认起始项」（is_default）；指定新项会自动取消旧项
播放模式：loop_one（单曲循环）/ loop_all（列表循环）；留空则跟随全局 default_play_mode
图片停留时长：按项设置，单位秒，入库时换算为毫秒
缩放模式：stretch（拉伸铺满）/ normal（原始比例）
批量替换：PUT /api/playlist/batch 会先清空再事务写入，适合整套内容切换
排序：PUT /api/playlist/order 接收 id 数组，按数组顺序重排

3.2 播放逻辑

从「默认项」开始；没有默认项则从第 1 项开始
loop_all：播完最后一项回到第 1 项
loop_one：当前项循环
视频之间尝试无缝预排队；若引擎未自动切换，5 秒兜底看门狗会显式切到下一项
解码错误：500 ms 后跳到下一项；连续跳过达到节目单总数则停止，避免无限空转
图片按 image_hold_time 停留，不参与进度跳转

4. 播放控制

4.1 后台控制

仪表盘提供播放/暂停、上/下一项、音量、重播、进度跳转。也可在「节目单管理」点击某一项直接播放。

4.2 外部指令

四个通道共用指令格式：

{"id":"","cmd":"setplay","params":{"file":"#1"}}

常用指令：

指令	参数	说明
`setplay`	`file` / `playlist_id`	切到指定文件；`#N` 表示节目单第 N 项（从 1 开始）
`play`	无 / `file` / `playlist_id`	无参数时按状态恢复；带文件时等价于 `setplay`
`pause` / `resume`	无	暂停 / 恢复
`replay`	无	重播当前项
`seek`	`mode` + `seconds` / `percent`	`absolute` / `relative` / `progress`
`volume`	`level` 0–100	设置音量
`next` / `previous`	无	下一项 / 上一项
`status`	无	返回状态与当前文件
`playlist`	无	返回节目单与当前索引

完整字段与响应见《FoxPlayer 集成与 API》。

5. 系统设置

卡片	主要内容	生效方式
服务与端口	`http_port`、`tcp_port`、`udp_port`、`ws_port`、各通道开关；网络信息（IP / 掩码 / 网关 / DNS，只读）	端口类重启应用
播放器设置	设备 ID、开机自启、媒体目录、`startup_volume`、`default_play_mode`、`image_hold_time`、`decoder_override`、音频直通	即时或下次播放
数据外发推送	`progress_http/tcp/udp_*` 推送开关与目标、推送内容开关	即时
监视设置	监视页布局（`monitor_`）、按钮显示（`btn_`）	即时
外设接口与扩展服务	外设与扩展相关开关	即时或重启
高级媒体转码	`player_use_transcoded`、`monitor_use_transcoded`、转码编码/码率/分辨率/帧率等	下次转码任务

端口类配置保存后不会立即改监听，需退出应用后重新启动；界面会给出提示。 修改密码不在系统设置里：点后台右上角管理员名字 → 「修改密码」。

6. 授权管理

「授权管理」页显示本机机器码（32 位十六进制）、授权状态、到期时间、剩余天数
激活：粘贴授权码（格式 Base64(payload).Base64(signature)）→ 保存
校验：机器码匹配 → RSA-2048/SHA-256 验签 → 到期时间
状态：有效 / 即将过期（≤30 天）/ 已过期 / 未授权
清除授权：删除 license.key，界面立即回到未授权状态
程序每 60 秒复查；授权过期或未授权时，播放画面会被全屏授权提示遮挡，且不加载节目单；恢复授权后自动重新加载并恢复播放

7. 操作日志

记录字段：指令、通道（http/ws/tcp/udp/pub）、时间、参数、结果
后台按通道、指令、结果筛选，最多返回最近 500 条
可一键清空
日志用于「谁在什么时候切了什么内容」的追溯，不记录视频内容本身

8. 数据与文件位置

内容	位置
数据库	数据目录 `foxplayer.db`（WAL 模式）
素材	数据目录 `media/`（可由 `media_dir` 改）
转码产物	`media/<原名>.transcoded.<扩展名>`
缩略图	`media/_thumb.jpg`
授权	数据目录 `license.key`
日志	数据目录 `logs/foxplayer.log`（5 MB 轮转）
Web 后台资源	程序内置 `web/` 或打包资源目录

数据目录由 path_provider 的 getApplicationSupportDirectory() 决定；Windows 通常为 %APPDATA%\com.foxplayer\foxplayer，以日志首行为准。

9. 日常维护建议

每周看一眼操作日志与 foxplayer.log，确认没有反复的授权失败、解码失败或端口占用
每月备份一次 foxplayer.db 与 media/；节目单与授权都在其中
素材总量接近磁盘上限前清理旧文件；删除素材会联动软禁用节目单
长期无人值守时保持 auto_start=true，并在系统电源设置中关闭「自动睡眠」
修改 control_secret 后，所有第三方调用方需同步更新 token，否则会收到 unauthorized