Episode-ReName多季番剧处理：TMDB集数适配技术详解

引言：多季番剧的命名困境

你是否遇到过这样的场景？下载了《鬼灭之刃》第二季，文件命名是S02E28.mp4，但在TMDB（The Movie Database）中，这一集实际上是第二季的第二集。传统的媒体服务器如Emby、Jellyfin无法正确刮削元数据，导致剧集信息混乱。Episode-ReName的TMDB集数适配技术正是为解决这一痛点而生。

通过本文，你将深入了解：

• TMDB集数适配的核心原理与实现机制
• all.txt配置文件的灵活使用方法
• 多组offset匹配的复杂场景处理
• 与qb-rss-manager的深度集成方案
• 实际应用中的最佳实践与故障排除

技术架构与核心原理

集数修正处理流程

flowchart TD
    A[开始集数修正] --> B[向上查找目录结构]
    B --> C{找到all.txt文件?}
    C -->|是| D[读取offset数值]
    C -->|否| E[查找qb-rss-manager配置]
    D --> F[应用单一offset修正]
    E --> G{找到QRM配置?}
    G -->|是| H[解析多组offset匹配]
    G -->|否| I[返回原始集数]
    H --> J[应用匹配的offset]
    F --> K[处理小数集数特殊情况]
    J --> K
    K --> L[返回修正后集数]
    I --> M[返回原始集数]

核心代码实现

Episode-ReName通过ep_offset_patch函数实现TMDB集数适配，该函数位于utils/episode_utils.py中：

def ep_offset_patch(file_path, ep, application_path):
    """
    多季集数修正 - 核心适配函数
    Args:
        file_path: 文件路径
        ep: 原始集数
        application_path: 应用程序路径
    Returns:
        str: 修正后的集数
    """
    logger.debug(f"开始进行集数修正，原始集数: {ep}")
    
    # 向上查找目录，寻找all.txt文件
    b = os.path.dirname(file_path.replace('\\', '/'))
    offset_str = None
    
    while b:
        if offset_str:
            break
        if not '/' in b:
            break
            
        b, fo = b.rsplit('/', 1)
        offset_str = None
        
        if get_season(fo):  # 检查是否为季文件夹
            logger.debug(f"检查季文件夹是否有集数修正文件: {b}/{fo}")
            try:
                for fn in os.listdir(b + '/' + fo):
                    if fn.lower() != 'all.txt':
                        continue
                        
                    all_txt_path = f"{b}/{fo}/{fn}"
                    logger.debug(f"找到集数修正文件: {all_txt_path}")
                    
                    with open(all_txt_path, encoding='utf-8') as f:
                        offset_str = f.read()
                        logger.info(f"从 {all_txt_path} 读取到集数修正值: {offset_str}")
                        break
            except Exception as e:
                logger.error(f"读取集数修正文件时出错: {str(e)}")
                return ep

all.txt配置文件的灵活使用

基础配置模式

单一数字offset - 最常用的配置方式：

26

这将把S02E28修正为S02E02（28 - 26 = 2）

负数offset - 用于增加集数：

-12

这将把S02E01修正为S02E13（1 - (-12) = 13）

多组匹配配置

对于复杂的多版本资源，支持管道符分隔的多组offset：

12|0|-11

这表示：

• 第一组匹配：集数减12
• 第二组匹配：集数不变
• 第三组匹配：集数加11

文件放置规范

all.txt必须放置在季文件夹内，与视频文件同一目录：

鬼灭之刃/
├── Season 1/
│   ├── all.txt
│   ├── S01E01.mp4
│   └── S01E02.mp4
├── Season 2/
│   ├── all.txt      # 放置在这里
│   ├── S02E28.mp4   # 将被修正为S02E02
│   └── S02E29.mp4   # 将被修正为S02E03
└── season.nfo

与qb-rss-manager的深度集成

配置自动发现机制

当目录中不存在all.txt时，Episode-ReName会自动尝试发现qb-rss-manager的配置文件：

# 没有找到all.txt 尝试寻找qb-rss-manager的配置文件
if not offset_str:
    qrm_config = get_qrm_config(application_path)
    
    if qrm_config:
        season_path = get_season_path(file_path)
        if 'data_list' in qrm_config:  # 旧版格式
            logger.info('检测到 qb-rss-manager 的旧版格式数据')
            for x in qrm_config['data_list']:
                if format_path(x[5]) == format_path(season_path):
                    if x[4]:  # rename_offset字段
                        offset_str = x[4]
        else:  # v1格式
            logger.info('检测到 qb-rss-manager 的v1格式数据')
            for data_group in qrm_config['data_dump']['data_groups']:
                for x in data_group['data']:
                    if format_path(x['savePath']) == format_path(season_path):
                        if x['rename_offset']:
                            offset_str = x['rename_offset']

多组offset的智能匹配

对于多组offset配置，系统会根据文件名中的关键词自动选择正确的offset组：

