匹配、合并与时间轴

自动匹配不准、弹幕太少、两个来源想合并、弹幕早晚不同步时，主要看这一组配置。

自动匹配会看哪些信息

POST /api/v2/match 会从文件名或标题里解析：

• 标题
• 季数，例如 S01
• 集数，例如 E05、第5集
• 年份
• @平台 动态优先级
• 上次手动选择记忆

示例：

{
  "fileName": "凡人修仙传 S01E01 @youku"
}

@youku 只影响候选中的平台优先级，不等于启用 youku 来源。要让优酷参与搜索，仍然要在 SOURCE_ORDER 里加入对应来源。

让标题更容易搜到

外文标题转中文

适合网盘文件名没有中文标题，例如：

Blood.River.S01E05

配置：

TITLE_TO_CHINESE=true
TMDB_API_KEY=你的TMDB_API_KEY

它会在自动匹配时尝试把外文标题转换为中文再搜索。因为要请求外部服务，速度会比普通匹配慢。

标题映射表

适合某些资源标题和平台收录标题不一致：

TITLE_MAPPING_TABLE=唐朝诡事录->唐朝诡事录之西行;国色芳华->锦绣芳华

FongMi /danmaku 接口也会使用这个映射。遇到播放器传入的标题固定不准时，这个变量比改播放器更稳。

繁简转换

如果资源标题是繁体，可以开启：

ANIME_TITLE_SIMPLIFIED=true

搜索时会把繁体标题转换为简体再处理。

过滤预告、花絮和非正片

如果搜索结果里总是预告、花絮、特辑，可以开启：

ENABLE_ANIME_EPISODE_FILTER=true

配合：

ANIME_TITLE_FILTER=广告|预告|无关剧名
EPISODE_TITLE_FILTER=预告|花絮|特辑|试看

默认 EPISODE_TITLE_FILTER 已经包含很长的规则。普通用户只需要补充自己的关键词，不建议随便整段替换。

源合并

MERGE_SOURCE_PAIRS

用于把多个来源的弹幕合成一份。格式：

主源&副源&副源,主源&副源

示例：

MERGE_SOURCE_PAIRS=dandan&animeko&bahamut,imgo&iqiyi

注意：

• 一组里第一个是主源，其它是副源。
• 主源没有结果时，会尝试轮替下一个作为主源。
• 合并太多来源可能带来重复、时间轴不一致或误合并，建议先单源跑通。
• 可以只写单源，例如 imgo，表示保留原结果，不额外合并。

CUSTOM_MERGE_RULES

用于具体作品的高级补丁。

常见用途：

1. 应该合并但没有合并：用 -> 强制合并。
2. 集数错位：用路由规则指定副源集数对应主源集数。
3. 标题很像但不是同一部：用 × 阻断误合并。

示例：

天气之子@bilibili -> 天气之子@dandan
我推的孩子/S01@bahamut -> 我推的孩子/S03@dandan | E25~E35>E25~E35
辉夜大小姐想让我告白@bilibili × 辉夜大小姐 OVA@dandan

后台有可视化添加规则面板，日常优先用面板生成，不建议手写复杂规则。

弹幕时间轴偏移

DANMU_OFFSET 用来修正弹幕早晚不同步。

普通秒数偏移

DANMU_OFFSET=overlord/S01:90,re-zero/S02@bilibili:120,re-zero/S02/E03@dandan&bilibili:10

含义：

• 剧名:秒：全剧偏移。
• 剧名/S01:秒：整季偏移。
• 剧名/S01/E03:秒：单集偏移。
• @来源：只对指定来源生效。
• 正数表示弹幕延后，负数表示弹幕提前。

百分比模式

当整集不是简单早几秒或晚几秒，而是越到后面越偏，可以用百分比模式：

DANMU_OFFSET=东方/S03/E02@tencent%:11

百分比模式会按公式缩放弹幕时间：

新时间 = 原时间 * (视频时长 + 偏移秒数) / 视频时长

它适合视频整体快慢不一致的情况。

弹幕清洗和数量控制

屏蔽词

BLOCKED_WORDS=/.{20,}/,/^\d{5,}$/,/第[一二三四五六七八九十百\d]+/

支持普通词、正则和多条规则。正则要注意不要过宽，否则会误杀正常弹幕。

去重窗口

GROUP_MINUTE=1

按多少分钟分组后合并重复弹幕。0 表示不去重，最大建议不超过 30。

限制弹幕总量

DANMU_LIMIT=5

单位是 k。5 表示弹幕超过 5000 条时等间隔采样到约 5000 条。0 表示不限制。

样式转换

CONVERT_TOP_BOTTOM_TO_SCROLL=true
CONVERT_COLOR=white
COLOR_POOL=16711680,65280,255,16776960

适合播放器不支持顶部/底部弹幕、彩色弹幕显示异常，或者只想保留白色弹幕的场景。

AI 匹配

AI 匹配用于候选很多、标题复杂、普通规则难以判断时辅助选择。

需要配置：

AI_BASE_URL=https://api.openai.com/v1
AI_MODEL=gpt-4o
AI_API_KEY=你的AI_API_KEY

可选：

AI_MATCH_PROMPT=自定义提示词

后台可通过 AI 连通性测试接口或系统配置界面验证。没有 AI_API_KEY 时，AI 匹配不会生效。

推荐排查顺序

1. 先用后台“弹幕测试”手动搜作品，看候选是否正确。
2. 候选都没有，先改 SOURCE_ORDER、Cookie、代理或标题映射。
3. 候选有但自动选错，改 PLATFORM_ORDER、TITLE_MAPPING_TABLE 或开启 AI 匹配。
4. 弹幕少，考虑 MERGE_SOURCE_PAIRS 或更换来源。
5. 弹幕不同步，再配置 DANMU_OFFSET。
6. 弹幕太脏或太多，再配置 BLOCKED_WORDS、GROUP_MINUTE、DANMU_LIMIT。