📖 User Guide

In a nutshell: drop a folder of messy movie or TV-show downloads - the app cleans the filenames, organises them into the standard Title (Year)/ or Show/Season XX/ layout, and scrapes full metadata (NFO, posters, fanart, cast photos, per-episode data for TV). A complete, library-ready result on its own; CineLibrary then browses it.

1. Install & first launch

1. Download the latest CineLibraryEssentials_Setup_<version>.exe from the Releases page.
2. Run it. The installer is per-user (no admin required), self-contained (no .NET / WindowsAppSDK to install separately), and roughly 58 MB.
3. Pick an install location, optionally tick desktop / Start Menu shortcut, and finish.

When the app launches you'll see three step pills at the top - ① Clean Names › ② Organize › ③ Scrape. Click any pill to jump to that step. The active pill is filled with the accent colour.

There's no setup screen - the TMDb API key is embedded, so the app is ready to use immediately.

2. The 3-stage workflow

CineLibrary Essentials sits between your downloads and your final media library. The complete pipeline:

Downloads/             Step 1: Clean Names         Step 2: Organize         Step 3: Scrape                  CineLibrary
──────────             ────────────────────        ─────────────────        ──────────────────────          ───────────
movie.1080p.mkv  →     "Movie (Year).mkv"     →    Movie (Year)/       →    Movie (Year).nfo + art    →     Browse + play
Show.S01E01.mkv        "Show - S01E01.mkv"         Show/Season 01/          tvshow.nfo + episode NFOs       …

You don't have to do all three steps. The app supports several workflows:

You can skip steps in either direction at any time.

Movies and TV shows

CineLibrary Essentials handles both in the same wizard. A Mode selector at the top of Step 1 (and Step 3) decides how files are treated:

When you load a different folder, the mode switches back to Auto, so a mode you forced for one folder doesn't carry over to the next.

Organization differs by type. Folders are created right where your files already are (there is no separate output folder):

• Movies → Title (Year)/Title (Year).ext
• TV episodes → Show Name/Season 01/Show Name - S01E01.ext

If the original filename already contains the episode title, it's kept (Show - S01E01 - Title). Otherwise the real title comes from TMDb in Step 3 and is written into each episode's .nfo, which is where Kodi, Plex, Jellyfin and CineLibrary read it from. Want the title in the filename too? Turn on Settings → Add episode titles to file names (see Episode titles in file names).

Scraping differs too: movies get Title (Year).nfo + poster + fanart + .actors/; TV shows get tvshow.nfo + show artwork + cast at the root, plus a per-episode .nfo and thumbnail for each episode. Flat single-season folders (like Breaking Bad Season 1 Complete/) are recognized - the show name is read from the episode filenames, not the folder name. When such folders sit inside a folder named after the show (Dark/Dark Season 1 Complete/), or inside a folder that holds only that show's seasons (Billions (S1 S2 S3)/Billions S1/, GoT [Hindi]/Game of Thrones - Season 1 Complete (Hindi)/), they're seasons of that show: one card, with tvshow.nfo and the show's artwork in the show's folder. A folder that also holds another show or a movie is never taken for one show.

3. Step 1 - Clean Names

This is where messy filenames become clean ones. The app shows you a side-by-side preview of every video file and what it'll be renamed to - you review, edit if needed, then commit.

Loading files

Three ways:

1. Click the folder icon next to the Source box. Pick a folder. Done.
2. Click the ▾ on the folder button for a dropdown of recent folders.
3. Drag a folder from File Explorer onto the window. A dimmed overlay confirms the drop is accepted.

If you drop a file instead of a folder, the app uses the file's parent folder.

If the folder you load is a season folder (Season 01, Specials, or Dark Season 1 Complete inside a Dark folder), a message offers Use show folder. That loads the show's folder with Subfolders on, so every season is cleaned together and Steps 2 and 3 see the whole show.

Each row explained

Editing & bulk tools

You can fix names three ways:

