audiometa-python 0.6.0__py3-none-any.whl

audiometa/test/helpers/id3v1/id3v1_metadata_setter.py

@@ -0,0 +1,82 @@
+"""ID3v1 metadata setting operations."""
+
+from pathlib import Path
+from typing import Any
+
+from ..common.external_tool_runner import run_external_tool
+
+
+class ID3v1MetadataSetter:
+    """Static utility class for ID3v1 metadata setting using external tools."""
+
+    @staticmethod
+    def set_genre(file_path: Path, genre_code: str) -> None:
+        """Set ID3v1 genre using external id3v2 tool."""
+        command = ["id3v2", "--id3v1-only", "--genre", genre_code, str(file_path)]
+        run_external_tool(command, "id3v2")
+
+    @staticmethod
+    def set_comment(file_path: Path, comment: str) -> None:
+        """Set ID3v1 comment using external id3v2 tool."""
+        command = ["id3v2", "--id3v1-only", "--comment", comment, str(file_path)]
+        run_external_tool(command, "id3v2")
+
+    @staticmethod
+    def set_title(file_path: Path, title: str) -> None:
+        """Set ID3v1 title using external id3v2 tool."""
+        command = ["id3v2", "--id3v1-only", "--song", title, str(file_path)]
+        run_external_tool(command, "id3v2")
+
+    @staticmethod
+    def set_artist(file_path: Path, artist: str) -> None:
+        """Set ID3v1 artist using external id3v2 tool."""
+        command = ["id3v2", "--id3v1-only", "--artist", artist, str(file_path)]
+        run_external_tool(command, "id3v2")
+
+    @staticmethod
+    def set_album(file_path: Path, album: str) -> None:
+        """Set ID3v1 album using external id3v2 tool."""
+        command = ["id3v2", "--id3v1-only", "--album", album, str(file_path)]
+        run_external_tool(command, "id3v2")
+
+    @staticmethod
+    def set_max_metadata(file_path: Path) -> None:
+        """Set maximum ID3v1 metadata using external script."""
+        from pathlib import Path
+
+        from ..common.external_tool_runner import run_script
+
+        scripts_dir = Path(__file__).parent.parent.parent.parent / "test" / "helpers" / "scripts"
+        run_script("set-id3v1-max-metadata.sh", file_path, scripts_dir)
+
+    @staticmethod
+    def set_metadata(file_path: Path, metadata: dict[str, Any]) -> None:
+        """Set ID3v1 metadata using id3v2 tool (id3v2 can also set ID3v1 tags)."""
+        # Ensure ID3v1.1 format when track is set
+        metadata = metadata.copy()
+        if "track" in metadata and "comment" not in metadata:
+            metadata["comment"] = " " * 28  # Set comment to 28 spaces to enable ID3v1.1
+
+        cmd = ["id3v2", "--id3v1-only"]
+
+        # Map common metadata keys to id3v2 arguments for ID3v1
+        key_mapping = {
+            "title": "--song",
+            "artist": "--artist",
+            "album": "--album",
+            "year": "--year",
+            "genre": "--genre",
+            "comment": "--comment",
+            "track": "--track",
+        }
+
+        metadata_added = False
+        for key, value in metadata.items():
+            if key.lower() in key_mapping:
+                cmd.extend([key_mapping[key.lower()], str(value)])
+                metadata_added = True
+
+        # Only run id3v2 if metadata was actually added
+        if metadata_added:
+            cmd.append(str(file_path))
+            run_external_tool(cmd, "id3v2")

audiometa/test/helpers/id3v2/__init__.py

@@ -0,0 +1,28 @@
+"""ID3v2 metadata format helpers."""
+
+# Core operations (following RIFF pattern)
+# External tool wrappers
+from ..common.external_tool_runner import ExternalMetadataToolError
+
+# Advanced tools
+from .id3v2_frame_manual_creator import ManualID3v2FrameCreator
+from .id3v2_header_verifier import ID3v2HeaderVerifier
+from .id3v2_metadata_deleter import ID3v2MetadataDeleter
+from .id3v2_metadata_getter import ID3v2MetadataGetter
+from .id3v2_metadata_setter import ID3v2MetadataSetter
+
+# Specialized managers (moved to ID3v2MetadataSetter)
+
+
+__all__ = [
+    # Core operations
+    "ID3v2HeaderVerifier",
+    "ID3v2MetadataDeleter",
+    "ID3v2MetadataSetter",
+    "ID3v2MetadataGetter",
+    # Specialized managers (moved to ID3v2MetadataSetter)
+    # Advanced tools
+    "ManualID3v2FrameCreator",
+    # External tool wrappers
+    "ExternalMetadataToolError",
+]

