jellyfin-renaming

name	jellyfin-renaming
description	Manually rename Jellyfin movie, TV show, anime, special episode, external subtitle, external audio, movie directory, and TV show directory names for reliable library matching. Use when the user wants to automatically rename real media files or folders on disk, clean messy release filenames, convert files to Jellyfin movie or SxxExx show naming, align subtitles with videos, preserve traceability, or verify Jellyfin-compatible media naming without using bulk renaming scripts or paid renaming tools.
license	MIT

Jellyfin Renaming

Manually decide and apply Jellyfin-compatible movie and TV show file and directory renames. Treat every rename as a reviewed mapping, not a blind bulk text transformation.

Core Rule

When the user gives real filesystem paths and asks to rename media, perform the rename on disk after building and checking a mapping. If the user gives only a list of names or explicitly asks for suggestions, return exactly one output filename for each input filename, in the same order.

If a movie, episode, special, subtitle, audio track, version label, or language suffix cannot be identified with confidence, keep the original name.

Absolute Prohibition: Never Delete Files

Never delete any file under any circumstance. Every operation that would remove a file must instead move that file to a Rubbish/ folder inside the affected movie or show folder. This rule has no exceptions — not for duplicates, not for noise files, not for files the user calls "junk". After all operations are complete, always remind the user:

⚠️ Please review the Rubbish/ folder and delete it manually when you are sure the files inside are no longer needed.

Manual Workflow

Step	What to do
1. Identify context	Use the movie or series title, year, season, folder name, and surrounding files before deciding a final name.
2. Remove noise	Drop release group, source, codec, resolution, audio channel, CRC/hash, website, and bracketed download tags unless they are needed as movie version labels.
3. Preserve evidence	Keep extensions, subtitle language/flag suffixes, multi-episode ranges, split-part markers, edition/version labels, and meaningful special labels.
4. Match Jellyfin	Prefer official Jellyfin movie and show patterns, including movie folders, season folders, SxxExx markers, version labels, and external-track suffixes.
5. Refuse guesses	If the input does not contain enough information, output the original filename unchanged.
6. Check safety	Before renaming, check for path collisions, invalid characters, case-only conflicts, and ambiguous matches.
7. Apply carefully	Rename files before parent directories when needed; rename deeper paths before shallower paths.
8. Record traceability	After completing all renames for a movie or show, create a rename log that records every original path and final path.

Automatic Rename Execution

Use this workflow when the user asks to rename actual directories or files.

Step	Requirement
Plan first	Before executing any filesystem operation, output a numbered step-by-step plan listing every rename, every move-to-Rubbish, and every new directory to be created. Wait for implicit or explicit user acknowledgement, then execute the steps one by one in the listed order.
Inventory	List only the target movie/show folder and the files needed for the task. Do not modify unrelated media.
Mapping	Build a reviewed old-path to new-path mapping for files and directories.
Conflict check	Stop before renaming if two sources map to the same target, a target already exists, or a rename would move media outside the intended folder.
Directory order	Rename files first, then season folders, then show/movie folders. For nested directory renames, process deepest paths first.
Case-only renames	On case-insensitive filesystems, use a temporary intermediate name before applying a case-only rename.
Subtitle pairing	Rename subtitles and external audio after the corresponding video basename is finalized.
Unwanted files	Never delete files directly. Move any file that should be removed to Rubbish/ inside the affected movie or show folder. After all operations are complete, remind the user to review Rubbish/ and delete it manually.
Log	Create or append rename-log.md in the affected movie or show folder after the rename succeeds.

Do not use generic bulk renaming scripts or paid renaming tools. It is acceptable to use normal filesystem operations to apply the reviewed mapping.

TMDB Lookup Script

Use the local TMDB helper when a movie or series title, year, media type, or provider id needs confirmation before renaming.

Requirements:

Item	Details
Environment variable	TMDB_API_KEY must contain a TMDB API read access token.
Working directory	Run commands from skills/jellyfin-renaming/scripts/.
Output	The script prints JSON records with id, title, original_title, overview, release_date, media_type, vote_average, and poster_path.

Commands:

uv run tmdb.py "Movie or Show Title"
uv run tmdb.py "Movie or Show Title" --lang en-US --limit 5 --pretty
uv run tmdb.py --help

Use TMDB results as supporting evidence, not as an automatic rename source. Pick the result that matches the surrounding files, release year, original title, and media type.

Jellyfin Movie Rules

Use these rules for Movies libraries.

