mkv-episode-matcher 0.9.2__tar.gz → 0.9.4__tar.gz

{mkv_episode_matcher-0.9.2 → mkv_episode_matcher-0.9.4}/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.3] - 2025-07-07
+
+### Added
+- Onboarding flag (`--onboard`) and interactive onboarding sequence for first-time setup and configuration updates
+- Onboarding prompts for TMDb API key, OpenSubtitles API key, Consumer Name, Username, Password, and Show Directory
+- Existing config values are shown as defaults during onboarding and can be accepted or overwritten
+- Documentation updated to reflect onboarding requirements and workflow in README and docs
+
+### Changed
+- Improved configuration experience for new and returning users
+- Quick Start and Configuration documentation now reference onboarding and required credentials
+
 ## [0.9.0] - 2025-06-01
 
 ### Changed

mkv_episode_matcher-0.9.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jonathan Sakkos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{mkv_episode_matcher-0.9.2 → mkv_episode_matcher-0.9.4}/PKG-INFO

@@ -1,11 +1,31 @@
 Metadata-Version: 2.4
 Name: mkv-episode-matcher
-Version: 0.9.2
+Version: 0.9.4
 Summary: The MKV Episode Matcher is a tool for identifying TV series episodes from MKV files and renaming the files accordingly.
 Home-page: https://github.com/Jsakkos/mkv-episode-matcher
 Author: Jonathan Sakkos
 Author-email: Jsakkos <jonathansakkos@gmail.com>
-License: MIT
+License: MIT License
+        
+        Copyright (c) 2025 Jonathan Sakkos
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
 Project-URL: Documentation, https://github.com/Jsakkos/mkv-episode-matcher#readme
 Project-URL: Issues, https://github.com/Jsakkos/mkv-episode-matcher/issues
 Project-URL: Source, https://github.com/Jsakkos/mkv-episode-matcher
@@ -16,6 +36,8 @@ Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Requires-Python: <3.13,>=3.9
 Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: chardet>=5.2.0
 Requires-Dist: configparser>=7.1.0
 Requires-Dist: ffmpeg>=1.4
 Requires-Dist: loguru>=0.7.2
@@ -28,6 +50,7 @@ Requires-Dist: tmdb-client>=0.0.1
 Requires-Dist: torch>=2.5.1
 Requires-Dist: torchaudio>=2.5.1
 Requires-Dist: torchvision>=0.20.1
+Dynamic: license-file
 
 # MKV Episode Matcher
 