audiometa/test/helpers/id3v2/id3v2_frame_manual_creator.py

@@ -0,0 +1,349 @@
+#!/usr/bin/env python3
+"""Manual implementation to create multiple separate ID3v2 frames for testing.
+
+This bypasses standard tools and libraries that automatically consolidate frames, allowing creation of test files with
+truly separate TPE1, TPE2, TCON etc. frames.
+"""
+
+import struct
+import subprocess
+import tempfile
+from pathlib import Path
+
+from audiometa.utils.tool_path_resolver import get_tool_path
+
+
+class ManualID3v2FrameCreator:
+    """Creates ID3v2 tags with multiple separate frames by manual binary construction."""
+
+    @staticmethod
+    def create_multiple_tpe1_frames(file_path: Path, artists: list[str], version: str = "2.4") -> None:
+        if version not in ["2.3", "2.4"]:
+            msg = "Version must be '2.3' or '2.4'"
+            raise ValueError(msg)
+        frames = []
+        for artist in artists:
+            frame_data = ManualID3v2FrameCreator._create_text_frame("TPE1", artist, version)
+            frames.append(frame_data)
+
+        ManualID3v2FrameCreator._write_id3v2_tag(file_path, frames, version)
+
+    @staticmethod
+    def create_multiple_tpe2_frames(file_path: Path, album_artists: list[str], version: str = "2.4") -> None:
+        if version not in ["2.3", "2.4"]:
+            msg = "Version must be '2.3' or '2.4'"
+            raise ValueError(msg)
+        frames = []
+        for album_artist in album_artists:
+            frame_data = ManualID3v2FrameCreator._create_text_frame("TPE2", album_artist, version)
+            frames.append(frame_data)
+
+        ManualID3v2FrameCreator._write_id3v2_tag(file_path, frames, version)
+
+    @staticmethod
+    def create_multiple_tcon_frames(file_path: Path, genres: list[str], version: str = "2.4") -> None:
+        if version not in ["2.3", "2.4"]:
+            msg = "Version must be '2.3' or '2.4'"
+            raise ValueError(msg)
+        frames = []
+        for genre in genres:
+            frame_data = ManualID3v2FrameCreator._create_text_frame("TCON", genre, version)
+            frames.append(frame_data)
+
+        ManualID3v2FrameCreator._write_id3v2_tag(file_path, frames, version)
+
+    @staticmethod
+    def create_multiple_tcom_frames(file_path: Path, composers: list[str], version: str = "2.4") -> None:
+        if version not in ["2.3", "2.4"]:
+            msg = "Version must be '2.3' or '2.4'"
+            raise ValueError(msg)
+        frames = []
+        for composer in composers:
+            frame_data = ManualID3v2FrameCreator._create_text_frame("TCOM", composer, version)
+            frames.append(frame_data)
+
+        ManualID3v2FrameCreator._write_id3v2_tag(file_path, frames, version)
+
+    @staticmethod
+    def create_mixed_multiple_frames(
+        file_path: Path, artists: list[str], genres: list[str], version: str = "2.4"
+    ) -> None:
+        if version not in ["2.3", "2.4"]:
+            msg = "Version must be '2.3' or '2.4'"
+            raise ValueError(msg)
+        frames = []
+
+        # Add multiple TPE1 frames
+        for artist in artists:
+            frame_data = ManualID3v2FrameCreator._create_text_frame("TPE1", artist, version)
+            frames.append(frame_data)
+
+        # Add multiple TCON frames
+        for genre in genres:
+            frame_data = ManualID3v2FrameCreator._create_text_frame("TCON", genre, version)
+            frames.append(frame_data)
+
+        ManualID3v2FrameCreator._write_id3v2_tag(file_path, frames, version)
+
+    @staticmethod
+    def _create_text_frame(frame_id: str, text: str, version: str, encoding: int | None = None) -> bytes:
+        """Create a single ID3v2 text frame with the given ID and text."""
+        # Choose encoding based on version or provided encoding
+        if encoding is not None:
+            enc = encoding
+        elif version == "2.3":
+            # ID3v2.3: Use ISO-8859-1
+            enc = 0
+        else:  # ID3v2.4
+            # ID3v2.4: Use UTF-8
+            enc = 3
+
+        # Determine null terminator based on encoding
+        null_terminator = b"\x00\x00" if enc in (1, 2) else b"\x00"
+
+        # Encode text
+        if enc == 0:  # ISO-8859-1
+            text_bytes = text.encode("latin1", errors="ignore")
+        elif enc == 1:  # UTF-16 with BOM
+            text_bytes = text.encode("utf-16")
+        elif enc == 2:  # UTF-16BE without BOM
+            text_bytes = text.encode("utf-16be")
+        elif enc == 3:  # UTF-8
+            text_bytes = text.encode("utf-8")
+        else:
+            text_bytes = text.encode("latin1", errors="ignore")
+
+        # Frame data: encoding byte + text + null terminator
+        frame_data = struct.pack("B", enc) + text_bytes + null_terminator
+
+        # Frame header: ID (4 bytes) + size (4 bytes) + flags (2 bytes)
+        frame_id_bytes = frame_id.encode("ascii")
+        frame_size = len(frame_data)
+        frame_flags = 0x0000  # No flags
+
+        if version == "2.3":
+            frame_header = (
+                frame_id_bytes
+                + struct.pack(">I", frame_size)  # Big-endian 32-bit size
+                + struct.pack(">H", frame_flags)  # Big-endian 16-bit flags
+            )
+        else:  # ID3v2.4
+            frame_header = (
+                frame_id_bytes
+                + ManualID3v2FrameCreator._synchsafe_int(frame_size)  # Synchsafe size
+                + struct.pack(">H", frame_flags)  # Big-endian 16-bit flags
+            )
+
+        return frame_header + frame_data
+
+    @staticmethod
+    def _synchsafe_int(value: int) -> bytes:
+        """Convert integer to ID3v2 synchsafe integer (7 bits per byte)."""
+        # Split into 7-bit chunks, most significant first
+        result: list[int] = []
+        for _i in range(4):
+            result.insert(0, value & 0x7F)
+            value >>= 7
+        return struct.pack("4B", *result)
+
+    @staticmethod
+    def _syncsafe_decode(data: bytes) -> int:
+        """Decode a 4-byte syncsafe integer."""
+        return ((data[0] & 0x7F) << 21) | ((data[1] & 0x7F) << 14) | ((data[2] & 0x7F) << 7) | (data[3] & 0x7F)
+
+    @staticmethod
+    def _write_id3v2_tag(file_path: Path, frames: list[bytes], version: str) -> None:
+        """Write ID3v2 tag with the given frames to the file, preserving existing frames."""
+
+        # Read existing file content
+        with file_path.open("rb") as f:
+            original_data = f.read()
+
+        # Extract existing frames and audio data
+        existing_frames: list[bytes] = []
+        audio_data = original_data
+        frame_ids_to_replace: set[str] = set()
+
+        # Extract frame IDs from new frames to know which ones to replace
+        for frame_bytes in frames:
+            if len(frame_bytes) >= 4:
+                frame_id = frame_bytes[:4].decode("ascii", errors="ignore")
+                frame_ids_to_replace.add(frame_id)
+
+        if original_data.startswith(b"ID3") and len(original_data) >= 10:
+            # Parse existing ID3v2 tag
+            existing_version = original_data[3]
+            size_bytes = original_data[6:10]
+
+            if existing_version == 4:
+                # ID3v2.4 uses synchsafe integers
+                existing_tag_size = 0
+                for byte in size_bytes:
+                    existing_tag_size = (existing_tag_size << 7) | (byte & 0x7F)
+            else:
+                # ID3v2.3 and earlier use regular integers
+                existing_tag_size = struct.unpack(">I", size_bytes)[0]
+
+            # Read existing tag data
+            tag_data = original_data[10 : 10 + existing_tag_size]
+            audio_data = original_data[10 + existing_tag_size :]
+
+            # Parse existing frames, preserving those not being replaced
+            pos = 0
+            while pos < len(tag_data) - 10:
+                frame_id_bytes = tag_data[pos : pos + 4]
+                if frame_id_bytes == b"\x00\x00\x00\x00":
+                    break
+
+                try:
+                    frame_id_str = frame_id_bytes.decode("ascii")
+                except UnicodeDecodeError:
+                    break
+
+                # Determine frame size based on version
+                if existing_version == 4:
+                    frame_size = ManualID3v2FrameCreator._syncsafe_decode(tag_data[pos + 4 : pos + 8])
+                else:
+                    frame_size = int.from_bytes(tag_data[pos + 4 : pos + 8], "big")
+
+                if pos + 10 + frame_size > len(tag_data):
+                    break
+
+                # Only preserve frames that aren't being replaced
+                if frame_id_str not in frame_ids_to_replace:
+                    frame_data = tag_data[pos : pos + 10 + frame_size]
+                    existing_frames.append(frame_data)
+
+                pos += 10 + frame_size
+
+        # Combine existing frames (that aren't being replaced) with new frames
+        all_frames = existing_frames + frames
+        frames_data = b"".join(all_frames)
+        tag_size = len(frames_data)
+
+        # Create header based on version
+        if version == "2.3":
+            # ID3v2.3 header: "ID3" + version + flags + size (regular integer)
+            header = (
+                b"ID3"  # ID3 identifier
+                + struct.pack("BB", 3, 0)  # Version 2.3.0
+                + struct.pack("B", 0)  # Flags (no unsynchronisation, etc.)
+                + struct.pack(">I", tag_size)  # Size as regular 32-bit integer
+            )
+        else:  # ID3v2.4
+            # ID3v2.4 header: "ID3" + version + flags + size (synchsafe integer)
+            header = (
+                b"ID3"  # ID3 identifier
+                + struct.pack("BB", 4, 0)  # Version 2.4.0
+                + struct.pack("B", 0)  # Flags (no unsynchronisation, etc.)
+                + ManualID3v2FrameCreator._synchsafe_int(tag_size)  # Size as synchsafe integer
+            )
+
+        # Write new file with merged ID3v2 tag
+        with file_path.open("wb") as f:
+            f.write(header)
+            f.write(frames_data)
+            f.write(audio_data)
+
+
+def manual_multiple_frames_test():
+    """Test the manual frame creation for both ID3v2.3 and ID3v2.4."""
+
+    def run_test_for_version(version: str):
+        """Test a specific ID3v2 version."""
+
+        # Create a temporary MP3 file
+        with tempfile.NamedTemporaryFile(suffix=".mp3", delete=False) as tmp:
+            tmp_path = Path(tmp.name)
+
+        try:
+            # Create minimal MP3 file
+            subprocess.run(
+                ["ffmpeg", "-f", "lavfi", "-i", "anullsrc=duration=1", "-acodec", "mp3", "-y", str(tmp_path)],
+                check=True,
+                capture_output=True,
+            )
+
+            # Test 1: Multiple TPE1 frames
+            artists = ["Artist One", "Artist Two", "Artist Three"]
+            ManualID3v2FrameCreator.create_multiple_tpe1_frames(tmp_path, artists, version)
+
+            # Check result with mid3v2
+            result = subprocess.run(
+                [get_tool_path("mid3v2"), "-l", str(tmp_path)], capture_output=True, text=True, check=False
+            )
+
+            # Count TPE1 occurrences
+            tpe1_count = result.stdout.count("TPE1=")
+
+            if tpe1_count > 1:
+                pass
+            else:
+                pass
+
+            # Test 2: Multiple TCON frames
+            genres = ["Rock", "Pop", "Alternative"]
+            ManualID3v2FrameCreator.create_multiple_tcon_frames(tmp_path, genres, version)
+
+            result = subprocess.run(
+                [get_tool_path("mid3v2"), "-l", str(tmp_path)], capture_output=True, text=True, check=False
+            )
+
+            tcon_count = result.stdout.count("TCON=")
+
+            # Test 3: Mixed multiple frames
+            ManualID3v2FrameCreator.create_mixed_multiple_frames(
+                tmp_path, artists=["Artist A", "Artist B"], genres=["Genre X", "Genre Y"], version=version
+            )
+
+            result = subprocess.run(
+                [get_tool_path("mid3v2"), "-l", str(tmp_path)], capture_output=True, text=True, check=False
+            )
+
+            # Check version in the file and verify multiple frames exist in binary
+            result = subprocess.run(
+                [get_tool_path("mid3v2"), "-l", str(tmp_path)], capture_output=True, text=True, check=False
+            )
+            if result.stdout:
+                # Verify multiple frames exist by checking raw binary
+                with Path(tmp_path).open("rb") as f:
+                    data = f.read(1000)  # Read first 1KB to check for multiple frame IDs
+                    tpe1_count = data.count(b"TPE1")
+                    tcon_count = data.count(b"TCON")
+
+                    if tpe1_count > 1 or tcon_count > 1:
+                        pass
+                    else:
+                        pass
+
+        finally:
+            if tmp_path.exists():
+                tmp_path.unlink()
+
+    # Test both versions
+    run_test_for_version("2.3")
+    run_test_for_version("2.4")
+
+
+def create_test_file_with_version(
+    output_path: Path, version: str = "2.4", artists: list[str] | None = None, genres: list[str] | None = None
+) -> None:
+    """Create a test MP3 file with multiple frames in the specified ID3v2 version."""
+    if artists is None:
+        artists = ["Artist One", "Artist Two", "Artist Three"]
+    if genres is None:
+        genres = ["Rock", "Pop", "Alternative"]
+
+    # Create minimal MP3 file
+    subprocess.run(
+        ["ffmpeg", "-f", "lavfi", "-i", "anullsrc=duration=1", "-acodec", "mp3", "-y", str(output_path)],
+        check=True,
+        capture_output=True,
+    )
+
+    # Add multiple frames
+    ManualID3v2FrameCreator.create_mixed_multiple_frames(output_path, artists, genres, version)
+
+
+if __name__ == "__main__":
+    manual_multiple_frames_test()

