OcPlayer v0.2.1 · 设置页重构为 hub 首屏 + 子页、TMDb 元数据补全、内核换装官方 v0.2.1

OcPlayer v0.2.1 · 设置页重构为 hub 首屏 + 子页、TMDb 元数据补全、内核换装官方 v0.2.1

下载

文件	平台	说明
OcPlayer-v0.2.1-macOS-arm64.dmg / .zip	macOS（Apple Silicon）	ad-hoc 签名，未经公证，首次打开可能有 Gatekeeper 提示
OcPlayer-v0.2.1-ios-unsigned.ipa	iOS（iPhone / iPad）	未签名 IPA，需用 AltStore / Sideloadly / TrollStore 等工具重签安装
SHA256SUMS.txt / SHA256SUMS-ios.txt	—	对应平台产物校验和

播放内核换装上游官方 v0.2.1（Config/Erika.version 是唯一事实源，哈希入仓并与 release 自带 SHA256SUMS 逐字节核对；本次是纯新增 C ABI，App 侧零适配）。产物内写入 build 号与提交短哈希（关于页显示 v0.2.1 (Build N · 短哈希)）。

升级须知

• 设置页整页重构：所有设置项按功能拆进子页（播放 / 首页栏目 / 弹幕 / 网络 / Jellyfin / Bangumi / MoviePilot / TMDb / 维护 / 关于），一级页只剩 11 行导航行，每行右侧直接显示当前值（服务器名、登录态、内核、弹幕加载方式、栏目数、TMDb 状态、版本号）。找不到原来某一项时，先看一级页对应那一行。
• 升级后首次打开会重下一批海报：图片缓存键此前含「服务器地址 + App 版本」，于是换地址（局域网 ↔ Tailscale ↔ 反代）和每次发版都会把整份缓存作废。键改为「服务器 + 账号」维度并做了一次性旧键清理——这次清理不额外增加任何下载（新键本来就要重下），此后换地址与升级都不再重下。
• jellyfin-sdk-swift 升到 3.3.0（按 Jellyfin 12.1 OpenAPI 生成）：兼容 Jellyfin 12（版本号从 10.11 直接跳到 12.0）。三项客户端可见的破坏性变更逐项核对全不沾（旧式鉴权头、/emby 路径别名、GetItems 递归过滤语义）。遗留提醒：跳过片头依赖服务器端 intro-skipper 插件，10.11 时代的插件在 12.0 上不加载，需等插件适配版（服务器侧，与播放器无关）。
• TMDb 元数据补全是可选功能：默认关闭，需自己在「设置 → TMDb 元数据补全」填 API Key（v3 / v4 格式都收）。不填则整个功能禁用、不发任何请求，行为与上一版一致。

本次改动

TMDb 元数据补全（新功能）

填好 API Key 后，详情页可用 TMDb 补简介、评分、类型、演员、海报 / 背景 / 分集剧照。匹配走「服务端 ProviderIds["Tmdb"] 直连 → 标题 + 年份搜索兜底」，六档打分只有 ≥0.85 才自动落库——错误匹配比没有匹配更糟：用户会看到别人的简介和海报，而且显示得像真的一样。匹配不上的可在详情页手动搜候选、绑定或解除（手动绑定的不会被自动匹配顶掉）。设置页可对整个媒体库批量补全：剧集连同各季一起补（季数据决定分集标题 / 剧照 / 切季简介），带进度条与「新补 / 跳过 / 匹配不上 / 失败」四类计数，可随时取消——进度状态就是数据库本身，取消后再点一次自然续跑，不会重复打请求。文本与图片可分开选「TMDb 优先 / 只补缺」（默认两者都是 TMDb 优先），缓存期硬夹在 6 个月内（TMDb 条款），并带署名。

冷启动与离线不再空白

首页三条栏 / 库列表 / 条目详情 / 季与集 / 翻过的库页 / 媒体技术信息落进 SQLite（Media.sqlite）：冷启动先读磁盘、首屏立刻有内容，网络结果回来原位覆盖。断网时有内容才显示一行小字——noNetwork / serverUnreachable 说「离线 · 数据更新于 X 前」，5xx / 401 说「内容可能不是最新 · 刷新失败」，不把服务端的问题引去查网络。播放进度只读缓存、服务端响应一律覆盖（进度与元数据两个独立时间戳、两条独立淘汰上限）。库损坏 / 迁移失败删库重建；payload 宽容解码，以后给条目加字段不需要迁移。

图片：换地址与升级不再重下，离线出图不再等网络

