Peach: Local-first video metadata scraper and media manager.
外部播放器与 VR
本地播放器
Windows 或 macOS 上,在运行 Peach 的电脑打开作品详情,在详情上方选择「系统默认播放器」或检测到的播放器,再点同一行的「打开」。Windows 检测 PATH 和常见安装目录中的 PotPlayer、VLC、mpv;macOS 检测系统与用户应用目录中的 IINA、VLC、mpv。选择保存在当前浏览器;播放器接收原始媒体文件,网页播放在请求成功后暂停。
播放器菜单只列出当前部署支持且检测到已安装的程序,以及系统默认播放器。同一选择器还提供网络播放地址和 M3U 播放列表,供 Docker 和远程访问使用。在 Windows 上下载 M3U 后,可用系统默认播放器打开,或通过系统的「打开方式」选择播放器。播放器需要支持对应媒体格式、网络地址及 Peach 证书。
本地打开接口只对本机直接连接开放,拒绝转发请求;Docker 和无桌面部署不启动宿主机或容器中的应用。接口接受账本资产 ID 和固定播放器 ID,经媒体根目录授权后打开文件,不接受客户端指定程序或文件路径。STRM 使用网络播放地址或 M3U。
观看进度回传
从详情选定 mpv、VLC(Windows)或 IINA、mpv(macOS)打开时,Peach 跟踪这次播放,把观看记录写进网页播放器使用的同一组列:位置第一次前进时计一次播放(play_count、last_played),连续前进的时长累计进 play_seconds,大幅跳转计入 seek_count,最后位置写成 leave_ratio,放完记为 1。每 30 秒和播放器退出时各写一次。系统默认播放器和 PotPlayer 不回传。
| 播放器 | 通道 | 启动参数 |
|---|---|---|
| mpv | JSON IPC:Windows 命名管道,macOS Unix socket,名字随机 | --input-ipc-server=… |
| IINA | 经 iina-cli 透传给内置 mpv,读法同 mpv |
--mpv-input-ipc-server=… |
| VLC | Lua HTTP 接口的 requests/status.json,只听 127.0.0.1,端口和密码随机 |
--extraintf=http --http-host=127.0.0.1 --http-port=… --http-password=… |
Peach 每秒读一次位置、时长与暂停状态。播放器退出、断开、换成别的文件、mpv 进入空闲或 VLC 停止时结束跟踪;停下时离片尾不到 3 秒,或 mpv 报告文件放完,都按放完记录。同时最多跟踪 4 个播放器,每个最长 12 小时;启动后 15 秒内连不上进度接口就放弃。连不上、读失败或播放器异常退出时只是不记,不提示用户;已经看过的部分照常写入。Peach 关闭时先写下在跟踪的播放再退出。
续播位置在网页播放器里先读当前浏览器保存的位置,没有时才用 leave_ratio。在这个浏览器里看过的作品,外部播放器写入的位置不会改变网页续播点。
VLC 开启了「只允许一个实例」并已在运行时,新打开的文件交给已有窗口,HTTP 接口不会启动,这次播放不记录。
PotPlayer 取证
PotPlayer 只做了取证,没有接入,原因如下:
- 社区记录的做法是向 PotPlayer 窗口发送
WM_USER(0x0400)消息,wParam0x5004返回当前毫秒数,0x5002返回总时长。这不是官方公开接口。要查询当前文件名,PotPlayer 只能通过WM_COPYDATA回信,Peach 需要再建一个接收消息的窗口。 - 要把窗口对应到具体文件,只能用
/new强制新开实例,再按进程 ID 找窗口。用户在同一窗口里换片后,Peach 无法得知。服务进程须与 PotPlayer 在同一桌面会话;PotPlayer 以管理员身份运行时,UIPI 会拦截普通权限进程发出的消息。 - 本机 PotPlayer 的设置在注册表
HKCU\Software\DAUM\PotPlayerMini64。其中Positions存放窗口位置和大小,不是播放位置;Settings下也没有逐文件续播记录。默认播放列表%APPDATA%\PotPlayerMini64\Playlist\PotPlayerMini64.dpl是文本文件,只记录最后一个文件的playname=、playtime=和saveplaypos=,无法区分多次播放。playtime的单位和写入时机未取得。 SendMessage读数没有实测。启动 PotPlayer 会改写用户默认播放列表里的「上次播放」记录,因此没有在这台机器上执行。
网页画面旋转
播放器「设置 → 画面旋转」提供 0°、90°、180°、270°;0° 恢复原始方向。画面保持比例并适配播放器,控制条保持正向。切换清晰度、影院模式和全屏时继续适配。旋转只影响网页画面,不修改媒体文件或外部播放器设置。
旋转、播放速度、字幕选择与字幕外观按视频保存到服务端同一份记忆文件,详情、小窗和沉浸播放共用;刷新、重新打开或更换浏览器后恢复。设置 0°、正常速度或关闭字幕同样会保存,各部视频互不影响。WebVTT 内容与记忆文件放在数据目录的 state/player-subtitles/<视频标识>/,清单为 subtitles.json。Windows、macOS 和 Docker 共用此存储;Docker 需要持久挂载数据目录。已有字幕内容与选择直接沿用,浏览器已保存的字幕外观作为尚无外观记录的视频的初始值。播放记忆接口为 GET/PUT /api/player/memory?video=…,字幕接口共用同一份清单;更新仅合并提交的字段,不修改 ledger。
画中画入口在支持该 API 的浏览器中固定占位,媒体加载期间禁用。浏览器明确拒绝画中画时,入口保留不可用原因。浏览器声明 API 可用不能保证系统窗口可创建,限制及异常见 Picture-in-Picture API。
网络播放
本地或已挂载视频的作品详情共用一行播放器选择和「打开」按钮。选择网络播放方式后点击「打开」, 即可生成限时链接并下载 M3U。选择「网络播放地址 / VR」时,只显示可复制的地址。
| 选项 | 使用方式 |
|---|---|
| M3U 播放列表 | 用支持网络地址的外部播放器打开下载的 .m3u |
| 网络播放地址 / VR | 生成地址并显示,供 VR 等播放器使用 |
播放器选择只保存在当前浏览器。另一台设备需要能访问当前 Peach 地址;电脑上用 localhost
生成的地址不能供手机访问。HTTPS 使用项目证书时,外部设备也需要信任该证书。
播放链接有效期为 6 小时,Peach 重启后失效。链接只允许读取选中的资产,不包含本机盘符路径或 长期登录凭据。请求支持 HTTP Range,传输原始文件;解码能力、VR 投影方式由外部播放器决定。 生成链接和打开播放器不计作观看记录,也不能证明播放器已经起播。
协议与验证
签发接口 POST /api/external-playback?id=… 使用现有登录及同源检查。流和 M3U 端点验证
进程内密钥签发的单资产限时票据,每次读取仍经过现有媒体根目录检查。
播放地址的 origin 一并签名:优先使用通过同源检查的页面 Origin;无 Origin 的客户端使用已配置的
隧道入口或当前服务地址。M3U 使用该签名地址,代理转发的本机 Host 不会改写列表中的公网入口。
播放器程序不随 Peach 分发;进度回传只用 Python 标准库,无新增依赖。自动化验证覆盖票据、Range、 M3U 内容和页面交互,不替代真实设备的解码验收。
Windows 原生验证使用现有 ffplay、临时 HTTPS 服务与专用测试证书,播放 M3U 中的签名网络地址。 两秒 H.264 合成测试画面在关闭音频、隐藏输出时正常播放并退出,ffprobe 确认解码 20 帧; TLS 校验保持开启。该验证不覆盖本机播放器唤起或 VR 投影。
本地打开复用 Python 标准库的 Windows 文件关联 和 macOS 的 open。进程参数以数组传递,不经 shell。跨平台自动化覆盖调用参数和权限边界;系统关联、应用唤起及真实媒体解码需要在对应桌面系统验证。