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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: audiometa-python
-Version: 0.9.0
+Version: 0.11.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.9.0 → audiometa_python-0.11.0}/audiometa/__init__.py

@@ -468,6 +468,16 @@ def _validate_metadata_field_formats(unified_metadata: UnifiedMetadata) -> None:
         if isrc_value is not None and isinstance(isrc_value, str) and isrc_value:
             _MetadataManager.validate_isrc(isrc_value)
 
+    # Validate MusicBrainz Track ID format if present and non-empty
+    if UnifiedMetadataKey.MUSICBRAINZ_TRACKID in unified_metadata:
+        musicbrainz_trackid_value = unified_metadata[UnifiedMetadataKey.MUSICBRAINZ_TRACKID]
+        if (
+            musicbrainz_trackid_value is not None
+            and isinstance(musicbrainz_trackid_value, str)
+            and musicbrainz_trackid_value
+        ):
+            _MetadataManager.validate_musicbrainz_trackid(musicbrainz_trackid_value)
+
 
 def validate_metadata_for_update(
     unified_metadata: dict[UnifiedMetadataKey, Any] | UnifiedMetadata,

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

@@ -94,6 +94,9 @@ def format_as_table(data: dict[str, Any]) -> str:
             "replaygain",
             "archival_location",
             "isrc",
+            "musicbrainz_trackid",
+            "description",
+            "originator",
         }
         if unified_keys.intersection(set(data.keys())):
             # This is a unified metadata dict, wrap it
@@ -188,12 +191,16 @@ def _write_metadata(args: argparse.Namespace) -> None:
         metadata[UnifiedMetadataKey.COMMENT] = args.comment
     if args.description and args.description.strip():
         metadata[UnifiedMetadataKey.DESCRIPTION] = args.description
+    if args.originator and args.originator.strip():
+        metadata[UnifiedMetadataKey.ORIGINATOR] = args.originator
     if args.replaygain and args.replaygain.strip():
         metadata[UnifiedMetadataKey.REPLAYGAIN] = args.replaygain
     if args.archival_location and args.archival_location.strip():
         metadata[UnifiedMetadataKey.ARCHIVAL_LOCATION] = args.archival_location
     if args.isrc and args.isrc.strip():
         metadata[UnifiedMetadataKey.ISRC] = args.isrc
+    if args.musicbrainz_track_id and args.musicbrainz_track_id.strip():
+        metadata[UnifiedMetadataKey.MUSICBRAINZ_TRACKID] = args.musicbrainz_track_id
 
     # List fields (can be specified multiple times)
     if args.artist:
@@ -432,9 +439,15 @@ Examples:
     write_parser.add_argument("--lyrics", help="Unsynchronized lyrics text")
     write_parser.add_argument("--comment", help="Comment")
     write_parser.add_argument("--description", help="Description")
+    write_parser.add_argument("--originator", help="Originator")
     write_parser.add_argument("--replaygain", help="ReplayGain information")
     write_parser.add_argument("--archival-location", help="Archival location")
     write_parser.add_argument("--isrc", help="International Standard Recording Code (12 characters)")
+    write_parser.add_argument(
+        "--musicbrainz-track-id",
+        dest="musicbrainz_track_id",
+        help="MusicBrainz Track ID (Recording ID) - UUID format (e.g., '9d6f6f7c-9d52-4c76-8f9e-01d18d8f8ec6')",
+    )
     write_parser.add_argument(
         "--force-format",
         choices=["id3v2", "id3v1", "vorbis", "riff"],

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

@@ -255,6 +255,48 @@ class _MetadataManager:
             isrc,
         )
 
