别再手动整理了！用这个Python脚本，一键把TMM刮的演员图灌进Jellyfin

解放双手！Python自动化脚本实现TMM演员图无缝迁移至Jellyfin

每次打开Jellyfin看到那些缺失的演员头像，是不是总有种美中不足的感觉？作为影视库管理员，我们都希望自己的媒体库尽善尽美。但现实是，Jellyfin默认的演员图片抓取机制存在明显局限——每个演员最多只能获取15张图片，而且质量参差不齐。与此同时，Tiny Media Manager（TMM）虽然能获取更全面的演员图片资源，却分散在各个影片目录的.actors文件夹中，难以直接利用。这种割裂的状态让影视库管理变得异常繁琐。

1. 为什么需要自动化迁移工具

手动整理演员图片的工作量有多大？假设你的媒体库有1000部电影，每部电影平均有10个演员，每个演员平均有5张图片，那么你需要处理的图片总数将达到惊人的5万张！更不用说这些图片分散在数千个不同的文件夹中，手动复制粘贴不仅效率低下，还极易出错。

Jellyfin的演员图片存储采用了一种特定的目录结构：Jellyfin\ServerData\metadata\People\[首字母]\[演员姓名]\poster.ext。这种结构虽然便于系统管理，但对人工操作极不友好。想象一下，你需要为每个演员创建多层目录，然后正确命名图片文件——这简直是场噩梦。

而TMM存储演员图片的方式完全不同，它会在每个影片目录下创建.actors子文件夹，将所有相关演员图片集中存放。虽然这种组织方式便于影片级别的管理，却无法直接被Jellyfin识别使用。这种不兼容性正是我们需要解决的核心问题。

2. 自动化脚本的工作原理

我们开发的Python脚本主要解决三个关键问题：图片收集、规范命名和目录重构。脚本的设计遵循"一次配置，一键运行"的原则，即使没有编程经验的用户也能轻松使用。

2.1 核心功能模块

脚本包含两个主要功能函数：

def copy_files_from_actors_folders(root_dir, target_dir): # 递归搜索指定目录下所有.actors文件夹 actors_folders = glob.glob(os.path.join(root_dir, '**', '.actors'), recursive=True) for folder in actors_folders: # 复制.actors文件夹中的所有图片到临时目录 for file_name in os.listdir(folder): full_file_path = os.path.join(folder, file_name) if os.path.isfile(full_file_path): shutil.copy2(full_file_path, target_dir)

这个函数负责从分散的.actors文件夹中收集所有演员图片，将它们集中到一个临时目录中。采用递归搜索确保不会遗漏任何子目录中的图片资源。

def organize_images(root_dir): for dirpath, dirnames, filenames in os.walk(root_dir): for filename in filenames: if filename.lower().endswith(('.png', '.jpg', '.jpeg')): # 处理文件名：替换下划线为空格，获取首字母 image_full_name = os.path.splitext(filename)[0].replace('_', ' ') first_char = image_full_name[0].upper() if image_full_name[0].isalpha() else image_full_name[0] # 创建Jellyfin标准目录结构 first_level_dir = os.path.join(root_dir, first_char) second_level_dir = os.path.join(first_level_dir, image_full_name) os.makedirs(second_level_dir, exist_ok=True) # 移动并重命名文件 target_path = os.path.join(second_level_dir, f"poster{os.path.splitext(filename)[1]}") shutil.move(os.path.join(dirpath, filename), target_path)

第二个函数则将收集到的图片按照Jellyfin要求的目录结构和命名规范进行重组。它会自动创建多层目录，并将图片统一命名为poster.ext格式。

2.2 智能处理机制

脚本在设计时考虑到了各种特殊情况：

• 重复文件处理：使用shutil.copy2保留原始文件的元数据
• 文件名规范化：自动将下划线替换为空格，符合Jellyfin的命名习惯
• 首字母分类：根据演员姓名的首字母创建一级目录，便于管理
• 错误处理：exist_ok=True参数避免因目录已存在导致的错误

3. 如何使用这个自动化工具

使用这个脚本只需要简单的几步操作，整个过程不超过5分钟。下面是详细的使用指南：

3.1 环境准备

首先确保你的系统满足以下要求：

• Python 3.6或更高版本
• TMM已配置为将演员图片保存到.actors目录
• 对源目录和目标目录有读写权限

3.2 分步操作指南

1. 下载脚本：将提供的Python脚本保存到本地，例如tmm_to_jellyfin.py

2. 运行脚本：在命令行中执行python tmm_to_jellyfin.py

3. 选择操作模式：

   • 输入1选择源目录（包含你的媒体库，脚本会递归搜索所有.actors文件夹）
   • 输入2对已收集的图片进行整理和重命名

4. 指定目录路径：

   • 临时目录：用于存放中间文件，建议使用空文件夹
   • 源目录：包含你的电影/电视剧文件的根目录

5. 最终迁移：

   • 将处理好的People文件夹移动到Jellyfin\ServerData\metadata\目录
   • 在Jellyfin后台执行"刷新演职人员"任务

提示：首次运行时建议先在小规模目录上测试，确认无误后再处理整个媒体库。

3.3 参数配置选项

脚本支持通过修改以下变量来调整行为：

4. 高级技巧与最佳实践

4.1 定期更新策略

演员图片库不是一劳永逸的，随着媒体库的增长，你需要定期更新。建议：

• 每月运行一次脚本，获取新增演员图片
• 在TMM中设置定期自动刮削，确保图片库最新
• 使用Jellyfin的计划任务功能自动刷新元数据

4.2 质量控制方法

为了获得最佳的显示效果，可以考虑：

1. 图片筛选：在TMM中设置只下载高质量图片
2. 统一风格：优先选择正面清晰的头像照片
3. 尺寸规范：确保图片分辨率至少为500x750像素

4.3 性能优化建议

处理大型媒体库时，可以采取以下措施提高效率：

• 在SSD上运行脚本，加快文件操作速度
• 增加Python的内存限制（如使用-X pycache_prefix参数）
• 分批处理，避免一次性操作过多文件

# 示例：分批处理大型媒体库 import math def batch_process(source_dir, target_dir, batch_size=1000): all_actors = glob.glob(os.path.join(source_dir, '**', '.actors'), recursive=True) for i in range(0, len(all_actors), batch_size): batch = all_actors[i:i + batch_size] process_batch(batch, target_dir)

4.4 异常情况处理

在实际使用中可能会遇到的一些问题及解决方案：

经过几个月的实际使用，我发现这个脚本最实用的地方在于它完全解放了双手。以前需要数小时才能完成的工作，现在只需几分钟就能搞定，而且结果更加准确可靠。特别是在媒体库大规模更新后，运行一次脚本就能同步所有新增演员的图片，这种效率提升是实实在在的。