feat(debug): add comprehensive debug logging for downloaders and muxing

unshackle/core/tracks/tracks.py

@@ -22,7 +22,7 @@ from unshackle.core.tracks.chapters import Chapter, Chapters
 from unshackle.core.tracks.subtitle import Subtitle
 from unshackle.core.tracks.track import Track
 from unshackle.core.tracks.video import Video
-from unshackle.core.utilities import is_close_match, sanitize_filename
+from unshackle.core.utilities import get_debug_logger, is_close_match, sanitize_filename
 from unshackle.core.utils.collections import as_list, flatten
 
 
@@ -507,6 +507,35 @@ class Tracks:
         if not output_path:
             raise ValueError("No tracks provided, at least one track must be provided.")
 
+        debug_logger = get_debug_logger()
+        if debug_logger:
+            debug_logger.log(
+                level="DEBUG",
+                operation="mux_start",
+                message="Starting mkvmerge muxing",
+                context={
+                    "title": title,
+                    "output_path": str(output_path),
+                    "video_count": len(self.videos),
+                    "audio_count": len(self.audio),
+                    "subtitle_count": len(self.subtitles),
+                    "attachment_count": len(self.attachments),
+                    "has_chapters": bool(self.chapters),
+                    "video_tracks": [
+                        {"id": v.id, "codec": getattr(v, "codec", None), "language": str(v.language)}
+                        for v in self.videos
+                    ],
+                    "audio_tracks": [
+                        {"id": a.id, "codec": getattr(a, "codec", None), "language": str(a.language)}
+                        for a in self.audio
+                    ],
+                    "subtitle_tracks": [
+                        {"id": s.id, "codec": getattr(s, "codec", None), "language": str(s.language)}
+                        for s in self.subtitles
+                    ],
+                },
+            )
+
         # let potential failures go to caller, caller should handle
         try:
             errors = []
@@ -516,7 +545,33 @@ class Tracks:
                     errors.append(line)
                 if "progress" in line:
                     progress(total=100, completed=int(line.strip()[14:-1]))
-            return output_path, p.wait(), errors
+
+            returncode = p.wait()
+
+            if debug_logger:
+                if returncode != 0 or errors:
+                    debug_logger.log(
+                        level="ERROR",
+                        operation="mux_failed",
+                        message=f"mkvmerge exited with code {returncode}",
+                        context={
+                            "returncode": returncode,
+                            "output_path": str(output_path),
+                            "errors": errors,
+                        },
+                    )
+                else:
+                    debug_logger.log(
+                        level="DEBUG",
+                        operation="mux_complete",
+                        message="mkvmerge muxing completed successfully",
+                        context={
+                            "output_path": str(output_path),
+                            "output_exists": output_path.exists() if output_path else False,
+                        },
+                    )
+
+            return output_path, returncode, errors
         finally:
             if chapters_path:
                 chapters_path.unlink()