audiometa/test/helpers/id3v2/id3v2_header_verifier.py

@@ -0,0 +1,38 @@
+"""ID3 metadata header verification utilities."""
+
+from pathlib import Path
+
+
+class ID3v2HeaderVerifier:
+    """Utilities for verifying ID3 metadata headers in audio files."""
+
+    @staticmethod
+    def has_id3v2_header(file_path: Path) -> bool:
+        """Check if file has ID3v2 header by reading the first 10 bytes."""
+        try:
+            with file_path.open("rb") as f:
+                header = f.read(10)
+                return header[:3] == b"ID3"
+        except OSError:
+            return False
+
+    @staticmethod
+    def get_id3v2_version(file_path: Path) -> tuple[int, int, int] | None:
+        """Get the ID3v2 version of the file.
+
+        Args:
+            file_path: Path to the audio file
+
+        Returns:
+            Version tuple (major, minor, revision) or None if no ID3v2 header found
+        """
+        try:
+            from mutagen.id3 import ID3, ID3NoHeaderError
+
+            id3_tags = ID3(file_path)
+        except ID3NoHeaderError:
+            return None
+        except Exception:
+            return None
+        else:
+            return id3_tags.version

audiometa/test/helpers/id3v2/id3v2_metadata_deleter.py

@@ -0,0 +1,56 @@
+"""ID3v2 metadata deletion operations."""
+
+from pathlib import Path
+
+from ..common.external_tool_runner import run_external_tool
+
+
+class ID3v2MetadataDeleter:
+    """Static utility class for ID3v2 metadata deletion using external tools."""
+
+    @staticmethod
+    def delete_frame(file_path: Path, frame_id: str) -> None:
+        """Delete a specific ID3v2 frame."""
+        try:
+            command = ["mid3v2", "--delete-frames", frame_id, str(file_path)]
+            run_external_tool(command, "mid3v2")
+        except Exception:
+            # Ignore if frame doesn't exist
+            pass
+
+    @staticmethod
+    def delete_comment(file_path: Path) -> None:
+        ID3v2MetadataDeleter.delete_frame(file_path, "COMM")
+
+    @staticmethod
+    def delete_title(file_path: Path) -> None:
+        ID3v2MetadataDeleter.delete_frame(file_path, "TIT2")
+
+    @staticmethod
+    def delete_artist(file_path: Path) -> None:
+        ID3v2MetadataDeleter.delete_frame(file_path, "TPE1")
+
+    @staticmethod
+    def delete_album(file_path: Path) -> None:
+        ID3v2MetadataDeleter.delete_frame(file_path, "TALB")
+
+    @staticmethod
+    def delete_genre(file_path: Path) -> None:
+        ID3v2MetadataDeleter.delete_frame(file_path, "TCON")
+
+    @staticmethod
+    def delete_lyrics(file_path: Path) -> None:
+        ID3v2MetadataDeleter.delete_frame(file_path, "USLT")
+
+    @staticmethod
+    def delete_language(file_path: Path) -> None:
+        ID3v2MetadataDeleter.delete_frame(file_path, "TLAN")
+
+    @staticmethod
+    def delete_bpm(file_path: Path) -> None:
+        ID3v2MetadataDeleter.delete_frame(file_path, "TBPM")
+
+    @staticmethod
+    def delete_tag(file_path: Path, tag_name: str) -> None:
+        command = ["id3v2", "--id3v2-only", "--delete", tag_name, str(file_path)]
+        run_external_tool(command, "id3v2")