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

{audiometa_python-1.3.2/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.2
+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.2 → 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.2 → 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.2 → audiometa_python-1.4.0}/audiometa/manager/_MetadataManager.py

@@ -5,6 +5,7 @@ from typing import TYPE_CHECKING, TypeVar, Union, cast
 from mutagen._file import FileType as MutagenMetadata
 
 from audiometa.exceptions import InvalidMetadataFieldFormatError, InvalidMetadataFieldTypeError
+from audiometa.utils.disc_number_read import parse_disc_number_from_combined_str
 from audiometa.utils.unified_metadata_key import UnifiedMetadataKey
 
 if TYPE_CHECKING:
@@ -698,6 +699,10 @@ class _MetadataManager:
                 return track_str
             return None
 
+        # DISCNUMBER / TPOS-style "n", "n/m", "n-m" (formats using the base read path)
+        if unified_metadata_key == UnifiedMetadataKey.DISC_NUMBER:
+            return parse_disc_number_from_combined_str(str(value[0]))
+
         from typing import get_args, get_origin
 
         origin = get_origin(unified_metadata_key_optional_type)

{audiometa_python-1.3.2 → audiometa_python-1.4.0}/audiometa/manager/_rating_supporting/id3v2/_Id3v2Manager.py

@@ -30,6 +30,7 @@ from mutagen.id3._frames import (
 )
 from mutagen.id3._util import ID3NoHeaderError
 
+from audiometa.utils.disc_number_read import parse_disc_number_from_combined_str, parse_disc_total_from_combined_str
 from audiometa.utils.raw_metadata_sanitizer import sanitize_id3v2_raw_info
 from audiometa.utils.unified_metadata_key import UnifiedMetadataKey
 
@@ -415,12 +416,7 @@ class _Id3v2Manager(_RatingSupportingMetadataManager):
             if tpos_value is None or len(tpos_value) == 0:
                 return None
             tpos_str = str(tpos_value[0])
-            import re
-
-            match = re.match(r"^(\d+)(?:/(\d+))?$", tpos_str)
-            if match:
-                return int(match.group(1))
-            return None
+            return parse_disc_number_from_combined_str(tpos_str)
         if unified_metadata_key == UnifiedMetadataKey.DISC_TOTAL:
             tpos_key = self.Id3TextFrame.DISC_NUMBER
             if tpos_key not in raw_clean_metadata:
@@ -429,12 +425,7 @@ class _Id3v2Manager(_RatingSupportingMetadataManager):
             if tpos_value is None or len(tpos_value) == 0:
                 return None
             tpos_str = str(tpos_value[0])
-            import re
-
-            match = re.match(r"^(\d+)/(\d+)$", tpos_str)
-            if match:
-                return int(match.group(2))
-            return None
+            return parse_disc_total_from_combined_str(tpos_str)
         msg = f"Metadata key not handled: {unified_metadata_key}"
         raise MetadataFieldNotSupportedByMetadataFormatError(msg)
 

{audiometa_python-1.3.2 → audiometa_python-1.4.0}/audiometa/manager/_rating_supporting/vorbis/_VorbisManager.py

@@ -6,6 +6,11 @@ from typing import TYPE_CHECKING, Any, TypeVar, cast
 if TYPE_CHECKING:
     from ...._audio_file import _AudioFile
 from ....exceptions import FileCorruptedError, InvalidRatingValueError, MetadataFieldNotSupportedByMetadataFormatError
+from ....utils.disc_number_read import (
+    parse_disc_number_from_combined_str,
+    parse_disc_total_from_combined_str,
+    parse_explicit_non_negative_disctotal,
+)
 from ....utils.rating_profiles import RatingWriteProfile
 from ....utils.raw_metadata_sanitizer import sanitize_vorbis_raw_info
 from ....utils.tool_path_resolver import get_tool_path
@@ -260,6 +265,49 @@ class _VorbisManager(_RatingSupportingMetadataManager):
         # Cast to RawMetadataDict since RawMetadataKey is str, Enum and string keys work
         self.raw_clean_metadata_uppercase_keys = cast(RawMetadataDict, result_dict)
 
