MediaLink：一款递归扫描下载目录并自动整理媒体文件的 CLI 工具

项目地址： github.com/This-is-XiaoDeng/MediaLink
许可证： GNU General Public License v3.0
开发语言： Python 3.11+

概述

MediaLink 是一个命令行工具，能够递归扫描媒体下载目录，通过创建符号链接（或硬链接、复制、移动）将媒体文件按照「标题 / 季 / 集」的标准化结构整理到目标目录。它的主要使用场景是配合 Plex、Jellyfin、Emby、飞牛影视等媒体库服务器使用，减轻手动整理文件的工作量。

背景

订阅或手动下载的番剧、电视剧、电影，文件名通常包含发布组信息和压制参数（如 [Airota&VCB-Studio] Chuunibyou demo Koi ga Shitai! [01][Hi10p_1080p][x264_flac].mkv），并且嵌套在多层子目录中。这种命名风格对媒体库服务器不够友好——后者期望的是类似 Chuunibyou demo Koi ga Shitai! S01E01.mkv 的简单命名和扁平化目录结构。

手动重命名和整理一批文件需要大量重复劳动。MediaLink 试图自动化这一过程。

功能特性

🔍 文件名智能解析

底层依赖 guessit 库，从文件名中自动提取标题（title）、季号（season）、集号（episode）、年份（year）、文件类型（剧集/电影）等信息。对于部分文件名不规范的文件，也尝试通过父目录名称进行回退推断。

📁 四种文件处理模式

📺 自动分类：剧集 vs 电影

根据解析到的信息自动判断媒体类型：

• 剧集 → {target}/anime/{Title}/Season {NN}/{Title} S{NN}E{NN}.{ext}
• 电影 → {target}/movies/{Title}/{Title} ({Year}).{ext}

也可以通过 --movie-dir 参数自定义电影的输出目录。

📜 字幕文件自动匹配

支持 .ass、.ssa、.srt、.sub、.idx、.vtt 等多种字幕格式。字幕文件会根据所在目录和集号自动匹配到对应的视频文件，语言标签（.sc、.tc、.en 等）会被自动识别并保留在目标文件名中。

🧪 Dry-run 预览

使用 --dry-run 参数可以预览所有将要执行的文件操作，但不实际执行。适合在正式运行前确认整理结果是否正确。

🎛 元数据覆写

当自动解析的结果不准确时，可以通过 --override（或 -o）参数手动指定：

--override title="Chuunibyou demo Koi ga Shitai! Ren"
--override season=2
--override episode_offset=5

🔢 自动编号

--auto-number 参数可以为未能检测到集号的文件自动分配递增的序号（从 1 开始，跳过已有集号）。

⏭ 特殊目录跳过

--skip-specials 参数可以跳过位于 Specials、SPs、OVA、Extras 等目录中的文件。

🖥 美观的输出

借助 rich 库，终端输出包含带颜色的表格和面板，扫描结果和操作计划都结构清晰。

项目架构

代码分为六个模块，职责分离清晰：

medialink/
├── __init__.py       # 包声明
├── __main__.py       # python -m medialink 入口
├── cli.py            # 命令行参数解析，主流程编排
├── scanner.py        # 文件系统递归扫描，按扩展名分类
├── identifier.py     # guessit 文件名解析，字幕匹配
├── models.py         # 数据模型：FileKind, MediaFile, Series, Season, Episode 等
├── planner.py        # 源文件到目标路径的映射计划
├── executor.py       # 执行文件操作（链接/复制/移动）
└── output.py         # rich 终端输出格式化

工作流程：

扫描目录  →  解析文件名  →  分组为 Series/Season/Episode  →  规划目标路径  →  执行文件操作
scanner.py    identifier.py    identifier.py                    planner.py           executor.py

安装与使用

依赖

• Python >= 3.11
• Poetry（用于依赖管理和运行）

安装步骤

git clone https://github.com/This-is-XiaoDeng/MediaLink
cd MediaLink
poetry install

基本用法

# 预览操作
poetry run medialink /path/to/source /path/to/library --dry-run

# 实际执行
poetry run medialink /path/to/source /path/to/library

全部选项

使用示例

整理一部番剧

输入目录结构：

种子下载/
  [Airota&VCB-Studio] Chuunibyou demo Koi ga Shitai!/
    [Airota&VCB-Studio] Chuunibyou demo Koi ga Shitai! [Hi10p_1080p]/
      [Airota&VCB-Studio] Chuunibyou demo Koi ga Shitai! [01][Hi10p_1080p][x264_flac].mkv
      [Airota&VCB-Studio] Chuunibyou demo Koi ga Shitai! [01][Hi10p_1080p][x264_flac].sc.ass
      [Airota&VCB-Studio] Chuunibyou demo Koi ga Shitai! [02][Hi10p_1080p][x264_flac].mkv
      [Airota&VCB-Studio] Chuunibyou demo Koi ga Shitai! [02][Hi10p_1080p][x264_flac].sc.ass

执行后输出（默认软链接模式）：

anime/
  Chuunibyou demo Koi ga Shitai!/
    Season 01/
      Chuunibyou demo Koi ga Shitai! S01E01.mkv
      Chuunibyou demo Koi ga Shitai! S01E01.sc.ass
      Chuunibyou demo Koi ga Shitai! S01E02.mkv
      Chuunibyou demo Koi ga Shitai! S01E02.sc.ass

源文件保留在原位置，目标目录下创建的是指向源文件的符号链接。

覆写不准确的自动识别结果

poetry run medialink download/ library/ \
  -o "title=Chuunibyou demo Koi ga Shitai! Ren" \
  -o season=2

输出效果预览

2026-07-10T09:16:34.png

适用场景

• 使用 Plex / Jellyfin / Emby / 飞牛影视 搭建媒体库的用户
• 通过 BT 或自动化工具（如 qBittorrent、Aria2）下载番剧和影视的用户
• 需要将下载文件以标准结构接入媒体库服务器，但不希望移动源文件的场景
• 跨平台用户（已在 Linux 和 Windows 环境下测试可用）

技术要点

• 不修改源文件：默认的软链接和硬链接模式不会改变源文件的位置或内容，媒体库读取目标目录时透明地映射到原始文件。
• 字幕文件语言标签保留：自动识别字幕文件名中包含的语言代码（简体中文 .sc、英文 .en 等），在目标文件名中保留标签，便于媒体库区分多语言字幕。
• 目录自清理：运行工具的目录应只包含需要处理的媒体文件。工具默认跳过常见的非媒体文件（.txt、.nfo、.jpg、.png 等），可通过 --include-other 取消这一过滤。

许可

MediaLink 以 GPL-3.0 许可证发布，允许自由使用、修改和分发，但修改后的版本也必须以相同许可证发布。

MediaLink 由 This-is-XiaoDeng 开发维护。