audiometa-python 0.6.0__py3-none-any.whl

audiometa/manager/id3v1/id3v1_raw_metadata.py

@@ -0,0 +1,242 @@
+"""ID3v1 raw metadata handling."""
+
+import struct
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from mutagen._file import FileType
+
+from ._constants import (
+    ID3V1_MIN_COMMENT_LENGTH_FOR_TRACK_NUMBER,
+    ID3V1_TAG_SIZE,
+    ID3V1_TRACK_NUMBER_POSITION,
+    ID3V1_TRACK_NUMBER_VALUE_POSITION,
+)
+from .id3v1_raw_metadata_key import Id3v1RawMetadataKey
+
+
+class Id3v1RawMetadata(FileType):
+    """A custom file-like object for ID3v1 tags, providing a consistent interface similar to mutagen.
+
+    This class encapsulates the ID3v1 128-byte structure and provides a clean interface for accessing and modifying tag
+    data. It supports both reading and writing using direct file manipulation.
+    """
+
+    @dataclass
+    class Id3v1Tag:
+        title: str = ""
+        artists_names_str: str = ""
+        album_name: str = ""
+        year: str = ""
+        comment: str = ""
+        track_number: int | None = None
+        genre_code: int = 255  # 255 is undefined genre
+
+    def __init__(self, fileobj: Any):
+        self.fileobj = fileobj
+        object.__setattr__(self, "tags", None)
+        self._load_tags()
+
+    def _load_tags(self) -> None:
+        # Handle both file objects and file paths
+        if isinstance(self.fileobj, str | Path):
+            with Path(self.fileobj).open("rb") as f:
+                f.seek(-ID3V1_TAG_SIZE, 2)  # Seek from end
+                data = f.read(ID3V1_TAG_SIZE)
+        else:
+            self.fileobj.seek(-ID3V1_TAG_SIZE, 2)  # Seek from end
+            data = self.fileobj.read(ID3V1_TAG_SIZE)
+
+        if not data.startswith(b"TAG"):
+            self.tags = None
+            return
+
+        # Parse the fixed structure into our tag object
+        tag = self.Id3v1Tag(
+            title=data[3:33].strip(b"\0").decode("latin1", "replace"),
+            artists_names_str=data[33:63].strip(b"\0").decode("latin1", "replace"),
+            album_name=data[63:93].strip(b"\0").decode("latin1", "replace"),
+            year=data[93:97].strip(b"\0").decode("latin1", "replace"),
+            genre_code=struct.unpack("B", data[127:128])[0],
+        )
+
+        # Handle ID3v1.1 track number in comment field
+        try:
+            comment = data[97:127]
+
+            # Check for ID3v1.1 track number format (bytes 125-126)
+            if (
+                len(comment) >= ID3V1_MIN_COMMENT_LENGTH_FOR_TRACK_NUMBER
+                and comment[ID3V1_TRACK_NUMBER_POSITION] == 0
+                and comment[ID3V1_TRACK_NUMBER_VALUE_POSITION] != 0
+            ):
+                # ID3v1.1 format: track number in last two bytes
+                tag.track_number = comment[ID3V1_TRACK_NUMBER_VALUE_POSITION]
+                tag.comment = comment[:ID3V1_TRACK_NUMBER_POSITION].strip(b"\0").decode("latin1", "replace")
+            else:
+                # Regular ID3v1 format: no track number
+                tag.track_number = None
+                tag.comment = comment.strip(b"\0").decode("latin1", "replace")
+        except Exception:
+            pass
+
+        # Convert to dictionary format similar to other metadata formats
+        tags_dict: dict[Id3v1RawMetadataKey, list[str]] = {}
+        if tag.title:
+            tags_dict[Id3v1RawMetadataKey.TITLE] = [tag.title]
+        if tag.artists_names_str:
+            tags_dict[Id3v1RawMetadataKey.ARTISTS_NAMES_STR] = [tag.artists_names_str]
+        if tag.album_name:
+            tags_dict[Id3v1RawMetadataKey.ALBUM] = [tag.album_name]
+        if tag.year:
+            tags_dict[Id3v1RawMetadataKey.YEAR] = [tag.year]
+        if tag.genre_code is not None:
+            tags_dict[Id3v1RawMetadataKey.GENRE_CODE_OR_NAME] = [str(tag.genre_code)]
+        if tag.track_number and tag.track_number != 0:
+            tags_dict[Id3v1RawMetadataKey.TRACK_NUMBER] = [str(tag.track_number)]
+        if tag.comment:
+            tags_dict[Id3v1RawMetadataKey.COMMENT] = [tag.comment]
+        object.__setattr__(self, "tags", tags_dict)
+
+    def save(self) -> None:
+        """Save ID3v1 metadata to file using direct file manipulation."""
+        if not self.tags:
+            return
+
+        # Read the entire file
+        if isinstance(self.fileobj, str | Path):  # type: ignore[unreachable]
+            # File path
+            with Path(self.fileobj).open("rb") as f:
+                file_data = bytearray(f.read())
+        else:
+            # File object - use the same pattern as _load_tags
+            self.fileobj.seek(0)
+            file_data = bytearray(self.fileobj.read())
+
+        # Create ID3v1 tag data
+        tag_data = self._create_id3v1_tag_data()
+
+        # Remove existing ID3v1 tag if present
+        self._remove_existing_id3v1_tag(file_data)
+
+        # Append new ID3v1 tag
+        file_data.extend(tag_data)
+
+        # Write back to file
+        if isinstance(self.fileobj, str | Path):
+            # File path
+            with Path(self.fileobj).open("wb") as f:
+                f.write(file_data)
+        else:
+            # File object
+            self.fileobj.seek(0)
+            self.fileobj.write(file_data)
+            self.fileobj.truncate()
+
+    def _create_id3v1_tag_data(self) -> bytes:
+        """Create 128-byte ID3v1 tag data from current tags."""
+        from typing import cast as type_cast
+
+        tags: dict[Id3v1RawMetadataKey, list[str]] = type_cast(dict[Id3v1RawMetadataKey, list[str]], self.tags)
+        if not tags:
+            msg = "Tags must be loaded before creating tag data"
+            raise ValueError(msg)
+        # Initialize with null bytes
+        tag_data = bytearray(ID3V1_TAG_SIZE)
+
+        # TAG identifier (bytes 0-2)
+        tag_data[0:3] = b"TAG"
+
+        # Title (bytes 3-32, 30 chars max)
+        title = tags.get(Id3v1RawMetadataKey.TITLE, [""])[0]
+        title_bytes = self._truncate_string(title, 30).encode("latin-1", errors="ignore")
+        tag_data[3 : 3 + len(title_bytes)] = title_bytes
+
+        # Artist (bytes 33-62, 30 chars max)
+        artist = tags.get(Id3v1RawMetadataKey.ARTISTS_NAMES_STR, [""])[0]
+        artist_bytes = self._truncate_string(artist, 30).encode("latin-1", errors="ignore")
+        tag_data[33 : 33 + len(artist_bytes)] = artist_bytes
+
+        # Album (bytes 63-92, 30 chars max)
+        album = tags.get(Id3v1RawMetadataKey.ALBUM, [""])[0]
+        album_bytes = self._truncate_string(album, 30).encode("latin-1", errors="ignore")
+        tag_data[63 : 63 + len(album_bytes)] = album_bytes
+
+        # Year (bytes 93-96, 4 chars max)
+        year = tags.get(Id3v1RawMetadataKey.YEAR, [""])[0]
+        year_bytes = self._truncate_string(year, 4).encode("latin-1", errors="ignore")
+        tag_data[93 : 93 + len(year_bytes)] = year_bytes
+
+        # Comment and track number (bytes 97-126, 28 chars for comment + 2 for track)
+        comment = tags.get(Id3v1RawMetadataKey.COMMENT, [""])[0]
+        comment_bytes = self._truncate_string(comment, 28).encode("latin-1", errors="ignore")
+        tag_data[97 : 97 + len(comment_bytes)] = comment_bytes
+
+        # Track number (bytes 125-126 for ID3v1.1)
+        track_number = tags.get(Id3v1RawMetadataKey.TRACK_NUMBER, ["0"])[0]
+        if track_number and track_number != "0":
+            track_num = max(0, min(255, int(track_number)))
+            if track_num > 0:
+                tag_data[125] = 0  # Null byte to indicate track number presence
+                tag_data[126] = track_num
+
+        # Genre (byte 127)
+        genre_code = tags.get(Id3v1RawMetadataKey.GENRE_CODE_OR_NAME, ["255"])[0]
+        try:
+            tag_data[127] = int(genre_code)
+        except ValueError:
+            tag_data[127] = 255  # Unknown genre
+
+        return bytes(tag_data)
+
+    def _remove_existing_id3v1_tag(self, file_data: bytearray) -> bool:
+        """Remove existing ID3v1 tag from file data if present.
+
+        Returns:
+            bool: True if a tag was removed, False otherwise
+        """
+        if len(file_data) >= ID3V1_TAG_SIZE:
+            # Check if last 128 bytes contain ID3v1 tag
+            last_128 = file_data[-ID3V1_TAG_SIZE:]
+            if last_128[:3] == b"TAG":
+                # Remove the last 128 bytes
+                del file_data[-ID3V1_TAG_SIZE:]
+                return True
+        return False
+
+    def _truncate_string(self, text: str, max_length: int) -> str:
+        """Truncate string to maximum length, handling encoding properly."""
+        if len(text) <= max_length:
+            return text
+        return text[:max_length]
+
+    @property
+    def mime(self) -> list[str]:
+        """Return a list of MIME types this file type could be."""
+        return ["audio/mpeg"]  # ID3v1 is typically used with MP3 files
+
+    def add_tags(self) -> None:
+        """Add a new ID3v1 tag to the file."""
+        if self.tags is None:
+            object.__setattr__(self, "tags", {})
+
+    def delete(self, filename: str) -> None:
+        """Remove tags from a file."""
+        try:
+            # Read the entire file
+            with Path(filename).open("rb") as f:
+                file_data = bytearray(f.read())
+
+            # Remove existing ID3v1 tag if present
+            if self._remove_existing_id3v1_tag(file_data):
+                # Write back to file
+                with Path(filename).open("wb") as f:
+                    f.write(file_data)
+        except Exception:
+            pass  # Ignore errors during deletion
+
+    @staticmethod
+    def score(_filename: str, _fileobj: Any, _header: Any) -> int:
+        """Return a score indicating how likely this class can handle the file."""
+        return 0  # We don't want this to be auto-detected by mutagen

