安装影音优化助手
影音优化会提前准备视频的播放信息。远程 STRM 的结果由安装在 Emby 或 Jellyfin 中的 Mediora Helper 写入，助手写入后，Mediora 会再读回核对，确认保存内容一致才显示“媒体服务器已采用”。助手不可用时，准备结果仍保留在 Mediora。
下载与兼容范围
Emby 和 Jellyfin 使用各自的安装包，不能互换。从 Mediora-Helpers 下载页选择明确的 emby-helper-vX.Y.Z 或 jellyfin-helper-vX.Y.Z，同时下载 ZIP、同名 .sha256 和 release-evidence.json；发行证据记录源码和检查范围。两个助手独立维护版本，无需在每次升级 Mediora 时重新安装；请按本页兼容范围选择插件版本。
两个助手均支持手动安装，无需通过插件市场。下载文件与校验和以独立发行附件为准。
| 助手 | 安装兼容说明 | 已记录的真实服务器验证范围 |
|---|---|---|
| Emby | 不按服务器版本号设固定上限，升级宿主后仍需重新检测。 | 媒体信息同步已在官方 4.10.1.0 隔离宿主及实际 NAS 验证；搜索优化在官方 4.10.1.0 隔离宿主验证。 |
| Jellyfin | 最低 10.10.0，使用 Jellyfin 专用安装包。 | 媒体信息同步已在官方 10.10.7 隔离宿主、实际 NAS 和指定原生播放器验证；搜索优化在官方 10.10.7 隔离宿主验证。 |
升级媒体服务器后先重新检测助手。未来宿主改变接口时仍可能需要适配，不能仅根据版本号判断兼容。Emby 无法准确表达的 Dolby Vision 组合会提示格式不支持；Jellyfin 10.10 无法持久保存 HDR10+，会拒绝该格式。原始准备结果保留，不会静默降级成另一种格式。
构建检查过其他版本的接口，不等于已经在那些服务器和全部客户端上实际播放验收。先用一部常见格式影片验证同步、字幕和播放，再扩大范围。
安装到 Emby
- 下载对应版本的 ZIP 和校验和，在同一目录执行
shasum -a 256 -c 安装包文件名.zip.sha256，确认校验通过。 - 从 Emby 后台的服务器信息确认实际程序数据目录。把 ZIP 中的
MedioraEmbyHelper.dll直接放到它的plugins/根目录，例如/config/plugins/MedioraEmbyHelper.dll。 - 如果有旧文件名
Mediora.Emby.Helper.dll或Mediora.Helper.dll，停机后移走旧文件，避免重复加载。升级前保留旧安装包、插件配置及下述保护状态目录的备份。 - 重启 Emby，在“插件 → 我的插件”中查看 Mediora Helper，打开插件说明页。
Emby 不需要为助手新建插件子目录；不要把解压工具生成的外层目录整体放进去。
安装到 Jellyfin
- 下载并验证对应版本 ZIP 的校验和。
- 把 ZIP 内的整个
Mediora Helper_助手版本.0文件夹放进实际plugins/目录，保留安装包内的原始文件夹名称。 - 确保
MedioraJellyfinHelper.dll、meta.json和build.yaml在同一个插件子目录内；不要把 DLL 单独放在plugins/根目录。旧文件名或旧插件目录应在停机备份后移走，避免重复加载。 - 重启 Jellyfin，在“插件 → 我的插件”中查看 Mediora Helper 并打开说明页。
安装后先核对文件位置
以媒体服务器容器的数据目录为 /config、助手版本为 1.0.5 为例：
Emby：
/config/plugins/MedioraEmbyHelper.dll
Jellyfin：
/config/plugins/Mediora Helper_1.0.5.0/MedioraJellyfinHelper.dll
/config/plugins/Mediora Helper_1.0.5.0/meta.json
/config/plugins/Mediora Helper_1.0.5.0/build.yaml
这是容器内路径。用 NAS 文件管理器复制时，要进入该容器 /config 对应的宿主机目录；插件不是放进 Mediora 的 /app/data。版本号和文件夹名称按你实际下载的 ZIP 保留，复制完成后重启对应的 Emby 或 Jellyfin。
回到 Mediora 确认
- 打开 播放服务 → 影音优化 → 处理规则，点击“重新检测助手”。
- 核对所选服务器、媒体库和助手状态，再按页面显示点击“保存规则”“保存规则并确认助手权限”或“确认助手同步权限”。这一步才会确认新的助手状态。
- 在“优化任务”打开任务“详情”，对已结束的视频点击“重新同步”。它使用已有准备结果，不会重新探测网盘。
助手重置或保护状态变化后，旧请求会被拒绝。只点击重新检测或等待后台重试不会自动批准新状态；必须核对并保存处理范围。
“重新优化”会再次读取来源影片；只是想把已准备结果写回服务器时，优先选择“重新同步”。状态应分别确认：Mediora 已准备、备份已保存、服务器已采用，三者不能互相代替。
更换媒体服务器地址或管理员密钥后，也须重新检测并保存范围；原连接上的检测与确认不会自动授权新连接。
可选搜索优化
- 安装支持搜索优化的助手（1.0.4 或更新版本）并重启媒体服务器后，打开“插件 → Mediora Helper”。
- 勾选“启用搜索优化”，按需选择“同时搜索原语言标题”和默认媒体类型范围，再保存。
- 首次启用会在后台准备索引，显示“已就绪”后，直接使用 Emby 或 Jellyfin 原有的搜索框；准备期间继续使用原生搜索。
支持中文部分标题和简繁混搜，例如“波特”“鳳凰”；支持拼音和首字母，例如 halibote、hlbt；也可输入 tmdb=671、tmdbid=671、tt0241527 等已有媒体编号。纯数字按标题搜索，不会自动当作媒体编号。
增强范围为电影、剧集和合集，客户端明确指定的媒体类型优先。权限、媒体库范围、筛选和分页继续由媒体服务器处理。标题与编号索引仅保存在媒体服务器本机内存，重启后重新准备；新增、改名和删除会随条目更新。字符级拼音不判断多音字语境，也不提供错别字纠正或语义搜索。Emby 的旧版搜索建议接口不扩展。
功能默认关闭。关闭并保存后即恢复原生搜索，不需要还原标题或重建媒体库；索引准备失败或宿主接口不兼容时也会保留原生搜索，并在设置页显示状态。
| 提示 | 处理方法 |
|---|---|
| 未安装或需要升级 | 检查实际插件目录、服务器启动日志和安装包版本，重启后重新检测。 |
| 权限不足 | 使用媒体服务器的管理员凭据；媒体信息同步和搜索设置管理都要求管理员权限。 |
| 保护状态已更新 | 重新检测，核对所选媒体库并保存设置，再重新同步。 |
| 格式不支持 | 保留准备结果，核对宿主支持的格式；持续重试不会使宿主获得缺失能力。 |
| 无法连接 | 在“系统 → 系统设置 → 服务设置”中测试地址与连接。 |
保护状态与恢复
助手会记住哪些播放信息已经写入，避免旧任务覆盖新结果。这份“保护状态”保存在媒体服务器数据目录里的 mediora-emby-helper/revision-store 或 mediora-jellyfin-helper/revision-store，普通重启会保留。
升级或迁移助手时，应一起备份旧安装包、插件配置和整个保护状态目录。只保留 DLL 不等于备份完整。1.0.3 及后续版本发现已有状态目录不完整时会停止继续写入；应先停机保存现场，再从完整备份恢复，不要删除部分状态文件来绕过提示。
管理员恢复操作 Reset 会作废旧任务的写入许可，但不会撤回已经写入的媒体信息。普通同步失败优先排查并使用“重新同步”；只有明确执行恢复操作时才使用 Reset。恢复旧保护状态备份后，也需按助手恢复说明重置状态，然后回到 Mediora 重新检测、核对并保存范围。
Mediora 只向已确认范围内的远程 STRM 同步结果，助手核对目标归属和来源版本，不改写本地真实媒体。同步和插件设置管理要求媒体服务器的管理员权限，日常搜索继续沿用服务器原有用户权限。助手安装在媒体服务器中，不要把 DLL 放进 Mediora 容器或把媒体服务器数据库共享给 Mediora。