feat: extract and store track duration for teal.fm scrobbles (#469)

- add mutagen dependency for audio metadata extraction
- create backend/utilities/audio.py with extract_duration()
- extract duration during upload, store in track.extra["duration"]
- add backfill script for tracks uploaded before this feature

duration is now correctly passed to teal.fm scrobble records.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <[e-mail]>

backend/pyproject.toml

···
     "aioboto3>=15.5.0",
     "slowapi @ git+https://github.com/zzstoatzz/slowapi.git@fix-deprecation",
     "orjson>=3.11.4",
+    "mutagen>=1.47.0",
 ]
 
 requires-python = ">=3.11"

backend/src/backend/api/tracks/mutations.py

···
         audio_url=audio_url,
         file_type=track.file_type,
         album=track.album,
-        duration=None,
+        duration=track.duration,
         features=track.features if track.features else None,
         image_url=image_url_override or await track.get_image_url(),
     )
···
         audio_url=track.r2_url,
         file_type=track.file_type,
         album=track.album,
-        duration=None,
+        duration=track.duration,
         features=track.features if track.features else None,
         image_url=await track.get_image_url(),
     )

backend/src/backend/api/tracks/uploads.py

···
 from backend.models import Artist, Tag, Track, TrackTag
 from backend.models.job import JobStatus, JobType
 from backend.storage import storage
+from backend.utilities.audio import extract_duration
 from backend.utilities.database import db_session
 from backend.utilities.hashing import CHUNK_SIZE
 from backend.utilities.progress import R2ProgressTracker
···
                     error=f"unsupported file type: {ext}",
                 )
                 return
+
+            # extract duration from audio file
+            with open(file_path, "rb") as f:
+                duration = extract_duration(f)
+            if duration:
+                logfire.info("extracted duration", duration=duration)
 
             # save audio file
             await job_service.update_progress(
···
                             audio_url=r2_url,
                             file_type=ext[1:],
                             album=album,
-                            duration=None,
+                            duration=duration,
                             features=featured_artists if featured_artists else None,
                             image_url=image_url,
                         )
···
                     phase="database",
                 )
                 extra = {}
+                if duration:
+                    extra["duration"] = duration
                 album_record = None
                 if album:
                     extra["album"] = album

backend/src/backend/utilities/audio.py

···
+"""audio file utilities."""
+
+import io
+import logging
+from typing import BinaryIO
+
+from mutagen import File as MutagenFile
+
+logger = logging.getLogger(__name__)
+
+
+def extract_duration(audio_data: bytes | BinaryIO) -> int | None:
+    """extract duration from audio file data.
+
+    args:
+        audio_data: raw audio bytes or file-like object
+
+    returns:
+        duration in seconds, or None if extraction fails
+    """
+    try:
+        if isinstance(audio_data, bytes):
+            audio_data = io.BytesIO(audio_data)
+
+        audio = MutagenFile(audio_data)
+        if audio is None:
+            logger.warning("mutagen could not identify audio format")
+            return None
+
+        if audio.info is None:
+            logger.warning("audio file has no info")
+            return None
+
+        duration = getattr(audio.info, "length", None)
+        if duration is None:
+            logger.warning("audio file has no length info")
+            return None
+
+        return int(duration)
+
+    except Exception as e:
+        logger.warning(f"failed to extract duration: {e}")
+        return None

backend/uv.lock

···
     { name = "greenlet" },
     { name = "httpx" },
     { name = "logfire", extra = ["fastapi", "sqlalchemy"] },
+    { name = "mutagen" },
     { name = "orjson" },
     { name = "passlib", extra = ["bcrypt"] },
     { name = "psycopg", extra = ["binary"] },
···
     { name = "greenlet", specifier = ">=3.2.4" },
     { name = "httpx", specifier = ">=0.28.0" },
     { name = "logfire", extras = ["fastapi", "sqlalchemy"], specifier = ">=4.14.2" },
+    { name = "mutagen", specifier = ">=1.47.0" },
     { name = "orjson", specifier = ">=3.11.4" },
     { name = "passlib", extras = ["bcrypt"], specifier = ">=1.7.4" },
     { name = "psycopg", extras = ["binary"], specifier = ">=3.2.12" },