audiometa/manager/id3v1/id3v1_raw_metadata_key.py

@@ -0,0 +1,13 @@
+from audiometa.utils.unified_metadata_key import UnifiedMetadataKey
+
+from ...utils.types import RawMetadataKey
+
+
+class Id3v1RawMetadataKey(RawMetadataKey):
+    TITLE = UnifiedMetadataKey.TITLE
+    ARTISTS_NAMES_STR = UnifiedMetadataKey.ARTISTS
+    ALBUM = UnifiedMetadataKey.ALBUM
+    GENRE_CODE_OR_NAME = "GENRE_CODE_OR_NAME"
+    YEAR = "YEAR"
+    TRACK_NUMBER = "TRACK_NUMBER"
+    COMMENT = "COMMENT"

audiometa/test/__init__.py

@@ -0,0 +1 @@
+"""Test package for audiometa-python."""

audiometa/test/assets/create_test_files.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+"""Script to create test audio files for testing."""
+
+import subprocess
+from pathlib import Path
+
+
+def create_silent_audio_file(output_path: Path, duration: float = 1.0, sample_rate: int = 44100):
+    """Create a silent audio file using ffmpeg."""
+    try:
+        # Determine codec based on file extension
+        ext = output_path.suffix.lower()
+        if ext == ".mp3":
+            codec = "libmp3lame"
+            bitrate = "128k"
+        elif ext == ".flac":
+            codec = "flac"
+            bitrate = None
+        elif ext == ".wav":
+            codec = "pcm_s16le"
+            bitrate = None
+        else:
+            codec = "libmp3lame"
+            bitrate = "128k"
+
+        cmd = [
+            "ffmpeg",
+            "-f",
+            "lavfi",
+            "-i",
+            f"anullsrc=duration={duration}:sample_rate={sample_rate}",
+            "-c:a",
+            codec,
+            "-y",  # Overwrite output file
+            str(output_path),
+        ]
+
+        if bitrate:
+            cmd.insert(-1, "-b:a")
+            cmd.insert(-1, bitrate)
+
+        subprocess.run(cmd, check=True, capture_output=True)
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return False
+    else:
+        return True
+
+
+def create_test_files():
+    """Create test audio files in different formats."""
+    test_dir = Path(__file__).parent
+    test_dir.mkdir(exist_ok=True)
+
+    # Create different format test files
+    formats = [
+        ("sample.mp3", 1.0),
+        ("sample.flac", 1.0),
+        ("sample.wav", 1.0),
+    ]
+
+    for filename, duration in formats:
+        output_path = test_dir / filename
+        if not output_path.exists():
+            success = create_silent_audio_file(output_path, duration)
+            if not success:
+                pass
+        else:
+            pass
+
+
+if __name__ == "__main__":
+    create_test_files()

