Combined file Support

Support combined episode files under a special season for Stremio

Combined episode files (e.g. "S01 [E04-06]") and whole-season
"Combined" files are now indexed under a special season, so they
appear and play in Stremio.

Recommended setup — give this addon priority over Cinemeta:
- Stremio: arrange the Telegram Stremio addon above the Cinemeta
addon using https://addon-manager.dontwanttos.top/
- Nuvio: in the Addons section, move Telegram Stremio to the top
(before the Cinemeta addon).

Limitation -
Combined files doesn't work in global search.

Backend/helper/metadata.py

@@ -10,7 +10,7 @@ from Backend.logger import LOGGER
 from Backend.helper.imdb import get_detail, get_season, search_title, search_title_multi
 from Backend.helper.settings_manager import SettingsManager
 from Backend.helper.encrypt import encode_string
-from Backend.helper.split_files import parse_split_info
+from Backend.helper.split_files import parse_split_info, parse_combined_episodes
 from themoviedb import aioTMDb
 from rapidfuzz import fuzz
 from guessit import guessit as _guessit
@@ -47,6 +47,21 @@ API_SEMAPHORE = asyncio.Semaphore(12)
 
 _MULTIPART_RE = re.compile(r"(?:part|cd|disc|disk)[s._-]*\d+(?=\.\w+$)", re.IGNORECASE)
 
+# Combined episode files (e.g. "S01 [E04-06]" or "S01 Combined") are grouped under a special season.
+COMBINED_SEASON = 0
+
+
+# Re-file a combined entry under the special season with a descriptive title.
+def _apply_combined_override(payload: dict, combined: dict) -> None:
+    season, start, end = combined["season"], combined["start"], combined["end"]
+    payload["season_number"] = COMBINED_SEASON
+    if start is None:
+        payload["episode_number"] = season * 1000
+        payload["episode_title"] = f"S{season:02d} Complete (Combined)"
+    else:
+        payload["episode_number"] = season * 1000 + start
+        payload["episode_title"] = f"S{season:02d} E{start:02d}-E{end:02d} (Combined)"
+
 _tmdb_client: aioTMDb | None = None
 _tmdb_client_key: str | None = None
 
@@ -531,12 +546,14 @@ async def metadata(filename: str, channel: int, msg_id, override_id: str = None)
         LOGGER.info(f"Skipping {filename}: split video file not meant to be combined in Stremio")
         return None
 
+    combined = parse_combined_episodes(filename)
+
     excess = parsed.get("excess")
-    if excess and any("combined" in item.lower() for item in excess):
+    if not combined and excess and any("combined" in item.lower() for item in excess):
         LOGGER.info(f"Skipping {filename}: contains 'combined'")
         return None
 
-    split_info = parse_split_info(filename)
+    split_info = None if combined else parse_split_info(filename)
     part_number = split_info[1] if split_info else None
 
     title = parsed.get("title")
@@ -545,7 +562,9 @@ async def metadata(filename: str, channel: int, msg_id, override_id: str = None)
     year = parsed.get("year")
     quality = parsed.get("quality")
 
-    if isinstance(season, list) or isinstance(episode, list):
+    if combined:
+        season, episode = combined["season"], combined["start"] or 1
+    elif isinstance(season, list) or isinstance(episode, list):
         LOGGER.warning(f"Invalid season/episode format for {filename}: {parsed}")
         return None
     if season and not episode:
@@ -571,6 +590,8 @@ async def metadata(filename: str, channel: int, msg_id, override_id: str = None)
         if season and episode:
             LOGGER.info(f"Fetching TV metadata: {title} S{season:02d}E{episode:02d} (year={year})")
             result = await fetch_tv_metadata(title, season, episode, encoded_string, year, quality, default_id)
+            if result is not None and combined:
+                _apply_combined_override(result, combined)
         else:
             LOGGER.info(f"Fetching Movie metadata: {title} (year={year})")
             result = await fetch_movie_metadata(title, encoded_string, year, quality, default_id)

Backend/helper/split_files.py

@@ -39,6 +39,48 @@ def parse_split_info(filename: str) -> Optional[Tuple[str, int]]:
     return _normalize(remainder), part_num
 
 
+_COMBINED_EPISODES_RE = re.compile(
+    r"E(?:P|PISODE)?[\s._-]*0*(\d{1,4})[\s._-]*(?:-|–|~|to)+[\s._-]*(?:E(?:P|PISODE)?[\s._-]*)?0*(\d{1,4})(?=\D|$)",
+    re.IGNORECASE,
+)
+_COMBINED_SEASON_RE = re.compile(r"S(?:EASON)?[\s._-]*0*(\d{1,3})", re.IGNORECASE)
+_COMBINED_KEYWORD_RE = re.compile(r"\bcombined\b", re.IGNORECASE)
+
+
+def _combined_season(name: str) -> Optional[int]:
+    match = _COMBINED_SEASON_RE.search(name)
+    return int(match.group(1)) if match else None
+
+
+# Detect a combined file: an episode range ("S01 E04-06") or a whole-season
+# "Combined" file. Returns {season, start, end} (start/end None for whole season).
+def parse_combined_episodes(filename: str) -> Optional[dict]:
+    if not filename:
+        return None
+
+    match = _COMBINED_EPISODES_RE.search(filename)
+    if match:
+        start, end = int(match.group(1)), int(match.group(2))
+        if 1 <= start < end <= 99:
+            return {"season": _combined_season(filename) or 1, "start": start, "end": end}
+
+    if _COMBINED_KEYWORD_RE.search(filename):
+        season = _combined_season(filename)
+        if season is not None:
+            return {"season": season, "start": None, "end": None}
+
+    return None
+
+
+# True when a combined file covers the requested season/episode.
+def combined_covers(combined: dict, season: Optional[int], episode: Optional[int]) -> bool:
+    if season is not None and combined["season"] != int(season):
+        return False
+    if episode is None or combined["start"] is None:
+        return True
+    return combined["start"] <= int(episode) <= combined["end"]
+
+
 def strip_part_suffix(filename: str) -> str:
     if not filename:
         return filename