From c47aad6fa17f017bce135a7597e0d2bb19eecca4 Mon Sep 17 00:00:00 2001 From: imSp4rky Date: Sat, 11 Jul 2026 11:46:58 -0600 Subject: [PATCH] feat(tags): add OMDb metadata provider with omdb_api_key config --- docs/reference/configuration.md | 4 +- unshackle/core/config.py | 1 + unshackle/core/providers/__init__.py | 23 ++++- unshackle/core/providers/omdb.py | 130 +++++++++++++++++++++++++++ 4 files changed, 155 insertions(+), 3 deletions(-) create mode 100644 unshackle/core/providers/omdb.py diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index abdfcf84..7f8366ed 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -37,7 +37,7 @@ This page assumes you already know the basics and want precise details. | [DRM & CDM](#drm-cdm) | `cdm`, `remote_cdm`, `decryption` | | [Network & proxy](#network-proxy) | `network`, `headers`, `proxy_providers` | | [Key vaults](#key-vaults) | `key_vaults`, `vault_timeout` | -| [External API keys](#external-api-keys) | `imdb_api_enabled`, `tmdb_api_key`, `simkl_client_id`, `decrypt_labs_api_key`, `ipinfo_api_key` | +| [External API keys](#external-api-keys) | `imdb_api_enabled`, `omdb_api_key`, `tmdb_api_key`, `simkl_client_id`, `decrypt_labs_api_key`, `ipinfo_api_key` | | [Caching & updates](#caching-updates) | `title_cache_enabled`, `title_cache_time`, `title_cache_max_retention`, `update_checks`, `update_check_interval` | | [Logging, privacy & debug](#logging-privacy-debug) | `redact_paths`, `debug`, `debug_keys`, `debug_requests`, `set_terminal_bg` | | [Deprecated & removed](#deprecated-removed-keys) | `curl_impersonate`, `downloader`, `scene_naming` | @@ -749,6 +749,7 @@ All default to an empty string and enable optional metadata/geolocation features | Key | Type | Default | Description | |-----|------|---------|-------------| | `imdb_api_enabled` | bool | `false` | Use the free imdbapi.dev metadata provider, which needs no API key. Off by default since the site has been unreliable. | +| `omdb_api_key` | str | `""` | [OMDb](https://www.omdbapi.com/) API key for IMDb metadata lookups; a more reliable alternative to imdbapi.dev. Free keys are available on the OMDb site. | | `tmdb_api_key` | str | `""` | TMDB API key for metadata enrichment and external-ID tags. | | `simkl_client_id` | str | `""` | SIMKL client ID for metadata lookups; an alternative/fallback source to TMDB. | | `decrypt_labs_api_key` | str | `""` | Global Decrypt Labs API key (used by remote CDM / vault). | @@ -872,6 +873,7 @@ proxy_providers: basic: us: http://user:pass@1.2.3.4:8080 +omdb_api_key: "your-omdb-key" tmdb_api_key: "your-tmdb-key" title_cache_time: 3600 redact_paths: true diff --git a/unshackle/core/config.py b/unshackle/core/config.py index a8008741..f8cf4973 100644 --- a/unshackle/core/config.py +++ b/unshackle/core/config.py @@ -115,6 +115,7 @@ class Config: self.tag_group_name: bool = kwargs.get("tag_group_name", True) self.tag_imdb_tmdb: bool = kwargs.get("tag_imdb_tmdb", True) self.imdb_api_enabled: bool = kwargs.get("imdb_api_enabled", False) + self.omdb_api_key: str = kwargs.get("omdb_api_key") or "" self.tmdb_api_key: str = kwargs.get("tmdb_api_key") or "" self.simkl_client_id: str = kwargs.get("simkl_client_id") or "" self.decrypt_labs_api_key: str = kwargs.get("decrypt_labs_api_key") or "" diff --git a/unshackle/core/providers/__init__.py b/unshackle/core/providers/__init__.py index 5ec73435..85bdc667 100644 --- a/unshackle/core/providers/__init__.py +++ b/unshackle/core/providers/__init__.py @@ -6,14 +6,15 @@ import requests from unshackle.core.providers._base import ExternalIds, MetadataProvider, MetadataResult, fuzzy_match, log from unshackle.core.providers.imdbapi import IMDBApiProvider +from unshackle.core.providers.omdb import OMDBProvider from unshackle.core.providers.simkl import SimklProvider from unshackle.core.providers.tmdb import TMDBProvider if TYPE_CHECKING: from unshackle.core.title_cacher import TitleCacher -# Ordered by priority: IMDBApi (free), SIMKL, TMDB -ALL_PROVIDERS: list[type[MetadataProvider]] = [IMDBApiProvider, SimklProvider, TMDBProvider] +# Ordered by priority: IMDBApi (free), OMDb, SIMKL, TMDB +ALL_PROVIDERS: list[type[MetadataProvider]] = [IMDBApiProvider, OMDBProvider, SimklProvider, TMDBProvider] def get_available_providers() -> list[MetadataProvider]: @@ -390,6 +391,24 @@ def _cached_to_result(cached: dict, provider_name: str, kind: str) -> Optional[M source="simkl", raw=cached, ) + elif provider_name == "omdb": + title = cached.get("Title") + year_str = cached.get("Year") + year = int(year_str[:4]) if year_str and len(year_str) >= 4 and year_str[:4].isdigit() else None + enriched = cached.get("_enriched_ids", {}) + return MetadataResult( + title=title, + year=year, + kind=kind, + external_ids=ExternalIds( + imdb_id=cached.get("imdbID"), + tmdb_id=enriched.get("tmdb_id"), + tmdb_kind=enriched.get("tmdb_kind"), + tvdb_id=enriched.get("tvdb_id"), + ), + source="omdb", + raw=cached, + ) elif provider_name == "imdbapi": title = cached.get("primaryTitle") or cached.get("originalTitle") year = cached.get("startYear") diff --git a/unshackle/core/providers/omdb.py b/unshackle/core/providers/omdb.py new file mode 100644 index 00000000..8f450f84 --- /dev/null +++ b/unshackle/core/providers/omdb.py @@ -0,0 +1,130 @@ +from __future__ import annotations + +from difflib import SequenceMatcher +from typing import Optional, Union + +import requests + +from unshackle.core.config import config +from unshackle.core.providers._base import ExternalIds, MetadataProvider, MetadataResult, _clean, fuzzy_match + +# Mapping from our kind ("movie"/"tv") to OMDb title types +KIND_TO_TYPE: dict[str, str] = { + "movie": "movie", + "tv": "series", +} + + +def _parse_year(value: Optional[str]) -> Optional[int]: + # OMDb years look like "2017", "2008–2013" or "2023–" + if value and len(value) >= 4 and value[:4].isdigit(): + return int(value[:4]) + return None + + +class OMDBProvider(MetadataProvider): + """OMDb metadata provider (omdbapi.com). Native IDs are IMDb IDs.""" + + NAME = "omdb" + REQUIRES_KEY = True + BASE_URL = "https://www.omdbapi.com/" + + def is_available(self) -> bool: + return bool(config.omdb_api_key) + + @property + def _api_key(self) -> str: + return config.omdb_api_key + + def _get(self, params: dict[str, str]) -> Optional[dict]: + try: + r = self.session.get(self.BASE_URL, params={"apikey": self._api_key, **params}, timeout=30) + r.raise_for_status() + data = r.json() + except (requests.RequestException, ValueError) as exc: + self.log.debug("OMDb request failed: %s", exc) + return None + if data.get("Response") != "True": + self.log.debug("OMDb error: %s", data.get("Error")) + return None + return data + + def search(self, title: str, year: Optional[int], kind: str) -> Optional[MetadataResult]: + self.log.debug("Searching OMDb for %r (%s, %s)", title, kind, year) + + params: dict[str, str] = {"s": title} + type_filter = KIND_TO_TYPE.get(kind) + if type_filter: + params["type"] = type_filter + if year is not None: + params["y"] = str(year) + + data = self._get(params) + if not data and year is not None: + # OMDb's year filter is exact; retry without it for off-by-one metadata + del params["y"] + data = self._get(params) + if not data: + return None + + results = data.get("Search") or [] + + best_match: Optional[dict] = None + best_ratio = 0.0 + for candidate in results: + name = candidate.get("Title") or "" + if not name: + continue + ratio = SequenceMatcher(None, _clean(title), _clean(name)).ratio() + if ratio > best_ratio: + candidate_year = _parse_year(candidate.get("Year")) + if year and candidate_year and abs(year - candidate_year) > 1: + continue + best_ratio = ratio + best_match = candidate + + if not best_match: + self.log.debug("No matching result found in OMDb for %r", title) + return None + + result_title = best_match.get("Title") + if not result_title or not fuzzy_match(result_title, title): + self.log.debug("OMDb title mismatch: searched %r, got %r", title, result_title) + return None + + imdb_id = best_match.get("imdbID") + self.log.debug("OMDb -> %s (ID %s)", result_title, imdb_id) + + # Fetch full detail so raw carries ratings, genre, rating cert, etc. + detail = self._get({"i": imdb_id}) if imdb_id else None + + return MetadataResult( + title=result_title, + year=_parse_year(best_match.get("Year")), + kind=kind, + external_ids=ExternalIds(imdb_id=imdb_id), + source="omdb", + raw=detail or best_match, + ) + + def get_by_id(self, provider_id: Union[int, str], kind: str) -> Optional[MetadataResult]: + """Fetch metadata by IMDb ID (e.g. 'tt1375666').""" + imdb_id = str(provider_id) + self.log.debug("Fetching OMDb title %s", imdb_id) + + data = self._get({"i": imdb_id}) + if not data: + return None + + return MetadataResult( + title=data.get("Title"), + year=_parse_year(data.get("Year")), + kind=kind, + external_ids=ExternalIds(imdb_id=data.get("imdbID")), + source="omdb", + raw=data, + ) + + def get_external_ids(self, provider_id: Union[int, str], kind: str) -> ExternalIds: + """Return external IDs. For OMDb, the provider_id IS the IMDb ID.""" + return ExternalIds(imdb_id=str(provider_id))