audiometa-python 0.6.0__py3-none-any.whl

audiometa/utils/tool_path_resolver.py

@@ -0,0 +1,135 @@
+"""Utility to resolve paths to pinned versions of external tools."""
+
+import platform
+import subprocess
+from pathlib import Path
+
+from audiometa.utils.os_dependencies_checker.config import load_dependencies_pinned_versions
+
+
+def _get_os_type() -> str | None:
+    """Detect OS type."""
+    system = platform.system().lower()
+    if system == "linux":
+        return "ubuntu"
+    if system == "darwin":
+        return "macos"
+    if system == "windows":
+        return "windows"
+    return None
+
+
+def get_tool_path(tool_name: str) -> str:
+    """Get the path to the pinned version of a tool, or fallback to tool name.
+
+    This function resolves the absolute path to the pinned version's executable
+    if available, ensuring the correct version is used. Falls back to the tool
+    name if pinned version path cannot be resolved (relies on PATH).
+
+    Args:
+        tool_name: Name of the tool (e.g., "flac", "ffprobe", "metaflac")
+
+    Returns:
+        Absolute path to pinned version executable, or tool name if not found
+    """
+    pinned_versions = load_dependencies_pinned_versions()
+    if not pinned_versions:
+        return tool_name
+
+    os_type = _get_os_type()
+    if not os_type:
+        return tool_name
+
+    # Map tool names to Homebrew package names
+    brew_package_map = {
+        "ffmpeg": "ffmpeg",
+        "ffprobe": "ffmpeg",  # ffprobe comes from ffmpeg package
+        "flac": "flac",
+        "metaflac": "flac",  # metaflac comes from flac package
+        "mediainfo": "media-info",
+        "id3v2": "id3v2",
+        "bwfmetaedit": "bwfmetaedit",
+        "exiftool": "exiftool",
+    }
+
+    brew_package = brew_package_map.get(tool_name)
+    if not brew_package:
+        return tool_name
+
+    # Get pinned version for this OS
+    if brew_package not in pinned_versions:
+        return tool_name
+
+    versions = pinned_versions[brew_package]
+    pinned_version = versions.get(os_type)
+    if not pinned_version:
+        return tool_name
+
+    # Resolve path based on OS
+    if os_type == "macos":
+        try:
+            brew_prefix_result = subprocess.run(
+                ["brew", "--prefix"],
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+            if brew_prefix_result.stdout:
+                brew_prefix = brew_prefix_result.stdout.strip()
+
+                # Special handling for ffmpeg/ffprobe (keg-only, versioned)
+                if brew_package == "ffmpeg":
+                    # ffmpeg@7 is keg-only, check versioned path
+                    tool_path = Path(brew_prefix) / "opt" / f"ffmpeg@{pinned_version}" / "bin" / tool_name
+                    if tool_path.exists() and tool_path.is_file():
+                        return str(tool_path)
+
+                # For other tools, check Cellar (exact version) and opt (symlink)
+                # Check Cellar first (exact version path)
+                cellar_path = Path(brew_prefix) / "Cellar" / brew_package / pinned_version / "bin" / tool_name
+                if cellar_path.exists() and cellar_path.is_file():
+                    return str(cellar_path)
+
+                # Check opt (symlink, usually points to latest)
+                opt_path = Path(brew_prefix) / "opt" / brew_package / "bin" / tool_name
+                if opt_path.exists() and opt_path.is_file():
+                    # Verify it's the pinned version
+                    try:
+                        result = subprocess.run(
+                            [str(opt_path), "--version" if tool_name != "ffprobe" else "-version"],
+                            capture_output=True,
+                            text=True,
+                            check=False,
+                        )
+                        output = result.stdout + result.stderr
+                        # Check if version matches pinned version
+                        import re
+
+                        if tool_name in ["flac", "metaflac"]:
+                            match = re.search(r"(\d+\.\d+\.\d+)", output)
+                        elif tool_name == "mediainfo":
+                            match = re.search(r"(\d+\.\d+(?:\.\d+)?)", output)
+                        elif tool_name in ["id3v2", "bwfmetaedit"]:
+                            match = re.search(r"(\d+\.\d+\.\d+)", output)
+                        elif tool_name == "exiftool":
+                            match = re.search(r"(\d+\.\d+(?:\.\d+)?)", output)
+                        else:
+                            match = re.search(r"(\d+\.\d+\.\d+)", output)
+
+                        if match:
+                            running_version = match.group(1)
+                            # Normalize for comparison
+                            pinned_normalized = pinned_version.split("_")[0]
+                            running_normalized = running_version.split("_")[0]
+                            if running_normalized == pinned_normalized or running_normalized.startswith(
+                                pinned_normalized + "."
+                            ):
+                                return str(opt_path)
+                    except Exception:
+                        pass
+
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            pass
+
+    # Fallback: return tool name (will use PATH)
+    return tool_name

audiometa/utils/types.py

@@ -0,0 +1,82 @@
+"""Type definitions for audio metadata handling.
+
+This module contains type aliases and enums used throughout the application for representing raw and unified metadata
+values.
+"""
+
+from collections.abc import MutableMapping
+from enum import Enum
+from typing import Any, TypedDict
+
+from .unified_metadata_key import UnifiedMetadataKey
+
+
+class RawMetadataKey(str, Enum):
+    """Enumeration of raw metadata keys."""
+
+    def __str__(self) -> str:
+        """Return string representation of the key."""
+        return str(self.value)
+
+
+"""
+Raw metadata value can be none (when not set), string (title), integer (rating), float(BPM) or list[str] (artists
+names).
+"""
+UnifiedMetadataValue = int | float | str | list[str] | None
+RawMetadataValue = list[int] | list[float] | list[str] | None
+RawMetadataDict = dict[RawMetadataKey, RawMetadataValue]
+UnifiedMetadata = MutableMapping[UnifiedMetadataKey, UnifiedMetadataValue]
+
+
+class FormatPriorities(TypedDict):
+    """Type for format priorities information."""
+
+    file_extension: str
+    reading_order: list[str]
+    writing_format: str | None
+
+
+class TechnicalInfo(TypedDict):
+    """Type for technical audio information."""
+
+    duration_seconds: float
+    bitrate_bps: int
+    sample_rate_hz: int
+    channels: int
+    file_size_bytes: int
+    file_extension: str
+    audio_format_name: str
+    is_flac_md5_valid: bool | None
+
+
+class HeaderInfo(TypedDict):
+    """Type for format-specific header information."""
+
+    present: bool
+    version: str | None
+    size_bytes: int
+    position: int | None
+    flags: dict[str, Any]
+    extended_header: dict[str, Any]
+
+
+class RawMetadataInfo(TypedDict):
+    """Type for raw metadata information."""
+
+    raw_data: Any
+    parsed_fields: dict[str, Any]
+    frames: dict[str, Any]
+    comments: dict[str, Any]
+    chunk_structure: dict[str, Any]
+
+
+class FullMetadata(TypedDict):
+    """Type for comprehensive metadata returned by get_full_metadata."""
+
+    unified_metadata: UnifiedMetadata
+    technical_info: TechnicalInfo
+    metadata_format: dict[str, UnifiedMetadata]
+    headers: dict[str, HeaderInfo]
+    raw_metadata: dict[str, RawMetadataInfo]
+    format_priorities: FormatPriorities

audiometa/utils/unified_metadata_key.py

@@ -0,0 +1,87 @@
+"""Unified metadata keys for audio file metadata handling.
+
+This module defines the standardized keys used throughout the application for representing audio metadata in a unified
+format.
+"""
+
+from enum import Enum
+from typing import cast
+
+
+class UnifiedMetadataKey(str, Enum):
+    """Enumeration of unified metadata keys used for audio file metadata."""
+
+    TITLE = "title"
+    ARTISTS = "artists"
+    ALBUM = "album"
+    ALBUM_ARTISTS = "album_artists"
+    GENRES_NAMES = "genres_names"
+    RATING = "rating"
+    LANGUAGE = "language"
+    RELEASE_DATE = "release_date"
+    TRACK_NUMBER = "track_number"
+    DISC_NUMBER = "disc_number"
+    DISC_TOTAL = "disc_total"
+    BPM = "bpm"
+    COMPOSERS = "composer"
+    PUBLISHER = "publisher"
+    COPYRIGHT = "copyright"
+    UNSYNCHRONIZED_LYRICS = "unsynchronized_lyrics"
+    COMMENT = "comment"
+    REPLAYGAIN = "replaygain"
+    ARCHIVAL_LOCATION = "archival_location"
+    ISRC = "isrc"
+
+    def can_semantically_have_multiple_values(self) -> bool:
+        """Check if the metadata key can semantically have multiple values.
+
+        Returns:
+            True if the key can have multiple values, False otherwise.
+        """
+        # Fields that can contain multiple values (lists) - only semantically meaningful ones
+        multi_value_fields = {
+            UnifiedMetadataKey.ARTISTS,
+            UnifiedMetadataKey.ALBUM_ARTISTS,
+            UnifiedMetadataKey.GENRES_NAMES,
+            UnifiedMetadataKey.COMPOSERS,
+        }
+
+        result = self in multi_value_fields
+        if result and self.get_optional_type() != list[str]:
+            msg = f"Optional type for {self} is not list"
+            raise ValueError(msg)
+        return result
+
+    def get_optional_type(self) -> type[int | float | str | list[str]]:
+        """Get the optional type for the metadata key.
+
+        Returns:
+            The type of the metadata value.
+        """
+        app_metadata_keys_optional_types_map: dict[UnifiedMetadataKey, object] = {
+            UnifiedMetadataKey.TITLE: str,
+            UnifiedMetadataKey.ARTISTS: list[str],
+            UnifiedMetadataKey.ALBUM: str,
+            UnifiedMetadataKey.ALBUM_ARTISTS: list[str],
+            UnifiedMetadataKey.GENRES_NAMES: list[str],
+            UnifiedMetadataKey.RATING: int | float,
+            UnifiedMetadataKey.LANGUAGE: str,
+            UnifiedMetadataKey.RELEASE_DATE: str,
+            UnifiedMetadataKey.TRACK_NUMBER: str,  # Can be int or str
+            UnifiedMetadataKey.DISC_NUMBER: int,
+            UnifiedMetadataKey.DISC_TOTAL: int | None,
+            UnifiedMetadataKey.BPM: int,
+            UnifiedMetadataKey.COMPOSERS: list[str],
+            UnifiedMetadataKey.PUBLISHER: str,
+            UnifiedMetadataKey.COPYRIGHT: str,
+            UnifiedMetadataKey.UNSYNCHRONIZED_LYRICS: str,
+            UnifiedMetadataKey.COMMENT: str,
+            UnifiedMetadataKey.REPLAYGAIN: str,
+            UnifiedMetadataKey.ARCHIVAL_LOCATION: str,
+            UnifiedMetadataKey.ISRC: str,
+        }
+        result_type = app_metadata_keys_optional_types_map.get(self)
+        if not result_type:
+            msg = f"No optional type defined for {self}"
+            raise ValueError(msg)
+        return cast(type[int | float | str | list[str]], result_type)