Add XMP metadata support for MP4 files

This patch adds basic XMP metadata support for MP4 files, using XMP
data as a fallback when standard MP4 metadata atoms are missing.

Implementation:
- Parse XMP data from standard UUID atoms (BE7ACFCB-97A9-42E8-9C71-999491E3AFAC)
- Support Dublin Core metadata fields (dc:title, dc:creator, dc:date, etc.)
- Parse structured filenames from stRef:filePath references in XMP
- Single-pass parsing: capture XMP during atom traversal
- Only process XMP when standard metadata is missing (fallback behavior)
- Clean up internal XMP data field after processing

XMP metadata is only used when the corresponding standard MP4 metadata
field is not present, ensuring compatibility with existing behavior while
providing fallback metadata extraction for files with incomplete tagging.

Author: aw-was-here

tinytag/tinytag.py

@@ -99,6 +99,7 @@ def __init__(self) -> None:
         self.genre: str | None = None
         self._genre_text: str | None = None  # From ©gen text atom
         self._genre_binary: str | None = None  # From gnre binary atom
+        self._xmp_data: bytes | None = None  # XMP data from uuid atoms
         self.year: str | None = None
         self.comment: str | None = None
 
@@ -280,6 +281,9 @@ def _cleanup_internal_fields(self) -> None:
             delattr(self, '_genre_text')
         if hasattr(self, '_genre_binary'):
             delattr(self, '_genre_binary')
+        # Remove XMP processing fields
+        if hasattr(self, '_xmp_data'):
+            delattr(self, '_xmp_data')
 
     def _set_field(self, fieldname: str, value: str | float,
                    check_conflict: bool = True) -> None:
@@ -524,7 +528,9 @@ def _parse_tag(self, fh: BinaryIO) -> None:
         # the atom data. Callables return {fieldname: value} which is updates
         # the TinyTag.
         if _MP4._meta_data_tree is None:
-            _MP4._meta_data_tree = {b'moov': {b'udta': {b'meta': {b'ilst': {
+            _MP4._meta_data_tree = {
+                b'uuid': lambda atom_data: {},  # handled by special case
+                b'moov': {b'udta': {b'meta': {b'ilst': {
                 # http://atomicparsley.sourceforge.net/mpeg-4files.html
                 # https://metacpan.org/dist/Image-ExifTool/source/lib/Image/ExifTool/QuickTime.pm#L3093
                 b'\xa9ART': {b'data': _MP4._data_parser('artist')},
@@ -551,10 +557,13 @@ def _parse_tag(self, fh: BinaryIO) -> None:
                 b'tmpo': {b'data': _MP4._data_parser('other.bpm')},
                 b'covr': {b'data': _MP4._parse_cover_image},
                 b'----': _MP4._parse_custom_field,
-            }}}}}
+                }}}},
+            }
         self._traverse_atoms(fh, path=_MP4._meta_data_tree)
         # Apply genre priority: prefer ©gen text over gnre binary
         self._resolve_mp4_genre()
+        # Apply XMP metadata as fallback for missing fields
+        self._apply_xmp_metadata_fallback()
 
     def _resolve_mp4_genre(self) -> None:
         """Apply MP4 genre priority: prefer ©gen text over gnre binary."""
@@ -568,6 +577,45 @@ def _resolve_mp4_genre(self) -> None:
         self._genre_text = None
         self._genre_binary = None
 
