SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsjellyfin

jellyfin

General & other

View repository

Updated 10-16 08:11

About this skill

Jellyfin Media Library Renaming Tool

Configuration

In agent_config.toml add the OMDb configuration (apply for a free API Key from https://www.omdbapi.com/apikey.aspx ):

[jellyfin.omdb]
base_url = "http://www.omdbapi.com"
api_key = "your_api_key_here"

Configuration file search order: current directory → skill directory → git root directory.

How to Run

# 变量定义（SKILL_DIR 为本 skill 的绝对路径）
SKILL_DIR="/path/to/skills/jellyfin"
uv run --project "$SKILL_DIR/scripts" "$SKILL_DIR/scripts/jellyfin_tool.py" <command> [options]

Command

clean — batch clean up spaces

Traverse all subfolders under the specified directory, remove spaces from folder names and file names, and rename images to {视频名}-poster{ext}。

# 预览（不执行）
uv run --project "$SKILL_DIR/scripts" "$SKILL_DIR/scripts/jellyfin_tool.py" clean /path/to/media --dry-run

# 执行（跳过确认，适合 agent 使用）
uv run --project "$SKILL_DIR/scripts" "$SKILL_DIR/scripts/jellyfin_tool.py" clean /path/to/media --yes

rename — smart renaming (Jellyfin conventions + IMDB ID)

Parse BT/fansub-style folder names, query the OMDb API to obtain the IMDB ID, and rename according to Jellyfin standards.

Output Format：

  • Movie folder:Movie Name (year) [imdbid-ttXXXXXXXX]
  • Movie video file:Movie Name (year) [imdbid-ttXXXXXXXX].mkv
  • Series folder:Show Name (year) [imdbid-ttXXXXXXXX]
  • Series video file:Show Name S01E01.mkv
  • Images: primary image Name (year) [imdbid-ttXXXXXXXX]-poster.jpgaccording to Jellyfin conventions extrafanart/fanart1.jpg、extrafanart/fanart2.jpg …
  • Subtitles: subtitles whose filenames are the same as a video (or only have extra language tags such as .chs ) will be renamed along with that video, making it easier for Jellyfin to mount them; subtitles that cannot match any video keep their original names
# 单个文件夹（自动检测是电影还是剧集）
uv run --project "$SKILL_DIR/scripts" "$SKILL_DIR/scripts/jellyfin_tool.py" rename "/path/to/Movie.Name.2020.1080P" --dry-run

# 批量处理整个目录（--exclude 跳过无需处理的子目录，可多次使用）
uv run --project "$SKILL_DIR/scripts" "$SKILL_DIR/scripts/jellyfin_tool.py" rename /path/to/Movies/ --batch --exclude Film --exclude H --dry-run

# 手动指定标题（当自动解析不准时）
uv run --project "$SKILL_DIR/scripts" "$SKILL_DIR/scripts/jellyfin_tool.py" rename "/path/to/folder" --title "The Matrix" --year 1999

# 手动指定 IMDB ID（当 API 返回候选列表时使用）
uv run --project "$SKILL_DIR/scripts" "$SKILL_DIR/scripts/jellyfin_tool.py" rename "/path/to/folder" --imdb-id tt0133093 --yes

# 强制指定为剧集类型
uv run --project "$SKILL_DIR/scripts" "$SKILL_DIR/scripts/jellyfin_tool.py" rename "/path/to/folder" --type series

Typical Workflow

  1. Preview first: always first use --dry-run to check whether the parsing result is correct
  2. Clean up noisy folder names: if a folder name contains site ads (such as "xxx.电影港 地址发布页 www.dygang.me 收藏不迷路"), the entire Chinese name will be carried into the new name, so first mv clean it into a clean Chinese title before rename
  3. Handle the candidate list: if the API returns multiple candidates, select the correct IMDB ID from the list and then use --imdb-id to retry
  4. When specifying an IMDB ID, also provide --title/--year: the OMDb API occasionally times out; when--imdb-id the query fails, it will fall back to --title/--year, and providing both ensures the fallback name is also correct
  5. Batch processing: when using --batch , failed folders will be summarized at the end; handle them one by one with --imdb-id Post-processing
  6. Confirm execution: after the preview is correct, remove --dry-run and add --yes to execute

Supported File Formats

  • Video:.mp4 .mkv .avi .wmv .mov .ts .m2ts .flv .rmvb
  • Images (poster/fanart):.jpg .jpeg .png .webp .gif .tbn
  • Subtitles:.srt .ass .ssa .sub .vtt(those that can match a video are renamed along with the video; the rest keep their original filenames)