riplex 0.1.0__tar.gz

riplex-0.1.0/.github/copilot-instructions.md

@@ -0,0 +1,17 @@
+# Copilot Instructions for riplex
+
+## Documentation changelog
+
+When any file under `docs/` is added, modified, or removed, update `docs/changelog.md` with a dated entry describing the change. Follow the [Keep a Changelog](https://keepachangelog.com/) format with sections like Added, Changed, Removed, or Fixed under a date heading.
+
+## CLI executable
+
+Always use `py` to run Python on this project (not `python` or `python3`). The installed `riplex.exe` in PATH may point to the wrong Python version. Prefer `py -m riplex` to ensure the correct interpreter.
+
+## Dry-run default
+
+The `organize` subcommand is dry-run by default. There is no `--dry-run` flag. Use `--execute` to actually move files.
+
+## Testing
+
+Run tests with `pytest` from the project root. All tests must pass before committing.

riplex-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

riplex-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+
+# Config file with API keys
+riplex.toml
+plex-planner.toml

riplex-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: riplex
+Version: 0.1.0
+Summary: Automates the tedious manual work around MakeMKV: figuring out what to rip, which MKV files are actually what, and organizing everything into Plex-compatible folder structures.
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Requires-Dist: dvdcompare-scraper>=0.1.0
+Requires-Dist: platformdirs>=4.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+
+# riplex
+
+Automates the tedious manual work around MakeMKV: figuring out what to rip, which MKV files are actually what, and organizing everything into Plex-compatible folder structures.
+
+## Why?
+
+MakeMKV is great at one thing: reading a disc and dumping raw MKV files. But that's where its job ends and yours begins.
+
+You're left with a pile of generically-named files (`title_t00.mkv`, `title_t01.mkv`, ...) and no idea which is the main film, which are featurettes, which are duplicates, and which is the play-all compilation you didn't need. For a multi-disc TV series, you're looking at hours of manual effort: reading disc cases, Googling runtimes, renaming files one by one, and building the exact folder hierarchy Plex demands.
+
+We identified the best sources of disc metadata (TMDb for canonical titles and episode info, dvdcompare.net for per-disc content breakdowns) and automated the entire pipeline. riplex pulls that data, figures out what's on every disc in a release, tells you exactly which MakeMKV titles to rip (and which to skip), then matches, renames, deduplicates, splits, and organizes everything into the correct Plex structure automatically.
+
+## What it does
+
+| Command | What it does |
+|---|---|
+| `orchestrate` | Full pipeline: insert a disc, riplex handles detection, metadata lookup, ripping, and organizing. Multi-disc with swap prompts. |
+| `rip` | Single-disc rip with smart title selection (skips play-alls, duplicates, junk). |
+| `organize` | Scan existing MKV rips, deduplicate, match to metadata by runtime, move into Plex layout. |
+| `lookup` | Preview disc contents and recommended rip strategy before touching MakeMKV. |
+
+## Quick Start
+
+### Install
+
+```bash
+pip install -e ".[dev]"
+```
+
+### Configure
+
+Create a config file at `%APPDATA%\riplex\config.toml` (Windows) or `~/.config/riplex/config.toml`:
+
+```toml
+tmdb_api_key = "your_key_here"
+output_root = "E:/Media"
+rip_output = "E:/Media/Rips"
+```
+
+Get a free TMDb API key at https://www.themoviedb.org/settings/api.
+
+### Rip a disc (interactive)
+
+Insert a disc and run:
+
+```bash
+riplex orchestrate --execute
+```
+
+riplex auto-detects the title from the volume label, looks up disc metadata, shows you what's on each disc, lets you choose which to rip, and organizes everything into Plex folders when done.
+
+### Rip a disc (unattended)
+
+```bash
+riplex orchestrate --execute --auto
+```
+
+Skips all prompts, uses best-guess defaults. Good for scripted or scheduled runs.
+
+### Organize existing rips
+
+Already ripped with MakeMKV manually? Point `organize` at the folder:
+
+```bash
+riplex organize path/to/rips/Oppenheimer --execute
+```
+
+## Requirements
+
+- Python 3.11+
+- [TMDb API key](https://www.themoviedb.org/settings/api) (free)
+- [MakeMKV](https://www.makemkv.com/) with `makemkvcon` on PATH
+- [ffmpeg](https://ffmpeg.org/) (`ffprobe`) for metadata extraction
+- [MKVToolNix](https://mkvtoolnix.download/) (`mkvmerge`, `mkvpropedit`) for chapter splitting and tagging
+
+## Related Projects
+
+- **[dvdcompare-scraper](https://github.com/ashergarland/dvdcompare-scraper)**: Scrapes per-disc content metadata from dvdcompare.net (featurettes, interviews, deleted scenes, runtimes). Required dependency that powers riplex's disc content lookup. Contributions welcome.
+
+## Documentation
+
+Full documentation is in the [docs/](docs/) folder:
+
+- [Getting Started](docs/getting-started/installation.md): installation, configuration
+- [User Guide](docs/guide/workflow.md): workflows, command-by-command guides
+- [CLI Reference](docs/reference/cli.md): all options for all commands
+- [Architecture](docs/architecture.md): design, data flow, project structure
+
+## License
+
+MIT

riplex-0.1.0/PLANNED_FEATURES.md

@@ -0,0 +1,57 @@
+# Planned Features
+
+## Recently Implemented
+
+### Orchestrate Mode
+
+The `riplex orchestrate` command is now fully implemented. It handles
+the complete multi-disc rip-then-organize workflow in a single session:
+insert a disc, auto-detect the title, look up dvdcompare for disc contents,
+select which discs to rip, rip each one with disc-swap prompts, then
+organize all files into Plex folder structure.
+
+See the orchestrate guide in the docs for full usage details.
+
+
+## Multi-Resolution Support (4K + Standard Blu-ray)
+
+Many 4K boxsets include standard Blu-ray discs with the same content at 1080p.
+Some users may want to rip both so Plex can serve the lower-resolution version
+to mobile devices without transcoding.
+
+### Plex support status
+
+**Movies**: Fully supported via "Multi-Version Movies." Multiple files in the
+same folder with different suffixes are collapsed into one library item. Plex
+auto-selects the best version per device, and many apps let the user choose
+manually. Naming convention:
+
+```
+/Movies/MovieName (Year)/
+   MovieName (Year) - 4K.mkv
+   MovieName (Year) - 1080p.mkv
+```
+
+**TV Shows**: NOT officially supported. Plex's TV naming documentation does not
+mention multi-version episodes. There is no documented way to have 4K and 1080p
+versions of the same episode collapse into a single item. Community workarounds
+exist (separate libraries, or relying on Plex's automatic version detection
+which sometimes works for TV but is undocumented and unreliable).
+
+### Plan
+
+- **Movies**: Support ripping both 4K and standard Blu-ray discs. During
+  organize, name them with resolution suffixes so Plex collapses them.
+- **TV Shows**: Since Plex does not officially support multi-version TV
+  episodes, we should:
+  1. Warn the user during rip if they attempt to rip a standard Blu-ray disc
+     for a TV show that already has 4K rips.
+  2. Offer to skip it with an explanation of why.
+  3. If Plex adds official TV multi-version support in the future, revisit.
+  4. Optionally allow it anyway for users who use separate libraries or
+     other workarounds, but make the limitation clear.
+
+
+## Other Ideas
+
+(Add future feature ideas here as they come up.)

riplex-0.1.0/README.md

@@ -0,0 +1,91 @@
+# riplex
+
+Automates the tedious manual work around MakeMKV: figuring out what to rip, which MKV files are actually what, and organizing everything into Plex-compatible folder structures.
+
+## Why?
+
+MakeMKV is great at one thing: reading a disc and dumping raw MKV files. But that's where its job ends and yours begins.
+
+You're left with a pile of generically-named files (`title_t00.mkv`, `title_t01.mkv`, ...) and no idea which is the main film, which are featurettes, which are duplicates, and which is the play-all compilation you didn't need. For a multi-disc TV series, you're looking at hours of manual effort: reading disc cases, Googling runtimes, renaming files one by one, and building the exact folder hierarchy Plex demands.
+
+We identified the best sources of disc metadata (TMDb for canonical titles and episode info, dvdcompare.net for per-disc content breakdowns) and automated the entire pipeline. riplex pulls that data, figures out what's on every disc in a release, tells you exactly which MakeMKV titles to rip (and which to skip), then matches, renames, deduplicates, splits, and organizes everything into the correct Plex structure automatically.
+
+## What it does
+
+| Command | What it does |
+|---|---|
+| `orchestrate` | Full pipeline: insert a disc, riplex handles detection, metadata lookup, ripping, and organizing. Multi-disc with swap prompts. |
+| `rip` | Single-disc rip with smart title selection (skips play-alls, duplicates, junk). |
+| `organize` | Scan existing MKV rips, deduplicate, match to metadata by runtime, move into Plex layout. |
+| `lookup` | Preview disc contents and recommended rip strategy before touching MakeMKV. |
+
+## Quick Start
+
+### Install
+
+```bash
+pip install -e ".[dev]"
+```
+
+### Configure
+
+Create a config file at `%APPDATA%\riplex\config.toml` (Windows) or `~/.config/riplex/config.toml`:
+
+```toml
+tmdb_api_key = "your_key_here"
+output_root = "E:/Media"
+rip_output = "E:/Media/Rips"
+```
+
+Get a free TMDb API key at https://www.themoviedb.org/settings/api.
+
+### Rip a disc (interactive)
+
+Insert a disc and run:
+
+```bash
+riplex orchestrate --execute
+```
+
+riplex auto-detects the title from the volume label, looks up disc metadata, shows you what's on each disc, lets you choose which to rip, and organizes everything into Plex folders when done.
+
+### Rip a disc (unattended)
+
+```bash
+riplex orchestrate --execute --auto
+```
+
+Skips all prompts, uses best-guess defaults. Good for scripted or scheduled runs.
+
+### Organize existing rips
+
+Already ripped with MakeMKV manually? Point `organize` at the folder:
+
+```bash
+riplex organize path/to/rips/Oppenheimer --execute
+```
+
+## Requirements
+
+- Python 3.11+
+- [TMDb API key](https://www.themoviedb.org/settings/api) (free)
+- [MakeMKV](https://www.makemkv.com/) with `makemkvcon` on PATH
+- [ffmpeg](https://ffmpeg.org/) (`ffprobe`) for metadata extraction
+- [MKVToolNix](https://mkvtoolnix.download/) (`mkvmerge`, `mkvpropedit`) for chapter splitting and tagging
+
+## Related Projects
+
+- **[dvdcompare-scraper](https://github.com/ashergarland/dvdcompare-scraper)**: Scrapes per-disc content metadata from dvdcompare.net (featurettes, interviews, deleted scenes, runtimes). Required dependency that powers riplex's disc content lookup. Contributions welcome.
+
+## Documentation
+
+Full documentation is in the [docs/](docs/) folder:
+
+- [Getting Started](docs/getting-started/installation.md): installation, configuration
+- [User Guide](docs/guide/workflow.md): workflows, command-by-command guides
+- [CLI Reference](docs/reference/cli.md): all options for all commands
+- [Architecture](docs/architecture.md): design, data flow, project structure
+
+## License
+
+MIT

riplex-0.1.0/docs/architecture.md

@@ -0,0 +1,129 @@
+# Architecture
+
+## Overview
+
+riplex is a Python CLI application with four commands, each targeting a different stage of the disc ripping workflow:
+
+- **`orchestrate`**: The primary workflow. Multi-disc rip-then-organize in a single session. Combines disc detection, dvdcompare lookup, disc selection, ripping, and organizing.
+- **`rip`**: Single-disc rip via makemkvcon. Disc analysis, auto title selection, and optional post-rip organize.
+- **`organize`**: The file organization pipeline. Scans MKV files, deduplicates, looks up TMDb + dvdcompare, matches files by runtime, and moves everything into Plex folder layout.
+- **`lookup`**: TMDb + dvdcompare lookup. Shows disc contents and recommended rip strategy before ripping. Helps users decide which MakeMKV titles to rip vs skip, and creates correct folder structure.
+
+## Metadata provider
+
+The metadata provider is abstracted behind a clean interface (`MetadataProvider`). The default implementation uses TMDb, which is the same source Plex uses for its metadata agents. The provider can be swapped out for TheTVDB or any other source by implementing the interface.
+
+## Project structure
+
+```
+src/riplex/
+    __init__.py
+    cli.py                  # CLI entry point (orchestrate, rip, organize, lookup subcommands)
+    config.py               # Config file loading and setting resolution
+    models.py               # Data models (ScannedFile, PlannedDisc, MatchCandidate, etc.)
+    metadata_provider.py    # Abstract provider interface
+    metadata_sources/
+        tmdb.py             # TMDb API implementation
+    normalize.py            # Filename/path normalization
+    formatter.py            # Text and JSON output formatters
+    planner.py              # Core planning orchestrator
+    matcher.py              # Runtime-based file matching with disc constraints
+    scanner.py              # MakeMKV folder scanner (ffprobe-based metadata extraction)
+    snapshot.py             # Snapshot capture and loading (JSON serialization of scan results)
+    detect.py               # Format auto-detection, title grouping, incomplete file detection
+    dedup.py                # Duplicate MKV detection (metadata fingerprint + perceptual hash)
+    cache.py                # File-based JSON cache with TTL (dvdcompare, TMDb)
+    disc_provider.py        # dvdcompare.net disc extras metadata bridge
+    disc_analysis.py        # Live disc analysis via makemkvcon (title classification, rip recommendations)
+    makemkv.py              # makemkvcon wrapper (disc reading, title ripping, progress parsing)
+    organizer.py            # Plex destination path builder and file mover
+    splitter.py             # Chapter-based MKV splitting via mkvmerge
+    tagger.py               # MKV organized tagging via mkvpropedit
+    ui.py                   # Interactive prompts (multi-select, confirmations, text input)
+tests/
+    test_cache.py
+    test_cli_utils.py
+    test_config.py
+    test_dedup.py
+    test_detect.py
+    test_disc_analysis.py
+    test_disc_provider.py
+    test_formatter.py
+    test_makemkv.py
+    test_matcher.py
+    test_normalize.py
+    test_organizer.py
+    test_planner.py
+    test_rip_guide.py
+    test_scanner.py
+    test_splitter.py
+    test_tagger.py
+    test_ui.py
+    snapshots/              # MKV metadata snapshots for offline test replay
+```
+
+## Key data flow
+
+### Orchestrate mode
+
+```
+Physical disc
+  -> Drive detection (auto-scan optical drives)
+  -> Volume label parsing (title auto-detection)
+  -> TMDb API (canonical title lookup, disambiguation)
+  -> dvdcompare (disc breakdown, content listings)
+  -> Disc selection (interactive or --discs flag)
+  -> Per-disc loop:
+     -> makemkvcon (disc reading, title analysis)
+     -> Disc analysis (classification, rip recommendations)
+     -> makemkvcon (title ripping with progress)
+     -> Manifest writing (disc metadata snapshot)
+  -> Organize pipeline (dedup, match, move, split, tag)
+  -> Archive (move rip folder to archive_root, optional)
+```
+
+### Rip mode
+
+```
+Physical disc
+  -> Drive detection + volume label parsing
+  -> TMDb API (canonical title lookup)
+  -> dvdcompare (disc breakdown)
+  -> makemkvcon (disc reading, title analysis)
+  -> Disc analysis (classification, rip/skip recommendations)
+  -> makemkvcon (title ripping with progress)
+  -> Optional: Organize pipeline
+```
+
+### Plan mode
+
+```
+User input (title, year)
+  -> TMDb API (via MetadataProvider)
+  -> Planner (builds PlannedMovie or PlannedShow)
+  -> Formatter (text or JSON output)
+```
+
+### Organize mode
+
+```
+MakeMKV rip folder
+  -> Scanner (ffprobe metadata extraction)
+  -> Dedup (duplicate detection and removal)
+  -> Detect (play-all detection, format inference, title grouping)
+  -> TMDb API (canonical title lookup)
+  -> dvdcompare (disc extras metadata)
+  -> Matcher (runtime-based file-to-entry matching)
+  -> Organizer (destination path builder)
+  -> Splitter (chapter-based MKV splitting, if needed)
+  -> Tagger (mark files as organized)
+```
+
+### Rip guide mode
+
+```
+User input (title, year)
+  -> TMDb API (canonical title lookup)
+  -> dvdcompare (disc breakdown)
+  -> CLI (formatted disc guide output)
+```

riplex-0.1.0/docs/changelog.md

@@ -0,0 +1,56 @@
+# Documentation Changelog
+
+All notable changes to the riplex documentation are recorded here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/).
+
+## 2026-04-30
+
+### Added
+
+- Orchestrate guide (`docs/guide/orchestrate.md`): full documentation for the new primary workflow command
+- `orchestrate` subcommand in CLI Reference with complete options table
+- `rip` subcommand added to README (features block, usage examples, CLI reference table)
+- `orchestrate` subcommand added to README (features block, usage examples, CLI reference table)
+- New config keys documented: `rip_output` and `archive_root` (README, configuration.md, CLI reference)
+- Orchestrate and Rip data flow diagrams in architecture.md
+- MakeMKV/makemkvcon added to Requirements section
+- New source files documented in project structure: `ui.py`, `disc_analysis.py`, `makemkv.py`
+- Orchestrate entry in mkdocs.yml navigation
+
+### Changed
+
+- README Features section reordered: orchestrate and rip are now listed first as the primary commands
+- `plan` marked as deprecated (alias for `rip-guide`) throughout README and CLI reference
+- Organize output examples updated to new grouped format (subfolder headings, `<-` arrow notation)
+- Rip-guide output examples updated to use configurable rip output path instead of hardcoded `_MakeMKV`
+- Architecture section updated from 4 modes to 6 modes (added orchestrate, rip)
+- Project structure listings updated to include all current source and test files
+- `docs/guide/workflow.md` updated to recommend orchestrate as the primary workflow
+- `docs/architecture.md` updated with orchestrate and rip modes and data flows
+- `PLANNED_FEATURES.md` orchestrate section moved to "Recently Implemented"
+- CLI reference tables for organize (added `--snapshot`, `--auto`) and rip-guide (added `--drive`) updated
+
+## 2025-04-20
+
+### Changed
+
+- Replaced all personal/machine-specific paths with generic placeholders across all docs and README
+- CLI examples now use `path/to/rips/Title` for user-supplied input paths
+- Tool output examples (rip-guide folder structure) use `<output_root>/_MakeMKV/` to clarify the staging directory
+- Output destination examples use relative paths (e.g. `Movies/...`, `TV Shows/...`)
+- Config examples use `/path/to/media` placeholder
+- Debug log references changed to "OS temp directory" instead of platform-specific paths
+- Removed personal Python install path from `.github/copilot-instructions.md`
+
+### Added
+
+- Initial documentation structure in `docs/` folder
+- Home page with feature overview and quick start (`index.md`)
+- Getting Started section: Installation, Configuration
+- User Guide section: Typical Workflow, Rip Guide, Organizing Files, Planning, Snapshots
+- CLI Reference page with all subcommands and options
+- Architecture overview with data flow diagrams
+- Plex Naming Rules reference
+- `mkdocs.yml` configuration (ready for MkDocs Material when published)
+- This changelog

riplex-0.1.0/docs/getting-started/configuration.md

@@ -0,0 +1,35 @@
+# Configuration
+
+riplex reads settings from three sources, in priority order:
+
+1. CLI flags (highest priority)
+2. Environment variables
+3. Config file (lowest priority)
+
+## Config file
+
+Create a config file at one of these locations:
+
+| Platform | Path |
+|---|---|
+| Windows | `%APPDATA%\riplex\config.toml` |
+| Linux/macOS | `~/.config/riplex/config.toml` |
+| Any (local) | `riplex.toml` in the current working directory |
+
+Example:
+
+```toml
+tmdb_api_key = "your_api_key_here"
+output_root = "/path/to/media"
+rip_output = "/path/to/media/Rips"
+archive_root = "/path/to/media/Rips/_archive"
+```
+
+## Settings
+
+| Setting | CLI flag | Env var | Config key | Description |
+|---|---|---|---|---|
+| TMDb API key | `--api-key` | `TMDB_API_KEY` | `tmdb_api_key` | Required for all commands |
+| Output root | `--output` | `PLEX_ROOT` | `output_root` | Root directory for organized output. Plex subfolders like `Movies/` and `TV Shows/` are created under this. |
+| Rip output | `--output` | - | `rip_output` | Directory for MakeMKV rip output. Default: `{output_root}/Rips`. Used by `rip` and `orchestrate`. |
+| Archive root | - | - | `archive_root` | Directory to move rip folders after successful organize. Optional; if not set, rip folders are left in place. |

riplex-0.1.0/docs/getting-started/installation.md

@@ -0,0 +1,45 @@
+# Installation
+
+## Requirements
+
+- Python 3.11+
+- A TMDb API key (free at <https://www.themoviedb.org/settings/api>)
+- ffprobe (from ffmpeg, required for `organize` mode)
+- mkvmerge (from MKVToolNix, required for chapter splitting in `organize` mode)
+- mkvpropedit (from MKVToolNix, required for organized tagging in `organize` mode)
+- [dvdcompare-scraper](https://github.com/OWNER/dvdcompare-scraper) (sibling project, required for `organize` and `lookup` modes)
+
+## Install from source
+
+```bash
+cd Projects/riplex
+pip install -e ".[dev]"
+```
+
+This installs the `riplex` CLI command and all dependencies including test tooling.
+
+## Verify installation
+
+```bash
+riplex --help
+```
+
+You should see the four subcommands: `orchestrate`, `rip`, `organize`, and `lookup`.
+
+## External tools
+
+### ffprobe / ffmpeg
+
+Download from <https://ffmpeg.org/download.html> and ensure `ffprobe` is on your PATH.
+
+On Windows, you can verify with:
+
+```powershell
+ffprobe -version
+```
+
+### MKVToolNix
+
+Download from <https://mkvtoolnix.download/downloads.html>. The installer adds `mkvmerge` and `mkvpropedit` to your PATH automatically.
+
+On Windows, the default install location is `C:\Program Files\MKVToolNix\`.