riplex 0.7.1__tar.gz → 0.7.3__tar.gz

{riplex-0.7.1 → riplex-0.7.3}/.github/agents/riplex.agent.md

@@ -65,7 +65,8 @@ docs/
   naming-rules.md      # Plex naming conventions
   changelog.md         # Documentation changelog (Keep a Changelog format)
   getting-started/     # Installation, configuration
-  guide/               # Per-command workflow guides
+  gui-guide/           # Desktop app walkthroughs
+  cli-guide/           # Command-by-command workflow guides
   reference/           # CLI reference
 ```
 
@@ -162,9 +163,16 @@ Docs live in `docs/` and are referenced from README.md.
 - `docs/naming-rules.md`: Plex naming conventions and folder layout rules
 - `docs/changelog.md`: Documentation changelog (update when docs change)
 - `docs/getting-started/`: Installation and configuration guides
-- `docs/guide/`: Per-command workflow walkthroughs
+- `docs/gui-guide/`: Desktop app walkthroughs
+- `docs/cli-guide/`: Command-by-command workflow walkthroughs
 - `docs/reference/cli.md`: Complete CLI option reference
 
+*** Delete File: c:\Users\asher\Projects\anycredit5518\riplex\docs\guide\gui-walkthrough.md
+*** Delete File: c:\Users\asher\Projects\anycredit5518\riplex\docs\guide\workflow.md
+*** Delete File: c:\Users\asher\Projects\anycredit5518\riplex\docs\guide\orchestrate.md
+*** Delete File: c:\Users\asher\Projects\anycredit5518\riplex\docs\guide\lookup.md
+*** Delete File: c:\Users\asher\Projects\anycredit5518\riplex\docs\guide\organize.md
+
 ### Documentation rules
 
 - When making significant changes (new features, renamed modules, changed behavior), update the relevant docs

riplex-0.7.3/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: riplex
+Version: 0.7.3
+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
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Requires-Dist: dvdcompare-scraper>=0.1.15
+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"
+Provides-Extra: gui
+Requires-Dist: flet<0.86,>=0.84; extra == "gui"
+Dynamic: license-file
+
+# riplex
+
+Automatically organizes MKV files from physical disc collections into Plex-compatible folder structures with the right names, the right folders, and no manual work.
+
+riplex includes both a desktop app for guided ripping and a full CLI for terminal-first and automated workflows.
+
+<p align="center">
+	<img src="screenshots/0_Rip_Flow_BTTF.gif" alt="Rip flow demo" width="800">
+</p>
+
+## Why?
+
+After using MakeMKV to back up a disc, 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.
+
+riplex solves this by pulling metadata from TMDb (canonical titles, years, episode info) and [dvdcompare.net](https://www.dvdcompare.net) (per-disc content breakdowns including featurettes, deleted scenes, runtimes), then automatically classifying, deduplicating, matching, renaming, and organizing everything into the correct Plex structure.
+
+## Get started
+
+Start with the [Getting Started guide](docs/getting-started/installation.md). It covers all three install paths:
+
+- **Pre-built app**: fastest way to try riplex. Download links and platform-specific notes are in the [installation guide](docs/getting-started/installation.md#option-a-pre-built-executables).
+- **pipx**: recommended if you have Python or do not mind installing it. See [Option B](docs/getting-started/installation.md#option-b-install-with-pipx-recommended).
+- **From source**: for developers and unsupported binary platforms. See [Option C](docs/getting-started/installation.md#option-c-install-from-source).
+
+If you just want the desktop app right now, the latest binaries are on the [Releases page](https://github.com/AnyCredit5518/riplex/releases/latest). For the guided desktop flow after install, see the [GUI Walkthrough](docs/gui-guide/gui-walkthrough.md).
+
+If you prefer the command line, riplex also ships a full CLI with `lookup`, `rip`, `organize`, and `orchestrate` workflows. For the end-to-end terminal flow, see the [CLI Workflow guide](docs/cli-guide/workflow.md).
+
+After installing:
+
+1. Run setup. The GUI walks you through it on first launch, or you can use [`riplex setup`](docs/getting-started/installation.md#setup).
+2. If you want to see the GUI step by step, read the [GUI Walkthrough](docs/gui-guide/gui-walkthrough.md).
+3. Follow the [CLI Workflow guide](docs/cli-guide/workflow.md) for the end-to-end flow.
+4. If you prefer the terminal, use the [CLI reference](docs/reference/cli.md) for command details.
+
+## What it looks like
+
+Instead of leaving you to sort through a wall of raw MakeMKV titles, riplex helps you understand what is actually on the disc and choose the titles worth ripping. It surfaces likely matches, highlights junk and duplicates, and helps you avoid play-all traps.
+
+![Title selection](screenshots/5_Select_Title_to_RIP_BTTF.png)
+
+More screenshots:
+[welcome](screenshots/1_Welcome_Screen.png),
+[disc detection](screenshots/2_Disc_Detection_BTTF.png),
+[metadata lookup](screenshots/3_Metadata_Lookup_BTTF.png),
+[release picker](screenshots/4_Disc_Release_BTTF.png),
+[disc overview](screenshots/5_Multi_Disc_Overview_BTTF.png).
+
+> [!NOTE]
+> riplex currently handles one film (or one TV show) per session. Multi-film box sets that bundle separate films onto separate discs (e.g. a trilogy in one box) need to be ripped one film at a time.
+
+## Requirements
+
+riplex uses MakeMKV, ffmpeg, and MKVToolNix under the hood. The setup wizard installs them for you on Windows (winget), macOS (Homebrew), and Debian/Ubuntu Linux (apt). On other platforms see [the installation guide](docs/getting-started/installation.md).
+
+You'll also need a free [TMDb API key](https://www.themoviedb.org/settings/api). The wizard prompts you for it.
+
+## Data sources
+
+- **[TMDb](https://www.themoviedb.org/)**: canonical movie and TV metadata (titles, years, episodes, runtimes)
+- **[dvdcompare.net](https://www.dvdcompare.net)**: per-disc content breakdowns (featurettes, deleted scenes, play-all groupings, runtimes). An invaluable community resource.
+
+## Related projects
+
+- **[dvdcompare-scraper](https://github.com/AnyCredit5518/dvdcompare-scraper)**: Python client for dvdcompare.net. Powers riplex's disc lookup. Contributions welcome.
+
+## Documentation
+
+- [Getting started](docs/getting-started/installation.md): installation, configuration
+- [GUI walkthrough](docs/gui-guide/gui-walkthrough.md): the main desktop flow, screen by screen
+- [CLI workflow](docs/cli-guide/workflow.md): end-to-end terminal workflows
+- [CLI reference](docs/reference/cli.md): every command and flag
+- [Architecture](docs/architecture.md): design, data flow, project structure
+
+## License
+
+MIT

riplex-0.7.3/README.md

@@ -0,0 +1,77 @@
+# riplex
+
+Automatically organizes MKV files from physical disc collections into Plex-compatible folder structures with the right names, the right folders, and no manual work.
+
+riplex includes both a desktop app for guided ripping and a full CLI for terminal-first and automated workflows.
+
+<p align="center">
+	<img src="screenshots/0_Rip_Flow_BTTF.gif" alt="Rip flow demo" width="800">
+</p>
+
+## Why?
+
+After using MakeMKV to back up a disc, 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.
+
+riplex solves this by pulling metadata from TMDb (canonical titles, years, episode info) and [dvdcompare.net](https://www.dvdcompare.net) (per-disc content breakdowns including featurettes, deleted scenes, runtimes), then automatically classifying, deduplicating, matching, renaming, and organizing everything into the correct Plex structure.
+
+## Get started
+
+Start with the [Getting Started guide](docs/getting-started/installation.md). It covers all three install paths:
+
+- **Pre-built app**: fastest way to try riplex. Download links and platform-specific notes are in the [installation guide](docs/getting-started/installation.md#option-a-pre-built-executables).
+- **pipx**: recommended if you have Python or do not mind installing it. See [Option B](docs/getting-started/installation.md#option-b-install-with-pipx-recommended).
+- **From source**: for developers and unsupported binary platforms. See [Option C](docs/getting-started/installation.md#option-c-install-from-source).
+
+If you just want the desktop app right now, the latest binaries are on the [Releases page](https://github.com/AnyCredit5518/riplex/releases/latest). For the guided desktop flow after install, see the [GUI Walkthrough](docs/gui-guide/gui-walkthrough.md).
+
+If you prefer the command line, riplex also ships a full CLI with `lookup`, `rip`, `organize`, and `orchestrate` workflows. For the end-to-end terminal flow, see the [CLI Workflow guide](docs/cli-guide/workflow.md).
+
+After installing:
+
+1. Run setup. The GUI walks you through it on first launch, or you can use [`riplex setup`](docs/getting-started/installation.md#setup).
+2. If you want to see the GUI step by step, read the [GUI Walkthrough](docs/gui-guide/gui-walkthrough.md).
+3. Follow the [CLI Workflow guide](docs/cli-guide/workflow.md) for the end-to-end flow.
+4. If you prefer the terminal, use the [CLI reference](docs/reference/cli.md) for command details.
+
+## What it looks like
+
+Instead of leaving you to sort through a wall of raw MakeMKV titles, riplex helps you understand what is actually on the disc and choose the titles worth ripping. It surfaces likely matches, highlights junk and duplicates, and helps you avoid play-all traps.
+
+![Title selection](screenshots/5_Select_Title_to_RIP_BTTF.png)
+
+More screenshots:
+[welcome](screenshots/1_Welcome_Screen.png),
+[disc detection](screenshots/2_Disc_Detection_BTTF.png),
+[metadata lookup](screenshots/3_Metadata_Lookup_BTTF.png),
+[release picker](screenshots/4_Disc_Release_BTTF.png),
+[disc overview](screenshots/5_Multi_Disc_Overview_BTTF.png).
+
+> [!NOTE]
+> riplex currently handles one film (or one TV show) per session. Multi-film box sets that bundle separate films onto separate discs (e.g. a trilogy in one box) need to be ripped one film at a time.
+
+## Requirements
+
+riplex uses MakeMKV, ffmpeg, and MKVToolNix under the hood. The setup wizard installs them for you on Windows (winget), macOS (Homebrew), and Debian/Ubuntu Linux (apt). On other platforms see [the installation guide](docs/getting-started/installation.md).
+
+You'll also need a free [TMDb API key](https://www.themoviedb.org/settings/api). The wizard prompts you for it.
+
+## Data sources
+
+- **[TMDb](https://www.themoviedb.org/)**: canonical movie and TV metadata (titles, years, episodes, runtimes)
+- **[dvdcompare.net](https://www.dvdcompare.net)**: per-disc content breakdowns (featurettes, deleted scenes, play-all groupings, runtimes). An invaluable community resource.
+
+## Related projects
+
+- **[dvdcompare-scraper](https://github.com/AnyCredit5518/dvdcompare-scraper)**: Python client for dvdcompare.net. Powers riplex's disc lookup. Contributions welcome.
+
+## Documentation
+
+- [Getting started](docs/getting-started/installation.md): installation, configuration
+- [GUI walkthrough](docs/gui-guide/gui-walkthrough.md): the main desktop flow, screen by screen
+- [CLI workflow](docs/cli-guide/workflow.md): end-to-end terminal workflows
+- [CLI reference](docs/reference/cli.md): every command and flag
+- [Architecture](docs/architecture.md): design, data flow, project structure
+
+## License
+
+MIT

{riplex-0.7.1 → riplex-0.7.3}/docs/changelog.md

@@ -4,6 +4,29 @@ All notable changes to the riplex documentation are recorded here.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## v0.7.3 — 2026-06-10
+
+### Fixed
+
+- **GUI: silent "No optical drives detected" when MakeMKV is expired or unregistered.** When `makemkvcon` rejects requests with a fatal MSG (codes `5021` too-old, `5022` key-expired, `5023` key-invalid) it exits cleanly with zero `DRV:` lines, so riplex previously rendered an empty drive list. The shared library now parses these fatal MSGs and raises `MakeMKVError`; the Disc Detection screen surfaces the verbatim `makemkvcon` message along with **Download MakeMKV ↗** and **Get beta key ↗** buttons so users can resolve the lockout in one click.
+
+## v0.7.2 — 2026-05-17
+
+### Fixed
+
+- **Auto-detected disc labels with compact season/disc suffixes.** Volume labels such as `Hannibal St01bd1` and `HANNIBAL_S1_BD1` now strip the trailing season/disc marker before TMDb and dvdcompare lookup, so both the GUI and CLI start from the correct base title instead of searching for the raw disc label.
+
+## 2026-05-16
+
+### Added
+
+- New GUI walkthrough guide with screenshots for the main desktop flow: welcome, disc detection, metadata lookup, release picker, title selection, and multi-disc overview.
+
+### Changed
+
+- Split the user guides into `docs/gui-guide/` and `docs/cli-guide/` so the desktop flow and terminal flow are documented separately.
+- Linked the new GUI walkthrough from the README, installation guide, CLI workflow guide, and docs index so beginners can discover the desktop flow more easily.
+
 ## v0.7.1 — 2026-05-16
 
 ### Fixed
@@ -141,7 +164,7 @@ Summary: organize-time match quality fixes, faster post-rip organize, and a rele
 
 ### Added
 
-- Orchestrate guide (`docs/guide/orchestrate.md`): full documentation for the new primary workflow command
+- Orchestrate guide (`docs/cli-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)
@@ -159,7 +182,7 @@ Summary: organize-time match quality fixes, faster post-rip organize, and a rele
 - 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/cli-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

