audiometa-python 0.6.0__py3-none-any.whl

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])

audiometa/utils/os_dependencies_checker/ubuntu.py

@@ -0,0 +1,95 @@
+"""Ubuntu-specific dependency checker using dpkg."""
+
+import subprocess
+
+from audiometa.utils.os_dependencies_checker.base import OsDependenciesChecker
+
+
+class UbuntuDependenciesChecker(OsDependenciesChecker):
+    """Ubuntu-specific dependency checker using dpkg."""
+
+    @classmethod
+    def get_os_type(cls) -> str:
+        return "ubuntu"
+
+    def check_tool_available(self, tool_name: str) -> bool:
+        """Check if tool is available in PATH."""
+        try:
+            result = subprocess.run(
+                [tool_name, "--version"],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+            return bool(result.stdout or result.stderr)
+        except FileNotFoundError:
+            return False
+
+    def get_installed_version(self, package: str, expected_version: str | None = None) -> str | None:  # noqa: ARG002
+        """Get installed package version on Ubuntu."""
+        try:
+            result = subprocess.run(["dpkg", "-l"], capture_output=True, text=True, check=True)
+            for line in result.stdout.split("\n"):
+                if line.startswith("ii") and package in line:
+                    parts = line.split()
+                    if len(parts) >= 3:  # noqa: PLR2004
+                        return parts[2]
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            pass
+        return None
+
+    @staticmethod
+    def _versions_match(version1: str, version2: str) -> bool:
+        """Check if two Ubuntu/Debian package version strings match.
+
+        Handles Debian package version format: upstream-version-debian-revision
+        Compares the upstream version part (before the first '-') for compatibility.
+        Supports flexible prefix matching (e.g., "24.01" matches "24.01.1" or "24.01+dfsg").
+
+        Args:
+            version1: First version string (e.g., "24.01", "24.01.1-1build2", or "25.04.1")
+            version2: Second version string (e.g., "24.01+dfsg-1build2", "24.01.1-1build2", or "25.04.1-1")
+
+        Returns:
+            True if upstream versions match, False otherwise
+        """
+        # Extract upstream version (part before first '-')
+        # Handle both formats: "24.01.1-1build2" -> "24.01.1" and "25.04.1" -> "25.04.1"
+        v1_upstream = version1.split("-")[0]
+        v2_upstream = version2.split("-")[0]
+
+        # Normalize versions: remove revision suffix (like _4) and Debian suffixes (like +dfsg)
+        # This allows "24.01" to match "24.01+dfsg" or "24.01.1"
+        v1_normalized = UbuntuDependenciesChecker._normalize_debian_version(v1_upstream)
+        v2_normalized = UbuntuDependenciesChecker._normalize_debian_version(v2_upstream)
+
+        # Check if versions match exactly
+        if v1_normalized == v2_normalized:
+            return True
+
+        # Check if one version is a prefix of the other
+        # "24.01" should match "24.01.1" (v2 starts with v1 + ".")
+        # "24.01.1" should match "24.01" (v1 starts with v2 + ".")
+        return v2_normalized.startswith(v1_normalized + ".") or v1_normalized.startswith(v2_normalized + ".")
+
+    @staticmethod
+    def _normalize_debian_version(version: str) -> str:
+        """Normalize Debian version string by removing suffixes.
+
+        Removes revision suffixes (like _4) and Debian-specific suffixes (like +dfsg, +ds).
+
+        Args:
+            version: Version string (e.g., "24.01+dfsg" or "24.01.1_4")
+
+        Returns:
+            Normalized version without suffixes
+        """
+        # Remove revision suffix (like _4)
+        normalized = OsDependenciesChecker._normalize_version(version)
+
+        # Remove Debian-specific suffixes (like +dfsg, +ds)
+        # Split on '+' and take the first part
+        if "+" in normalized:
+            normalized = normalized.split("+")[0]
+
+        return normalized

audiometa/utils/os_dependencies_checker/windows.py

@@ -0,0 +1,227 @@
+"""Windows-specific dependency checker."""
+
+import re
+import subprocess
+from pathlib import Path
+
+from audiometa.utils.os_dependencies_checker.base import OsDependenciesChecker
+
+
+class WindowsDependenciesChecker(OsDependenciesChecker):
+    """Windows-specific dependency checker."""
+
+    @classmethod
+    def get_os_type(cls) -> str:
+        return "windows"
+
+    def check_tool_available(self, tool_name: str) -> bool:
+        """Check if tool is available in PATH or default Windows locations."""
+        # Check default installation paths for manually installed tools
+        if tool_name == "bwfmetaedit":
+            exe_path = r"C:\Program Files\BWFMetaEdit\bwfmetaedit.exe"
+            if Path(exe_path).exists():
+                return True
+        elif tool_name == "exiftool":
+            exe_path = r"C:\Program Files\ExifTool\exiftool.exe"
+            if Path(exe_path).exists():
+                return True
+        elif tool_name == "id3v2":
+            wrapper_path = r"C:\Program Files\id3v2-wrapper\id3v2.bat"
+            if Path(wrapper_path).exists():
+                return True
+            try:
+                subprocess.run(["wsl", "--version"], capture_output=True, check=False)
+            except FileNotFoundError:
+                pass
+            else:
+                return True
+
+        # Check PATH
+        try:
+            result = subprocess.run(
+                [tool_name, "--version" if tool_name != "ffprobe" else "-version"],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+            return bool(result.stdout or result.stderr)
+        except FileNotFoundError:
+            return False
+
+    def get_installed_version(self, package: str, expected_version: str | None = None) -> str | None:  # noqa: ARG002
+        """Get installed package version on Windows."""
+        # Handle different installation methods
+        if package == "id3v2":
+            try:
+                result = subprocess.run(
+                    ["wsl", "id3v2", "--version"],
+                    capture_output=True,
+                    text=True,
+                    check=False,
+                )
+                if result.stdout or result.stderr:
+                    output = result.stdout + result.stderr
+                    match = re.search(r"(\d+\.\d+\.\d+)", output)
+                    if match:
+                        return match.group(1)
+            except FileNotFoundError:
+                pass
+            return None
+
+        if package == "bwfmetaedit":
+            exe_path = r"C:\Program Files\BWFMetaEdit\bwfmetaedit.exe"
+            try:
+                if not Path(exe_path).exists():
+                    return None
+
+                result = subprocess.run(
+                    [exe_path, "--version"],
+                    capture_output=True,
+                    text=True,
+                    check=False,
+                    timeout=10,
+                )
+                output = result.stdout + result.stderr
+
+                if not output.strip() or result.returncode != 0:
+                    result = subprocess.run(
+                        [exe_path],
+                        capture_output=True,
+                        text=True,
+                        check=False,
+                        timeout=10,
+                    )
+                    output = result.stdout + result.stderr
+
+                if output:
+                    patterns = [
+                        r"(\d+\.\d+\.\d+)",
+                        r"(\d+\.\d+)",
+                    ]
+                    for pattern in patterns:
+                        matches = re.findall(pattern, output)
+                        for match in matches:
+                            version = str(match)
+                            if re.match(r"^\d+\.\d+", version):
+                                return version
+            except (FileNotFoundError, subprocess.TimeoutExpired, Exception):
+                pass
+            return None
+
+        if package == "exiftool":
+            exe_path = r"C:\Program Files\ExifTool\exiftool.exe"
+            try:
+                result = subprocess.run(
+                    [exe_path, "-ver"],
+                    capture_output=True,
+                    text=True,
+                    check=False,
+                )
+                if result.stdout:
+                    version = result.stdout.strip()
+                    if re.match(r"^\d+\.\d+", version):
+                        return version
+            except FileNotFoundError:
+                pass
+            return None
+
+        # For Chocolatey packages
+        choco_version = None
+        try:
+            result = subprocess.run(
+                ["choco", "list", "--local-only", package, "--exact"],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+            output = result.stdout + result.stderr
+
+            if output.strip():
+                pattern = rf"^{re.escape(package)}\s+(\S+)"
+                for raw_line in output.split("\n"):
+                    line = raw_line.strip()
+                    if not line or line.startswith("Chocolatey"):
+                        continue
+
+                    match = re.match(pattern, line, re.IGNORECASE)
+                    if match:
+                        version = match.group(1)
+                        if version.startswith(("v", "V")):
+                            version = version[1:]
+                        if re.match(r"^\d+\.\d+", version):
+                            choco_version = version
+                            break
+
+                    if "|" in line:
+                        parts = line.split("|")
+                        if len(parts) >= 2 and parts[0].strip().lower() == package.lower():  # noqa: PLR2004
+                            version = parts[1].strip()
+                            if version.startswith(("v", "V")):
+                                version = version[1:]
+                            if re.match(r"^\d+\.\d+", version):
+                                choco_version = version
+                                break
+        except FileNotFoundError:
+            pass
+
+        if choco_version:
+            return choco_version
+
+        # Fallback: Get version from executable directly (for Chocolatey-installed tools)
+        # This handles cases where Chocolatey version detection fails but tool is installed
+        tool_name = "ffprobe" if package == "ffmpeg" else package
+        try:
+            version_flag = "-version" if tool_name == "ffprobe" else "--version"
+            result = subprocess.run(
+                [tool_name, version_flag],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+            output = result.stdout + result.stderr
+            if output:
+                # Extract version from output (look for patterns like "version 7.1.0" or "7.1.0")
+                patterns = [
+                    r"version\s+(\d+\.\d+\.\d+)",
+                    r"version\s+(\d+\.\d+)",
+                    r"(\d+\.\d+\.\d+)",
+                    r"(\d+\.\d+)",
+                ]
+                for pattern in patterns:
+                    matches = re.findall(pattern, output, re.IGNORECASE)
+                    for match in matches:
+                        version = str(match)
+                        if re.match(r"^\d+\.\d+", version):
+                            return version
+        except FileNotFoundError:
+            pass
+
+        return None
+
+    @staticmethod
+    def _versions_match(version1: str, version2: str) -> bool:
+        """Check if two Windows version strings match (handles different precision).
+
+        Handles cases where versions have different precision levels:
+        - "7.1.0" matches "7.1" (v2 is prefix of v1)
+        - "7.1" matches "7.1.0" (v1 is prefix of v2)
+        - "7.1.0" matches "7.1.0" (exact match)
+
+        Args:
+            version1: First version string (e.g., "7.1.0")
+            version2: Second version string (e.g., "7.1")
+
+        Returns:
+            True if versions match, False otherwise
+        """
+        v1_normalized = OsDependenciesChecker._normalize_version(version1)
+        v2_normalized = OsDependenciesChecker._normalize_version(version2)
+
+        # Check exact match
+        if v1_normalized == v2_normalized:
+            return True
+
+        # Check if one version is a prefix of the other
+        # "7.1" should match "7.1.0" (v2 starts with v1 + ".")
+        # "7.1.0" should match "7.1" (v1 starts with v2 + ".")
+        return v2_normalized.startswith(v1_normalized + ".") or v1_normalized.startswith(v2_normalized + ".")

audiometa/utils/rating_profiles.py

@@ -0,0 +1,110 @@
+"""Rating Compatibility Table Across Different Audio Players.
+
+⚠️  AUTHORITATIVE SOURCE: This is the single source of truth for rating compatibility.
+The README references this table for the complete details.
+
+The following table shows how different audio players handle ratings across various audio formats.
+Values represent the actual numbers written to files for each star rating (0-5 stars).
+
++----+----------------+------------+------------+------------+------------+---------+
+| ⭐ |      kid3      |   Windows  |  MusicBee  |   Winamp   |   Traktor  |  iTunes |
+|    |   /Lollypop    |Media Player|            |            |            |         |
++----+---+-------+----+------------+------------+------------+------------+---------+
+|ext.|mp3|  wav  |flac|mp3 wav flac|mp3 wav flac|mp3 wav flac|mp3 wav flac|W ops not|
++----+-----------+----+------------+------------+------------+------------+         +
+|tags|id3|rif id3|vorb|id3  ✗  vorb|id3 id3 vorb|id3  ✗  vorb|id3  ✗  vorb|supported|
++----+---+-------+----+------------+------------+------------+------------+---------+
+|None| ✗   ✗   ✗    ✗ | ✗       ✗  | ✗   ✗   ✗  |  ✗      ✗  | 0        0 |         |
+| 0  |                |            | 0   0   0  |            |            |         |
+|0.5 |                |            |13   10  10 |            |            |         |
+| 1  | 1   20  1   20 | 1       20 | 1   20  20 |  1      20 | 51      51 |         |
+|1.5 |                |            |54   30  30 |            |            |         |
+| 2  |64   40  64  40 | 64      40 |64   40  40 | 64      40 |102     102 |         |
+|2.5 |                |            |118  50  50 |            |            |         |
+| 3  |128  60 128  60 | 128     60 |128  60  60 | 128     60 |153     153 |         |
+|3.5 |                |            |186  70  70 |            |            |         |
+| 4  |196  80 196  80 |196  80  80 | 196     80 | 196     80 |204     204 |         |
+|4.5 |                |            |242  90  90 |            |            |         |
+| 5  |255 100 255  100| 255    100 |255 100 100 | 255    100 |255     255 |         |
++----+----------------+------------+------------+------------+------------+---------+
+|Prof| A   B   A   B  |  A   ✗  B  | A   B   B  |  A   ✗  B  | C   ✗   C  |    ✗    |
++----+----------------+------------+------------+------------+------------+---------+
+
+Legend:
+    id3 = id3v2
+    rif = RIFF
+    vorb = Vorbis
+    ✗ = No tag written
+    empty = Rating value not supported
+    ✓ = Can write ratings
+
+- Rating Profiles:
+    A. 255 non-proportional: .mp3 id3v2 not Traktor, RIFF
+    B. 100 proportional: Vorbis not Traktor, .wav id3v2
+    C. 255 proportional: Traktor id3v2/Vorbis
+
+- Key Point
+Despite having different profiles, each rating value uniquely maps to one star value, enabling reliable star rating
+interpretation regardless of the source profile.
+
+- Example: All these values map to 3 stars
+    assert rating_to_stars(128) == 3.0  # Profile A
+    assert rating_to_stars(60) == 3.0   # Profile B
+    assert rating_to_stars(153) == 3.0  # Profile C
+
+- Exception:
+0 can either mean no rating (Traktor) or 0 stars (MusicBee).
+Luckily, Traktor ratings are written with special tags making them easy to distinguish.
+"""
+
+from collections.abc import Iterator
+from enum import Enum
+
+
+class RatingReadProfile(Enum):
+    """Enumeration of rating read profiles for different audio formats."""
+
+    BASE_255_NON_PROPORTIONAL = (0, 13, 1, 54, 64, 118, 128, 186, 196, 242, 255)
+    BASE_255_PROPORTIONAL_TRAKTOR = (None, None, 51, None, 102, None, 153, None, 204, None, 255)
+    BASE_100_PROPORTIONAL = (0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100)
+
+    def __getitem__(self, index: int) -> int | None:
+        result = self.value[index]
+        return result if isinstance(result, int | type(None)) else int(result)
+
+    def __len__(self) -> int:
+        return len(self.value)
+
+    def __iter__(self) -> Iterator[int | None]:
+        return iter(self.value)
+
+    def __contains__(self, item: object) -> bool:
+        return item in self.value
+
+
+"""
+Regarding the ratings that the app will write in the audio files, the app currently uses the 2 most widely supported
+profiles:
+- 255 non proportional (ID3v2, RIFF)
+- 100 proportional (Vorbis)
+"""
+
+
+class RatingWriteProfile(Enum):
+    """Enumeration of rating write profiles for different audio formats."""
+
+    BASE_255_NON_PROPORTIONAL = RatingReadProfile.BASE_255_NON_PROPORTIONAL.value
+    BASE_100_PROPORTIONAL = RatingReadProfile.BASE_100_PROPORTIONAL.value
+
+    def __getitem__(self, index: int) -> int | None:
+        result = self.value[index]
+        return result if isinstance(result, int | type(None)) else int(result)
+
+    def __len__(self) -> int:
+        return len(self.value)
+
+    def __iter__(self) -> Iterator[int | None]:
+        return iter(self.value)
+
+    def __contains__(self, item: object) -> bool:
+        return item in self.value