HUB
Sign inSign up

passport888/submini

By passport888

•Updated 4 days ago

为初代 iPad mini(iOS 9)准备的极简 Subsonic 播放器

Image
0

4.5K

passport888/submini repository overview

⁠submini

为初代 iPad mini(iOS 9.3.5 的 Safari)准备的极简 Subsonic 播放器。

现代前端框架(Vue/React + ES6)在这台机器的 Safari 上跑不起来,所以这个项目的页面是手写 ES5 单文件:没有构建步骤、没有框架、没有外部资源。服务端做三件事:托管这个页面、把 /rest/* 反向代理到 Subsonic 服务端(Navidrome 等),让页面与 API 同源绕开老浏览器的 CORS 限制;保存连接配置;并在转发时注入鉴权参数。音频流的 Range 请求由代理原样透传,拖进度条靠它。

⁠截图(初代 iPad mini 实机)

全屏播放器(Walkman 磁带机 + 播放队列):

全屏播放器

曲库随机页 + 底部迷你播放条:

曲库与迷你播放条

装框上桌(平时就立在桌上:播歌时是播放器,停播几分钟后自动切换成画框屏保):

装框实机:播放中

装框实机:屏保画作

⁠运行

镜像由 GitHub Actions 在打 v* 标签时构建,推送到 Docker Hub(passport888/submini)与 GHCR。家里部署只需拉镜像:

mkdir -p data && sudo chown 65534:65534 data   # 容器以 nobody(65534) 运行,数据目录要归它
docker compose pull
docker compose up -d

compose 用的是 host 网络模式:Docker 默认网桥只有 IPv4,上游如果是纯 IPv6 地址(如公网 AAAA-only 域名)容器里会连不上;host 模式下容器直接用宿主机的网络栈,IPv6 照常,9898 端口也直接落在宿主机上。

然后打开 http://<家里服务器>:9898,第一次打开会看到连接设置表单:填服务器地址(如 http://192.168.1.10:4533)、Subsonic 用户名和密码,点「连接并保存」。后端会先向服务器验证一次,成功才保存;之后任何设备打开这个页面都直接进播放器,不用再输。

本地构建也可以:docker build -t submini .,或直接 go run .(见下文)。

⁠配置与数据

连接信息存在后端的 SQLite 数据库里(submini.db),compose 把它挂在工作目录的 ./data 下(容器内 /data),升级镜像不丢,备份也方便。存的是 Subsonic 的 token 和 salt,不是密码原文——密码只在提交表单时用一次,算完 token 就丢弃。点页面右上角「退出」会清掉已保存的连接,回到设置表单。

环境变量只剩两个基础设施项:

变量默认说明
LISTEN:9898监听地址
DATA_DIR.(镜像里是 /data)submini.db 所在目录

注意:设置接口(/api/*)本身没有鉴权,这是给可信局域网用的家用小工具,别把 9898 端口直接暴露到公网。

⁠后端兼容性

submini 对后端的要求只有一个:对方实现 Subsonic REST API。页面和代理实际用到的端点是 ping、getPlaylists / getPlaylist、getAlbumList2、getAlbum、getArtists / getArtist、getRandomSongs、search3、getCoverArt、stream,以及队列同步的 getPlayQueue / savePlayQueue;鉴权用 Subsonic 标准的 token+salt(t = md5(密码 + s))。

  • Navidrome:开发和日常使用都基于它,全功能实测。
  • Subgram(playwjj/subsonic-telegram⁠,一个把 Telegram 当存储的 Subsonic 服务端):上面这些端点它全部实现,连接方式相同——设置表单里填它的地址和账号即可。两个差别注意一下:一是它不做转码,stream 的 format=mp3 参数会被忽略、直接返回导入时的原文件,所以音频本身要是 iPad 能播的 MP3/AAC(它受 Telegram 限制单文件不超过 20MB,导入的本来也以这些格式为主);二是它单用户,账号就是部署时设定的那个。
  • 其他 Subsonic 兼容服务端(Subsonic、Airsonic、Gonic 等)理论上同样可用,但没有逐一实测;个别端点缺失时对应功能会降级,例如没有 getPlayQueue / savePlayQueue 时,打开页面后的队列恢复会退回本机 localStorage 那一份。

⁠功能

  • 歌单 / 专辑(最新)/ 歌手 / 随机歌曲 / 搜索(歌曲·专辑·歌手)
  • 连续播放:点任意一首,所在列表整列连播
  • 随机播放:播放条上的 🔀 开关,打开后在当前队列里乱序连播;另有「随机」页签随机抽 50 首
  • 上一首/下一首,进度条可点选拖动
  • 没有封面的专辑/歌曲统一显示磁带占位图(web/icons/cover-placeholder.jpg);Navidrome 自带的无封面占位图是 WebP,iOS 9 解不了,后端代理会把它换成这张 JPEG
  • 封面加载走页面内一条全局队列,同一时刻最多 4 张在途:歌手页近两千张封面若一口气全发,会把 iOS 9 每主机的几条连接堵死几分钟,之后打开的任何页面都跟着没图。队列先进先出,切走的页面其待加载封面自动作废,单张卡住 10 秒自动跳过;列表行封面滚动到附近才入队;封面尺寸统一为 100/300 两档,避免同一张图重复要多个尺寸。歌手页每次只渲染 100 位,点「显示更多」续载。代理层另把真实封面缓存在内存里(上限 32MB)并落盘到数据目录(上限 64MB),下发一周浏览器缓存头:同一张图只问 Navidrome 要一次,容器重启、升级后封面也还是热的
  • 播放请求带 format=mp3:Navidrome 会把 FLAC 等格式实时转码,老 Safari 只认 MP3/AAC 也能放
  • 添加到主屏幕:iPad 上用 Safari 打开 → 分享 →「添加到主屏幕」,图标(沿用 subgram 的随身听图标)、启动图、全屏模式都已备好,点开就是一个独立 App 的样子
  • 全屏播放界面:打开就是全屏的大随身听,背景是从当前封面取色生成的渐变(canvas 采样 16×16 像素,换歌时淡入淡出、播放时缓慢漂移),播放键、进度条、正在播放的高亮也随封面变色;首次打开会自动装载随机歌曲填满队列(不自动播放,按播放键开始);带单曲循环与「换一批」(随机歌整表替换当前队列,正在播的歌不中断)
  • 播放状态自动保存与恢复:队列、当前歌曲和进度一方面存入浏览器本地(换歌/暂停/拖动时存,播放中每 5 秒存,切后台时再存),一方面同步到 Subsonic 服务端自带的播放队列(savePlayQueue,最多每 15 秒一次、切后台立即推)。重开时优先读服务端队列,其次本地存档:换浏览器、换设备打开都是同一个队列同一进度。iOS 9 的桌面图标应用退出即被系统回收、音频必停且页面重载——这点网页无解(Safari 标签页能后台播放,是因为 Safari 本身常驻);但重开图标会精确恢复到被回收前的那首歌、那一秒,点一下播放键即接着播
  • iPad 横屏:全屏播放器一屏放下,左侧随身听 + 信息 + 控制,右侧是独立滚动的播放队列面板
  • 收起后是一行约 72px 的迷你播放条:封面缩略图、歌名、上一首/播放/下一首,进度为顶部细线(可点、可拖动)
  • 列表:专辑为封面网格,专辑/歌单/随机页带大封面头部和「播放全部」「随机播放」按钮,正在播放的歌显示跳动的均衡器图标
  • 返回不重载:每层列表连同滚动位置、已展开的「显示更多」原样保留,点「返回」直接放回;切页时立即清空成骨架占位,迟到的旧请求结果自动丢弃,不会串页
  • 歌曲行右侧「⋯」:下一首播放(随机模式下也优先)、加到队列末尾、查看专辑、查看歌手;全屏播放器里点歌手名/专辑名直接跳转
  • 播放队列:已播部分变暗,每行可移除(带撤销);「换一批」也可撤销
  • 专辑页可切排序(最新 / 最近播放 / 最常播放 / 随机 / A–Z),每次 60 张、可继续加载;歌手页右侧 A–Z 索引条,点按或拖动跳到对应字母
  • 右上角 ⚙ 收纳版本号与「退出登录」,退出需连点两次确认

⁠iOS 9 约束(改页面时注意)

  • 只用 ES5:不用箭头函数、let/const、模板字符串、Promise、fetch(用 XMLHttpRequest)
  • 布局只用 float/block/inline-block/absolute,不用 flex/gap/grid
  • 可以用:CSS 渐变、transition、@keyframes(加 -webkit- 前缀)、-webkit-backdrop-filter、:not()、canvas getImageData(封面走同源 /rest 代理,不会被污染)
  • 别对大面积图层用 filter: blur():A5 的 GPU 带不动,「模糊封面」效果用封面取色的渐变代替
  • 播放必须由点击手势直接触发,playAt() 不要隔异步回调调用

⁠本地开发

go run .            # 需要 Go 1.26+
DATA_DIR=/tmp/submini-dev go run .

⁠开发与发布

  • 页面脚本必须是纯 ES5(iOS 9)。tools/check_page.py 会抽取页面脚本做违规词扫描并用 node --check 验语法,CI 每次推送都会跑;漏一个箭头函数,iPad 上就是整页打不开。
  • 版本号在发布时由 git tag 经 Docker 构建注入二进制,页面右上角与登录卡会显示当前运行版本(本地构建显示 dev)。
  • 全屏背景的渐变漂移只在每次换歌/恢复播放后动约 12 秒,随后静止——A5 的 GPU 经不起整场持续动画。
  • 播放看门狗与断线提示:iOS 9 的流媒体偶尔会静默假死(元素显示“播放中”但进度冻结),看门狗每 2 秒核对进度,冻结满 10 秒就从原位置重连流;连续 3 次恢复失败(或服务器真的关机/断网)后停止自动重试,弹出红色提示条并提供手动「重试」。进度恢复推进后失败计数自动清零,页面切后台时不误报。
  • 屏保(仅桌面图标打开时):音乐未播放且 5 分钟无操作后,全屏轮播世界名画与风景,每 3 分钟交叉淡入换一张,左下角小字标注作品/地点;点任意处或开始播放即退出。图片只从本机服务加载:镜像内置 11 幅公共领域名画(梵高、莫奈、葛饰北斋、维梅尔、特纳、塞尚等,1024 宽),服务端另每日自动更新一批到数据目录——Bing 每日壁纸(风景)与大都会博物馆开放馆藏(仅取 Paintings/Prints 分类、公共领域、横构图者),拉取失败或数量不足时沿用旧图,断网不影响已有图集。
  • 屏保图集更新策略:每日新图与已有图集合并(新的在前、上限 24 张),某个图源当天失败不影响另一源入库;Bing 列表请求失败会自动重试一次。
  • 桌面图标模式下状态栏为透明融合式(black-translucent):系统的时间/电量图标直接浮在应用顶栏上,不再有独立黑条(网页无法彻底隐藏系统图标,这是网页端能做到的极限)。注意:此类 meta 在创建桌面图标时就被 iOS 存死,改版后需把桌面图标删除并重新添加一次才生效;配置存在服务端,删图标不丢登录与队列。
  • 屏保轮播为穿插式:摄影(Bing)与名画(大都会/内置)按各自在图集中的占比均匀编织,不会出现整段同一主题;只有一类时顺序不变。
  • Bing 图源带三条备用路线:www.bing.com⁠ 默认路线失败(某些家庭宽带上会被重置、报 EOF)时,自动依次改走「强制 IPv4」与「cn.bing.com」(同一图库),日志会注明实际走通的路线;三条全失败才跳过当天照片,大都会一路不受影响。
  • 屏保夜间模式(写死 0:00–6:00,本机时间):该时段屏保为纯黑,不加载图片;正在放图时跨过 0 点自动淡出转黑,跨过 6 点自动恢复轮播。个人设备的固定作息不做成配置项,要改时段改页面里 SAVER_NIGHT_FROM/TO 两个常量即可。
  • 播放中屏保(卡座可视化,同样仅桌面图标打开时):音乐播放中且 3 分钟无操作,全屏换成一屏「卡座版」正在播放,构图沿用全屏播放页:一台银色拉丝铝卡座做主角(与随身听同一套配色、斜向反光和同款米色磁带,卷轴随进度倒带,PLAY 灯在重拍时闪红),旁边是播放页同款的大标题/歌手/专辑、封面强调色进度条与时间,角上一个时钟;底部 32 根封面强调色频谱柱直接立在背景上,带峰值和淡倒影;背景就是播放页的封面取色渐变,光晕随低音呼吸,各部件位置固定不漂移。点任意处退出;播放中暂停超过 10 秒自动转为名画屏保,名画屏保期间从锁屏/耳机恢复播放则切回卡座;夜间时段(同上 0–6 点)画面压暗而不全黑。
  • 卡座的节奏不是 iPad 实时分析的(iOS 9 上把 <audio> 接进 Web Audio 会破坏后台播放和断线重连),而是后端 /api/rhythm 拉同一条 MP3 流用纯 Go 解码,算出每 50ms 的 8 个频段能量、响度和鼓点,页面按 audio.currentTime 对齐回放。每首歌只分析一次(同一时刻只跑一首,5 分钟的歌约 5 秒),结果存内存并落盘到数据目录 rhythm/(上限 48MB);空闲满 1 分钟预取当前歌,屏保开着时顺带预取下一首,结果到达前频谱只做轻微呼吸。绘制上照顾 iPad mini 1(A5):金属拉丝、反光、投影与文字都只在静态层换歌(取色完成)时画一次,不用任何 CSS 动画层;每帧只局部重画会动的部分(频谱柱的渐变每次换色才建一次),进度条/时间每秒、时钟每分钟才重画一次,约 25fps,横竖屏各一套布局。
  • 在电脑浏览器里试屏保:地址后加 #saver(如 http://<服务器>:9898/#saver)即在非桌面图标模式下也启用两种屏保。
  • 兼容性说明:状态栏融合间距(.sa)只在 iOS 10 及更早的图标模式下启用——iOS 11 起系统自己预留状态栏区域并忽略 black-translucent meta,页面按 UA 版本设门(needsSaInset),新系统不再多出 22px 空间距。其余设计天然跨版本:无 vh/vw 单位、布局只用 float/block、播放全由点击手势发起、毛玻璃同时写标准与 -webkit- 前缀写法;刘海屏的 viewport-fit/safe-area 不在目标内(无 viewport-fit 时新系统自动把页面收进安全区,不会与刘海/小横条相撞)。
  • 新系统渐进增强(Media Session):在支持的浏览器上(iOS 17 / 现代 Android 等),锁屏与控制中心会显示歌名/歌手/专辑与封面,并可从锁屏、耳机线控做播放/暂停/上一首/下一首/拖动;用 'mediaSession' in navigator 特性检测接入,iOS 9 上该检测为假,旧设备零影响。现代 iOS 的图标应用本身也已支持后台播放,这套增强与之配套;iOS 9 图标应用退出即停的老限制不变,仍靠播放状态恢复兜底。
  • 修复「播放中断,正在重连…」不消失:该状态原本只有切页面加载新列表时才会被顺带清掉,恢复成功/手动暂停/切歌都不清——现在凡是退出重连状态都由 clearWdStatus 收回(恢复确认、暂停、切歌、放弃转离线提示四处);另外音频 error 事件在元素已暂停时直接忽略,避免用户手动暂停后迟到的网络错误又触发重连(还会擅自恢复播放)。

Tag summary

Content type

Image

Digest

sha256:bf7bbeac4…

Size

11.3 MB

Last updated

4 days ago

docker pull passport888/submini