audiometa-python 0.2.2__py3-none-any.whl

audiometa/utils/id3v1_genre_code_map.py

@@ -0,0 +1,205 @@
+"""Standard ID3v1 genre codes mapping.
+
+This is the complete standard genre map used by both ID3v1 and RIFF formats. Genres 0-79 are from the original ID3v1
+spec. Genres 80-125 were added by Winamp. Genres 126-147 were added by other players. Genres 148-191 were added in
+Winamp 5.6 (November 2010).
+"""
+
+ID3V1_GENRE_CODE_MAP = {
+    0: "Blues",
+    1: "Classic Rock",
+    2: "Country",
+    3: "Dance",
+    4: "Disco",
+    5: "Funk",
+    6: "Grunge",
+    7: "Hip-Hop",
+    8: "Jazz",
+    9: "Metal",
+    10: "New Age",
+    11: "Oldies",
+    12: "Other",
+    13: "Pop",
+    14: "R&B",
+    15: "Rap",
+    16: "Reggae",
+    17: "Rock",
+    18: "Techno",
+    19: "Industrial",
+    20: "Alternative",
+    21: "Ska",
+    22: "Death Metal",
+    23: "Pranks",
+    24: "Soundtrack",
+    25: "Euro-Techno",
+    26: "Ambient",
+    27: "Trip-Hop",
+    28: "Vocal",
+    29: "Jazz+Funk",
+    30: "Fusion",
+    31: "Trance",
+    32: "Classical",
+    33: "Instrumental",
+    34: "Acid",
+    35: "House",
+    36: "Game",
+    37: "Sound Clip",
+    38: "Gospel",
+    39: "Noise",
+    40: "Alternative Rock",
+    41: "Bass",
+    42: "Soul",
+    43: "Punk",
+    44: "Space",
+    45: "Meditative",
+    46: "Instrumental Pop",
+    47: "Instrumental Rock",
+    48: "Ethnic",
+    49: "Gothic",
+    50: "Darkwave",
+    51: "Techno-Industrial",
+    52: "Electronic",
+    53: "Pop-Folk",
+    54: "Eurodance",
+    55: "Dream",
+    56: "Southern Rock",
+    57: "Comedy",
+    58: "Cult",
+    59: "Gangsta",
+    60: "Top 40",
+    61: "Christian Rap",
+    62: "Pop/Funk",
+    63: "Jungle",
+    64: "Native US",
+    65: "Cabaret",
+    66: "New Wave",
+    67: "Psychedelic",
+    68: "Rave",
+    69: "Showtunes",
+    70: "Trailer",
+    71: "Lo-Fi",
+    72: "Tribal",
+    73: "Acid Punk",
+    74: "Acid Jazz",
+    75: "Polka",
+    76: "Retro",
+    77: "Musical",
+    78: "Rock & Roll",
+    79: "Hard Rock",
+    # Winamp extensions
+    80: "Folk",
+    81: "Folk-Rock",
+    82: "National Folk",
+    83: "Swing",
+    84: "Fast Fusion",
+    85: "Bebop",
+    86: "Latin",
+    87: "Revival",
+    88: "Celtic",
+    89: "Bluegrass",
+    90: "Avantgarde",
+    91: "Gothic Rock",
+    92: "Progressive Rock",
+    93: "Psychedelic Rock",
+    94: "Symphonic Rock",
+    95: "Slow Rock",
+    96: "Big Band",
+    97: "Chorus",
+    98: "Easy Listening",
+    99: "Acoustic",
+    100: "Humour",
+    101: "Speech",
+    102: "Chanson",
+    103: "Opera",
+    104: "Chamber Music",
+    105: "Sonata",
+    106: "Symphony",
+    107: "Booty Bass",
+    108: "Primus",
+    109: "Porn Groove",
+    110: "Satire",
+    111: "Slow Jam",
+    112: "Club",
+    113: "Tango",
+    114: "Samba",
+    115: "Folklore",
+    116: "Ballad",
+    117: "Power Ballad",
+    118: "Rhythmic Soul",
+    119: "Freestyle",
+    120: "Duet",
+    121: "Punk Rock",
+    122: "Drum Solo",
+    123: "A Cappella",
+    124: "Euro-House",
+    125: "Dance Hall",
+    # Other extensions
+    126: "Goa",
+    127: "Drum & Bass",
+    128: "Club-House",
+    129: "Hardcore",
+    130: "Terror",
+    131: "Indie",
+    132: "BritPop",
+    133: "Negerpunk",
+    134: "Polsk Punk",
+    135: "Beat",
+    136: "Christian Gangsta Rap",
+    137: "Heavy Metal",
+    138: "Black Metal",
+    139: "Crossover",
+    140: "Contemporary Christian",
+    141: "Christian Rock",
+    142: "Merengue",
+    143: "Salsa",
+    144: "Thrash Metal",
+    145: "Anime",
+    146: "JPop",
+    147: "Synthpop",
+    # Winamp 5.6 extensions (November 2010)
+    148: "Christmas",
+    149: "Art Rock",
+    150: "Baroque",
+    151: "Bhangra",
+    152: "Big Beat",
+    153: "Breakbeat",
+    154: "Chillout",
+    155: "Downtempo",
+    156: "Dub",
+    157: "EBM",
+    158: "Eclectic",
+    159: "Electro",
+    160: "Electroclash",
+    161: "Emo",
+    162: "Experimental",
+    163: "Garage",
+    164: "Global",
+    165: "IDM",
+    166: "Illbient",
+    167: "Industro-Goth",
+    168: "Jam Band",
+    169: "Krautrock",
+    170: "Leftfield",
+    171: "Lounge",
+    172: "Math Rock",
+    173: "New Romantic",
+    174: "Nu-Breakz",
+    175: "Post-Punk",
+    176: "Post-Rock",
+    177: "Psytrance",
+    178: "Shoegaze",
+    179: "Space Rock",
+    180: "Trop Rock",
+    181: "World Music",
+    182: "Neoclassical",
+    183: "Audiobook",
+    184: "Audio Theatre",
+    185: "Neue Deutsche Welle",
+    186: "Podcast",
+    187: "Indie Rock",
+    188: "G-Funk",
+    189: "Dubstep",
+    190: "Garage Rock",
+    191: "Psybient",
+    255: None,
+}