···
     { url = "https://files.pythonhosted.org/packages/ba/8f/0a60e501584145588be1af5cc829265701ba3c35a64aec8e07cbb71d39bb/multidict-6.7.0-cp314-cp314t-win_amd64.whl", hash = "sha256:09929cab6fcb68122776d575e03c6cc64ee0b8fca48d17e135474b042ce515cd", size = 53507, upload-time = "2025-10-06T14:51:53.672Z" },
     { url = "https://files.pythonhosted.org/packages/7f/ae/3148b988a9c6239903e786eac19c889fab607c31d6efa7fb2147e5680f23/multidict-6.7.0-cp314-cp314t-win_arm64.whl", hash = "sha256:cc41db090ed742f32bd2d2c721861725e6109681eddf835d0a82bd3a5c382827", size = 44804, upload-time = "2025-10-06T14:51:55.415Z" },
     { url = "https://files.pythonhosted.org/packages/b7/da/7d22601b625e241d4f23ef1ebff8acfc60da633c9e7e7922e24d10f592b3/multidict-6.7.0-py3-none-any.whl", hash = "sha256:394fc5c42a333c9ffc3e421a4c85e08580d990e08b99f6bf35b4132114c5dcb3", size = 12317, upload-time = "2025-10-06T14:52:29.272Z" },
+]
+
+[[package]]
+name = "mutagen"
+version = "1.47.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/81/e6/64bc71b74eef4b68e61eb921dcf72dabd9e4ec4af1e11891bbd312ccbb77/mutagen-1.47.0.tar.gz", hash = "sha256:719fadef0a978c31b4cf3c956261b3c58b6948b32023078a2117b1de09f0fc99", size = 1274186, upload-time = "2023-09-03T16:33:33.411Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b0/7a/620f945b96be1f6ee357d211d5bf74ab1b7fe72a9f1525aafbfe3aee6875/mutagen-1.47.0-py3-none-any.whl", hash = "sha256:edd96f50c5907a9539d8e5bba7245f62c9f520aef333d13392a79a4f70aca719", size = 194391, upload-time = "2023-09-03T16:33:29.955Z" },
 ]
 
 [[package]]

scripts/backfill_duration.py