{riplex-0.7.1/docs/guide → riplex-0.7.3/docs/cli-guide}/workflow.md

@@ -1,6 +1,9 @@
-# Typical Workflow
+# CLI Workflow
 
-This page walks through the recommended end-to-end workflow for ripping a disc set and organizing it into Plex.
+This page walks through the recommended end-to-end command-line workflow for ripping a disc set and organizing it into Plex.
+
+If you want to see the desktop app screen by screen first, start with the
+[GUI Walkthrough](../gui-guide/gui-walkthrough.md).
 
 ## Recommended: Use `orchestrate`
 

{riplex-0.7.1 → riplex-0.7.3}/docs/getting-started/installation.md

@@ -4,9 +4,12 @@
 
 There are three ways to install riplex:
 
-- **[Pre-built executables](#option-a-pre-built-executables)** - easiest, no Python needed
-- **[pipx](#option-b-install-with-pipx-recommended)** - recommended for Python users
-- **[From source](#option-c-install-from-source)** - for developers
+- **[Pre-built executables](#option-a-pre-built-executables)** — fastest
+  way to try riplex. No Python required, but upgrades mean re-downloading.
+- **[pipx](#option-b-install-with-pipx-recommended)** — recommended.
+  Requires Python, but `pipx upgrade riplex` makes staying current effortless.
+- **[From source](#option-c-install-from-source)** — for developers and
+  platforms without a pre-built binary (Intel Mac, Linux).
 
 ### Option A: Pre-built executables
 
@@ -225,6 +228,12 @@ riplex setup
 Or just launch the GUI -- it checks for missing tools on startup and walks you
 through setup automatically.
 
+If you want to preview the desktop flow before ripping a disc, see the
+[GUI Walkthrough](../gui-guide/gui-walkthrough.md).
+
+If you prefer the terminal workflow after setup, see the
+[CLI Workflow guide](../cli-guide/workflow.md).
+
 The setup wizard will:
 
 1. Ask for your TMDb API key (free at https://www.themoviedb.org/settings/api)

riplex-0.7.3/docs/gui-guide/gui-walkthrough.md

@@ -0,0 +1,90 @@
+# GUI Walkthrough
+
+This page walks through the main riplex GUI flow using the screenshots in this repo. It is not a screen-by-screen reference manual. The goal is to show what each step is for, what decision you make there, and what happens next.
+
+## 1. Welcome
+
+![Welcome screen](../../screenshots/1_Welcome_Screen.png)
+
+The Welcome screen checks your setup before you start. If riplex is missing a required tool or configuration value, this is where it tells you.
+
+What you do here:
+- confirm that your TMDb key and output paths are configured
+- let riplex install or point to missing tools if needed
+- continue once the environment is ready
+
+## 2. Disc detection
+
+![Disc detection](../../screenshots/2_Disc_Detection_BTTF.png)
+
+Once a disc is in the drive, riplex detects it and reads the volume label.
+
+What you do here:
+- verify that the detected disc is the one you intended to rip
+- if multiple drives are present, choose the correct drive
+- continue once the disc has been read successfully
+
+Troubleshooting:
+- if no drive appears, verify that MakeMKV can see the drive and that `makemkvcon` is installed correctly
+- if the detected title is wrong, you can correct it on the next step
+
+## 3. Metadata lookup
+
+![Metadata lookup](../../screenshots/3_Metadata_Lookup_BTTF.png)
+
+riplex uses the disc label as a starting point, then looks up the title on TMDb.
+
+What you do here:
+- confirm the detected title if it is already correct
+- edit the search text if the disc label is abbreviated or noisy
+- choose the correct TMDb match if there is more than one possible result
+
+## 4. Release picker
+
+![Release picker](../../screenshots/4_Disc_Release_BTTF.png)
+
+After the TMDb title is confirmed, riplex looks up the corresponding physical-media release on dvdcompare.net.
+
+What you do here:
+- pick the release that matches the disc in your drive
+- pay attention to format and region when several similar releases exist
+- use the dvdcompare link to verify the page if needed
+
+Troubleshooting:
+- if riplex picks the wrong dvdcompare page, use the manual override on this screen to paste a dvdcompare film id or URL
+
+## 5. Title selection
+
+![Title selection](../../screenshots/5_Select_Title_to_RIP_BTTF.png)
+
+This is the most important decision point in the GUI. riplex analyzes the disc, classifies the titles, and shows you what is likely worth ripping.
+
+What you do here:
+- review the recommended titles before starting the rip
+- keep the main feature, episodes, or useful extras selected
+- deselect obvious junk, duplicates, or play-all titles if needed
+
+Why this screen matters:
+- MakeMKV exposes raw titles and durations, but not what those titles actually are
+- riplex uses metadata, disc context, and runtime matching to turn that pile of titles into something understandable
+
+## 6. Disc overview for multi-disc releases
+
+![Disc overview](../../screenshots/5_Multi_Disc_Overview_BTTF.png)
+
+When a single film release spans multiple discs, riplex keeps them together as one project and shows you where the current disc fits into the full release.
+
+What you do here:
+- confirm that you are ripping the expected disc in the set
+- move through the discs in order as riplex prompts you
+- let riplex merge the results into one organized output when the project is complete
+
+Important note:
+- riplex currently handles one film or one TV show per session
+- multi-film box sets still need to be ripped one film at a time
+
+## What comes next
+
+After title selection, riplex starts the rip, shows progress, and then summarizes the results when it finishes.
+
+If you want the full end-to-end terminal flow after setup, see the [CLI Workflow](../cli-guide/workflow.md).

{riplex-0.7.1 → riplex-0.7.3}/docs/index.md

@@ -10,10 +10,10 @@ riplex has four commands, each targeting a different stage of the disc ripping w
 
 | Command | Stage | What it does |
 |---|---|---|
-| [`orchestrate`](guide/orchestrate.md) | Full pipeline | Multi-disc rip-then-organize in one session |
+| [`orchestrate`](cli-guide/orchestrate.md) | Full pipeline | Multi-disc rip-then-organize in one session |
 | [`rip`](reference/cli.md#rip) | Ripping | Single-disc rip via makemkvcon with auto title selection |
-| [`organize`](guide/organize.md) | After ripping | Scans MKV files, deduplicates, matches by runtime, moves into Plex layout |
-| [`lookup`](guide/lookup.md) | Before ripping | Shows disc contents from dvdcompare, recommends which titles to rip, creates folder structure |
+| [`organize`](cli-guide/organize.md) | After ripping | Scans MKV files, deduplicates, matches by runtime, moves into Plex layout |
+| [`lookup`](cli-guide/lookup.md) | Before ripping | Shows disc contents from dvdcompare, recommends which titles to rip, creates folder structure |
 
 ## Quick start
 
@@ -33,6 +33,9 @@ riplex organize path/to/rips/Oppenheimer --execute
 
 See [Installation](getting-started/installation.md) for full setup instructions.
 
+If you prefer the desktop app, see the [GUI Walkthrough](gui-guide/gui-walkthrough.md)
+for the main flow with screenshots.
+
 ## Features
 
 - **TMDb integration**: Identifies movies vs TV shows, gets canonical titles, episode lists, and runtimes

{riplex-0.7.1 → riplex-0.7.3}/mkdocs.yml

@@ -48,11 +48,13 @@ nav:
   - Getting Started:
       - Installation: getting-started/installation.md
       - Configuration: getting-started/configuration.md
-  - User Guide:
-      - Typical Workflow: guide/workflow.md
-      - Orchestrate: guide/orchestrate.md
-      - Lookup: guide/lookup.md
-      - Organizing Files: guide/organize.md
+  - GUI Guide:
+    - Walkthrough: gui-guide/gui-walkthrough.md
+  - CLI Guide:
+    - Workflow: cli-guide/workflow.md
+    - Orchestrate: cli-guide/orchestrate.md
+    - Lookup: cli-guide/lookup.md
+    - Organizing Files: cli-guide/organize.md
   - CLI Reference: reference/cli.md
   - Architecture: architecture.md
   - Plex Naming Rules: naming-rules.md

{riplex-0.7.1 → riplex-0.7.3}/src/riplex/detect.py

@@ -10,7 +10,9 @@ import logging
 import re
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Literal
+
+from riplex.title import parse_season_number, parse_title_and_season, strip_year_from_title
 
 if TYPE_CHECKING:
     from riplex.models import ScannedDisc, ScannedFile
@@ -34,9 +36,18 @@ class TitleGroup:
 
     title: str
     folders: list[Path] = field(default_factory=list)
+    season_number: int | None = None
     detected_format: str | None = None
 
 
+@dataclass
+class OrganizeLayout:
+    """How an organize root should be processed."""
+
+    mode: Literal["single", "batch", "empty"]
+    groups: list[TitleGroup] = field(default_factory=list)
+
+
 def detect_format(discs: list[ScannedDisc]) -> str | None:
     """Infer disc format from the maximum video resolution across all files.
 
@@ -124,7 +135,8 @@ def group_title_folders(root: Path) -> list[TitleGroup]:
     Ignores folders starting with ``_`` (e.g. ``_archive``).
     Returns groups sorted by title, each containing the original folder paths.
     """
-    groups: dict[str, list[Path]] = {}
+    groups: dict[tuple[str, int | None], list[Path]] = {}
+    root_title, _ = strip_year_from_title(root.name)
 
     for sub in sorted(root.iterdir()):
         if not sub.is_dir():
@@ -142,14 +154,38 @@ def group_title_folders(root: Path) -> list[TitleGroup]:
             continue
 
         base = _normalize_title(sub.name)
-        groups.setdefault(base, []).append(sub)
+        title, season_number = parse_title_and_season(base)
+        if title is None and season_number is not None:
+            title = root_title
+        if title is None:
+            title = base
+            season_number = parse_season_number(base)
+        groups.setdefault((title, season_number), []).append(sub)
 
     result: list[TitleGroup] = []
-    for title in sorted(groups):
-        result.append(TitleGroup(title=title, folders=groups[title]))
+    for title, season_number in sorted(groups):
+        result.append(TitleGroup(title=title, folders=groups[(title, season_number)], season_number=season_number))
     return result
 
 
+def detect_organize_layout(root: Path) -> OrganizeLayout:
+    """Classify an organize root as single-title, batch, or empty.
+
+    Single mode covers a flat folder of MKVs or a folder whose immediate
+    subfolders are disc folders. Batch mode covers roots that contain nested
+    season/title folders such as ``Show/Season 6/Disc 1``.
+    """
+    has_root_mkvs = any(root.glob("*.mkv"))
+    has_sub_mkvs = any(root.glob("*/*.mkv"))
+    has_nested_mkvs = any(root.glob("*/*/*.mkv"))
+
+    if has_root_mkvs or (has_sub_mkvs and not has_nested_mkvs):
+        return OrganizeLayout(mode="single")
+    if has_sub_mkvs or has_nested_mkvs:
+        return OrganizeLayout(mode="batch", groups=group_title_folders(root))
+    return OrganizeLayout(mode="empty")
+
+
 def infer_media_type(disc_info) -> str:
     """Infer 'movie' or 'tv' from disc title structure.
 

{riplex-0.7.1 → riplex-0.7.3}/src/riplex/disc/makemkv.py

@@ -114,6 +114,15 @@ class MakeMKVPreflight:
     error: str = ""  # short human-readable failure reason
 
 
+class MakeMKVError(RuntimeError):
+    """makemkvcon ran but refused to do useful work (e.g. expired beta key)."""
+
+    def __init__(self, message: str, *, code: int | None = None, raw: str = ""):
+        super().__init__(message)
+        self.code = code
+        self.raw = raw
+
+
 @dataclass
 class DiscInfo:
     """Parsed disc information from makemkvcon -r info."""
@@ -276,6 +285,43 @@ def parse_drive_list(output: str) -> list[DriveInfo]:
     return drives
 
 
+# MSG codes makemkvcon emits when it refuses to do real work. The user-facing
+# message is the first quoted field. Anything in this set should be surfaced
+# verbatim to the user with an actionable hint, since the rest of the run
+# will silently produce empty results otherwise (no DRV lines, no titles).
+_MAKEMKV_FATAL_MSG_CODES: frozenset[int] = frozenset({
+    5021,  # "This application version is too old..." (expired beta key)
+    5022,  # registration key expired
+    5023,  # registration key invalid
+})
+
+
+def parse_fatal_message(output: str) -> tuple[int, str] | None:
+    """Return ``(code, message)`` for the first known fatal MSG line, else None.
+
+    makemkvcon emits ``MSG:<code>,<flags>,<count>,"<text>",...`` lines.
+    When it refuses to scan (expired beta, invalid key, etc.) it prints
+    one of those and then exits without any ``DRV:`` lines, which makes
+    ``parse_drive_list`` legitimately return ``[]``. Callers can use
+    this helper to distinguish "no drives" from "makemkvcon won't run".
+    """
+    for line in output.splitlines():
+        if not line.startswith("MSG:"):
+            continue
+        parts = _split_robot_line(line[4:])
+        if len(parts) < 4:
+            continue
+        try:
+            code = int(parts[0])
+        except ValueError:
+            continue
+        if code not in _MAKEMKV_FATAL_MSG_CODES:
+            continue
+        # parts[3] is the rendered, human-readable message text.
+        return code, parts[3]
+    return None
+
+
 def _split_robot_line(text: str) -> list[str]:
     """Split a makemkvcon robot-mode CSV line, respecting quoted strings."""
     parts: list[str] = []
@@ -415,7 +461,12 @@ class MakeMKV:
         return parse_disc_info(output)
 
     def drive_list(self) -> list[DriveInfo]:
-        """List available optical drives."""
+        """List available optical drives.
+
+        Raises :class:`MakeMKVError` if makemkvcon ran but returned no
+        drive lines because of a known fatal condition (most commonly
+        an expired beta version that refuses to scan until updated).
+        """
         exe = self._require_exe()
 
         cmd = [str(exe), "-r", "info", "list"]
@@ -429,7 +480,13 @@ class MakeMKV:
             **_SUBPROCESS_FLAGS,
         )
         output = result.stdout + result.stderr
-        return parse_drive_list(output)
+        drives = parse_drive_list(output)
+        if not drives:
+            fatal = parse_fatal_message(output)
+            if fatal is not None:
+                code, message = fatal
+                raise MakeMKVError(message, code=code, raw=output)
+        return drives
 
     def resolve_drive(self, drive_arg: str = "auto") -> DriveInfo:
         """Resolve a drive argument to a :class:`DriveInfo`.

{riplex-0.7.1 → riplex-0.7.3}/src/riplex/lookup.py

@@ -63,8 +63,11 @@ async def lookup_metadata(
 
     if not skip_dvdcompare:
         try:
+            dvdcompare_title = canonical
+            if not is_movie and request.season_number is not None:
+                dvdcompare_title = f"{canonical}: Season {request.season_number}"
             discs, release_name = await fetch_and_select_release(
-                canonical,
+                dvdcompare_title,
                 disc_format=disc_format,
                 disc_info=disc_info,
                 preferred=preferred_release,

{riplex-0.7.1 → riplex-0.7.3}/src/riplex/metadata/planner.py

@@ -139,6 +139,8 @@ async def _plan_show(
 
     seasons: list[PlannedSeason] = []
     for sm in detail.seasons:
+        if request.season_number is not None and sm.season_number != request.season_number:
+            continue
         episodes: list[PlannedEpisode] = []
         for em in sm.episodes:
             fname = episode_file_name(

{riplex-0.7.1 → riplex-0.7.3}/src/riplex/models.py

@@ -12,6 +12,7 @@ class SearchRequest:
 
     title: str
     year: int | None = None
+    season_number: int | None = None
     media_type: Literal["movie", "tv", "auto"] = "auto"
     include_specials: bool = True
     include_extras_skeleton: bool = True