• Type directly into the Cleaned field. Updates apply when you click out of the field.
• Bulk Find & Replace - type something in Find, something in Replace, click Replace. Affects every checked row.
• Select all box (left of the toolbar, also Ctrl+A) - ticks every row, or clears them all when everything is already ticked. A dash means some rows are ticked.
• More menu (top-right ⋯) - Apply Smart Title Case, Reset Auto-Cleaning.

Right-click any row for the same actions on just that one row, plus Open Containing Folder and Remove from List.

Keyboard shortcuts

Words to always remove

Some tags are never recognized automatically, like a release group's name (ION10, mSD) or a website watermark. Add them once in Settings → Words to always remove, one per line. They're matched as whole words, upper or lower case, and removed from every name the next time files are cleaned (the current list is cleaned again as soon as you close Settings).

Filters & search

• 🔍 Search box - live-filters by both original and cleaned name.
• Confidence dropdown - All / High / Medium / Low / Warnings / Needs renaming.
• Show only warnings - when any row has a ⚠, this link appears next to the file count at the bottom. One click shows just those rows; Show all files brings the rest back.
• Modified only toggle - quick way to hide rows where the cleaned name already matches the original.

Sorting

Click any of the three column headers - Original, Cleaned, Confidence - to sort by that column. Click again to reverse direction. The arrow next to the column name shows current state. Your sort choice is remembered between sessions.

TMDb search per row

When the parser isn't sure (or you just want to verify), click the 🔍 button on any row. A search dialog opens with the cleaned title and year pre-filled, a list of matches showing poster + plot + year - pick one, click Use Selected.

The cleaned name updates to the canonical TMDb title + year, the row is marked reviewed, and confidence jumps to 100%. The original on disk hasn't changed yet - that only happens when you hit Rename Selected.

Top-row toggles

Output template

Choose between two formats for the cleaned filename:

• {Title} ({Year}) - the Plex / Kodi / Jellyfin / MediaElch standard
• {Year} - {Title} - sortable chronologically

Switching the template re-applies it to all non-reviewed rows. Reviewed rows (your edits, TMDb confirmations) are left alone so you don't lose your work.

The Rename button

When you're happy with the list, click Rename Selected:

• A confirmation dialog tells you how many files will be touched.
• Companion subtitles (.srt, .sub, .ass, .ssa, .vtt, .idx) are renamed alongside their video.
• If Rename folder is on, the parent folder is renamed after the file (so paths stay valid).
• If Clean metadata is on, the file's embedded tags are scrubbed.

When the rename finishes, you'll see a toast notification at the bottom-right.

Undo

The success toast has an Undo button. You have 30 seconds to click it - after that the toast dismisses and the rename is final.

Undo reverses every rename in the batch (files first, folders last) so you're back to where you started.

Tip: even though we have undo, you should still review carefully before committing. If you close the toast or wait too long, you'll have to fix any mistakes manually.

4. Step 2 - Organize

Step 2 takes the (renamed) files and moves each one into a Title (Year)/ folder - the layout Plex, Kodi, Jellyfin, and MediaElch all expect.

How files arrive in Step 2

1. From Step 1 - automatic. Files carry over, all checked, the moment you click into Step 2.
2. + Add Files - multi-select file picker. Use this when filenames are already clean.
3. + Add Folder - recursively pulls every video out of a folder. Good for processing a whole drive of pre-named files.
4. Drag-drop - drop a folder or files onto the page.

Each row shows the source file → arrow → destination folder + new filename.

Where the folders go

There is no output folder to pick: each file's new folder is created right where the file already is. Only loose files are listed. Files that already sit in their own correctly named folder (or a Season XX folder for TV) are skipped automatically, and the status line tells you how many were skipped.

Running the move

Tick / untick rows you want to skip (the Select all box toggles every row), then click Run File to Folder. The app:

1. Creates a Title (Year)/ folder (movies) or Show/Season XX/ folders (TV) next to each file.
2. Moves the video into it.
3. Moves any matching subtitle files alongside.
4. Advances to Step 3 automatically on success.

