StrmTool for Emby

English Documentation (README_EN.md)

StrmTool 是一款专为 Emby 媒体服务器打造的 .strm 媒体增强插件。它通过预提取媒体技术信息（音视频编码、分辨率、字幕、图片、音乐标签与外挂歌词等）并导出为本地 JSON 备份，大幅提升网盘/远程流媒体的媒体库展示效果与点播起播速度；媒体信息丢失时还可从备份一键恢复。

当前版本：v2.7.0（适用 Emby 4.8+；已在 4.8.11.0 与 4.9.1.80 上测试通过，其他版本请自行测试。如果你使用的是 Jellyfin，请前往 StrmTool-Jellyfin——Jellyfin 版已独立为单独仓库，基于 .NET 10 / Jellyfin 12 构建，本仓库不再更新 Jellyfin 版本）

推荐搭配：如果你还需要从 OpenList / Alist 网盘批量生成 .strm 文件，推荐搭配本人的另一个开源项目 openlist-strm（带 WebUI 的轻量级 .strm 生成服务），在 Emby 上获得完整的流媒体播放体验。

---

✨ 核心功能

1. 🚀 媒体信息预提取与起播加速

• 入库即提取：新 .strm 文件入库后自动在后台提取音视频编码、分辨率、字幕、图片等媒体信息，详情页立即展示完整的媒体规格标签。
• 起播加速：播放前无需等待 Emby 临时探测远程流，点播起播更快。
• 智能去重：仅处理缺少完整媒体信息的 .strm 文件，已具备完整信息的条目直接跳过，避免重复操作。
• 兜底扫描：内置计划任务（默认每天凌晨 3 点，可自定义）全库扫描，确保无遗漏。
• 🎵 音乐库 .strm 完整支持：针对音乐媒体库中的 .strm 曲目，自动提取远程音频内嵌标签（歌名、专辑、歌手、专辑歌手、作曲、流派、音轨号、碟片号、发行年份等），在标签缺失时支持按 艺术家\专辑\音轨 目录结构与文件名回退补全，自动触发 Emby 生成专辑/艺术家实体与本地封面，并自动关联同目录 .lrc / .elrc 外挂歌词。

2. 💾 媒体信息备份与一键恢复

• 自动备份：提取媒体信息后自动在 .strm 同目录下导出同名 {filename}-mediainfo.json 备份文件（已有同名文件自动跳过，自动提取与手动任务均生效）。
• 一键恢复：支持从 JSON 备份批量恢复媒体信息，恢复时自动识别缺少音视频信息的文件，仅补缺失、不覆盖已有数据。
• 坏文件自愈：备份 JSON 损坏或校验失败时自动重命名为 .bak 隔离，并降级到远程探测重新提取、重新导出。

3. 📦 批量导出与离线恢复计划任务

• 提供独立的导出与恢复计划任务（恢复为纯本地磁盘操作，零远程网络请求），方便老媒体库建立初始备份，或在迁移、重建媒体库后快速恢复所有媒体技术信息。

---

📦 安装方法

手动下载安装

1. 从 Releases 页面下载最新版本的 StrmTool.dll。
2. 进入 Emby 配置目录下的插件文件夹（Docker 环境通常为 /config/plugins），新建文件夹 StrmTool。
3. 将 StrmTool.dll 放入 StrmTool 文件夹中，重启 Emby 服务器。
4. 进入 Emby 管理后台 → 插件，看到 StrmTool 状态为 Active 即表示安装成功，插件将自动开始工作。

⚠️ 版本注意：下载时请选择 Emby 版本（-emby 后缀）的插件文件。Jellyfin 版本已迁移至 StrmTool-Jellyfin 仓库发布。

---

⚙️ 插件设置说明

进入 Emby 管理后台 → 插件，找到 StrmTool，点击插件名称即可打开配置页面（v2.5.1 起提供）。

配置项	默认值	功能说明
启用自动提取	开启	检测到新 .strm 文件入库时，是否自动在后台提取媒体信息。
处理延迟（毫秒）	2000 ms	每次真实探测远程媒体信息前等待的毫秒数，用于平滑请求节奏，防止触发网盘/WebDAV 高频风控（从 JSON 备份恢复为本地操作，不延迟）。
最大并发数	3	同时处理的最大文件数量，后台探测与批量任务共用此并发上限。

其他说明：

• 所有设置点击保存后立即生效，无需重启 Emby。
• 计划任务的执行时间可在 Emby 「计划任务」页面按需调整。

---

🕒 计划任务指南

进入 Emby 管理后台 → 计划任务，可使用以下三个任务：

任务名称	默认触发	适用场景与行为说明
提取 Strm 媒体信息	每天凌晨 3 点	主力任务。全库扫描缺少媒体信息的 .strm 条目：优先从同目录 JSON 备份恢复（纯本地）；无备份则发起远程探测并自动导出备份。作为兜底定时运行，确保信息无遗漏。
导出 STRM 媒体信息	手动执行	老库生成备份。将库中已具备媒体信息、但本地尚无 -mediainfo.json 的条目批量导出为备份文件，已有备份自动跳过。
恢复 STRM 媒体信息	手动执行	迁移/重建后恢复。扫描全库，利用同目录的 JSON 备份批量恢复缺失的音视频流信息（纯本地操作，零远程网络请求）。

---

💡 常见使用场景指南

场景一：全新安装与日常使用

保持插件默认设置即可。新入库的 .strm 影片会自动在后台提取媒体信息并生成 JSON 备份；每天凌晨的兜底扫描会确保信息无遗漏，无需任何手动操作。

场景二：已有大量影片的老媒体库首次使用本插件

1. 先运行一次 「导出 STRM 媒体信息」 任务，将 Emby 数据库里已有的媒体信息批量导出为本地 JSON 备份（已有备份自动跳过）。
2. 再运行一次 「提取 Strm 媒体信息」 任务，为剩余尚未探测过的 .strm 影片补齐媒体信息并生成备份。

场景三：重建媒体库、重装 Emby 或媒体信息丢失

• 备份文件还在：手动刷新媒体库可能导致已提取信息丢失。只要在影片目录下保留了 -mediainfo.json 备份文件，运行一次 「恢复 STRM 媒体信息」 任务即可批量恢复，全程零远程网络请求。
• 迁移到新服务器：连同影片目录一起拷贝备份文件，新库扫描完成后运行「恢复 STRM 媒体信息」即可。

---

📌 注意事项与常见问题

1. 恢复任务会覆盖已有的媒体信息吗？
   • 不会。恢复仅针对缺少音视频信息的条目补全数据，已有完整信息的条目自动跳过。
2. JSON 备份文件可以随意移动或改名吗？
   • 备份文件必须与 .strm 文件位于同一目录且保持同名（仅后缀不同），例如 Movie.strm 对应 Movie-mediainfo.json。整体迁移媒体目录不影响恢复。
3. 网盘有风控限制，探测太频繁怎么办？
   • 调大 「处理延迟（毫秒）」（如改为 5000），并适当调小 「最大并发数」。命中本地 JSON 备份的条目不会发起远程请求，也不受延迟影响。
4. 插件安装后没有生效？
   • 确认下载的是 Emby 版本（-emby 后缀）的 DLL，并已重启 Emby 服务；插件列表中状态应为 Active。