+    def _apply_xmp_metadata_fallback(self) -> None:
+        """Apply XMP metadata as fallback for missing MP4 fields."""
+        # Only process XMP if we have missing metadata and captured XMP data
+        if (self._xmp_data and
+            (not self.title or not self.artist or not self.album or
+             not self.year or not self.comment)):
+
+            # Process the stored XMP data
+            xmp_metadata = self._parse_xmp_metadata(self._xmp_data)
+
+            # Only use XMP data if TinyTag didn't find the corresponding fields
+            title = xmp_metadata.get("title")
+            if title and isinstance(title, str) and not self.title:
+                self.title = title
+            artist = xmp_metadata.get("artist")
+            if artist and isinstance(artist, str) and not self.artist:
+                self.artist = artist
+            album = xmp_metadata.get("album")
+            if album and isinstance(album, str) and not self.album:
+                self.album = album
+            track = xmp_metadata.get("track")
+            if track and not self.track:
+                try:
+                    if isinstance(track, str):
+                        self.track = int(track)
+                    elif isinstance(track, int):
+                        self.track = track
+                except (ValueError, TypeError):
+                    pass
+            year = xmp_metadata.get("year")
+            if year and isinstance(year, str) and not self.year:
+                self.year = year
+            comment = xmp_metadata.get("comment")
+            if comment and isinstance(comment, str) and not self.comment:
+                self.comment = comment
+
+        # Clear XMP data after processing
+        self._xmp_data = None
+
     def _traverse_atoms(self,
                         fh: BinaryIO,
                         path: _DataTreeDict,
@@ -621,7 +669,15 @@ def _traverse_atoms(self,
                                      curr_path=curr_path + [atom_type])
             # if the path-leaf is a callable, call it on the atom data
             elif callable(sub_path):
-                for fieldname, value in sub_path(fh.read(atom_size)).items():
+                atom_data = fh.read(atom_size)
+                # Special handling for UUID atoms to capture XMP data
+                if atom_type == b'uuid':
+                    self._parse_uuid_atom(atom_data)
+                    result_dict = {}
+                else:
+                    result_dict = sub_path(atom_data)
+
+                for fieldname, value in result_dict.items():
                     if _DEBUG:
                         print(' ' * 4 * len(curr_path), 'FIELD: ', fieldname)
                     if isinstance(value, Image):
@@ -699,6 +755,160 @@ def _parse_cover_image(cls, data_atom: bytes) -> dict[str, Image]:
             'front_cover', data_atom[8:], cls._IMAGE_MIME_TYPES.get(data_type))
         return {'images.front_cover': image}
 