+    @staticmethod
+    def validate_musicbrainz_trackid(track_id: str) -> None:
+        """Validate MusicBrainz Track ID (UUID) format.
+
+        MusicBrainz Track ID must be a valid UUID string in one of the following formats:
+        - 36-character hyphenated UUID (preferred): "9d6f6f7c-9d52-4c76-8f9e-01d18d8f8ec6"
+        - 32-character hex string without hyphens: "9d6f6f7c9d524c768f9e01d18d8f8ec6"
+        - Empty string is allowed (represents no Track ID)
+
+        Args:
+            track_id: The MusicBrainz Track ID string to validate
+
+        Raises:
+            InvalidMetadataFieldFormatError: If the Track ID format is invalid
+
+        Examples:
+            >>> _MetadataManager.validate_musicbrainz_trackid("9d6f6f7c-9d52-4c76-8f9e-01d18d8f8ec6")
+            # Valid (36 chars)
+            >>> _MetadataManager.validate_musicbrainz_trackid("9d6f6f7c9d524c768f9e01d18d8f8ec6")
+            # Valid (32 chars)
+            >>> _MetadataManager.validate_musicbrainz_trackid("")  # Valid (empty string)
+            >>> _MetadataManager.validate_musicbrainz_trackid("not-a-uuid")
+            # Raises InvalidMetadataFieldFormatError
+        """
+        if not track_id:
+            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}$", track_id):
+            return
+
+        # 32-character hex string without hyphens
+        if re.match(r"^[0-9a-fA-F]{32}$", track_id):
+            return
+
+        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,
+        )
+
     @abstractmethod
     def _extract_mutagen_metadata(self) -> MutagenMetadata:
         raise NotImplementedError

{audiometa_python-0.9.0 → audiometa_python-0.11.0}/audiometa/manager/_rating_supporting/id3v2/_Id3v2Manager.py

@@ -31,6 +31,7 @@ from mutagen.id3._frames import (
     TSRC,
     TXXX,
     TYER,
+    UFID,
     USLT,
     WOAR,
 )
@@ -284,6 +285,7 @@ class _Id3v2Manager(_RatingSupportingMetadataManager):
             UnifiedMetadataKey.COMMENT: self.Id3TextFrame.COMMENT,
             UnifiedMetadataKey.REPLAYGAIN: None,
             UnifiedMetadataKey.ISRC: self.Id3TextFrame.ISRC,
