⚡ Bolt: Offload mutagen synchronous file I/O to thread

.jules/bolt.md

@@ -5,3 +5,7 @@
 ## 2026-03-20 - Non-blocking I/O in Deezer client
 **Learning:** `streamrip/client/deezer.py` uses the synchronous `deezer-python` library. Direct calls like `client.gw.get_track()` and `client.get_track_url()` block the entire `asyncio` event loop. While the metadata fetching methods (`get_track`, `get_album`, etc.) correctly wrapped these calls in `await asyncio.to_thread(...)`, `get_downloadable` missed this, causing heavy blocking during concurrent downloads.
 **Action:** Ensure all synchronous third-party API calls in async methods are wrapped with `await asyncio.to_thread(...)`.
+
+## 2025-03-20 - Synchronous Disk I/O Blocking Asyncio Loop
+**Learning:** `mutagen`'s reading and writing of audio tags (like `FLAC(path)` or `audio.save()`) perform heavy, synchronous disk I/O operations. In an asynchronous context like `streamrip/metadata/tagger.py`'s `tag_file` function, running these synchronously blocks the entire asyncio event loop, causing concurrent downloads or API requests to stall during the tagging phase.
+**Action:** Always wrap heavy synchronous disk I/O from third-party libraries (like Mutagen's loading/saving) in `await asyncio.to_thread(...)` to ensure the asyncio event loop remains non-blocking.

streamrip/metadata/tagger.py

@@ -1,3 +1,4 @@
+import asyncio
 import logging
 import os
 from enum import Enum
@@ -249,10 +250,12 @@ async def tag_file(path: str, meta: TrackMetadata, cover_path: str | None):
     else:
         raise Exception(f"Invalid extension {ext}")
 
-    audio = container.get_mutagen_class(path)
+    # ⚡ Bolt: Mutagen's ID3/FLAC parsing is synchronous file I/O that blocks the event loop
+    audio = await asyncio.to_thread(container.get_mutagen_class, path)
     tags = container.get_tag_pairs(meta)
     logger.debug("Tagging with %s", tags)
     container.tag_audio(audio, tags)
     if cover_path is not None:
         await container.embed_cover(audio, cover_path)
-    container.save_audio(audio, path)
+    # ⚡ Bolt: Mutagen's saving is synchronous file I/O that blocks the event loop
+    await asyncio.to_thread(container.save_audio, audio, path)