feat: save channel art metadata to <channel>.channel.json on volume

- _fetch_channel_art now accepts data_path and saves the raw yt-dlp info
  dict to <channel>.channel.json for debugging and future reference
- Saves inside <data_path>/<channel_name>/ if that dir exists (per-channel
  layout), otherwise falls back to <data_path>/<channel_name>.channel.json
- _sanitize_filename strips filesystem-unsafe chars from the channel name
- _prefetch_channel_art_bg passes DATA_PATH to _fetch_channel_art
- build_index comment explicitly documents why *.channel.json is skipped
- 7 new tests: build_index isolation, save location, filename sanitization,
  save-error resilience, no-data-path skip

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: aarro

provider/app.py

@@ -134,6 +134,9 @@ def onerror(err: OSError) -> None:
 
     for root, _, files in os.walk(data_path, onerror=onerror):
         for f in files:
+            # Only index yt-dlp video metadata files. *.channel.json (channel art
+            # cache written by _fetch_channel_art) and _collection_map.json must
+            # not be treated as video entries.
             if not f.endswith(".info.json"):
                 continue
             # Try the filename first (yt-dlp default: "Title [VIDEO_ID].info.json").
@@ -214,12 +217,23 @@ def _try_index_from_filename(video_id: str, media_path: str) -> bool:
 
 # ── Channel art helpers ───────────────────────────────────────────────────────
 
+_FILENAME_UNSAFE_RE = re.compile(r'[<>:"/\\|?*\x00-\x1f]')
 
-def _fetch_channel_art(uploader_url: str) -> dict | None:
+
+def _sanitize_filename(name: str) -> str:
+    """Replace filesystem-unsafe characters with underscores."""
+    return _FILENAME_UNSAFE_RE.sub("_", name).strip()
+
+
+def _fetch_channel_art(uploader_url: str, data_path: str | None = None) -> dict | None:
     """Fetch channel avatar and banner from YouTube via yt-dlp. Synchronous — call via thread.
 
     Returns {channel, avatar_url, banner_url} or None on failure.
     Only attempts YouTube URLs (uploader_url contains 'youtube.com').
+
+    If data_path is given, saves the raw yt-dlp channel info dict to
+    <channel_name>.channel.json in the channel's subdirectory (if it exists
+    under data_path) or at the data_path root as a fallback.
     """
     if "youtube.com" not in uploader_url:
         return None
@@ -234,8 +248,22 @@ def _fetch_channel_art(uploader_url: str) -> dict | None:
         }
         with _yt_dlp.YoutubeDL(ydl_opts) as ydl:  # type: ignore[union-attr]
             info = ydl.extract_info(uploader_url, download=False) or {}
+        channel_name = info.get("channel") or info.get("uploader") or ""
+        if data_path and channel_name:
+            safe_name = _sanitize_filename(channel_name)
+            channel_dir = os.path.join(data_path, channel_name)
+            if os.path.isdir(channel_dir):
+                save_path = os.path.join(channel_dir, f"{safe_name}.channel.json")
+            else:
+                save_path = os.path.join(data_path, f"{safe_name}.channel.json")
+            try:
+                with open(save_path, "w", encoding="utf-8") as fh:
+                    json.dump(info, fh, indent=2, ensure_ascii=False)
+                logger.debug("_fetch_channel_art: saved channel JSON to '%s'", save_path)
+            except OSError as e:
+                logger.warning("_fetch_channel_art: could not save channel JSON to '%s': %s", save_path, e)
         return {
-            "channel": info.get("channel") or info.get("uploader") or "",
+            "channel": channel_name,
             "avatar_url": info.get("thumbnail") or "",
             "banner_url": info.get("tvBanner") or info.get("banner") or "",
         }
@@ -318,7 +346,7 @@ async def _prefetch_channel_art_bg(collection_names: list[str]) -> None:
             for url in urls:
                 if url not in _channel_art_cache:
                     try:
