📖 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:

Organization differs by type:

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

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.

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.

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.
• More menu (top-right ⋯) — Select All / None, 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.

Filters & search

• 🔍 Search box — live-filters by both original and cleaned name.
• Confidence dropdown — All / High / Medium / Low / Warnings only / Needs renaming.
• 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.

Output folder

The output folder defaults to the source folder so the moves happen "in place" (creating subfolders inside the source). Click the folder button to pick a different output, or use ▾ for recents. If you change the output folder, every destination preview updates automatically.

Running the move

Tick / untick rows you want to skip, then click Run File to Folder. The app:

1. Creates a Title (Year)/ folder under the output for each movie.
2. Moves the video into it.
3. Moves any matching subtitle files alongside.
4. Advances to Step 3 automatically on success.

If a destination already exists or there's a collision, that row is skipped and reported. The rest of the batch still processes.

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.

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 with a status like "TV · 3 seasons · Complete". 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.

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, color-coded crew / studio / country / genres / IDs / file info, scrollable cast strip with photos, plus Play / Open Folder / Trailer buttons). ESC closes it. Resizable and maximizable.
• 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.

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.

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.

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 / output folders (last 10 each)
• 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 - Title, 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.

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 output folder to layer in extra sources.

Enjoy your tidy movie & TV collection! 🎬📺