diff --git a/.jules/bolt.md b/.jules/bolt.md index babd2024..0cf6e327 100644 --- a/.jules/bolt.md +++ b/.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. diff --git a/streamrip/metadata/tagger.py b/streamrip/metadata/tagger.py index aae8e2b5..f4c3bf1a 100644 --- a/streamrip/metadata/tagger.py +++ b/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)