媒体库

媒体库负责管理本地视频文件、NFO 元数据和播放入口。目前支持「电影」和「电视剧」两种类型，每个媒体库对应一个根目录。

• 创建后扫描已有文件，运行期间持续监控文件变动
• 按媒体库控制启动时是否全量扫描，也可随时手动扫描
• 读取本地 NFO，或通过绑定的工作流刮削元数据
• 根据 NFO 和重命名模板自动整理目录、视频及相关文件

创建媒体库

管理员在设置 → 系统设置 → 媒体库管理中点击「新增」，填写以下字段：

字段	必填	说明
类型	✓	支持「电影」和「电视剧」，创建后不可修改
名称	✓	媒体库的显示名称，不可与已有媒体库重名
语言		刮削时使用的偏好语言
目录	✓	媒体文件的根目录，Docker 部署时填写容器内路径，创建后不可修改
启动时全量扫描		默认开启；关闭后重启服务不再自动全量扫描，实时监控和手动扫描仍可使用
自动重命名模板		按 NFO 元数据整理目录和文件名，留空关闭，详见自动整理
弹幕服务器		兼容弹弹play API 的接口地址，留空则不从服务器匹配和加载弹幕
弹幕缓存（小时）		本地弹幕缓存有效期，默认 24 小时，详见弹幕设置
绑定的工作流		绑定「资源入库」类别的工作流，用于自动或手动刮削元数据

媒体库目录不能相同，也不能互相包含；通过软链接指向相同或重叠目录时同样会被拒绝。目录选择器支持创建文件夹和删除空文件夹，操作的是服务端实际目录。

扫描与实时监控

创建媒体库时，无论「启动时全量扫描」是否开启，都会扫描一次已有文件。之后的处理分为以下几种情况：

场景	行为
启动服务	开启启动扫描的媒体库会自动全量扫描；关闭后仍启动文件监控并恢复待处理事件
服务运行期间增删或替换文件	实时监控会更新媒体条目，并按需触发元数据处理
服务停止期间增删媒体文件或更新 NFO	下次启动扫描或手动扫描时同步；关闭启动扫描后需手动补扫
手动扫描	发现新增或缺失条目，处理更新的 NFO，并补齐缺失文件信息及需要执行的入库流程

管理员可在媒体库管理中执行扫描，也可在媒体库页面侧栏将鼠标移到媒体库名称上，点击右侧扫描按钮。扫描期间按钮显示加载状态，不能重复提交同一媒体库的扫描。

扫描主要负责发现文件变化；刮削和自动整理还会在后台继续处理。扫描结束不表示所有元数据工作流已经完成，也不会强制重新刮削已有且未变化的 NFO。

元数据

Kaloscope 从本地 NFO 文件读取标题、简介、评分、年份、演员、导演、标签和海报等信息。NFO 内容使用 Kodi 风格的 XML，文件位置需要与 Kaloscope 的条目结构对应：

条目	NFO 位置示例	XML 根元素
根目录中的单文件电影	Movies/Film.mkv → Movies/Film.nfo	movie
子目录中的电影	Movies/Film/Film.mkv → Movies/Film/Film.nfo，目录条目的 NFO 与目录同名	movie
剧集或季度目录	Shows/Series/Season 01/ → Shows/Series/Season 01/Season 01.nfo	tvshow
单集视频	Shows/Series/Season 01/S01E01.mkv → 同目录下的 S01E01.nfo	episodedetails

缺少 NFO 时，可以为媒体库绑定元数据刮削工作流。入库时会自动触发工作流，并根据资源入库「结束节点」的结果生成 NFO。

管理员也可以在媒体条目菜单中点击「刮削元数据」，填写标题、年份、语言等条件，搜索并确认候选结果。刮削完成后会生成或更新 NFO、刷新媒体信息；如果已配置重命名模板，还会尝试自动整理。

在线播放

点击媒体文件可在内置播放器中播放。播放器优先直连播放浏览器支持的视频；浏览器不支持时，可通过服务端转码实时转为 HLS 流。

• 支持倍速、长按加速、分集或分段切换，以及移动端样式全屏
• 支持弹幕显示、手动匹配、重复合并和正则过滤
• 支持外挂字幕和视频内嵌的文本字幕，可调整字幕时间偏移、字号和位置
• 本地视频含有可识别的内嵌章节时，可在播放器中查看并跳转章节
• 支持播放进度记录和续播；开启首页「最近观看」后，同一媒体目录条目只展示最近观看的一集或分段

外挂字幕需放在视频旁，使用同名或带语言后缀的文件名，例如 S01E01.zh-CN.srt。支持 VTT、SRT、ASS 和 SSA；字幕会统一转换为 WebVTT，复杂 ASS 特效不保证保留。内嵌字幕支持文本轨道，不包含 PGS 等图片字幕。

目录结构建议

文件层级决定媒体条目的组织方式。使用下载转移或重命名模板时，也应保持以下层级。

电影

Movies/
├── Film (1990).mp4
├── Film (1994).mp4
├── Film (2008)/
│   └── Film.mkv
└── Film (2010)/
    ├── Film-cd1.avi
    └── Film-cd2.avi

电影支持根目录下的单文件，或根目录下一层子目录中的视频。多分段电影可以入库和播放，但目前不会自动重命名整理。

电视剧

Shows/
├── Series Name A (2010)/
│   ├── Series Name A S01E01.mkv
│   └── Series Name A S01E02.mkv
└── Series Name B (2018)/
    ├── Season 01/
    │   ├── Series Name B S01E01.mkv
    │   └── Series Name B S01E02.mkv
    └── Season 02/
        ├── Series Name B S02E01.mkv
        └── Series Name B S02E02.mkv

电视剧支持「剧集目录 / 视频」和「剧集目录 / 季目录 / 视频」两种结构。目录名和文件名中的年份、季数、集数会用于初始识别；准确的 NFO 元数据可进一步用于按季整理和弹幕匹配。