audiometa-python 0.6.1__tar.gz → 0.8.0__tar.gz

{audiometa_python-0.6.1/audiometa_python.egg-info → audiometa_python-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: audiometa-python
-Version: 0.6.1
+Version: 0.8.0
 Summary: A comprehensive Python library for reading and writing audio metadata across multiple formats
 Author: AudioMeta Python Contributors
 Author-email: Andreas Garcia <garcia.andreas.1991@gmail.com>

{audiometa_python-0.6.1 → audiometa_python-0.8.0}/audiometa/__init__.py

@@ -30,6 +30,7 @@ from .manager._rating_supporting.id3v2._Id3v2Manager import _Id3v2Manager
 from .manager._rating_supporting.riff._RiffManager import _RiffManager
 from .manager._rating_supporting.vorbis._VorbisManager import _VorbisManager
 from .manager.id3v1._Id3v1Manager import _Id3v1Manager
+from .utils.flac_md5_state import FlacMd5State
 from .utils.metadata_format import MetadataFormat
 from .utils.metadata_writing_strategy import MetadataWritingStrategy
 from .utils.types import UnifiedMetadata, UnifiedMetadataValue
@@ -552,6 +553,7 @@ def update_metadata(
     metadata_strategy: MetadataWritingStrategy | None = None,
     metadata_format: MetadataFormat | None = None,
     fail_on_unsupported_field: bool = False,
+    warn_on_unsupported_field: bool = True,
 ) -> None:
     """Update metadata in an audio file.
 
@@ -574,6 +576,9 @@ def update_metadata(
             If False (default), unsupported fields are filtered out with individual warnings for each field.
             For SYNC strategy, this applies per-format: unsupported fields are skipped for each format that
             doesn't support them, while still syncing all supported fields.
+        warn_on_unsupported_field: If True (default), issues warnings when unsupported fields are encountered.
+            If False, suppresses warnings about unsupported fields. Automatically set to False when
+            fail_on_unsupported_field is True.
 
     Returns:
         None
@@ -599,8 +604,9 @@ def update_metadata(
 
         When metadata_strategy is used, unsupported metadata fields are handled based on the
         fail_on_unsupported_field parameter: True raises MetadataFieldNotSupportedByMetadataFormatError, False (default)
-        filters unsupported fields and warns about each one individually. For SYNC strategy, unsupported fields
-        are skipped per-format, allowing supported fields to sync while warning about unsupported ones.
+        filters unsupported fields and warns about each one individually (unless warn_on_unsupported_field is False).
+        For SYNC strategy, unsupported fields are skipped per-format, allowing supported fields to sync while warning
+        about unsupported ones.
 
         Data Filtering:
         For list-type metadata fields (e.g., ARTISTS, GENRES), empty strings and None values
@@ -641,6 +647,9 @@ def update_metadata(
         }
         # Results in: ["Artist 1", "Artist 2"] - empty strings and None filtered out
         update_metadata("song.mp3", metadata)
+
+        # Suppress warnings about unsupported fields
+        update_metadata("song.mp3", metadata, warn_on_unsupported_field=False)
     """
     audio_file = _AudioFile(file)
 
@@ -654,6 +663,11 @@ def update_metadata(
         )
         raise MetadataWritingConflictParametersError(msg)
 
+    # Automatically disable warnings when failing on unsupported fields
+    # This provides a more intuitive API where fail takes precedence over warn
+    if fail_on_unsupported_field:
+        warn_on_unsupported_field = False
+
     # Default to SYNC strategy if not specified
     if metadata_strategy is None:
         metadata_strategy = MetadataWritingStrategy.SYNC
@@ -676,6 +690,7 @@ def update_metadata(
         id3v2_version,
         metadata_format,
         fail_on_unsupported_field,
+        warn_on_unsupported_field,
     )
 
 
@@ -687,6 +702,7 @@ def _handle_metadata_strategy(
     id3v2_version: tuple[int, int, int] | None,
     target_format: MetadataFormat | None = None,
     fail_on_unsupported_field: bool = False,
+    warn_on_unsupported_field: bool = True,
 ) -> None:
     """Handle metadata strategy-specific behavior for all strategies."""
 
@@ -742,11 +758,12 @@ def _handle_metadata_strategy(
                 msg = f"Fields not supported by {target_format_actual.value} format: {unsupported_fields}"
                 raise MetadataFieldNotSupportedByMetadataFormatError(msg)
             # Warn about each unsupported field individually
-            for unsupported_field in unsupported_fields:
-                field_warn_msg = (
-                    f"Field {unsupported_field} not supported by {target_format_actual.value} format, skipped"
-                )
-                warnings.warn(field_warn_msg, stacklevel=2)
+            if warn_on_unsupported_field:
+                for unsupported_field in unsupported_fields:
+                    field_warn_msg = (
+                        f"Field {unsupported_field} not supported by {target_format_actual.value} format, skipped"
+                    )
+                    warnings.warn(field_warn_msg, stacklevel=2)
             # Create filtered metadata without unsupported fields
             filtered_metadata = {k: v for k, v in unified_metadata.items() if k not in unsupported_fields}
             unified_metadata = filtered_metadata
@@ -783,11 +800,12 @@ def _handle_metadata_strategy(
                     unsupported_fields.append(field)
             if unsupported_fields:
                 # Warn about each unsupported field individually for target format
-                for unsupported_field in unsupported_fields:
-                    field_warn_msg = (
-                        f"Field {unsupported_field} not supported by {target_format_actual.value} format, skipped"
-                    )
-                    warnings.warn(field_warn_msg, stacklevel=2)
+                if warn_on_unsupported_field:
+                    for unsupported_field in unsupported_fields:
+                        field_warn_msg = (
+                            f"Field {unsupported_field} not supported by {target_format_actual.value} format, skipped"
+                        )
+                        warnings.warn(field_warn_msg, stacklevel=2)
                 # Create filtered metadata without unsupported fields
                 filtered_metadata = {k: v for k, v in unified_metadata.items() if k not in unsupported_fields}
                 unified_metadata = filtered_metadata
@@ -798,8 +816,9 @@ def _handle_metadata_strategy(
             target_manager.update_metadata(unified_metadata)
         except MetadataFieldNotSupportedByMetadataFormatError as e:
             # For SYNC strategy, log warning but continue with other formats
-            format_warn_msg = f"Format {target_format_actual} doesn't support some metadata fields: {e}"
-            warnings.warn(format_warn_msg, stacklevel=2)
+            if warn_on_unsupported_field:
+                format_warn_msg = f"Format {target_format_actual} doesn't support some metadata fields: {e}"
+                warnings.warn(format_warn_msg, stacklevel=2)
         except Exception as e:
             # Re-raise user errors (like InvalidRatingValueError) immediately
             from .exceptions import ConfigurationError, InvalidRatingValueError
@@ -827,9 +846,10 @@ def _handle_metadata_strategy(
             )
 
             # Warn about each unsupported field individually for non-target formats
-            for unsupported_field in unsupported_fields:
-                field_warn_msg = f"Field {unsupported_field} not supported by {fmt_name} format, skipped"
-                warnings.warn(field_warn_msg, stacklevel=2)
+            if warn_on_unsupported_field:
+                for unsupported_field in unsupported_fields:
+                    field_warn_msg = f"Field {unsupported_field} not supported by {fmt_name} format, skipped"
+                    warnings.warn(field_warn_msg, stacklevel=2)
 
             # Try to update with supported fields only
             if format_metadata:  # Only update if there are supported fields
@@ -867,7 +887,8 @@ def _handle_metadata_strategy(
             unsupported_warn_msg = (
                 f"Fields not supported by {target_format_actual.value} format will be skipped: {unsupported_fields}"
             )
-            warnings.warn(unsupported_warn_msg, stacklevel=2)
+            if warn_on_unsupported_field:
+                warnings.warn(unsupported_warn_msg, stacklevel=2)
             # Create filtered metadata without unsupported fields
             filtered_metadata = {k: v for k, v in unified_metadata.items() if k not in unsupported_fields}
             unified_metadata = filtered_metadata
@@ -1106,8 +1127,8 @@ def get_duration_in_sec(file: PublicFileType) -> float:
     return audio_file.get_duration_in_sec()
 
 
-def is_flac_md5_valid(file: PublicFileType) -> bool:
-    """Check if a FLAC file's MD5 signature is valid.
+def is_flac_md5_valid(file: PublicFileType) -> FlacMd5State:
+    """Check the MD5 checksum validation state of a FLAC file.
 
     This function verifies the integrity of a FLAC file by checking its MD5 signature.
     Only works with FLAC files.
@@ -1116,17 +1137,27 @@ def is_flac_md5_valid(file: PublicFileType) -> bool:
         file: Audio file path (str or Path; must be FLAC)
 
     Returns:
-        True if MD5 signature is valid, False otherwise
+        FlacMd5State indicating the validation state:
+        - FlacMd5State.VALID: MD5 is set and matches the audio data
+        - FlacMd5State.UNSET: MD5 is all zeros (not set)
+        - FlacMd5State.UNCHECKABLE_DUE_TO_ID3V1: MD5 is set but cannot be validated due to ID3v1 tags
+        - FlacMd5State.INVALID: MD5 is set but doesn't match the audio data (corrupted)
 
     Raises:
         FileTypeNotSupportedError: If the file is not a FLAC file
         FileNotFoundError: If the file does not exist
 
     Examples:
+        from audiometa import is_flac_md5_valid, FlacMd5State
+
         # Check FLAC file integrity
-        is_valid = is_flac_md5_valid("song.flac")
-        if is_valid:
+        state = is_flac_md5_valid("song.flac")
+        if state == FlacMd5State.VALID:
             print("FLAC file is intact")
+        elif state == FlacMd5State.UNSET:
+            print("MD5 checksum is not set")
+        elif state == FlacMd5State.UNCHECKABLE_DUE_TO_ID3V1:
+            print("MD5 cannot be validated due to ID3v1 tags")
         else:
             print("FLAC file may be corrupted")
     """
@@ -1134,7 +1165,7 @@ def is_flac_md5_valid(file: PublicFileType) -> bool:
     try:
         return audio_file.is_flac_file_md5_valid()
     except FileCorruptedError:
-        return False
+        return FlacMd5State.INVALID
 
 
 def fix_md5_checking(file: PublicFileType) -> str:
@@ -1237,7 +1268,9 @@ def get_full_metadata(
                 "file_extension": audio_file.file_extension,
                 "audio_format_name": audio_file.get_audio_format_name(),
                 "is_flac_md5_valid": (
-                    audio_file.is_flac_file_md5_valid() if audio_file.file_extension == ".flac" else None
+                    audio_file.is_flac_file_md5_valid() == FlacMd5State.VALID
+                    if audio_file.file_extension == ".flac"
+                    else None
                 ),
             }
         except Exception:

{audiometa_python-0.6.1 → audiometa_python-0.8.0}/audiometa/_audio_file.py

@@ -5,6 +5,7 @@ import json
 import subprocess
 import tempfile
 import types
+import warnings
 from pathlib import Path
 from typing import cast
 
@@ -23,6 +24,7 @@ from .exceptions import (
 )
 from .manager._rating_supporting.id3v2._id3v2_constants import ID3V2_HEADER_SIZE
 from .manager._rating_supporting.riff._riff_constants import RIFF_HEADER_SIZE
+from .utils.flac_md5_state import FlacMd5State
 from .utils.metadata_format import MetadataFormat
 from .utils.mutagen_exception_handler import handle_mutagen_exception
 from .utils.tool_path_resolver import get_tool_path
@@ -280,14 +282,31 @@ class _AudioFile:
         except Exception:
             return False
 
-    def is_flac_file_md5_valid(self) -> bool:
+    def _has_id3v1_tags(self) -> bool:
+        """Check if FLAC file has ID3v1 tags.
+
+        Only ID3v1 tags cause validation failures, so we only need to check for ID3v1.
+        ID3v2 tags do not interfere with flac -t validation.
+        """
+        try:
+            with Path(self.file_path).open("rb") as f:
+                # Check for ID3v1 at the end (last 128 bytes)
+                f.seek(-128, 2)
+                id3v1_header = f.read(3)
+                return id3v1_header == b"TAG"
+        except Exception:
+            return False
+
+    def is_flac_file_md5_valid(self) -> FlacMd5State:
         if self.file_extension != ".flac":
             msg = "The file is not a FLAC file"
             raise FileTypeNotSupportedError(msg)
 
+        # Check if MD5 is unset (all zeros)
         if self._is_md5_unset():
-            return False
+            return FlacMd5State.UNSET
 
+        # Run flac -t to validate MD5
         result = subprocess.run([get_tool_path("flac"), "-t", self.file_path], capture_output=True, check=False)
 
         # Combine stdout and stderr as flac may output to either
@@ -295,20 +314,26 @@ class _AudioFile:
         stderr_output = result.stderr.decode()
         combined_output = stdout_output + stderr_output
 
-        # flac -t returns 0 on success, non-zero on error
-        # If return code is non-zero, the file is invalid
-        if result.returncode != 0:
-            return False
+        # Check for explicit success message
+        if result.returncode == 0 and "ok" in combined_output.lower():
+            return FlacMd5State.VALID
+
+        # Check for ID3v1-related errors when ID3v1 tags are present
+        has_id3v1 = self._has_id3v1_tags()
+        if has_id3v1 and "FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC" in combined_output:
+            return FlacMd5State.UNCHECKABLE_DUE_TO_ID3V1
 
-        # Check for explicit error messages (shouldn't happen with return code 0, but defensive)
+        # Check for explicit MD5 mismatch (corruption)
         if "MD5 signature mismatch" in combined_output:
-            return False
-        if "FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC" in combined_output:
-            return False
+            return FlacMd5State.INVALID
 
-        # Check for explicit success message
-        if "ok" in combined_output.lower():
-            return True
+        # If flac -t failed and we have ID3v1 tags, it's likely due to ID3v1 interference
+        if has_id3v1 and result.returncode != 0:
+            return FlacMd5State.UNCHECKABLE_DUE_TO_ID3V1
+
+        # If return code is non-zero and no specific error message, assume invalid
+        if result.returncode != 0:
+            return FlacMd5State.INVALID
 
         # If return code was 0 but no "ok" found, something unexpected happened
         msg = "The Flac file md5 check failed"
@@ -332,6 +357,16 @@ class _AudioFile:
             msg = "The file is not a FLAC file"
             raise FileTypeNotSupportedError(msg)
 
+        # Warn if ID3v1 tags will be removed during re-encoding
+        if self._has_id3v1_tags():
+            warnings.warn(
+                "ID3v1 tags detected in FLAC file. These tags will be removed during MD5 repair "
+                "as they are non-standard in FLAC format and interfere with integrity validation. "
+                "Consider backing up ID3v1 metadata before repair if you need to preserve it.",
+                UserWarning,
+                stacklevel=3,
+            )
+
         # Create a temporary file to store the corrected FLAC content
         temp_file = tempfile.NamedTemporaryFile(delete=False, suffix=".flac")
         temp_path = temp_file.name

{audiometa_python-0.6.1/audiometa/test/tests/integration/technical_info/flac_md5/test_invalid_md5 → audiometa_python-0.8.0/audiometa/test/tests/integration/technical_info/flac_md5/md5_checking}/test_audio_data_corruption.py

@@ -1,6 +1,6 @@
 import pytest
 
-from audiometa import is_flac_md5_valid
+from audiometa import FlacMd5State, is_flac_md5_valid
 from audiometa.test.helpers.temp_file_with_metadata import temp_file_with_metadata
 from audiometa.test.tests.integration.technical_info.flac_md5.conftest import corrupt_audio_data, ensure_flac_has_md5
 
@@ -18,4 +18,5 @@ class TestAudioDataCorruption:
             # If the decoded PCM is unchanged, the MD5 will still match (correct behavior).
             # Manual MD5 verification works correctly - it will detect when MD5 doesn't match PCM.
             # This test verifies the function handles this scenario gracefully.
-            assert isinstance(result, bool)
+            assert isinstance(result, FlacMd5State)
+            assert result in [FlacMd5State.VALID, FlacMd5State.INVALID]

audiometa_python-0.8.0/audiometa/test/tests/integration/technical_info/flac_md5/md5_checking/test_file.py

@@ -0,0 +1,33 @@
+from pathlib import Path
+
+import pytest
+
+from audiometa import FlacMd5State, is_flac_md5_valid
+from audiometa.exceptions import FileTypeNotSupportedError
+
+
+@pytest.mark.integration
+class TestValidFlacMd5:
+    def test_is_flac_md5_valid_works_with_path_string(self, sample_flac_file: Path):
+        state = is_flac_md5_valid(str(sample_flac_file))
+        assert isinstance(state, FlacMd5State)
+        assert state in [
+            FlacMd5State.VALID,
+            FlacMd5State.UNSET,
+            FlacMd5State.UNCHECKABLE_DUE_TO_ID3V1,
+            FlacMd5State.INVALID,
+        ]
+
+    def test_is_flac_md5_valid_works_with_pathlib_path(self, sample_flac_file: Path):
+        state = is_flac_md5_valid(sample_flac_file)
+        assert isinstance(state, FlacMd5State)
+        assert state in [
+            FlacMd5State.VALID,
+            FlacMd5State.UNSET,
+            FlacMd5State.UNCHECKABLE_DUE_TO_ID3V1,
+            FlacMd5State.INVALID,
+        ]
+
+    def test_is_flac_md5_valid_non_flac(self, sample_mp3_file: Path):
+        with pytest.raises(FileTypeNotSupportedError):
+            is_flac_md5_valid(sample_mp3_file)

audiometa_python-0.8.0/audiometa/test/tests/integration/technical_info/flac_md5/md5_checking/test_invalid_md5.py

@@ -0,0 +1,35 @@
+"""Test invalid MD5 validation."""
+
+import pytest
+
+from audiometa import FlacMd5State, is_flac_md5_valid
+from audiometa.test.helpers.temp_file_with_metadata import temp_file_with_metadata
+from audiometa.test.tests.integration.technical_info.flac_md5.conftest import corrupt_md5, ensure_flac_has_md5
+
+
+@pytest.mark.integration
+class TestInvalidMd5:
+    def test_is_flac_md5_valid_detects_random_md5_corruption(self):
+        with temp_file_with_metadata({}, "flac") as test_file:
+            ensure_flac_has_md5(test_file)
+            corrupt_md5(test_file, "random")
+
+            assert (
+                is_flac_md5_valid(test_file) == FlacMd5State.INVALID
+            ), "Random MD5 corruption should be detected as INVALID"
+
+    def test_is_flac_md5_valid_detects_partial_md5_corruption(self):
+        with temp_file_with_metadata({}, "flac") as test_file:
+            ensure_flac_has_md5(test_file)
+            corrupt_md5(test_file, "partial")
+
+            assert (
+                is_flac_md5_valid(test_file) == FlacMd5State.INVALID
+            ), "Partially corrupted MD5 should be detected as INVALID"
+
+    def test_is_flac_md5_valid_detects_flipped_md5(self):
+        with temp_file_with_metadata({}, "flac") as test_file:
+            ensure_flac_has_md5(test_file)
+            corrupt_md5(test_file, "flip_all")
+
+            assert is_flac_md5_valid(test_file) == FlacMd5State.INVALID, "Flipped MD5 should be detected as INVALID"

audiometa_python-0.8.0/audiometa/test/tests/integration/technical_info/flac_md5/md5_checking/test_metadata_combinations/test_md5_invalid_with_metadata_combinations.py

@@ -0,0 +1,101 @@
+"""Test INVALID MD5 state with metadata format combinations that support validation."""
+
+import pytest
+
+from audiometa import FlacMd5State, is_flac_md5_valid
+from audiometa.test.helpers.id3v1 import ID3v1MetadataSetter
+from audiometa.test.helpers.id3v2 import ID3v2MetadataSetter
+from audiometa.test.helpers.temp_file_with_metadata import temp_file_with_metadata
+from audiometa.test.helpers.vorbis import VorbisMetadataSetter
+from audiometa.test.tests.integration.technical_info.flac_md5.conftest import corrupt_md5, ensure_flac_has_md5
+
+
+@pytest.mark.integration
+class TestMd5InvalidWithMetadataCombinations:
+    """Test INVALID MD5 state with metadata format combinations that support validation."""
+
+    def test_invalid_md5_no_metadata(self):
+        """Test INVALID state with no metadata."""
+        with temp_file_with_metadata({}, "flac") as test_file:
+            ensure_flac_has_md5(test_file)
+            corrupt_md5(test_file, "random")
+            state = is_flac_md5_valid(test_file)
+            assert state == FlacMd5State.INVALID, "Clean FLAC with invalid MD5 should return INVALID"
+
+    def test_invalid_md5_vorbis_only(self):
+        """Test INVALID state with Vorbis metadata only."""
+        with temp_file_with_metadata({}, "flac") as test_file:
+            ensure_flac_has_md5(test_file)
+            VorbisMetadataSetter.add_title(test_file, "Vorbis Title")
+            corrupt_md5(test_file, "random")
+            state = is_flac_md5_valid(test_file)
+            assert state == FlacMd5State.INVALID, "FLAC with Vorbis metadata and invalid MD5 should return INVALID"
+
+    def test_invalid_md5_id3v2_only(self):
+        """Test INVALID state with ID3v2 metadata only."""
+        with temp_file_with_metadata({}, "flac") as test_file:
+            ensure_flac_has_md5(test_file)
+            ID3v2MetadataSetter.set_metadata(test_file, {"title": "ID3v2 Title"})
+            corrupt_md5(test_file, "random")
+            state = is_flac_md5_valid(test_file)
+            assert state == FlacMd5State.INVALID, "FLAC with ID3v2 metadata and invalid MD5 should return INVALID"
+
+    def test_invalid_md5_vorbis_and_id3v2(self):
+        """Test INVALID state with Vorbis and ID3v2 metadata."""
+        with temp_file_with_metadata({}, "flac") as test_file:
+            ensure_flac_has_md5(test_file)
+            VorbisMetadataSetter.add_title(test_file, "Vorbis Title")
+            ID3v2MetadataSetter.set_metadata(test_file, {"title": "ID3v2 Title"})
+            corrupt_md5(test_file, "random")
+            state = is_flac_md5_valid(test_file)
+            assert (
+                state == FlacMd5State.INVALID
+            ), "FLAC with Vorbis and ID3v2 metadata and invalid MD5 should return INVALID"
+
+    def test_invalid_md5_with_id3v1_returns_uncheckable(self):
+        """Test that invalid MD5 with ID3v1 returns UNCHECKABLE_DUE_TO_ID3, not INVALID."""
+        with temp_file_with_metadata({}, "flac") as test_file:
+            ensure_flac_has_md5(test_file)
+            ID3v1MetadataSetter.set_title(test_file, "ID3v1 Title")
+            corrupt_md5(test_file, "random")
+            state = is_flac_md5_valid(test_file)
+            assert (
+                state == FlacMd5State.UNCHECKABLE_DUE_TO_ID3V1
+            ), "FLAC with ID3v1 should return UNCHECKABLE_DUE_TO_ID3 even if MD5 corrupted (ID3v1 takes precedence)"
+
+    def test_invalid_md5_vorbis_and_id3v1_returns_uncheckable(self):
+        """Test that invalid MD5 with Vorbis and ID3v1 returns UNCHECKABLE_DUE_TO_ID3."""
+        with temp_file_with_metadata({}, "flac") as test_file:
+            ensure_flac_has_md5(test_file)
+            VorbisMetadataSetter.add_title(test_file, "Vorbis Title")
+            ID3v1MetadataSetter.set_title(test_file, "ID3v1 Title")
+            corrupt_md5(test_file, "random")
+            state = is_flac_md5_valid(test_file)
+            assert (
+                state == FlacMd5State.UNCHECKABLE_DUE_TO_ID3V1
+            ), "FLAC with Vorbis and ID3v1 metadata should return UNCHECKABLE_DUE_TO_ID3 (ID3v1 takes precedence)"
+
+    def test_invalid_md5_id3v1_and_id3v2_returns_uncheckable(self):
+        """Test that invalid MD5 with ID3v1 and ID3v2 returns UNCHECKABLE_DUE_TO_ID3."""
+        with temp_file_with_metadata({}, "flac") as test_file:
+            ensure_flac_has_md5(test_file)
+            ID3v1MetadataSetter.set_title(test_file, "ID3v1 Title")
+            ID3v2MetadataSetter.set_metadata(test_file, {"title": "ID3v2 Title"})
+            corrupt_md5(test_file, "random")
+            state = is_flac_md5_valid(test_file)
+            assert (
+                state == FlacMd5State.UNCHECKABLE_DUE_TO_ID3V1
+            ), "FLAC with ID3v1 and ID3v2 metadata should return UNCHECKABLE_DUE_TO_ID3 (ID3v1 takes precedence)"
+
+    def test_invalid_md5_all_formats_returns_uncheckable(self):
+        """Test that invalid MD5 with all metadata formats returns UNCHECKABLE_DUE_TO_ID3."""
+        with temp_file_with_metadata({}, "flac") as test_file:
+            ensure_flac_has_md5(test_file)
+            VorbisMetadataSetter.add_title(test_file, "Vorbis Title")
+            ID3v1MetadataSetter.set_title(test_file, "ID3v1 Title")
+            ID3v2MetadataSetter.set_metadata(test_file, {"title": "ID3v2 Title"})
+            corrupt_md5(test_file, "random")
+            state = is_flac_md5_valid(test_file)
+            assert (
+                state == FlacMd5State.UNCHECKABLE_DUE_TO_ID3V1
+            ), "FLAC with all metadata formats should return UNCHECKABLE_DUE_TO_ID3 (ID3v1 takes precedence)"

audiometa_python-0.8.0/audiometa/test/tests/integration/technical_info/flac_md5/md5_checking/test_metadata_combinations/test_md5_state_precedence.py

@@ -0,0 +1,39 @@
+"""Test that state detection follows correct precedence rules for MD5 validation."""
+
+import pytest
+
+from audiometa import FlacMd5State, is_flac_md5_valid
+from audiometa.test.helpers.id3v1 import ID3v1MetadataSetter
+from audiometa.test.helpers.temp_file_with_metadata import temp_file_with_metadata
+from audiometa.test.tests.integration.technical_info.flac_md5.conftest import (
+    corrupt_md5,
+    create_flac_without_md5,
+    ensure_flac_has_md5,
+)
+
+
+@pytest.mark.integration
+class TestMd5StatePrecedence:
+    """Test that state detection follows correct precedence rules."""
+
+    def test_unset_takes_precedence_over_uncheckable(self):
+        """Test that UNSET state takes precedence over UNCHECKABLE_DUE_TO_ID3."""
+        with temp_file_with_metadata({}, "flac") as test_file:
+            ensure_flac_has_md5(test_file)
+            ID3v1MetadataSetter.set_title(test_file, "ID3v1 Title")
+            create_flac_without_md5(test_file)
+            state = is_flac_md5_valid(test_file)
+            assert (
+                state == FlacMd5State.UNSET
+            ), "UNSET should take precedence over UNCHECKABLE_DUE_TO_ID3 when MD5 is unset"
+
+    def test_uncheckable_takes_precedence_over_invalid_when_id3v1_present(self):
+        """Test that UNCHECKABLE_DUE_TO_ID3 takes precedence over INVALID when ID3v1 is present."""
+        with temp_file_with_metadata({}, "flac") as test_file:
+            ensure_flac_has_md5(test_file)
+            ID3v1MetadataSetter.set_title(test_file, "ID3v1 Title")
+            corrupt_md5(test_file, "random")
+            state = is_flac_md5_valid(test_file)
+            assert (
+                state == FlacMd5State.UNCHECKABLE_DUE_TO_ID3V1
+            ), "UNCHECKABLE_DUE_TO_ID3 should take precedence over INVALID when ID3v1 is present"

audiometa_python-0.8.0/audiometa/test/tests/integration/technical_info/flac_md5/md5_checking/test_metadata_combinations/test_md5_unset_with_metadata_combinations.py

@@ -0,0 +1,101 @@
+"""Test UNSET MD5 state with all metadata format combinations."""
+
+import pytest
+
+from audiometa import FlacMd5State, is_flac_md5_valid
+from audiometa.test.helpers.id3v1 import ID3v1MetadataSetter
+from audiometa.test.helpers.id3v2 import ID3v2MetadataSetter
+from audiometa.test.helpers.temp_file_with_metadata import temp_file_with_metadata
+from audiometa.test.helpers.vorbis import VorbisMetadataSetter
+from audiometa.test.tests.integration.technical_info.flac_md5.conftest import (
+    create_flac_without_md5,
+    ensure_flac_has_md5,
+)
+
+
+@pytest.mark.integration
+class TestMd5UnsetWithMetadataCombinations:
+    """Test UNSET MD5 state with all metadata format combinations."""
+
+    def test_unset_md5_no_metadata(self):
+        """Test UNSET state with no metadata."""
+        with temp_file_with_metadata({}, "flac") as test_file:
+            create_flac_without_md5(test_file)
+            state = is_flac_md5_valid(test_file)
+            assert state == FlacMd5State.UNSET, "Clean FLAC with unset MD5 should return UNSET"
+
+    def test_unset_md5_vorbis_only(self):
+        """Test UNSET state with Vorbis metadata only."""
+        with temp_file_with_metadata({}, "flac") as test_file:
+            ensure_flac_has_md5(test_file)
+            create_flac_without_md5(test_file)
+            VorbisMetadataSetter.add_title(test_file, "Vorbis Title")
+            state = is_flac_md5_valid(test_file)
+            assert state == FlacMd5State.UNSET, "FLAC with Vorbis metadata and unset MD5 should return UNSET"
+
+    def test_unset_md5_id3v2_only(self):
+        """Test UNSET state with ID3v2 metadata only."""
+        with temp_file_with_metadata({}, "flac") as test_file:
+            ensure_flac_has_md5(test_file)
+            create_flac_without_md5(test_file)
+            ID3v2MetadataSetter.set_metadata(test_file, {"title": "ID3v2 Title"})
+            state = is_flac_md5_valid(test_file)
+            assert state == FlacMd5State.UNSET, "FLAC with ID3v2 metadata and unset MD5 should return UNSET"
+
+    def test_unset_md5_id3v1_only(self):
+        """Test UNSET state with ID3v1 metadata only (should still be UNSET, not UNCHECKABLE)."""
+        with temp_file_with_metadata({}, "flac") as test_file:
+            ensure_flac_has_md5(test_file)
+            create_flac_without_md5(test_file)
+            ID3v1MetadataSetter.set_title(test_file, "ID3v1 Title")
+            state = is_flac_md5_valid(test_file)
+            assert (
+                state == FlacMd5State.UNSET
+            ), "FLAC with ID3v1 metadata and unset MD5 should return UNSET (unset takes precedence)"
+
+    def test_unset_md5_vorbis_and_id3v2(self):
+        """Test UNSET state with Vorbis and ID3v2 metadata."""
+        with temp_file_with_metadata({}, "flac") as test_file:
+            ensure_flac_has_md5(test_file)
+            create_flac_without_md5(test_file)
+            VorbisMetadataSetter.add_title(test_file, "Vorbis Title")
+            ID3v2MetadataSetter.set_metadata(test_file, {"title": "ID3v2 Title"})
+            state = is_flac_md5_valid(test_file)
+            assert state == FlacMd5State.UNSET, "FLAC with Vorbis and ID3v2 metadata and unset MD5 should return UNSET"
+
+    def test_unset_md5_vorbis_and_id3v1(self):
+        """Test UNSET state with Vorbis and ID3v1 metadata (unset takes precedence)."""
+        with temp_file_with_metadata({}, "flac") as test_file:
+            ensure_flac_has_md5(test_file)
+            create_flac_without_md5(test_file)
+            VorbisMetadataSetter.add_title(test_file, "Vorbis Title")
+            ID3v1MetadataSetter.set_title(test_file, "ID3v1 Title")
+            state = is_flac_md5_valid(test_file)
+            assert (
+                state == FlacMd5State.UNSET
+            ), "FLAC with Vorbis and ID3v1 metadata and unset MD5 should return UNSET (unset takes precedence)"
+
+    def test_unset_md5_id3v1_and_id3v2(self):
+        """Test UNSET state with ID3v1 and ID3v2 metadata (unset takes precedence)."""
+        with temp_file_with_metadata({}, "flac") as test_file:
+            ensure_flac_has_md5(test_file)
+            create_flac_without_md5(test_file)
+            ID3v1MetadataSetter.set_title(test_file, "ID3v1 Title")
+            ID3v2MetadataSetter.set_metadata(test_file, {"title": "ID3v2 Title"})
+            state = is_flac_md5_valid(test_file)
+            assert (
+                state == FlacMd5State.UNSET
+            ), "FLAC with ID3v1 and ID3v2 metadata and unset MD5 should return UNSET (unset takes precedence)"
+
+    def test_unset_md5_all_formats(self):
+        """Test UNSET state with all metadata formats (unset takes precedence)."""
+        with temp_file_with_metadata({}, "flac") as test_file:
+            ensure_flac_has_md5(test_file)
+            create_flac_without_md5(test_file)
+            VorbisMetadataSetter.add_title(test_file, "Vorbis Title")
+            ID3v1MetadataSetter.set_title(test_file, "ID3v1 Title")
+            ID3v2MetadataSetter.set_metadata(test_file, {"title": "ID3v2 Title"})
+            state = is_flac_md5_valid(test_file)
+            assert (
+                state == FlacMd5State.UNSET
+            ), "FLAC with all metadata formats and unset MD5 should return UNSET (unset takes precedence)"