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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: audiometa-python
-Version: 0.6.0
+Version: 0.6.1
 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>
@@ -480,6 +480,8 @@ from audiometa.utils.MetadataFormat import MetadataFormat
 update_metadata("song.wav", new_metadata, metadata_format=MetadataFormat.RIFF)
 ```
 
+**For comprehensive documentation** on writing strategies, format handling, and unsupported field management, see the **[Writing Metadata Guide](docs/WRITING_METADATA.md)**.
+
 ### Deleting Metadata
 
 There are two ways to remove metadata from audio files:
@@ -936,6 +938,10 @@ validate_metadata_for_update({UnifiedMetadataKey.RELEASE_DATE: "2024/01/01"})
 
 ### Writing Metadata (API Reference)
 
+**For comprehensive writing metadata documentation**, including writing strategies, format handling, unsupported field management, and advanced examples, see the dedicated guide:
+
+**[Writing Metadata Guide](docs/WRITING_METADATA.md)**
+
 For validation before writing, see [Pre-Update Validation (API Reference)](#pre-update-validation-api-reference).
 
 #### Metadata Dictionary Structure
@@ -1057,6 +1063,7 @@ The library provides flexible control over how metadata is written to files that
 1. **`SYNC` (Default)**: Write to native format and synchronize other metadata formats that are already present
 2. **`PRESERVE`**: Write to native format only, preserve existing metadata in other formats
 3. **`CLEANUP`**: Write to native format and remove all non-native metadata formats
+4. **`FORCE`**: Write only to the specified format (when `metadata_format` is provided), fail on unsupported fields
 
 ##### Usage Examples
 
@@ -1075,35 +1082,17 @@ update_metadata("song.wav", {"title": "New Title"},
 # PRESERVE strategy - keep other formats unchanged
 update_metadata("song.wav", {"title": "New Title"},
                     metadata_strategy=MetadataWritingStrategy.PRESERVE)
+
+# FORCE strategy - write only to specified format
+from audiometa.utils.MetadataFormat import MetadataFormat
+update_metadata("song.mp3", {"title": "New Title"},
+                    metadata_format=MetadataFormat.ID3V2)
 ```
 
 ##### Default Behavior
 
 By default, the library uses the **SYNC strategy** which writes metadata to the native format and synchronizes other metadata formats that are already present. This provides the best user experience by writing metadata where possible and handling unsupported fields gracefully.
 
-- **MP3 files**: Writes to ID3v2 and syncs other formats
-- **FLAC files**: Writes to Vorbis comments and syncs other formats
-- **WAV files**: Writes to RIFF and syncs other formats
-
-#### Forced Format Behavior
-
-When you specify a `metadata_format` parameter, you **cannot** also specify a `metadata_strategy`:
-
-- **Write only to the specified format**: Other formats are left completely untouched
-- **Fail fast on unsupported fields**: Raises `MetadataFieldNotSupportedByMetadataFormatError` for any unsupported metadata
-- **Predictable behavior**: No side effects on other metadata formats
-
-```python
-# Correct usage - specify only the format
-update_metadata("song.mp3", metadata,
-                    metadata_format=MetadataFormat.RIFF)  # Writes only to RIFF, ignores ID3v2
-
-# This will raise MetadataWritingConflictParametersError - cannot specify both parameters
-update_metadata("song.mp3", metadata,
-                    metadata_format=MetadataFormat.RIFF,
-                    metadata_strategy=MetadataWritingStrategy.CLEANUP)  # Raises MetadataWritingConflictParametersError
-```
-
 #### Usage Examples
 
 **Default Behavior (SYNC strategy)**