audiometa/utils/metadata_format.py

@@ -0,0 +1,31 @@
+"""Tag type constants for audio metadata handling.
+
+This module defines the supported metadata formats and their file extension priorities for reading and writing audio
+metadata across different file types.
+"""
+
+from enum import Enum
+
+
+class MetadataFormat(str, Enum):
+    """Enumeration of supported audio metadata formats."""
+
+    ID3V2 = "id3v2"
+    ID3V1 = "id3v1"
+    VORBIS = "vorbis"
+    RIFF = "riff"
+
+    @classmethod
+    def get_priorities(cls) -> dict[str, list["MetadataFormat"]]:
+        """Get tag format priorities for different file formats.
+
+        First tag format in each list has highest priority.
+
+        Returns:
+            dictionary mapping file extensions to ordered list of tag types
+        """
+        return {
+            ".flac": [cls.VORBIS, cls.ID3V2, cls.ID3V1],
+            ".mp3": [cls.ID3V2, cls.ID3V1],
+            ".wav": [cls.RIFF, cls.ID3V2, cls.ID3V1],
+        }

audiometa/utils/metadata_writing_strategy.py

@@ -0,0 +1,16 @@
+"""Metadata writing strategy constants for audio metadata handling."""
+
+from enum import Enum
+
+
+class MetadataWritingStrategy(str, Enum):
+    """Strategy for handling metadata when writing to files with existing metadata in other formats."""
+
+    SYNC = "sync"
+    """Write to native format and synchronize other metadata formats that are already present (default)"""
+
+    PRESERVE = "preserve"
+    """Write to native format only, preserve existing metadata in other formats."""
+
+    CLEANUP = "cleanup"
+    """Write to native format and remove all non-native metadata formats."""