-                        result = await asyncio.to_thread(_fetch_channel_art, url)
+                        result = await asyncio.to_thread(_fetch_channel_art, url, DATA_PATH)
                     except Exception:
                         logger.exception(
                             "_prefetch_channel_art_bg: unhandled exception fetching art for '%s' (collection '%s')",

provider/tests/test_app.py

@@ -1962,6 +1962,54 @@ async def test_put_collections_art_field_triggers_artwork_sync(patched_app, monk
     mock_artwork.assert_awaited_once()
 
 
+# ── build_index — *.channel.json and *.info.json separation ──────────────────
+
+
+def test_build_index_ignores_channel_json(tmp_path):
+    """*.channel.json files are not indexed as videos."""
+    from app import build_index
+
+    # A .channel.json file that would collide if incorrectly parsed
+    (tmp_path / "Studio Bruxelles.channel.json").write_text(
+        json.dumps({"id": "should_not_be_indexed", "channel": "Studio Bruxelles"}),
+        encoding="utf-8",
+    )
+    # A legitimate video info file
+    valid_id = "validIDxxxxx"
+    (tmp_path / f"Video [{valid_id}].info.json").write_text(
+        json.dumps({"id": valid_id, "title": "Test"}),
+        encoding="utf-8",
+    )
+
+    index, _ = build_index(str(tmp_path))
+
+    assert valid_id in index, "valid info.json should be indexed"
+    assert "should_not_be_indexed" not in index, "channel.json must not be indexed as a video"
+    assert len(index) == 1
+
+
+def test_build_index_channel_json_in_subdir(tmp_path):
+    """*.channel.json inside a channel subdirectory is also ignored."""
+    from app import build_index
+
+    channel_dir = tmp_path / "alt-J"
+    channel_dir.mkdir()
+    (channel_dir / "alt-J.channel.json").write_text(
+        json.dumps({"id": "fake", "channel": "alt-J"}),
+        encoding="utf-8",
+    )
+    valid_id = "altJvideo1234"
+    (channel_dir / f"Live Set [{valid_id}].info.json").write_text(
+        json.dumps({"id": valid_id, "title": "Live Set"}),
+        encoding="utf-8",
+    )
+
+    index, _ = build_index(str(tmp_path))
+
+    assert valid_id in index
+    assert "fake" not in index
+
+
 # ── _fetch_channel_art ────────────────────────────────────────────────────────
 
 
@@ -2001,6 +2049,94 @@ def test_fetch_channel_art_exception_returns_none(monkeypatch):
     assert result is None
 
 
+def _make_yt_dlp_mock(monkeypatch, info: dict):
+    """Wire up a mock yt-dlp module that returns `info` from extract_info."""
+    mock_ydl = MagicMock()
+    mock_ydl.__enter__ = MagicMock(return_value=mock_ydl)
+    mock_ydl.__exit__ = MagicMock(return_value=False)
+    mock_ydl.extract_info.return_value = info
+    mock_module = MagicMock()
+    mock_module.YoutubeDL.return_value = mock_ydl
+    monkeypatch.setattr(yamp_app, "_yt_dlp", mock_module)
+    monkeypatch.setattr(yamp_app, "_YT_DLP_AVAILABLE", True)
+    return mock_ydl
+
+
+def test_fetch_channel_art_saves_json_flat(tmp_path, monkeypatch):
+    """When no channel subdirectory exists, channel.json is saved at the data root."""
+    from app import _fetch_channel_art
+
+    _make_yt_dlp_mock(monkeypatch, {"channel": "Studio Bruxelles", "thumbnail": "https://img/av.jpg"})
+
+    result = _fetch_channel_art("https://www.youtube.com/@StudioBruxelles", data_path=str(tmp_path))
+
+    assert result is not None
+    assert result["channel"] == "Studio Bruxelles"
+    saved = tmp_path / "Studio Bruxelles.channel.json"
+    assert saved.exists(), "channel.json should be written at the data root"
+    data = json.loads(saved.read_text(encoding="utf-8"))
+    assert data["channel"] == "Studio Bruxelles"
+
+
+def test_fetch_channel_art_saves_json_in_channel_dir(tmp_path, monkeypatch):
+    """When a matching channel subdirectory exists, channel.json is saved inside it."""
+    from app import _fetch_channel_art
+
+    channel_dir = tmp_path / "Studio Bruxelles"
+    channel_dir.mkdir()
+    _make_yt_dlp_mock(monkeypatch, {"channel": "Studio Bruxelles", "thumbnail": "https://img/av.jpg"})
+
+    _fetch_channel_art("https://www.youtube.com/@StudioBruxelles", data_path=str(tmp_path))
+
+    saved = channel_dir / "Studio Bruxelles.channel.json"
+    assert saved.exists(), "channel.json should be saved inside the existing channel dir"
+    assert (tmp_path / "Studio Bruxelles.channel.json").exists() is False, "should not also save at root"
+
+
+def test_fetch_channel_art_sanitizes_filename(tmp_path, monkeypatch):
+    """Channel names with unsafe characters are sanitized in the filename."""
+    from app import _fetch_channel_art
+
+    _make_yt_dlp_mock(monkeypatch, {"channel": 'AC/DC: Rock"n"Roll', "thumbnail": ""})
+
+    _fetch_channel_art("https://www.youtube.com/@ACDC", data_path=str(tmp_path))
+
+    files = list(tmp_path.iterdir())
+    assert len(files) == 1
+    assert files[0].name.endswith(".channel.json")
+    assert "/" not in files[0].name
+    assert ":" not in files[0].name
+
+
+def test_fetch_channel_art_save_error_does_not_raise(tmp_path, monkeypatch):
+    """An OSError while saving channel.json is logged but does not affect the return value."""
+    from app import _fetch_channel_art
+
+    _make_yt_dlp_mock(monkeypatch, {"channel": "Test Channel", "thumbnail": "https://img/av.jpg"})
+
+    # Make tmp_path read-only so the write fails
+    tmp_path.chmod(0o555)
+    try:
+        result = _fetch_channel_art("https://www.youtube.com/@TestChannel", data_path=str(tmp_path))
+    finally:
+        tmp_path.chmod(0o755)  # restore so tmp_path cleanup works
+
+    assert result is not None
+    assert result["channel"] == "Test Channel"
+
+
+def test_fetch_channel_art_no_data_path_skips_save(tmp_path, monkeypatch):
+    """When data_path is None, no file is written."""
+    from app import _fetch_channel_art
+
+    _make_yt_dlp_mock(monkeypatch, {"channel": "Test Channel", "thumbnail": "https://img/av.jpg"})
+
+    result = _fetch_channel_art("https://www.youtube.com/@TestChannel", data_path=None)
+
+    assert result is not None
+    assert list(tmp_path.iterdir()) == [], "no file should be written when data_path is None"
+
+
 # ── _prefetch_channel_art_bg — error handling ────────────────────────────────