···
+#!/usr/bin/env -S uv run --script --quiet
+"""backfill duration for tracks missing it.
+
+## Context
+
+Tracks uploaded before duration extraction was implemented have NULL duration.
+This affects teal.fm scrobbles which should include duration metadata.
+
+## What This Script Does
+
+1. Finds all tracks with NULL duration in extra
+2. Downloads audio files from R2 concurrently (semaphore-limited)
+3. Extracts duration using mutagen
+4. Updates database with extracted durations
+
+## Usage
+
+```bash
+# dry run (show what would be updated)
+uv run scripts/backfill_duration.py --dry-run
+
+# actually update the database
+uv run scripts/backfill_duration.py
+
+# limit concurrency (default: 10)
+uv run scripts/backfill_duration.py --concurrency 5
+
+# target specific environment
+DATABASE_URL=postgresql://... uv run scripts/backfill_duration.py
+```
+
+Run in order: dev → staging → prod
+"""
+
+import asyncio
+import io
+import logging
+import sys
+from pathlib import Path
+
+import httpx
+from mutagen import File as MutagenFile
+
+# add src to path so we can import backend modules
+sys.path.insert(0, str(Path(__file__).parent.parent / "backend" / "src"))
+
+from sqlalchemy import select, update
+
+from backend.models import Track
+from backend.utilities.database import db_session
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(levelname)s - %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+
+def extract_duration_from_bytes(audio_data: bytes) -> int | None:
+    """extract duration from audio bytes."""
+    try:
+        audio = MutagenFile(io.BytesIO(audio_data))
+        if audio is None or audio.info is None:
+            return None
+        length = getattr(audio.info, "length", None)
+        return int(length) if length else None
+    except Exception as e:
+        logger.warning(f"mutagen error: {e}")
+        return None
+
+
+async def fetch_and_extract(
+    client: httpx.AsyncClient,
+    track: Track,
+    semaphore: asyncio.Semaphore,
+) -> tuple[int, int | None, str | None]:
+    """fetch audio from R2 and extract duration.
+
+    returns: (track_id, duration, error)
+    """
+    async with semaphore:
+        if not track.r2_url:
+            return (track.id, None, "no r2_url")
+
+        try:
+            logger.info(f"fetching track {track.id}: {track.title[:40]}...")
+            response = await client.get(track.r2_url, follow_redirects=True)
+            response.raise_for_status()
+
+            duration = extract_duration_from_bytes(response.content)
+            if duration:
+                logger.info(f"  → {duration}s")
+                return (track.id, duration, None)
+            else:
+                return (track.id, None, "could not extract duration")
+
+        except httpx.HTTPStatusError as e:
+            return (track.id, None, f"HTTP {e.response.status_code}")
+        except Exception as e:
+            return (track.id, None, str(e))
+
+
+async def fetch_and_extract_simple(
+    client: httpx.AsyncClient,
+    track_id: int,
+    title: str,
+    r2_url: str | None,
+    semaphore: asyncio.Semaphore,
+) -> tuple[int, int | None, str | None]:
+    """fetch audio header from R2 and extract duration.
+
+    uses Range request to fetch only first 256KB (enough for metadata).
+    falls back to full download if range request fails or duration not found.
+
+    returns: (track_id, duration, error)
+    """
+    async with semaphore:
+        if not r2_url:
+            return (track_id, None, "no r2_url")
+
+        try:
+            logger.info(f"fetching track {track_id}: {title[:40]}...")
+
+            # try range request first (256KB should be enough for most formats)
+            headers = {"Range": "bytes=0-262143"}
+            response = await client.get(r2_url, headers=headers, follow_redirects=True)
+
+            # 206 = partial content (range worked), 200 = full file (range ignored)
+            if response.status_code not in (200, 206):
+                response.raise_for_status()
+
+            duration = extract_duration_from_bytes(response.content)
+            if duration:
+                logger.info(f"  → {duration}s")
+                return (track_id, duration, None)
+
+            # if range didn't give us duration, try full file
+            if response.status_code == 206:
+                logger.info("  range request didn't work, fetching full file...")
+                response = await client.get(r2_url, follow_redirects=True)
+                response.raise_for_status()
+                duration = extract_duration_from_bytes(response.content)
+                if duration:
+                    logger.info(f"  → {duration}s")
+                    return (track_id, duration, None)
+
+            return (track_id, None, "could not extract duration")
+
+        except httpx.HTTPStatusError as e:
+            return (track_id, None, f"HTTP {e.response.status_code}")
+        except Exception as e:
+            return (track_id, None, str(e))
+
+
+async def backfill_duration(dry_run: bool = False, concurrency: int = 10) -> None:
+    """backfill duration for tracks missing it."""
+
+    # phase 1: query tracks needing backfill, then close connection
+    track_data: list[tuple[int, str, str | None, dict | None]] = []
+    async with db_session() as db:
+        stmt = select(Track).where(
+            Track.extra["duration"].astext.is_(None) | ~Track.extra.has_key("duration")
+        )
+        result = await db.execute(stmt)
+        tracks = list(result.scalars().all())
+
+        if not tracks:
+            logger.info("no tracks need duration backfill")
+            return
+
+        logger.info(f"found {len(tracks)} tracks needing duration backfill")
+
+        if dry_run:
+            logger.info("dry run mode - tracks that would be updated:")
+            for track in tracks:
+                logger.info(f"  {track.id}: {track.title} ({track.r2_url})")
+            return
+
+        # extract plain data before closing session
+        track_data = [(t.id, t.title, t.r2_url, t.extra) for t in tracks]
+
+    # phase 2: download files and extract durations (no DB connection)
+    semaphore = asyncio.Semaphore(concurrency)
+    logger.info(
+        f"processing {len(track_data)} tracks with concurrency={concurrency}..."
+    )
+
+    async with httpx.AsyncClient(timeout=120.0) as client:
+        results = await asyncio.gather(
+            *[
+                fetch_and_extract_simple(client, tid, title, r2_url, semaphore)
+                for tid, title, r2_url, _ in track_data
+            ]
+        )
+
+    # build update map
+    updates: list[tuple[int, dict]] = []
+    failed = 0
+    track_extras = {tid: extra or {} for tid, _, _, extra in track_data}
+    track_titles = {tid: title for tid, title, _, _ in track_data}
+
+    for track_id, duration, error in results:
+        if duration:
+            new_extra = {**track_extras[track_id], "duration": duration}
+            updates.append((track_id, new_extra))
+        else:
+            failed += 1
+            logger.warning(
+                f"failed track {track_id} ({track_titles[track_id]}): {error}"
+            )
+
+    if not updates:
+        logger.info("no updates to commit")
+        return
+
+    # phase 3: fresh connection to commit updates
+    logger.info(f"committing {len(updates)} updates...")
+    async with db_session() as db:
+        for track_id, new_extra in updates:
+            stmt = update(Track).where(Track.id == track_id).values(extra=new_extra)
+            await db.execute(stmt)
+        await db.commit()
+
+    logger.info(f"backfill complete: {len(updates)} updated, {failed} failed")
+
+
+async def main() -> None:
+    """main entry point."""
+    dry_run = "--dry-run" in sys.argv
+
+    concurrency = 10
+    for i, arg in enumerate(sys.argv):
+        if arg == "--concurrency" and i + 1 < len(sys.argv):
+            concurrency = int(sys.argv[i + 1])
+
+    if dry_run:
+        logger.info("DRY RUN mode - no changes will be made")
+
+    await backfill_duration(dry_run=dry_run, concurrency=concurrency)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())