SoftPlayer 使用手册

在目标机上完成解压并确认运行环境满足要求。

1. 确认运行机器为 Windows 10/11 x64 系统。
2. 将 SoftPlayer 压缩包解压到固定目录，例如 C:\SoftPlayer\。
3. 解压后确认目录中存在 SoftPlayer.exe、appsettings.json、SoftPlayerMedia\ 子目录结构。
4. 如需播放 8K 视频，确认机器有支持硬件解码的独立显卡（GTX 1060+ 或同等）；4K 及以下集成显卡可用。

• 解压目录中可以看到 SoftPlayer.exe。
• SoftPlayerMedia\ 目录已自动预创建，包含 Video、StandBy、Audio、PPT 等子目录。

• 建议把 SoftPlayer 放到固定路径，因为媒体文件、日志和授权状态都保存在程序同级目录。
• SSD 存储读取速度建议 200MB/s+，4K 视频更流畅。

确认程序正常启动并完成首次引导。

1. 双击 SoftPlayer.exe 启动程序（无需管理员权限）。
2. 首次启动时，程序会用默认浏览器打开快速上手.html 引导页（仅首次，后续启动不再弹出）。
3. 引导页阅读完毕后，在浏览器中访问 http://localhost:8766/ 进入管理台。
4. 在管理台仪表盘中确认播放器状态显示正常，版本号和授权状态可见。

• 浏览器成功打开管理台（http://localhost:8766/），仪表盘显示播放器状态。
• 管理台顶部显示当前版本号和授权状态。

如需禁用首次启动引导，在 appsettings.json 中将 System.ShowQuickStartOnFirstRun 改为 false。

通过 UDP 成功控制播放器，确认控制链路通畅。

1. 把一个视频文件（例如 test.mp4）放到 SoftPlayerMedia\Video\ 目录。
2. 打开 PowerShell，执行以下命令发送播放指令：
3. $udp = New-Object System.Net.Sockets.UdpClient
4. $data = [System.Text.Encoding]::UTF8.GetBytes("video:test.mp4")
5. $udp.Send($data, $data.Length, "127.0.0.1", 7600)
6. $udp.Close()
7. 观察 SoftPlayer 窗口是否开始播放该视频。

• SoftPlayer 窗口开始播放指定视频文件。
• 管理台日志页可以看到收到命令的记录。

• 视频文件放错目录（应放到 SoftPlayerMedia\Video\，而不是程序根目录）。
• 端口写错（默认 7600，注意不是管理台的 8766）。

掌握命令格式，理解成功和失败响应的区别。

1. 命令格式：命令名:参数，例如 video:show.mp4 或 volume:80。
2. 无参命令直接发命令名，例如 play: 或 stop:（冒号可省略）。
3. 成功响应格式：OK:原始命令，例如 OK:video:show.mp4。
4. 失败响应格式：ERR:原始命令:错误信息。
5. 媒体文件路径只需写文件名（不含子目录路径），播放器会自动在对应子目录查找：video: 命令在 SoftPlayerMedia/Video/ 下查找。

• 发送命令后能收到 OK 开头的响应，说明命令格式正确且被执行。
• 收到 ERR 响应时，错误信息会指出具体原因（文件不存在、格式错误等）。

如需指定子目录，可用斜杠分隔：video:subfolder/video.mp4 会在 SoftPlayerMedia/Video/subfolder/ 下查找。

掌握视频播放相关的全部命令。

1. 播放本地视频：video:文件名.mp4（在 Video 目录查找）。
2. 播放网络视频流：webvideo:URL（支持 HTTP/HTTPS/RTSP/RTMP/UDP 流）。
3. 播放/恢复：play:（恢复暂停的媒体）。
4. 暂停：pause:（暂停当前媒体）。
5. 停止并切回待机：stop:（回到欢迎画面/待机循环）。
6. 彻底停止黑屏：stoped:（关灯节电语义，纯黑屏）。
7. 重新播放当前媒体：replay:。
8. 进度控制：seek:毫秒数（跳转到指定位置）、forward:（前进10秒）、backward:（后退10秒）。
9. 播放速度：speed:1.5（支持 1.5/2.0 等倍速）。

• video: 命令执行后播放器开始播放该文件。
• stop: 命令执行后返回待机画面（如果配置了待机文件）。

• 展厅长时间待机建议使用 standby: 命令切到待机文件循环，而不是 stoped: 黑屏（黑屏可能让观众认为设备故障）。
• stop 与 stoped 语义不同：stop 切回欢迎画面，stoped 是纯黑屏。

掌握音量调节和音频播放控制命令。

1. 设置音量（0-100）：volume:80（直接设置到指定值）。
2. 音量加 10%：volup:（每次调用增加 10%）。
3. 音量减 10%：voldown:（每次调用减少 10%）。
4. 静音切换：mute:（在静音/非静音之间切换）。
5. 明确开启静音：muteon:。
6. 明确取消静音：muteoff:。
7. 播放音频文件：audio:文件名.mp3（在 SoftPlayerMedia/Audio/ 查找）。
8. 停止音频：audiostoped:。