Item	Preferred format	Notes
Movie folder	Movie Name (year) [providerid-id]	Each movie should have its own folder. year and provider id are optional, but improve matching. Examples: [tmdbid-12345], [imdbid-tt0000000].
Main movie file	Movie Name (year) [providerid-id].ext	The video filename should match the folder name exactly, before the extension.
Movie with no year	Movie Name/Movie Name.ext	Acceptable, but less reliable for matching.
External subtitle or audio	Movie Name (year).language-or-flags.ext	The basename should match the movie video basename. Use dot-separated language, title, and flag suffixes.
Disc folders	VIDEO_TS or BDMV inside the movie folder	Supported for movies and music videos, but not for multiple versions, multiple parts, or external subtitle/audio tracks.
Disc images	.iso and similar	May work but are not supported. Prefer remuxing to mkv or extracting to VIDEO_TS or BDMV.

Movie Versions

Jellyfin supports multiple versions of the same movie in one movie folder only when every version filename begins with the parent folder name exactly.

Movie (2021) [imdbid-tt12801262]/
Movie (2021) [imdbid-tt12801262] - 2160p.mp4
Movie (2021) [imdbid-tt12801262] - 1080p.mp4
Movie (2021) [imdbid-tt12801262] - Directors Cut.mp4

Rules:

Requirement	Details
Exact prefix	The filename must start with the folder name character-for-character, including year and provider id.
Version separator	Use space, hyphen, space: -. The hyphen is required.
Version label	Labels are user-defined, such as 2160p, 1080p, Directors Cut, or [Extended Cut].
Avoid unsupported separators	Do not use periods or commas as the version separator.
Missing label	Without a version label, Jellyfin may treat files as separate movies.

3D Movies

Preserve 3D tags when present. The first 3D tag must be 3D, combined with one supported format tag.

3D format	Flag
half side by side	hsbs
full side by side	fsbs
half top and bottom	htab
full top and bottom	ftab
Multiview Video Coding	mvc

Valid examples:

Awesome 3D Movie (2022).3D.FTAB.mp4
Awesome 3D Movie (2022)_3D_htab.mp4
Awesome 3D Movie (2022)-3d-hsbs.mp4
Awesome 3D Movie (2022) - 3D_FTAB.mp4

Multi-Part Movies

For one movie split across multiple files, preserve supported part markers.

Movie Name (2010)/
Movie Name-cd1.mkv
Movie Name-cd2.mkv
Movie Name-cd3.mkv

Supported part types: cd, dvd, part, pt, disc, disk.

Supported separators between part type and part number: space, ., -, _, or no separator. Part numbers can be numbers or letters a through d.

Do not combine multi-part naming with multiple-version naming.

Jellyfin TV Show Rules

Use these rules for Shows libraries.

Item	Preferred format	Notes
Series folder	Series Name (year) [providerid-id]	year and provider id are optional, but improve matching.
Season folder	Season 01	Officially Season *; do not abbreviate to S01 or SE01. Padding with zeroes is recommended.
Regular episode	Series Name S01E01.ext	Title may be appended if useful: Series Name S01E01 Episode Title.ext.
Multi-episode file	Series Name S01E01-E02.ext	Jellyfin displays it as one entry with metadata from multiple episodes. Prefer split files when possible.
Split same episode	Series Name S02E03 Part 1.ext, Series Name S02E03 Part 2.ext	Use only when one episode is split across multiple files.
Specials with provider metadata	Season 00/Series Name S00E01.ext	Special numbering varies by metadata provider. Verify before assigning numbers.
Specials without provider metadata	Season 00/Descriptive Special Name.ext	Prefer a descriptive name over guessed S00E## to avoid wrong metadata.

Episode Renaming

When the user provides a series name and season, normalize regular episodes to:

Series Name S01E01.ext

Rules:

Situation	Output
Single regular episode	Series Name S01E01.ext
Consecutive combined episodes	Series Name S01E07-E08.ext
Existing correct SxxExx	Keep the episode marker; only remove obvious noise if the user asked for cleanup.
Absolute anime numbering only	Convert only if the season/episode mapping is clear from context or metadata; otherwise keep original.
No reliable episode marker	Keep original filename.

Do not invent episode titles. Include titles only when they are already clear and useful.

Anime Specials, OP, ED, OVA, OAD

Anime downloads often label extras as OP, NCOP, ED, NCED, SP, OVA, or OAD. Handle them carefully:

