mov-renamarr/PLAN.md

Mov Renamarr CLI - Project Plan

Goal

Build a Linux CLI that scans a directory of movie files, queries online metadata (OMDb/TMDb), and writes Radarr-compatible folder and file names to an output directory. Project name: Mov Renamarr.

Core Requirements

• Input: directory tree containing video files.
• Output: Movie Title (Year)/Movie Title (Year) [Quality] [id].ext.
• Uses ffprobe for media info and filename parsing for hints.
• Queries OMDb/TMDb, with caching to avoid repeat lookups.
• Non-interactive by default: skip ambiguous/unmatched files, report them at end.
• Optional --interactive to confirm matches.
• Linux support only (for now).

Non-Goals (for MVP)

• No Radarr API integration.
• No TV/series handling.
• No transcoding or media repair.

Decisions to Lock In

• Default action: copy (safe default).
• Optional flags: --move and --rename-in-place.
• Config file support (XDG by default) + CLI overrides. Config format: TOML.
• Provider selection: auto based on available API keys, with optional user preference. Default auto priority: TMDb.
• Match scoring and minimum confidence threshold.
• Cache storage format (SQLite vs JSON) + TTL + --refresh-cache.
• Quality tags default to resolution only; configurable via CLI/config.
• Optional local LLM integration (Ollama) for filename parsing and lookup assist, disabled by default.
• Default report format: text.
• Sidecar notes: off by default; opt-in only.
• Include top-3 candidates in unresolved items by default.
• Emphasize performance, broad Linux compatibility, and robust error handling.
• UX: per-file status line (file/provider/result/new name), progress counts, color when TTY, --verbose for debug details.
• Collision policy: default skip if destination exists; optional --overwrite or --suffix to avoid data loss.
• Sidecar files: optionally move/copy all sidecar files with --sidecars flag (off by default).
• Concurrency: default jobs = min(4, max(1, floor(cores/2))); default net-jobs = min(2, jobs); allow overrides.
• ffprobe required (no native parsing fallback).
• Reports: stdout by default; optional report file name pattern mov-renamarr-report-YYYYMMDD-HHMMSS.txt when --report is set without a path.
• Config precedence: defaults -> config TOML -> env -> CLI flags.
• Config path: $XDG_CONFIG_HOME/mov-renamarr/config.toml (fallback ~/.config/mov-renamarr/config.toml).
• Cache path: $XDG_CACHE_HOME/mov-renamarr/cache.db (fallback ~/.cache/mov-renamarr/cache.db).
• Report file default location: current working directory when --report is set without a path.
• Provider base URLs configurable in config/env to support testing/mocking.
• Create a commented default config file on first run and notify the user.

Proposed CLI (Draft)

• mov-renamarr --input <dir> --output <dir>
• --config <path> (default: XDG config)
• --provider auto|omdb|tmdb|both
• --api-key-omdb <key> / --api-key-tmdb <key> (override config/env)
• --cache <path> (default: ~/.cache/mov-renamarr.db)
• --refresh-cache (bypass cache)
• --dry-run
• --move / --rename-in-place
• --interactive
• --report <path> + --report-format text|json|csv
• --sidecar-notes (write per-file skip notes)
• --min-score <0-100>
• --include-id (tmdb/omdb/imdb if available)
• --quality-tags resolution|resolution,codec,source
• --color auto|always|never
• --jobs <n|auto>
• --net-jobs <n|auto>
• --no-lookup (skip external providers; use filename/LLM only)
• --llm-mode off|parse|assist (default: off)
• --llm-endpoint <url> (Ollama, default http://localhost:11434)
• --llm-model <name> (Ollama model name)
• --llm-timeout <seconds> / --llm-max-tokens <n>

Matching Heuristics (Draft)

• Parse filename for title/year hints; strip extra release metadata.
• Use ffprobe for duration and resolution.
• Prefer exact year match; allow +/- 1 year when missing.
• Use string similarity + runtime delta to choose best match.

Pipeline (Draft)

1. Load config (XDG) + merge CLI overrides.
2. Discover files and filter by extension; skip output subtree when output != input to avoid reprocessing.
3. Parse filename hints (title/year) and strip release metadata (optionally via LLM parse).
4. Run ffprobe for duration/resolution/codec.
5. Select provider(s) based on available API keys and user preference.
6. Query provider(s) with hints (LLM assist may propose candidates but must be verified).
7. Score and select match; if below threshold, mark as unresolved.
8. Build Radarr-compatible output path.
9. Copy/move/rename-in-place file to output directory.
10. Write summary report of successes and unresolved items.

Milestones

• M0: Project scaffold and plan (done).
• M1: CLI skeleton and config parsing.
• M2: ffprobe integration and media metadata model.
• M3: OMDb/TMDb client + caching.
• M4: Matching, naming, and file move/copy.
• M5: Reporting, tests, and polish.
• M6: Automated test harness and fixtures.
• M7: Performance pass and profiling.