audio-media-utils 0.1.0__tar.gz

audio_media_utils-0.1.0/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: audio-media-utils
+Version: 0.1.0
+Summary: Utilities for yt-dlp audio downloads and simple mutagen metadata workflows
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: mutagen<2.0,>=1.47
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=9; extra == "dev"
+Requires-Dist: pytest-cov<7,>=6; extra == "dev"
+Requires-Dist: sphinx<9,>=8; extra == "dev"
+
+# audio_media_utils
+
+Utilities for audio-oriented download workflows and simple metadata editing.
+
+This repository is intentionally focused on reusable domain helpers for:
+
+- YouTube and `yt-dlp` download helpers
+- playlist detection and expansion
+- simple audio metadata reads and writes with `mutagen`
+- filename and path helpers for tagged audio files
+
+It does not include worker loops, logging infrastructure, Docker wiring, or service-specific orchestration.
+
+## Planned package layout
+
+```txt
+src/audio_media_utils/
+|-- youtube/
+|   |-- models.py
+|   |-- urls.py
+|   |-- ytdlp_runner.py
+|   |-- playlists.py
+|   `-- downloads.py
+|-- audio/
+|   |-- models.py
+|   |-- mutagen_tags.py
+|   |-- files.py
+|   `-- naming.py
+`-- exceptions.py
+```

audio_media_utils-0.1.0/README.md

@@ -0,0 +1,30 @@
+# audio_media_utils
+
+Utilities for audio-oriented download workflows and simple metadata editing.
+
+This repository is intentionally focused on reusable domain helpers for:
+
+- YouTube and `yt-dlp` download helpers
+- playlist detection and expansion
+- simple audio metadata reads and writes with `mutagen`
+- filename and path helpers for tagged audio files
+
+It does not include worker loops, logging infrastructure, Docker wiring, or service-specific orchestration.
+
+## Planned package layout
+
+```txt
+src/audio_media_utils/
+|-- youtube/
+|   |-- models.py
+|   |-- urls.py
+|   |-- ytdlp_runner.py
+|   |-- playlists.py
+|   `-- downloads.py
+|-- audio/
+|   |-- models.py
+|   |-- mutagen_tags.py
+|   |-- files.py
+|   `-- naming.py
+`-- exceptions.py
+```

audio_media_utils-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "audio-media-utils"
+version = "0.1.0"
+description = "Utilities for yt-dlp audio downloads and simple mutagen metadata workflows"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "mutagen>=1.47,<2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=9,<10",
+    "pytest-cov>=6,<7",
+    "sphinx>=8,<9",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

audio_media_utils-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

audio_media_utils-0.1.0/src/audio_media_utils/__init__.py

@@ -0,0 +1,6 @@
+"""Reusable helpers for audio downloads and metadata workflows."""
+
+from audio_media_utils.audio.models import AudioTags
+from audio_media_utils.youtube.models import DownloadOptions, DownloadResult, PlaylistEntry, VideoMetadata
+
+__all__ = [s for s in dir() if not s.startswith("_")]

audio_media_utils-0.1.0/src/audio_media_utils/audio/__init__.py

@@ -0,0 +1,7 @@
+"""Helpers for audio metadata and file naming."""
+
+from audio_media_utils.audio.models import AudioTags
+from audio_media_utils.audio.mutagen_tags import read_tags, update_tags, write_tags
+from audio_media_utils.audio.naming import build_music_path, sanitize_path_component
+
+__all__ = [s for s in dir() if not s.startswith("_")]

audio_media_utils-0.1.0/src/audio_media_utils/audio/files.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+"""Helpers for file-level audio operations."""
+
+from pathlib import Path
+from mutagen import File
+
+
+def read_audio_duration(path: str | Path) -> float:
+    """Return audio duration in seconds."""
+    file_path = Path(path)
+    audio = File(file_path)
+    if audio is None or not hasattr(audio, 'info') or audio.info is None:
+        raise ValueError(f"Unable to read duration from {file_path}")
+
+    return float(audio.info.length)

audio_media_utils-0.1.0/src/audio_media_utils/audio/models.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+"""Typed models used by the audio helpers."""
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class AudioTags:
+    """Normalized tag container for simple mutagen write operations."""
+
+    artist: str | None = None
+    albumartist: str | None = None
+    album: str | None = None
+    title: str | None = None
+    tracknumber: int | None = None
+    date: str | None = None
+    genre: list[str] = field(default_factory=list)
+    musicbrainz_trackid: str | None = None
+    musicbrainz_albumid: str | None = None