Folder merging: if a destination folder already exists, files are merged into it instead of erroring. Existing files are never overwritten.

5. Step 3 - Scrape

Step 3 downloads metadata, posters, fanart, and actor photos from TMDb and writes them into each movie folder in the Plex / Kodi NFO standard layout:

Bawarchi (1972)/
├── Bawarchi (1972).mkv
├── Bawarchi (1972)-poster.jpg
├── Bawarchi (1972)-fanart.jpg
├── Bawarchi (1972).nfo
└── .actors/
    ├── Rajesh-Khanna.jpg
    └── …

Card view

The default view is a grid of cards - each card shows the poster (or a placeholder), the title, the folder path, a status pill, and three buttons (Scrape / Open / Remove).

Status pills are colour-coded:

If a folder was already scraped (it has both an .nfo and a -poster.jpg), the app detects this on load and pre-unchecks it so a bulk Scrape Selected won't redo it.

Per-movie scrape

Click Scrape on any card → the same TMDb search dialog as Step 1 opens, pre-filled with the title and year. Pick a result → app downloads everything. The card flips to green and the poster appears.

Bulk auto-scrape

Click Scrape Selected (auto) at the top → every checked card is processed sequentially using the first TMDb match (movie or TV show, depending on the card). Fast for batch processing, less precise than per-card.

The Select all box ticks every card (or clears them all), and a progress bar at the bottom shows "Scraping 3 of 12: Title" while a batch runs.

Fill gaps only (verify a library)

Click Fill gaps only → the app sweeps every folder and scrapes only the ones missing something (NFO, poster, fanart, or actor photos). Complete folders are skipped, so it's safe to re-run on an existing library - it just patches the holes. Each card's status shows exactly what's missing, e.g. "Missing: poster · fanart" or "Complete".

TV shows in Step 3

TV folders appear as one card per show. Under the title, a line like "TV · 3 seasons · 24 episodes" counts what's on disk (double episodes like S01E01E02 count as two), and after a scrape it adds how many aired episodes are missing, e.g. "· 2 missing". The status pill shows Complete or what's missing, the same as for movies.

Scraping a TV card writes tvshow.nfo + show artwork at the root and a per-episode .nfo + thumbnail for every episode. Right-click → Search TMDb searches the TV database (not movies) for TV cards. If you add a Season 01 folder (or Dark Season 1 Complete inside Dark), the card is made for the show folder above it, which is where the show's files belong.

The cast comes from every season of the show, not just the latest one. Scraping a show again keeps the TMDb show its tvshow.nfo is already matched to, so a show you once corrected with Search TMDb stays correct. To match it to a different show, use Search TMDb.

Shows scraped by v1.3.0 and earlier as one show per Dark Season 1 Complete folder are fixed when you add them: the show's tvshow.nfo, poster, fanart and .actors move up from the first season folder into Dark/ (only what Dark/ doesn't have yet, nothing is overwritten). The copies left in the other season folders are no longer used. Scrape the show again for the full cast and the right missing-episode count.

Episode titles in file names

Off by default. Turn on Settings → Add episode titles to file names, and scraping a TV show renames episodes that have no title yet:

Breaking Bad - S01E01.mkv   →   Breaking Bad - S01E01 - Pilot.mkv

Subtitles (.en.srt and so on), the episode .nfo and the thumbnail are renamed with it. Files that already have a title are left alone, as are double episodes and placeholder titles like "Episode 5". Nothing is ever overwritten. When a scrape renamed anything, a message offers Undo, which puts every original name back (one Undo for a whole batch).

Ratings: IMDb and TMDb

Every NFO gets both ratings, each with its vote count, so Kodi, Jellyfin and CineLibrary can show either one. Settings → Main rating picks which one players show first (IMDb by default, when the title has one).

IMDb ratings change over time. ⋯ → Refresh IMDb ratings updates them for the checked cards (or all cards when none are checked) in one quick request. Only the ratings in the NFO change: nothing is re-scraped and nothing else in the file is touched. NFOs scraped before v1.1.10 have only the TMDb id, so their IMDb id is looked up on TMDb first and added to the NFO. Ratings from other sources (such as Rotten Tomatoes) are kept as they are.