@@ -1111,13 +1100,14 @@ update_metadata("song.mp3", metadata,
 ```python
 from audiometa import update_metadata
 
-# WAV file with existing ID3v1 tags (30-char limit)
-update_metadata("song.wav", {"title": "This is a Very Long Title That Exceeds ID3v1 Limits"})
+# WAV file with existing ID3v1 tags (30-char limit and no album artist support)
+update_metadata("song.wav", {"title": "This is a Very Long Title That Exceeds ID3v1 Limits",
+                                 "album_artist": "Various Artists"})
 
 # Result:
-# - RIFF tags: Updated with full title (native format)
-# - ID3v1 tags: Synchronized with truncated title (30 chars max)
-# - When reading: RIFF title is returned (higher precedence)
+# - RIFF tags: Updated with full title (native format) and album artist
+# - ID3v1 tags: Synchronized only with truncated 30-char truncated title and no album artist (not supported)
+# - When reading: RIFF title is returned (higher precedence) and album artist is available
 # Note: ID3v1 title becomes "This is a Very Long Title Th" (truncated)
 ```
 
@@ -1152,11 +1142,15 @@ update_metadata("song.wav", {"title": "New Title"},
 # Note: SYNC preserves and updates ALL existing metadata formats
 ```
 
-**Format-Specific Writing**
+**FORCE Strategy - Format-Specific Writing**
 
 ```python
 from audiometa.utils.MetadataFormat import MetadataFormat
 
+# Write specifically to ID3v1 format
+update_metadata("song.flac", {"title": "New Title"},
+                    metadata_format=MetadataFormat.ID3V1)
+
 # Write specifically to ID3v2 format (even for WAV files)
 update_metadata("song.wav", {"title": "New Title"},
                     metadata_format=MetadataFormat.ID3V2)
@@ -1164,6 +1158,10 @@ update_metadata("song.wav", {"title": "New Title"},
 # Write specifically to RIFF format
 update_metadata("song.wav", {"title": "New Title"},
                     metadata_format=MetadataFormat.RIFF)
+
+# Write specifically to Vorbis format
+update_metadata("song.flac", {"title": "New Title"},
+                    metadata_format=MetadataFormat.VORBIS)
 ```
 
 ### Deleting Metadata (API Reference)
@@ -1344,17 +1342,17 @@ For comprehensive documentation on all exceptions that can be raised by the libr
 The library handles unsupported metadata consistently across all strategies:
 
 - **Forced format** (when `metadata_format` is specified): Always fails fast by raising `MetadataFieldNotSupportedByMetadataFormatError` for any unsupported field. **No writing is performed** - the file remains completely unchanged.
-- **All strategies (SYNC, PRESERVE, CLEANUP) with `fail_on_unsupported_field=False` (default)**: Handle unsupported fields gracefully by logging warnings and continuing with supported fields
+- **All strategies (SYNC, PRESERVE, CLEANUP) with `fail_on_unsupported_field=False` (default)**: Handle unsupported fields gracefully by logging individual warnings for each unsupported field and continuing with supported fields. For SYNC strategy, unsupported fields are filtered per-format, allowing all supported fields to sync to each format.
 - **All strategies (SYNC, PRESERVE, CLEANUP) with `fail_on_unsupported_field=True`**: Fails fast if any field is not supported by the target format. **No writing is performed** - the file remains completely unchanged (atomic operation).
 
 #### Format-Specific Limitations
 
-| Format         | Forced Format                     | All Strategies with `fail_on_unsupported_field=False`       | All Strategies with `fail_on_unsupported_field=True` |
-| -------------- | --------------------------------- | ----------------------------------------------------------- | ---------------------------------------------------- |
-| **RIFF (WAV)** | Always fails fast, **no writing** | Logs warnings for unsupported fields, writes supported ones | Fails fast for unsupported fields, **no writing**    |
-| **ID3v1**      | Always fails fast, **no writing** | Logs warnings for unsupported fields, writes supported ones | Fails fast for unsupported fields, **no writing**    |
-| **ID3v2**      | Always fails fast, **no writing** | All fields supported                                        | All fields supported                                 |
-| **Vorbis**     | Always fails fast, **no writing** | All fields supported                                        | All fields supported                                 |
+| Format         | Forced Format                     | All Strategies with `fail_on_unsupported_field=False`                 | All Strategies with `fail_on_unsupported_field=True` |
+| -------------- | --------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------- |
+| **RIFF (WAV)** | Always fails fast, **no writing** | Logs individual warnings per unsupported field, writes supported ones | Fails fast for unsupported fields, **no writing**    |
+| **ID3v1**      | Always fails fast, **no writing** | Logs individual warnings per unsupported field, writes supported ones | Fails fast for unsupported fields, **no writing**    |
+| **ID3v2**      | Always fails fast, **no writing** | All fields supported                                                  | All fields supported                                 |
+| **Vorbis**     | Always fails fast, **no writing** | All fields supported                                                  | All fields supported                                 |
 
 #### Atomic Write Operations
 

{audiometa_python-0.6.0 → audiometa_python-0.6.1}/README.md

@@ -438,6 +438,8 @@ from audiometa.utils.MetadataFormat import MetadataFormat
 update_metadata("song.wav", new_metadata, metadata_format=MetadataFormat.RIFF)
 ```
 
+**For comprehensive documentation** on writing strategies, format handling, and unsupported field management, see the **[Writing Metadata Guide](docs/WRITING_METADATA.md)**.
+
 ### Deleting Metadata
 
 There are two ways to remove metadata from audio files:
@@ -894,6 +896,10 @@ validate_metadata_for_update({UnifiedMetadataKey.RELEASE_DATE: "2024/01/01"})
 
 ### Writing Metadata (API Reference)
 
+**For comprehensive writing metadata documentation**, including writing strategies, format handling, unsupported field management, and advanced examples, see the dedicated guide:
+
+**[Writing Metadata Guide](docs/WRITING_METADATA.md)**
+
 For validation before writing, see [Pre-Update Validation (API Reference)](#pre-update-validation-api-reference).
 
 #### Metadata Dictionary Structure
@@ -1015,6 +1021,7 @@ The library provides flexible control over how metadata is written to files that
 1. **`SYNC` (Default)**: Write to native format and synchronize other metadata formats that are already present
 2. **`PRESERVE`**: Write to native format only, preserve existing metadata in other formats
 3. **`CLEANUP`**: Write to native format and remove all non-native metadata formats
+4. **`FORCE`**: Write only to the specified format (when `metadata_format` is provided), fail on unsupported fields
 
 ##### Usage Examples
 
@@ -1033,35 +1040,17 @@ update_metadata("song.wav", {"title": "New Title"},
 # PRESERVE strategy - keep other formats unchanged
 update_metadata("song.wav", {"title": "New Title"},
                     metadata_strategy=MetadataWritingStrategy.PRESERVE)
+
+# FORCE strategy - write only to specified format
+from audiometa.utils.MetadataFormat import MetadataFormat
+update_metadata("song.mp3", {"title": "New Title"},
+                    metadata_format=MetadataFormat.ID3V2)
 ```
 
 ##### Default Behavior
 
 By default, the library uses the **SYNC strategy** which writes metadata to the native format and synchronizes other metadata formats that are already present. This provides the best user experience by writing metadata where possible and handling unsupported fields gracefully.
 
-- **MP3 files**: Writes to ID3v2 and syncs other formats
-- **FLAC files**: Writes to Vorbis comments and syncs other formats
-- **WAV files**: Writes to RIFF and syncs other formats
-
-#### Forced Format Behavior
-
-When you specify a `metadata_format` parameter, you **cannot** also specify a `metadata_strategy`:
-
-- **Write only to the specified format**: Other formats are left completely untouched
-- **Fail fast on unsupported fields**: Raises `MetadataFieldNotSupportedByMetadataFormatError` for any unsupported metadata
-- **Predictable behavior**: No side effects on other metadata formats
-
-```python
-# Correct usage - specify only the format
-update_metadata("song.mp3", metadata,
-                    metadata_format=MetadataFormat.RIFF)  # Writes only to RIFF, ignores ID3v2
-
-# This will raise MetadataWritingConflictParametersError - cannot specify both parameters
-update_metadata("song.mp3", metadata,
-                    metadata_format=MetadataFormat.RIFF,
-                    metadata_strategy=MetadataWritingStrategy.CLEANUP)  # Raises MetadataWritingConflictParametersError
-```
-
 #### Usage Examples
 
 **Default Behavior (SYNC strategy)**
@@ -1069,13 +1058,14 @@ update_metadata("song.mp3", metadata,
 ```python
 from audiometa import update_metadata
 
-# WAV file with existing ID3v1 tags (30-char limit)
-update_metadata("song.wav", {"title": "This is a Very Long Title That Exceeds ID3v1 Limits"})
+# WAV file with existing ID3v1 tags (30-char limit and no album artist support)
+update_metadata("song.wav", {"title": "This is a Very Long Title That Exceeds ID3v1 Limits",
+                                 "album_artist": "Various Artists"})
 
 # Result:
-# - RIFF tags: Updated with full title (native format)
-# - ID3v1 tags: Synchronized with truncated title (30 chars max)
-# - When reading: RIFF title is returned (higher precedence)
+# - RIFF tags: Updated with full title (native format) and album artist
+# - ID3v1 tags: Synchronized only with truncated 30-char truncated title and no album artist (not supported)
+# - When reading: RIFF title is returned (higher precedence) and album artist is available
 # Note: ID3v1 title becomes "This is a Very Long Title Th" (truncated)
 ```
 
@@ -1110,11 +1100,15 @@ update_metadata("song.wav", {"title": "New Title"},
 # Note: SYNC preserves and updates ALL existing metadata formats
 ```
 
-**Format-Specific Writing**
+**FORCE Strategy - Format-Specific Writing**
 
 ```python
 from audiometa.utils.MetadataFormat import MetadataFormat
 
+# Write specifically to ID3v1 format
+update_metadata("song.flac", {"title": "New Title"},
+                    metadata_format=MetadataFormat.ID3V1)
+
 # Write specifically to ID3v2 format (even for WAV files)
 update_metadata("song.wav", {"title": "New Title"},
                     metadata_format=MetadataFormat.ID3V2)
@@ -1122,6 +1116,10 @@ update_metadata("song.wav", {"title": "New Title"},
 # Write specifically to RIFF format
 update_metadata("song.wav", {"title": "New Title"},
                     metadata_format=MetadataFormat.RIFF)
+
+# Write specifically to Vorbis format
+update_metadata("song.flac", {"title": "New Title"},
+                    metadata_format=MetadataFormat.VORBIS)
 ```
 
 ### Deleting Metadata (API Reference)
@@ -1302,17 +1300,17 @@ For comprehensive documentation on all exceptions that can be raised by the libr
 The library handles unsupported metadata consistently across all strategies:
 
 - **Forced format** (when `metadata_format` is specified): Always fails fast by raising `MetadataFieldNotSupportedByMetadataFormatError` for any unsupported field. **No writing is performed** - the file remains completely unchanged.
-- **All strategies (SYNC, PRESERVE, CLEANUP) with `fail_on_unsupported_field=False` (default)**: Handle unsupported fields gracefully by logging warnings and continuing with supported fields
+- **All strategies (SYNC, PRESERVE, CLEANUP) with `fail_on_unsupported_field=False` (default)**: Handle unsupported fields gracefully by logging individual warnings for each unsupported field and continuing with supported fields. For SYNC strategy, unsupported fields are filtered per-format, allowing all supported fields to sync to each format.
 - **All strategies (SYNC, PRESERVE, CLEANUP) with `fail_on_unsupported_field=True`**: Fails fast if any field is not supported by the target format. **No writing is performed** - the file remains completely unchanged (atomic operation).
 
 #### Format-Specific Limitations
 
-| Format         | Forced Format                     | All Strategies with `fail_on_unsupported_field=False`       | All Strategies with `fail_on_unsupported_field=True` |
-| -------------- | --------------------------------- | ----------------------------------------------------------- | ---------------------------------------------------- |
-| **RIFF (WAV)** | Always fails fast, **no writing** | Logs warnings for unsupported fields, writes supported ones | Fails fast for unsupported fields, **no writing**    |
-| **ID3v1**      | Always fails fast, **no writing** | Logs warnings for unsupported fields, writes supported ones | Fails fast for unsupported fields, **no writing**    |
-| **ID3v2**      | Always fails fast, **no writing** | All fields supported                                        | All fields supported                                 |
-| **Vorbis**     | Always fails fast, **no writing** | All fields supported                                        | All fields supported                                 |
+| Format         | Forced Format                     | All Strategies with `fail_on_unsupported_field=False`                 | All Strategies with `fail_on_unsupported_field=True` |
+| -------------- | --------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------- |
+| **RIFF (WAV)** | Always fails fast, **no writing** | Logs individual warnings per unsupported field, writes supported ones | Fails fast for unsupported fields, **no writing**    |
+| **ID3v1**      | Always fails fast, **no writing** | Logs individual warnings per unsupported field, writes supported ones | Fails fast for unsupported fields, **no writing**    |
+| **ID3v2**      | Always fails fast, **no writing** | All fields supported                                                  | All fields supported                                 |
+| **Vorbis**     | Always fails fast, **no writing** | All fields supported                                                  | All fields supported                                 |
 
 #### Atomic Write Operations
 

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

@@ -571,7 +571,9 @@ def update_metadata(
         metadata_format: Specific format to write to. If None, uses the file's native format.
             When specified, strategy is ignored and metadata is written only to this format.
         fail_on_unsupported_field: If True, fails when any metadata field is not supported by the target format.
-            Applies to all strategies (SYNC, PRESERVE, CLEANUP). Defaults to False (graceful handling with warnings).
+            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.
 
     Returns:
         None
@@ -597,7 +599,8 @@ 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)
-        handles gracefully with warnings.
+        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.
 
         Data Filtering:
         For list-type metadata fields (e.g., ARTISTS, GENRES), empty strings and None values
@@ -738,10 +741,12 @@ def _handle_metadata_strategy(
             if fail_on_unsupported_field:
                 msg = f"Fields not supported by {target_format_actual.value} format: {unsupported_fields}"
                 raise MetadataFieldNotSupportedByMetadataFormatError(msg)
-            warnings.warn(
-                f"Fields not supported by {target_format_actual.value} format will be skipped: {unsupported_fields}",
-                stacklevel=2,
-            )
+            # 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)
             # 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
@@ -777,10 +782,12 @@ def _handle_metadata_strategy(
                 ) and field not in target_manager.metadata_keys_direct_map_write:
                     unsupported_fields.append(field)
             if unsupported_fields:
-                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)
+                # 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)
                 # 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
@@ -804,16 +811,31 @@ def _handle_metadata_strategy(
         # Then sync all other available formats
         # Note: We need to be careful about the order to avoid conflicts
         for fmt_name, manager in other_managers.items():
-            try:
-                manager.update_metadata(unified_metadata)
-            except MetadataFieldNotSupportedByMetadataFormatError as e:
-                # For SYNC strategy, log warning but continue with other formats
-                format_warn_msg = f"Format {fmt_name} doesn't support some metadata fields: {e}"
-                warnings.warn(format_warn_msg, stacklevel=2)
-                continue
-            except Exception:
-                # Some managers might not support writing or might fail for other reasons
-                pass
+            # For non-target formats, filter out unsupported fields and warn about them
+            # This allows syncing supported fields even when some fields are not supported
+            unsupported_fields = []
+            if hasattr(manager, "metadata_keys_direct_map_write") and manager.metadata_keys_direct_map_write:
+                for field in unified_metadata:
+                    if field not in manager.metadata_keys_direct_map_write:
+                        unsupported_fields.append(field)
+
+            # Create filtered metadata with only supported fields
+            format_metadata = (
+                {k: v for k, v in unified_metadata.items() if k not in unsupported_fields}
+                if unsupported_fields
+                else unified_metadata
+            )
+
+            # 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)
+
+            # Try to update with supported fields only
+            if format_metadata:  # Only update if there are supported fields
+                with contextlib.suppress(Exception):
+                    # Some managers might fail for other reasons - continue with next format
+                    manager.update_metadata(format_metadata)
 
     elif strategy == MetadataWritingStrategy.PRESERVE:
         # For PRESERVE, we need to save existing metadata from other formats first

{audiometa_python-0.6.0 → audiometa_python-0.6.1}/audiometa/test/helpers/common/external_tool_runner.py

@@ -27,7 +27,18 @@ def run_external_tool(
     """
     try:
         text = not isinstance(input_data, bytes) if input_data is not None else True
-        return subprocess.run(command, capture_output=True, text=text, check=check, input=input_data)
+
+        # Ensure venv's bin directory is in PATH for Python tools like mid3v2
+        import os
+        import sys
+
+        env = os.environ.copy()
+        if hasattr(sys, "prefix"):
+            venv_bin = Path(sys.prefix) / "bin"
+            if venv_bin.exists():
+                env["PATH"] = f"{venv_bin}:{env.get('PATH', '')}"
+
+        return subprocess.run(command, capture_output=True, text=text, check=check, input=input_data, env=env)
     except (subprocess.CalledProcessError, FileNotFoundError) as e:
         msg = f"{tool_name} failed: {e}"
         raise ExternalMetadataToolError(msg) from e

{audiometa_python-0.6.0 → audiometa_python-0.6.1}/audiometa/test/helpers/id3v2/id3v2_metadata_setter.py

@@ -3,6 +3,8 @@
 from pathlib import Path
 from typing import Any
 
+from audiometa.utils.tool_path_resolver import get_tool_path
+
 from ..common.external_tool_runner import run_external_tool
 
 
@@ -47,7 +49,7 @@ class ID3v2MetadataSetter:
             }
         else:
             tool = "mid3v2"
-            cmd = ["mid3v2"]
+            cmd = [get_tool_path("mid3v2")]
             # Map common metadata keys to mid3v2 tool arguments
             key_mapping = {
                 "title": "--song",
@@ -174,7 +176,7 @@ class ID3v2MetadataSetter:
             command = ["id3v2", "--id3v2-only", "--song", title, str(file_path)]
             run_external_tool(command, "id3v2")
         else:
-            command = ["mid3v2", "--song", title, str(file_path)]
+            command = [get_tool_path("mid3v2"), "--song", title, str(file_path)]
             run_external_tool(command, "mid3v2")
 
     @staticmethod
@@ -200,7 +202,7 @@ class ID3v2MetadataSetter:
                 run_external_tool(command, "id3v2")
             else:
                 # Use mid3v2 for ID3v2.4
-                command = ["mid3v2", "--artist", artists, str(file_path)]
+                command = [get_tool_path("mid3v2"), "--artist", artists, str(file_path)]
                 run_external_tool(command, "mid3v2")
         else:
             # For list input, use multiple values handling
@@ -214,7 +216,7 @@ class ID3v2MetadataSetter:
             command = ["id3v2", "--id3v2-only", "--album", album, str(file_path)]
             run_external_tool(command, "id3v2")
         else:
-            command = ["mid3v2", "--album", album, str(file_path)]
+            command = [get_tool_path("mid3v2"), "--album", album, str(file_path)]
             run_external_tool(command, "mid3v2")
 
     @staticmethod
@@ -232,7 +234,7 @@ class ID3v2MetadataSetter:
             command = ["id3v2", "--id3v2-only", "--USLT", lyrics, str(file_path)]
             run_external_tool(command, "id3v2")
         else:
-            command = ["mid3v2", "--USLT", lyrics, str(file_path)]
+            command = [get_tool_path("mid3v2"), "--USLT", lyrics, str(file_path)]
             run_external_tool(command, "mid3v2")
 
     @staticmethod
@@ -287,7 +289,7 @@ class ID3v2MetadataSetter:
                 run_external_tool(command, "id3v2")
         else:
             # ID3v2.4: Use TDRC with full date
-            command = ["mid3v2", "--TDRC", date_str, str(file_path)]
+            command = [get_tool_path("mid3v2"), "--TDRC", date_str, str(file_path)]
             run_external_tool(command, "mid3v2")
 
     @staticmethod

{audiometa_python-0.6.0 → audiometa_python-0.6.1}/audiometa/test/tests/integration/writing/writing_strategies/test_sync_strategy.py

@@ -213,3 +213,67 @@ class TestSyncStrategy:
 
             vorbis_after = get_unified_metadata(test_file, metadata_format=MetadataFormat.VORBIS)
             assert vorbis_after.get(UnifiedMetadataKey.TITLE) == "Synced Title"
+
+    def test_sync_strategy_mp3_genre_and_album_artist(self):
+        """Test SYNC strategy updates genre and album artist on MP3 file with ID3v1 present.
+
+        This test verifies that when writing metadata with SYNC strategy:
+        1. ID3v2 metadata is written with all fields including genre and album artist
+        2. ID3v1 metadata is synced with supported fields (genre) but unsupported fields (album_artists) are skipped
+        """
+        with temp_file_with_metadata({}, "mp3") as test_file:
+            # Add ID3v1 metadata using external tools (to establish ID3v1 as an existing format)
+            ID3v1MetadataSetter.set_metadata(
+                test_file,
+                {
+                    "title": "ID3v1 Title",
+                    "artist": "ID3v1 Artist",
+                    "album": "ID3v1 Album",
+                    "genre": "Rock",
+                },
+            )
+
+            # Verify ID3v1 metadata was written
+            id3v1_result = get_unified_metadata(test_file, metadata_format=MetadataFormat.ID3V1)
+            assert id3v1_result.get(UnifiedMetadataKey.TITLE) == "ID3v1 Title"
+            assert id3v1_result.get(UnifiedMetadataKey.GENRES_NAMES) == ["Rock"]
+
+            # Now write ID3v2 metadata with SYNC strategy including genre and album artist
+            # SYNC should write to ID3v2 (native format) and sync to ID3v1 (existing format)
+            id3v2_metadata = {
+                UnifiedMetadataKey.TITLE: "Synced Title",
+                UnifiedMetadataKey.ARTISTS: ["Synced Artist"],
+                UnifiedMetadataKey.ALBUM: "Synced Album",
+                UnifiedMetadataKey.GENRES_NAMES: ["Jazz", "Blues"],
+                UnifiedMetadataKey.ALBUM_ARTISTS: ["Album Artist 1", "Album Artist 2"],
+            }
+            update_metadata(test_file, id3v2_metadata, metadata_strategy=MetadataWritingStrategy.SYNC)
+
+            # Verify ID3v2 metadata has all values including multiple genres and album artists
+            id3v2_after = get_unified_metadata(test_file, metadata_format=MetadataFormat.ID3V2)
+            assert id3v2_after.get(UnifiedMetadataKey.TITLE) == "Synced Title"
+            assert id3v2_after.get(UnifiedMetadataKey.ARTISTS) == ["Synced Artist"]
+            assert id3v2_after.get(UnifiedMetadataKey.ALBUM) == "Synced Album"
+            assert id3v2_after.get(UnifiedMetadataKey.GENRES_NAMES) == ["Jazz", "Blues"]
+            assert id3v2_after.get(UnifiedMetadataKey.ALBUM_ARTISTS) == ["Album Artist 1", "Album Artist 2"]
+
+            # Verify ID3v1 metadata was synced with supported fields only
+            # When SYNC strategy encounters unsupported fields (like ALBUM_ARTISTS in ID3v1),
+            # it should sync only the supported fields and skip the unsupported ones.
+            # This is the correct behavior for non-target formats in SYNC strategy.
+            id3v1_after = get_unified_metadata(test_file, metadata_format=MetadataFormat.ID3V1)
+
+            # ID3v1 should be synced with all supported fields
+            assert id3v1_after.get(UnifiedMetadataKey.TITLE) == "Synced Title"
+            assert id3v1_after.get(UnifiedMetadataKey.ARTISTS) == ["Synced Artist"]
+            assert id3v1_after.get(UnifiedMetadataKey.ALBUM) == "Synced Album"
+            assert id3v1_after.get(UnifiedMetadataKey.GENRES_NAMES) == ["Jazz"]  # Only first genre in ID3v1
+
+            # Album artists are not supported in ID3v1, should be None (field is skipped)
+            assert id3v1_after.get(UnifiedMetadataKey.ALBUM_ARTISTS) is None
+
+            # Merged metadata should prefer ID3v2 (higher precedence)
+            merged = get_unified_metadata(test_file)
+            assert merged.get(UnifiedMetadataKey.TITLE) == "Synced Title"
+            assert merged.get(UnifiedMetadataKey.GENRES_NAMES) == ["Jazz", "Blues"]
+            assert merged.get(UnifiedMetadataKey.ALBUM_ARTISTS) == ["Album Artist 1", "Album Artist 2"]

{audiometa_python-0.6.0 → audiometa_python-0.6.1}/audiometa/utils/tool_path_resolver.py

@@ -27,7 +27,7 @@ def get_tool_path(tool_name: str) -> str:
     name if pinned version path cannot be resolved (relies on PATH).
 
     Args:
-        tool_name: Name of the tool (e.g., "flac", "ffprobe", "metaflac")
+        tool_name: Name of the tool (e.g., "flac", "ffprobe", "metaflac", "mid3v2")
 
     Returns:
         Absolute path to pinned version executable, or tool name if not found
@@ -48,6 +48,7 @@ def get_tool_path(tool_name: str) -> str:
         "metaflac": "flac",  # metaflac comes from flac package
         "mediainfo": "media-info",
         "id3v2": "id3v2",
+        "mid3v2": "mutagen",  # mid3v2 comes from mutagen package
         "bwfmetaedit": "bwfmetaedit",
         "exiftool": "exiftool",
     }