media-cleaner

A CLI tool that renames and organizes media files into a clean, consistent structure.

Breaking.Bad.S05E14.Ozymandias.1080p.BluRay.x264-YIFY.mkv
  → Breaking.Bad/S05/Breaking.Bad.S05E14.Ozymandias.mkv

The.Godfather.1972.1080p.BluRay.x264.mkv
  → The.Godfather.mkv

Parasite.2019.KOREAN.1080p.BluRay.mkv  (alongside a TV show)
  → Movies/Parasite.mkv

Junk files (.nfo, samples, readmes, tracker text files) are deleted. Subtitles are matched to their video and renamed to match.

Install

npm install -g media-cleaner

Requires Node.js 18 or later.

Quick start

cd ~/Downloads/ShowName.S01
media-cleaner

Without API keys, titles are cleaned from the filename alone. Add an OMDb API key (free) for canonical titles and episode names:

media-cleaner config omdbApiKey YOUR_KEY

Commands

media-cleaner [directory]

Scan and clean a directory. Defaults to the current working directory.

media-cleaner                   # current directory, interactive
media-cleaner ~/Downloads/Show  # specific directory
media-cleaner --dry-run         # preview changes, make nothing
media-cleaner --safe-mode       # always use safe mode
media-cleaner --destructive     # always use destructive mode
media-cleaner --auto            # skip all prompts (for automation)
media-cleaner --no-api          # skip API calls, filename parsing only

Safe mode (default when interactive) writes a .recovery/manifest.json before touching any files, backs up deleted files, and marks each operation complete as it goes. A crashed or interrupted run can be resumed or rolled back. Destructive mode makes changes with no backup.

If a run was interrupted, media-cleaner will detect the partial manifest and ask what to do.

media-cleaner recover [directory]

Restore a directory to its state before the last clean-up. Requires a .recovery/ folder from a safe-mode run.

media-cleaner recover
media-cleaner recover ~/Downloads/Show
media-cleaner recover --auto    # skip confirmation

media-cleaner config [key] [value]

View or set persistent configuration.

media-cleaner config                        # show all settings
media-cleaner config omdbApiKey YOUR_KEY    # set a value
media-cleaner config subtitleLanguages en,fr,de

Configuration

Config is stored at ~/.config/media-cleaner/config.json. All settings can be viewed and changed with media-cleaner config.

| Key | Default | Description | |-----|---------|-------------| | omdbApiKey | (not set) | OMDb API key for title lookup | | anthropicApiKey | (not set) | Anthropic API key for Claude fallback (also read from $ANTHROPIC_API_KEY) | | claudeModel | claude-haiku-4-5-20251001 | Claude model used as OMDb fallback | | subtitleLanguages | en | Comma-separated language codes to keep; others are deleted (en,fr,de) | | movieYear | disambiguation | Include year in movie filename: always, disambiguation, or never | | episodeTitles | true | Append episode title to TV filenames | | keepApostrophes | true | Keep apostrophes in filenames (false → Dont instead of Don't) | | defaultMode | safe | Default execution mode: safe or destructive | | videoExtensions | (common list) | Video extensions to treat as media files | | tvDir | TV | Wrapper directory name for TV shows in mixed-content directories | | moviesDir | Movies | Wrapper directory name for movies in mixed-content directories |

API keys

OMDb (recommended): Get a free key at omdbapi.com/apikey.aspx. Used for canonical titles and episode names.

Anthropic (optional fallback): Set via media-cleaner config anthropicApiKey YOUR_KEY or the ANTHROPIC_API_KEY environment variable. Only called when OMDb fails to find a title.

OMDb results are cached at ~/.config/media-cleaner/cache.json (30 days for titles, 90 days for episodes) to avoid redundant API calls across runs.

Directory layout

Single type (all TV or all movies — no wrapper):

Show.Name/
  S01/
    Show.Name.S01E01.Episode.Title.mkv

Mixed content (TV/ and Movies/ wrappers added automatically):

TV/
  Show.Name/
    S01/
      Show.Name.S01E01.mkv
Movies/
  Movie.Title.mkv

The wrapper names are configurable via tvDir and moviesDir.

Automation

Pass --auto to skip all prompts. Combined with --destructive for no-confirmation, no-backup runs:

media-cleaner --auto --destructive /path/to/completed/download

Example post-download hook (varies by download manager):

media-cleaner --auto /path/to/completed/%N

Filename rules

• Dots used throughout: Show.Name.S01E01.Episode.Title.mkv
• Special characters: /\: → dot, & → And, ()[]{}?!*"<>| removed
• Apostrophes kept by default (configurable)
• Release group tags, quality tokens (1080p, BluRay, x264, etc.) stripped

Legal

This software renames and organizes files that already exist on your system. It does not download content, circumvent technical protection measures, or facilitate unauthorized access to any service.

Users are solely responsible for ensuring their use of this software complies with applicable copyright law and any relevant terms of service. The author does not condone use of this software to organize or facilitate access to content obtained without proper authorization.

License

MIT