# 多组数据的offset解析
if '|' in offset_str:
    logger.info(f'多组数据的offset解析: {offset_str}')
    
    # 查找QRM配置匹配的组序号
    index = 0
    for data_group in qrm_config['data_dump']['data_groups']:
        for x in data_group['data']:
            if format_path(x['savePath']) == format_path(season_path):
                try:
                    must_contain_tmp = x['mustContain']
                    if '|' not in must_contain_tmp:
                        break
                    else:
                        # 根据关键词匹配选择正确的offset组
                        for i, keywords in enumerate(must_contain_tmp.split('|')):
                            keywords_list = keywords.strip().split(' ')
                            if all([keyword.strip() in file_path for keyword in keywords_list]):
                                index = i
                                break
                except Exception as e:
                    logger.error(f'解析mustContain时出错: {str(e)}')
    
    # 获取对应的offset值
    offset_parts = offset_str.split('|')
    if index < len(offset_parts):
        offset = int(offset_parts[index].strip())

实际应用场景与案例

场景一：连续季集数修正

案例：《进击的巨人》最终季Part 2

• TMDB中为Season 4 Part 2，但文件发布时可能延续之前的集数编号
• 配置all.txt：16（如果Part 1有16集）

文件命名转换：

S04E17.mp4 → S04E01.mp4
S04E18.mp4 → S04E02.mp4

场景二：特殊版本处理

案例：同一季有多个版本（如导演剪辑版、扩展版）

all.txt 内容：5|0|-3

匹配规则：

• 版本1关键词：减5集
• 版本2关键词：保持不变
• 版本3关键词：加3集

场景三：小数集数处理

支持特殊的小数集数格式（如12.5集）：

# 处理带小数点的集数
if '.' in ep:
    ep_int, ep_tail = ep.split('.')
    ep_int = int(ep_int)
    
    # 安全检查：只有当集数大于等于offset时才修正
    if int(ep_int) >= offset:
        original_ep = ep
        ep_int = ep_int - offset
        ep = str(ep_int) + '.' + ep_tail
        logger.info(f"集数修正: {original_ep} -> {ep} (offset={offset})")

最佳实践与配置建议

1. 文件编码与格式

• all.txt必须使用UTF-8编码
• 内容应为纯数字或数字组合，前后无空格
• 支持整数和负数，支持管道符分隔的多组配置

2. 放置位置规范

文件类型	正确位置	错误位置
all.txt	Season文件夹内	剧集根目录
all.txt	与视频文件同级	父级目录

3. 日志调试技巧

启用详细日志输出以调试集数适配：

EpisodeReName.exe --path "D:\番剧\鬼灭之刃\Season 2" --log_to_file 1 --log_level DEBUG

查看日志中的关键信息：

从 D:/番剧/鬼灭之刃/Season 2/all.txt 读取到集数修正值: 26
集数修正: 28 -> 02 (offset=26)

4. 安全机制

• 集数安全检查：防止产生负数集数
• 文件存在检查：避免误操作
• 备份机制：建议先在小范围测试

故障排除与常见问题

Q1: all.txt配置不生效

检查项：

• 文件是否放置在正确的季文件夹内
• 文件编码是否为UTF-8
• 内容格式是否正确（纯数字）

Q2: 小数集数修正异常

解决方案：

• 确认offset值为整数
• 检查日志中的详细处理过程

Q3: 多组offset匹配错误

调试方法：

• 启用DEBUG级别日志
• 检查文件名中的关键词匹配情况

Q4: 与qb-rss-manager集成问题

排查步骤：

1. 确认qb-rss-manager配置正确
2. 检查savePath路径匹配
3. 验证mustContain关键词设置

技术优势与创新点

1. 智能路径发现

采用向上递归查找算法，自动发现季文件夹中的all.txt配置文件。

2. 多配置源支持

支持本地all.txt文件和qb-rss-manager远程配置的双重配置源。

3. 安全修正机制

内置集数范围检查，防止产生无效的负数集数。

4. 灵活的多组匹配

支持基于关键词的多组offset匹配，适应复杂的多版本场景。

5. 小数集数兼容

完整支持12.5等特殊集数格式的修正计算。

总结与展望

Episode-ReName的TMDB集数适配技术通过创新的all.txt配置文件和智能的offset计算算法，完美解决了多季番剧在TMDB标准下的集数匹配问题。该技术：

• ✅ 支持正负offset灵活配置
• ✅ 兼容多组复杂匹配场景
• ✅ 提供完善的安全检查机制
• ✅ 实现与qb-rss-manager深度集成
• ✅ 具备详细的日志调试能力

对于媒体库管理者而言，这一技术大大简化了多季番剧的整理工作，确保了Emby、Jellyfin等媒体服务器能够正确刮削元数据，提升了整体的媒体管理体验。

未来该技术可进一步扩展支持更多元数据源的适配规则，为开源媒体管理生态提供更加完善的解决方案。