audiometa/test/helpers/__init__.py

@@ -0,0 +1,51 @@
+"""Test helpers package for audiometa.
+
+This package provides utilities for creating and managing test files with metadata.
+Classes are organized by metadata format in subdirectories following clean architecture principles.
+
+Main Classes:
+- TempFileWithMetadata: Context manager for test files with comprehensive metadata operations
+  Located in: temp_file_with_metadata.py
+
+Organized by Format:
+
+ID3v1 Format (id3v1/):
+- Id3v1Tool: Wrapper for id3v1 operations using id3v2 tool
+- ID3v1MetadataDeleter: Deleting ID3v1 metadata
+
+ID3v2 Format (id3v2/):
+- ID3v2MetadataVerifier: Verifying ID3v2 metadata
+- ID3v2MetadataSetter: Setting ID3v2 metadata including multiple frame values
+
+- ManualID3v2FrameCreator: Manual binary construction of ID3v2 frames for testing edge cases
+- ID3HeaderVerifier: Verifying ID3v1/ID3v2 headers
+
+Vorbis Format (vorbis/):
+- VorbisMetadataSetter: Setting Vorbis metadata and managing multiple Vorbis comment values
+- VorbisMetadataDeleter: Deleting Vorbis metadata
+- VorbisHeaderVerifier: Verifying Vorbis comment headers and retrieving metadata information
+- VorbisMetadataVerifier: Verifying Vorbis comments
+
+RIFF Format (riff/):
+- RIFFMetadataVerifier: Verifying RIFF metadata
+- RIFFMetadataSetter: Setting RIFF metadata, managing separator-based metadata, and managing multiple RIFF chunk values
+- RIFFMetadataDeleter: Deleting RIFF metadata
+- RIFFHeaderVerifier: Verifying RIFF INFO chunk headers and retrieving metadata information
+
+Common Utilities (common/):
+- AudioFileCreator: Utilities for creating minimal audio files
+- ComprehensiveMetadataVerifier: Cross-format comprehensive verification and header detection
+- run_script: Unified function for running external scripts with proper error handling
+
+Usage:
+    from audiometa.test.helpers.temp_file_with_metadata import TempFileWithMetadata
+    from audiometa.test.helpers.id3v1 import Id3v1Tool, ID3v1MetadataDeleter
+    from audiometa.test.helpers.id3v2 import (
+        ID3v2MetadataVerifier, ID3v2MetadataSetter, ManualID3v2FrameCreator, ID3HeaderVerifier
+    )
+    from audiometa.test.helpers.vorbis import (
+        VorbisMetadataSetter, VorbisMetadataDeleter, VorbisHeaderVerifier, VorbisMetadataVerifier
+    )
+    from audiometa.test.helpers.riff import RIFFMetadataVerifier, RIFFHeaderVerifier
+    from audiometa.test.helpers.common import AudioFileCreator, ComprehensiveMetadataVerifier, run_script
+"""

