reader/docs/media-user-guide.zh-CN.md

影音使用说明

影音支持电影、剧集、音乐和有声书。打开站点进入首页（#/），汇总继续阅读、继续观看/收听与书架；应用导航（手机为底部标签栏，宽屏为左侧边栏）中的「影音」进入影视频道（#/media/video），「书架」返回阅读。手机在频道页顶部用影视/音乐/有声书分段切换频道，并可左右滑动切换分类；宽屏在侧边栏「影音」下切换频道。导航细节见导航约定。

新建与管理媒体库

管理员从「我的 → 媒体库」（或影视页「更多操作 → 媒体库管理」）进入，点「新建媒体库」，选择内容类型、接入方式和访问范围。普通用户只看到已获授权的媒体库。

• 服务器目录：填写 Reader 服务端能读取的路径。Docker 部署填写容器内路径，例如将宿主目录只读挂载到 /media/music 后，填 /media/music。
• OpenList：填写服务地址、远端绝对目录，以及可选访问令牌和目录密码。创建前验证连接。编辑已有库可更新或清除凭据；不改服务地址和根目录。见OpenList 接入说明。

创建后自动提交扫描。若创建已成功而扫描失败，查看该库任务并重试扫描，不必再次建库。创建请求响应丢失时，在原表单保持配置不变重试可恢复同次创建；刷新或修改配置后，先核对是否已有目标库。

扫描只读源文件，不移动、改名或写回标签。目录或远端读取失败会保留已发布目录和资料。缺失文件可在详情查看状态；恢复文件后重扫。不同播放版本需要明确选择，不能按文件名推断为同一版。

媒体库管理页顶部有“扫描与刮削”和“新建媒体库”，列表显示全部媒体库（与从哪个频道进入无关）。每个媒体库卡片显示缺失文件数和最近一次扫描：完成时间、进行中的进度（已处理百分比）和“取消”，或失败原因与“重试”“查看详情”；从未扫描的库显示“开始扫描”。卡片的 ⋯ 菜单提供编辑媒体库、访问权限和扫描记录。“扫描与元数据”是全部媒体库共用的四个开关，也出现在「我的 → 服务配置」的“扫描设置”中：

• 自动扫描新文件（默认开）：每小时检查一次所有媒体库，未变化的文件沿用上次的技术信息。
• 刮削封面与简介（默认关）：扫描完成后，用已配置的 TMDB 或 MusicBrainz 为还没有在线资料、也从未刮削过的作品发起一次批量刮削；未匹配的作品不会每次重试。
• 读取内嵌字幕与歌词（默认开）：关闭后不再提供视频内嵌字幕流和音频标签里的歌词。
• 扫描隐藏文件夹（默认关）：名称以“.”开头的文件夹和文件（例如 macOS 的 ._影片.mp4）不参与扫描；原来扫描到的这类文件会在下一次扫描后标记为缺失，打开开关重扫即可恢复。

剧集与多季命名

影视库综合目录规则、NFO、季目录和文件名识别单集。支持 S01E01、1x02、“第一季第二集”；Season 01、S01、“第一季”和 Specials（特别篇，第 0 季）目录下还支持 EP01、E01、“第01集”和 01.mp4。缺少可靠季集信息或遇到多集合集时保留为独立文件，重新识别预览中标记待确认，不自动拆分。

推荐目录结构：

剧集/
  远山之路/
    Season 01/
      远山之路 S01E01.mkv
      远山之路 S01E02.mkv
    Season 02/
      远山之路 S02E01.mkv

同一库中按“剧目录＋剧名”归组；父目录名为 Season 01、S01 或“第一季”等季目录形式时，使用其上一级作为剧目录。各季、各集按数字排序，同季同集的不同文件作为不同版本。不同目录下的同名剧不会自动合并。

季目录下优先使用剧目录名，避免把 Season 01 当作剧名。文件名中的分辨率、编码、音轨格式、已知字幕组和哈希标记会从展示标题移出，保留年份作为资料。默认保留 1917、2001 太空漫游、续集序号等可能属于片名的数字，不改原始文件名。

同目录 NFO 查找顺序为“同名 .nfo → movie.nfo → tvshow.nfo → album.nfo → audiobook.nfo”，采用首份有效记录，NFO 字段优先于标签和文件名。单集 NFO 可用 showtitle、season、episode 明确归属；影视识别还读取同目录 season.nfo 的 seasonnumber/season，并向上查找 tvshow.nfo 的剧名与年份（最多 64 层，不越过库根目录）。

按目录配置识别与重新识别

管理员在影视频道工具栏点「打开文件夹」，进入目标目录后从右上角 ⋯ 菜单选择「识别规则与预览」（仅影视库）。本地和 OpenList 库使用同一套规则：

• 继承上级：删除当前目录的独立规则，使用最近的上级规则。
• 自动识别：显式恢复自动判断，也可覆盖上级“忽略”规则。
• 电影目录：强制按电影处理。
• 剧集目录：指定剧名、可选默认季/版本名称；文件中明确的季号优先于默认值。
• 指定季目录：必须填写当前目录的季/版本名称，可以是季号，也可以是“特别版”“4K版”“OVA”这类命名分组；剧名可继承上级剧目录。
• 忽略目录：跳过新文件的识别，已有作品保留；仍存在的文件不会仅因被忽略而标记缺失。