Case	Jellyfin-safe choice
Metadata provider has a matching special number	Put under Season 00 and use Series Name S00E##.ext.
No known provider special number	Use a descriptive filename in Season 00, such as NCOP 01.ext or OVA 01.ext.
User specifically wants suffix-style extras	Use Jellyfin extra suffixes such as -extra, -clip, -featurette, or .trailer only when appropriate.

Keep the original special type label when it matters. Do not force every OP/ED/OVA into a guessed S00E##.

Subtitle and Audio Matching

External subtitles and audio tracks should share the exact video basename, then add dot-separated language, title, or flag parts before the final extension.

Film (1986).mkv
Film (1986).default.en.forced.ass
Series Name S01E01.mkv
Series Name S01E01.ja.ass
Series Name S01E01.commentary.ja.aac

Supported flags include default, forced, foreign, sdh, cc, and hi. Multiple suffix parts are dot-separated.

When matching subtitle files to renamed videos:

Rule	Behavior
Subtitle clearly matches one video	Rename subtitle basename to the video basename and keep language/flag suffixes.
Subtitle has .ass, .ssa, .srt, .vtt, or similar extension	Preserve the subtitle extension exactly.
Subtitle has language suffixes such as .sc, .tc, .chs, .cht, .ja, .en, or .en_us	Preserve those suffixes unless the user asks to normalize language codes.
Multiple possible video matches	Keep the subtitle filename unchanged.
Subtitle list order matters	Return subtitle outputs in the exact order provided by the user.

Extras Reference

Jellyfin recognizes movie, show, season, and music-video extras by folder, exact filename, or suffix.

Method	Supported values
Extra folders	behind the scenes, deleted scenes, interviews, scenes, samples, shorts, featurettes, clips, other, extras, trailers, theme-music, backdrops
Exact filenames	trailer.ext, sample.ext
Extra suffixes	-trailer, .trailer, _trailer, trailer, -sample, .sample, _sample, sample, -scene, -clip, -interview, -behindthescenes, -deleted, -deletedscene, -featurette, -short, -other, -extra

Use extras only when the file is truly supplemental. Do not turn normal show specials or OVAs into extras if they are listed as episodes by the metadata provider.

Movie Images

Jellyfin supports local artwork files placed directly inside the movie folder. Local files take priority over artwork fetched from online metadata providers.

Generic Image Filenames

Use these filenames inside the movie folder for Jellyfin to recognize them automatically:

Image type	Accepted filenames	Notes
Primary (poster)	poster.jpg, folder.jpg, cover.jpg	Main movie cover shown in library grids.
Backdrop (fanart)	backdrop.jpg, backdrop.webp	Background shown on the movie detail page.
Logo	logo.png, logo.svg	Transparent title logo overlaid on artwork.
Banner	banner.jpg	Wide strip image used in banner view.
Thumb	thumb.jpg	Landscape thumbnail used in some views.
Art (clearart)	art.png	Character art or promotional transparent PNG.
Disc	disc.png, disc.jpg	Disc cover used in some themes.

Multiple backdrops are supported by appending a number:

Movie Name (2020)/
  Movie Name (2020).mkv
  poster.jpg
  backdrop.jpg
  backdrop-1.jpg
  backdrop-2.jpg
  logo.png

Media-Prefixed Image Filenames

Alternatively, name the image with the same basename as the video file and append a hyphen-separated image type:

Image type	Filename pattern	Example
Primary (poster)	<video-basename>-poster.ext	Movie Name (2020)-poster.jpg
Backdrop	<video-basename>-backdrop.ext	Movie Name (2020)-backdrop.jpg
Logo	<video-basename>-logo.ext	Movie Name (2020)-logo.png
Banner	<video-basename>-banner.ext	Movie Name (2020)-banner.jpg
Thumb	<video-basename>-thumb.ext	Movie Name (2020)-thumb.jpg

Using generic filenames (poster.jpg, backdrop.jpg) is preferred for simplicity. Use media-prefixed filenames when multiple image sets must coexist in the same folder.

Supported Image Formats

.jpg, .jpeg, .png, .webp, .gif, .bmp, .tbn

Prefer .jpg for photos and .png for transparent images such as logos and clearart.

Image Handling Rules