audiometa/utils/os_dependencies_checker/__init__.py

@@ -0,0 +1,24 @@
+"""OS-specific dependency checkers for verifying system dependencies."""
+
+import platform
+
+from audiometa.utils.os_dependencies_checker.base import OsDependenciesChecker
+from audiometa.utils.os_dependencies_checker.macos import MacOSDependenciesChecker
+from audiometa.utils.os_dependencies_checker.ubuntu import UbuntuDependenciesChecker
+from audiometa.utils.os_dependencies_checker.windows import WindowsDependenciesChecker
+
+
+def get_dependencies_checker() -> OsDependenciesChecker | None:
+    """Get the appropriate OS-specific dependencies checker.
+
+    Returns:
+        OS-specific checker instance, or None if OS not supported
+    """
+    system = platform.system().lower()
+    if system == "darwin":
+        return MacOSDependenciesChecker()
+    if system == "linux":
+        return UbuntuDependenciesChecker()
+    if system == "windows":
+        return WindowsDependenciesChecker()
+    return None

audiometa/utils/os_dependencies_checker/base.py

@@ -0,0 +1,62 @@
+"""Base class for OS-specific dependency checkers."""
+
+from abc import ABC, abstractmethod
+
+
+class OsDependenciesChecker(ABC):
+    """Base class for OS-specific dependency checkers."""
+
+    @classmethod
+    @abstractmethod
+    def get_os_type(cls) -> str:
+        """Get OS type identifier."""
+
+    @abstractmethod
+    def check_tool_available(self, tool_name: str) -> bool:
+        """Check if a tool is available (in PATH or default locations).
+
+        Args:
+            tool_name: Name of the tool to check
+
+        Returns:
+            True if tool is available, False otherwise
+        """
+
+    @abstractmethod
+    def get_installed_version(self, package: str, expected_version: str | None = None) -> str | None:
+        """Get installed version of a package.
+
+        Args:
+            package: Package name
+            expected_version: Optional expected/pinned version
+
+        Returns:
+            Installed version string, or None if not found
+        """
+
+    @staticmethod
+    def _normalize_version(version: str) -> str:
+        """Normalize version string by removing revision suffix.
+
+        Args:
+            version: Version string (e.g., "7.1_4" or "1.5.0")
+
+        Returns:
+            Normalized version without revision suffix
+        """
+        return version.split("_")[0]
+
+    @staticmethod
+    def _versions_match(version1: str, version2: str) -> bool:
+        """Check if two version strings match (handles different precision).
+
+        Args:
+            version1: First version string
+            version2: Second version string
+
+        Returns:
+            True if versions match, False otherwise
+        """
+        v1_normalized = OsDependenciesChecker._normalize_version(version1)
+        v2_normalized = OsDependenciesChecker._normalize_version(version2)
+        return v1_normalized == v2_normalized or v2_normalized.startswith(v1_normalized + ".")

audiometa/utils/os_dependencies_checker/config.py

@@ -0,0 +1,51 @@
+"""Configuration loading for OS-specific dependency checkers."""
+
+import tomllib
+from pathlib import Path
+
+
+def load_dependencies_pinned_versions() -> dict[str, dict[str, str]] | None:
+    """Load pinned versions from system-dependencies.toml.
+
+    Returns:
+        Dictionary mapping tool names to OS-specific versions, or None if config not found
+    """
+    # Try to find system-dependencies.toml relative to this file
+    # This file is in audiometa/utils/os_dependencies_checker/, so go up to project root
+    config_path = Path(__file__).parent.parent.parent.parent / "system-dependencies.toml"
+
+    if not config_path.exists():
+        return None
+
+    try:
+        with config_path.open("rb") as f:
+            config = tomllib.load(f)
+
+        pinned_versions: dict[str, dict[str, str]] = {}
+
+        # Extract versions for each OS
+        for os_type in ["ubuntu", "macos", "windows"]:
+            if os_type not in config:
+                continue
+
+            os_config = config[os_type]
+            for tool in ["ffmpeg", "flac", "mediainfo", "id3v2", "bwfmetaedit", "exiftool"]:
+                if tool not in os_config:
+                    continue
+
+                version_value = os_config[tool]
+                # Handle both string values and dict values (for bwfmetaedit, exiftool on Windows)
+                if isinstance(version_value, str):
+                    version = version_value
+                elif isinstance(version_value, dict) and "pinned_version" in version_value:
+                    version = version_value["pinned_version"]
+                else:
+                    continue
+
+                if tool not in pinned_versions:
+                    pinned_versions[tool] = {}
+                pinned_versions[tool][os_type] = version
+    except Exception:
+        return None
+    else:
+        return pinned_versions

