97 lines
4.9 KiB
Markdown
97 lines
4.9 KiB
Markdown
# 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.
|