audiometa/test/helpers/common/__init__.py

@@ -0,0 +1,6 @@
+"""Common utilities for metadata testing."""
+
+from .audio_file_creator import AudioFileCreator
+from .external_tool_runner import run_external_tool, run_script
+
+__all__ = ["AudioFileCreator", "run_external_tool", "run_script"]

audiometa/test/helpers/common/audio_file_creator.py

@@ -0,0 +1,68 @@
+"""Audio file creator utilities for testing."""
+
+import shutil
+import subprocess
+from pathlib import Path
+
+
+class AudioFileCreator:
+    """Utilities for creating minimal audio files for testing."""
+
+    @staticmethod
+    def create_minimal_audio_file(file_path: Path, format_type: str, assets_dir: Path) -> None:
+        """Create a minimal audio file for testing.
+
+        Args:
+            file_path: Path where to create the file
+            format_type: Audio format ('mp3', 'flac', 'wav')
+            assets_dir: Directory containing template files
+        """
+        if format_type.lower() in ["mp3", "id3v1", "id3v2.3", "id3v2.4"]:
+            template_file = assets_dir / "metadata=none.mp3"
+        elif format_type.lower() == "flac":
+            template_file = assets_dir / "metadata=none.flac"
+        elif format_type.lower() == "wav":
+            template_file = assets_dir / "metadata=none.wav"
+        else:
+            msg = f"Unsupported format type: {format_type}"
+            raise ValueError(msg)
+
+        if template_file.exists():
+            # Copy from template
+            shutil.copy2(template_file, file_path)
+        else:
+            # Fallback: create a minimal file using ffmpeg if available
+            try:
+                # For id3v1, id3v2.3, id3v2.4, use mp3 format for ffmpeg
+                actual_format = "mp3" if format_type.lower() in ["id3v1", "id3v2.3", "id3v2.4"] else format_type.lower()
+                AudioFileCreator._create_minimal_audio_with_ffmpeg(file_path, actual_format)
+            except (subprocess.CalledProcessError, FileNotFoundError):
+                # Last resort: copy from any available sample file
+                search_format = "mp3" if format_type.lower() in ["id3v1", "id3v2.3", "id3v2.4"] else format_type.lower()
+                sample_files = list(assets_dir.glob(f"*.{search_format}"))
+                if sample_files:
+                    shutil.copy2(sample_files[0], file_path)
+                else:
+                    msg = f"No template file found for {format_type}"
+                    raise RuntimeError(msg) from None
+
+    @staticmethod
+    def _create_minimal_audio_with_ffmpeg(file_path: Path, format_type: str) -> None:
+        """Create a minimal audio file using ffmpeg."""
+        # Create 1 second of silence
+        cmd = [
+            "ffmpeg",
+            "-f",
+            "lavfi",
+            "-i",
+            "anullsrc=duration=1",
+        ]
+
+        # For WAV, don't specify -acodec as ffmpeg will use the default PCM codec
+        # For other formats, specify the codec
+        if format_type.lower() != "wav":
+            cmd.extend(["-acodec", format_type.lower()])
+
+        cmd.extend(["-y", str(file_path)])
+
+        subprocess.run(cmd, check=True, capture_output=True)