audiometa/utils/os_dependencies_checker/macos.py

@@ -0,0 +1,236 @@
+"""MacOS-specific dependency checker using Homebrew."""
+
+import re
+import subprocess
+from pathlib import Path
+
+from audiometa.utils.os_dependencies_checker.base import OsDependenciesChecker
+
+
+class MacOSDependenciesChecker(OsDependenciesChecker):
+    """MacOS-specific dependency checker using Homebrew."""
+
+    @classmethod
+    def get_os_type(cls) -> str:
+        return "macos"
+
+    def _get_brew_prefix(self) -> str | None:
+        """Get Homebrew prefix path."""
+        try:
+            result = subprocess.run(
+                ["brew", "--prefix"],
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+            if result.stdout:
+                return result.stdout.strip()
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            pass
+        return None
+
+    def _extract_version_from_output(self, output: str, tool_name: str) -> str | None:
+        """Extract version number from tool output."""
+        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)
+
+        return match.group(1) if match else None
+
+    def check_tool_available(self, tool_name: str) -> bool:
+        """Check if tool is available in PATH or Homebrew locations."""
+        brew_prefix = self._get_brew_prefix()
+        if brew_prefix:
+            tool_paths = [
+                f"{brew_prefix}/opt/{tool_name}/bin/{tool_name}",
+                f"{brew_prefix}/bin/{tool_name}",
+            ]
+            # Special handling for ffmpeg/ffprobe (keg-only packages)
+            if tool_name in ["ffmpeg", "ffprobe"]:
+                for version in ["7", "6", "5"]:
+                    tool_paths.insert(0, f"{brew_prefix}/opt/ffmpeg@{version}/bin/{tool_name}")
+
+            for tool_path in tool_paths:
+                if Path(tool_path).exists() and Path(tool_path).is_file():
+                    try:
+                        # exiftool uses -ver, not --version
+                        if tool_name == "exiftool":
+                            version_flag = "-ver"
+                        elif tool_name == "ffprobe":
+                            version_flag = "-version"
+                        else:
+                            version_flag = "--version"
+                        result = subprocess.run(
+                            [tool_path, version_flag],
+                            capture_output=True,
+                            text=True,
+                            check=False,
+                        )
+                        if result.stdout or result.stderr:
+                            return True
+                    except Exception:
+                        continue
+
+        # Fallback to PATH check
+        try:
+            # exiftool uses -ver, not --version
+            if tool_name == "exiftool":
+                version_flag = "-ver"
+            elif tool_name == "ffprobe":
+                version_flag = "-version"
+            else:
+                version_flag = "--version"
+            result = subprocess.run(
+                [tool_name, version_flag],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+            return bool(result.stdout or result.stderr)
+        except FileNotFoundError:
+            return False
+
+    def _get_ffmpeg_version(self) -> str | None:
+        """Get ffmpeg version (special handling for keg-only package)."""
+        ffprobe_paths = ["ffprobe"]
+        brew_prefix = self._get_brew_prefix()
+        if brew_prefix:
+            for version in ["7", "6", "5"]:
+                ffprobe_paths.append(f"{brew_prefix}/opt/ffmpeg@{version}/bin/ffprobe")
+
+        for ffprobe_path in ffprobe_paths:
+            try:
+                result = subprocess.run(
+                    [ffprobe_path, "-version"],
+                    capture_output=True,
+                    text=True,
+                    check=False,
+                )
+                if result.stdout or result.stderr:
+                    output = result.stdout + result.stderr
+                    match = re.search(r"version\s+(\d+(?:\.\d+)*)", output)
+                    if match:
+                        return match.group(1)
+            except FileNotFoundError:
+                continue
+        return None
+
+    def _get_running_version_from_executable(self, package: str, tool_name: str) -> str | None:
+        """Get version from tool executable."""
+        tool_paths = [tool_name]
+        brew_prefix = self._get_brew_prefix()
+        if brew_prefix:
+            tool_paths.extend(
+                [
+                    f"{brew_prefix}/opt/{package}/bin/{tool_name}",
+                    f"{brew_prefix}/bin/{tool_name}",
+                ]
+            )
+
+        for tool_path in tool_paths:
+            try:
+                # exiftool uses -ver, not --version
+                if tool_name == "exiftool":
+                    version_flag = "-ver"
+                elif tool_name == "ffprobe":
+                    version_flag = "-version"
+                else:
+                    version_flag = "--version"
+                result = subprocess.run(
+                    [tool_path, version_flag],
+                    capture_output=True,
+                    text=True,
+                    check=False,
+                )
+                if result.stdout or result.stderr:
+                    output = result.stdout + result.stderr
+                    version = self._extract_version_from_output(output, tool_name)
+                    if version:
+                        return version
+            except FileNotFoundError:
+                continue
+        return None
+
+    def _get_installed_versions_from_brew(self, package: str) -> list[str] | None:
+        """Get list of installed versions from Homebrew."""
+        try:
+            result = subprocess.run(
+                ["brew", "list", "--versions", package],
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+            if result.stdout:
+                parts = result.stdout.strip().split()
+                if len(parts) > 1:
+                    return parts[1:]
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            pass
+        return None
+
+    def _verify_pinned_version_installed(self, installed_versions: list[str], expected_version: str) -> bool:
+        """Verify that pinned version is in the installed versions list."""
+        expected_normalized = self._normalize_version(expected_version)
+        for version in installed_versions:
+            version_normalized = self._normalize_version(version)
+            if self._versions_match(expected_normalized, version_normalized):
+                return True
+        return False
+
+    def _find_pinned_version_in_list(self, installed_versions: list[str], expected_version: str) -> str | None:
+        """Find and return the pinned version from installed versions list."""
+        expected_normalized = self._normalize_version(expected_version)
+        for version in installed_versions:
+            version_normalized = self._normalize_version(version)
+            if self._versions_match(expected_normalized, version_normalized):
+                return version_normalized
+        return None
+
+    def get_installed_version(self, package: str, expected_version: str | None = None) -> str | None:
+        """Get installed package version on macOS."""
+        # Special handling for ffmpeg
+        if package == "ffmpeg":
+            return self._get_ffmpeg_version()
+
+        # Map package name to tool executable name
+        tool_name = package
+        if package == "media-info":
+            tool_name = "mediainfo"
+
+        # Get running version from executable
+        running_version = self._get_running_version_from_executable(package, tool_name)
+
+        # Verify pinned version is installed
+        installed_versions = self._get_installed_versions_from_brew(package)
+        if installed_versions is None:
+            return running_version
+
+        # If expected version is provided, check if running version or Homebrew version matches
+        if expected_version:
+            # Accept running version if it matches the pinned version
+            # This handles cases where tool is installed manually or from another source
+            if running_version and self._versions_match(expected_version, running_version):
+                return running_version
+
+            # If running version doesn't match, check if Homebrew has the pinned version
+            if installed_versions:
+                pinned_version = self._find_pinned_version_in_list(installed_versions, expected_version)
+                if pinned_version:
+                    # Homebrew has the pinned version, but running version doesn't match
+                    # Return None to indicate mismatch (running version should match pinned version)
+                    return None
+
+            # Pinned version not found in Homebrew and running version doesn't match
+            return None
+
+        # If expected version not provided, return running version or first installed version
+        if running_version:
+            return running_version
+        return self._normalize_version(installed_versions[0])