refactor(tags): Simplify Simkl search logic and soft-fail when no results found

Previously, using multiple track selection flags like `-S -A` would not work
as expected. The flags were treated as mutually exclusive, resulting in only
one type of track being downloaded.

This change refactors the track selection logic to properly handle combinations:

- Multiple "only" flags now work together (e.g., `-S -A` downloads both)
- Exclusion flags (`--no-*`) continue to work and override selections
- Default behavior (no flags) remains unchanged

Fixes #10

.dockerignore

@@ -1,62 +0,0 @@
-# Logs and temporary files
-
-Logs/
-logs/
-temp/
-\*.log
-
-# Sensitive files
-
-key_vault.db
-unshackle/WVDs/
-unshackle/PRDs/
-unshackle/cookies/
-_.prd
-_.wvd
-
-# Cache directories
-
-unshackle/cache/
-**pycache**/
-_.pyc
-_.pyo
-\*.pyd
-.Python
-
-# Development files
-
-.git/
-.gitignore
-.vscode/
-.idea/
-_.swp
-_.swo
-
-# Documentation and plans
-
-plan/
-CONTRIBUTING.md
-CONFIG.md
-AGENTS.md
-OLD-CHANGELOG.md
-cliff.toml
-
-# Installation scripts
-
-install.bat
-
-# Test files
-
-_test_
-_Test_
-
-# Virtual environments
-
-venv/
-env/
-.venv/
-
-# OS generated files
-
-.DS_Store
-Thumbs.db

CHANGELOG.md

@@ -5,6 +5,60 @@ 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).
 
+## [1.4.0] - 2025-08-05
+
+### Added
+
+- **HLG Transfer Characteristics Preservation**: Enhanced video muxing to preserve HLG color metadata
+  - Added automatic detection of HLG video tracks during muxing process
+  - Implemented `--color-transfer-characteristics 0:18` argument for mkvmerge when processing HLG content
+  - Prevents incorrect conversion from HLG (18) to BT.2020 (14) transfer characteristics
+  - Ensures proper HLG playback support on compatible hardware without manual editing
+- **Original Language Support**: Enhanced language selection with 'orig' keyword support
+  - Added support for 'orig' language selector for both video and audio tracks
+  - Automatically detects and uses the title's original language when 'orig' is specified
+  - Improved language processing logic with better duplicate handling
+  - Enhanced help text to document original language selection usage
+- **Forced Subtitle Support**: Added option to include forced subtitle tracks
+  - New functionality to download and include forced subtitle tracks alongside regular subtitles
+- **WebVTT Subtitle Filtering**: Enhanced subtitle processing capabilities
+  - Added filtering for unwanted cues in WebVTT subtitles
+  - Improved subtitle quality by removing unnecessary metadata
+
+### Changed
+
+- **DRM Track Decryption**: Improved DRM decryption track selection logic
+  - Enhanced `get_drm_for_cdm()` method usage for better DRM-CDM matching
+  - Added warning messages when no matching DRM is found for tracks
+  - Improved error handling and logging for DRM decryption failures
+- **Series Tree Representation**: Enhanced episode tree display formatting
+  - Updated series tree to show season breakdown with episode counts
+  - Improved visual representation with "S{season}({count})" format
+  - Better organization of series information in console output
+- **Hybrid Processing UI**: Enhanced extraction and conversion processes
+  - Added dynamic spinning bars to follow the rest of the codebase design
+  - Improved visual feedback during hybrid HDR processing operations
+- **Track Selection Logic**: Enhanced multi-track selection capabilities
+  - Fixed track selection to support combining -V, -A, -S flags properly
+  - Improved flexibility in selecting multiple track types simultaneously
+- **Service Subtitle Support**: Added configuration for services without subtitle support
+  - Services can now indicate if they don't support subtitle downloads
+  - Prevents unnecessary subtitle download attempts for unsupported services
+- **Update Checker**: Enhanced update checking logic and cache handling
+  - Improved rate limiting and caching mechanisms for update checks
+  - Better performance and reduced API calls to GitHub
+
+### Fixed
+
+- **PlayReady KID Extraction**: Enhanced KID extraction from PSSH data
+  - Added base64 support and XML parsing for better KID detection
+  - Fixed issue where only one KID was being extracted for certain services
+  - Improved multi-KID support for PlayReady protected content
+- **Dolby Vision Detection**: Improved DV codec detection across all formats
+  - Fixed detection of dvhe.05.06 codec which was not being recognized correctly
+  - Enhanced detection logic in Episode and Movie title classes
+  - Better support for various Dolby Vision codec variants
+
 ## [1.3.0] - 2025-08-03
 
 ### Added
@@ -15,6 +69,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Enhanced PlayReady and Widevine DRM classes with mp4decrypt decryption support
   - Service-specific decryption mapping allows choosing between `shaka` and `mp4decrypt` per service
   - Improved error handling and progress reporting for mp4decrypt operations
+- **Scene Naming Configuration**: New `scene_naming` option for controlling file naming conventions
+  - Added scene naming logic to movie, episode, and song title classes
+  - Configurable through unshackle.yaml to enable/disable scene naming standards
+- **Terminal Cleanup and Signal Handling**: Enhanced console management
+  - Implemented proper terminal cleanup on application exit
+  - Added signal handling for graceful shutdown in ComfyConsole
+- **Configuration Template**: New `unshackle-example.yaml` template file
+  - Replaced main `unshackle.yaml` with example template to prevent git conflicts
+  - Users can now modify their local config without affecting repository updates
+- **Enhanced Credential Management**: Improved CDM and vault configuration
+  - Expanded credential management documentation in configuration
+  - Enhanced CDM configuration examples and guidelines
+- **Video Transfer Standards**: Added `Unspecified_Image` option to Transfer enum
+  - Implements ITU-T H.Sup19 standard value 2 for image characteristics
+  - Supports still image coding systems and unknown transfer characteristics
+- **Update Check Rate Limiting**: Enhanced update checking system
+  - Added configurable update check intervals to prevent excessive API calls
+  - Improved rate limiting for GitHub API requests
 
 ### Changed
 
@@ -22,12 +94,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Updated `dl.py` to handle service-specific decryption method selection
   - Refactored `Config` class to manage decryption method mapping per service
   - Enhanced DRM decrypt methods with `use_mp4decrypt` parameter for method selection
+- **Error Handling**: Improved exception handling in Hybrid class
+  - Replaced log.exit calls with ValueError exceptions for better error propagation
+  - Enhanced error handling consistency across hybrid processing
 
 ### Fixed
 
-- **Service Track Filtering**: Cleaned up ATVP service to remove unnecessary track filtering
+- **Proxy Configuration**: Fixed proxy server mapping in configuration
-  - Simplified track return logic to pass all tracks to dl.py for centralized filtering
+  - Renamed 'servers' to 'server_map' in proxy configuration to resolve Nord/Surfshark naming conflicts
-  - Removed unused codec and quality filter parameters from service initialization
+  - Updated configuration structure for better compatibility with proxy providers
+- **HTTP Vault**: Improved URL handling and key retrieval logic
+  - Fixed URL processing issues in HTTP-based key vaults
+  - Enhanced key retrieval reliability and error handling
 
 ## [1.2.0] - 2025-07-30
 

Dockerfile

