Tidy Tray

Tidy Tray is a Windows-first Electron app that automatically organizes movie and TV files using The Movie Database (TMDB).
It runs from the tray, gives you one combined app page (actions + settings + console), and supports both automatic processing and manual runs.

---

What It Does

• Watches your incoming folders for media files (.mkv, .mp4, .avi, etc.)
• Detects TV episodes and movies from filenames
• Looks up proper titles/episode names in TMDB
• Renames/moves files using your templates
• Logs every action in the embedded console

Examples:

• TV: Show Name/Season 01/Show Name - S01E05 - Episode Title.mkv
• Movie: Movie Name (2024).mkv

---

Key Features

• Combined app page: actions, settings, and live console in one place
• Tray workflow: click tray icon to open the app quickly
• Auto processing enabled by default
  • watcher enabled by default
  • polling enabled by default
  • default polling interval is 60 seconds
• Manual processing: run “Process watch folders now” any time
• Non-locked file safety: auto processing waits until files are readable and size-stable (helps avoid files still being copied)
• Template-based output: customize TV and movie naming structure
• Dry run mode: preview changes without moving files
• Recurring-folder recovery
  • detects recursive path issues
  • reprocesses affected files
  • removes empty leftover folders after moves

---

Quick Start

1) Get a TMDB API key (free)

1. Create an account at themoviedb.org
2. Open Settings -> API
3. Request a developer API key
4. Copy your API Key (v3 auth)

2) Install and run

From source:

git clone https://github.com/taylorivanoff/tidy-tray.git
cd tidy-tray
npm install
npm start

Windows package:

npm run release

Installer/output files are created under dist/.

3) Configure in app

1. Click the tray icon to open Tidy Tray
2. Add your TMDB API key and test it
3. Add one or more watch folders
4. Optionally set an output folder (leave blank to organize from watch roots)
5. Review templates and save

---

Processing Modes

Automatic mode

• Triggered by new/changed files in watch folders
• Uses polling (default 60 seconds)
• Skips files that appear locked/in-progress and retries on later events

Manual mode

• Runs a deeper scan of watch folders
• Useful for backfills and cleanup
• Performs pre-scan structure checks and logs findings

---

Filename Detection

Tidy Tray parses common patterns:

• TV:
  • Show.Name.S01E05.*
  • Show.Name.1x05.*
  • Show Name s01e05 ...
• Movies:
  • Movie.Name.2024.*
  • similar names containing a 4-digit year

The parsed title is used as the TMDB query.

---

Templates

Default TV template:

{show}/Season {s}/{show} - S{s}E{e} - {title}.{ext}

Default movie template:

{title} ({year}).{ext}

Supported placeholders:

• TV: {show}, {s}, {e}, {title}, {ext}
• Movie: {title}, {year}, {ext}

---

Scripts

Command	Description
npm start	Build and run the app
npm run build	Compile TypeScript
npm run release	Build Windows installer (NSIS)

---

Tech Stack

• Electron
• TMDB API
• chokidar
• electron-store

---

Attribution

This product uses the TMDB API but is not endorsed or certified by TMDB.

---

License

MIT. See LICENSE.