• volume:50 命令执行后，播放器音量降到 50%。
• mute: 命令可在有声和静音间切换。

掌握循环列表、PPT 翻页和网页加载命令。

1. 循环播放列表：listloop:文件1.mp4;文件2.mp4;文件3.mp4（用分号分隔多个文件）。
2. 顺序播放（播完停止）：liststop:文件名。
3. 列表下一曲：next:，上一曲：prev:。
4. 打开 PPT 全屏播放：ppt:文件名.pptx（在 SoftPlayerMedia/PPT/ 查找）。
5. PPT 翻页：ppt:next（下一页）、ppt:prev（上一页）、ppt:home（第一页）、ppt:end（最后一页）。
6. PPT 跳页：ppt:goto-5（跳转到第5页）。
7. PPT 自动翻页：ppt:auto-5-文件名.pptx（每5秒自动翻页）。
8. 加载网页：web:URL（全屏显示指定网页）。

• listloop: 命令执行后播放器开始循环播放列表中的文件。
• ppt:next 执行后 PPT 翻到下一页。

• PPT 文件需提前放入 SoftPlayerMedia/PPT/ 目录。
• 如果 PPT 是 PDF 格式，会退化为查看器窗口加按键模拟翻页。
• 展厅常用循环播放场景建议用 listloop 而不是手动逐个发命令。

了解遮罩和系统级命令的用法。

1. 显示遮罩：openmask:（在视频上叠加遮罩层）。
2. 隐藏遮罩：closemask:。
3. 设置播放结束行为：endbehavior:Stop（停止）/ Loop（循环）/ Standby（切待机）。
4. 获取版本号：version:（回执中包含当前版本信息）。
5. 重启播放器：restart:（远程重启播放器进程）。

• openmask: 执行后视频上出现遮罩覆盖层。
• version: 执行后收到包含版本信息的回执。

了解媒体文件的正确存放位置。

1. SoftPlayerMedia/Video/ — 放置视频文件（.mp4/.mkv/.avi 等），video: 命令在此查找。
2. SoftPlayerMedia/StandBy/ — 放置待机文件，standby: 命令和开机默认播放使用此目录。
3. SoftPlayerMedia/Audio/ — 放置音频文件（.mp3/.wav/.flac 等），audio: 命令在此查找。
4. SoftPlayerMedia/BackgroundAudio/ — 背景音频目录，启用后自动循环播放。
5. SoftPlayerMedia/PPT/ — 放置 PPT/PDF 文件，ppt: 命令在此查找。
6. SoftPlayerMedia/Mask/ — 放置遮罩图片，openmask: 命令使用此目录。
7. SoftPlayerMedia/Thumbnail/ — 缩略图缓存目录（自动生成，无需手动放文件）。

• 将视频文件放到 Video/ 目录后，用 video:文件名 命令可以正常播放。
• 目录结构在首次启动时自动创建，无需手动建目录。

通过浏览器管理台完成媒体文件的日常管理。

1. 在浏览器中打开 http://播放器IP:8766/ 进入管理台。
2. 点击顶部导航切换到「文件」标签。
3. 在文件管理页面选择目标目录（Video / StandBy / Audio / PPT 等）。
4. 点击「上传」按钮选择文件，或将文件拖拽到上传区。
5. 支持创建文件夹、重命名、删除文件/文件夹、下载文件等操作。
6. 文件最多支持 3 层子目录深度，上传时选择当前目录即可。

• 上传完成后在文件列表中可以看到新文件。
• 通过 video:文件名 命令可以成功播放刚上传的文件。

• 管理台使用 Basic Auth 认证，用户名和密码在 appsettings.json 中配置。
• 单文件上传限制默认为 500MB，可在配置文件修改。
• 现场运维人员无需 RDP 远程桌面即可通过管理台上传替换内容。

了解试用期规则，合理规划授权时间。

1. 首次运行 SoftPlayer 后自动进入 30 天试用期。
2. 试用期间全功能可用，包括高分辨率播放和所有 UDP 命令。
3. 在浏览器管理台「仪表盘」可查看剩余试用天数。
4. 试用期结束后，需要导入正式授权码才能继续使用。

• 管理台仪表盘显示当前为试用状态及剩余天数。
• 试用期内命令控制正常响应，无功能限制。

• 试用期建议在正式项目交付前完成测试和验收。
• 临近试用期结束时及时联系购买，避免现场授权到期影响展厅运营。

根据实际展厅分辨率需求选择合适的授权档位。

