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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: audiometa-python
-Version: 0.4.1
+Version: 0.6.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>
@@ -153,6 +153,8 @@ Your support helps make this project better for everyone! 🎵
 
 ### Format Capabilities
 
+For comprehensive information about each metadata format (history, structure, advantages, disadvantages, use cases), see the **[Metadata Formats Guide](docs/METADATA_FORMATS.md)**.
+
 #### ID3v1 Metadata Format
 
 - **Primary Support**: MP3 files (native format)
@@ -577,7 +579,7 @@ if is_audio_file("path/to/your/audio.flac"):
     file_size = get_file_size("path/to/your/audio.flac")
 
     print(f"Duration: {duration} seconds")
-    print(f"Bitrate: {bitrate} kbps")
+    print(f"Bitrate: {bitrate} bps ({bitrate // 1000} kbps)")
     print(f"Sample Rate: {sample_rate} Hz")
     print(f"Channels: {channels}")
     print(f"File Size: {file_size} bytes")
@@ -709,7 +711,7 @@ print(f"Artists: {full_metadata['unified_metadata'][UnifiedMetadataKey.ARTISTS]}
 
 # Access technical information
 print(f"Duration: {full_metadata['technical_info']['duration_seconds']} seconds")
-print(f"Bitrate: {full_metadata['technical_info']['bitrate_kbps']} kbps")
+print(f"Bitrate: {full_metadata['technical_info']['bitrate_bps']} bps ({full_metadata['technical_info']['bitrate_bps'] // 1000} kbps)")
 print(f"Sample Rate: {full_metadata['technical_info']['sample_rate_hz']} Hz")
 print(f"Channels: {full_metadata['technical_info']['channels']}")
 print(f"File Size: {full_metadata['technical_info']['file_size_bytes']} bytes")
@@ -749,7 +751,7 @@ A comprehensive dictionary containing:
     },
     'technical_info': {
         'duration_seconds': 180.5,
-        'bitrate_kbps': 320,
+        'bitrate_bps': 320000,
         'sample_rate_hz': 44100,
         'channels': 2,
         'file_size_bytes': 7234567,

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

@@ -111,6 +111,8 @@ Your support helps make this project better for everyone! 🎵
 
 ### Format Capabilities
 
+For comprehensive information about each metadata format (history, structure, advantages, disadvantages, use cases), see the **[Metadata Formats Guide](docs/METADATA_FORMATS.md)**.
+
 #### ID3v1 Metadata Format
 
 - **Primary Support**: MP3 files (native format)
@@ -535,7 +537,7 @@ if is_audio_file("path/to/your/audio.flac"):
     file_size = get_file_size("path/to/your/audio.flac")
 
     print(f"Duration: {duration} seconds")
-    print(f"Bitrate: {bitrate} kbps")
+    print(f"Bitrate: {bitrate} bps ({bitrate // 1000} kbps)")
     print(f"Sample Rate: {sample_rate} Hz")
     print(f"Channels: {channels}")
     print(f"File Size: {file_size} bytes")
@@ -667,7 +669,7 @@ print(f"Artists: {full_metadata['unified_metadata'][UnifiedMetadataKey.ARTISTS]}
 
 # Access technical information
 print(f"Duration: {full_metadata['technical_info']['duration_seconds']} seconds")
-print(f"Bitrate: {full_metadata['technical_info']['bitrate_kbps']} kbps")
+print(f"Bitrate: {full_metadata['technical_info']['bitrate_bps']} bps ({full_metadata['technical_info']['bitrate_bps'] // 1000} kbps)")
 print(f"Sample Rate: {full_metadata['technical_info']['sample_rate_hz']} Hz")
 print(f"Channels: {full_metadata['technical_info']['channels']}")
 print(f"File Size: {full_metadata['technical_info']['file_size_bytes']} bytes")
@@ -707,7 +709,7 @@ A comprehensive dictionary containing:
     },
     'technical_info': {
         'duration_seconds': 180.5,
-        'bitrate_kbps': 320,
+        'bitrate_bps': 320000,
         'sample_rate_hz': 44100,
         'channels': 2,
         'file_size_bytes': 7234567,

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

@@ -392,6 +392,80 @@ def _validate_unified_metadata_types(unified_metadata: UnifiedMetadata) -> None:
             )
 
 
+def _validate_rating_value(unified_metadata: UnifiedMetadata, normalized_rating_max_value: int | None) -> None:
+    """Validate rating value if present.
+
+    This is a shared helper used by both validate_metadata_for_update() and update_metadata().
+    """
+    if UnifiedMetadataKey.RATING not in unified_metadata:
+        return
+
+    rating_value = unified_metadata[UnifiedMetadataKey.RATING]
+    if rating_value is None:
+        return
+
+    if isinstance(rating_value, int | float):
+        # In raw mode (no normalization), only accept floats that can be parsed to int
+        # This allows the library to accept values like 196.0 as 196
+        if normalized_rating_max_value is None and isinstance(rating_value, float):
+            if rating_value.is_integer():
+                # Note: We can't modify the original dict here, caller handles this if needed
+                pass
+            else:
+                from .exceptions import InvalidRatingValueError
+
+                msg = (
+                    f"Rating value {rating_value} is invalid. In raw mode, float values must be whole numbers "
+                    f"(e.g., 196.0). Half-star values like {rating_value} require normalization."
+                )
+                raise InvalidRatingValueError(msg)
+        from .manager._rating_supporting._RatingSupportingMetadataManager import _RatingSupportingMetadataManager
+
+        _RatingSupportingMetadataManager.validate_rating_value(rating_value, normalized_rating_max_value)
+    else:
+        from .exceptions import InvalidRatingValueError
+
+        msg = f"Rating value must be numeric, got {type(rating_value).__name__}"
+        raise InvalidRatingValueError(msg)
+
+
+def _validate_metadata_field_formats(unified_metadata: UnifiedMetadata) -> None:
+    """Validate format of metadata fields that have specific format requirements.
+
+    Validates release_date, track_number, disc_number, disc_total, and isrc formats.
+    This is a shared helper used by both validate_metadata_for_update() and update_metadata().
+    """
+    # Validate release date if present and non-empty
+    if UnifiedMetadataKey.RELEASE_DATE in unified_metadata:
+        release_date_value = unified_metadata[UnifiedMetadataKey.RELEASE_DATE]
+        if release_date_value is not None and isinstance(release_date_value, str) and release_date_value:
+            _MetadataManager.validate_release_date(release_date_value)
+
+    # Validate track number if present and non-empty
+    if UnifiedMetadataKey.TRACK_NUMBER in unified_metadata:
+        track_number_value = unified_metadata[UnifiedMetadataKey.TRACK_NUMBER]
+        if track_number_value is not None and isinstance(track_number_value, str | int):
+            _MetadataManager.validate_track_number(track_number_value)
+
+    # Validate disc number if present and non-empty
+    if UnifiedMetadataKey.DISC_NUMBER in unified_metadata:
+        disc_number_value = unified_metadata[UnifiedMetadataKey.DISC_NUMBER]
+        if disc_number_value is not None and isinstance(disc_number_value, int):
+            _MetadataManager.validate_disc_number(disc_number_value)
+
+    # Validate disc total if present
+    if UnifiedMetadataKey.DISC_TOTAL in unified_metadata:
+        disc_total_value = unified_metadata[UnifiedMetadataKey.DISC_TOTAL]
+        if disc_total_value is None or isinstance(disc_total_value, int):
+            _MetadataManager.validate_disc_total(disc_total_value)
+
+    # Validate ISRC format if present and non-empty
+    if UnifiedMetadataKey.ISRC in unified_metadata:
+        isrc_value = unified_metadata[UnifiedMetadataKey.ISRC]
+        if isrc_value is not None and isinstance(isrc_value, str) and isrc_value:
+            _MetadataManager.validate_isrc(isrc_value)
+
+
 def validate_metadata_for_update(
     unified_metadata: dict[UnifiedMetadataKey, Any] | UnifiedMetadata,
     normalized_rating_max_value: int | None = None,
@@ -463,67 +537,11 @@ def validate_metadata_for_update(
     # Validate types
     _validate_unified_metadata_types(normalized_metadata)
 
-    # Validate rating if present and non-empty
-    if UnifiedMetadataKey.RATING in normalized_metadata:
-        rating_value = normalized_metadata[UnifiedMetadataKey.RATING]
-        if rating_value is not None:
-            if isinstance(rating_value, int | float):
-                # In raw mode (no normalization), only accept floats that can be parsed to int
-                # This allows the library to accept values like 196.0 as 196
-                if normalized_rating_max_value is None and isinstance(rating_value, float):
-                    if rating_value.is_integer():
-                        rating_value = int(rating_value)
-                        normalized_metadata[UnifiedMetadataKey.RATING] = rating_value
-                    else:
-                        from .exceptions import InvalidRatingValueError
-
-                        msg = (
-                            f"Rating value {rating_value} is invalid. In raw mode, float values must be whole numbers "
-                            f"(e.g., 196.0). Half-star values like {rating_value} require normalization."
-                        )
-                        raise InvalidRatingValueError(msg)
-                from .manager._rating_supporting._RatingSupportingMetadataManager import (
-                    _RatingSupportingMetadataManager,
-                )
-
-                _RatingSupportingMetadataManager.validate_rating_value(rating_value, normalized_rating_max_value)
-            else:
-                from .exceptions import InvalidRatingValueError
-
-                msg = f"Rating value must be numeric, got {type(rating_value).__name__}"
-                raise InvalidRatingValueError(msg)
-
-    # Validate release date if present and non-empty
-    if UnifiedMetadataKey.RELEASE_DATE in normalized_metadata:
-        release_date_value = normalized_metadata[UnifiedMetadataKey.RELEASE_DATE]
-        if release_date_value is not None and isinstance(release_date_value, str) and release_date_value:
-            from .manager._MetadataManager import _MetadataManager
-
-            _MetadataManager.validate_release_date(release_date_value)
-
-    # Validate track number if present and non-empty
-    if UnifiedMetadataKey.TRACK_NUMBER in normalized_metadata:
-        track_number_value = normalized_metadata[UnifiedMetadataKey.TRACK_NUMBER]
-        if track_number_value is not None:
-            from .manager._MetadataManager import _MetadataManager
-
-            if isinstance(track_number_value, str | int):
-                _MetadataManager.validate_track_number(track_number_value)
-
-    # Validate disc number if present and non-empty
-    if UnifiedMetadataKey.DISC_NUMBER in normalized_metadata:
-        disc_number_value = normalized_metadata[UnifiedMetadataKey.DISC_NUMBER]
-        if disc_number_value is not None:
-            from .manager._MetadataManager import _MetadataManager
-
-            _MetadataManager.validate_disc_number(disc_number_value)
-
-    # Validate disc total if present
-    if UnifiedMetadataKey.DISC_TOTAL in normalized_metadata:
-        disc_total_value = normalized_metadata[UnifiedMetadataKey.DISC_TOTAL]
-        from .manager._MetadataManager import _MetadataManager
+    # Validate rating if present
+    _validate_rating_value(normalized_metadata, normalized_rating_max_value)
 
-        _MetadataManager.validate_disc_total(disc_total_value)
+    # Validate field formats (release_date, track_number, disc_number, disc_total, isrc)
+    _validate_metadata_field_formats(normalized_metadata)
 
 
 def update_metadata(
@@ -641,22 +659,11 @@ def update_metadata(
     # Validate provided unified_metadata value types before attempting any writes
     _validate_unified_metadata_types(unified_metadata)
 
-    # Validate release date format if present and non-empty
-    if UnifiedMetadataKey.RELEASE_DATE in unified_metadata:
-        release_date_value = unified_metadata[UnifiedMetadataKey.RELEASE_DATE]
-        if release_date_value is not None and isinstance(release_date_value, str) and release_date_value:
-            from .manager._MetadataManager import _MetadataManager
-
-            _MetadataManager.validate_release_date(release_date_value)
-
-    # Validate track number format if present and non-empty
-    if UnifiedMetadataKey.TRACK_NUMBER in unified_metadata:
-        track_number_value = unified_metadata[UnifiedMetadataKey.TRACK_NUMBER]
-        if track_number_value is not None:
-            from .manager._MetadataManager import _MetadataManager
+    # Validate rating if present
+    _validate_rating_value(unified_metadata, normalized_rating_max_value)
 
-            if isinstance(track_number_value, str | int):
-                _MetadataManager.validate_track_number(track_number_value)
+    # Validate field formats (release_date, track_number, disc_number, disc_total, isrc)
+    _validate_metadata_field_formats(unified_metadata)
 
     _handle_metadata_strategy(
         audio_file,
@@ -941,7 +948,7 @@ def get_bitrate(file: PublicFileType) -> int:
         file: Audio file path (str or Path)
 
     Returns:
-        Bitrate in bits per second
+        Bitrate in bits per second (bps)
 
     Raises:
         FileTypeNotSupportedError: If the file format is not supported
@@ -950,6 +957,7 @@ def get_bitrate(file: PublicFileType) -> int:
     Examples:
         bitrate = get_bitrate("song.mp3")
         print(f"Bitrate: {bitrate} bps")
+        print(f"Bitrate: {bitrate // 1000} kbps")
     """
     audio_file = _AudioFile(file)
     return audio_file.get_bitrate()
@@ -1160,7 +1168,8 @@ def get_full_metadata(
 
         # Access technical information
         print(f"Duration: {full_metadata['technical_info']['duration_seconds']} seconds")
-        print(f"Bitrate: {full_metadata['technical_info']['bitrate_kbps']} kbps")
+        bitrate_bps = full_metadata['technical_info']['bitrate_bps']
+        print(f"Bitrate: {bitrate_bps} bps ({bitrate_bps // 1000} kbps)")
 
         # Access format-specific metadata
         print(f"ID3v2 Title: {full_metadata['metadata_format']['id3v2']['title']}")
@@ -1199,7 +1208,7 @@ def get_full_metadata(
         try:
             result["technical_info"] = {
                 "duration_seconds": audio_file.get_duration_in_sec(),
-                "bitrate_kbps": audio_file.get_bitrate(),
+                "bitrate_bps": audio_file.get_bitrate(),
                 "sample_rate_hz": audio_file.get_sample_rate(),
                 "channels": audio_file.get_channels(),
                 "file_size_bytes": get_file_size(file),
@@ -1212,7 +1221,7 @@ def get_full_metadata(
         except Exception:
             result["technical_info"] = {
                 "duration_seconds": 0,
-                "bitrate_kbps": 0,
+                "bitrate_bps": 0,
                 "sample_rate_hz": 0,
                 "channels": 0,
                 "file_size_bytes": 0,

{audiometa_python-0.4.1 → audiometa_python-0.6.0}/audiometa/_audio_file.py

@@ -174,7 +174,7 @@ class _AudioFile:
             audio = MP3(path)
             # Get MP3 bitrate directly from audio stream
             if audio.info.bitrate:
-                return int(audio.info.bitrate) // 1000
+                return int(audio.info.bitrate)
             return 0
         if self.file_extension == ".wav":
             try:
@@ -208,7 +208,7 @@ class _AudioFile:
                 stream = data["streams"][0]
                 # Get bitrate directly if available
                 if "bit_rate" in stream:
-                    return int(stream["bit_rate"]) // 1000
+                    return int(stream["bit_rate"])
 
                 # Calculate from sample_rate * channels * bits_per_sample if no direct bitrate
                 sample_rate = int(stream.get("sample_rate", 0))
@@ -219,7 +219,7 @@ class _AudioFile:
                     msg = "Missing audio stream information"
                     raise RuntimeError(msg) from None
 
-                return (sample_rate * channels * bits_per_sample) // 1000
+                return sample_rate * channels * bits_per_sample
             except json.JSONDecodeError as e:
                 msg = "Failed to parse audio file metadata from ffprobe output"
                 raise AudioFileMetadataParseError(msg) from e
@@ -228,7 +228,7 @@ class _AudioFile:
                 raise RuntimeError(msg) from exc
         elif self.file_extension == ".flac":
             audio_info = cast(StreamInfo, FLAC(path).info)
-            return int(float(audio_info.bitrate) / 1000)
+            return int(audio_info.bitrate)
         else:
             msg = f"Reading is not supported for file type: {self.file_extension}"
             raise FileTypeNotSupportedError(msg)

{audiometa_python-0.4.1 → audiometa_python-0.6.0}/audiometa/cli.py

@@ -93,6 +93,7 @@ def format_as_table(data: dict[str, Any]) -> str:
             "comment",
             "replaygain",
             "archival_location",
+            "isrc",
         }
         if unified_keys.intersection(set(data.keys())):
             # This is a unified metadata dict, wrap it
@@ -189,6 +190,8 @@ def _write_metadata(args: argparse.Namespace) -> None:
         metadata[UnifiedMetadataKey.REPLAYGAIN] = args.replaygain
     if args.archival_location and args.archival_location.strip():
         metadata[UnifiedMetadataKey.ARCHIVAL_LOCATION] = args.archival_location
+    if args.isrc and args.isrc.strip():
+        metadata[UnifiedMetadataKey.ISRC] = args.isrc
 
     # List fields (can be specified multiple times)
     if args.artist:
@@ -428,6 +431,7 @@ Examples:
     write_parser.add_argument("--comment", help="Comment")
     write_parser.add_argument("--replaygain", help="ReplayGain information")
     write_parser.add_argument("--archival-location", help="Archival location")
+    write_parser.add_argument("--isrc", help="International Standard Recording Code (12 characters)")
     write_parser.add_argument(
         "--force-format",
         choices=["id3v2", "id3v1", "vorbis", "riff"],

{audiometa_python-0.4.1 → audiometa_python-0.6.0}/audiometa/manager/_MetadataManager.py

@@ -215,6 +215,46 @@ class _MetadataManager:
                 UnifiedMetadataKey.DISC_TOTAL.value, "non-negative integer", str(disc_total)
             )
 
+    @staticmethod
+    def validate_isrc(isrc: str) -> None:
+        """Validate ISRC (International Standard Recording Code) format.
+
+        ISRC must be in one of the following formats:
+        - 12 alphanumeric characters without hyphens (e.g., "USRC17607839")
+        - 15 characters with hyphens in format CC-XXX-YY-NNNNN (e.g., "US-RC1-76-07839")
+          where CC=country code, XXX=registrant, YY=year, NNNNN=unique ID
+        - Empty string is allowed (represents no ISRC)
+
+        Args:
+            isrc: The ISRC string to validate
+
+        Raises:
+            InvalidMetadataFieldFormatError: If the ISRC format is invalid
+
+        Examples:
+            >>> _MetadataManager.validate_isrc("USRC17607839")  # Valid (12 chars)
+            >>> _MetadataManager.validate_isrc("US-RC1-76-07839")  # Valid (with hyphens)
+            >>> _MetadataManager.validate_isrc("")  # Valid (empty string)
+            >>> _MetadataManager.validate_isrc("ABC")  # Raises InvalidMetadataFieldFormatError
+        """
+        if not isrc:
+            return
+
+        # 12 alphanumeric characters without hyphens
+        if re.match(r"^[A-Za-z0-9]{12}$", isrc):
+            return
+
+        # 15 characters with hyphens: CC-XXX-YY-NNNNN
+        if re.match(r"^[A-Za-z]{2}-[A-Za-z0-9]{3}-\d{2}-\d{5}$", isrc):
+            return
+
+        raise InvalidMetadataFieldFormatError(
+            UnifiedMetadataKey.ISRC.value,
+            "12 alphanumeric characters (e.g., 'USRC17607839') or 15 characters with hyphens "
+            "(e.g., 'US-RC1-76-07839')",
+            isrc,
+        )
+
     @abstractmethod
     def _extract_mutagen_metadata(self) -> MutagenMetadata:
         raise NotImplementedError

{audiometa_python-0.4.1 → audiometa_python-0.6.0}/audiometa/manager/_rating_supporting/id3v2/_Id3v2Manager.py

@@ -283,6 +283,7 @@ class _Id3v2Manager(_RatingSupportingMetadataManager):
             UnifiedMetadataKey.UNSYNCHRONIZED_LYRICS: self.Id3TextFrame.UNSYNCHRONIZED_LYRICS,
             UnifiedMetadataKey.COMMENT: self.Id3TextFrame.COMMENT,
             UnifiedMetadataKey.REPLAYGAIN: None,
+            UnifiedMetadataKey.ISRC: self.Id3TextFrame.ISRC,
         }
         metadata_keys_direct_map_write: dict[UnifiedMetadataKey, RawMetadataKey | None] = {
             UnifiedMetadataKey.TITLE: self.Id3TextFrame.TITLE,
@@ -303,6 +304,7 @@ class _Id3v2Manager(_RatingSupportingMetadataManager):
             UnifiedMetadataKey.UNSYNCHRONIZED_LYRICS: self.Id3TextFrame.UNSYNCHRONIZED_LYRICS,
             UnifiedMetadataKey.COMMENT: self.Id3TextFrame.COMMENT,
             UnifiedMetadataKey.REPLAYGAIN: None,
+            UnifiedMetadataKey.ISRC: self.Id3TextFrame.ISRC,
         }
 
         super().__init__(