audiometa/test/helpers/common/external_tool_runner.py

@@ -0,0 +1,74 @@
+"""Unified utility for running external tools and scripts with consistent error handling."""
+
+import subprocess
+from pathlib import Path
+
+
+class ExternalMetadataToolError(Exception):
+    """Exception raised when external metadata tools fail."""
+
+
+def run_external_tool(
+    command: list[str], tool_name: str = "external tool", check: bool = True, input_data: str | bytes | None = None
+) -> subprocess.CompletedProcess:
+    """Run an external tool command with proper error handling.
+
+    Args:
+        command: List of command and arguments to execute
+        tool_name: Name of the tool for error messages (e.g., "metaflac", "mid3v2")
+        check: Whether to raise exception on non-zero exit code
+        input_data: Optional input to pass to stdin
+
+    Returns:
+        subprocess.CompletedProcess: The result of the command execution
+
+    Raises:
+        ExternalMetadataToolError: If the command fails or tool is not found
+    """
+    try:
+        text = not isinstance(input_data, bytes) if input_data is not None else True
+        return subprocess.run(command, capture_output=True, text=text, check=check, input=input_data)
+    except (subprocess.CalledProcessError, FileNotFoundError) as e:
+        msg = f"{tool_name} failed: {e}"
+        raise ExternalMetadataToolError(msg) from e
+
+
+def run_script(
+    script_path: str | Path, target_file: str | Path, scripts_dir: str | Path | None = None
+) -> subprocess.CompletedProcess:
+    """Run a shell script with proper error handling and permissions.
+
+    Convenience wrapper around run_external_tool for script execution.
+
+    Args:
+        script_path: Path to the script file, or script name if scripts_dir is provided
+        target_file: File to pass as argument to the script
+        scripts_dir: Directory containing scripts (optional, if script_path is relative)
+
+    Returns:
+        subprocess.CompletedProcess: The result of the script execution
+
+    Raises:
+        FileNotFoundError: If the script file doesn't exist
+        ExternalMetadataToolError: If the script execution fails
+    """
+    # Resolve script path
+    full_script_path = Path(scripts_dir) / script_path if scripts_dir is not None else Path(script_path)
+
+    # Validate script exists
+    if not full_script_path.exists():
+        msg = f"Script not found: {full_script_path}"
+        raise FileNotFoundError(msg)
+
+    if not full_script_path.is_file():
+        msg = f"Script is not a file: {full_script_path}"
+        raise FileNotFoundError(msg)
+
+    # Make script executable
+    full_script_path.chmod(0o755)
+
+    # Run script using the unified external tool runner
+    script_name = full_script_path.name
+    command = [str(full_script_path), str(target_file)]
+
+    return run_external_tool(command, f"script {script_name}")