Other things you can do

• + Add Folder - add a movie folder that wasn't part of Steps 1 or 2. Accepts both single movie folders and parent folders containing many movie folders.
• Drag-drop - same as above.
• Double-tap a scraped card - opens the Movie Details window (hero fanart, floating poster, plot, IMDb and TMDb rating chips, color-coded crew / studio / country / genres / IDs / file info, scrollable cast strip with photos, plus Play / Open Folder / Edit / Trailer buttons). ESC closes it. Resizable and maximizable. For a TV show it also lists the episodes.
• Double-tap an unscraped card - opens the resizable TMDb search dialog so you can pick the right match.
• Right-click a card → View details / Search TMDb / Open Folder / Remove from List.
• List view toggle (icon in toolbar) - for libraries with hundreds of movies, the dense list view is faster. Preference is remembered.
• Each card shows an inline spinner next to its status pill while it's being scraped, so you always know which one is in flight.
• Done button - closes out the workflow. Files are already on disk, so this is more of a "finished" indicator.

Episodes and missing episodes

The details window of a TV show has an Episodes section, grouped by season (specials last). Each episode shows its thumbnail, title and air date, read from the files Step 3 wrote. Double-click an episode to play it.

While you look, the app asks TMDb which aired episodes aren't in your library and adds them to the list with an orange Missing tag. A season you don't have at all shows as one line ("All 10 aired episodes"). Episodes that haven't aired yet and specials are never reported as missing. This needs an internet connection; without one the list simply shows what's on disk.

Edit NFO

Scraped the right title but want to fix something? Right-click a card → Edit NFO..., or click Edit in the details window. The editor is its own window: resize it, maximize it, keep it open next to the app. Sections on the left:

• Chips for lists: type a genre, studio or name and press Enter; click × (or press Backspace in the empty box) to remove one. While you type, it suggests values already used in your library, so "Sci-Fi" and "Science Fiction" don't both creep in.
• Fetch from TMDb (the download-arrow button next to title, tagline, plot and outline) fills in just that field from TMDb, in a language you pick.
• Nothing is written until you Save (Ctrl+S). The header counts your unsaved changes; Revert throws them away, and closing the window asks first.
• Only what you change is written. Everything else in the NFO, like file info and tags added by other tools, stays exactly as it was.
• Restore previous version puts back the files exactly as they were before your last save: the NFO and any picture, actor photo or episode file that save replaced. Backups are kept in the app's own folder, not next to your movies.
• Protect from re-scrapes (ticked by default) marks the NFO as locked when you save (<lockdata>true</lockdata>, which Jellyfin understands too). After that, Fill gaps and Scrape Selected keep your edits and your chosen pictures, and only add images that are missing. Picking a match yourself in Search TMDb... is an explicit re-scrape and still replaces everything.

Bulk edit

