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

解放双手Python自动化脚本实现TMM演员图无缝迁移至Jellyfin每次打开Jellyfin看到那些缺失的演员头像是不是总有种美中不足的感觉作为影视库管理员我们都希望自己的媒体库尽善尽美。但现实是Jellyfin默认的演员图片抓取机制存在明显局限——每个演员最多只能获取15张图片而且质量参差不齐。与此同时Tiny Media ManagerTMM虽然能获取更全面的演员图片资源却分散在各个影片目录的.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), recursiveTrue) 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_okTrue) # 移动并重命名文件 target_path os.path.join(second_level_dir, fposter{os.path.splitext(filename)[1]}) shutil.move(os.path.join(dirpath, filename), target_path)第二个函数则将收集到的图片按照Jellyfin要求的目录结构和命名规范进行重组。它会自动创建多层目录并将图片统一命名为poster.ext格式。2.2 智能处理机制脚本在设计时考虑到了各种特殊情况重复文件处理使用shutil.copy2保留原始文件的元数据文件名规范化自动将下划线替换为空格符合Jellyfin的命名习惯首字母分类根据演员姓名的首字母创建一级目录便于管理错误处理exist_okTrue参数避免因目录已存在导致的错误3. 如何使用这个自动化工具使用这个脚本只需要简单的几步操作整个过程不超过5分钟。下面是详细的使用指南3.1 环境准备首先确保你的系统满足以下要求Python 3.6或更高版本TMM已配置为将演员图片保存到.actors目录对源目录和目标目录有读写权限3.2 分步操作指南下载脚本将提供的Python脚本保存到本地例如tmm_to_jellyfin.py运行脚本在命令行中执行python tmm_to_jellyfin.py选择操作模式输入1选择源目录包含你的媒体库脚本会递归搜索所有.actors文件夹输入2对已收集的图片进行整理和重命名指定目录路径临时目录用于存放中间文件建议使用空文件夹源目录包含你的电影/电视剧文件的根目录最终迁移将处理好的People文件夹移动到Jellyfin\ServerData\metadata\目录在Jellyfin后台执行刷新演职人员任务提示首次运行时建议先在小规模目录上测试确认无误后再处理整个媒体库。3.3 参数配置选项脚本支持通过修改以下变量来调整行为参数默认值说明RECURSIVE_SEARCHTrue是否递归搜索子目录ALLOWED_EXTENSIONS(.png,.jpg)处理的图片格式OVERWRITE_EXISTINGFalse是否覆盖已存在文件4. 高级技巧与最佳实践4.1 定期更新策略演员图片库不是一劳永逸的随着媒体库的增长你需要定期更新。建议每月运行一次脚本获取新增演员图片在TMM中设置定期自动刮削确保图片库最新使用Jellyfin的计划任务功能自动刷新元数据4.2 质量控制方法为了获得最佳的显示效果可以考虑图片筛选在TMM中设置只下载高质量图片统一风格优先选择正面清晰的头像照片尺寸规范确保图片分辨率至少为500x750像素4.3 性能优化建议处理大型媒体库时可以采取以下措施提高效率在SSD上运行脚本加快文件操作速度增加Python的内存限制如使用-X pycache_prefix参数分批处理避免一次性操作过多文件# 示例分批处理大型媒体库 import math def batch_process(source_dir, target_dir, batch_size1000): all_actors glob.glob(os.path.join(source_dir, **, .actors), recursiveTrue) for i in range(0, len(all_actors), batch_size): batch all_actors[i:i batch_size] process_batch(batch, target_dir)4.4 异常情况处理在实际使用中可能会遇到的一些问题及解决方案问题现象可能原因解决方法部分图片未显示文件名包含特殊字符在TMM中重新刮削该演员目录结构不正确路径长度限制缩短媒体库路径或启用长路径支持权限错误脚本无写入权限以管理员身份运行或修改目录权限经过几个月的实际使用我发现这个脚本最实用的地方在于它完全解放了双手。以前需要数小时才能完成的工作现在只需几分钟就能搞定而且结果更加准确可靠。特别是在媒体库大规模更新后运行一次脚本就能同步所有新增演员的图片这种效率提升是实实在在的。