audiometa/test/helpers/id3v1/__init__.py

@@ -0,0 +1,8 @@
+"""ID3v1 metadata format helpers."""
+
+from .id3v1_header_verifier import ID3v1HeaderVerifier
+from .id3v1_metadata_deleter import ID3v1MetadataDeleter
+from .id3v1_metadata_getter import ID3v1MetadataGetter
+from .id3v1_metadata_setter import ID3v1MetadataSetter
+
+__all__ = ["ID3v1MetadataDeleter", "ID3v1MetadataSetter", "ID3v1HeaderVerifier", "ID3v1MetadataGetter"]

audiometa/test/helpers/id3v1/id3v1_header_verifier.py

@@ -0,0 +1,18 @@
+"""ID3v1 metadata header verification utilities."""
+
+from pathlib import Path
+
+
+class ID3v1HeaderVerifier:
+    """Utilities for verifying ID3v1 metadata headers in audio files."""
+
+    @staticmethod
+    def has_id3v1_header(file_path: Path) -> bool:
+        """Check if file has ID3v1 header by reading the last 128 bytes."""
+        try:
+            with file_path.open("rb") as f:
+                f.seek(-128, 2)  # Seek to last 128 bytes
+                header = f.read(128)
+                return header[:3] == b"TAG"
+        except OSError:
+            return False

audiometa/test/helpers/id3v1/id3v1_metadata_deleter.py

