audiometa-python 1.3.3__tar.gz → 1.4.0__tar.gz

{audiometa_python-1.3.3/audiometa_python.egg-info → audiometa_python-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: audiometa-python
-Version: 1.3.3
+Version: 1.4.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>
@@ -9,7 +9,7 @@ Project-URL: Homepage, https://github.com/BehindTheMusicTree/audiometa
 Project-URL: Repository, https://github.com/BehindTheMusicTree/audiometa
 Project-URL: Issues, https://github.com/BehindTheMusicTree/audiometa/issues
 Keywords: audio,metadata,mp3,flac,wav,id3,vorbis,riff
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: OS Independent
@@ -321,11 +321,13 @@ AudioMeta uses a combination of Python libraries and external command-line tools
 
 ### Reading Metadata
 
-When reading metadata, there are three functions to use: `get_unified_metadata` and `get_unified_metadata_field`, and `get_full_metadata`.
+When reading metadata, the main entry points are `get_unified_metadata`, `get_unified_metadata_field`, and `get_full_metadata`. For tooling and UIs, `get_unified_metadata_field_schema` and `get_supported_unified_metadata_field_ids` describe the full unified vocabulary and which fields are writable for a given file’s primary format.
 
 - `get_unified_metadata`: Reads all metadata from a file and returns a unified dictionary.
 - `get_unified_metadata_field`: Reads a specific metadata field from a file.
-- `get_full_metadata`: Reads all metadata from a file and returns a dictionary including headers and technical info.
+- `get_full_metadata`: Reads all metadata from a file and returns a dictionary including headers, technical info, raw tags, **unified field schema**, and **per-file supported unified field ids**.
+- `get_unified_metadata_field_schema`: Returns wire-oriented descriptors (`id`, `label`, `multiple`, `value_type`, `optional_value`) for every `UnifiedMetadataKey` (no file required).
+- `get_supported_unified_metadata_field_ids`: Returns sorted unified field ids that have a write mapping for the file’s primary metadata format.
 
 #### Reading from a specific metadata format
 
@@ -413,6 +415,21 @@ except MetadataFieldNotSupportedByMetadataFormatError as e:
     print(f"Error: {e}")
 ```
 
+#### Unified field schema and writable field ids
+
+**`get_unified_metadata_field_schema()`** returns one descriptor per `UnifiedMetadataKey`: stable string **`id`** (the enum value), English **`label`**, **`multiple`**, JSON-oriented **`value_type`**, and **`optional_value`**. Use it for forms, validation, or API docs without hard-coding the enum.
+
+**`get_supported_unified_metadata_field_ids(file)`** returns sorted **`UnifiedMetadataKey.value`** strings for fields that have a non-`None` write mapping in the file’s **primary** (native) metadata format.
+
+```python
+from audiometa import get_unified_metadata_field_schema, get_supported_unified_metadata_field_ids
+
+schema = get_unified_metadata_field_schema()
+writable_on_this_file = get_supported_unified_metadata_field_ids("song.mp3")
+```
+
+`get_full_metadata` always includes **`unified_metadata_field_schema`** (same list as above) and **`supported_unified_metadata_field_ids`** for that path. The **`audiometa read`** command surfaces these keys in **JSON** and **YAML** output; **table** output only prints unified, technical, and format metadata sections.
+
 #### Reading Full Metadata From All Formats Including Headers and Technical Info
 
 **`get_full_metadata(file_path, include_headers=True, include_technical=True, include_raw_binary_data=False)`**
@@ -425,6 +442,8 @@ Gets comprehensive metadata including all available information from a file, inc
 from audiometa import get_full_metadata
 
 full_metadata = get_full_metadata("song.mp3")
+# full_metadata["unified_metadata_field_schema"]  — all unified keys
+# full_metadata["supported_unified_metadata_field_ids"]  — writable via primary format
 ```
 
 ### Validate Metadata Before Update
@@ -702,6 +721,7 @@ This function provides the most complete view of an audio file by combining:
 - Technical information (duration, bitrate, sample rate, channels, file size)
 - Format-specific headers and structure information
 - Raw metadata details from each format (when include_raw_binary_data is False, binary/opaque content such as APIC, PRIV, TRAKTOR4 is summarized as size placeholders)
+- **Unified field schema** (`unified_metadata_field_schema`) and **per-file writable unified ids** (`supported_unified_metadata_field_ids`); see `get_unified_metadata_field_schema` and `get_supported_unified_metadata_field_ids`
 
 ```python
 from audiometa import get_full_metadata, UnifiedMetadataKey
@@ -713,6 +733,10 @@ full_metadata = get_full_metadata("song.mp3")
 print(f"Title: {full_metadata['unified_metadata'][UnifiedMetadataKey.TITLE]}")
 print(f"Artists: {full_metadata['unified_metadata'][UnifiedMetadataKey.ARTISTS]}")
 
+# Field vocabulary and ids writable for this file's primary format
+print(full_metadata["unified_metadata_field_schema"][0])
+print(full_metadata["supported_unified_metadata_field_ids"])
+
 # Access technical information
 print(f"Duration: {full_metadata['technical_info']['duration_seconds']} seconds")
 print(f"Bitrate: {full_metadata['technical_info']['bitrate_bps']} bps ({full_metadata['technical_info']['bitrate_bps'] // 1000} kbps)")
@@ -839,6 +863,22 @@ A comprehensive dictionary containing:
             'chunk_structure': {...}
         }
     },
+    'unified_metadata_field_schema': [
+        {
+            'id': 'title',
+            'label': 'Title',
+            'multiple': False,
+            'value_type': 'string',
+            'optional_value': False,
+        },
+        # ... one entry per UnifiedMetadataKey
+    ],
+    'supported_unified_metadata_field_ids': [
+        'album',
+        'artists',
+        'title',
+        # ... ids with a write mapping for this file's primary format
+    ],
     'format_priorities': {
         'file_extension': '.mp3',
         'reading_order': ['id3v2', 'id3v1'],

{audiometa_python-1.3.3 → audiometa_python-1.4.0}/README.md

@@ -279,11 +279,13 @@ AudioMeta uses a combination of Python libraries and external command-line tools
 
 ### Reading Metadata
 
-When reading metadata, there are three functions to use: `get_unified_metadata` and `get_unified_metadata_field`, and `get_full_metadata`.
+When reading metadata, the main entry points are `get_unified_metadata`, `get_unified_metadata_field`, and `get_full_metadata`. For tooling and UIs, `get_unified_metadata_field_schema` and `get_supported_unified_metadata_field_ids` describe the full unified vocabulary and which fields are writable for a given file’s primary format.
 
 - `get_unified_metadata`: Reads all metadata from a file and returns a unified dictionary.
 - `get_unified_metadata_field`: Reads a specific metadata field from a file.
-- `get_full_metadata`: Reads all metadata from a file and returns a dictionary including headers and technical info.
+- `get_full_metadata`: Reads all metadata from a file and returns a dictionary including headers, technical info, raw tags, **unified field schema**, and **per-file supported unified field ids**.
+- `get_unified_metadata_field_schema`: Returns wire-oriented descriptors (`id`, `label`, `multiple`, `value_type`, `optional_value`) for every `UnifiedMetadataKey` (no file required).
+- `get_supported_unified_metadata_field_ids`: Returns sorted unified field ids that have a write mapping for the file’s primary metadata format.
 
 #### Reading from a specific metadata format
 
@@ -371,6 +373,21 @@ except MetadataFieldNotSupportedByMetadataFormatError as e:
     print(f"Error: {e}")
 ```
 
+#### Unified field schema and writable field ids
+
+**`get_unified_metadata_field_schema()`** returns one descriptor per `UnifiedMetadataKey`: stable string **`id`** (the enum value), English **`label`**, **`multiple`**, JSON-oriented **`value_type`**, and **`optional_value`**. Use it for forms, validation, or API docs without hard-coding the enum.
+
+**`get_supported_unified_metadata_field_ids(file)`** returns sorted **`UnifiedMetadataKey.value`** strings for fields that have a non-`None` write mapping in the file’s **primary** (native) metadata format.
+
+```python
+from audiometa import get_unified_metadata_field_schema, get_supported_unified_metadata_field_ids
+
+schema = get_unified_metadata_field_schema()
+writable_on_this_file = get_supported_unified_metadata_field_ids("song.mp3")
+```
+
+`get_full_metadata` always includes **`unified_metadata_field_schema`** (same list as above) and **`supported_unified_metadata_field_ids`** for that path. The **`audiometa read`** command surfaces these keys in **JSON** and **YAML** output; **table** output only prints unified, technical, and format metadata sections.
+
 #### Reading Full Metadata From All Formats Including Headers and Technical Info
 
 **`get_full_metadata(file_path, include_headers=True, include_technical=True, include_raw_binary_data=False)`**
@@ -383,6 +400,8 @@ Gets comprehensive metadata including all available information from a file, inc
 from audiometa import get_full_metadata
 
 full_metadata = get_full_metadata("song.mp3")
+# full_metadata["unified_metadata_field_schema"]  — all unified keys
+# full_metadata["supported_unified_metadata_field_ids"]  — writable via primary format
 ```
 
 ### Validate Metadata Before Update
@@ -660,6 +679,7 @@ This function provides the most complete view of an audio file by combining:
 - Technical information (duration, bitrate, sample rate, channels, file size)
 - Format-specific headers and structure information
 - Raw metadata details from each format (when include_raw_binary_data is False, binary/opaque content such as APIC, PRIV, TRAKTOR4 is summarized as size placeholders)
+- **Unified field schema** (`unified_metadata_field_schema`) and **per-file writable unified ids** (`supported_unified_metadata_field_ids`); see `get_unified_metadata_field_schema` and `get_supported_unified_metadata_field_ids`
 
 ```python
 from audiometa import get_full_metadata, UnifiedMetadataKey
@@ -671,6 +691,10 @@ full_metadata = get_full_metadata("song.mp3")
 print(f"Title: {full_metadata['unified_metadata'][UnifiedMetadataKey.TITLE]}")
 print(f"Artists: {full_metadata['unified_metadata'][UnifiedMetadataKey.ARTISTS]}")
 
+# Field vocabulary and ids writable for this file's primary format
+print(full_metadata["unified_metadata_field_schema"][0])
+print(full_metadata["supported_unified_metadata_field_ids"])
+
 # Access technical information
 print(f"Duration: {full_metadata['technical_info']['duration_seconds']} seconds")
 print(f"Bitrate: {full_metadata['technical_info']['bitrate_bps']} bps ({full_metadata['technical_info']['bitrate_bps'] // 1000} kbps)")
@@ -797,6 +821,22 @@ A comprehensive dictionary containing:
             'chunk_structure': {...}
         }
     },
