媒体库

媒体库用来集中管理本地的影视与书籍资源，目前支持「电影」「电视剧」「小说」和「漫画」四种类型，每个库各自对应一个根目录。

建好媒体库后，系统会先扫描现有文件，并在运行期间持续监听文件变化；同时读取本地元数据（影视看 NFO，小说看 OPF，漫画看 ComicInfo），或者通过绑定的工作流自动刮削，并按重命名模板整理目录和文件名。

本页的 NFO、播放与目录示例主要面向电影和电视剧。小说与漫画另有格式、目录、元数据和阅读说明。

创建媒体库

管理员在 设置 → 系统设置 → 媒体库管理 中点击「新增」，按说明填写即可：

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

注意不同媒体库的根目录不能完全相同，也不能互相包含；就算是通过软链接指向相同或重叠的目录也不行。目录选择器支持直接在界面里新建文件夹或删除空文件夹，操作的是服务端真实的磁盘目录。

扫描与实时监控

创建媒体库时，不管「启动时全量扫描」有没有开，都会先扫描一次已有文件。之后日常运行时的行为如下：

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

管理员可以在媒体库管理里点扫描，也可以在媒体库页面左侧栏把鼠标移到媒体库名称上，点右侧的扫描按钮。扫描期间按钮会显示加载状态，不能重复触发同一媒体库的扫描。

需要注意的是，扫描本身主要负责把文件变化找出来，后面的刮削和自动整理还会在后台继续跑——扫描结束不代表所有元数据工作流都已经完成，普通扫描也不会把没变过的 NFO 强行重刮一遍。

小说与漫画还会在后台建立正文索引，目录与处理状态见扫描与索引。管理员也可通过 AI 助手预览并确认影视库扫描、重新刮削与入库配置修改；保存配置本身不会立刻重扫或整理已有文件。

元数据

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

条目	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 等图形字幕。

目录结构建议

文件层级决定了 Kaloscope 怎么把它们识别成媒体条目。配置下载转移或重命名模板时，也建议保持下面这两种结构。

电影

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 元数据后，才能更稳妥地按季整理目录和匹配弹幕。