audio_media_utils-0.1.0/src/audio_media_utils/audio/mutagen_tags.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+"""Simple mutagen helpers for reading and writing tags."""
+
+from pathlib import Path
+from mutagen import File
+from audio_media_utils.audio.models import AudioTags
+
+
+def read_tags(path: str | Path) -> dict[str, list[str]]:
+    """Read easy tags from an audio file when available."""
+    file_path = Path(path)
+    audio = File(file_path, easy=True)
+    if audio is None or audio.tags is None:
+        return {}
+
+    return {
+        str(key): [str(item) for item in value]
+        for key, value in audio.tags.items()
+    }
+
+
+def write_tags(path: str | Path, tags: AudioTags) -> None:
+    """Overwrite common audio tags with normalized values."""
+    file_path = Path(path)
+    audio = File(file_path, easy=True)
+    if audio is None:
+        raise ValueError(f"No compatible mutagen handler for {file_path.suffix!r}")
+
+    if audio.tags is None and hasattr(audio, 'add_tags'):
+        audio.add_tags()
+
+    if audio.tags is None:
+        raise ValueError(f"Unable to initialize metadata container for {file_path}")
+
+    assignments: dict[str, list[str]] = {}
+    if tags.artist:
+        assignments['artist'] = [tags.artist]
+    if tags.albumartist:
+        assignments['albumartist'] = [tags.albumartist]
+    if tags.album:
+        assignments['album'] = [tags.album]
+    if tags.title:
+        assignments['title'] = [tags.title]
+    if tags.tracknumber is not None:
+        assignments['tracknumber'] = [str(tags.tracknumber)]
+    if tags.date:
+        assignments['date'] = [tags.date]
+    if tags.genre:
+        assignments['genre'] = list(tags.genre)
+    if tags.musicbrainz_trackid:
+        assignments['musicbrainz_trackid'] = [tags.musicbrainz_trackid]
+    if tags.musicbrainz_albumid:
+        assignments['musicbrainz_albumid'] = [tags.musicbrainz_albumid]
+
+    audio.delete()
+    for key, value in assignments.items():
+        audio.tags[key] = value
+    audio.save()
+
+
+def update_tags(path: str | Path, tags: AudioTags) -> None:
+    """Alias kept for a friendlier public API while bootstrapping the package."""
+    write_tags(path, tags)

audio_media_utils-0.1.0/src/audio_media_utils/audio/naming.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+"""Helpers for building safe music file paths."""
+
+import re
+import unicodedata
+from pathlib import Path
+
+_INVALID_PATH_CHARS = re.compile(r'[<>:"/\\|?*\n\r\t]+')
+_MULTISPACE_CHARS = re.compile(r'\s+')
+_MULTI_UNDERSCORES = re.compile(r'_+')
+
+
+def sanitize_path_component(value: str) -> str:
+    """Normalize a filesystem path component for music libraries."""
+    normalized = unicodedata.normalize('NFKC', value)
+    cleaned = _INVALID_PATH_CHARS.sub('_', normalized)
+    cleaned = _MULTISPACE_CHARS.sub(' ', cleaned)
+    cleaned = _MULTI_UNDERSCORES.sub('_', cleaned)
+    cleaned = cleaned.strip(' .')
+    return cleaned or 'Unknown'
+
+
+def build_music_path(
+    base_dir: str | Path,
+    *,
+    artist: str,
+    album: str,
+    title: str,
+    track_number: int | None = None,
+    suffix: str = '.mp3',
+) -> Path:
+    """Build a normalized destination path for a tagged music file."""
+    root = Path(base_dir)
+    safe_artist = sanitize_path_component(artist)
+    safe_album = sanitize_path_component(album)
+    safe_title = sanitize_path_component(title)
+    prefix = f'{track_number:02d} - ' if track_number is not None else ''
+    return root / safe_artist / safe_album / f'{prefix}{safe_title}{suffix}'

audio_media_utils-0.1.0/src/audio_media_utils/exceptions.py