+    'unified_metadata_field_schema': [
+        {
+            'id': 'title',
+            'label': 'Title',
+            'multiple': False,
+            'value_type': 'string',
+            'optional_value': False,
+        },
+        # ... one entry per UnifiedMetadataKey
+    ],
+    'supported_unified_metadata_field_ids': [
+        'album',
+        'artists',
+        'title',
+        # ... ids with a write mapping for this file's primary format
+    ],
     'format_priorities': {
         'file_extension': '.mp3',
         'reading_order': ['id3v2', 'id3v1'],

{audiometa_python-1.3.3 → audiometa_python-1.4.0}/audiometa/__init__.py

@@ -34,10 +34,13 @@ from .utils.flac_md5_state import FlacMd5State
 from .utils.metadata_format import MetadataFormat
 from .utils.metadata_writing_strategy import MetadataWritingStrategy
 from .utils.types import UnifiedMetadata, UnifiedMetadataValue
+from .utils.unified_metadata_field_schema import get_unified_metadata_field_schema
 from .utils.unified_metadata_key import UnifiedMetadataKey
 
 __all__ = [
     "UnifiedMetadataKey",
+    "get_unified_metadata_field_schema",
+    "get_supported_unified_metadata_field_ids",
     "FlacMd5State",
     "MetadataFormat",
     "MetadataWritingStrategy",
@@ -79,6 +82,35 @@ METADATA_FORMAT_MANAGER_CLASS_MAP: dict[MetadataFormat, type] = {
 type PublicFileType = str | Path
 
 
+def _supported_unified_metadata_field_ids_from_manager(manager: _MetadataManager | None) -> list[str]:
+    if manager is None:
+        return []
+    wmap = getattr(manager, "metadata_keys_direct_map_write", None)
+    if not wmap:
+        return []
+    return sorted(ukey.value for ukey, raw_key in wmap.items() if raw_key is not None)
+
+
+def get_supported_unified_metadata_field_ids(file: PublicFileType) -> list[str]:
+    """Return unified field ids writable to the file's primary (native) metadata format.
+
+    Keys are :attr:`UnifiedMetadataKey.value` strings. Fields with no write mapping
+    for that format (``None`` in the manager's write map) are omitted.
+    """
+    audio_file = _AudioFile(file)
+    available_formats = MetadataFormat.get_priorities().get(audio_file.file_extension, [])
+    if not available_formats:
+        return []
+    target_format = available_formats[0]
+    manager = _get_metadata_manager(
+        audio_file=audio_file,
+        metadata_format=target_format,
+        normalized_rating_max_value=None,
+        id3v2_version=None,
+    )
+    return _supported_unified_metadata_field_ids_from_manager(manager)
+
+
 def _get_metadata_manager(
     audio_file: _AudioFile,
     metadata_format: MetadataFormat | None = None,
@@ -1290,7 +1322,18 @@ def get_full_metadata(
             TRAKTOR4). If False (default), such content is replaced by size placeholders.
 
     Returns:
-        Comprehensive dictionary containing all available metadata and technical information
+        Comprehensive dictionary. Top-level keys always include:
+
+        - ``unified_metadata``: Same merged view as :func:`get_unified_metadata`
+        - ``technical_info``, ``metadata_format``, ``headers``, ``raw_metadata``: As documented below;
+          ``technical_info`` / ``headers`` may be empty dicts when disabled via parameters
+        - ``unified_metadata_field_schema``: List of field descriptors (``id``, ``label``, ``multiple``,
+          ``value_type``, ``optional_value``) for every
+          :class:`~audiometa.utils.unified_metadata_key.UnifiedMetadataKey`; same data as
+          :func:`get_unified_metadata_field_schema`
+        - ``supported_unified_metadata_field_ids``: Sorted :attr:`UnifiedMetadataKey.value` strings writable
+          for this file's primary metadata format (see :func:`get_supported_unified_metadata_field_ids`)
+        - ``format_priorities``: Extension, reading order, and primary writing format
 
     Raises:
         FileTypeNotSupportedError: If the file format is not supported
@@ -1315,6 +1358,10 @@ def get_full_metadata(
         # Access header information
         print(f"ID3v2 Version: {full_metadata['headers']['id3v2']['version']}")
         print(f"Has ID3v1 Header: {full_metadata['headers']['id3v1']['present']}")
+
+        # Full unified key schema; writable field ids for this file's primary format
+        print(len(full_metadata['unified_metadata_field_schema']))
+        print(full_metadata['supported_unified_metadata_field_ids'])
     """
     audio_file = _AudioFile(file)
 
@@ -1324,6 +1371,9 @@ def get_full_metadata(
     # Get file-specific format priorities
     available_formats = MetadataFormat.get_priorities().get(audio_file.file_extension, [])
 
+    primary_format = available_formats[0] if available_formats else None
+    primary_manager = all_managers.get(primary_format) if primary_format is not None else None
+
     # Initialize result structure
     result: dict[str, Any] = {
         "unified_metadata": {},
@@ -1331,6 +1381,8 @@ def get_full_metadata(
         "metadata_format": {},
         "headers": {},
         "raw_metadata": {},
+        "unified_metadata_field_schema": get_unified_metadata_field_schema(),
+        "supported_unified_metadata_field_ids": _supported_unified_metadata_field_ids_from_manager(primary_manager),
         "format_priorities": {
             "file_extension": audio_file.file_extension,
             "reading_order": [fmt.value for fmt in available_formats],

{audiometa_python-1.3.3 → audiometa_python-1.4.0}/audiometa/test/tests/integration/get_full_metadata/test_get_full_metadata.py

@@ -4,7 +4,7 @@ from pathlib import Path
 
 import pytest
 
-from audiometa import get_full_metadata
+from audiometa import UnifiedMetadataKey, get_full_metadata, get_unified_metadata_field_schema
 
 
 @pytest.mark.integration
@@ -20,6 +20,8 @@ class TestGetFullMetadata:
         assert "headers" in result
         assert "raw_metadata" in result
         assert "format_priorities" in result
+        assert "unified_metadata_field_schema" in result
+        assert "supported_unified_metadata_field_ids" in result
 
         # Check that each section is a dictionary
         assert isinstance(result["unified_metadata"], dict)
@@ -28,6 +30,16 @@ class TestGetFullMetadata:
         assert isinstance(result["headers"], dict)
         assert isinstance(result["raw_metadata"], dict)
         assert isinstance(result["format_priorities"], dict)
+        schema = result["unified_metadata_field_schema"]
+        assert isinstance(schema, list)
+        assert len(schema) == len(UnifiedMetadataKey)
+        assert {item["id"] for item in schema} == {k.value for k in UnifiedMetadataKey}
+        supported = result["supported_unified_metadata_field_ids"]
+        assert isinstance(supported, list)
+        assert all(isinstance(x, str) for x in supported)
+        assert supported == sorted(supported)
+        assert set(supported) <= {k.value for k in UnifiedMetadataKey}
+        assert schema == get_unified_metadata_field_schema()
 
     def test_get_full_metadata_format_priorities_structure(self, sample_mp3_file: Path):
         """Test that format_priorities has the expected structure."""

audiometa_python-1.4.0/audiometa/test/tests/unit/test_get_supported_unified_metadata_field_ids.py

@@ -0,0 +1,48 @@
+"""Tests for get_supported_unified_metadata_field_ids."""
+
+from pathlib import Path
+
+import pytest
+
+from audiometa import FileTypeNotSupportedError, get_full_metadata, get_supported_unified_metadata_field_ids
+
+
+@pytest.mark.unit
+class TestGetSupportedUnifiedMetadataFieldIds:
+    @pytest.mark.parametrize(
+        "fixture_name",
+        [
+            pytest.param("sample_mp3_file", id="mp3"),
+            pytest.param("sample_flac_file", id="flac"),
+            pytest.param("sample_wav_file", id="wav"),
+        ],
+    )
+    def test_returns_sorted_ids(self, fixture_name: str, request: pytest.FixtureRequest) -> None:
+        path: Path = request.getfixturevalue(fixture_name)
+        supported = get_supported_unified_metadata_field_ids(path)
+        assert supported == sorted(supported)
+
+    @pytest.mark.parametrize(
+        "fixture_name",
+        [
+            pytest.param("sample_mp3_file", id="mp3"),
+            pytest.param("sample_flac_file", id="flac"),
+            pytest.param("sample_wav_file", id="wav"),
+        ],
+    )
+    def test_matches_get_full_metadata(self, fixture_name: str, request: pytest.FixtureRequest) -> None:
+        path: Path = request.getfixturevalue(fixture_name)
+        direct = get_supported_unified_metadata_field_ids(path)
+        from_full = get_full_metadata(path)["supported_unified_metadata_field_ids"]
+        assert direct == from_full
+
+    def test_accepts_str_path(self, sample_mp3_file: Path) -> None:
+        a = get_supported_unified_metadata_field_ids(str(sample_mp3_file))
+        b = get_supported_unified_metadata_field_ids(sample_mp3_file)
+        assert a == b
+
+    def test_unsupported_extension_raises(self, tmp_path: Path) -> None:
+        p = tmp_path / "x.txt"
+        p.write_bytes(b"not audio")
+        with pytest.raises(FileTypeNotSupportedError):
+            get_supported_unified_metadata_field_ids(p)

audiometa_python-1.4.0/audiometa/test/tests/unit/utils/test_unified_metadata_field_schema.py

@@ -0,0 +1,88 @@
+"""Tests for unified metadata field schema helpers."""
+
+import pytest
+
+from audiometa import UnifiedMetadataKey, get_unified_metadata_field_schema
+from audiometa.utils.unified_metadata_field_schema import describe_unified_metadata_field
+
+
+def _expected_value_shape(key: UnifiedMetadataKey) -> tuple[str, bool, bool]:
+    if key.can_semantically_have_multiple_values():
+        return ("strings", True, False)
+    if key == UnifiedMetadataKey.TRACK_NUMBER:
+        return ("string_or_integer", False, False)
+    if key == UnifiedMetadataKey.DISC_TOTAL:
+        return ("integer", False, True)
+    if key == UnifiedMetadataKey.RATING:
+        return ("number", False, False)
+    opt = key.get_optional_type()
+    if opt is str:
+        return ("string", False, False)
+    if opt is int:
+        return ("integer", False, False)
+    return ("string", False, False)
+
+
+@pytest.mark.unit
+class TestUnifiedMetadataFieldSchema:
+    def test_schema_covers_all_enum_members(self) -> None:
+        schema = get_unified_metadata_field_schema()
+        ids = {entry["id"] for entry in schema}
+        assert ids == {k.value for k in UnifiedMetadataKey}
+
+    def test_each_descriptor_keys_and_id_match_enum(self) -> None:
+        required = {"id", "label", "multiple", "value_type", "optional_value"}
+        for key in UnifiedMetadataKey:
+            d = describe_unified_metadata_field(key)
+            assert set(d.keys()) == required
+            assert d["id"] == key.value
+            assert isinstance(d["label"], str)
+            assert d["label"]
+            assert isinstance(d["multiple"], bool)
+            assert isinstance(d["value_type"], str)
+            assert d["value_type"]
+            assert isinstance(d["optional_value"], bool)
+
+    def test_each_descriptor_value_shape_matches_contract(self) -> None:
+        for key in UnifiedMetadataKey:
+            d = describe_unified_metadata_field(key)
+            vt, mult, optv = _expected_value_shape(key)
+            assert d["value_type"] == vt
+            assert d["multiple"] is mult
+            assert d["optional_value"] is optv
+
+    def test_describe_title_scalar_string(self) -> None:
+        d = describe_unified_metadata_field(UnifiedMetadataKey.TITLE)
+        assert d["id"] == "title"
+        assert d["label"] == "Title"
+        assert d["multiple"] is False
+        assert d["value_type"] == "string"
+        assert d["optional_value"] is False
+
+    def test_describe_artists_multi_strings(self) -> None:
+        d = describe_unified_metadata_field(UnifiedMetadataKey.ARTISTS)
+        assert d["multiple"] is True
+        assert d["value_type"] == "strings"
+
+    def test_describe_track_number_string_or_integer(self) -> None:
+        d = describe_unified_metadata_field(UnifiedMetadataKey.TRACK_NUMBER)
+        assert d["value_type"] == "string_or_integer"
+        assert d["multiple"] is False
+        assert d["optional_value"] is False
+
+    def test_describe_disc_total_integer_optional_value(self) -> None:
+        d = describe_unified_metadata_field(UnifiedMetadataKey.DISC_TOTAL)
+        assert d["value_type"] == "integer"
+        assert d["optional_value"] is True
+        assert d["multiple"] is False
+
+    def test_describe_rating_number(self) -> None:
+        d = describe_unified_metadata_field(UnifiedMetadataKey.RATING)
+        assert d["value_type"] == "number"
+        assert d["multiple"] is False
+        assert d["optional_value"] is False
+
+    def test_describe_bpm_integer_scalar(self) -> None:
+        d = describe_unified_metadata_field(UnifiedMetadataKey.BPM)
+        assert d["value_type"] == "integer"
+        assert d["optional_value"] is False

{audiometa_python-1.3.3 → audiometa_python-1.4.0}/audiometa/utils/types.py

@@ -71,6 +71,16 @@ class RawMetadataInfo(TypedDict):
     chunk_structure: dict[str, Any]
 
 
+class UnifiedMetadataFieldDescriptor(TypedDict):
+    """Single entry from get_unified_metadata_field_schema()."""
+
+    id: str
+    label: str
+    multiple: bool
+    value_type: str
+    optional_value: bool
+
+
 class FullMetadata(TypedDict):
     """Type for comprehensive metadata returned by get_full_metadata."""
 
@@ -79,4 +89,6 @@ class FullMetadata(TypedDict):
     metadata_format: dict[str, UnifiedMetadata]
     headers: dict[str, HeaderInfo]
     raw_metadata: dict[str, RawMetadataInfo]
+    unified_metadata_field_schema: list[UnifiedMetadataFieldDescriptor]
+    supported_unified_metadata_field_ids: list[str]
     format_priorities: FormatPriorities

audiometa_python-1.4.0/audiometa/utils/unified_metadata_field_schema.py

@@ -0,0 +1,80 @@
+"""Wire-oriented schema for unified metadata fields (API / UI).
+
+Describes every :class:`UnifiedMetadataKey` with stable ids (enum values), human labels,
+and value shape hints. Format-specific mapping stays in metadata managers.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from audiometa.utils.unified_metadata_key import UnifiedMetadataKey
+
+# Stable English labels for clients that do not localize.
+_UNIFIED_METADATA_LABELS: dict[UnifiedMetadataKey, str] = {
+    UnifiedMetadataKey.TITLE: "Title",
+    UnifiedMetadataKey.ARTISTS: "Artists",
+    UnifiedMetadataKey.ALBUM: "Album",
+    UnifiedMetadataKey.ALBUM_ARTISTS: "Album artists",
+    UnifiedMetadataKey.GENRES_NAMES: "Genres",
+    UnifiedMetadataKey.RATING: "Rating",
+    UnifiedMetadataKey.LANGUAGE: "Language",
+    UnifiedMetadataKey.RELEASE_DATE: "Release date",
+    UnifiedMetadataKey.TRACK_NUMBER: "Track number",
+    UnifiedMetadataKey.DISC_NUMBER: "Disc number",
+    UnifiedMetadataKey.DISC_TOTAL: "Total discs",
+    UnifiedMetadataKey.BPM: "BPM",
+    UnifiedMetadataKey.COMPOSERS: "Composers",
+    UnifiedMetadataKey.PUBLISHER: "Publisher",
+    UnifiedMetadataKey.COPYRIGHT: "Copyright",
+    UnifiedMetadataKey.UNSYNCHRONIZED_LYRICS: "Lyrics (unsynchronized)",
+    UnifiedMetadataKey.COMMENT: "Comment",
+    UnifiedMetadataKey.REPLAYGAIN: "ReplayGain",
+    UnifiedMetadataKey.ARCHIVAL_LOCATION: "Archival location",
+    UnifiedMetadataKey.ISRC: "ISRC",
+    UnifiedMetadataKey.MUSICBRAINZ_TRACKID: "MusicBrainz recording ID",
+    UnifiedMetadataKey.MUSICBRAINZ_ARTISTIDS: "MusicBrainz artist IDs",
+    UnifiedMetadataKey.DESCRIPTION: "Description",
+    UnifiedMetadataKey.ORIGINATOR: "Originator",
+}
+
+# value_type is a coarse JSON-oriented hint for forms.
+# - strings: list of strings
+# - string, integer, number: scalar
+# - string_or_integer: track number (library accepts int or str on write)
+# integer with optional_value=True: may be null (e.g. disc total)
+_VALUE_SHAPE: dict[UnifiedMetadataKey, tuple[str, bool, bool]] = {}
+for _k in UnifiedMetadataKey:
+    if _k.can_semantically_have_multiple_values():
+        _VALUE_SHAPE[_k] = ("strings", True, False)
+    elif _k == UnifiedMetadataKey.TRACK_NUMBER:
+        _VALUE_SHAPE[_k] = ("string_or_integer", False, False)
+    elif _k == UnifiedMetadataKey.DISC_TOTAL:
+        _VALUE_SHAPE[_k] = ("integer", False, True)
+    elif _k == UnifiedMetadataKey.RATING:
+        _VALUE_SHAPE[_k] = ("number", False, False)
+    else:
+        _opt = _k.get_optional_type()
+        if _opt is str:
+            _VALUE_SHAPE[_k] = ("string", False, False)
+        elif _opt is int:
+            _VALUE_SHAPE[_k] = ("integer", False, False)
+        else:
+            _VALUE_SHAPE[_k] = ("string", False, False)
+
+
+def describe_unified_metadata_field(key: UnifiedMetadataKey) -> dict[str, Any]:
+    """Single field descriptor for APIs."""
+    value_type, multiple, optional_value = _VALUE_SHAPE[key]
+    return {
+        "id": key.value,
+        "label": _UNIFIED_METADATA_LABELS[key],
+        "multiple": multiple,
+        "value_type": value_type,
+        "optional_value": optional_value,
+    }
+
+
+def get_unified_metadata_field_schema() -> list[dict[str, Any]]:
+    """Return descriptors for all unified metadata keys (library vocabulary)."""
+    return [describe_unified_metadata_field(k) for k in UnifiedMetadataKey]