screen_controller/用户操作指引.md

屏幕播放控制系统 · 用户操作指引

本指引面向展厅介绍员 / 运维人员，帮助你快速上手系统的日常使用。 技术部署相关内容请参见 README.md。

---

一、系统角色说明

本系统有两套界面，分别用于「管理」和「播放」：

界面	地址	使用者	用途
控制端（控制台）	http://<服务器IP>:5000/	展厅介绍员	管理设备、编排播放列表、上传媒体
播放端	http://<服务器IP>:5000/player?device_id=xxx	每块屏幕	按时间自动播放图片/视频

说明：<服务器IP> 指运行 main.py 的那台电脑的内网 IP（如 192.168.1.100）。 控制端和播放端可以运行在不同设备上，只要在同一局域网即可。

---

二、首次使用流程

1. 启动服务  →  2. 打开控制端  →  3. 创建设备  →  4. 上传媒体
   →  5. 编排播放列表  →  6. 各屏幕打开播放端  →  7. 日常维护

步骤 1：启动服务

在服务器上执行：

python main.py

看到 屏幕控制系统已启动： http://0.0.0.0:5000/ 即表示成功。

步骤 2：打开控制端

在任意同一局域网的电脑/平板浏览器中访问：

http://<服务器IP>:5000/

步骤 3：创建设备

1. 点击左侧「+ 新增」按钮，系统自动生成一个设备（如 d1）。
2. 在右侧「设备名称」填写便于识别的名字（如「入口主屏」）。
3. 点击「保存设备信息」。

每块实体屏幕对应一个设备，设备 ID（如 d1）将在播放端地址中使用，请勿重复。

步骤 4：上传媒体文件

1. 在页面下方「媒体库」区域点击「上传媒体」。
2. 选择本地图片（png/jpg 等）或视频（mp4/webm 等）。
3. 上传成功后文件出现在媒体库中，可点击「使用」直接加入当前设备的播放列表。

也可不通过媒体库，手动在播放列表中填写 static/ 下的文件路径。

步骤 5：编排播放列表

在「播放列表」区域：

1. 点击「+ 添加条目」新增一条播放内容。
2. 填写每条内容的参数：

参数	说明	示例
类型	图片 / 视频	image
路径	媒体在 static/ 下的访问地址	/static/video1.mp4
开始时间	该内容开始播放的时间（本地时间）	2026-08-24T16:32
时长(秒)	仅图片有效，到时自动切换	10

3. 多条内容按「开始时间」从早到晚自动排序播放。
4. 编辑完成后点击「保存播放列表」。

步骤 6：各屏幕打开播放端

在每块展示屏幕的浏览器中访问对应地址（设备 ID 对应步骤 3 的值）：

http://<服务器IP>:5000/player?device_id=d1

建议按 F11 进入全屏，并固定该页面不关闭。

步骤 7：日常维护

• 修改配置后无需重启播放端：播放端每 30 秒自动拉取最新配置。
• 紧急情况可手动刷新播放端页面（F5）立即生效。

---

三、常见操作场景

场景 A：临时插播一段视频

1. 控制端 → 媒体库「上传媒体」上传视频。
2. 播放列表「+ 添加条目」→ 类型选视频 → 路径选刚上传的文件 → 开始时间设为「现在或稍后」。
3. 保存。对应屏幕会在到点后自动播放。

场景 B：更换某块屏幕的全部内容

直接在控制端选中该设备，清空或重新编排播放列表后保存即可。

场景 C：新增一块屏幕

1. 控制端「+ 新增」创建设备，记住其 ID。
2. 新屏幕浏览器打开 /player?device_id=新ID。
3. 编排该设备播放列表并保存。

场景 D：图片轮播展示

将多条图片条目依次排列，每条设置合适的「时长(秒)」，系统会按时间顺序、各自展示设定秒数后切换。

---

四、播放端状态说明

播放端页面右下角会显示当前状态，含义如下：

状态文字	含义
正在初始化...	正在从服务端获取配置
即将播放: xxx @ 时间	已排到下一条，正在倒计时
正在播放: xxx	当前正在展示该内容
当前没有待播放内容	配置中所有条目的开始时间都已过去
获取配置失败：设备不存在	device_id 在配置中找不到，请核对
请在 URL 中指定 device_id...	打开播放端时未带 ?device_id=，请补全

播放端右上角有时钟，用于核对本地系统时间是否与标准时间一致（播放以屏幕本机时间为准）。

---

五、注意事项与排错

1. 时间同步：各屏幕设备的系统时间应保持一致（建议开启网络时间同步），否则定时播放会偏差。
2. 访问地址：播放端必须用服务器内网 IP 访问，不能用 localhost（localhost 只指向本机）。
3. 自动播放限制：部分浏览器禁止带声音的视频自动播放，展厅设备建议在浏览器设置中允许自动播放，或保持页面在前台。
4. 媒体文件：上传的视频建议控制在合理体积，避免网络传输卡顿；文件存于 static/ 目录。
5. 配置备份：config.json 保存了全部设备与播放列表，定期备份该文件以防丢失。

---

六、快捷键速查

操作	快捷键
浏览器全屏（推荐播放端使用）	F11
刷新播放端立即生效	F5
控制台保存	页面内「保存」按钮

---

如遇到本指引未覆盖的问题，请查阅 README.md 的「常见问题」章节。