@@ -0,0 +1,37 @@
+"""ID3v1 metadata deletion operations."""
+
+from pathlib import Path
+
+from ..common.external_tool_runner import ExternalMetadataToolError, run_external_tool
+
+
+class ID3v1MetadataDeleter:
+    """Static utility class for ID3v1 metadata deletion using external tools."""
+
+    @staticmethod
+    def delete_tag(file_path: Path, tag_name: str) -> None:
+        try:
+            command = ["id3v2", "--id3v1-only", "--delete", tag_name, str(file_path)]
+            run_external_tool(command, "id3v2")
+        except ExternalMetadataToolError:
+            pass
+
+    @staticmethod
+    def delete_comment(file_path: Path) -> None:
+        ID3v1MetadataDeleter.delete_tag(file_path, "COMM")
+
+    @staticmethod
+    def delete_title(file_path: Path) -> None:
+        ID3v1MetadataDeleter.delete_tag(file_path, "TIT2")
+
+    @staticmethod
+    def delete_artist(file_path: Path) -> None:
+        ID3v1MetadataDeleter.delete_tag(file_path, "TPE1")
+
+    @staticmethod
+    def delete_album(file_path: Path) -> None:
+        ID3v1MetadataDeleter.delete_tag(file_path, "TALB")
+
+    @staticmethod
+    def delete_genre(file_path: Path) -> None:
+        ID3v1MetadataDeleter.delete_tag(file_path, "TCON")

audiometa/test/helpers/id3v1/id3v1_metadata_getter.py

@@ -0,0 +1,61 @@
+"""ID3v1 metadata inspection utilities for testing audio file metadata."""
+
+from pathlib import Path
+from typing import Any
+
+
+class ID3v1MetadataGetter:
+    """Utilities for inspecting ID3v1 metadata in audio files."""
+
+    @staticmethod
+    def get_raw_metadata(file_path: Path) -> dict[str, Any]:
+        """Return the raw metadata for a specific ID3v1 field."""
+        with file_path.open("rb") as f:
+            f.seek(-128, 2)  # Seek to last 128 bytes (ID3v1 tag location)
+            data = f.read(128)
+
+        # Check for ID3v1 tag header
+        if not data.startswith(b"TAG"):
+            return {}
+
+        # Determine if it's ID3v1.1 (has track number)
+        is_id3v1_1 = data[125] != 0
+
+        # Parse fields based on ID3v1 specification
+        field_info = {
+            "title": (3, 33, 30),  # bytes 3-32, 30 chars max
+            "artist": (33, 63, 30),  # bytes 33-62, 30 chars max
+            "album": (63, 93, 30),  # bytes 63-92, 30 chars max
+            "year": (93, 97, 4),  # bytes 93-96, 4 chars max
+            "genre": (127, 128, 1),  # byte 127
+        }
+
+        if is_id3v1_1:
+            field_info["comment"] = (97, 125, 28)  # bytes 97-124, 28 chars max (ID3v1.1)
+            field_info["track"] = (125, 126, 1)  # byte 125 (ID3v1.1)
+        else:
+            field_info["comment"] = (97, 127, 30)  # bytes 97-126, 30 chars max (ID3v1)
+
+        metadata: dict[str, str | int | None] = {}
+        for field, (start, end, _max_chars) in field_info.items():
+            raw_bytes = data[start:end]
+            if field in ["title", "artist", "album", "year", "comment"]:
+                metadata[field] = raw_bytes.decode("latin-1").rstrip("\x00")
+            elif field == "track":
+                metadata[field] = raw_bytes[0] if raw_bytes and raw_bytes[0] != 0 else None
+            elif field == "genre":
+                metadata[field] = raw_bytes[0] if raw_bytes else 0
+
+        # Handle ID3v1 track number stored in comment field (non-standard but common)
+        if "track" not in metadata or metadata["track"] is None:
+            comment = metadata.get("comment", "")
+            if isinstance(comment, str) and len(comment) == 30 and comment[-1] != "\x00":
+                metadata["track"] = ord(comment[-1])
+                metadata["comment"] = comment[:-1].rstrip("\x00")
+
+        return metadata
+
+    @staticmethod
+    def get_title(file_path):
+        metadata = ID3v1MetadataGetter.get_raw_metadata(file_path)
+        return metadata.get("title", "")