+            UnifiedMetadataKey.MUSICBRAINZ_TRACKID: None,
         }
         metadata_keys_direct_map_write: dict[UnifiedMetadataKey, RawMetadataKey | None] = {
             UnifiedMetadataKey.TITLE: self.Id3TextFrame.TITLE,
@@ -305,6 +307,7 @@ class _Id3v2Manager(_RatingSupportingMetadataManager):
             UnifiedMetadataKey.COMMENT: self.Id3TextFrame.COMMENT,
             UnifiedMetadataKey.REPLAYGAIN: None,
             UnifiedMetadataKey.ISRC: self.Id3TextFrame.ISRC,
+            UnifiedMetadataKey.MUSICBRAINZ_TRACKID: None,
         }
 
         super().__init__(
@@ -396,6 +399,56 @@ class _Id3v2Manager(_RatingSupportingMetadataManager):
                     result[self.Id3TextFrame.REPLAYGAIN] = txxx_frame.text
                     break
 
+        # Handle UFID frames for MusicBrainz Track ID (preferred)
+        musicbrainz_trackid = None
+        for raw_mutagen_frame in raw_mutagen_metadata.items():
+            if raw_mutagen_frame[0].startswith("UFID"):
+                ufid_frame = raw_mutagen_frame[1]
+                if (
+                    hasattr(ufid_frame, "owner")
+                    and ufid_frame.owner == "http://musicbrainz.org"
+                    and hasattr(ufid_frame, "data")
+                ):
+                    # UFID data is bytes, decode to string
+                    try:
+                        musicbrainz_trackid = ufid_frame.data.decode("utf-8", errors="replace").strip("\x00")
+                        # Normalize to hyphenated UUID format if it's 32 hex chars
+                        uuid_hex_length = 32
+                        if len(musicbrainz_trackid) == uuid_hex_length and all(
+                            c in "0123456789abcdefABCDEF" for c in musicbrainz_trackid
+                        ):
+                            musicbrainz_trackid = (
+                                f"{musicbrainz_trackid[:8]}-{musicbrainz_trackid[8:12]}-"
+                                f"{musicbrainz_trackid[12:16]}-{musicbrainz_trackid[16:20]}-{musicbrainz_trackid[20:32]}"
+                            )
+                        break
+                    except (UnicodeDecodeError, AttributeError):
+                        pass
+
+        # Handle TXXX frames for MusicBrainz Track ID (fallback)
+        if not musicbrainz_trackid:
+            for raw_mutagen_frame in raw_mutagen_metadata.items():
+                if raw_mutagen_frame[0].startswith("TXXX"):
+                    txxx_frame = raw_mutagen_frame[1]
+                    if hasattr(txxx_frame, "desc") and txxx_frame.desc == "MusicBrainz Track Id" and txxx_frame.text:
+                        musicbrainz_trackid = (
+                            txxx_frame.text[0] if isinstance(txxx_frame.text, list) else str(txxx_frame.text)
+                        )
+                        # Normalize to hyphenated UUID format if it's 32 hex chars
+                        uuid_hex_length = 32
+                        if len(musicbrainz_trackid) == uuid_hex_length and all(
+                            c in "0123456789abcdefABCDEF" for c in musicbrainz_trackid
+                        ):
+                            musicbrainz_trackid = (
+                                f"{musicbrainz_trackid[:8]}-{musicbrainz_trackid[8:12]}-"
+                                f"{musicbrainz_trackid[12:16]}-{musicbrainz_trackid[16:20]}-{musicbrainz_trackid[20:32]}"
+                            )
+                        break
+
+        if musicbrainz_trackid:
+            # Use a special key for MusicBrainz Track ID (not a text frame, so use string key)
+            result[cast(RawMetadataKey, "MUSICBRAINZ_TRACKID")] = [musicbrainz_trackid]
+
         # Special handling for release date: if TDRC is not present, try to construct from TYER + TDAT
         # Only do this for ID3v2 files (not ID3v1) and only when both TYER and TDAT are present
         if self.Id3TextFrame.RECORDING_TIME not in result:
@@ -443,6 +496,23 @@ class _Id3v2Manager(_RatingSupportingMetadataManager):
             if app_metadata_value is not None:
                 # Add new TXXX frame with desc 'REPLAYGAIN'
                 raw_mutagen_metadata.add(TXXX(encoding=3, desc="REPLAYGAIN", text=str(app_metadata_value)))
+        elif unified_metadata_key == UnifiedMetadataKey.MUSICBRAINZ_TRACKID:
+            # Remove existing UFID frames with MusicBrainz owner
+            raw_mutagen_metadata.delall("UFID:http://musicbrainz.org")
+            # Remove existing TXXX frames with MusicBrainz Track Id description
+            raw_mutagen_metadata.delall("TXXX:MusicBrainz Track Id")
+
+            if app_metadata_value is not None and app_metadata_value != "":
+                # Normalize UUID: convert 32-char hex to 36-char hyphenated format if needed
+                track_id = str(app_metadata_value).strip()
+                uuid_hex_length = 32
+                if len(track_id) == uuid_hex_length and all(c in "0123456789abcdefABCDEF" for c in track_id):
+                    track_id = f"{track_id[:8]}-{track_id[8:12]}-{track_id[12:16]}-{track_id[16:20]}-{track_id[20:32]}"
+
+                # Write as UFID frame with owner "http://musicbrainz.org"
+                # UFID data should be the UUID as bytes (without null terminator)
+                track_id_bytes = track_id.encode("utf-8")
+                raw_mutagen_metadata.add(UFID(owner="http://musicbrainz.org", data=track_id_bytes))
         elif unified_metadata_key in (UnifiedMetadataKey.DISC_NUMBER, UnifiedMetadataKey.DISC_TOTAL):
             tpos_key = self.Id3TextFrame.DISC_NUMBER
             tpos_frame_class = TPOS
@@ -512,6 +582,17 @@ class _Id3v2Manager(_RatingSupportingMetadataManager):
                 return None
             first_value = replaygain_value[0]
             return cast(UnifiedMetadataValue, first_value)
+        if unified_metadata_key == UnifiedMetadataKey.MUSICBRAINZ_TRACKID:
+            musicbrainz_trackid_key = cast(RawMetadataKey, "MUSICBRAINZ_TRACKID")
+            if musicbrainz_trackid_key not in raw_clean_metadata:
+                return None
+            trackid_value = raw_clean_metadata[musicbrainz_trackid_key]
+            if trackid_value is None:
+                return None
+            if len(trackid_value) == 0:
+                return None
+            first_value = trackid_value[0]
+            return cast(UnifiedMetadataValue, first_value)
         if unified_metadata_key == UnifiedMetadataKey.DISC_NUMBER:
             tpos_key = self.Id3TextFrame.DISC_NUMBER
             if tpos_key not in raw_clean_metadata:

{audiometa_python-0.9.0 → audiometa_python-0.11.0}/audiometa/manager/_rating_supporting/riff/_RiffManager.py

@@ -15,7 +15,13 @@ from ....utils.rating_profiles import RatingWriteProfile
 from ....utils.types import RawMetadataDict, RawMetadataKey, UnifiedMetadata, UnifiedMetadataValue
 from ....utils.unified_metadata_key import UnifiedMetadataKey
 from .._RatingSupportingMetadataManager import _RatingSupportingMetadataManager
-from ._riff_bext_chunk import extract_bext_chunk, find_bext_chunk, find_fmt_chunk, update_bext_description_in_riff_data
+from ._riff_bext_chunk import (
+    extract_bext_chunk,
+    find_bext_chunk,
+    find_fmt_chunk,
+    update_bext_description_in_riff_data,
+    update_bext_originator_in_riff_data,
+)
 from ._riff_constants import (
     RIFF_AUDIO_FORMAT_IEEE_FLOAT,
     RIFF_FORMAT_CHUNK_MIN_SIZE,
@@ -115,6 +121,7 @@ class _RiffManager(_RatingSupportingMetadataManager):
 
         # BWF
         ISRC = "ISRC"  # International Standard Recording Code
+        MBID = "MBID"  # MusicBrainz Track ID (Recording ID)
 
     def __init__(self, audio_file: "_AudioFile", normalized_rating_max_value: None | int = None):
         # Validate that the file is a WAV file
@@ -138,7 +145,9 @@ class _RiffManager(_RatingSupportingMetadataManager):
             UnifiedMetadataKey.UNSYNCHRONIZED_LYRICS: self.RiffTagKey.UNSYNCHRONIZED_LYRICS,
             UnifiedMetadataKey.TRACK_NUMBER: self.RiffTagKey.TRACK_NUMBER,
             UnifiedMetadataKey.ISRC: self.RiffTagKey.ISRC,
+            UnifiedMetadataKey.MUSICBRAINZ_TRACKID: self.RiffTagKey.MBID,
             UnifiedMetadataKey.DESCRIPTION: None,
+            UnifiedMetadataKey.ORIGINATOR: None,
         }
         metadata_keys_direct_map_write: dict[UnifiedMetadataKey, RawMetadataKey | None] = {
             UnifiedMetadataKey.TITLE: self.RiffTagKey.TITLE,
@@ -156,7 +165,9 @@ class _RiffManager(_RatingSupportingMetadataManager):
             UnifiedMetadataKey.UNSYNCHRONIZED_LYRICS: self.RiffTagKey.UNSYNCHRONIZED_LYRICS,
             UnifiedMetadataKey.TRACK_NUMBER: self.RiffTagKey.TRACK_NUMBER,
             UnifiedMetadataKey.ISRC: self.RiffTagKey.ISRC,
+            UnifiedMetadataKey.MUSICBRAINZ_TRACKID: self.RiffTagKey.MBID,
             UnifiedMetadataKey.DESCRIPTION: None,
+            UnifiedMetadataKey.ORIGINATOR: None,
         }
         super().__init__(
             audio_file=audio_file,
@@ -280,6 +291,17 @@ class _RiffManager(_RatingSupportingMetadataManager):
             except Exception:
                 pass
             return None
+        if unified_metadata_key == UnifiedMetadataKey.ORIGINATOR:
+            # Read from bext chunk
+            try:
+                self.audio_file.seek(0)
+                file_data = self.audio_file.read()
+                bext_data = self._extract_bext_chunk(file_data)
+                if bext_data and "Originator" in bext_data:
+                    return cast(str, bext_data["Originator"])
+            except Exception:
+                pass
+            return None
         msg = f"Metadata key not handled: {unified_metadata_key}"
         raise MetadataFieldNotSupportedByMetadataFormatError(msg)
 
@@ -459,6 +481,9 @@ class _RiffManager(_RatingSupportingMetadataManager):
         if UnifiedMetadataKey.DESCRIPTION in merged_metadata:
             description_value = merged_metadata[UnifiedMetadataKey.DESCRIPTION]
             update_bext_description_in_riff_data(riff_data, cast(str | None, description_value))
+        if UnifiedMetadataKey.ORIGINATOR in merged_metadata:
+            originator_value = merged_metadata[UnifiedMetadataKey.ORIGINATOR]
+            update_bext_originator_in_riff_data(riff_data, cast(str | None, originator_value))
 
     def _update_riff_chunk_size(self, riff_data: bytearray) -> None:
         """Update RIFF chunk size in RIFF data.

{audiometa_python-0.9.0 → audiometa_python-0.11.0}/audiometa/manager/_rating_supporting/riff/_riff_bext_chunk.py

@@ -210,25 +210,33 @@ def extract_bext_chunk(file_data: bytes, skip_id3v2_tags_func: Callable[[bytes],
     return None
 
 
-def update_bext_description_in_riff_data(riff_data: bytearray, value: str | None) -> None:
-    """Update the Description field in the bext chunk within RIFF data.
+def _update_bext_field_in_riff_data(
+    riff_data: bytearray, value: str | None, field_size: int, field_offset: int
+) -> None:
+    """Update a field in the bext chunk within RIFF data.
 
     This function modifies the riff_data bytearray in-place to update or create
-    the bext chunk with the Description field. This is integrated into the main
+    the bext chunk with the specified field. This is integrated into the main
     update flow to avoid multiple file writes.
 
     Args:
         riff_data: RIFF data bytearray (modified in-place)
-        value: Description value to write, or None/empty string to clear
+        value: Field value to write, or None/empty string to clear
+        field_size: Size of the field in bytes
+        field_offset: Offset of the field within the bext chunk
     """
-    encoded = b"\x00" * 256 if value is None or value == "" else value.encode("utf-8")[:255].ljust(256, b"\x00")
+    encoded = (
+        b"\x00" * field_size
+        if value is None or value == ""
+        else value.encode("utf-8")[: field_size - 1].ljust(field_size, b"\x00")
+    )
 
     # Find bext chunk in RIFF data (no ID3v2 tags in riff_data at this point)
     pos = find_bext_chunk_in_riff_data(riff_data)
     if pos != -1:
-        # Update existing bext chunk Description field
+        # Update existing bext chunk field
         bext_start = pos + 8
-        riff_data[bext_start : bext_start + 256] = encoded
+        riff_data[bext_start + field_offset : bext_start + field_offset + field_size] = encoded
     else:
         # No bext chunk, create one
         fmt_pos = find_fmt_chunk_in_riff_data(riff_data)
@@ -237,12 +245,24 @@ def update_bext_description_in_riff_data(riff_data: bytearray, value: str | None
         fmt_size = int.from_bytes(bytes(riff_data[fmt_pos + 4 : fmt_pos + 8]), "little")
         insert_pos = fmt_pos + 8 + fmt_size
         # Create bext chunk data: 602 bytes v1
-        bext_data = b"bext" + (602).to_bytes(4, "little") + encoded + b"\x00" * 346
+        # Fill with zeros, then set the specific field
+        bext_data = bytearray(b"bext" + (602).to_bytes(4, "little") + b"\x00" * 602)
+        bext_data[8 + field_offset : 8 + field_offset + field_size] = encoded
         # Insert bext chunk after fmt chunk
         riff_data[insert_pos:insert_pos] = bext_data
         # Note: RIFF chunk size will be updated by caller after this method
 
 
+def update_bext_description_in_riff_data(riff_data: bytearray, value: str | None) -> None:
+    """Update the Description field in the bext chunk within RIFF data."""
+    _update_bext_field_in_riff_data(riff_data, value, 256, 0)
+
+
+def update_bext_originator_in_riff_data(riff_data: bytearray, value: str | None) -> None:
+    """Update the Originator field in the bext chunk within RIFF data."""
+    _update_bext_field_in_riff_data(riff_data, value, 32, 256)
+
+
 def find_bext_chunk_in_riff_data(riff_data: bytearray) -> int:
     """Find the position of the bext chunk in RIFF data.
 

{audiometa_python-0.9.0 → audiometa_python-0.11.0}/audiometa/manager/_rating_supporting/vorbis/_VorbisManager.py

@@ -59,6 +59,7 @@ class _VorbisManager(_RatingSupportingMetadataManager):
         LOCATION = "LOCATION"  # Recording location
         CONTACT = "CONTACT"  # Contact information
         ISRC = "ISRC"  # International Standard Recording Code
+        MUSICBRAINZ_TRACKID = "MUSICBRAINZ_TRACKID"  # MusicBrainz Track ID (Recording ID)
 
         # Non-standard
         LANGUAGE = "LANGUAGE"
@@ -92,6 +93,7 @@ class _VorbisManager(_RatingSupportingMetadataManager):
             UnifiedMetadataKey.REPLAYGAIN: self.VorbisKey.REPLAYGAIN,
             UnifiedMetadataKey.PUBLISHER: self.VorbisKey.PUBLISHER,
             UnifiedMetadataKey.ISRC: self.VorbisKey.ISRC,
+            UnifiedMetadataKey.MUSICBRAINZ_TRACKID: self.VorbisKey.MUSICBRAINZ_TRACKID,
             UnifiedMetadataKey.DESCRIPTION: self.VorbisKey.DESCRIPTION,
         }
         metadata_keys_direct_map_write = {
@@ -114,6 +116,7 @@ class _VorbisManager(_RatingSupportingMetadataManager):
             UnifiedMetadataKey.REPLAYGAIN: self.VorbisKey.REPLAYGAIN,
             UnifiedMetadataKey.PUBLISHER: self.VorbisKey.PUBLISHER,
             UnifiedMetadataKey.ISRC: self.VorbisKey.ISRC,
+            UnifiedMetadataKey.MUSICBRAINZ_TRACKID: self.VorbisKey.MUSICBRAINZ_TRACKID,
             UnifiedMetadataKey.DESCRIPTION: self.VorbisKey.DESCRIPTION,
         }
         super().__init__(
@@ -398,6 +401,7 @@ class _VorbisManager(_RatingSupportingMetadataManager):
                 "ENCODER": "ENCODER",
                 "URL": "URL",
                 "ISRC": "ISRC",
+                "MUSICBRAINZ_TRACKID": "MUSICBRAINZ_TRACKID",
                 "PUBLISHER": "PUBLISHER",
             }
 

{audiometa_python-0.9.0 → audiometa_python-0.11.0}/audiometa/test/helpers/id3v2/id3v2_frame_manual_creator.py

@@ -85,6 +85,60 @@ class ManualID3v2FrameCreator:
 
         ManualID3v2FrameCreator._write_id3v2_tag(file_path, frames, version)
 
+    @staticmethod
+    def _create_ufid_frame(owner: str, data: bytes, version: str = "2.4") -> bytes:
+        """Create a UFID (Unique File Identifier) frame.
+
+        Args:
+            owner: UFID owner identifier (null-terminated string)
+            data: UFID data (binary data, no null terminator)
+            version: ID3v2 version ("2.3" or "2.4")
+
+        Returns:
+            Complete UFID frame as bytes (header + frame data)
+        """
+        # UFID frame format:
+        # - Owner: null-terminated string (ISO-8859-1)
+        # - Data: binary data (no null terminator)
+        owner_bytes = owner.encode("latin1", errors="ignore") + b"\x00"
+        frame_data = owner_bytes + data
+
+        # Frame header: ID (4 bytes) + size (4 bytes) + flags (2 bytes)
+        frame_id_bytes = b"UFID"
+        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 create_ufid_frame(file_path: Path, owner: str, data: bytes, version: str = "2.4") -> None:
+        """Create a UFID frame in an ID3v2 tag.
+
+        Args:
+            file_path: Path to the audio file
+            owner: UFID owner identifier (e.g., "http://musicbrainz.org")
+            data: UFID data (binary data)
+            version: ID3v2 version ("2.3" or "2.4")
+        """
+        if version not in ["2.3", "2.4"]:
+            msg = "Version must be '2.3' or '2.4'"
+            raise ValueError(msg)
+        frame = ManualID3v2FrameCreator._create_ufid_frame(owner, data, version)
+        ManualID3v2FrameCreator._write_id3v2_tag(file_path, [frame], 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."""

{audiometa_python-0.9.0 → audiometa_python-0.11.0}/audiometa/test/helpers/id3v2/id3v2_metadata_setter.py

@@ -118,6 +118,29 @@ class ID3v2MetadataSetter:
                 cmd.extend(["--TDRC", release_date])
             metadata_added = True
 
+        # Handle musicbrainz_trackid (UFID frame) - needs special handling
+        musicbrainz_trackid = None
+        for key, value in metadata.items():
+            if key.lower() == "musicbrainz_trackid" and not isinstance(value, list) and value:
+                musicbrainz_trackid = str(value).strip()
+                break
+
+        if musicbrainz_trackid:
+            # Normalize UUID: convert 32-char hex to 36-char hyphenated format if needed
+            if len(musicbrainz_trackid) == 32 and all(c in "0123456789abcdefABCDEF" for c in musicbrainz_trackid):
+                musicbrainz_trackid = (
+                    f"{musicbrainz_trackid[:8]}-{musicbrainz_trackid[8:12]}-"
+                    f"{musicbrainz_trackid[12:16]}-{musicbrainz_trackid[16:20]}-{musicbrainz_trackid[20:32]}"
+                )
+            # Use manual frame creator for UFID frames to maintain test isolation
+            # (mid3v2 doesn't handle URLs with colons in UFID owner field correctly)
+            from .id3v2_frame_manual_creator import ManualID3v2FrameCreator
+
+            track_id_bytes = musicbrainz_trackid.encode("utf-8")
+            ManualID3v2FrameCreator.create_ufid_frame(
+                file_path, "http://musicbrainz.org", track_id_bytes, version=version
+            )
+
         # Handle non-list values (excluding already handled fields and list fields)
         # Only exclude list fields if they're actually lists (single strings should be processed)
         list_field_keys = set()
@@ -129,7 +152,7 @@ class ID3v2MetadataSetter:
             if (
                 key.lower() in key_mapping
                 and not isinstance(value, list)
-                and key.lower() not in ["disc_number", "disc_total", "release_date", "year"]
+                and key.lower() not in ["disc_number", "disc_total", "release_date", "year", "musicbrainz_trackid"]
                 and key.lower() not in list_field_keys  # Only exclude if it's actually a list
             ):
                 # Special handling for rating (POPM frame requires app name prefix)
@@ -506,3 +529,52 @@ class ID3v2MetadataSetter:
         creator = ManualID3v2FrameCreator()
         frame_data = creator._create_text_frame("TPE1", text, "2.4", encoding=encoding)
         creator._write_id3v2_tag(file_path, [frame_data], "2.4")
+
+    @staticmethod
+    def set_musicbrainz_trackid_ufid(file_path: Path, track_id: str) -> None:
+        """Set MusicBrainz Track ID using UFID frame (preferred format).
+
+        Uses manual binary construction to maintain test isolation (avoids using mutagen
+        which is also used in the implementation).
+
+        Args:
+            file_path: Path to the MP3 file
+            track_id: MusicBrainz Track ID (UUID string, hyphenated or 32-char hex)
+        """
+        from .id3v2_frame_manual_creator import ManualID3v2FrameCreator
+
+        track_id_bytes = track_id.encode("utf-8")
+        ManualID3v2FrameCreator.create_ufid_frame(file_path, "http://musicbrainz.org", track_id_bytes, version="2.4")
+
+    @staticmethod
+    def set_musicbrainz_trackid_txxx(file_path: Path, track_id: str) -> None:
+        """Set MusicBrainz Track ID using TXXX frame (fallback format).
+
+        Args:
+            file_path: Path to the MP3 file
+            track_id: MusicBrainz Track ID (UUID string, hyphenated or 32-char hex)
+        """
+        command = [
+            get_tool_path("mid3v2"),
+            "--TXXX",
+            f"MusicBrainz Track Id:{track_id}",
+            str(file_path),
+        ]
+        run_external_tool(command, "mid3v2")
+
+    @staticmethod
+    def set_ufid_with_owner(file_path: Path, owner: str, data: str) -> None:
+        """Set UFID frame with a specific owner (for testing purposes).
+
+        Uses manual binary construction to maintain test isolation (avoids using mutagen
+        which is also used in the implementation).
+
+        Args:
+            file_path: Path to the MP3 file
+            owner: UFID owner identifier (e.g., "http://musicbrainz.org", "http://example.com")
+            data: UFID data (typically a UUID or identifier string)
+        """
+        from .id3v2_frame_manual_creator import ManualID3v2FrameCreator
+
+        data_bytes = data.encode("utf-8")
+        ManualID3v2FrameCreator.create_ufid_frame(file_path, owner, data_bytes, version="2.4")

{audiometa_python-0.9.0 → audiometa_python-0.11.0}/audiometa/test/helpers/riff/riff_manual_metadata_creator.py

@@ -143,6 +143,18 @@ class ManualRIFFMetadataCreator:
         all_fields = [*existing_fields, rating_field]
         ManualRIFFMetadataCreator._write_riff_info_chunk(file_path, all_fields)
 
+    @staticmethod
+    def create_mbid_field(file_path: Path, mbid: str) -> None:
+        """Create MBID field in the RIFF INFO chunk, preserving existing fields."""
+        # Read existing fields and add MBID
+        existing_fields = ManualRIFFMetadataCreator._read_existing_info_fields(file_path)
+        # Remove existing MBID if present (we'll replace it)
+        existing_fields = [f for f in existing_fields if f[:4] != b"MBID"]
+        # Add new MBID field
+        mbid_field = ManualRIFFMetadataCreator._create_info_field("MBID", mbid)
+        all_fields = [*existing_fields, mbid_field]
+        ManualRIFFMetadataCreator._write_riff_info_chunk(file_path, all_fields)
+
     @staticmethod
     def _create_info_field(field_id: str, text: str) -> bytes:
         """Create a single RIFF INFO field with the given FourCC and text."""

{audiometa_python-0.9.0 → audiometa_python-0.11.0}/audiometa/test/helpers/riff/riff_metadata_setter.py

@@ -34,7 +34,9 @@ class RIFFMetadataSetter:
             "rating": "--IRTD",
             "copyright": "--ICOP",
             "isrc": "--ISRC",
+            "musicbrainz_trackid": "--MBID",
             "description": "--Description",
+            "originator": "--Originator",
         }
 
         # Handle list values - include first value in main command to avoid overwriting
@@ -50,8 +52,16 @@ class RIFFMetadataSetter:
                 elif key.lower() == "composer":
                     composer_value = value[0]  # Store first composer for main command
 
+        # Handle musicbrainz_trackid (MBID FourCC) - needs special handling with manual creator
+        musicbrainz_trackid = None
+        for key, value in metadata.items():
+            if key.lower() == "musicbrainz_trackid" and not isinstance(value, list) and value:
+                musicbrainz_trackid = str(value).strip()
+                break
+
         # Handle non-list values and include list values in main command
-        # Note: Rating, BPM, Language, and Composer need to be set AFTER bwfmetaedit to avoid being overwritten
+        # Note: Rating, BPM, Language, Composer, and MusicBrainz Track ID need to be set
+        # AFTER bwfmetaedit to avoid being overwritten
         rating_value = None
         bpm_value = None
         language_value = None
@@ -67,6 +77,9 @@ class RIFFMetadataSetter:
                     language_value = str(value)  # Store for later
                 elif key.lower() == "composer":
                     composer_single_value = str(value)  # Store for later
+                elif key.lower() == "musicbrainz_trackid":
+                    # Handled separately after bwfmetaedit
+                    pass
                 else:
                     cmd.extend([f"{key_mapping[key.lower()]}={value}"])
                     metadata_added = True
@@ -112,6 +125,12 @@ class RIFFMetadataSetter:
 
             ManualRIFFMetadataCreator.create_composer_field(file_path, composer_single_value)
 
+        # Set MusicBrainz Track ID (MBID FourCC) AFTER bwfmetaedit
+        if musicbrainz_trackid is not None:
+            from .riff_manual_metadata_creator import ManualRIFFMetadataCreator
+
+            ManualRIFFMetadataCreator.create_mbid_field(file_path, musicbrainz_trackid)
+
     @staticmethod
     def set_comment(file_path: Path, comment: str) -> None:
         command = ["bwfmetaedit", f"--ICMT={comment}", str(file_path)]

{audiometa_python-0.9.0 → audiometa_python-0.11.0}/audiometa/test/helpers/vorbis/vorbis_metadata_setter.py

@@ -59,6 +59,7 @@ class VorbisMetadataSetter:
             "encoder": "ENCODER",
             "url": "URL",
             "isrc": "ISRC",
+            "musicbrainz_trackid": "MUSICBRAINZ_TRACKID",
             "publisher": "PUBLISHER",
             "disc_number": "DISCNUMBER",
             "disc_total": "DISCTOTAL",