From 2c1f5aacc175c55aeb6f5ca749259379382755ca Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sun, 29 Mar 2026 22:31:53 +0000 Subject: [PATCH] =?UTF-8?q?=E2=9A=A1=20Bolt:=20Offload=20mutagen=20synchro?= =?UTF-8?q?nous=20file=20I/O=20to=20thread?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mutagen uses synchronous file I/O blocking the main asyncio loop. This commit moves the `get_mutagen_class` and `save_audio` operations to `asyncio.to_thread` preventing blocked concurrent downloads. Co-authored-by: davidjuarezdev <230496599+davidjuarezdev@users.noreply.github.com> --- .jules/bolt.md | 4 ++++ streamrip/metadata/tagger.py | 7 +++++-- 2 files changed, 9 insertions(+), 2 deletions(-) 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)