@@ -0,0 +1,13 @@
+"""Custom exceptions used across the package."""
+
+
+class AudioMediaUtilsError(Exception):
+    """Base exception for the package."""
+
+
+class YtDlpError(AudioMediaUtilsError):
+    """Raised when a yt-dlp command fails."""
+
+
+class MetadataError(AudioMediaUtilsError):
+    """Raised when audio metadata cannot be processed."""

audio_media_utils-0.1.0/src/audio_media_utils/youtube/__init__.py

@@ -0,0 +1,7 @@
+"""Helpers for YouTube URL inspection and yt-dlp workflows."""
+
+from audio_media_utils.youtube.downloads import download_audio
+from audio_media_utils.youtube.playlists import expand_playlist
+from audio_media_utils.youtube.urls import extract_playlist_id, extract_video_id, is_playlist_url, is_video_url
+
+__all__ = [s for s in dir() if not s.startswith("_")]

audio_media_utils-0.1.0/src/audio_media_utils/youtube/downloads.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+"""Helpers for audio downloads through yt-dlp."""
+
+from audio_media_utils.youtube.models import DownloadOptions, DownloadResult
+
+
+def download_audio(url: str, *, options: DownloadOptions) -> DownloadResult:
+    """Download audio from ``url`` using the provided options.
+
+    This is a placeholder implementation that will be filled in next.
+    """
+    return DownloadResult(success=False, url=url, error_reason="not_implemented")