Tick several cards, then ⋯ → Bulk edit checked items... to change them all at once: set (or clear) the collection, set the age rating, add or remove genres and tags (each title keeps the ones you don't mention), and protect them from re-scrapes or stop protecting them.

Only what you tick or fill in changes. Every changed title keeps a backup, so Edit NFO → Restore previous version undoes it for that title.

6. Settings page

A gear icon lives in the title bar next to the About icon. Clicking it opens a single Settings dialog with everything you can persist.

General

• Default output template - {Title} ({Year}) or {Year} - {Title}.
• Recursively scan subfolders by default - Step 1 starts with the Subfolders toggle on.
• Clean embedded MKV metadata by default - Step 1's "Clean metadata" checkbox starts on.
• Words to always remove - tags Step 1 should always strip, one per line (see Words to always remove).

Scraping

• TMDb language - 16 languages including English, Burmese, Hindi, Tamil, Telugu, Thai, Chinese, Japanese, Korean, French, German, Spanish, Italian, Portuguese, Russian, Arabic. TMDb returns titles, plots and posters in the chosen language where available, and falls back to English when it doesn't.
• Main rating - IMDb (when available) or TMDb: which rating players show first. Both are always saved.
• Add episode titles to file names - off by default (see Episode titles in file names).

Updates

• Check for updates on startup - silent once-per-24h check against GitHub. When a newer version is published, a toast appears with a Download button that fetches the installer directly inside the app (with a live progress percentage) and launches it for you.

Persistence

The app saves settings into appsettings.json next to the .exe. You shouldn't need to touch this file, but if you ever want to reset everything, just delete it.

What's remembered between sessions:

• TMDb API key (embedded by default)
• Everything from the Settings page above
• Recent source folders (last 10)
• Window size + position
• Which warnings you've dismissed
• Step 3 view preference (Grid / List)
• Step 1 sort column + direction
• Last successful update-check timestamp

7. Tips & tricks

• Drag-drop works on every step. Step 1 = load source. Step 2 = add to organize queue. Step 3 = add to scrape queue.
• Right-click is your friend. Every list / card has a context menu with the most useful actions.
• Use Modified only + Low filter to focus on the rows that actually need attention in big folders.
• The TMDb dialog accepts year in the search box - type Movie 2024, the year is parsed out and used as a release-year filter.
• The 30-second Undo applies to the whole batch. If you regret part of the rename, undo, fix that one row, and re-rename.
• Step 3 detects already-scraped folders. Re-load the same folder a hundred times - it won't re-scrape what's already done unless you tick the row.
• Clean metadata is a one-shot fix for the website-in-VLC-titlebar problem. Once it's done for a file, the file is clean forever.

8. Troubleshooting

9. FAQ

Will this app re-encode my videos?

No. It only renames files (a metadata-level operation) and moves them between folders. Even Clean metadata only rewrites tags in the file container - no audio or video data is touched. Operations are near-instant regardless of file size.

Does it work with TV shows?

Yes - fully. As of v1.2.0 TV shows are a first-class workflow alongside movies. The app detects episode patterns (S01E03, 1x03, Season 1 Episode 3), renames them to the Kodi convention Show - S01E01 (keeping the episode title if the filename has one), organizes them into Show/Season XX/ folders, and scrapes a tvshow.nfo + show poster/fanart/cast plus a per-episode .nfo and thumbnail for every episode. A Mode selector (Auto / Movies / TV Shows) lets you force or filter the type, and flat "Season Complete" folders are recognized too.

What about my movie's existing subtitles?

Companion files with the same base name (.srt, .sub, .ass, .ssa, .vtt, .idx) are renamed alongside the video automatically. They get moved into the Title (Year)/ folder along with the video in Step 2.

My TMDb API key - is it the app's or mine?

The app ships with an embedded API key, so it works out of the box. If you want to use your own (e.g. for higher rate limits), edit the TmdbApiKey field in appsettings.json.

Can I trust this with my library?

Step 1's renames are reversible via the 30-second Undo toast. Steps 2 and 3 are more conservative - they create new folders and move files but don't delete anything. As always, try it on a small folder first before unleashing it on your whole collection.

Where do I report bugs / request features?

Open an issue at github.com/aungkokomm/CineLibraryEssentials/issues. For a bug, open ⓘ About → Copy diagnostics first and paste the result into the issue. It holds the app version, your settings (never your API key) and the warnings you saw this session. Have a look before posting: those warnings can include file or folder names.

Do I still need MediaElch?

Not for most libraries. CineLibrary Essentials now writes the same Kodi-standard NFO, posters, fanart, cast photos and (for TV) per-episode metadata that MediaElch does. MediaElch is still a great option if you want extra image sources or edition-specific artwork - it reads the exact folders Essentials produces, so you can layer it on whenever you like.

Next steps

When your library is clean and scraped:

1. For browsing + management → grab CineLibrary, the companion app that catalogs your prepared library across multiple drives.
2. Optional: deeper artwork → point MediaElch at your library folder to layer in extra sources.

Enjoy your tidy movie & TV collection! 🎬📺