@@ -1,78 +0,0 @@
-FROM python:3.12-slim
-
-# Set environment variables to reduce image size
-ENV PYTHONDONTWRITEBYTECODE=1 \
-    PYTHONUNBUFFERED=1 \
-    UV_CACHE_DIR=/tmp/uv-cache
-
-# Add container metadata
-LABEL org.opencontainers.image.description="Docker image for Unshackle with all required dependencies for downloading media content"
-
-# Install base dependencies
-RUN apt-get update && apt-get install -y --no-install-recommends \
-    wget \
-    gnupg \
-    git \
-    curl \
-    build-essential \
-    cmake \
-    pkg-config \
-    && apt-get clean \
-    && rm -rf /var/lib/apt/lists/*
-
-# Set up repos for mkvtools and bullseye for ccextractor
-RUN wget -O /etc/apt/keyrings/gpg-pub-moritzbunkus.gpg https://mkvtoolnix.download/gpg-pub-moritzbunkus.gpg \
-    && echo "deb [signed-by=/etc/apt/keyrings/gpg-pub-moritzbunkus.gpg] https://mkvtoolnix.download/debian/ bookworm main" >> /etc/apt/sources.list \
-    && echo "deb-src [signed-by=/etc/apt/keyrings/gpg-pub-moritzbunkus.gpg] https://mkvtoolnix.download/debian/ bookworm main" >> /etc/apt/sources.list \
-    && echo "deb http://ftp.debian.org/debian bullseye main" >> /etc/apt/sources.list
-
-# Install all dependencies from apt
-RUN apt-get update && apt-get install -y \
-    ffmpeg \
-    ccextractor \
-    mkvtoolnix \
-    aria2 \
-    libmediainfo-dev \
-    && apt-get clean \
-    && rm -rf /var/lib/apt/lists/*
-
-# Install shaka packager
-RUN wget https://github.com/shaka-project/shaka-packager/releases/download/v2.6.1/packager-linux-x64 \
-    && chmod +x packager-linux-x64 \
-    && mv packager-linux-x64 /usr/local/bin/packager
-
-# Install N_m3u8DL-RE
-RUN wget https://github.com/nilaoda/N_m3u8DL-RE/releases/download/v0.3.0-beta/N_m3u8DL-RE_v0.3.0-beta_linux-x64_20241203.tar.gz \
-    && tar -xzf N_m3u8DL-RE_v0.3.0-beta_linux-x64_20241203.tar.gz \
-    && mv N_m3u8DL-RE /usr/local/bin/ \
-    && chmod +x /usr/local/bin/N_m3u8DL-RE \
-    && rm N_m3u8DL-RE_v0.3.0-beta_linux-x64_20241203.tar.gz
-
-# Create binaries directory and add symlinks for all required executables
-RUN mkdir -p /app/binaries && \
-    ln -sf /usr/bin/ffprobe /app/binaries/ffprobe && \
-    ln -sf /usr/bin/ffmpeg /app/binaries/ffmpeg && \
-    ln -sf /usr/bin/mkvmerge /app/binaries/mkvmerge && \
-    ln -sf /usr/local/bin/N_m3u8DL-RE /app/binaries/N_m3u8DL-RE && \
-    ln -sf /usr/local/bin/packager /app/binaries/packager && \
-    ln -sf /usr/local/bin/packager /usr/local/bin/shaka-packager && \
-    ln -sf /usr/local/bin/packager /usr/local/bin/packager-linux-x64
-
-# Install uv
-RUN pip install --no-cache-dir uv
-
-# Set working directory
-WORKDIR /app
-
-# Copy dependency files and README (required by pyproject.toml)
-COPY pyproject.toml uv.lock README.md ./
-
-# Copy source code first
-COPY unshackle/ ./unshackle/
-
-# Install dependencies with uv (including the project itself)
-RUN uv sync --frozen --no-dev
-
-# Set entrypoint to allow passing commands directly to unshackle
-ENTRYPOINT ["uv", "run", "unshackle"]
-CMD ["-h"]

README.md

@@ -42,45 +42,6 @@ uv tool install git+https://github.com/unshackle-dl/unshackle.git
 uvx unshackle --help   # or just `unshackle` once PATH updated
 ```
 
-### Docker Installation
-
-Run unshackle using our pre-built Docker image from GitHub Container Registry:
-
-```bash
-# Run with default help command
-docker run --rm ghcr.io/unshackle-dl/unshackle:latest
-
-# Check environment dependencies
-docker run --rm ghcr.io/unshackle-dl/unshackle:latest env check
-
-# Download content (mount directories for persistent data)
-docker run --rm \
-  -v "$(pwd)/unshackle/downloads:/app/downloads" \
-  -v "$(pwd)/unshackle/cookies:/app/unshackle/cookies" \
-  -v "$(pwd)/unshackle/services:/app/unshackle/services" \
-  -v "$(pwd)/unshackle/WVDs:/app/unshackle/WVDs" \
-  -v "$(pwd)/unshackle/PRDs:/app/unshackle/PRDs" \
-  -v "$(pwd)/unshackle/unshackle.yaml:/app/unshackle.yaml" \
-  ghcr.io/unshackle-dl/unshackle:latest dl SERVICE_NAME CONTENT_ID
-
-# Run interactively for configuration
-docker run --rm -it \
-  -v "$(pwd)/unshackle/cookies:/app/unshackle/cookies" \
-  -v "$(pwd)/unshackle/services:/app/unshackle/services" \
-  -v "$(pwd)/unshackle.yaml:/app/unshackle.yaml" \
-  ghcr.io/unshackle-dl/unshackle:latest cfg
-```
-
-**Alternative: Build locally**
-
-```bash
-# Clone and build your own image
-git clone https://github.com/unshackle-dl/unshackle.git
-cd unshackle
-docker build -t unshackle .
-docker run --rm unshackle env check
-```
-
 > [!NOTE]
 > After installation, you may need to add the installation path to your PATH environment variable if prompted.
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "unshackle"
-version = "1.3.0"
+version = "1.4.0"
 description = "Modular Movie, TV, and Music Archival Software."
 authors = [{ name = "unshackle team" }]
 requires-python = ">=3.10,<3.13"

unshackle/commands/dl.py

@@ -139,7 +139,13 @@ class dl:
         default=None,
         help="Wanted episodes, e.g. `S01-S05,S07`, `S01E01-S02E03`, `S02-S02E03`, e.t.c, defaults to all.",
     )
-    @click.option("-l", "--lang", type=LANGUAGE_RANGE, default="en", help="Language wanted for Video and Audio.")
+    @click.option(
+        "-l",
+        "--lang",
+        type=LANGUAGE_RANGE,
+        default="orig",
+        help="Language wanted for Video and Audio. Use 'orig' to select the original language, e.g. 'orig,en' for both original and English.",
+    )
     @click.option(
         "-vl",
         "--v-lang",
@@ -148,6 +154,7 @@ class dl:
         help="Language wanted for Video, you would use this if the video language doesn't match the audio.",
     )
     @click.option("-sl", "--s-lang", type=LANGUAGE_RANGE, default=["all"], help="Language wanted for Subtitles.")
+    @click.option("-fs", "--forced-subs", is_flag=True, default=False, help="Include forced subtitle tracks.")
     @click.option(
         "--proxy",
         type=str,
@@ -405,6 +412,7 @@ class dl:
         lang: list[str],
         v_lang: list[str],
         s_lang: list[str],
+        forced_subs: bool,
         sub_format: Optional[Subtitle.Codec],
         video_only: bool,
         audio_only: bool,
@@ -428,6 +436,7 @@ class dl:
         **__: Any,
     ) -> None:
         self.tmdb_searched = False
+        self.search_source = None
         start_time = time.time()
 
         # Check if dovi_tool is available when hybrid mode is requested
@@ -485,34 +494,34 @@ class dl:
                 if self.tmdb_id:
                     tmdb_title = tags.get_title(self.tmdb_id, kind)
                 else:
-                    self.tmdb_id, tmdb_title = tags.search_tmdb(title.title, title.year, kind)
+                    self.tmdb_id, tmdb_title, self.search_source = tags.search_show_info(title.title, title.year, kind)
                     if not (self.tmdb_id and tmdb_title and tags.fuzzy_match(tmdb_title, title.title)):
                         self.tmdb_id = None
                 if list_ or list_titles:
                     if self.tmdb_id:
                         console.print(
                             Padding(
-                                f"TMDB -> {tmdb_title or '?'} [bright_black](ID {self.tmdb_id})",
+                                f"Search -> {tmdb_title or '?'} [bright_black](ID {self.tmdb_id})",
                                 (0, 5),
                             )
                         )
                     else:
-                        console.print(Padding("TMDB -> [bright_black]No match found[/]", (0, 5)))
+                        console.print(Padding("Search -> [bright_black]No match found[/]", (0, 5)))
                 self.tmdb_searched = True
 
             if isinstance(title, Movie) and (list_ or list_titles) and not self.tmdb_id:
-                movie_id, movie_title = tags.search_tmdb(title.name, title.year, "movie")
+                movie_id, movie_title, _ = tags.search_show_info(title.name, title.year, "movie")
                 if movie_id:
                     console.print(
                         Padding(
-                            f"TMDB -> {movie_title or '?'} [bright_black](ID {movie_id})",
+                            f"Search -> {movie_title or '?'} [bright_black](ID {movie_id})",
                             (0, 5),
                         )
                     )
                 else:
-                    console.print(Padding("TMDB -> [bright_black]No match found[/]", (0, 5)))
+                    console.print(Padding("Search -> [bright_black]No match found[/]", (0, 5)))
 
-            if self.tmdb_id:
+            if self.tmdb_id and getattr(self, 'search_source', None) != 'simkl':
                 kind = "tv" if isinstance(title, Episode) else "movie"
                 tags.external_ids(self.tmdb_id, kind)
                 if self.tmdb_year:
@@ -533,7 +542,12 @@ class dl:
                 events.subscribe(events.Types.TRACK_REPACKED, service.on_track_repacked)
                 events.subscribe(events.Types.TRACK_MULTIPLEX, service.on_track_multiplex)
 
-            if no_subs:
+            if hasattr(service, "NO_SUBTITLES") and service.NO_SUBTITLES:
+                console.log("Skipping subtitles - service does not support subtitle downloads")
+                no_subs = True
+                s_lang = None
+                title.tracks.subtitles = []
+            elif no_subs:
                 console.log("Skipped subtitles as --no-subs was used...")
                 s_lang = None
                 title.tracks.subtitles = []
@@ -560,8 +574,31 @@ class dl:
                     )
 
             with console.status("Sorting tracks by language and bitrate...", spinner="dots"):
-                title.tracks.sort_videos(by_language=v_lang or lang)
+                video_sort_lang = v_lang or lang
-                title.tracks.sort_audio(by_language=lang)
+                processed_video_sort_lang = []
+                for language in video_sort_lang:
+                    if language == "orig":
+                        if title.language:
+                            orig_lang = str(title.language) if hasattr(title.language, "__str__") else title.language
+                            if orig_lang not in processed_video_sort_lang:
+                                processed_video_sort_lang.append(orig_lang)
+                    else:
+                        if language not in processed_video_sort_lang:
+                            processed_video_sort_lang.append(language)
+
+                processed_audio_sort_lang = []
+                for language in lang:
+                    if language == "orig":
+                        if title.language:
+                            orig_lang = str(title.language) if hasattr(title.language, "__str__") else title.language
+                            if orig_lang not in processed_audio_sort_lang:
+                                processed_audio_sort_lang.append(orig_lang)
+                    else:
+                        if language not in processed_audio_sort_lang:
+                            processed_audio_sort_lang.append(language)
+
+                title.tracks.sort_videos(by_language=processed_video_sort_lang)
+                title.tracks.sort_audio(by_language=processed_audio_sort_lang)
                 title.tracks.sort_subtitles(by_language=s_lang)
 
             if list_:
@@ -592,12 +629,27 @@ class dl:
                             self.log.error(f"There's no {vbitrate}kbps Video Track...")
                             sys.exit(1)
 
-                    # Filter out "best" from the video languages list.
                     video_languages = [lang for lang in (v_lang or lang) if lang != "best"]
                     if video_languages and "all" not in video_languages:
-                        title.tracks.videos = title.tracks.by_language(title.tracks.videos, video_languages)
+                        processed_video_lang = []
+                        for language in video_languages:
+                            if language == "orig":
+                                if title.language:
+                                    orig_lang = (
+                                        str(title.language) if hasattr(title.language, "__str__") else title.language
+                                    )
+                                    if orig_lang not in processed_video_lang:
+                                        processed_video_lang.append(orig_lang)
+                                else:
+                                    self.log.warning(
+                                        "Original language not available for title, skipping 'orig' selection for video"
+                                    )
+                            else:
+                                if language not in processed_video_lang:
+                                    processed_video_lang.append(language)
+                        title.tracks.videos = title.tracks.by_language(title.tracks.videos, processed_video_lang)
                         if not title.tracks.videos:
-                            self.log.error(f"There's no {video_languages} Video Track...")
+                            self.log.error(f"There's no {processed_video_lang} Video Track...")
                             sys.exit(1)
 
                     if quality:
@@ -672,6 +724,7 @@ class dl:
                             self.log.error(f"There's no {s_lang} Subtitle Track...")
                             sys.exit(1)
 
+                    if not forced_subs:
                         title.tracks.select_subtitles(lambda x: not x.forced or is_close_match(x.language, lang))
 
                 # filter audio tracks
@@ -699,8 +752,24 @@ class dl:
                             self.log.error(f"There's no {abitrate}kbps Audio Track...")
                             sys.exit(1)
                     if lang:
-                        if "best" in lang:
+                        processed_lang = []
-                            # Get unique languages and select highest quality for each
+                        for language in lang:
+                            if language == "orig":
+                                if title.language:
+                                    orig_lang = (
+                                        str(title.language) if hasattr(title.language, "__str__") else title.language
+                                    )
+                                    if orig_lang not in processed_lang:
+                                        processed_lang.append(orig_lang)
+                                else:
+                                    self.log.warning(
+                                        "Original language not available for title, skipping 'orig' selection"
+                                    )
+                            else:
+                                if language not in processed_lang:
+                                    processed_lang.append(language)
+
+                        if "best" in processed_lang:
                             unique_languages = {track.language for track in title.tracks.audio}
                             selected_audio = []
                             for language in unique_languages:
@@ -710,30 +779,36 @@ class dl:
                                 )
                                 selected_audio.append(highest_quality)
                             title.tracks.audio = selected_audio
-                        elif "all" not in lang:
+                        elif "all" not in processed_lang:
-                            title.tracks.audio = title.tracks.by_language(title.tracks.audio, lang, per_language=1)
+                            per_language = 0 if len(processed_lang) > 1 else 1
+                            title.tracks.audio = title.tracks.by_language(
+                                title.tracks.audio, processed_lang, per_language=per_language
+                            )
                             if not title.tracks.audio:
-                                self.log.error(f"There's no {lang} Audio Track, cannot continue...")
+                                self.log.error(f"There's no {processed_lang} Audio Track, cannot continue...")
                                 sys.exit(1)
 
                 if video_only or audio_only or subs_only or chapters_only or no_subs or no_audio or no_chapters:
-                    # Determine which track types to keep based on the flags
+                    keep_videos = False
+                    keep_audio = False
+                    keep_subtitles = False
+                    keep_chapters = False
+
+                    if video_only or audio_only or subs_only or chapters_only:
+                        if video_only:
+                            keep_videos = True
+                        if audio_only:
+                            keep_audio = True
+                        if subs_only:
+                            keep_subtitles = True
+                        if chapters_only:
+                            keep_chapters = True
+                    else:
                         keep_videos = True
                         keep_audio = True
                         keep_subtitles = True
                         keep_chapters = True
 
-                    # Handle exclusive flags (only keep one type)
-                    if video_only:
-                        keep_audio = keep_subtitles = keep_chapters = False
-                    elif audio_only:
-                        keep_videos = keep_subtitles = keep_chapters = False
-                    elif subs_only:
-                        keep_videos = keep_audio = keep_chapters = False
-                    elif chapters_only:
-                        keep_videos = keep_audio = keep_subtitles = False
-
-                    # Handle exclusion flags (remove specific types)
                     if no_subs:
                         keep_subtitles = False
                     if no_audio:
@@ -741,7 +816,6 @@ class dl:
                     if no_chapters:
                         keep_chapters = False
 
-                    # Build the kept_tracks list without duplicates
                     kept_tracks = []
                     if keep_videos:
                         kept_tracks.extend(title.tracks.videos)
@@ -765,8 +839,7 @@ class dl:
                 DOWNLOAD_LICENCE_ONLY.set()
 
             try:
-                # Use transient mode to prevent display remnants
+                with Live(Padding(download_table, (1, 5)), console=console, refresh_per_second=5):
-                with Live(Padding(download_table, (1, 5)), console=console, refresh_per_second=5, transient=True):
                     with ThreadPoolExecutor(downloads) as pool:
                         for download in futures.as_completed(
                             (
@@ -839,6 +912,7 @@ class dl:
                 while (
                     not title.tracks.subtitles
                     and not no_subs
+                    and not (hasattr(service, "NO_SUBTITLES") and service.NO_SUBTITLES)
                     and not video_only
                     and len(title.tracks.videos) > video_track_n
                     and any(
@@ -927,12 +1001,15 @@ class dl:
                     with console.status(f"Decrypting tracks with {decrypt_tool}..."):
                         has_decrypted = False
                         for track in drm_tracks:
-                            for drm in track.drm:
+                            drm = track.get_drm_for_cdm(self.cdm)
-                                if hasattr(drm, "decrypt"):
+                            if drm and hasattr(drm, "decrypt"):
                                 drm.decrypt(track.path, use_mp4decrypt=use_mp4decrypt)
                                 has_decrypted = True
                                 events.emit(events.Types.TRACK_REPACKED, track=track)
-                                    break
+                            else:
+                                self.log.warning(
+                                    f"No matching DRM found for track {track} with CDM type {type(self.cdm).__name__}"
+                                )
                         if has_decrypted:
                             self.log.info(f"Decrypted tracks with {decrypt_tool}")
 
@@ -1035,7 +1112,7 @@ class dl:
 
                             multiplex_tasks.append((task_id, task_tracks))
 
-                    with Live(Padding(progress, (0, 5, 1, 5)), console=console, transient=True):
+                    with Live(Padding(progress, (0, 5, 1, 5)), console=console):
                         for task_id, task_tracks in multiplex_tasks:
                             progress.start_task(task_id)  # TODO: Needed?
                             muxed_path, return_code, errors = task_tracks.mux(

unshackle/core/__init__.py

@@ -1 +1 @@
-__version__ = "1.3.0"
+__version__ = "1.4.0"

unshackle/core/config.py

@@ -85,6 +85,8 @@ class Config:
 
         self.set_terminal_bg: bool = kwargs.get("set_terminal_bg", False)
         self.tag: str = kwargs.get("tag") or ""
+        self.tag_group_name: bool = kwargs.get("tag_group_name", True)
+        self.tag_imdb_tmdb: bool = kwargs.get("tag_imdb_tmdb", True)
         self.tmdb_api_key: str = kwargs.get("tmdb_api_key") or ""
         self.update_checks: bool = kwargs.get("update_checks", True)
         self.update_check_interval: int = kwargs.get("update_check_interval", 24)

unshackle/core/console.py

@@ -1,7 +1,4 @@
-import atexit
 import logging
-import signal
-import sys
 from datetime import datetime
 from types import ModuleType
 from typing import IO, Callable, Iterable, List, Literal, Mapping, Optional, Union
@@ -170,8 +167,6 @@ class ComfyConsole(Console):
             time.monotonic.
     """
 
-    _cleanup_registered = False
-
     def __init__(
         self,
         *,
@@ -238,9 +233,6 @@ class ComfyConsole(Console):
         if log_renderer:
             self._log_render = log_renderer
 
-        # Register terminal cleanup handlers
-        self._register_cleanup()
-
     def status(
         self,
         status: RenderableType,
@@ -291,38 +283,6 @@ class ComfyConsole(Console):
 
         return status_renderable
 
-    def _register_cleanup(self):
-        """Register terminal cleanup handlers."""
-        if not ComfyConsole._cleanup_registered:
-            ComfyConsole._cleanup_registered = True
-
-            # Register cleanup on normal exit
-            atexit.register(self._cleanup_terminal)
-
-            # Register cleanup on signals
-            signal.signal(signal.SIGINT, self._signal_handler)
-            signal.signal(signal.SIGTERM, self._signal_handler)
-
-    def _cleanup_terminal(self):
-        """Restore terminal to a clean state."""
-        try:
-            # Show cursor using ANSI escape codes
-            sys.stdout.write("\x1b[?25h")  # Show cursor
-            sys.stdout.write("\x1b[0m")  # Reset attributes
-            sys.stdout.flush()
-
-            # Also use Rich's method
-            self.show_cursor(True)
-        except Exception:
-            # Silently fail if cleanup fails
-            pass
-
-    def _signal_handler(self, signum, frame):
-        """Handle signals with cleanup."""
-        self._cleanup_terminal()
-        # Exit after cleanup
-        sys.exit(1)
-
 
 catppuccin_mocha = {
     # Colors based on "CatppuccinMocha" from Gogh themes

unshackle/core/drm/playready.py

@@ -39,7 +39,13 @@ class PlayReady:
         if not isinstance(pssh, PSSH):
             raise TypeError(f"Expected pssh to be a {PSSH}, not {pssh!r}")
 
-        kids: list[UUID] = []
+        if pssh_b64:
+            kids = self._extract_kids_from_pssh_b64(pssh_b64)
+        else:
+            kids = []
+
+        # Extract KIDs using pyplayready's method (may miss some KIDs)
+        if not kids:
             for header in pssh.wrm_headers:
                 try:
                     signed_ids, _, _, _ = header.read_attributes()
@@ -72,6 +78,66 @@ class PlayReady:
         if pssh_b64:
             self.data.setdefault("pssh_b64", pssh_b64)
 
+    def _extract_kids_from_pssh_b64(self, pssh_b64: str) -> list[UUID]:
+        """Extract all KIDs from base64-encoded PSSH data."""
+        try:
+            import xml.etree.ElementTree as ET
+
+            # Decode the PSSH
+            pssh_bytes = base64.b64decode(pssh_b64)
+
+            # Try to find XML in the PSSH data
+            # PlayReady PSSH usually has XML embedded in it
+            pssh_str = pssh_bytes.decode("utf-16le", errors="ignore")
+
+            # Find WRMHEADER
+            xml_start = pssh_str.find("<WRMHEADER")
+            if xml_start == -1:
+                # Try UTF-8
+                pssh_str = pssh_bytes.decode("utf-8", errors="ignore")
+                xml_start = pssh_str.find("<WRMHEADER")
+
+            if xml_start != -1:
+                clean_xml = pssh_str[xml_start:]
+                xml_end = clean_xml.find("</WRMHEADER>") + len("</WRMHEADER>")
+                clean_xml = clean_xml[:xml_end]
+
+                root = ET.fromstring(clean_xml)
+                ns = {"pr": "http://schemas.microsoft.com/DRM/2007/03/PlayReadyHeader"}
+
+                kids = []
+
+                # Extract from CUSTOMATTRIBUTES/KIDS
+                kid_elements = root.findall(".//pr:CUSTOMATTRIBUTES/pr:KIDS/pr:KID", ns)
+                for kid_elem in kid_elements:
+                    value = kid_elem.get("VALUE")
+                    if value:
+                        try:
+                            kid_bytes = base64.b64decode(value + "==")
+                            kid_uuid = UUID(bytes_le=kid_bytes)
+                            kids.append(kid_uuid)
+                        except Exception:
+                            pass
+
+                # Also get individual KID
+                individual_kids = root.findall(".//pr:DATA/pr:KID", ns)
+                for kid_elem in individual_kids:
+                    if kid_elem.text:
+                        try:
+                            kid_bytes = base64.b64decode(kid_elem.text.strip() + "==")
+                            kid_uuid = UUID(bytes_le=kid_bytes)
+                            if kid_uuid not in kids:
+                                kids.append(kid_uuid)
+                        except Exception:
+                            pass
+
+                return kids
+
+        except Exception:
+            pass
+
+        return []
+
     @classmethod
     def from_track(cls, track: AnyTrack, session: Optional[Session] = None) -> PlayReady:
         if not session:

unshackle/core/titles/episode.py

@@ -170,8 +170,9 @@ class Episode(Title):
                 frame_rate = float(primary_video_track.frame_rate)
                 if hdr_format:
                     if (primary_video_track.hdr_format or "").startswith("Dolby Vision"):
-                        if (primary_video_track.hdr_format_commercial) != "Dolby Vision":
+                        name += " DV"
-                            name += f" DV {DYNAMIC_RANGE_MAP.get(hdr_format)} "
+                        if DYNAMIC_RANGE_MAP.get(hdr_format) and DYNAMIC_RANGE_MAP.get(hdr_format) != "DV":
+                            name += " HDR"
                     else:
                         name += f" {DYNAMIC_RANGE_MAP.get(hdr_format)} "
                 elif trc and "HLG" in trc:
@@ -201,9 +202,10 @@ class Series(SortedKeyList, ABC):
     def tree(self, verbose: bool = False) -> Tree:
         seasons = Counter(x.season for x in self)
         num_seasons = len(seasons)
-        num_episodes = sum(seasons.values())
+        sum(seasons.values())
+        season_breakdown = ", ".join(f"S{season}({count})" for season, count in sorted(seasons.items()))
         tree = Tree(
-            f"{num_seasons} Season{['s', ''][num_seasons == 1]}, {num_episodes} Episode{['s', ''][num_episodes == 1]}",
+            f"{num_seasons} seasons, {season_breakdown}",
             guide_style="bright_black",
         )
         if verbose:

unshackle/core/titles/movie.py

@@ -121,8 +121,9 @@ class Movie(Title):
                 frame_rate = float(primary_video_track.frame_rate)
                 if hdr_format:
                     if (primary_video_track.hdr_format or "").startswith("Dolby Vision"):
-                        if (primary_video_track.hdr_format_commercial) != "Dolby Vision":
+                        name += " DV"
-                            name += f" DV {DYNAMIC_RANGE_MAP.get(hdr_format)} "
+                        if DYNAMIC_RANGE_MAP.get(hdr_format) and DYNAMIC_RANGE_MAP.get(hdr_format) != "DV":
+                            name += " HDR"
                     else:
                         name += f" {DYNAMIC_RANGE_MAP.get(hdr_format)} "
                 elif trc and "HLG" in trc:

unshackle/core/tracks/hybrid.py

@@ -126,8 +126,7 @@ class Hybrid:
     def extract_stream(self, save_path, type_):
         output = Path(config.directories.temp / f"{type_}.hevc")
 
-        self.log.info(f"+ Extracting {type_} stream")
+        with console.status(f"Extracting {type_} stream...", spinner="dots"):
-
             returncode = self.ffmpeg_simple(save_path, output)
 
         if returncode:
@@ -135,14 +134,17 @@ class Hybrid:
             self.log.error(f"x Failed extracting {type_} stream")
             sys.exit(1)
 
+        self.log.info(f"Extracted {type_} stream")
+
     def extract_rpu(self, video, untouched=False):
         if os.path.isfile(config.directories.temp / "RPU.bin") or os.path.isfile(
             config.directories.temp / "RPU_UNT.bin"
         ):
             return
 
-        self.log.info(f"+ Extracting{' untouched ' if untouched else ' '}RPU from Dolby Vision stream")
+        with console.status(
-
+            f"Extracting{' untouched ' if untouched else ' '}RPU from Dolby Vision stream...", spinner="dots"
+        ):
             extraction_args = [str(DoviTool)]
             if not untouched:
                 extraction_args += ["-m", "3"]
@@ -168,6 +170,8 @@ class Hybrid:
             else:
                 raise ValueError(f"Failed extracting{' untouched ' if untouched else ' '}RPU from Dolby Vision stream")
 
+        self.log.info(f"Extracted{' untouched ' if untouched else ' '}RPU from Dolby Vision stream")
+
     def level_6(self):
         """Edit RPU Level 6 values"""
         with open(config.directories.temp / "L6.json", "w+") as level6_file:
@@ -185,7 +189,7 @@ class Hybrid:
             json.dump(level6, level6_file, indent=3)
 
         if not os.path.isfile(config.directories.temp / "RPU_L6.bin"):
-            self.log.info("+ Editing RPU Level 6 values")
+            with console.status("Editing RPU Level 6 values...", spinner="dots"):
                 level6 = subprocess.run(
                     [
                         str(DoviTool),
@@ -205,6 +209,8 @@ class Hybrid:
                 Path.unlink(config.directories.temp / "RPU_L6.bin")
                 raise ValueError("Failed editing RPU Level 6 values")
 
+            self.log.info("Edited RPU Level 6 values")
+
             # Update rpu_file to use the edited version
             self.rpu_file = "RPU_L6.bin"
 
@@ -212,8 +218,7 @@ class Hybrid:
         if os.path.isfile(config.directories.temp / self.hevc_file):
             return
 
-        self.log.info(f"+ Injecting Dolby Vision metadata into {self.hdr_type} stream")
+        with console.status(f"Injecting Dolby Vision metadata into {self.hdr_type} stream...", spinner="dots"):
-
             inject_cmd = [
                 str(DoviTool),
                 "inject-rpu",
@@ -241,6 +246,8 @@ class Hybrid:
             Path.unlink(config.directories.temp / self.hevc_file)
             raise ValueError("Failed injecting Dolby Vision metadata into HDR10 stream")
 
+        self.log.info(f"Injected Dolby Vision metadata into {self.hdr_type} stream")
+
     def extract_hdr10plus(self, _video):
         """Extract HDR10+ metadata from the video stream"""
         if os.path.isfile(config.directories.temp / self.hdr10plus_file):
@@ -249,8 +256,7 @@ class Hybrid:
         if not HDR10PlusTool:
             raise ValueError("HDR10Plus_tool not found. Please install it to use HDR10+ to DV conversion.")
 
-        self.log.info("+ Extracting HDR10+ metadata")
+        with console.status("Extracting HDR10+ metadata...", spinner="dots"):
-
             # HDR10Plus_tool needs raw HEVC stream
             extraction = subprocess.run(
                 [
@@ -271,13 +277,14 @@ class Hybrid:
         if os.path.getsize(config.directories.temp / self.hdr10plus_file) == 0:
             raise ValueError("No HDR10+ metadata found in the stream")
 
+        self.log.info("Extracted HDR10+ metadata")
+
     def convert_hdr10plus_to_dv(self):
         """Convert HDR10+ metadata to Dolby Vision RPU"""
         if os.path.isfile(config.directories.temp / "RPU.bin"):
             return
 
-        self.log.info("+ Converting HDR10+ metadata to Dolby Vision")
+        with console.status("Converting HDR10+ metadata to Dolby Vision...", spinner="dots"):
-
             # First create the extra metadata JSON for dovi_tool
             extra_metadata = {
                 "cm_version": "V29",
@@ -312,6 +319,7 @@ class Hybrid:
         if conversion.returncode:
             raise ValueError("Failed converting HDR10+ to Dolby Vision")
 
+        self.log.info("Converted HDR10+ metadata to Dolby Vision")
         self.log.info("✓ HDR10+ successfully converted to Dolby Vision Profile 8")
 
         # Clean up temporary files

unshackle/core/tracks/subtitle.py

@@ -233,6 +233,7 @@ class Subtitle(Track):
             try:
                 caption_set = pycaption.WebVTTReader().read(text)
                 Subtitle.merge_same_cues(caption_set)
+                Subtitle.filter_unwanted_cues(caption_set)
                 subtitle_text = pycaption.WebVTTWriter().write(caption_set)
                 self.path.write_text(subtitle_text, encoding="utf8")
             except pycaption.exceptions.CaptionReadSyntaxError:
@@ -241,6 +242,7 @@ class Subtitle(Track):
                 try:
                     caption_set = pycaption.WebVTTReader().read(text)
                     Subtitle.merge_same_cues(caption_set)
+                    Subtitle.filter_unwanted_cues(caption_set)
                     subtitle_text = pycaption.WebVTTWriter().write(caption_set)
                     self.path.write_text(subtitle_text, encoding="utf8")
                 except Exception:
@@ -444,6 +446,8 @@ class Subtitle(Track):
 
         caption_set = self.parse(self.path.read_bytes(), self.codec)
         Subtitle.merge_same_cues(caption_set)
+        if codec == Subtitle.Codec.WebVTT:
+            Subtitle.filter_unwanted_cues(caption_set)
         subtitle_text = writer().write(caption_set)
 
         output_path.write_text(subtitle_text, encoding="utf8")
@@ -520,6 +524,8 @@ class Subtitle(Track):
 
             caption_set = self.parse(self.path.read_bytes(), self.codec)
             Subtitle.merge_same_cues(caption_set)
+            if codec == Subtitle.Codec.WebVTT:
+                Subtitle.filter_unwanted_cues(caption_set)
             subtitle_text = writer().write(caption_set)
 
             output_path.write_text(subtitle_text, encoding="utf8")
@@ -681,6 +687,24 @@ class Subtitle(Track):
             if merged_captions:
                 caption_set.set_captions(lang, merged_captions)
 
+    @staticmethod
+    def filter_unwanted_cues(caption_set: pycaption.CaptionSet):
+        """
+        Filter out subtitle cues containing only   or whitespace.
+        """
+        for lang in caption_set.get_languages():
+            captions = caption_set.get_captions(lang)
+            filtered_captions = pycaption.CaptionList()
+
+            for caption in captions:
+                text = caption.get_text().strip()
+                if not text or text == " " or all(c in " \t\n\r\xa0" for c in text.replace(" ", "\xa0")):
+                    continue
+
+                filtered_captions.append(caption)
+
+            caption_set.set_captions(lang, filtered_captions)
+
     @staticmethod
     def merge_segmented_wvtt(data: bytes, period_start: float = 0.0) -> tuple[CaptionList, Optional[str]]:
         """
@@ -846,7 +870,18 @@ class Subtitle(Track):
         elif sdh_method == "filter-subs":
             # Force use of filter-subs
             sub = Subtitles(self.path)
+            try:
                 sub.filter(rm_fonts=True, rm_ast=True, rm_music=True, rm_effects=True, rm_names=True, rm_author=True)
+            except ValueError as e:
+                if "too many values to unpack" in str(e):
+                    # Retry without name removal if the error is due to multiple colons in time references
+                    # This can happen with lines like "at 10:00 and 2:00"
+                    sub = Subtitles(self.path)
+                    sub.filter(
+                        rm_fonts=True, rm_ast=True, rm_music=True, rm_effects=True, rm_names=False, rm_author=True
+                    )
+                else:
+                    raise
             sub.save()
             return
         elif sdh_method == "auto":
@@ -882,7 +917,18 @@ class Subtitle(Track):
             )
         else:
             sub = Subtitles(self.path)
+            try:
                 sub.filter(rm_fonts=True, rm_ast=True, rm_music=True, rm_effects=True, rm_names=True, rm_author=True)
+            except ValueError as e:
+                if "too many values to unpack" in str(e):
+                    # Retry without name removal if the error is due to multiple colons in time references
+                    # This can happen with lines like "at 10:00 and 2:00"
+                    sub = Subtitles(self.path)
+                    sub.filter(
+                        rm_fonts=True, rm_ast=True, rm_music=True, rm_effects=True, rm_names=False, rm_author=True
+                    )
+                else:
+                    raise
             sub.save()
 
     def reverse_rtl(self) -> None:

unshackle/core/tracks/tracks.py

@@ -355,6 +355,14 @@ class Tracks:
                     ]
                 )
 
+            if hasattr(vt, "range") and vt.range == Video.Range.HLG:
+                video_args.extend(
+                    [
+                        "--color-transfer-characteristics",
+                        "0:18",  # ARIB STD-B67 (HLG)
+                    ]
+                )
+
             cl.extend(video_args + ["(", str(vt.path), ")"])
 
         for i, at in enumerate(self.audio):

unshackle/core/update_checker.py

@@ -10,11 +10,22 @@ import requests
 
 
 class UpdateChecker:
-    """Check for available updates from the GitHub repository."""
+    """
+    Check for available updates from the GitHub repository.
+
+    This class provides functionality to check for newer versions of the application
+    by querying the GitHub releases API. It includes rate limiting, caching, and
+    both synchronous and asynchronous interfaces.
+
+    Attributes:
+        REPO_URL: GitHub API URL for latest release
+        TIMEOUT: Request timeout in seconds
+        DEFAULT_CHECK_INTERVAL: Default time between checks in seconds (24 hours)
+    """
 
     REPO_URL = "https://api.github.com/repos/unshackle-dl/unshackle/releases/latest"
     TIMEOUT = 5
-    DEFAULT_CHECK_INTERVAL = 24 * 60 * 60  # 24 hours in seconds
+    DEFAULT_CHECK_INTERVAL = 24 * 60 * 60
 
     @classmethod
     def _get_cache_file(cls) -> Path:
@@ -23,6 +34,86 @@ class UpdateChecker:
 
         return config.directories.cache / "update_check.json"
 
+    @classmethod
+    def _load_cache_data(cls) -> dict:
+        """
+        Load cache data from file.
+
+        Returns:
+            Cache data dictionary or empty dict if loading fails
+        """
+        cache_file = cls._get_cache_file()
+
+        if not cache_file.exists():
+            return {}
+
+        try:
+            with open(cache_file, "r") as f:
+                return json.load(f)
+        except (json.JSONDecodeError, OSError):
+            return {}
+
+    @staticmethod
+    def _parse_version(version_string: str) -> str:
+        """
+        Parse and normalize version string by removing 'v' prefix.
+
+        Args:
+            version_string: Raw version string from API
+
+        Returns:
+            Cleaned version string
+        """
+        return version_string.lstrip("v")
+
+    @staticmethod
+    def _is_valid_version(version: str) -> bool:
+        """
+        Validate version string format.
+
+        Args:
+            version: Version string to validate
+
+        Returns:
+            True if version string is valid semantic version, False otherwise
+        """
+        if not version or not isinstance(version, str):
+            return False
+
+        try:
+            parts = version.split(".")
+            if len(parts) < 2:
+                return False
+
+            for part in parts:
+                int(part)
+
+            return True
+        except (ValueError, AttributeError):
+            return False
+
+    @classmethod
+    def _fetch_latest_version(cls) -> Optional[str]:
+        """
+        Fetch the latest version from GitHub API.
+
+        Returns:
+            Latest version string if successful, None otherwise
+        """
+        try:
+            response = requests.get(cls.REPO_URL, timeout=cls.TIMEOUT)
+
+            if response.status_code != 200:
+                return None
+
+            data = response.json()
+            latest_version = cls._parse_version(data.get("tag_name", ""))
+
+            return latest_version if cls._is_valid_version(latest_version) else None
+
+        except Exception:
+            return None
+
     @classmethod
     def _should_check_for_updates(cls, check_interval: int = DEFAULT_CHECK_INTERVAL) -> bool:
         """
@@ -34,45 +125,40 @@ class UpdateChecker:
         Returns:
             True if we should check for updates, False otherwise
         """
-        cache_file = cls._get_cache_file()
+        cache_data = cls._load_cache_data()
 
-        if not cache_file.exists():
+        if not cache_data:
             return True
 
-        try:
-            with open(cache_file, "r") as f:
-                cache_data = json.load(f)
-
         last_check = cache_data.get("last_check", 0)
         current_time = time.time()
 
         return (current_time - last_check) >= check_interval
 
-        except (json.JSONDecodeError, KeyError, OSError):
-            # If cache is corrupted or unreadable, allow check
-            return True
-
     @classmethod
-    def _update_cache(cls, latest_version: Optional[str] = None) -> None:
+    def _update_cache(cls, latest_version: Optional[str] = None, current_version: Optional[str] = None) -> None:
         """
-        Update the cache file with the current timestamp and latest version.
+        Update the cache file with the current timestamp and version info.
 
         Args:
             latest_version: The latest version found, if any
+            current_version: The current version being used
         """
         cache_file = cls._get_cache_file()
 
         try:
-            # Ensure cache directory exists
             cache_file.parent.mkdir(parents=True, exist_ok=True)
 
-            cache_data = {"last_check": time.time(), "latest_version": latest_version}
+            cache_data = {
+                "last_check": time.time(),
+                "latest_version": latest_version,
+                "current_version": current_version,
+            }
 
             with open(cache_file, "w") as f:
-                json.dump(cache_data, f)
+                json.dump(cache_data, f, indent=2)
 
         except (OSError, json.JSONEncodeError):
-            # Silently fail if we can't write cache
             pass
 
     @staticmethod
@@ -87,6 +173,9 @@ class UpdateChecker:
         Returns:
             True if latest > current, False otherwise
         """
+        if not UpdateChecker._is_valid_version(current) or not UpdateChecker._is_valid_version(latest):
+            return False
+
         try:
             current_parts = [int(x) for x in current.split(".")]
             latest_parts = [int(x) for x in latest.split(".")]
@@ -116,20 +205,14 @@ class UpdateChecker:
         Returns:
             The latest version string if an update is available, None otherwise
         """
+        if not cls._is_valid_version(current_version):
+            return None
+
         try:
             loop = asyncio.get_event_loop()
-            response = await loop.run_in_executor(None, lambda: requests.get(cls.REPO_URL, timeout=cls.TIMEOUT))
+            latest_version = await loop.run_in_executor(None, cls._fetch_latest_version)
 
-            if response.status_code != 200:
+            if latest_version and cls._compare_versions(current_version, latest_version):
-                return None
-
-            data = response.json()
-            latest_version = data.get("tag_name", "").lstrip("v")
-
-            if not latest_version:
-                return None
-
-            if cls._compare_versions(current_version, latest_version):
                 return latest_version
 
         except Exception:
@@ -137,6 +220,31 @@ class UpdateChecker:
 
         return None
 
+    @classmethod
+    def _get_cached_update_info(cls, current_version: str) -> Optional[str]:
+        """
+        Check if there's a cached update available for the current version.
+
+        Args:
+            current_version: The current version string
+
+        Returns:
+            The latest version string if an update is available from cache, None otherwise
+        """
+        cache_data = cls._load_cache_data()
+
+        if not cache_data:
+            return None
+
+        cached_current = cache_data.get("current_version")
+        cached_latest = cache_data.get("latest_version")
+
+        if cached_current == current_version and cached_latest:
+            if cls._compare_versions(current_version, cached_latest):
+                return cached_latest
+
+        return None
+
     @classmethod
     def check_for_updates_sync(cls, current_version: str, check_interval: Optional[int] = None) -> Optional[str]:
         """
@@ -149,40 +257,20 @@ class UpdateChecker:
         Returns:
             The latest version string if an update is available, None otherwise
         """
-        # Use config value if not specified
+        if not cls._is_valid_version(current_version):
+            return None
+
         if check_interval is None:
             from unshackle.core.config import config
 
-            check_interval = config.update_check_interval * 60 * 60  # Convert hours to seconds
+            check_interval = config.update_check_interval * 60 * 60
 
-        # Check if we should skip this check due to rate limiting
         if not cls._should_check_for_updates(check_interval):
-            return None
+            return cls._get_cached_update_info(current_version)
 
-        try:
+        latest_version = cls._fetch_latest_version()
-            response = requests.get(cls.REPO_URL, timeout=cls.TIMEOUT)
+        cls._update_cache(latest_version, current_version)
-
+        if latest_version and cls._compare_versions(current_version, latest_version):
-            if response.status_code != 200:
-                # Update cache even on failure to prevent rapid retries
-                cls._update_cache()
-                return None
-
-            data = response.json()
-            latest_version = data.get("tag_name", "").lstrip("v")
-
-            if not latest_version:
-                cls._update_cache()
-                return None
-
-            # Update cache with the latest version info
-            cls._update_cache(latest_version)
-
-            if cls._compare_versions(current_version, latest_version):
             return latest_version
 
-        except Exception:
-            # Update cache even on exception to prevent rapid retries
-            cls._update_cache()
-            pass
-
         return None

unshackle/core/utils/tags.py

@@ -44,6 +44,89 @@ def fuzzy_match(a: str, b: str, threshold: float = 0.8) -> bool:
     return ratio >= threshold
 
 
+def search_simkl(title: str, year: Optional[int], kind: str) -> Tuple[Optional[dict], Optional[str], Optional[int]]:
+    """Search Simkl API for show information by filename (no auth required)."""
+    log.debug("Searching Simkl for %r (%s, %s)", title, kind, year)
+
+    # Construct appropriate filename based on type
+    filename = f"{title}"
+    if year:
+        filename = f"{title} {year}"
+
+    if kind == "tv":
+        filename += " S01E01.mkv"
+    else:  # movie
+        filename += " 2160p.mkv"
+
+    try:
+        resp = requests.post("https://api.simkl.com/search/file", json={"file": filename}, headers=HEADERS, timeout=30)
+        resp.raise_for_status()
+        data = resp.json()
+        log.debug("Simkl API response received")
+
+        # Handle case where SIMKL returns empty list (no results)
+        if isinstance(data, list):
+            log.debug("Simkl returned list (no matches) for %r", filename)
+            return None, None, None
+
+        # Handle TV show responses
+        if data.get("type") == "episode" and "show" in data:
+            show_info = data["show"]
+            show_title = show_info.get("title")
+            show_year = show_info.get("year")
+
+            # Verify title matches and year if provided
+            if not fuzzy_match(show_title, title):
+                log.debug("Simkl title mismatch: searched %r, got %r", title, show_title)
+                return None, None, None
+            if year and show_year and abs(year - show_year) > 1:  # Allow 1 year difference
+                log.debug("Simkl year mismatch: searched %d, got %d", year, show_year)
+                return None, None, None
+
+            tmdb_id = show_info.get("ids", {}).get("tmdbtv")
+            if tmdb_id:
+                tmdb_id = int(tmdb_id)
+            log.debug("Simkl -> %s (TMDB ID %s)", show_title, tmdb_id)
+            return data, show_title, tmdb_id
+
+        # Handle movie responses
+        elif data.get("type") == "movie" and "movie" in data:
+            movie_info = data["movie"]
+            movie_title = movie_info.get("title")
+            movie_year = movie_info.get("year")
+
+            # Verify title matches and year if provided
+            if not fuzzy_match(movie_title, title):
+                log.debug("Simkl title mismatch: searched %r, got %r", title, movie_title)
+                return None, None, None
+            if year and movie_year and abs(year - movie_year) > 1:  # Allow 1 year difference
+                log.debug("Simkl year mismatch: searched %d, got %d", year, movie_year)
+                return None, None, None
+
+            ids = movie_info.get("ids", {})
+            tmdb_id = ids.get("tmdb") or ids.get("moviedb")
+            if tmdb_id:
+                tmdb_id = int(tmdb_id)
+            log.debug("Simkl -> %s (TMDB ID %s)", movie_title, tmdb_id)
+            return data, movie_title, tmdb_id
+
+    except (requests.RequestException, ValueError, KeyError) as exc:
+        log.debug("Simkl search failed: %s", exc)
+
+    return None, None, None
+
+
+def search_show_info(title: str, year: Optional[int], kind: str) -> Tuple[Optional[int], Optional[str], Optional[str]]:
+    """Search for show information, trying Simkl first, then TMDB fallback. Returns (tmdb_id, title, source)."""
+    simkl_data, simkl_title, simkl_tmdb_id = search_simkl(title, year, kind)
+
+    if simkl_data and simkl_title and fuzzy_match(simkl_title, title):
+        return simkl_tmdb_id, simkl_title, "simkl"
+
+    tmdb_id, tmdb_title = search_tmdb(title, year, kind)
+    return tmdb_id, tmdb_title, "tmdb"
+
+
 def search_tmdb(title: str, year: Optional[int], kind: str) -> Tuple[Optional[int], Optional[str]]:
     api_key = _api_key()
     if not api_key:
@@ -202,10 +285,8 @@ def tag_file(path: Path, title: Title, tmdb_id: Optional[int] | None = None) ->
     log.debug("Tagging file %s with title %r", path, title)
     standard_tags: dict[str, str] = {}
     custom_tags: dict[str, str] = {}
-    # To add custom information to the tags
-    # custom_tags["Text to the left side"] = "Text to the right side"
 
-    if config.tag:
+    if config.tag and config.tag_group_name:
         custom_tags["Group"] = config.tag
     description = getattr(title, "description", None)
     if description:
@@ -216,12 +297,6 @@ def tag_file(path: Path, title: Title, tmdb_id: Optional[int] | None = None) ->
             description = truncated + "..."
         custom_tags["Description"] = description
 
-    api_key = _api_key()
-    if not api_key:
-        log.debug("No TMDB API key set; applying basic tags only")
-        _apply_tags(path, custom_tags)
-        return
-
     if isinstance(title, Movie):
         kind = "movie"
         name = title.name
@@ -234,10 +309,38 @@ def tag_file(path: Path, title: Title, tmdb_id: Optional[int] | None = None) ->
         _apply_tags(path, custom_tags)
         return
 
+    if config.tag_imdb_tmdb:
+        # If tmdb_id is provided (via --tmdb), skip Simkl and use TMDB directly
+        if tmdb_id is not None:
+            log.debug("Using provided TMDB ID %s for tags", tmdb_id)
+        else:
+            # Try Simkl first for automatic lookup
+            simkl_data, simkl_title, simkl_tmdb_id = search_simkl(name, year, kind)
+
+            if simkl_data and simkl_title and fuzzy_match(simkl_title, name):
+                log.debug("Using Simkl data for tags")
+                if simkl_tmdb_id:
+                    tmdb_id = simkl_tmdb_id
+
+                show_ids = simkl_data.get("show", {}).get("ids", {})
+                if show_ids.get("imdb"):
+                    standard_tags["IMDB"] = f"https://www.imdb.com/title/{show_ids['imdb']}"
+                if show_ids.get("tvdb"):
+                    standard_tags["TVDB"] = f"https://thetvdb.com/dereferrer/series/{show_ids['tvdb']}"
+                if show_ids.get("tmdbtv"):
+                    standard_tags["TMDB"] = f"https://www.themoviedb.org/tv/{show_ids['tmdbtv']}"
+
+        # Use TMDB API for additional metadata (either from provided ID or Simkl lookup)
+        api_key = _api_key()
+        if not api_key:
+            log.debug("No TMDB API key set; applying basic tags only")
+            _apply_tags(path, custom_tags)
+            return
+
         tmdb_title: Optional[str] = None
         if tmdb_id is None:
             tmdb_id, tmdb_title = search_tmdb(name, year, kind)
-        log.debug("Search result: %r (ID %s)", tmdb_title, tmdb_id)
+            log.debug("TMDB search result: %r (ID %s)", tmdb_title, tmdb_id)
             if not tmdb_id or not tmdb_title or not fuzzy_match(tmdb_title, name):
                 log.debug("TMDB search did not match; skipping external ID lookup")
                 _apply_tags(path, custom_tags)
@@ -269,6 +372,8 @@ def tag_file(path: Path, title: Title, tmdb_id: Optional[int] | None = None) ->
 
 
 __all__ = [
+    "search_simkl",
+    "search_show_info",
     "search_tmdb",
     "get_title",
     "get_year",

unshackle/services/EXAMPLE/__init__.py

@@ -33,6 +33,7 @@ class EXAMPLE(Service):
 
     TITLE_RE = r"^(?:https?://?domain\.com/details/)?(?P<title_id>[^/]+)"
     GEOFENCE = ("US", "UK")
+    NO_SUBTITLES = True
 
     @staticmethod
     @click.command(name="EXAMPLE", short_help="https://domain.com")

unshackle/unshackle-example.yaml

@@ -1,6 +1,12 @@
 # Group or Username to postfix to the end of all download filenames following a dash
 tag: user_tag
 
+# Enable/disable tagging with group name (default: true)
+tag_group_name: true
+
+# Enable/disable tagging with IMDB/TMDB/TVDB details (default: true)
+tag_imdb_tmdb: true
+
 # Set terminal background color (custom option not in CONFIG.md)
 set_terminal_bg: false
 

uv.lock

@@ -1505,7 +1505,7 @@ wheels = [
 
 [[package]]
 name = "unshackle"
-version = "1.2.0"
+version = "1.4.0"
 source = { editable = "." }
 dependencies = [
     { name = "appdirs" },