Initial commit

.gitignore

@@ -0,0 +1,8 @@
+.env
+logs/
+backups/
+.trash/
+cache.json
+__pycache__/
+*.pyc
+.DS_Store

README.md

@@ -0,0 +1,197 @@
+# Plex Library Tool
+
+A single Python script that scans your Movies / TV Shows folders, looks each one up on [TMDb](https://www.themoviedb.org/), and renames everything into clean, Plex-friendly names: folders, video files, season folders, and subtitles.
+
+No installation, no dependencies, nothing to compile. It's one `.py` file that runs anywhere Python runs: Mac, Windows, or Linux.
+
+This guide assumes you've never used Python or GitHub before. If you already know your way around both, skip to [Quick Start](#quick-start).
+
+---
+
+## What it does
+
+- Matches your existing folder names against TMDb and renames them to `Movie Name (Year)` / `Show Name (Year)` format
+- Renames video files to match, and organizes TV episodes into `S01`, `S02`, etc. season folders
+- Finds subtitle files, figures out which one matches your primary language (by filename, and by reading the file's content/metadata if the filename doesn't say), and renames it to match the video. Defaults to English, but follows whatever language you've set for TMDb results (see [Non-English users](#non-english-users)).
+- Optionally cleans up junk files/folders (samples, `.nfo`, `.txt`, screenshots, unwanted-language subtitles) into a local trash folder. Nothing is deleted permanently, and every cleanup can be reversed.
+- Fully customizable naming convention (`names.yaml`): change `S01` to `Season 01`, use dots instead of spaces, uppercase everything, rename the "Subs" folder to something else, etc.
+- Every rename is logged, and can be undone with one command
+- Works on Mac, Linux, and Windows
+
+Nothing this script does is destructive by default. It asks for confirmation before renaming anything (unless you pass `-y`), and everything it changes is logged so it can be undone.
+
+---
+
+## Requirements
+
+- **Python 3.8 or later.** That's it. No other software or packages are required.
+- **A free TMDb account**, to get an API key. Takes about 2 minutes, and is covered below.
+
+---
+
+## Quick Start
+
+### 1. Install Python
+
+**Windows 11:**
+
+Open PowerShell (search "PowerShell" in the Start menu) and run:
+
+```
+winget install Python.Python.3.14
+```
+
+Close and reopen PowerShell afterward, then check it worked:
+
+```
+python --version
+```
+
+If `winget` doesn't work on your machine, download the installer from [python.org/downloads](https://www.python.org/downloads/) instead. **Important:** on the first screen of the installer, check the box that says **"Add python.exe to PATH"** before clicking Install. This is the single most common thing people miss, and without it Windows won't recognize the `python` command.
+
+**Mac:**
+
+Macs usually already have Python 3 installed. Open Terminal (search "Terminal" in Spotlight) and run:
+
+```
+python3 --version
+```
+
+If that fails, download the installer from [python.org/downloads](https://www.python.org/downloads/) and run it.
+
+**Linux:**
+
+Almost every Linux distribution comes with Python 3 preinstalled. Confirm with:
+
+```
+python3 --version
+```
+
+If it's missing, install it with your distro's package manager, e.g. `sudo apt install python3` on Ubuntu/Debian.
+
+### 2. Download this repository
+
+If you've never used GitHub before: this page is a "repository" (a folder of files), and you don't need a GitHub account or `git` installed just to download it.
+
+1. Click the green **"Code"** button near the top of this page
+2. Click **"Download ZIP"**
+3. Once it's downloaded, extract/unzip it somewhere you'll remember (e.g. your Desktop or Downloads folder)
+
+(If you do have `git` installed and prefer it, `git clone` this repository's URL instead.)
+
+### 3. Get a free TMDb API key
+
+The script uses [TMDb](https://www.themoviedb.org/) (The Movie Database) to look up correct titles and years. This is free.
+
+1. Log in or create a free account: <https://www.themoviedb.org/login>
+2. Request an API key: <https://www.themoviedb.org/settings/api/request>
+3. Choose **"Developer"** when asked what type of key
+4. Fill in the short form (you can use placeholder info for personal/non-commercial use)
+5. On the resulting settings page, copy the value labeled **"API Key"** (the short one, **not** the longer "API Read Access Token")
+
+You don't need to do anything with this key yet. The script will ask for it the first time you run it.
+
+### 4. Run it
+
+Open a terminal in the folder you extracted:
+
+- **Windows:** open the extracted folder in File Explorer, click the address bar, type `powershell`, and press Enter
+- **Mac/Linux:** open Terminal, then `cd` into the folder, e.g. `cd ~/Downloads/plex-library-tool`
+
+Then run:
+
+```
+python plex-library-tool.py -r
+```
+
+(On Mac/Linux, use `python3` instead of `python` if `python` isn't recognized.)
+
+The first time you run it, it'll ask you to paste in the TMDb API key from step 3, and offer to save it to a local `.env` file so you're never asked again. That file stays on your computer and is never uploaded anywhere.
+
+### 5. Point it at your media
+
+After the API key step, the script will either:
+- automatically find SMB/network shares mounted on your computer and let you pick one, or
+- you can skip that entirely by giving it a path directly:
+
+```
+python plex-library-tool.py -r "/path/to/your/Movies"
+```
+
+```
+python plex-library-tool.py -r "D:\Movies"
+```
+
+It'll then walk through each folder, look it up, show you the proposed rename, and ask for confirmation before doing anything.
+
+**Tip:** before renaming anything for real, run it with `-t` (test mode) first to preview what it *would* do without changing anything:
+
+```
+python plex-library-tool.py -r "/path/to/your/Movies" -t
+```
+
+---
+
+## Command reference
+
+| Flag | What it does |
+|---|---|
+| `-r`, `--rename [PATH]` | Scan and rename a share. Pass a path to skip the share-selection prompt. |
+| `-c`, `--cleanup [PATH]` | Move junk files/folders (per `delete.yaml`) to a local trash folder. |
+| `-t`, `--test [N]` | Preview only. No changes are made. Optionally limit how many folders are shown. |
+| `-y`, `--yes` | Don't ask for confirmation before each rename. |
+| `-f`, `--force` | Force a full scan even if nothing looks like it changed since the last run. |
+| `-v`, `--verbose` | Print detailed diagnostic output about what the script is doing and why. |
+| `-m`, `--manual-rename CURRENT NEW` | Manually rename one specific folder/file, bypassing TMDb entirely. |
+| `--backup` | Snapshot current names to a log file without changing anything. |
+| `--restore [LOGFILE]` | Undo a previous run using its log file. Pick from a list if no file is given. |
+| `-u`, `--undo` | Instantly undo the most recent run, no need to look up a log filename. Can't be combined with any other flag. |
+
+Flags can be combined, e.g. `-rc` runs rename and cleanup back to back on the same share, `-rf` forces a full rename scan, `-ty` previews everything without prompting.
+
+---
+
+## Configuration files
+
+These live alongside the script and are all optional. The script works out of the box with sensible defaults. Every file is fully documented with comments and examples inside it.
+
+- **`names.yaml`**: customize the naming convention. Folder/file name format, season folder naming (`S01` vs `Season 01`), separators (spaces vs dots vs underscores), uppercase/lowercase, whether to include resolution tags like `1080p`, and the subtitle folder name (e.g. rename "Subs" to "Subtitles" or any word in your own language).
+- **`delete.yaml`**: what cleanup moves to trash. Folder name patterns (e.g. `sample`, `extras`), file name/extension patterns, and subtitle language rules (e.g. "only keep Spanish subtitles").
+
+---
+
+## Non-English users
+
+TMDb can return movie/show titles in your own language instead of English (e.g. Spanish, French, German titles). The first time you run the script, it detects your system's language and asks you to confirm before saving it to `.env`. You can also set it yourself at any time by adding a line to `.env`:
+
+```
+TMDB_LANGUAGE=es-MX
+```
+
+Use any TMDb-supported language code (ISO 639-1, optionally with a region, e.g. `en-US`, `fr-FR`, `de-DE`, `ja-JP`). This also decides which subtitle language is treated as primary: whichever subtitle file matches `TMDB_LANGUAGE` gets renamed to match the video (e.g. `Movie.es.srt` for Spanish), and everything else keeps its original filename. The script's own prompts and status messages (like "Renamed folder:") stay in English regardless of this setting.
+
+---
+
+## Safety
+
+- **Nothing is renamed without asking first**, unless you pass `-y`.
+- **Every rename is logged** to a `logs/` folder created next to the script.
+- **Cleanup never permanently deletes anything.** Matched files/folders are moved to a local `.trash/` folder, not deleted, and you're prompted per item unless `-y` is used.
+- **Undo anytime** with `-u` (most recent run) or `--restore <logfile>` (any past run).
+- **Your TMDb API key is never uploaded anywhere.** It's stored locally in a `.env` file, which is excluded from Git via `.gitignore`.
+
+---
+
+## Troubleshooting
+
+**`'python' is not recognized as an internal or external command`** (Windows)
+Python isn't on your PATH. Reinstall using the winget command above, or rerun the python.org installer and make sure "Add python.exe to PATH" is checked.
+
+**`No SMB shares found.`**
+The script couldn't auto-detect a network share. Pass the path directly instead: `python plex-library-tool.py -r "Z:\Movies"` (Windows) or `python plex-library-tool.py -r "/Volumes/Movies"` (Mac).
+
+**`No match found (Ignoring): <name>`**
+TMDb couldn't confidently match that folder to a title. This is intentionally conservative: the script would rather skip a folder than rename it wrong. You can rename it manually with `-m "current name" "new name"`, or clean up the raw folder name a bit and try again.
+
+**I want to undo something**
+Run `python plex-library-tool.py -u` to instantly undo the most recent run, or `python plex-library-tool.py --restore` to pick from any past run.

delete.yaml

@@ -0,0 +1,155 @@
+# delete.yaml
+#
+# Configures what cleanup (-c) moves to a local trash folder. Nothing here
+# is deleted permanently -- matched items are moved to a .trash folder next
+# to the script, and every move can be undone. All three sections below are
+# optional and independent; enable only the ones you want.
+#
+# ============================================================================
+# folders
+# ============================================================================
+#
+# Folder names to move to trash during cleanup.
+#
+# - Matching is case-insensitive.
+# - Matches the folder's full name -- e.g. "Screens" matches a folder named
+#   "Screens" or "screens", but not "My Screens" or "Screenshots".
+# - Wildcards are supported: "*" matches any run of characters and "?"
+#   matches a single character, so you can match partial or variable names.
+#   For example "* Potato" matches "123 Potato" or "Mr Potato", and
+#   "Potato*" matches "Potato Salad" or "Potatoes". A pattern with no
+#   wildcard still has to match the whole folder name exactly.
+# - Any folder anywhere in the scanned share with a matching name will be
+#   moved to trash, along with everything inside it. There is no
+#   confirmation beyond the normal cleanup run prompts, so double check
+#   this list before running for real.
+#
+# Uncomment and edit the list below to enable:
+#
+# folders:
+#   - Screens
+#   - Featurettes
+#   - Extras
+#   - Sample
+#   - Samples
+#   - Behind the Scenes
+#   - Deleted Scenes
+#   - Trailers
+#   - Interviews
+#   - Bonus
+#
+# ============================================================================
+# files
+# ============================================================================
+#
+# Files to move to trash during cleanup.
+#
+# - Matching is case-insensitive.
+# - Entries can be:
+#     - a full filename, e.g. "potato.txt" matches only a file named
+#       exactly "potato.txt" (or "Potato.TXT", etc.)
+#     - an extension pattern, e.g. "*.txt" matches any file ending in .txt
+#     - a wildcard pattern, e.g. "* potato.txt" matches "123 potato.txt" or
+#       "Mr potato.txt"; "?otato.txt" matches "potato.txt" or "Xotato.txt"
+#       ("*" matches any run of characters, "?" matches a single character)
+#     - an exclusion pattern, prefixed with "!", e.g. "!*.en.*" protects any
+#       file matching that pattern from deletion, even if another entry
+#       above would otherwise match it. A file is only deleted if it
+#       matches at least one non-"!" entry and matches none of the "!"
+#       entries.
+#     - the special exclusion "!language:en" protects English subtitle
+#       files (.srt, .sub, .idx) from deletion specifically, even when the
+#       filename has no language tag at all. It's hardcoded to English --
+#       the "subtitles:" section below is the friendlier, language-agnostic
+#       way to protect or target any language, including your own.
+# - Video file extensions (mp4, mkv, avi, etc.) are never deleted by
+#   cleanup, even if a pattern here would otherwise match them.
+#
+# Uncomment and edit the list below to enable:
+#
+# files:
+#   - "*.txt"
+#   - "*.nfo"
+#   - "*.jpg"
+#   - "*.jpeg"
+#   - "*.png"
+#   - "*.ico"
+#   - "*.url"
+#   - "*.sfv"
+#
+# ============================================================================
+# subtitles
+# ============================================================================
+#
+# A separate, language-aware way to manage .srt/.sub/.idx files without
+# needing to list those extensions under "files:" above -- this section
+# handles them on its own.
+#
+# - Entries are language names (or common codes), matched case-insensitively:
+#   "English", "en", "eng" all mean the same thing. Covers ~80 languages
+#   (see the script's LANGUAGE_CANONICAL table for the full list).
+# - Prefix an entry with "!" to KEEP that language and delete every other
+#   identified language. Use this if you only want one (or a few)
+#   languages kept -- replace "Spanish" below with whichever language you
+#   actually want to keep:
+#
+#     subtitles:
+#       - "!Spanish"
+#
+#   This deletes any subtitle file identified as a language other than
+#   Spanish, and leaves Spanish, and anything the tool can't confidently
+#   identify a language for, untouched.
+#
+# - An entry WITHOUT "!" means "delete just this language, leave every
+#   other language (including unidentified files) alone." Use this to
+#   strip out one unwanted language without being aggressive about
+#   everything else:
+#
+#     subtitles:
+#       - "English"
+#
+#   This deletes only English-identified subtitle files. Everything else,
+#   including unidentified files, is left as-is.
+#
+# - Language is identified from the filename first (e.g. "Movie.es.srt",
+#   "Movie.Spanish.srt"). If the filename has no language tag at all
+#   (e.g. a bare "Movie.srt"), the file's own content is read as a
+#   fallback: .idx files have a real "id: xx" language field, and .srt
+#   files are analyzed by script (Cyrillic, CJK, Arabic, etc.) and common
+#   word frequency for Latin-script languages. This is a best-effort
+#   heuristic for .srt content, not a guarantee, and always errs toward
+#   leaving a file alone if the result is unclear.
+#
+# Uncomment and edit to enable (replace "Spanish" with your own primary
+# language, or whichever language you want to keep):
+#
+# subtitles:
+#   - "!Spanish"
+
+ folders:
+   - Screens
+   - Featurettes
+   - Extras
+   - Sample
+   - Samples
+   - Behind the Scenes
+   - Deleted Scenes
+   - Trailers
+   - Interviews
+   - Bonus
+   - "* torrent"
+   - "* torrents"
+
+files:
+   - "*.txt"
+   - "*.nfo"
+   - "*.jpg"
+   - "*.jpeg"
+   - "*.png"
+   - "*.ico"
+   - "*.url"
+   - "*.sfv"
+   - "*.part"
+
+subtitles:
+  - "!English"

names.yaml

@@ -0,0 +1,76 @@
+# names.yaml
+#
+# Customize the naming convention used when renaming folders and files.
+# Uses Python's str.format() syntax: {token} for a plain value, or
+# {token:02d} to zero-pad a number to 2 digits, {token:03d} for 3, etc.
+#
+# Any line you don't include (or leave commented out) falls back to the
+# default shown below, so you only need to uncomment the ones you want
+# to change.
+#
+# Available tokens per line:
+#   movie_folder          {title} {year} {resolution}
+#   movie_folder_no_year   {title} {resolution}         (used when no year is found)
+#   show_folder            {title} {year} {resolution}
+#   show_folder_no_year     {title} {resolution}         (used when no year is found)
+#   movie_file              {title} {ext} {resolution}
+#   episode_file            {title} {season} {episode} {ext} {resolution}
+#   season_folder           {season}
+#   subtitle_file           {stem} {ext} {lang}   (stem = matching video's name, no extension; lang = TMDB_LANGUAGE's code, e.g. "en", "es", "fr")
+#   subtitle_folder         (no tokens -- just the folder name, e.g. "Subs", "Subtitles", or a word in your own language)
+#
+# The subtitle identified as matching TMDB_LANGUAGE (set in .env, see the
+# README) is treated as the primary one and renamed to match the video,
+# e.g. "Movie.es.srt" if TMDB_LANGUAGE is Spanish. If none of the subtitle
+# files can be matched to that language, an untagged one is used as a
+# best guess. Everything else keeps its original filename and is just
+# moved into the subtitle folder.
+#
+# {resolution} is opt-in -- it's detected from the original folder/file name
+# (720p, 1080p, 2160p, 4K, etc.) but NONE of the default templates above
+# reference it, so nothing changes unless you add {resolution} to a
+# template yourself, e.g. movie_folder: "{title} ({year}) [{resolution}]".
+# If no resolution is found, it renders as an empty string, and an empty
+# bracket/paren pair left behind by that (like "[]" or "()") is
+# automatically cleaned up.
+#
+# word_separator controls what replaces spaces INSIDE the {title} value
+# itself (the title comes back from TMDb as "Movie Name", space-separated).
+# Leave it as a single space for "Movie Name", or set it to "." for
+# "Movie.Name", "_" for "Movie_Name", etc. This only affects {title} --
+# combine it with the templates below to fully control the look, e.g.
+# word_separator: "." together with movie_folder: "{title}.{year}" gives
+# you "Movie.Name.2020" instead of "Movie Name (2020)".
+#
+# name_case forces the case of every rendered folder/file name (the whole
+# name, not just the title). Leave blank for the title case TMDb returns,
+# or set to "lower" for "movie name (2020)" / "movie.name.2020.mkv", or
+# "upper" for "MOVIE NAME (2020)" / "MOVIE.NAME.2020.MKV".
+#
+# Filesystem-illegal characters (< > : " / \ | ? *) are stripped from the
+# result automatically, so it's safe to use punctuation like colons if you
+# want -- it just won't survive into the final name.
+#
+# Examples:
+#   episode_file: "{title} - {season}x{episode:02d}.{ext}"   -> "Show - 1x05.mkv"
+#   season_folder: "Season {season:02d}"                      -> "Season 01"
+#   movie_folder: "{title} [{year}]"                          -> "Movie [2020]"
+#   word_separator: "."                                       -> "Movie.Name" instead of "Movie Name"
+#   name_case: "lower"                                        -> "movie name (2020)"
+#   movie_folder: "{title} ({year}) [{resolution}]"           -> "Movie (2020) [1080p]"
+#   subtitle_folder: "Subtitles"                               -> subs get consolidated into a "Subtitles" folder instead of "Subs"
+#   subtitle_folder: "Untertitel"                              -> or any word in your own language
+#
+# Uncomment and edit any of the lines below to enable:
+#
+# movie_folder: "{title} ({year})"
+# movie_folder_no_year: "{title}"
+# show_folder: "{title} ({year})"
+# show_folder_no_year: "{title}"
+# movie_file: "{title}.{ext}"
+# episode_file: "{title} S{season:02d}E{episode:02d}.{ext}"
+# season_folder: "S{season:02d}"
+# subtitle_file: "{stem}.{lang}.{ext}"
+# subtitle_folder: "Subs"
+# word_separator: " "
+# name_case: ""