+    def get_unified_metadata_field(self, unified_metadata_key: UnifiedMetadataKey) -> UnifiedMetadataValue:
+        if unified_metadata_key not in (
+            UnifiedMetadataKey.DISC_NUMBER,
+            UnifiedMetadataKey.DISC_TOTAL,
+        ):
+            return super().get_unified_metadata_field(unified_metadata_key)
+
+        if self.raw_clean_metadata_uppercase_keys is None:
+            self._extract_raw_clean_metadata_uppercase_keys_from_file()
+        keys = self.raw_clean_metadata_uppercase_keys
+        if keys is None:
+            return None
+
+        disc_number_key = self.VorbisKey.DISC_NUMBER
+        disc_total_key = self.VorbisKey.DISC_TOTAL
+
+        def _first_string(raw_key: RawMetadataKey) -> str | None:
+            if raw_key not in keys:
+                return None
+            vals = keys[raw_key]
+            if not vals or len(vals) == 0:
+                return None
+            v = vals[0]
+            if v is None or v == "":
+                return None
+            return str(v)
+
+        d = _first_string(disc_number_key)
+        t = _first_string(disc_total_key)
+
+        if unified_metadata_key == UnifiedMetadataKey.DISC_NUMBER:
+            if d is None:
+                return None
+            return parse_disc_number_from_combined_str(d)
+
+        if t is not None:
+            explicit = parse_explicit_non_negative_disctotal(t)
+            if explicit is not None:
+                return explicit
+        if d is None:
+            return None
+        return parse_disc_total_from_combined_str(d)
+
     def _get_raw_rating_by_traktor_or_not(self, raw_clean_metadata: RawMetadataDict) -> tuple[int | None, bool]:
         if self.VorbisKey.RATING in raw_clean_metadata:
             rating_list = raw_clean_metadata[self.VorbisKey.RATING]

