audiometa-python 0.11.0__tar.gz → 1.0.0__tar.gz

{audiometa_python-0.11.0/audiometa_python.egg-info → audiometa_python-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: audiometa-python
-Version: 0.11.0
+Version: 1.0.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>
@@ -413,7 +413,7 @@ except MetadataFieldNotSupportedByMetadataFormatError as e:
 
 #### Reading Full Metadata From All Formats Including Headers and Technical Info
 
-**`get_full_metadata(file_path, include_headers=True, include_technical=True)`**
+**`get_full_metadata(file_path, include_headers=True, include_technical=True, include_cover=True)`**
 
 Gets comprehensive metadata including all available information from a file, including headers and technical details even when no metadata is present.
 
@@ -462,7 +462,7 @@ See [Pre-Update Validation Function](#pre-update-validation-function) for detail
 from audiometa import update_metadata
 
 # Update metadata (use UnifiedMetadataKey for explicit typing)
-from audiometa.utils.UnifiedMetadataKey import UnifiedMetadataKey
+from audiometa import UnifiedMetadataKey
 
 new_metadata = {
     UnifiedMetadataKey.TITLE: 'New Song Title',
@@ -688,7 +688,7 @@ id3v2_rating = get_unified_metadata_field("song.mp3", UnifiedMetadataKey.RATING,
 
 #### Reading Full Metadata From All Formats Including Headers and Technical Info
 
-**`get_full_metadata(file_path, include_headers=True, include_technical=True)`**
+**`get_full_metadata(file_path, include_headers=True, include_technical=True, include_cover=True)`**
 
 Gets comprehensive metadata including all available information from a file, including headers and technical details even when no metadata is present.
 
@@ -738,6 +738,7 @@ print(f"Raw Vorbis Comments: {full_metadata['raw_metadata']['vorbis']['comments'
 - `file_path`: Path to the audio file (str or Path)
 - `include_headers`: Whether to include format-specific header information (default: True)
 - `include_technical`: Whether to include technical audio information (default: True)
+- `include_cover`: Whether to include cover/art image info in raw_metadata (default: True)
 
 **Returns:**
 A comprehensive dictionary containing:
@@ -865,6 +866,9 @@ metadata_only = get_full_metadata("song.mp3", include_technical=False)
 # Get only technical info without headers
 tech_only = get_full_metadata("song.mp3", include_headers=False)
 
+# Exclude cover/art from raw metadata
+no_cover = get_full_metadata("song.mp3", include_cover=False)
+
 # Check if file has specific format headers
 if full_info['headers']['id3v2']['present']:
     print("File has ID3v2 tags")
@@ -971,7 +975,7 @@ Updates metadata in a file. The function automatically calls pre-update validati
 from audiometa import update_metadata
 
 # Basic writing (recommended: use UnifiedMetadataKey constants)
-from audiometa.utils.UnifiedMetadataKey import UnifiedMetadataKey
+from audiometa import UnifiedMetadataKey
 
 update_metadata("song.mp3", {
     UnifiedMetadataKey.TITLE: 'New Title',

{audiometa_python-0.11.0 → audiometa_python-1.0.0}/README.md

@@ -371,7 +371,7 @@ except MetadataFieldNotSupportedByMetadataFormatError as e:
 
 #### Reading Full Metadata From All Formats Including Headers and Technical Info
 
-**`get_full_metadata(file_path, include_headers=True, include_technical=True)`**
+**`get_full_metadata(file_path, include_headers=True, include_technical=True, include_cover=True)`**
 
 Gets comprehensive metadata including all available information from a file, including headers and technical details even when no metadata is present.
 
@@ -420,7 +420,7 @@ See [Pre-Update Validation Function](#pre-update-validation-function) for detail
 from audiometa import update_metadata
 
 # Update metadata (use UnifiedMetadataKey for explicit typing)
-from audiometa.utils.UnifiedMetadataKey import UnifiedMetadataKey
+from audiometa import UnifiedMetadataKey
 
 new_metadata = {
     UnifiedMetadataKey.TITLE: 'New Song Title',
@@ -646,7 +646,7 @@ id3v2_rating = get_unified_metadata_field("song.mp3", UnifiedMetadataKey.RATING,
 
 #### Reading Full Metadata From All Formats Including Headers and Technical Info
 
-**`get_full_metadata(file_path, include_headers=True, include_technical=True)`**
+**`get_full_metadata(file_path, include_headers=True, include_technical=True, include_cover=True)`**
 
 Gets comprehensive metadata including all available information from a file, including headers and technical details even when no metadata is present.
 
@@ -696,6 +696,7 @@ print(f"Raw Vorbis Comments: {full_metadata['raw_metadata']['vorbis']['comments'
 - `file_path`: Path to the audio file (str or Path)
 - `include_headers`: Whether to include format-specific header information (default: True)
 - `include_technical`: Whether to include technical audio information (default: True)
+- `include_cover`: Whether to include cover/art image info in raw_metadata (default: True)
 
 **Returns:**
 A comprehensive dictionary containing:
@@ -823,6 +824,9 @@ metadata_only = get_full_metadata("song.mp3", include_technical=False)
 # Get only technical info without headers
 tech_only = get_full_metadata("song.mp3", include_headers=False)
 
+# Exclude cover/art from raw metadata
+no_cover = get_full_metadata("song.mp3", include_cover=False)
+
 # Check if file has specific format headers
 if full_info['headers']['id3v2']['present']:
     print("File has ID3v2 tags")
@@ -929,7 +933,7 @@ Updates metadata in a file. The function automatically calls pre-update validati
 from audiometa import update_metadata
 
 # Basic writing (recommended: use UnifiedMetadataKey constants)
-from audiometa.utils.UnifiedMetadataKey import UnifiedMetadataKey
+from audiometa import UnifiedMetadataKey
 
 update_metadata("song.mp3", {
     UnifiedMetadataKey.TITLE: 'New Title',

{audiometa_python-0.11.0 → audiometa_python-1.0.0}/audiometa/__init__.py

@@ -36,6 +36,36 @@ from .utils.metadata_writing_strategy import MetadataWritingStrategy
 from .utils.types import UnifiedMetadata, UnifiedMetadataValue
 from .utils.unified_metadata_key import UnifiedMetadataKey
 
+__all__ = [
+    "UnifiedMetadataKey",
+    "FlacMd5State",
+    "MetadataFormat",
+    "MetadataWritingStrategy",
+    "UnifiedMetadata",
+    "UnifiedMetadataValue",
+    "FileCorruptedError",
+    "FileTypeNotSupportedError",
+    "InvalidMetadataFieldTypeError",
+    "MetadataFieldNotSupportedByLibError",
+    "MetadataFieldNotSupportedByMetadataFormatError",
+    "MetadataFormatNotSupportedByAudioFormatError",
+    "MetadataWritingConflictParametersError",
+    "get_unified_metadata",
+    "get_unified_metadata_field",
+    "validate_metadata_for_update",
+    "update_metadata",
+    "delete_all_metadata",
+    "get_bitrate",
+    "get_channels",
+    "get_file_size",
+    "get_sample_rate",
+    "is_audio_file",
+    "get_duration_in_sec",
+    "is_flac_md5_valid",
+    "fix_md5_checking",
+    "get_full_metadata",
+]
+
 FILE_EXTENSION_NOT_HANDLED_MESSAGE = "The file's format is not handled by the service."
 
 METADATA_FORMAT_MANAGER_CLASS_MAP: dict[MetadataFormat, type] = {
@@ -478,6 +508,16 @@ def _validate_metadata_field_formats(unified_metadata: UnifiedMetadata) -> None:
         ):
             _MetadataManager.validate_musicbrainz_trackid(musicbrainz_trackid_value)
 
+    # Validate MusicBrainz Artist ID format if present and non-empty
+    if UnifiedMetadataKey.MUSICBRAINZ_ARTISTIDS in unified_metadata:
+        musicbrainz_artistids_value = unified_metadata[UnifiedMetadataKey.MUSICBRAINZ_ARTISTIDS]
+        if (
+            musicbrainz_artistids_value is not None
+            and isinstance(musicbrainz_artistids_value, list)
+            and musicbrainz_artistids_value
+        ):
+            _MetadataManager.validate_musicbrainz_artistids(musicbrainz_artistids_value)
+
 
 def validate_metadata_for_update(
     unified_metadata: dict[UnifiedMetadataKey, Any] | UnifiedMetadata,
@@ -1221,7 +1261,10 @@ def fix_md5_checking(file: PublicFileType) -> str:
 
 
 def get_full_metadata(
-    file: PublicFileType, include_headers: bool = True, include_technical: bool = True
+    file: PublicFileType,
+    include_headers: bool = True,
+    include_technical: bool = True,
+    include_cover: bool = True,
 ) -> dict[str, Any]:
     """Get comprehensive metadata including all available information from a file.
 
@@ -1237,6 +1280,7 @@ def get_full_metadata(
         file: Audio file path (str or Path)
         include_headers: Whether to include format-specific header information (default: True)
         include_technical: Whether to include technical audio information (default: True)
+        include_cover: Whether to include cover/art image info in raw_metadata (default: True)
 
     Returns:
         Comprehensive dictionary containing all available metadata and technical information
@@ -1383,4 +1427,25 @@ def get_full_metadata(
                     "chunk_structure": {},
                 }
 
+    if not include_cover:
+        id3v2_raw = raw_metadata_dict.get("id3v2", {})
+        frames = id3v2_raw.get("frames", {})
+        if "APIC:" in frames:
+            raw_metadata_dict["id3v2"] = {
+                **id3v2_raw,
+                "frames": {k: v for k, v in frames.items() if k != "APIC:"},
+            }
+
+        riff_raw = raw_metadata_dict.get("riff", {})
+        riff_cover_parsed_keys = frozenset({"ICON"})
+        riff_cover_chunk_keys = frozenset({"cover", "image"})
+        parsed = riff_raw.get("parsed_fields", {})
+        chunk = riff_raw.get("chunk_structure", {})
+        if riff_cover_parsed_keys & frozenset(parsed) or riff_cover_chunk_keys & frozenset(chunk):
+            raw_metadata_dict["riff"] = {
+                **riff_raw,
+                "parsed_fields": {k: v for k, v in parsed.items() if k not in riff_cover_parsed_keys},
+                "chunk_structure": {k: v for k, v in chunk.items() if k not in riff_cover_chunk_keys},
+            }
+
     return result

{audiometa_python-0.11.0 → audiometa_python-1.0.0}/audiometa/cli.py

@@ -95,6 +95,7 @@ def format_as_table(data: dict[str, Any]) -> str:
             "archival_location",
             "isrc",
             "musicbrainz_trackid",
+            "musicbrainz_artistids",
             "description",
             "originator",
         }
@@ -146,6 +147,7 @@ def _read_metadata(args: argparse.Namespace) -> None:
                     file_path,
                     include_headers=not getattr(args, "no_headers", False),
                     include_technical=not getattr(args, "no_technical", False),
+                    include_cover=not getattr(args, "no_cover", False),
                 )
 
             output = format_output(metadata, args.output_format)
@@ -203,6 +205,10 @@ def _write_metadata(args: argparse.Namespace) -> None:
         metadata[UnifiedMetadataKey.MUSICBRAINZ_TRACKID] = args.musicbrainz_track_id
 
     # List fields (can be specified multiple times)
+    if args.musicbrainz_artist_ids:
+        artist_ids = [aid.strip() for aid in args.musicbrainz_artist_ids if aid and aid.strip()]
+        if artist_ids:
+            metadata[UnifiedMetadataKey.MUSICBRAINZ_ARTISTIDS] = artist_ids
     if args.artist:
         artists = [a.strip() for a in args.artist if a and a.strip()]
         if artists:
@@ -385,6 +391,7 @@ Examples:
     read_parser.add_argument("--output", "-o", help="Output file (default: stdout)")
     read_parser.add_argument("--no-headers", action="store_true", help="Exclude header information")
     read_parser.add_argument("--no-technical", action="store_true", help="Exclude technical information")
+    read_parser.add_argument("--no-cover", action="store_true", help="Exclude cover/art image from raw metadata")
     read_parser.add_argument("--recursive", "-r", action="store_true", help="Process directories recursively")
     read_parser.add_argument(
         "--continue-on-error", action="store_true", help="Continue processing other files on error"
@@ -448,6 +455,12 @@ Examples:
         dest="musicbrainz_track_id",
         help="MusicBrainz Track ID (Recording ID) - UUID format (e.g., '9d6f6f7c-9d52-4c76-8f9e-01d18d8f8ec6')",
     )
+    write_parser.add_argument(
+        "--musicbrainz-artist-ids",
+        action="append",
+        dest="musicbrainz_artist_ids",
+        help="MusicBrainz Artist IDs - UUID format (can be specified multiple times for multiple artists)",
+    )
     write_parser.add_argument(
         "--force-format",
         choices=["id3v2", "id3v1", "vorbis", "riff"],

{audiometa_python-0.11.0 → audiometa_python-1.0.0}/audiometa/manager/_MetadataManager.py

@@ -4,7 +4,7 @@ from typing import TYPE_CHECKING, TypeVar, Union, cast
 
 from mutagen._file import FileType as MutagenMetadata
 
-from audiometa.exceptions import InvalidMetadataFieldFormatError
+from audiometa.exceptions import InvalidMetadataFieldFormatError, InvalidMetadataFieldTypeError
 from audiometa.utils.unified_metadata_key import UnifiedMetadataKey
 
 if TYPE_CHECKING:
@@ -255,6 +255,33 @@ class _MetadataManager:
             isrc,
         )
 
+    @staticmethod
+    def _validate_musicbrainz_uuid_format(uuid_str: str, field_key: UnifiedMetadataKey) -> None:
+        """Validate a single MusicBrainz UUID string format.
+
+        Accepts 36-character hyphenated UUID or 32-character hex string. Empty strings are allowed.
+
+        Raises:
+            InvalidMetadataFieldFormatError: If the UUID format is invalid
+        """
+        if not uuid_str:
+            return
+
+        # 36-character hyphenated UUID format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+        if re.match(r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", uuid_str):
+            return
+
+        # 32-character hex string without hyphens
+        if re.match(r"^[0-9a-fA-F]{32}$", uuid_str):
+            return
+
+        raise InvalidMetadataFieldFormatError(
+            field_key.value,
+            "36-character hyphenated UUID (e.g., '9d6f6f7c-9d52-4c76-8f9e-01d18d8f8ec6') or "
+            "32-character hex string (e.g., '9d6f6f7c9d524c768f9e01d18d8f8ec6')",
+            uuid_str,
+        )
+
     @staticmethod
     def validate_musicbrainz_trackid(track_id: str) -> None:
         """Validate MusicBrainz Track ID (UUID) format.
@@ -279,23 +306,28 @@ class _MetadataManager:
             >>> _MetadataManager.validate_musicbrainz_trackid("not-a-uuid")
             # Raises InvalidMetadataFieldFormatError
         """
-        if not track_id:
-            return
+        _MetadataManager._validate_musicbrainz_uuid_format(track_id, UnifiedMetadataKey.MUSICBRAINZ_TRACKID)
 
-        # 36-character hyphenated UUID format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
-        if re.match(r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", track_id):
-            return
+    @staticmethod
+    def validate_musicbrainz_artistids(artist_ids: list[str]) -> None:
+        """Validate MusicBrainz Artist ID(s) (UUID) format.
 
-        # 32-character hex string without hyphens
-        if re.match(r"^[0-9a-fA-F]{32}$", track_id):
-            return
+        Each Artist ID must be a valid UUID (36-char hyphenated or 32-char hex).
+        Empty list or list with empty strings is allowed.
 
-        raise InvalidMetadataFieldFormatError(
-            UnifiedMetadataKey.MUSICBRAINZ_TRACKID.value,
-            "36-character hyphenated UUID (e.g., '9d6f6f7c-9d52-4c76-8f9e-01d18d8f8ec6') or "
-            "32-character hex string (e.g., '9d6f6f7c9d524c768f9e01d18d8f8ec6')",
-            track_id,
-        )
+        Raises:
+            InvalidMetadataFieldFormatError: If any Artist ID format is invalid
+            InvalidMetadataFieldTypeError: If artist_ids is not a list
+        """
+        if not isinstance(artist_ids, list):
+            raise InvalidMetadataFieldTypeError(
+                UnifiedMetadataKey.MUSICBRAINZ_ARTISTIDS.value,
+                "list of strings",
+                type(artist_ids).__name__,
+            )
+
+        for artist_id in artist_ids:
+            _MetadataManager._validate_musicbrainz_uuid_format(artist_id, UnifiedMetadataKey.MUSICBRAINZ_ARTISTIDS)
 
     @abstractmethod
     def _extract_mutagen_metadata(self) -> MutagenMetadata:
@@ -714,6 +746,32 @@ class _MetadataManager:
             return self._get_genres_from_raw_clean_metadata_uppercase_keys(
                 self.raw_clean_metadata_uppercase_keys, raw_metadata_key
             )
+        if unified_metadata_key == UnifiedMetadataKey.MUSICBRAINZ_ARTISTIDS:
+            # First apply smart parsing to handle separator-based values
+            if unified_metadata_key.can_semantically_have_multiple_values():
+                if self._should_apply_smart_parsing(values_list_str):
+                    # Apply parsing for single entry (legacy data detection)
+                    parsed_values = self._apply_smart_parsing(values_list_str)
+                    values_list_str = parsed_values if parsed_values else []
+                else:
+                    # No parsing - filter empty/whitespace values
+                    values_list_str = [val.strip() for val in values_list_str if val.strip()]
+
+            # Then normalize UUIDs: convert 32-char hex to 36-char hyphenated format if needed
+            normalized_ids = []
+            uuid_hex_length = 32
+            for artist_id in values_list_str:
+                if artist_id and artist_id.strip():
+                    normalized_id = artist_id.strip()
+                    if len(normalized_id) == uuid_hex_length and all(
+                        c in "0123456789abcdefABCDEF" for c in normalized_id
+                    ):
+                        normalized_id = (
+                            f"{normalized_id[:8]}-{normalized_id[8:12]}-"
+                            f"{normalized_id[12:16]}-{normalized_id[16:20]}-{normalized_id[20:32]}"
+                        )
+                    normalized_ids.append(normalized_id)
+            return normalized_ids if normalized_ids else None
         if unified_metadata_key.can_semantically_have_multiple_values():
             # Apply smart parsing logic for semantically multi-value fields
             if self._should_apply_smart_parsing(values_list_str):