• 缓存键只保留「路径 + 查询 + 服务器/账号身份」（host 归一为占位符），同一台服务器换入口共用一份缓存；身份用跨进程稳定的哈希（hashValue 每进程随机播种，会让缓存每次启动全失效），且不再包含 App 版本。
• 仅靠 URLCache 跨实例读不回来（实测：同实例命中、重启一律 miss），故新增图片字节自存，网络失败时由图片管道回落。
• 兜底从「网络失败再读磁盘」改为磁盘优先：断网时不再每张图先等约 7 秒超时。后台刷新设三道闸门（7 天新鲜度 / 同键去重 / 并发 ≤4），翻页时不会突然打出上百个请求。
• 实测：旧键清理后图片缓存 110 MB → 6.5 MB；离线启动首页图片全部正常显示。

一台服务器多条地址，自动挑最快可达的那条

档案从「一个 URL」变成「一组地址 + 当前生效地址 + 可选固定项」，按服务器身份合并：换地址再登一次只是给这台服务器补一个入口，不会再冒出一条、也不会覆盖原地址。择优按实测延迟而不是按类别（Tailscale 直连有时比绕一圈的局域网更快），并有三条硬约束：粘性（两个入口延迟接近就不切，避免来回抖）、软过期后台重探（不阻塞请求）、失败开放（一个地址都探不通时保持原地址，绝不把「探活失败」变成「连不上服务器」）。传输层失败时自动换址并在新地址立刻重试一次；HTTP 4xx/5xx 不算地址不通。

设置页与详情页

• 设置页重构为 hub 首屏 + 子页：一级页 11 行导航行带当前值预览，说明文字随功能进各自子页；破坏性操作全部补确认（退出三种登录、清图片 / 元数据 / TMDb 缓存、清日志）；iPhone 栏目排序按钮热区补到 44×44（原先 2pt 间距误触率高），TMDb Key 输入改纵排避免被键盘顶住。
• 详情页头部补上「去原站看看」：Bangumi 与 TMDB 的官方彩色图标，点开用系统浏览器。季与分集刻意不给链接——它们要的是剧集级 id，硬拼会指到别人的片子。

弹幕与播放

• 弹幕字号改为百分比调整：从 4 档单选（小 / 标准 / 大 / 特大）改为与字幕一致的减小 / 重置 / 加大，根行显示百分比（22pt = 100%），步进 ±10%、范围 50%–200%；存储格式不变，旧档位值无需迁移。
• 内核换装上游官方 v0.2.1：资源回收（关闭 / 切换媒体 / seek 时取消旧的网络读取，销毁播放器时等后台 worker 退出并释放连接与线程，stop() 释放 HTTP 缓存与队列占用但保留从头重播）、预读窗口修复（预取不再跨越条带边界继续读取）、恢复硬解不可用时的软件回退（WMV/WMA、8/10-bit AV1）并修正 P010 插值精度。

修复

• 播放完返回详情页时，被盖住的媒体库页透过透明详情页漏出（内容间散落着库网格卡片）。
• 呈现式页面（下载管理 / 资源搜索 / 管理服务器 / 开源许可证）返回键点了没反应；同族的宿主漏出与半透漏底两洞一并修掉。
• 设置 → 退出 MoviePilot 每次必卡死（后台线程写 UserDefaults 造成的互等）。
• iOS 切后台回来播放器直接报错、只能点重试。
• MoviePilot 未登录时分区整页只有中间一块有氛围背景；Bangumi 未登录时顶栏是一条死灰横条。
• MoviePilot 只是没登录，分区首页却报「未配置 MoviePilot」。
• 测试宿主被「stderr → os_log → stderr」自激循环拖死（iOS 测试步骤此前在 CI 上从未绿过的根因）。
• 设置页补上「退出 Bangumi」出口（此前只在 Bangumi 分区个人页顶栏）。

说明

• 完整变更清单（含每条的踩坑记录与验证口径）见仓库 CHANGELOG.md 的 [0.2.1] 一节。
• 发版过程中修掉一个 CI 缺陷：tag push 时 Release 门禁的 checkout 步骤会因 git fetch --tags 缺少 --force 而必然失败（v0.2.1 首跑即挂在第一步、一条用例都没跑），已修并改用 workflow_dispatch 重跑；下一次发版直接验证 tag push 路径。
• 两条已知取舍（已写进代码注释与文档，不必重复讨论）：分集剧照是两段式（先服务端图、TMDb 到位后替换一帧）；服务端脏 ProviderIds（TMDb 404）会每次重试且不退回搜索——实测本机库 41 个带 Tmdb id 的条目全部有效，故未加退避。