规则包含子目录，最近的独立规则优先。除忽略外，还可填写“目录内文件名解析正则”，对当前目录及子目录的所有文件统一应用，支持 name、year、season、episode、order、edition 等具名组。可选年份覆盖自动年份；“移除文件名开头的排列编号”适合 001. 片名 等命名，默认关闭，启用后务必核对年份片名。目录规则不提供 TMDB ID 强制绑定，在线匹配继续通过作品的元数据匹配入口确认。

保存规则只影响后续扫描。已有作品通过“保存并预览重新识别”调整：单次最多 500 个可用资源，超过时进入子目录分批操作；低把握结果和多个文件合为同一集默认不勾选。人工整理、人工资料、已确认在线资料、共享或已有多版本作品保留，目标剧集已人工维护时同样不自动改动。

确认应用后不改源文件，保留资源、版本、播放片段 ID、播放进度和队列。同集版本合并时收藏合并保留。普通重扫不直接改变已有作品归属；预览有效期 15 分钟，规则或目录数据库发生变化需重新预览。应用使用预览时读取的 NFO 快照；若期间编辑过 NFO，请重新生成预览。扫描或批量刮削期间不可保存规则和应用结果。

扫描识别采用可解释规则与目录/NFO 证据，不调用模型。复杂命名可先用目录规则校正，再通过在线候选人工确认资料。「扫描与刮削」中的 AI 扫描需管理员在服务配置的「AI 功能」中启用，按批次作为可追踪任务运行并记录模型给出的分类结果，供查看；它不会改变已有作品的识别结果。

按目录清理失效资源

管理员打开频道的「文件夹」，选择媒体库并进入目标目录，从右上角 ⋯ 菜单选择「清理失效资源」。范围包含当前目录及所有子目录；在库内根目录操作则覆盖整个库。

先成功完成媒体库扫描，再预览清理数量。仅清理扫描已标记缺失的文件记录，不处理仅因编码不支持、探测失败、鉴权或网络错误而暂时无法播放的资源。扫描或批量刮削中不能清理；最近扫描失败或取消时需先重扫成功。

确认框会列出资源、播放片段、空版本、空作品/分类，以及所有用户受影响的收藏、播放进度和队列数量。确认后原子清理这些数据库记录及相关播放会话；仍有资源的版本、作品和上级分类保留，原始本地和 OpenList 文件不删除。预览后目录或关联范围变化时，需要重新预览。

清理不可撤销，文件恢复后可重新扫描入库，但已移除的进度与人工资料不会恢复。临时卸载目录或网盘挂载异常时应先恢复并重扫，不应清理。清理后当前目录变空会返回最近仍有记录的上级目录。

资料、刮削和整理

本地库优先读取文件标签、NFO 和同目录封面；ffprobe 用于编码、时长及章节探测，ffmpeg 用于部分内嵌资源提取，两者不等于转码功能。OpenList 支持外置 NFO、封面、歌词和字幕，暂不读取远端内嵌标签、封面及章节。

管理员打开「我的 → 服务配置」，在 TMDB 和 MusicBrainz 分类中配置令牌、API Key 或应用标识，保存后生效。管理员在作品菜单中匹配资料，审阅候选后确认；也可从「我的 → 扫描与刮削」的“刮削”标签发起批量任务并重试未完成项。来源网络、凭据或封面下载失败会单独提示。

详情的资源信息菜单可查看文件与技术信息、管理版本。手工资料、作品归属、版本拆分或合并会在重扫时保留，不修改原文件。移动版本不转移收藏，也不复制原作品的人工资料；更改剧集、季和单集关系后需重新确认受影响的在线匹配。

浏览、搜索与收藏

媒体库筛选位于列表左侧，排序等操作在右侧。演播者目录同样支持媒体库筛选。全局搜索支持频道和内容类型，权限及分页在服务端生效。

收藏统一使用 #/media/favorites，无频道 tab。右侧筛选选择内容类型，筛选和分页写入地址，刷新后可恢复。歌手、专辑、剧集和有声书分别进入自己的详情路由；返回使用实际来源页面。

播放与恢复

视频由 DPlayer 提供内置控件，播放页工具栏另有选集、字幕与音轨（字幕、音轨、版本）、全屏（手机上尝试锁定横屏）和更多选项；音频页面提供封面、进度、队列、歌词、倍速、睡眠定时和播放模式（顺序播放、随机、单曲循环；播放器不支持时按钮置灰）。关闭迷你播放器停止当前播放。章节和曲目按当前版本的真实顺序处理，失效资源不会悄悄切到其他版本。

播放器地址包含作品 ID 和播放部分 ID，刷新后重新读取会话与授权。服务器保存播放进度；权限被撤销、资源失效或会话冲突时需要按页面提示处理。浏览器自动播放限制可能要求再次点击播放。

Android 原生后台播放与条件恢复见后台播放说明。恢复保持暂停，不以旧快照覆盖另一设备的进度。

部署、备份与限制

影音数据使用 DATA_DIR/media.db，阅读和账号使用 reader.db。停服备份完整数据目录，成对恢复数据库及签名密钥，见备份恢复。影音异步启动，阅读健康检查成功不代表影音已就绪；MEDIA_STARTING 表示准备中，MEDIA_UNAVAILABLE 需要检查日志。

当前不包含 TVBox/JAR、转码、影音离线下载或云盘账号登录。OpenList 负责其挂载驱动访问，Reader 服务端必须能访问 OpenList 及下载源；某些驱动需要启用 OpenList Web 代理。实际可播放编码取决于浏览器或设备。

更多：导航约定、架构、验收媒体包、验证方式。