1. 标准版授权：支持最高 4K（3840×2160）分辨率输出。
2. 专业版授权：支持最高 16K（15360×8640）分辨率输出。
3. 4K 播放硬件要求：Intel i3+ / 8GB 内存 / 集成显卡即可（无需独立显卡）。
4. 8K 播放硬件要求：Intel i5 第8代+ / 16GB 内存 / GTX 1060+。
5. 16K 播放硬件要求：Intel i7+ / 32GB 内存 / RTX 3070+。
6. 如不确定所需档位，可先试用确认实际分辨率需求后再购买。

• 明确项目所用显示设备的最大分辨率，对应选择标准版或专业版。
• 采购前确认服务器硬件配置满足对应分辨率的最低要求。

无独立 GPU 的电脑可以播放 4K 及以下视频（程序自动选择软件解码），但播放 8K/16K 需要符合条件的独立显卡。

完成授权码的获取与导入，将试用版升级为正式版。

1. 在浏览器管理台「仪表盘」页面找到「设备 ID」字段，复制该 ID。
2. 将设备 ID 提供给供应商，说明所需授权档位（标准版/专业版）。
3. 收到授权码后，在管理台「配置」标签中找到「授权管理」区域。
4. 将授权码粘贴到输入框，点击「导入授权」。
5. 导入成功后，仪表盘的授权状态从「试用」变为「标准版」或「专业版」。

• 管理台仪表盘授权状态显示为正式版（标准版或专业版）。
• 高分辨率视频播放不再受分辨率限制。

• 把授权码应用到错误的设备（授权码与设备 ID 绑定，换机后需重新申请）。
• 试用期已过才开始申请授权，导致展厅停播等待授权。

恢复 UDP 命令控制链路。

1. 确认 SoftPlayer 正在运行（任务栏或任务管理器中可见）。
2. 确认发送的端口与 appsettings.json 中 Network.UdpPort 配置一致（默认 7600）。
3. 检查 Windows 防火墙是否放行了 UDP 7600 端口入站规则。
4. 如果启用了 IP 白名单（IpWhitelistEnabled: true），确认发送方 IP 在 AllowedIps 列表中。
5. 在管理台「日志」标签查看是否有命令接收记录，确认命令是否到达播放器。

• 管理台日志中出现命令接收记录，说明 UDP 通道正常。
• 发送 volume:50 命令后播放器音量变化。

• 局域网测试时先用 127.0.0.1（本机）验证，排除网络问题后再换实际 IP。
• 如需从 SoftControl 发命令，确认 SoftControl 的 UDP 指令协议和端口与 SoftPlayer 配置一致。

排查并解决媒体文件播放失败的问题。

1. 确认视频文件确实存放在 SoftPlayerMedia\Video\ 目录（不是程序根目录）。
2. 文件名区分大小写，确认命令中的文件名与实际文件名完全一致（包括扩展名）。
3. 如果文件在子目录，命令应包含相对路径：video:subfolder/video.mp4。
4. 在管理台「文件」标签浏览目录，确认文件确实存在。
5. 如果文件格式特殊，查看管理台日志中的错误信息确认 VLC 是否支持。
6. 尝试用 VLC 播放器在本机直接打开同一文件，排除文件本身损坏的问题。

• 管理台文件列表中能看到目标文件。
• 命令中的文件名与文件列表中显示的完全一致。

• 命令中写的文件名包含中文空格或全角字符，导致找不到文件。
• 文件扩展名大小写不匹配（如命令写 .MP4 但文件实际是 .mp4）。

解决高分辨率视频播放性能问题。

1. 首先确认当前授权档位：标准版仅支持 4K，专业版支持 16K。
2. 检查显卡是否支持硬件解码（GTX 1060+ 或同等，8K 需要）。
3. 在任务管理器「性能」标签查看 GPU 解码占用率，如果 GPU 占用率接近 100% 说明性能瓶颈在显卡。
4. 检查磁盘读取速度是否满足要求：4K 需 25-50 Mbps，8K 需 80-100 Mbps，16K 需 200+ Mbps。
5. 建议将高分辨率视频文件存放在 SSD 上，避免 HDD 导致的读取瓶颈。
6. 如需调整解码参数，查阅程序目录中的内置文档（docs\用户手册.html）获取 VLC 参数说明。

• 授权档位与需要播放的分辨率匹配。
• 硬件配置满足对应分辨率的最低要求。

恢复浏览器管理台的访问。

1. 确认 SoftPlayer 正在运行。
2. 本机访问用 http://localhost:8766/ 先排除网络问题。
3. 检查 appsettings.json 中 HttpMonitor.Enabled 是否为 true 且端口为 8766。
4. 检查 Windows 防火墙是否放行 TCP 8766 端口。
5. 如果端口被其他程序占用，在 appsettings.json 中修改 HttpMonitor.Port 为其他端口后重启。

• 浏览器可以访问 http://localhost:8766/ 并显示管理台界面。
• 管理台「仪表盘」显示播放器运行状态。