@@ -45,15 +68,11 @@ Automatically match and rename your MKV TV episodes using The Movie Database (TM
 
 ## Features
 
-- 🎯 **Automatic Episode Matching**: Uses TMDb to accurately identify episodes
-- 🎨 **Rich User Interface**: Color-coded output and progress indicators
-- 📝 **Subtitle Extraction**: Extracts subtitles from MKV files
-- 🔊 **Speech Recognition**: Uses Whisper for accurate episode identification
-- 🚀 **Multi-threaded**: Fast processing of multiple files
+- 🎯 **Automatic Episode Matching**: Uses TMDb and OpenSubtitles to accurately identify episodes
+- 🔊 **Speech Recognition**: Uses OpenAI Whisper for accurate episode identification
 - ⬇️ **Subtitle Downloads**: Integration with OpenSubtitles
 - ✨ **Bulk Processing**: Handle entire seasons at once
 - 🧪 **Dry Run Mode**: Test changes before applying
-- 🎮 **Interactive Mode**: User-friendly season selection and configuration
 
 ## Prerequisites
 
@@ -66,15 +85,41 @@ Automatically match and rename your MKV TV episodes using The Movie Database (TM
 
 1. Install the package:
 ```bash
-pip install mkv-episode-matcher
+pip install -U mkv-episode-matcher
 ```
-2. Download .srt subtitles files to ~/.mkv-episode-matcher/cache/data/Show Name/
+2. Run onboarding to set up your configuration (first-time users or to update credentials):
+```bash
+mkv-match --onboard
+```
+   - You will be prompted for:
+     - TMDb API key (for episode matching)
+     - OpenSubtitles API key, Consumer Name, Username, and Password (for subtitle downloads)
+     - Show Directory (main directory of your show)
+   - If a config value already exists, you can accept the default or enter a new value.
 
-3. Run on your show directory:
+3. 
+   a. If you setup the TMDb and Opensubtitles credentials above, automatically fetch subtitles with the `--get-subs` flag. 
+   b. Alternatively, manually download .srt subtitles files to ~/.mkv-episode-matcher/cache/data/Show Name/
+
+4. Run on your show directory:
 ```bash
 mkv-match --show-dir "path/to/your/show"
 ```
 
+## Onboarding & Configuration
+
+The onboarding process will prompt you for all required configuration values if you run with `--onboard` or if no config file exists. You can re-run onboarding at any time to update your credentials or show directory.
+
+**Required information:**
+- TMDb API key (for episode matching)
+- OpenSubtitles API key (for subtitle downloads)
+- OpenSubtitles Consumer Name (for subtitle downloads)
+- OpenSubtitles Username (for subtitle downloads)
+- OpenSubtitles Password (for subtitle downloads)
+- Show Directory (main directory of your show)
+
+If a value already exists, it will be shown as the default and you can accept it or enter a new value.
+
 ## Directory Structure
 
 MKV Episode Matcher expects your TV shows to be organized as follows:

{mkv_episode_matcher-0.9.2 → mkv_episode_matcher-0.9.4}/README.md

@@ -14,15 +14,11 @@ Automatically match and rename your MKV TV episodes using The Movie Database (TM
 
 ## Features
 
-- 🎯 **Automatic Episode Matching**: Uses TMDb to accurately identify episodes
-- 🎨 **Rich User Interface**: Color-coded output and progress indicators
-- 📝 **Subtitle Extraction**: Extracts subtitles from MKV files
-- 🔊 **Speech Recognition**: Uses Whisper for accurate episode identification
-- 🚀 **Multi-threaded**: Fast processing of multiple files
+- 🎯 **Automatic Episode Matching**: Uses TMDb and OpenSubtitles to accurately identify episodes
+- 🔊 **Speech Recognition**: Uses OpenAI Whisper for accurate episode identification
 - ⬇️ **Subtitle Downloads**: Integration with OpenSubtitles
 - ✨ **Bulk Processing**: Handle entire seasons at once
 - 🧪 **Dry Run Mode**: Test changes before applying
-- 🎮 **Interactive Mode**: User-friendly season selection and configuration
 
 ## Prerequisites
 
@@ -35,15 +31,41 @@ Automatically match and rename your MKV TV episodes using The Movie Database (TM
 
 1. Install the package:
 ```bash
-pip install mkv-episode-matcher
+pip install -U mkv-episode-matcher
 ```
-2. Download .srt subtitles files to ~/.mkv-episode-matcher/cache/data/Show Name/
+2. Run onboarding to set up your configuration (first-time users or to update credentials):
+```bash
+mkv-match --onboard
+```
+   - You will be prompted for:
+     - TMDb API key (for episode matching)
+     - OpenSubtitles API key, Consumer Name, Username, and Password (for subtitle downloads)
+     - Show Directory (main directory of your show)
+   - If a config value already exists, you can accept the default or enter a new value.
 
-3. Run on your show directory:
+3. 
+   a. If you setup the TMDb and Opensubtitles credentials above, automatically fetch subtitles with the `--get-subs` flag. 
+   b. Alternatively, manually download .srt subtitles files to ~/.mkv-episode-matcher/cache/data/Show Name/
+
+4. Run on your show directory:
 ```bash
 mkv-match --show-dir "path/to/your/show"
 ```
 
+## Onboarding & Configuration
+
+The onboarding process will prompt you for all required configuration values if you run with `--onboard` or if no config file exists. You can re-run onboarding at any time to update your credentials or show directory.
+
+**Required information:**
+- TMDb API key (for episode matching)
+- OpenSubtitles API key (for subtitle downloads)
+- OpenSubtitles Consumer Name (for subtitle downloads)
+- OpenSubtitles Username (for subtitle downloads)
+- OpenSubtitles Password (for subtitle downloads)
+- Show Directory (main directory of your show)
+
+If a value already exists, it will be shown as the default and you can accept it or enter a new value.
+
 ## Directory Structure
 
 MKV Episode Matcher expects your TV shows to be organized as follows:

{mkv_episode_matcher-0.9.2 → mkv_episode_matcher-0.9.4}/docs/configuration.md

@@ -36,25 +36,6 @@ mkv-match \
   --get-subs true
 ```
 
-## Environment Variables
-
-You can also use environment variables:
-
-```bash
-export TMDB_API_KEY="your_key"
-export SHOW_DIR="/path/to/shows"
-export OPEN_SUBTITLES_API_KEY="your_key"
-```
-
-## Configuration Priority
-
-Settings are loaded in the following order (later overrides earlier):
-
-1. Default values
-2. Configuration file
-3. Environment variables
-4. Command line arguments
-
 ## Detailed Options
 
 ### TMDb Configuration

{mkv_episode_matcher-0.9.2 → mkv_episode_matcher-0.9.4}/docs/quickstart.md

@@ -4,22 +4,36 @@ Get started with MKV Episode Matcher quickly and efficiently.
 
 ## Basic Usage
 
-### 1. Interactive Mode
+### 1. Onboarding (First-Time Setup)
+
+Before running any matching, set up your configuration:
+```bash
+mkv-match --onboard
+```
+You will be prompted for:
+- TMDb API key (for episode matching)
+- OpenSubtitles API key, Consumer Name, Username, and Password (for subtitle downloads)
+- Show Directory (main directory of your show)
+If a value already exists, you can accept the default or enter a new value.
+
+You can re-run onboarding at any time to update your credentials or show directory.
+
+### 2. Interactive Mode
 
 Simply run:
 ```bash
 mkv-match
 ```
-The program will guide you through the setup interactively.
+The program will guide you through the setup interactively if configuration is missing.
 
-### 2. Command Line Options
+### 3. Command Line Options
 
 Process a specific season:
 ```bash
 mkv-match --show-dir "/path/to/show" --season 1
 ```
 
-Process all seasons with subtitles:
+Process all seasons with subtitles (requires onboarding):
 ```bash
 mkv-match --show-dir "/path/to/show" --get-subs
 ```
@@ -53,7 +67,12 @@ Show Name/
 
 ## Configuration
 
-Configuration is stored at `~/.mkv-episode-matcher/config.ini`:
+Configuration is stored at `~/.mkv-episode-matcher/config.ini` and can be set up or updated at any time with:
+```bash
+mkv-match --onboard
+```
+
+Example config:
 ```ini
 [Config]
 tmdb_api_key = your_tmdb_api_key

{mkv_episode_matcher-0.9.2 → mkv_episode_matcher-0.9.4}/mkv_episode_matcher/__main__.py

@@ -7,7 +7,6 @@ from typing import Optional
 from loguru import logger
 from rich.console import Console
 from rich.panel import Panel
-from rich.progress import Progress, SpinnerColumn, TextColumn
 from rich.prompt import Confirm, Prompt
 
 from mkv_episode_matcher import __version__
@@ -62,15 +61,17 @@ def print_welcome_message():
     console.print()
 
 
-def confirm_api_key(config_value: Optional[str], key_name: str, description: str) -> str:
+def confirm_api_key(
+    config_value: Optional[str], key_name: str, description: str
+) -> str:
     """
     Confirm if the user wants to use an existing API key or enter a new one.
-    
+
     Args:
         config_value: The current value from the config
         key_name: The name of the key
         description: Description of the key for user information
-        
+
     Returns:
         The API key to use
     """
@@ -79,7 +80,7 @@ def confirm_api_key(config_value: Optional[str], key_name: str, description: str
         console.print(f"Current value: [green]{mask_api_key(config_value)}[/green]")
         if Confirm.ask("Use existing key?", default=True):
             return config_value
-    
+
     return Prompt.ask(f"Enter your {key_name}")
 
 
@@ -95,10 +96,10 @@ def mask_api_key(key: str) -> str:
 def select_season(seasons):
     """
     Allow user to select a season from a list.
-    
+
     Args:
         seasons: List of available seasons
-        
+
     Returns:
         Selected season number or None for all seasons
     """
@@ -106,21 +107,51 @@ def select_season(seasons):
     for i, season in enumerate(seasons, 1):
         season_num = Path(season).name.replace("Season ", "")
         console.print(f"  {i}. Season {season_num}")
-    
-    console.print(f"  0. All Seasons")
-    
+
+    console.print("  0. All Seasons")
+
     choice = Prompt.ask(
         "Select a season number (0 for all)",
         choices=[str(i) for i in range(len(seasons) + 1)],
-        default="0"
+        default="0",
     )
-    
+
     if int(choice) == 0:
         return None
-    
+
     selected_season = seasons[int(choice) - 1]
     return int(Path(selected_season).name.replace("Season ", ""))
 
+def onboarding(config_path):
+    """Prompt user for all required config values, showing existing as defaults."""
+    config = get_config(config_path) if config_path.exists() else {}
+
+    def ask_with_default(prompt_text, key, description, secret=False):
+        current = config.get(key)
+        if current:
+            console.print(f"[cyan]{key}:[/cyan] {description}")
+            console.print(f"Current value: [green]{mask_api_key(current) if secret else current}[/green]")
+            if Confirm.ask("Use existing value?", default=True):
+                return current
+        return Prompt.ask(f"Enter your {key}", default=current or "")
+
+    tmdb_api_key = ask_with_default("TMDb API key", "tmdb_api_key", "Used to lookup show and episode information. To get your API key, create an account at https://www.themoviedb.org/ and follow the instructions at https://developer.themoviedb.org/docs/getting-started", secret=True)
+    open_subtitles_username = ask_with_default("OpenSubtitles Username", "open_subtitles_username", "Account username for OpenSubtitles. To create an account, visit https://www.opensubtitles.com/ then click 'Register'")
+    open_subtitles_password = ask_with_default("OpenSubtitles Password", "open_subtitles_password", "Account password for OpenSubtitles", secret=True)
+    open_subtitles_user_agent = ask_with_default("OpenSubtitles Consumer Name", "open_subtitles_user_agent", "Required for subtitle downloads. Go to https://www.opensubtitles.com/en/consumers, click 'New Consumer', give it a name, then click 'Save'")
+    open_subtitles_api_key = ask_with_default("OpenSubtitles API key", "open_subtitles_api_key", "Required for subtitle downloads. Enter the API key linked with the OpenSubtitles Consumer that you created in the previous step.", secret=True)
+    show_dir = ask_with_default("Show Directory", "show_dir", "Main directory of the show")
+
+    set_config(
+        tmdb_api_key,
+        open_subtitles_api_key,
+        open_subtitles_user_agent,
+        open_subtitles_username,
+        open_subtitles_password,
+        show_dir,
+        config_path,
+    )
+    console.print("[bold green]Onboarding complete! Configuration saved.[/bold green]")
 
 @logger.catch
 def main():
@@ -165,7 +196,8 @@ def main():
         help="Check if GPU is available for faster processing",
     )
     parser.add_argument(
-        "--verbose", "-v",
+        "--verbose",
+        "-v",
         action="store_true",
         help="Enable verbose output",
     )
@@ -175,22 +207,30 @@ def main():
         default=0.7,
         help="Set confidence threshold for episode matching (0.0-1.0)",
     )
-    
+    parser.add_argument(
+        "--onboard",
+        action="store_true",
+        help="Run onboarding to set up configuration",
+    )
     args = parser.parse_args()
     if args.verbose:
         console.print("[bold cyan]Command-line Arguments[/bold cyan]")
         console.print(args)
     if args.check_gpu:
         from mkv_episode_matcher.utils import check_gpu_support
+
         with console.status("[bold green]Checking GPU support..."):
             check_gpu_support()
         return
 
-    
     logger.debug(f"Command-line arguments: {args}")
-
-    # Load configuration once
-    config = get_config(CONFIG_FILE)
+    # Onboarding: run if --onboard or config file missing
+    if args.onboard or not CONFIG_FILE.exists():
+        onboarding(CONFIG_FILE)
+        # Reload config after onboarding
+        config = get_config(CONFIG_FILE)
+    else:
+        config = get_config(CONFIG_FILE)
 
     # Get TMDb API key
     tmdb_api_key = args.tmdb_api_key or config.get("tmdb_api_key")
@@ -202,49 +242,49 @@ def main():
 
     if args.get_subs:
         console.print("[bold cyan]Subtitle Download Configuration[/bold cyan]")
-        
+
         tmdb_api_key = confirm_api_key(
-            tmdb_api_key, 
-            "TMDb API key", 
-            "Used to lookup show and episode information"
+            tmdb_api_key, "TMDb API key", "Used to lookup show and episode information"
         )
-        
+
         open_subtitles_api_key = confirm_api_key(
             open_subtitles_api_key,
             "OpenSubtitles API key",
-            "Required for subtitle downloads"
+            "Required for subtitle downloads",
         )
-        
+
         open_subtitles_user_agent = confirm_api_key(
             open_subtitles_user_agent,
             "OpenSubtitles User Agent",
-            "Required for subtitle downloads"
+            "Required for subtitle downloads",
         )
-        
+
         open_subtitles_username = confirm_api_key(
             open_subtitles_username,
             "OpenSubtitles Username",
-            "Account username for OpenSubtitles"
+            "Account username for OpenSubtitles",
         )
-        
+
         open_subtitles_password = confirm_api_key(
             open_subtitles_password,
             "OpenSubtitles Password",
-            "Account password for OpenSubtitles"
+            "Account password for OpenSubtitles",
         )
 
     # Use config for show directory
     show_dir = args.show_dir or config.get("show_dir")
     if not show_dir:
         show_dir = Prompt.ask("Enter the main directory of the show")
-    
+
     logger.info(f"Show Directory: {show_dir}")
     if not Path(show_dir).exists():
-        console.print(f"[bold red]Error:[/bold red] Show directory '{show_dir}' does not exist.")
+        console.print(
+            f"[bold red]Error:[/bold red] Show directory '{show_dir}' does not exist."
+        )
         return
-    
+
     if not show_dir:
-        show_dir = os.getcwd()
+        show_dir = Path.cwd()
         console.print(f"Using current directory: [cyan]{show_dir}[/cyan]")
 
     logger.debug(f"Show Directory: {show_dir}")
@@ -274,25 +314,27 @@ def main():
                 border_style="yellow",
             )
         )
-    
+
     seasons = get_valid_seasons(show_dir)
     if not seasons:
-        console.print("[bold red]Error:[/bold red] No seasons with .mkv files found in the show directory.")
+        console.print(
+            "[bold red]Error:[/bold red] No seasons with .mkv files found in the show directory."
+        )
         return
-    
+
     # If season wasn't specified and there are multiple seasons, let user choose
     selected_season = args.season
     if selected_season is None and len(seasons) > 1:
         selected_season = select_season(seasons)
-    
+
     # Show what's going to happen
     show_name = Path(show_dir).name
     season_text = f"Season {selected_season}" if selected_season else "all seasons"
-    
+
     console.print(
         f"[bold green]Processing[/bold green] [cyan]{show_name}[/cyan], {season_text}"
     )
-    
+
     # # Setup progress spinner
     # with Progress(
     #     TextColumn("[bold green]Processing...[/bold green]"),
@@ -300,15 +342,15 @@ def main():
     # ) as progress:
     #     task = progress.add_task("", total=None)
     process_show(
-        selected_season, 
-        dry_run=args.dry_run, 
-        get_subs=args.get_subs, 
+        selected_season,
+        dry_run=args.dry_run,
+        get_subs=args.get_subs,
         verbose=args.verbose,
-        confidence=args.confidence
+        confidence=args.confidence,
     )
-    
+
     console.print("[bold green]✓[/bold green] Processing completed successfully!")
-    
+
     # Show where logs are stored
     console.print(f"\n[dim]Logs available at: {log_dir}[/dim]")
 
@@ -323,4 +365,4 @@ if __name__ == "__main__":
     except Exception as e:
         console.print(f"\n[bold red]Error:[/bold red] {str(e)}")
         logger.exception("Unhandled exception")
-        sys.exit(1)
+        sys.exit(1)