Rule	Behavior
Local files present	Jellyfin uses local files and skips fetching that image type from online providers.
Multiple backdrops	backdrop.jpg is the primary; backdrop-1.jpg, backdrop-2.jpg, … are additional.
No local image	Jellyfin fetches and caches the image from the configured metadata provider.
Embedded images	Jellyfin can extract artwork embedded in video containers if the Embedded Image Extractor plugin is enabled in library settings.
Metadata refresh	After adding image files to an existing folder, run a library scan or trigger Refresh Metadata to apply them.

Image Renaming Guidelines

When renaming a movie folder or its video files, rename or verify image files in the same pass:

• Generic image filenames (poster.jpg, backdrop.jpg) do not need renaming when the movie folder is renamed; they stay in place.
• Media-prefixed image filenames must be updated to match the new video basename.
• Do not remove or discard existing local artwork files unless the user explicitly requests it.
• Record image file renames in the rename log alongside video and subtitle renames.

Rename Log

After all files and directories for a movie or show have been renamed, create a log file in that movie or show folder so the original paths can be traced later.

Recommended log filename:

rename-log.md

Recommended content:

# Rename Log

- Media: Movie or Series Name (year)
- Date: YYYY-MM-DD
- Scope: movie, season, show, subtitles, or mixed

| Original filename | New filename | Notes |
| ----------------- | ------------ | ----- |
| Original.Name.1080p.x265.mkv | Movie Name (2020).mkv | Removed release noise. |

Rules:

Requirement	Details
Record every rename	Include renamed directories, video files, subtitle files, audio tracks, NFO files, and relevant extra files.
Use paths when executing	When actual filesystem renames were performed, record relative paths from the affected movie or show folder, not just basenames.
Preserve unchanged files when useful	If a file or directory was reviewed but left unchanged because it was uncertain or already correct, record that in Notes.
Keep the log local	Store the log in the affected movie or series folder, not in a global location.
Do not overwrite history	Append a new dated section if rename-log.md already exists.

Execution and Output Contract

When asked to rename real files or directories:

Requirement	Details
Apply renames	Perform the filesystem renames after the mapping and safety checks pass.
Stop on ambiguity	If any planned rename is ambiguous or unsafe, do not partially apply that group; report what needs clarification.
Report concise results	Summarize what was renamed and where the log was written.
Preserve extensions	Keep .mkv, .mp4, .ass, .ssa, .srt, .vtt, .aac, etc.
Preserve uncertainty	Keep original filenames when unsure.
Avoid filesystem-invalid characters	Do not introduce <, >, :, ", /, \, `
Never delete directly	Move any file that would be deleted to a Rubbish/ folder inside the affected movie or show folder instead of removing it. After all operations complete, remind the user: "Please review Rubbish/ and delete it manually when you are sure the files are no longer needed."

When asked only to generate proposed filenames:

Requirement	Details
No explanation	Output filenames only unless the user asks for reasoning or a rename log.
One line per input	Preserve count and order exactly.
Preserve extensions	Keep .mkv, .mp4, .ass, .ssa, .srt, .vtt, .aac, etc.
Preserve uncertainty	Keep original filenames when unsure.
Avoid filesystem-invalid characters	Do not introduce <, >, :, ", /, \, `

Common Corrections

Problem	Prefer
Movie.Name.2020.1080p.x265.mkv	Movie Name (2020).mkv
Movie Name (2020) 4K.mkv	Movie Name (2020) - 4K.mkv when it is a version label.
Movie Name (2020).Directors.Cut.mkv	Movie Name (2020) - Directors Cut.mkv
Movie version filename does not start with folder name	Start with the exact folder name, then add - Version Label.
Season S01/ or S01/	Season 01/
Show S1E1.mkv	Show S01E01.mkv
Show 01.mkv with known season	Show S01E01.mkv
Show S01 E01.mkv	Show S01E01.mkv
Show S01E01 [1080p][x265][AAC].mkv	Show S01E01.mkv
subtitle.ass for a known video	Show S01E01.ass or Movie Name (2020).ass
Guessed special number	Keep descriptive name or original filename until verified.

Quality Checklist

• Confirm output line count equals input line count.
• Confirm every extension is preserved.
• Confirm movie files match their movie folder basename unless they are versions, 3D variants, or multi-part files.
• Confirm movie version files start with the exact folder name and use - before the label.
• Confirm subtitle language, title, and flag suffixes are preserved.
• Confirm multi-episode and multi-part ranges remain represented.
• Confirm no guessed episode, special, movie year, or provider id was introduced.
• Confirm season folders are Season *, preferably padded such as Season 01.
• Confirm rename-log.md is created or appended after the full movie or show rename is complete.