audio_media_utils-0.1.0/src/audio_media_utils/youtube/models.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+"""Typed models used by the YouTube helpers."""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class PlaylistEntry:
+    """Single entry extracted from a playlist."""
+
+    video_id: str
+    url: str
+    title: str | None = None
+
+
+@dataclass(frozen=True)
+class VideoMetadata:
+    """Subset of metadata commonly returned by yt-dlp."""
+
+    video_id: str | None
+    url: str
+    title: str | None = None
+    upload_date: str | None = None
+    duration_seconds: int | None = None
+    live_status: str | None = None
+    was_live: bool = False
+    release_timestamp: int | None = None
+
+
+@dataclass(frozen=True)
+class DownloadOptions:
+    """Options used when downloading audio with yt-dlp."""
+
+    output_template: str
+    audio_format: str = "mp3"
+    audio_quality: str | None = None
+    archive_file: Path | None = None
+    cookies_file: Path | None = None
+    timeout_seconds: int = 120
+    extra_args: list[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class DownloadResult:
+    """Result of a download attempt."""
+
+    success: bool
+    url: str
+    file_path: Path | None = None
+    title: str | None = None
+    already_downloaded: bool = False
+    stdout: str = ""
+    stderr: str = ""
+    error_reason: str | None = None

audio_media_utils-0.1.0/src/audio_media_utils/youtube/playlists.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+"""Helpers for playlist inspection and expansion."""
+
+from audio_media_utils.youtube.models import PlaylistEntry
+
+
+def expand_playlist(url: str, *, flat: bool = True) -> list[PlaylistEntry]:
+    """Expand a playlist URL into entries.
+
+    This is a placeholder implementation that will be filled in next.
+    """
+    _ = (url, flat)
+    return []

audio_media_utils-0.1.0/src/audio_media_utils/youtube/urls.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+"""URL helpers for YouTube video and playlist links."""
+
+from urllib.parse import parse_qs, urlparse
+
+
+def is_playlist_url(url: str) -> bool:
+    """Return whether ``url`` looks like a YouTube playlist URL."""
+    parsed = urlparse(url)
+    query = parse_qs(parsed.query)
+    return parsed.path == "/playlist" or "list" in query
+
+
+def is_video_url(url: str) -> bool:
+    """Return whether ``url`` looks like a YouTube video URL."""
+    parsed = urlparse(url)
+    query = parse_qs(parsed.query)
+    return parsed.path == "/watch" and "v" in query
+
+
+def extract_video_id(url: str) -> str | None:
+    """Extract the ``v`` parameter from a YouTube watch URL."""
+    parsed = urlparse(url)
+    return parse_qs(parsed.query).get("v", [None])[0]
+
+
+def extract_playlist_id(url: str) -> str | None:
+    """Extract the ``list`` parameter from a YouTube playlist URL."""
+    parsed = urlparse(url)
+    return parse_qs(parsed.query).get("list", [None])[0]

audio_media_utils-0.1.0/src/audio_media_utils/youtube/ytdlp_runner.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+"""Thin subprocess wrapper around yt-dlp."""
+
+import subprocess
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class YtDlpCommandResult:
+    """Raw result of a yt-dlp invocation."""
+
+    returncode: int
+    stdout: str
+    stderr: str
+    reason: str | None = None
+
+
+def run_ytdlp(command: list[str], timeout_seconds: int) -> YtDlpCommandResult:
+    """Run a yt-dlp command and normalize timeout and OS errors."""
+    try:
+        result = subprocess.run(
+            command,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            timeout=timeout_seconds,
+        )
+    except subprocess.TimeoutExpired as error:
+        return YtDlpCommandResult(
+            returncode=-1,
+            stdout=error.stdout or "",
+            stderr=error.stderr or "",
+            reason="timeout",
+        )
+    except OSError as error:
+        return YtDlpCommandResult(
+            returncode=-1,
+            stdout="",
+            stderr=str(error),
+            reason="os_error",
+        )
+
+    return YtDlpCommandResult(
+        returncode=result.returncode,
+        stdout=result.stdout,
+        stderr=result.stderr,
+    )

audio_media_utils-0.1.0/src/audio_media_utils.egg-info/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: audio-media-utils
+Version: 0.1.0
+Summary: Utilities for yt-dlp audio downloads and simple mutagen metadata workflows
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: mutagen<2.0,>=1.47
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=9; extra == "dev"
+Requires-Dist: pytest-cov<7,>=6; extra == "dev"
+Requires-Dist: sphinx<9,>=8; extra == "dev"
+
+# audio_media_utils
+
+Utilities for audio-oriented download workflows and simple metadata editing.
+
+This repository is intentionally focused on reusable domain helpers for:
+
+- YouTube and `yt-dlp` download helpers
+- playlist detection and expansion
+- simple audio metadata reads and writes with `mutagen`
+- filename and path helpers for tagged audio files
+
+It does not include worker loops, logging infrastructure, Docker wiring, or service-specific orchestration.
+
+## Planned package layout
+
+```txt
+src/audio_media_utils/
+|-- youtube/
+|   |-- models.py
+|   |-- urls.py
+|   |-- ytdlp_runner.py
+|   |-- playlists.py
+|   `-- downloads.py
+|-- audio/
+|   |-- models.py
+|   |-- mutagen_tags.py
+|   |-- files.py
+|   `-- naming.py
+`-- exceptions.py
+```

audio_media_utils-0.1.0/src/audio_media_utils.egg-info/SOURCES.txt

@@ -0,0 +1,26 @@
+README.md
+pyproject.toml
+src/audio_media_utils/__init__.py
+src/audio_media_utils/exceptions.py
+src/audio_media_utils.egg-info/PKG-INFO
+src/audio_media_utils.egg-info/SOURCES.txt
+src/audio_media_utils.egg-info/dependency_links.txt
+src/audio_media_utils.egg-info/requires.txt
+src/audio_media_utils.egg-info/top_level.txt
+src/audio_media_utils/audio/__init__.py
+src/audio_media_utils/audio/files.py
+src/audio_media_utils/audio/models.py
+src/audio_media_utils/audio/mutagen_tags.py
+src/audio_media_utils/audio/naming.py
+src/audio_media_utils/youtube/__init__.py
+src/audio_media_utils/youtube/downloads.py
+src/audio_media_utils/youtube/models.py
+src/audio_media_utils/youtube/playlists.py
+src/audio_media_utils/youtube/urls.py
+src/audio_media_utils/youtube/ytdlp_runner.py
+tests/test_audio_files.py
+tests/test_audio_mutagen_tags.py
+tests/test_audio_naming.py
+tests/test_exceptions.py
+tests/test_youtube_urls.py
+tests/test_ytdlp_runner.py

audio_media_utils-0.1.0/src/audio_media_utils.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

audio_media_utils-0.1.0/src/audio_media_utils.egg-info/requires.txt

@@ -0,0 +1,6 @@
+mutagen<2.0,>=1.47
+
+[dev]
+pytest<10,>=9
+pytest-cov<7,>=6
+sphinx<9,>=8

audio_media_utils-0.1.0/src/audio_media_utils.egg-info/top_level.txt

@@ -0,0 +1 @@
+audio_media_utils

audio_media_utils-0.1.0/tests/test_audio_files.py

@@ -0,0 +1,27 @@
+from types import SimpleNamespace
+
+import pytest
+
+from audio_media_utils.audio.files import read_audio_duration
+
+
+def test_read_audio_duration_returns_length(monkeypatch, tmp_path) -> None:
+    audio_file = tmp_path / 'song.mp3'
+    audio_file.write_bytes(b'data')
+
+    def _fake_file(path):
+        return SimpleNamespace(info=SimpleNamespace(length=123.45))
+
+    monkeypatch.setattr('audio_media_utils.audio.files.File', _fake_file)
+
+    assert read_audio_duration(audio_file) == 123.45
+
+
+def test_read_audio_duration_raises_for_missing_metadata(monkeypatch, tmp_path) -> None:
+    audio_file = tmp_path / 'song.mp3'
+    audio_file.write_bytes(b'data')
+
+    monkeypatch.setattr('audio_media_utils.audio.files.File', lambda path: None)
+
+    with pytest.raises(ValueError, match='Unable to read duration'):
+        read_audio_duration(audio_file)

audio_media_utils-0.1.0/tests/test_audio_mutagen_tags.py

@@ -0,0 +1,135 @@
+import pytest
+
+from audio_media_utils.audio.models import AudioTags
+from audio_media_utils.audio.mutagen_tags import read_tags, update_tags, write_tags
+
+
+class _FakeAudio:
+    def __init__(self, tags=None, allow_add_tags: bool = True) -> None:
+        self.tags = tags
+        self._allow_add_tags = allow_add_tags
+        self.delete_called = False
+        self.save_called = False
+
+    def add_tags(self) -> None:
+        if self._allow_add_tags:
+            self.tags = {}
+
+    def delete(self) -> None:
+        self.delete_called = True
+        self.tags = {}
+
+    def save(self) -> None:
+        self.save_called = True
+
+
+class _FakeAudioWithoutAddTags:
+    def __init__(self) -> None:
+        self.tags = None
+
+
+def test_read_tags_returns_empty_dict_when_handler_is_missing(monkeypatch, tmp_path) -> None:
+    audio_file = tmp_path / 'song.mp3'
+    audio_file.write_bytes(b'data')
+
+    monkeypatch.setattr('audio_media_utils.audio.mutagen_tags.File', lambda path, easy=True: None)
+
+    assert read_tags(audio_file) == {}
+
+
+def test_read_tags_returns_normalized_string_mapping(monkeypatch, tmp_path) -> None:
+    audio_file = tmp_path / 'song.mp3'
+    audio_file.write_bytes(b'data')
+
+    fake_audio = _FakeAudio(tags={'artist': ['Artist'], 'tracknumber': [3]})
+    monkeypatch.setattr('audio_media_utils.audio.mutagen_tags.File', lambda path, easy=True: fake_audio)
+
+    assert read_tags(audio_file) == {'artist': ['Artist'], 'tracknumber': ['3']}
+
+
+def test_write_tags_overwrites_common_fields(monkeypatch, tmp_path) -> None:
+    audio_file = tmp_path / 'song.mp3'
+    audio_file.write_bytes(b'data')
+
+    fake_audio = _FakeAudio(tags={'artist': ['Old']})
+    monkeypatch.setattr('audio_media_utils.audio.mutagen_tags.File', lambda path, easy=True: fake_audio)
+
+    write_tags(
+        audio_file,
+        AudioTags(
+            artist='Artist',
+            albumartist='Album Artist',
+            album='Album',
+            title='Song',
+            tracknumber=7,
+            date='2024',
+            genre=['Rock'],
+            musicbrainz_trackid='track-id',
+            musicbrainz_albumid='album-id',
+        ),
+    )
+
+    assert fake_audio.delete_called is True
+    assert fake_audio.save_called is True
+    assert fake_audio.tags == {
+        'artist': ['Artist'],
+        'albumartist': ['Album Artist'],
+        'album': ['Album'],
+        'title': ['Song'],
+        'tracknumber': ['7'],
+        'date': ['2024'],
+        'genre': ['Rock'],
+        'musicbrainz_trackid': ['track-id'],
+        'musicbrainz_albumid': ['album-id'],
+    }
+
+
+def test_write_tags_initializes_tags_when_missing(monkeypatch, tmp_path) -> None:
+    audio_file = tmp_path / 'song.mp3'
+    audio_file.write_bytes(b'data')
+
+    fake_audio = _FakeAudio(tags=None)
+    monkeypatch.setattr('audio_media_utils.audio.mutagen_tags.File', lambda path, easy=True: fake_audio)
+
+    write_tags(audio_file, AudioTags(artist='Artist'))
+
+    assert fake_audio.tags == {'artist': ['Artist']}
+
+
+def test_write_tags_raises_when_no_handler_exists(monkeypatch, tmp_path) -> None:
+    audio_file = tmp_path / 'song.unknown'
+    audio_file.write_bytes(b'data')
+
+    monkeypatch.setattr('audio_media_utils.audio.mutagen_tags.File', lambda path, easy=True: None)
+
+    with pytest.raises(ValueError, match='No compatible mutagen handler'):
+        write_tags(audio_file, AudioTags(artist='Artist'))
+
+
+def test_write_tags_raises_when_tag_container_cannot_be_initialized(monkeypatch, tmp_path) -> None:
+    audio_file = tmp_path / 'song.mp3'
+    audio_file.write_bytes(b'data')
+
+    fake_audio = _FakeAudioWithoutAddTags()
+    monkeypatch.setattr('audio_media_utils.audio.mutagen_tags.File', lambda path, easy=True: fake_audio)
+
+    with pytest.raises(ValueError, match='Unable to initialize metadata container'):
+        write_tags(audio_file, AudioTags(artist='Artist'))
+
+
+def test_update_tags_delegates_to_write_tags(monkeypatch, tmp_path) -> None:
+    audio_file = tmp_path / 'song.mp3'
+    audio_file.write_bytes(b'data')
+
+    captured = {}
+
+    def _fake_write_tags(path, tags):
+        captured['path'] = path
+        captured['tags'] = tags
+
+    monkeypatch.setattr('audio_media_utils.audio.mutagen_tags.write_tags', _fake_write_tags)
+
+    tags = AudioTags(artist='Artist')
+    update_tags(audio_file, tags)
+
+    assert captured == {'path': audio_file, 'tags': tags}

audio_media_utils-0.1.0/tests/test_audio_naming.py

@@ -0,0 +1,35 @@
+from pathlib import Path
+
+from audio_media_utils.audio.naming import build_music_path, sanitize_path_component
+
+
+def test_sanitize_path_component_normalizes_invalid_characters() -> None:
+    assert sanitize_path_component(' AC/DC: Live? ') == 'AC_DC_ Live_'
+
+
+def test_sanitize_path_component_returns_unknown_for_empty_result() -> None:
+    assert sanitize_path_component('   ...   ') == 'Unknown'
+
+
+def test_build_music_path_includes_track_prefix_when_present() -> None:
+    path = build_music_path(
+        Path('library'),
+        artist='Artist',
+        album='Album',
+        title='Song',
+        track_number=3,
+        suffix='.flac',
+    )
+
+    assert path == Path('library/Artist/Album/03 - Song.flac')
+
+
+def test_build_music_path_omits_track_prefix_when_missing() -> None:
+    path = build_music_path(
+        Path('library'),
+        artist='Artist',
+        album='Album',
+        title='Song',
+    )
+
+    assert path == Path('library/Artist/Album/Song.mp3')

audio_media_utils-0.1.0/tests/test_exceptions.py

@@ -0,0 +1,22 @@
+from audio_media_utils.exceptions import AudioMediaUtilsError, MetadataError, YtDlpError
+
+
+def test_audio_media_utils_error_is_package_base_exception() -> None:
+    error = AudioMediaUtilsError("base error")
+
+    assert str(error) == "base error"
+    assert isinstance(error, Exception)
+
+
+def test_ytdlp_error_inherits_from_package_base_exception() -> None:
+    error = YtDlpError("yt-dlp failed")
+
+    assert str(error) == "yt-dlp failed"
+    assert isinstance(error, AudioMediaUtilsError)
+
+
+def test_metadata_error_inherits_from_package_base_exception() -> None:
+    error = MetadataError("metadata failed")
+
+    assert str(error) == "metadata failed"
+    assert isinstance(error, AudioMediaUtilsError)

audio_media_utils-0.1.0/tests/test_youtube_urls.py

@@ -0,0 +1,60 @@
+from audio_media_utils.youtube.downloads import download_audio
+from audio_media_utils.youtube.models import DownloadOptions
+from audio_media_utils.youtube.playlists import expand_playlist
+from audio_media_utils.youtube.urls import (
+    extract_playlist_id,
+    extract_video_id,
+    is_playlist_url,
+    is_video_url,
+)
+
+
+def test_is_playlist_url_detects_standard_playlist_url() -> None:
+    assert is_playlist_url('https://www.youtube.com/playlist?list=PL123') is True
+
+
+def test_is_playlist_url_detects_watch_url_with_list_parameter() -> None:
+    assert is_playlist_url('https://www.youtube.com/watch?v=abc123&list=PL123') is True
+
+
+def test_is_playlist_url_rejects_plain_video_url() -> None:
+    assert is_playlist_url('https://www.youtube.com/watch?v=abc123') is False
+
+
+def test_is_video_url_detects_watch_url() -> None:
+    assert is_video_url('https://www.youtube.com/watch?v=abc123') is True
+
+
+def test_is_video_url_rejects_playlist_only_url() -> None:
+    assert is_video_url('https://www.youtube.com/playlist?list=PL123') is False
+
+
+def test_extract_video_id_returns_identifier() -> None:
+    assert extract_video_id('https://www.youtube.com/watch?v=abc123&list=PL123') == 'abc123'
+
+
+def test_extract_video_id_returns_none_when_missing() -> None:
+    assert extract_video_id('https://www.youtube.com/playlist?list=PL123') is None
+
+
+def test_extract_playlist_id_returns_identifier() -> None:
+    assert extract_playlist_id('https://www.youtube.com/playlist?list=PL123') == 'PL123'
+
+
+def test_extract_playlist_id_returns_none_when_missing() -> None:
+    assert extract_playlist_id('https://www.youtube.com/watch?v=abc123') is None
+
+
+def test_expand_playlist_placeholder_returns_empty_list() -> None:
+    assert expand_playlist('https://www.youtube.com/playlist?list=PL123') == []
+
+
+def test_download_audio_placeholder_returns_not_implemented_result() -> None:
+    result = download_audio(
+        'https://www.youtube.com/watch?v=abc123',
+        options=DownloadOptions(output_template='%(title)s.%(ext)s'),
+    )
+
+    assert result.success is False
+    assert result.url == 'https://www.youtube.com/watch?v=abc123'
+    assert result.error_reason == 'not_implemented'

audio_media_utils-0.1.0/tests/test_ytdlp_runner.py

@@ -0,0 +1,49 @@
+import subprocess
+
+from audio_media_utils.youtube.ytdlp_runner import YtDlpCommandResult, run_ytdlp
+
+
+class _CompletedProcess:
+    def __init__(self, returncode: int, stdout: str, stderr: str) -> None:
+        self.returncode = returncode
+        self.stdout = stdout
+        self.stderr = stderr
+
+
+def test_run_ytdlp_returns_normalized_result_on_success(monkeypatch) -> None:
+    def _fake_run(*args, **kwargs):
+        return _CompletedProcess(returncode=0, stdout='ok', stderr='')
+
+    monkeypatch.setattr(subprocess, 'run', _fake_run)
+
+    result = run_ytdlp(['yt-dlp', '--version'], timeout_seconds=10)
+
+    assert result == YtDlpCommandResult(returncode=0, stdout='ok', stderr='', reason=None)
+
+
+def test_run_ytdlp_returns_timeout_result(monkeypatch) -> None:
+    def _fake_run(*args, **kwargs):
+        raise subprocess.TimeoutExpired(cmd='yt-dlp', timeout=10, output='partial', stderr='late stderr')
+
+    monkeypatch.setattr(subprocess, 'run', _fake_run)
+
+    result = run_ytdlp(['yt-dlp', '--version'], timeout_seconds=10)
+
+    assert result.returncode == -1
+    assert result.stdout == 'partial'
+    assert result.stderr == 'late stderr'
+    assert result.reason == 'timeout'
+
+
+def test_run_ytdlp_returns_os_error_result(monkeypatch) -> None:
+    def _fake_run(*args, **kwargs):
+        raise OSError('yt-dlp not found')
+
+    monkeypatch.setattr(subprocess, 'run', _fake_run)
+
+    result = run_ytdlp(['yt-dlp', '--version'], timeout_seconds=10)
+
+    assert result.returncode == -1
+    assert result.stdout == ''
+    assert result.stderr == 'yt-dlp not found'
+    assert result.reason == 'os_error'