添加转换任务
转换任务是 OpenList to Stream 的核心功能，用于将 OpenList 中的文件列表转换为 STRM 流媒体文件。本页详细介绍如何创建和管理转换任务。
什么是转换任务？
转换任务定义了如何将 OpenList 中的特定路径转换为 STRM 文件：
- 指定要转换的 OpenList 路径
- 设置 STRM 文件的输出位置
- 配置转换选项（更新模式、刮削等）
- 设置定时执行计划
文件处理器链
系统在处理视频文件时，采用责任链模式依次执行多个处理器：
| Order | 处理器 | 功能 | 说明 |
|---|---|---|---|
| 10 | FileDiscoveryHandler | 文件发现 | 遍历 OpenList 文件树，收集所有文件信息 |
| 20 | FileFilterHandler | 文件过滤 | 过滤出需要处理的视频文件 |
| 30 | StrmGenerationHandler | STRM 生成 | 生成 STRM 流媒体文件 |
| 40 | NfoDownloadHandler | NFO 下载 | 下载媒体信息文件（三级优先级：本地 > OpenList > 刮削） |
| 41 | ImageDownloadHandler | 图片下载 | 下载海报、背景图、缩略图 |
| 42 | SubtitleCopyHandler | 字幕复制 | 复制同目录下的字幕文件 |
| 50 | MediaScrapingHandler | 媒体刮削 | 从 TMDB/AI 获取媒体信息 |
| 60 | OrphanCleanupHandler | 孤立文件清理 | 清理不再存在的源文件对应的 STRM |
处理器链执行流程
视频文件 → STRM生成 → NFO下载 → 图片下载 → 字幕复制 → 媒体刮削 → 清理孤立文件每个处理器都可以独立启用或通过配置控制是否执行。
创建新任务
前置条件
在创建任务之前，请确保：
- ✅ 已添加至少一个 OpenList 配置
- ✅ 已准备好 STRM 文件的输出目录
第一步：访问任务管理页面
- 登录系统
- 在首页的 OpenList 配置列表中，找到对应的配置
- 点击操作列中的「管理任务」按钮
- 在任务管理页面中，点击「创建任务」按钮
创建和编辑任务使用同一套表单，编辑时会自动填入当前任务配置。
第二步：基本信息
任务名称
给任务起一个描述性的名字，例如：
- 「电影库转换」
- 「电视剧同步」
- 「纪录片更新」
注意：任务管理页面已经关联到特定的 OpenList 配置，无需再次选择配置。
第三步：路径配置
任务路径
填写要转换的 OpenList 路径：
路径示例：
/电影- 电影目录/电视剧- 电视剧目录/纪录片- 纪录片目录
注意：这是必填字段，需要填写完整的 OpenList 路径
媒体库类型
每个任务需要指定当前任务根目录下的媒体类型。系统会根据类型解释目录层级，并约束 TMDB 搜索和 AI 识别：
| 类型 | 典型目录结构 | 解析方式 |
|---|---|---|
| 电影 | 电影名 (年份)/视频文件 | 优先从视频的直接父目录提取标题和年份 |
| 电视剧 | 剧名/Season 01/S01E01.ext | 从季目录上一级提取剧名，从目录和文件名提取季集 |
| 动画 | 动画名/Season 01/01.ext 或 动画名/[01].ext | 按电视剧刮削，并支持动画常见的绝对集数 |
| 自动识别 | 沿用原有目录结构 | 使用通用正则判断，仅建议旧任务兼容使用 |
配置建议
新任务请选择明确的电影、电视剧或动画类型。一个任务目录中不要混放不同媒体类型；需要混放时应拆分为多个任务。
STRM 输出路径
设置 STRM 文件的保存路径：
路径结构：
- 固定前缀：
/app/backend/strm/（系统固定，不可修改） - 子路径：您可以自定义子路径（可选）
示例：
- 子路径留空：
/app/backend/strm/ - 子路径为
movies：/app/backend/strm/movies - 子路径为
tv/series：/app/backend/strm/tv/series
路径建议
- 按媒体类型创建不同的子路径（如 movies、tv、documentaries）
- 避免使用特殊字符和中文路径
- 保持路径结构简洁明了
第四步：更新模式
全量更新
每次执行时重新处理所有文件：
- 优点：确保所有文件都是最新状态
- 缺点：处理时间长，重复刮削
增量更新
只处理新增、修改或本地尚未生成 STRM 的文件：
- 优点：执行速度快，节省资源
- 缺点：首次执行仍需要完整读取 OpenList 目录
增量模式工作原理：
- 保存任务上一次成功扫描的远端文件特征
- 下次执行时只处理变化目录和本地缺失的 STRM
- 同一次任务复用目录索引、TMDB 结果和图片下载结果
- 处理完成后清理远端已删除文件对应的孤立 STRM
第五步：任务执行选项
需要刮削
开启后使用 TMDB 和可选的 AI 文件名识别生成 NFO、海报与背景图。使用前需要在系统设置中启用刮削并填写 TMDB API Key。
普通任务自动重命名媒体
默认关闭。开启后，手动执行和 Cron 定时任务会先根据 TMDB 结果重命名 OpenList 中的媒体目录和文件，再重新读取远端清单并生成 STRM。
启用条件：
- 已开启“需要刮削”
- 媒体库类型是电影、电视剧或动画，不能是自动识别
- OpenList Token 具备重命名目录和文件的写入权限
无法识别、TMDB 未匹配或目标名称冲突时，系统保留原名称并继续任务，不会覆盖已有文件。该选项修改 OpenList 源文件；“STRM 文件名正则表达式”只修改本地生成的 .strm 文件名，两者互不替代。
完整命名规则和冲突保护见 目录检查与手动刮削。
跳过目录结构不符合的视频
开启后，结构异常的视频不会生成 STRM，也不会进入刮削流程。建议先使用任务操作区的“检查目录结构”确认异常列表。自动识别任务不能启用此选项。
第六步：任务完成后刷新媒体库
需要先在系统设置中添加并测试 Emby 或 Jellyfin。任务支持：
| 刷新范围 | 行为 |
|---|---|
| 不刷新 | 默认值，不调用媒体服务器 API |
| 刷新全部媒体库 | 任务完成后提交全库刷新请求 |
| 刷新指定媒体库 | 按媒体库 ID 校验目标，并提交精确目录更新 |
全量任务始终提交刷新；增量任务只有检测到视频变更、失效 STRM 清理或媒体重命名时才刷新。
选择“刷新指定媒体库”时，必须再选择媒体服务器和目标媒体库。系统不会在目标媒体库失效时按名称匹配，也不会回退为全部刷新。完整配置和异常处理见 Emby / Jellyfin 媒体库刷新。
第七步：资源下载配置
字幕文件配置
- 保留字幕文件：开启后自动下载视频同目录下的字幕文件
支持的字幕格式：
.srt- SubRip 字幕.ass- Advanced Substation Alpha.vtt- WebVTT 字幕.ssa- SubStation Alpha.sub- SubViewer.idx- VobSub 索引
字幕下载逻辑：
- 获取视频所在目录的所有文件
- 筛选出字幕格式的文件
- 下载到 STRM 文件同一目录
- 自动避免重复下载
图片文件配置
- 使用已有刮削信息：开启后优先使用本地文件
图片下载优先级（三级）：
- 本地检查：本地是否存在
{baseFileName}-poster.jpg等 - OpenList 下载：从 OpenList 同级目录下载
- TMDB 刮削：通过 API 获取媒体信息
支持的图片类型：
-poster.jpg- 海报图片-fanart.jpg- 背景图-thumb.jpg- 缩略图- 任意命名图片（降级策略）
NFO 文件配置
- 生成 NFO 文件：自动生成 Kodi/Plex 兼容的媒体信息文件
NFO 下载优先级：
- 本地是否存在同名 NFO
- OpenList 是否存在同名 NFO
- 通过 TMDB/AI 刮削获取
第八步：定时设置
Cron 表达式
设置任务的自动执行时间（可选）：
常用表达式：
| 表达式 | 说明 |
|---|---|
0 2 * * * | 每天凌晨2点 |
0 */6 * * * | 每6小时 |
0 0 * * 0 | 每周日午夜 |
0 0 1 * * | 每月1号午夜 |
0 0 * * 1-5 | 工作日午夜 |
配置说明：
- 留空表示不启用定时任务，只能手动执行
- 使用标准 Cron 表达式格式
- 系统会根据配置自动执行任务
第九步：保存和测试
保存任务
所有配置完成后，点击「保存」按钮创建任务。
注意：
- 任务名称和任务路径为必填项
- STRM 子路径和 Cron 表达式为可选项
- 系统会自动验证配置的有效性
管理现有任务
任务列表
在任务管理页面可以看到所有任务的状态：
| 任务名称 | OpenList 配置 | 状态 | 最后执行 | 下次执行 | 操作 |
|---|---|---|---|---|---|
| 电影库转换 | 家庭媒体服务器 | ✅ 运行中 | 2024-01-15 02:00 | 2024-01-16 02:00 | 执行/编辑/删除 |
| 电视剧同步 | 家庭媒体服务器 | ⏸️ 已暂停 | 2024-01-14 20:00 | - | 启动/编辑/删除 |
执行任务
手动执行
- 在任务列表中找到要执行的任务
- 点击「立即执行」按钮
- 确认执行操作
查看执行状态
- 等待中：任务已加入执行队列
- 执行中：正在处理文件
- 已完成：任务执行完成
- 失败：执行过程中出现错误
查看执行详情
任务执行时，您可以查看：
- 处理的文件数量统计
- 成功/失败统计
- 刮削结果统计（海报、NFO、字幕）
- 详细的执行日志
编辑任务
- 在任务列表中找到要编辑的任务
- 点击「编辑」按钮
- 修改配置信息
- 点击「保存」确认修改
检查目录结构
任务操作区提供「检查目录结构」入口。进入时会先强制刷新 OpenList，并只读取任务根目录和第一层媒体目录，不会立即遍历整个媒体库。用户点击某个第一层目录的「检查」按钮后，系统才递归扫描该目录。
检查规则：
| 类型 | 合法结构 |
|---|---|
| 电影 | 电影名 (年份)/视频文件 |
| 电视剧 | 剧名/Season 01/S01E01.ext，季目录也支持 S01、第1季 |
| 动画 | 动画名/Season 01/01.ext 或 动画名/[01].ext |
| 自动识别 | 没有固定结构，检查时会提示先选择明确的媒体库类型 |
字幕、图片和 NFO 等辅助文件不会被列为结构异常。检查只用于诊断，不会移动、重命名或删除 OpenList 中的文件。重新点击「检查」会再次读取该目录的最新内容。
完整操作说明请参阅 目录检查与手动刮削。
跳过目录结构不符合的视频
电影、电视剧和动画任务可以启用「跳过目录结构不符合的视频」：
- 异常视频不会生成 STRM，也不会进入 AI 或 TMDB 刮削流程
- 增量执行会清理此前为这些异常视频生成的本地 STRM 和刮削文件
- 自动识别任务没有固定目录结构，因此不能启用此选项
- 执行任务和检查页面使用同一套结构规则
启用前建议
先运行一次目录结构检查，确认规则符合当前媒体库。启用后，异常视频会从本次任务输出中排除。
手动刮削
任务操作区的「手动刮削」入口可以选择单个电影或剧集目录，预览 TMDB 信息、重命名计划和待上传文件。确认后任务会在后台异步执行，页面可查看进度，并在下载或上传失败后从中断阶段继续。
手动刮削支持使用标题、年份或 TMDB ID 修正自动匹配结果。电视剧还可以统一剧集根目录、季目录和媒体文件命名。详细说明请参阅 目录检查与手动刮削。
暂停/启动任务
- 在任务列表中找到要管理的任务
- 点击「暂停」或「启动」按钮
- 暂停的任务不会自动执行，但仍可手动执行
删除任务
- 在任务列表中找到要删除的任务
- 点击「删除」按钮
- 在确认对话框中点击「确认删除」
删除警告
删除任务不会删除已生成的 STRM 文件，但会停止所有未来的自动执行。
任务执行详情
执行日志
每个任务执行都会生成详细的日志：
日志信息包括：
- 开始和结束时间
- 处理的文件数量
- 成功/失败统计
- 错误信息和堆栈跟踪
- 刮削结果统计（NFO、海报、字幕）
性能统计
- 处理速度：文件/秒
- 网络请求：API 调用次数
- 资源占用：CPU 和内存使用情况
- 执行时长：总耗时
刮削统计
- NFO 文件：成功/失败/跳过
- 海报图片：成功/失败/跳过
- 背景图片：成功/失败/跳过
- 字幕文件：成功/失败/跳过
特殊配置项说明
并发控制配置
系统支持以下特殊的并发控制配置：
- 最大并发任务数：控制同时运行的任务数量
- 单任务最大文件处理数：限制单个任务处理的文件数量上限
- 网络请求超时时间：设置 HTTP 请求的最长等待时间
错误处理配置
提供多种错误处理策略选择：
- 失败重试：自动重试失败的文件，提高成功率
- 跳过错误：跳过错误文件继续处理其他文件，保证整体进度
- 停止执行：遇到错误时立即停止任务，便于快速定位问题
通知配置
在系统设置中启用 Apprise 后，普通任务和手动刮削到达终态时可发送成功、部分完成或失败通知。通知可以展示结构异常跳过、刮削未识别、重命名失败、媒体库刷新失败的完整路径和原因。详细配置见 Apprise 任务通知。
常见问题
Q: 任务执行很慢怎么办？
A: 可以尝试以下优化：
- 启用增量更新模式
- 减少并发任务数
- 开启「使用已有刮削信息」避免重复刮削
- 检查网络连接质量
- 考虑分批处理大量文件
Q: 如何处理大量文件？
A: 建议采用以下策略：
- 按媒体类型分别创建任务
- 使用增量更新模式
- 设置合适的执行时间（避开高峰期）
- 监控系统资源使用情况
- 开启字幕和图片的本地优先模式
Q: STRM 文件无法播放？
A: 检查以下几点：
- 确认 STRM 文件路径正确
- 检查媒体服务器配置
- 验证原始文件是否可访问
- 查看任务执行日志
- 检查 URL 编码设置
Q: 字幕文件没有下载？
A: 可能的原因：
- 未开启「保留字幕文件」选项
- OpenList 目录中不存在字幕文件
- 字幕格式不支持
- 查看执行日志确认是否有下载错误
Q: 图片文件没有下载？
A: 可能的原因：
- 未开启相关刮削选项
- 「使用已有刮削信息」设置不正确
- OpenList 目录中不存在图片文件
- TMDB API 未配置或无法访问
Q: 如何减少重复刮削？
A: 推荐配置：
- 开启「增量更新」模式
- 开启「使用已有刮削信息」
- 开启「保留字幕文件」
- 配置正确的图片下载优先级
最佳实践
1. 任务规划
- 按媒体类型（电影、电视剧、纪录片）分别创建任务
- 使用描述性的任务名称
- 设置合理的执行时间
2. 路径管理
- 保持 OpenList 路径和输出路径的一致性
- 使用绝对路径避免路径混淆
- 定期清理无用的任务和文件
3. 资源下载配置
- 首次运行：关闭增量模式，全量刮削
- 日常更新：开启增量模式 + 使用已有刮削信息
- 有本地资源：开启字幕保留 + 本地图片优先
4. 性能优化
- 优先使用增量更新
- 合理设置并发数量
- 监控系统资源使用
- 开启本地优先模式减少 API 调用
5. 监控和维护
- 定期查看执行日志
- 设置错误通知
- 及时处理失败的任务
- 监控刮削成功率