+    def _parse_uuid_atom(
+        self, atom_data: bytes
+    ) -> dict[str, str | int | bool | list[str]]:
+        """Parse uuid atoms and capture XMP data."""
+        if len(atom_data) >= 16:
+            uuid_bytes = atom_data[:16]
+            content = atom_data[16:]
+
+            # Standard XMP UUID: BE7ACFCB-97A9-42E8-9C71-999491E3AFAC
+            xmp_uuid = bytes.fromhex("BE7ACFCB97A942E89C71999491E3AFAC")
+
+            if (uuid_bytes == xmp_uuid or
+                    content.startswith(b"<?xpacket begin=") or
+                    b"<x:xmpmeta" in content or
+                    b'xmlns:x="adobe:ns:meta/"' in content):
+                # Store XMP data for later processing
+                self._xmp_data = content
+
+        return {}  # uuid atoms don't directly set metadata fields
+
+    @classmethod
+    def _parse_filename_metadata(
+        cls, filename: str
+    ) -> dict[str, str | int | bool | list[str]]:
+        """Parse metadata from structured filename patterns."""
+        import re
+        metadata: dict[str, str | int | bool | list[str]] = {}
+
+        # Parse different filename patterns
+        parts = [part.strip() for part in filename.split(" - ")]
+        if len(parts) >= 4:
+            # Format: artist - album - track_number - title
+            metadata["artist"] = parts[0]
+            metadata["album"] = parts[1]
+            metadata["track"] = parts[2]
+            metadata["title"] = parts[3]
+        elif len(parts) == 3:
+            # Format: artist - album - title or artist - album - track_number
+            metadata["artist"] = parts[0]
+            metadata["album"] = parts[1]
+            third_part = parts[2]
+
+            # Check if third part is just a number (track number)
+            if third_part.isdigit():
+                metadata["track"] = third_part
+            else:
+                # Check if it starts with a track number
+                track_match = re.match(r"^(\d+)\s*[-.]?\s*(.+)", third_part)
+                if track_match:
+                    metadata["track"] = track_match.group(1)
+                    if track_match.group(2):
+                        metadata["title"] = track_match.group(2)
+                else:
+                    metadata["title"] = third_part
+        elif len(parts) == 2:
+            # Format: artist - title
+            metadata["artist"] = parts[0]
+            title_part = parts[1]
+
+            # Check if title starts with track number
+            track_match = re.match(r"^(\d+)\s*[-.]?\s*(.+)", title_part)
+            if track_match:
+                metadata["track"] = track_match.group(1)
+                if track_match.group(2):
+                    metadata["title"] = track_match.group(2)
+            else:
+                metadata["title"] = title_part
+
+        return metadata
+
+    @classmethod
+    def _parse_dublin_core_metadata(
+        cls, xmp_text: str
+    ) -> dict[str, str | int | bool | list[str]]:
+        """Parse Dublin Core metadata from XMP text."""
+        import re
+        metadata: dict[str, str | int | bool | list[str]] = {}
+
+        # Look for standard Dublin Core metadata
+        # dc:title → title
+        dc_title_pattern = r"<dc:title[^>]*>.*?<rdf:li[^>]*>(.*?)</rdf:li>"
+        title_matches = re.findall(dc_title_pattern, xmp_text, re.DOTALL)
+        if title_matches:
+            metadata["title"] = title_matches[0].strip()
+
+        # dc:creator → artist
+        dc_creator_pattern = r"<dc:creator[^>]*>.*?<rdf:li[^>]*>(.*?)</rdf:li>"
+        creator_matches = re.findall(dc_creator_pattern, xmp_text, re.DOTALL)
+        if creator_matches:
+            metadata["artist"] = creator_matches[0].strip()
+
+        # dc:date → year
+        dc_date_pattern = r"<dc:date[^>]*>.*?<rdf:li[^>]*>(.*?)</rdf:li>"
+        date_matches = re.findall(dc_date_pattern, xmp_text, re.DOTALL)
+        if date_matches:
+            year_match = re.match(r"(\d{4})", date_matches[0].strip())
+            if year_match:
+                metadata["year"] = year_match.group(1)
+
+        # dc:subject → comments
+        dc_subject_pattern = r"<dc:subject[^>]*>.*?<rdf:li[^>]*>(.*?)</rdf:li>"
+        subject_matches = re.findall(dc_subject_pattern, xmp_text, re.DOTALL)
+        if subject_matches:
+            metadata["comment"] = subject_matches[0].strip()
+
+        # dc:description → comments (overwrites subject)
+        desc_pattern = r"<dc:description[^>]*>.*?<rdf:li[^>]*>(.*?)</rdf:li>"
+        description_matches = re.findall(desc_pattern, xmp_text, re.DOTALL)
+        if description_matches:
+            metadata["comment"] = description_matches[0].strip()
+
+        return metadata
+
+    @classmethod
+    def _parse_xmp_metadata(
+        cls, xmp_content: bytes
+    ) -> dict[str, str | int | bool | list[str]]:
+        """Parse XMP content for music metadata fields."""
+        if not xmp_content:
+            return {}
+
+        try:
+            # Decode XMP content
+            xmp_text = xmp_content.decode("utf-8", errors="ignore")
+            metadata: dict[str, str | int | bool | list[str]] = {}
+
+            # Look for file references that contain music metadata
+            import re
+            file_path_pattern = r'stRef:filePath="([^"]+)"'
+            file_paths = re.findall(file_path_pattern, xmp_text)
+
+            for file_path in file_paths:
+                # Check if it's an audio file
+                audio_exts = [".wav", ".mp3", ".flac", ".aac", ".m4a"]
+                if file_path and any(
+                    file_path.lower().endswith(ext) for ext in audio_exts
+                ):
+                    # Parse metadata from filename
+                    filename = file_path.split("/")[-1]  # Get filename
+                    filename = re.sub(r"\.[^.]+$", "", filename)  # Remove ext
+                    metadata.update(cls._parse_filename_metadata(filename))
+                    break  # Use first audio file found
+
+            # Add Dublin Core metadata if filename parsing didn't work
+            dublin_metadata = cls._parse_dublin_core_metadata(xmp_text)
+            for key, value in dublin_metadata.items():
+                if key not in metadata:
+                    metadata[key] = value
+
+            return metadata
+
+        except Exception:
+            return {}
+
     @classmethod
     def _read_extended_descriptor(cls, esds_atom: BinaryIO) -> None:
         for _i in range(4):