{audiometa_python-1.3.2 → 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/integration/metadata_field/disc_number/test_reading.py

@@ -0,0 +1,191 @@
+import pytest
+
+from audiometa import get_unified_metadata_field
+from audiometa.test.helpers.id3v2.id3v2_metadata_setter import ID3v2MetadataSetter
+from audiometa.test.helpers.temp_file_with_metadata import temp_file_with_metadata
+from audiometa.test.helpers.vorbis.vorbis_metadata_setter import VorbisMetadataSetter
+from audiometa.utils.unified_metadata_key import UnifiedMetadataKey
+
+
+@pytest.mark.integration
+class TestDiscNumberReading:
+    def test_id3v2_with_total(self):
+        with temp_file_with_metadata({}, "mp3") as test_file:
+            ID3v2MetadataSetter.set_metadata(test_file, {"disc_number": "1/2"})
+            disc_number = get_unified_metadata_field(test_file, UnifiedMetadataKey.DISC_NUMBER)
+            disc_total = get_unified_metadata_field(test_file, UnifiedMetadataKey.DISC_TOTAL)
+            assert disc_number == 1
+            assert disc_total == 2
+
+    def test_id3v2_without_total(self):
+        with temp_file_with_metadata({}, "mp3") as test_file:
+            ID3v2MetadataSetter.set_metadata(test_file, {"disc_number": "1"})
+            disc_number = get_unified_metadata_field(test_file, UnifiedMetadataKey.DISC_NUMBER)
+            disc_total = get_unified_metadata_field(test_file, UnifiedMetadataKey.DISC_TOTAL)
+            assert disc_number == 1
+            assert disc_total is None
+
+    def test_id3v2_max_value(self):
+        with temp_file_with_metadata({}, "mp3") as test_file:
+            ID3v2MetadataSetter.set_metadata(test_file, {"disc_number": "99/99"})
+            disc_number = get_unified_metadata_field(test_file, UnifiedMetadataKey.DISC_NUMBER)
+            disc_total = get_unified_metadata_field(test_file, UnifiedMetadataKey.DISC_TOTAL)
+            assert disc_number == 99
+            assert disc_total == 99
+
+    def test_id3v2_hyphen_separator_read(self):
+        with temp_file_with_metadata({}, "mp3") as test_file:
+            ID3v2MetadataSetter.set_metadata(test_file, {"disc_number": "1-2"})
+            disc_number = get_unified_metadata_field(test_file, UnifiedMetadataKey.DISC_NUMBER)
+            disc_total = get_unified_metadata_field(test_file, UnifiedMetadataKey.DISC_TOTAL)
+            assert disc_number == 1
+            assert disc_total == 2
+
+    def test_id3v2_invalid_tpos_multiple_slashes_returns_none(self):
+        with temp_file_with_metadata({}, "mp3") as test_file:
+            ID3v2MetadataSetter.set_metadata(test_file, {"disc_number": "1/2/3"})
+            disc_number = get_unified_metadata_field(test_file, UnifiedMetadataKey.DISC_NUMBER)
+            disc_total = get_unified_metadata_field(test_file, UnifiedMetadataKey.DISC_TOTAL)
+            assert disc_number is None
+            assert disc_total is None
+
+    def test_id3v2_read_tpos_above_255_not_clamped(self):
+        with temp_file_with_metadata({}, "mp3") as test_file:
+            ID3v2MetadataSetter.set_metadata(test_file, {"disc_number": "256/300"})
+            disc_number = get_unified_metadata_field(test_file, UnifiedMetadataKey.DISC_NUMBER)
+            disc_total = get_unified_metadata_field(test_file, UnifiedMetadataKey.DISC_TOTAL)
+            assert disc_number == 256
+            assert disc_total == 300
+
+    def test_vorbis_with_total(self):
+        with temp_file_with_metadata({}, "flac") as test_file:
+            VorbisMetadataSetter.set_metadata(test_file, {"disc_number": "1", "disc_total": "2"})
+            disc_number = get_unified_metadata_field(test_file, UnifiedMetadataKey.DISC_NUMBER)
+            disc_total = get_unified_metadata_field(test_file, UnifiedMetadataKey.DISC_TOTAL)
+            assert disc_number == 1
+            assert disc_total == 2
+
+    def test_vorbis_without_total(self):
+        with temp_file_with_metadata({}, "flac") as test_file:
+            VorbisMetadataSetter.set_metadata(test_file, {"disc_number": "2"})
+            disc_number = get_unified_metadata_field(test_file, UnifiedMetadataKey.DISC_NUMBER)
+            disc_total = get_unified_metadata_field(test_file, UnifiedMetadataKey.DISC_TOTAL)
+            assert disc_number == 2
+            assert disc_total is None
+
+    def test_vorbis_disc_number_combined_slash_form(self):
+        with temp_file_with_metadata({}, "flac") as test_file:
+            VorbisMetadataSetter.set_tag(test_file, "DISCNUMBER", "3/5")
+            disc_number = get_unified_metadata_field(test_file, UnifiedMetadataKey.DISC_NUMBER)
+            disc_total = get_unified_metadata_field(test_file, UnifiedMetadataKey.DISC_TOTAL)
+            assert disc_number == 3
+            assert disc_total == 5
+
+    def test_vorbis_discnumber_combined_slash_via_set_metadata(self):
+        with temp_file_with_metadata({}, "flac") as test_file:
+            VorbisMetadataSetter.set_metadata(test_file, {"disc_number": "1/2"})
+            disc_number = get_unified_metadata_field(test_file, UnifiedMetadataKey.DISC_NUMBER)
+            disc_total = get_unified_metadata_field(test_file, UnifiedMetadataKey.DISC_TOTAL)
+            assert disc_number == 1
+            assert disc_total == 2
+
+    def test_vorbis_disc_number_hyphen_form(self):
+        with temp_file_with_metadata({}, "flac") as test_file:
+            VorbisMetadataSetter.set_tag(test_file, "DISCNUMBER", "1-2")
+            disc_number = get_unified_metadata_field(test_file, UnifiedMetadataKey.DISC_NUMBER)
+            disc_total = get_unified_metadata_field(test_file, UnifiedMetadataKey.DISC_TOTAL)
+            assert disc_number == 1
+            assert disc_total == 2
+
+    def test_vorbis_disctotal_overrides_embedded_total(self):
+        with temp_file_with_metadata({}, "flac") as test_file:
+            VorbisMetadataSetter.set_tag(test_file, "DISCNUMBER", "1/3")
+            VorbisMetadataSetter.set_tag(test_file, "DISCTOTAL", "2")
+            disc_number = get_unified_metadata_field(test_file, UnifiedMetadataKey.DISC_NUMBER)
+            disc_total = get_unified_metadata_field(test_file, UnifiedMetadataKey.DISC_TOTAL)
+            assert disc_number == 1
+            assert disc_total == 2
+
+    def test_vorbis_discnumber_slash_with_matching_disctotal(self):
+        with temp_file_with_metadata({}, "flac") as test_file:
+            VorbisMetadataSetter.set_metadata(test_file, {"disc_number": "1/2", "disc_total": "2"})
+            disc_number = get_unified_metadata_field(test_file, UnifiedMetadataKey.DISC_NUMBER)
+            disc_total = get_unified_metadata_field(test_file, UnifiedMetadataKey.DISC_TOTAL)
+            assert disc_number == 1
+            assert disc_total == 2
+
+    def test_vorbis_invalid_disctotal_falls_back_to_discnumber_slash(self):
+        with temp_file_with_metadata({}, "flac") as test_file:
+            VorbisMetadataSetter.set_tag(test_file, "DISCNUMBER", "1/2")
+            VorbisMetadataSetter.set_tag(test_file, "DISCTOTAL", "bogus")
+            disc_number = get_unified_metadata_field(test_file, UnifiedMetadataKey.DISC_NUMBER)
+            disc_total = get_unified_metadata_field(test_file, UnifiedMetadataKey.DISC_TOTAL)
+            assert disc_number == 1
+            assert disc_total == 2
+
+    def test_vorbis_negative_disctotal_falls_back_to_discnumber_slash(self):
+        with temp_file_with_metadata({}, "flac") as test_file:
+            VorbisMetadataSetter.set_tag(test_file, "DISCNUMBER", "1/2")
+            VorbisMetadataSetter.set_tag(test_file, "DISCTOTAL", "-1")
+            disc_number = get_unified_metadata_field(test_file, UnifiedMetadataKey.DISC_NUMBER)
+            disc_total = get_unified_metadata_field(test_file, UnifiedMetadataKey.DISC_TOTAL)
+            assert disc_number == 1
+            assert disc_total == 2
+
+    def test_vorbis_invalid_combined_discnumber(self):
+        with temp_file_with_metadata({}, "flac") as test_file:
+            VorbisMetadataSetter.set_tag(test_file, "DISCNUMBER", "1/2/3")
+            disc_number = get_unified_metadata_field(test_file, UnifiedMetadataKey.DISC_NUMBER)
+            disc_total = get_unified_metadata_field(test_file, UnifiedMetadataKey.DISC_TOTAL)
+            assert disc_number is None
+            assert disc_total is None
+
+    def test_vorbis_disctotal_only(self):
+        with temp_file_with_metadata({}, "flac") as test_file:
+            VorbisMetadataSetter.set_tag(test_file, "DISCTOTAL", "2")
+            disc_number = get_unified_metadata_field(test_file, UnifiedMetadataKey.DISC_NUMBER)
+            disc_total = get_unified_metadata_field(test_file, UnifiedMetadataKey.DISC_TOTAL)
+            assert disc_number is None
+            assert disc_total == 2
+
+    def test_id3v1_not_supported(self):
+        from audiometa.exceptions import MetadataFieldNotSupportedByMetadataFormatError
+        from audiometa.utils.metadata_format import MetadataFormat
+
+        with temp_file_with_metadata({}, "id3v1") as test_file:
+            with pytest.raises(
+                MetadataFieldNotSupportedByMetadataFormatError,
+                match="UnifiedMetadataKey.DISC_NUMBER metadata not supported by ID3v1 format",
+            ):
+                get_unified_metadata_field(
+                    test_file, UnifiedMetadataKey.DISC_NUMBER, metadata_format=MetadataFormat.ID3V1
+                )
+
+            with pytest.raises(
+                MetadataFieldNotSupportedByMetadataFormatError,
+                match="UnifiedMetadataKey.DISC_TOTAL metadata not supported by ID3v1 format",
+            ):
+                get_unified_metadata_field(
+                    test_file, UnifiedMetadataKey.DISC_TOTAL, metadata_format=MetadataFormat.ID3V1
+                )
+
+    def test_riff_not_supported(self):
+        from audiometa.exceptions import MetadataFieldNotSupportedByMetadataFormatError
+        from audiometa.utils.metadata_format import MetadataFormat
+
+        with temp_file_with_metadata({}, "wav") as test_file:
+            with pytest.raises(
+                MetadataFieldNotSupportedByMetadataFormatError,
+                match="UnifiedMetadataKey.DISC_NUMBER metadata not supported by RIFF format",
+            ):
+                get_unified_metadata_field(
+                    test_file, UnifiedMetadataKey.DISC_NUMBER, metadata_format=MetadataFormat.RIFF
+                )
+
+            with pytest.raises(
+                MetadataFieldNotSupportedByMetadataFormatError,
+                match="UnifiedMetadataKey.DISC_TOTAL metadata not supported by RIFF format",
+            ):
+                get_unified_metadata_field(
+                    test_file, UnifiedMetadataKey.DISC_TOTAL, metadata_format=MetadataFormat.RIFF
+                )