TonieToolbox 0.5.0a1__py3-none-any.whl → 0.6.0a1__py3-none-any.whl

TonieToolbox/media_tags.py

@@ -13,8 +13,8 @@ import base64
 from mutagen.flac import Picture
 from .logger import get_logger
 from .dependency_manager import is_mutagen_available, ensure_mutagen
+from .constants import ARTWORK_NAMES, ARTWORK_EXTENSIONS, TAG_VALUE_REPLACEMENTS, TAG_MAPPINGS
 
-# Global variables to track dependency state and store module references
 MUTAGEN_AVAILABLE = False
 mutagen = None
 ID3 = None
@@ -53,84 +53,11 @@ def _import_mutagen():
         MUTAGEN_AVAILABLE = False
         return False
 
-# Try to import mutagen if it's available
 if is_mutagen_available():
     _import_mutagen()
 
 logger = get_logger('media_tags')
 
-# Define tag mapping for different formats to standardized names
-# This helps normalize tags across different audio formats
-TAG_MAPPING = {
-    # ID3 (MP3) tags
-    'TIT2': 'title',
-    'TALB': 'album',
-    'TPE1': 'artist',
-    'TPE2': 'albumartist',
-    'TCOM': 'composer',
-    'TRCK': 'tracknumber',
-    'TPOS': 'discnumber',
-    'TDRC': 'date',
-    'TCON': 'genre',
-    'TPUB': 'publisher',
-    'TCOP': 'copyright',
-    'COMM': 'comment',
-    
-    # Vorbis tags (FLAC, OGG)
-    'title': 'title',
-    'album': 'album',
-    'artist': 'artist',
-    'albumartist': 'albumartist',
-    'composer': 'composer',
-    'tracknumber': 'tracknumber',
-    'discnumber': 'discnumber',
-    'date': 'date',
-    'genre': 'genre',
-    'publisher': 'publisher',
-    'copyright': 'copyright',
-    'comment': 'comment',
-    
-    # MP4 (M4A, AAC) tags
-    '©nam': 'title',
-    '©alb': 'album',
-    '©ART': 'artist',
-    'aART': 'albumartist',
-    '©wrt': 'composer',
-    'trkn': 'tracknumber',
-    'disk': 'discnumber',
-    '©day': 'date',
-    '©gen': 'genre',
-    '©pub': 'publisher',
-    'cprt': 'copyright',
-    '©cmt': 'comment',
-    
-    # Additional tags some files might have
-    'album_artist': 'albumartist',
-    'track': 'tracknumber',
-    'track_number': 'tracknumber',
-    'disc': 'discnumber',
-    'disc_number': 'discnumber',
-    'year': 'date',
-    'albuminterpret': 'albumartist',  # German tag name
-    'interpret': 'artist',            # German tag name
-}
-
-# Define replacements for special tag values
-TAG_VALUE_REPLACEMENTS = {
-    "Die drei ???": "Die drei Fragezeichen",
-    "Die Drei ???": "Die drei Fragezeichen",
-    "DIE DREI ???": "Die drei Fragezeichen",
-    "Die drei !!!": "Die drei Ausrufezeichen",
-    "Die Drei !!!": "Die drei Ausrufezeichen",
-    "DIE DREI !!!": "Die drei Ausrufezeichen",
-    "TKKG™": "TKKG",
-    "Die drei ??? Kids": "Die drei Fragezeichen Kids",
-    "Die Drei ??? Kids": "Die drei Fragezeichen Kids",
-    "Bibi & Tina": "Bibi und Tina",
-    "Benjamin Blümchen™": "Benjamin Blümchen",
-    "???": "Fragezeichen",
-    "!!!": "Ausrufezeichen",
-}
 
 def normalize_tag_value(value: str) -> str:
     """
@@ -146,7 +73,6 @@ def normalize_tag_value(value: str) -> str:
     if not value:
         return value
         
-    # Check for direct replacements first
     if value in TAG_VALUE_REPLACEMENTS:
         logger.debug("Direct tag replacement: '%s' -> '%s'", value, TAG_VALUE_REPLACEMENTS[value])
         return TAG_VALUE_REPLACEMENTS[value]
@@ -158,10 +84,7 @@ def normalize_tag_value(value: str) -> str:
             original = result
             result = result.replace(pattern, replacement)
             logger.debug("Partial tag replacement: '%s' -> '%s'", original, result)
-    
-    # Special case for "Die drei ???" type patterns that might have been missed
-    result = result.replace("???", "Fragezeichen")
-    
+        
     return result
 
 def is_available() -> bool:
@@ -213,60 +136,61 @@ def get_file_tags(file_path: str) -> Dict[str, Any]:
                 id3 = audio if isinstance(audio, ID3) else audio.ID3
                 for tag_key, tag_value in id3.items():
                     tag_name = tag_key.split(':')[0]  # Handle ID3 tags with colons
-                    if tag_name in TAG_MAPPING:
+                    if tag_name in TAG_MAPPINGS:
                         tag_value_str = str(tag_value)
-                        tags[TAG_MAPPING[tag_name]] = normalize_tag_value(tag_value_str)
+                        tags[TAG_MAPPINGS[tag_name]] = normalize_tag_value(tag_value_str)
             except (AttributeError, TypeError) as e:
                 logger.debug("Error accessing ID3 tags: %s", e)
                 # Try alternative approach for ID3 tags
                 try:
                     if hasattr(audio, 'tags') and audio.tags:
                         for tag_key in audio.tags.keys():
-                            if tag_key in TAG_MAPPING:
+                            if tag_key in TAG_MAPPINGS:
                                 tag_value = audio.tags[tag_key]
                                 if hasattr(tag_value, 'text'):
                                     tag_value_str = str(tag_value.text[0]) if tag_value.text else ''
                                 else:
                                     tag_value_str = str(tag_value)
-                                tags[TAG_MAPPING[tag_key]] = normalize_tag_value(tag_value_str)
+                                tags[TAG_MAPPINGS[tag_key]] = normalize_tag_value(tag_value_str)
                 except Exception as e:
                     logger.debug("Alternative ID3 tag reading failed: %s", e)
         elif isinstance(audio, (FLAC, OggOpus, OggVorbis)):
             # FLAC and OGG files
             for tag_key, tag_values in audio.items():
                 tag_key_lower = tag_key.lower()
-                if tag_key_lower in TAG_MAPPING:
+                if tag_key_lower in TAG_MAPPINGS:
                     # Some tags might have multiple values, we'll take the first one
                     tag_value = tag_values[0] if tag_values else ''
-                    tags[TAG_MAPPING[tag_key_lower]] = normalize_tag_value(tag_value)
+                    tags[TAG_MAPPINGS[tag_key_lower]] = normalize_tag_value(tag_value)
         elif isinstance(audio, MP4):
             # MP4 files
             for tag_key, tag_value in audio.items():
-                if tag_key in TAG_MAPPING:
+                if tag_key in TAG_MAPPINGS:
                     if isinstance(tag_value, list):
                         if tag_key in ('trkn', 'disk'):
                             # Handle track and disc number tuples
                             if tag_value and isinstance(tag_value[0], tuple) and len(tag_value[0]) >= 1:
-                                tags[TAG_MAPPING[tag_key]] = str(tag_value[0][0])
+                                tags[TAG_MAPPINGS[tag_key]] = str(tag_value[0][0])
                         else:
                             tag_value_str = str(tag_value[0]) if tag_value else ''
-                            tags[TAG_MAPPING[tag_key]] = normalize_tag_value(tag_value_str)
+                            tags[TAG_MAPPINGS[tag_key]] = normalize_tag_value(tag_value_str)
                     else:
                         tag_value_str = str(tag_value)
-                        tags[TAG_MAPPING[tag_key]] = normalize_tag_value(tag_value_str)
+                        tags[TAG_MAPPINGS[tag_key]] = normalize_tag_value(tag_value_str)
         else:
             # Generic audio file - try to read any available tags
             for tag_key, tag_value in audio.items():
                 tag_key_lower = tag_key.lower()
-                if tag_key_lower in TAG_MAPPING:
+                if tag_key_lower in TAG_MAPPINGS:
                     if isinstance(tag_value, list):
                         tag_value_str = str(tag_value[0]) if tag_value else ''
-                        tags[TAG_MAPPING[tag_key_lower]] = normalize_tag_value(tag_value_str)
+                        tags[TAG_MAPPINGS[tag_key_lower]] = normalize_tag_value(tag_value_str)
                     else:
                         tag_value_str = str(tag_value)
-                        tags[TAG_MAPPING[tag_key_lower]] = normalize_tag_value(tag_value_str)
+                        tags[TAG_MAPPINGS[tag_key_lower]] = normalize_tag_value(tag_value_str)
                         
         logger.debug("Successfully read %d tags from file", len(tags))
+        logger.debug("Tags: %s", str(tags))
         return tags
     except Exception as e:
         logger.error("Error reading tags from file %s: %s", file_path, str(e))
@@ -330,12 +254,12 @@ def extract_album_info(folder_path: str) -> Dict[str, str]:
     if not all_tags:
         logger.debug("Could not read tags from any files in folder")
         return {}
-    
-    # Try to find consistent album information
     result = {}
-    key_tags = ['album', 'albumartist', 'artist', 'date', 'genre']
+    all_tag_names = set()
+    for tags in all_tags:
+        all_tag_names.update(tags.keys())
     
-    for tag_name in key_tags:
+    for tag_name in all_tag_names:
         # Count occurrences of each value
         value_counts = {}
         for tags in all_tags:
@@ -614,13 +538,10 @@ def find_cover_image(source_dir):
         return None
         
     # Common cover image file names
-    cover_names = [
-        'cover', 'folder', 'album', 'front', 'artwork', 'image', 
-        'albumart', 'albumartwork', 'booklet'
-    ]
+    cover_names = ARTWORK_NAMES
     
     # Common image extensions
-    image_extensions = ['.jpg', '.jpeg', '.png', '.bmp', '.gif']
+    image_extensions = ARTWORK_EXTENSIONS
     
     # Try different variations
     for name in cover_names:

TonieToolbox/ogg_page.py

@@ -18,12 +18,12 @@ from .logger import get_logger
 logger = get_logger('ogg_page')
 
 
-def create_crc_table():
+def create_crc_table() -> list[int]:
     """
     Create a CRC lookup table for OGG page checksums.
     
     Returns:
-        list: CRC32 lookup table for OGG pages
+        list[int]: CRC32 lookup table for OGG pages
     """
     logger.debug("Creating CRC table for OGG page checksums")
     table = []
@@ -39,12 +39,12 @@ def create_crc_table():
 CRC_TABLE = create_crc_table()
 
 
-def crc32(bytestream):
+def crc32(bytestream: bytes) -> int:
     """
     Calculate a CRC32 checksum for the given bytestream.
     
     Args:
-        bytestream: Bytes to calculate the CRC for
+        bytestream (bytes): Bytes to calculate the CRC for
         
     Returns:
         int: CRC32 checksum
@@ -64,7 +64,7 @@ class OggPage:
     with particular focus on features needed for Tonie compatibility.
     """
     
-    def __init__(self, filehandle):
+    def __init__(self, filehandle) -> None:
         """
         Initialize a new OggPage.
         
@@ -88,7 +88,7 @@ class OggPage:
         self.parse_header(filehandle)
         self.parse_segments(filehandle)
 
-    def parse_header(self, filehandle):
+    def parse_header(self, filehandle) -> None:
         """
         Parse the OGG page header.
         
@@ -108,7 +108,7 @@ class OggPage:
         logger.trace("Parsed OGG header - Page #%d, Type: %d, Granule: %d, Serial: %d, Segments: %d",
                    self.page_no, self.page_type, self.granule_position, self.serial_no, self.segment_count)
 
-    def parse_segments(self, filehandle):
+    def parse_segments(self, filehandle) -> None:
         """
         Parse the segments in this OGG page.
         
@@ -133,12 +133,12 @@ class OggPage:
             logger.error("Found an opus packet spanning OGG pages, which is not supported")
             raise RuntimeError("Found an opus packet spanning ogg pages. This is not supported yet.")
 
-    def correct_values(self, last_granule):
+    def correct_values(self, last_granule: int) -> None:
         """
         Correct the granule position and checksum for this page.
         
         Args:
-            last_granule: Last granule position
+            last_granule (int): Last granule position
             
         Raises:
             RuntimeError: If there are too many segments in the page
@@ -160,7 +160,7 @@ class OggPage:
         logger.trace("Corrected OGG page values: Page #%d, Segments: %d, Granule: %d", 
                    self.page_no, self.segment_count, self.granule_position)
 
-    def calc_checksum(self):
+    def calc_checksum(self) -> int:
         """
         Calculate the checksum for this page.
         
@@ -178,7 +178,7 @@ class OggPage:
         logger.trace("Calculated checksum for page #%d: 0x%X", self.page_no, checksum)
         return checksum
 
-    def get_page_size(self):
+    def get_page_size(self) -> int:
         """
         Get the total size of this page in bytes.
         
@@ -190,7 +190,7 @@ class OggPage:
             size = size + len(segment.data)
         return size
 
-    def get_size_of_first_opus_packet(self):
+    def get_size_of_first_opus_packet(self) -> int:
         """
         Get the size of the first opus packet in bytes.
         
@@ -208,7 +208,7 @@ class OggPage:
             i = i + 1
         return size
 
-    def get_segment_count_of_first_opus_packet(self):
+    def get_segment_count_of_first_opus_packet(self) -> int:
         """
         Get the number of segments in the first opus packet.
         
@@ -224,14 +224,14 @@ class OggPage:
             count = count + 1
         return count
 
-    def insert_empty_segment(self, index_after, spanning_packet=False, first_packet=False):
+    def insert_empty_segment(self, index_after: int, spanning_packet: bool = False, first_packet: bool = False) -> None:
         """
         Insert an empty segment after the specified index.
         
         Args:
-            index_after: Index to insert the segment after
-            spanning_packet: Whether this segment belongs to a packet that spans pages
-            first_packet: Whether this is the first segment of a packet
+            index_after (int): Index to insert the segment after
+            spanning_packet (bool): Whether this segment belongs to a packet that spans pages
+            first_packet (bool): Whether this is the first segment of a packet
         """
         logger.trace("Inserting empty segment after index %d (spanning: %s, first: %s)",
                    index_after, spanning_packet, first_packet)
@@ -242,12 +242,12 @@ class OggPage:
         segment.data = bytes()
         self.segments.insert(index_after + 1, segment)
 
-    def get_opus_packet_size(self, seg_start):
+    def get_opus_packet_size(self, seg_start: int) -> int:
         """
         Get the size of the opus packet starting at the specified segment index.
         
         Args:
-            seg_start: Starting segment index
+            seg_start (int): Starting segment index
             
         Returns:
             int: Size of the opus packet in bytes
@@ -259,12 +259,12 @@ class OggPage:
             seg_start = seg_start + 1
         return size
 
-    def get_segment_count_of_packet_at(self, seg_start):
+    def get_segment_count_of_packet_at(self, seg_start: int) -> int:
         """
         Get the number of segments in the packet starting at the specified segment index.
         
         Args:
-            seg_start: Starting segment index
+            seg_start (int): Starting segment index
             
         Returns:
             int: Number of segments
@@ -274,13 +274,13 @@ class OggPage:
             seg_end = seg_end + 1
         return seg_end - seg_start
 
-    def redistribute_packet_data_at(self, seg_start, pad_count):
+    def redistribute_packet_data_at(self, seg_start: int, pad_count: int) -> None:
         """
         Redistribute packet data starting at the specified segment index.
         
         Args:
-            seg_start: Starting segment index
-            pad_count: Number of padding bytes to add
+            seg_start (int): Starting segment index
+            pad_count (int): Number of padding bytes to add
         """
         logger.trace("Redistributing packet data at segment %d with %d padding bytes", 
                    seg_start, pad_count)
@@ -316,14 +316,14 @@ class OggPage:
         logger.trace("Redistribution complete, %d segments used", seg_count)
         assert len(full_data) == 0
 
-    def convert_packet_to_framepacking_three_and_pad(self, seg_start, pad=False, count=0):
+    def convert_packet_to_framepacking_three_and_pad(self, seg_start: int, pad: bool = False, count: int = 0) -> None:
         """
         Convert the packet to framepacking three mode and add padding if required.
         
         Args:
-            seg_start: Starting segment index
-            pad: Whether to add padding
-            count: Number of padding bytes to add
+            seg_start (int): Starting segment index
+            pad (bool): Whether to add padding
+            count (int): Number of padding bytes to add
             
         Raises:
             AssertionError: If the segment is not the first packet
@@ -336,13 +336,13 @@ class OggPage:
             self.segments[seg_start].set_pad_count(count)
         self.redistribute_packet_data_at(seg_start, count)
 
-    def calc_actual_padding_value(self, seg_start, bytes_needed):
+    def calc_actual_padding_value(self, seg_start: int, bytes_needed: int) -> int:
         """
         Calculate the actual padding value needed for the packet.
         
         Args:
-            seg_start: Starting segment index
-            bytes_needed: Number of bytes needed for padding
+            seg_start (int): Starting segment index
+            bytes_needed (int): Number of bytes needed for padding
             
         Returns:
             int: Actual padding value or a special return code
@@ -426,13 +426,13 @@ class OggPage:
             logger.trace("Calculated actual padding value: %d", result)
             return result
 
-    def pad(self, pad_to, idx_offset=-1):
+    def pad(self, pad_to: int, idx_offset: int = -1) -> None:
         """
         Pad the page to the specified size.
         
         Args:
-            pad_to: Target size to pad to
-            idx_offset: Index offset to start from, defaults to last segment
+            pad_to (int): Target size to pad to
+            idx_offset (int): Index offset to start from, defaults to last segment
             
         Raises:
             RuntimeError: If beginning of last packet cannot be found
@@ -490,7 +490,7 @@ class OggPage:
                        final_size, pad_to)
         assert final_size == pad_to
 
-    def pad_one_byte(self):
+    def pad_one_byte(self) -> None:
         """
         Add one byte of padding to the page.
         
@@ -515,7 +515,7 @@ class OggPage:
             logger.trace("Converting packet to framepacking 3")
             self.convert_packet_to_framepacking_three_and_pad(i)
 
-    def write_page(self, filehandle, sha1=None):
+    def write_page(self, filehandle, sha1=None) -> None:
         """
         Write the page to a file handle.
         
@@ -537,12 +537,12 @@ class OggPage:
             segment.write(filehandle)
 
     @staticmethod
-    def from_page(other_page):
+    def from_page(other_page: 'OggPage') -> 'OggPage':
         """
         Create a new OggPage based on another page.
         
         Args:
-            other_page: Source page to copy from
+            other_page (OggPage): Source page to copy from
             
         Returns:
             OggPage: New page with copied properties
@@ -560,7 +560,7 @@ class OggPage:
         return new_page
 
     @staticmethod
-    def seek_to_page_header(filehandle):
+    def seek_to_page_header(filehandle) -> bool:
         """
         Seek to the next OGG page header in a file.
         

TonieToolbox/opus_packet.py

@@ -18,15 +18,15 @@ class OpusPacket:
     with particular focus on features needed for Tonie compatibility.
     """
     
-    def __init__(self, filehandle, size=-1, last_size=-1, dont_parse_info=False):
+    def __init__(self, filehandle, size: int = -1, last_size: int = -1, dont_parse_info: bool = False) -> None:
         """
         Initialize a new OpusPacket.
         
         Args:
             filehandle: File handle to read the packet data from, or None to create an empty packet
-            size: Size of the packet in bytes
-            last_size: Size of the previous packet in bytes
-            dont_parse_info: If True, don't parse the packet information even if this is a first packet
+            size (int): Size of the packet in bytes
+            last_size (int): Size of the previous packet in bytes
+            dont_parse_info (bool): If True, don't parse the packet information even if this is a first packet
         """
         self.config_value = None
         self.stereo = None
@@ -51,7 +51,7 @@ class OpusPacket:
         if self.first_packet and not dont_parse_info:
             self.parse_segment_info()
 
-    def get_frame_count(self):
+    def get_frame_count(self) -> int:
         """
         Get the number of frames in this packet based on its framepacking.
         
@@ -68,7 +68,7 @@ class OpusPacket:
             unpacked = struct.unpack("<B", self.data[1:2])
             return unpacked[0] & 63
 
-    def get_padding(self):
+    def get_padding(self) -> int:
         """
         Get the padding count for this packet.
         
@@ -94,7 +94,7 @@ class OpusPacket:
         logger.trace("Packet has %d bytes of padding", total_padding)
         return total_padding
 
-    def get_frame_size(self):
+    def get_frame_size(self) -> float:
         """
         Get the frame size in milliseconds based on the config value.
         
@@ -121,7 +121,7 @@ class OpusPacket:
             logger.error(error_msg)
             raise RuntimeError(error_msg)
 
-    def calc_granule(self):
+    def calc_granule(self) -> float:
         """
         Calculate the granule position for this packet.
         
@@ -133,7 +133,7 @@ class OpusPacket:
                    granule, self.frame_size, self.frame_count)
         return granule
 
-    def parse_segment_info(self):
+    def parse_segment_info(self) -> None:
         """Parse the segment information from the packet data."""
         logger.trace("Parsing segment info from packet data")
         byte = struct.unpack("<B", self.data[0:1])[0]
@@ -148,7 +148,7 @@ class OpusPacket:
         logger.trace("Packet info: config=%d, stereo=%d, framepacking=%d, frame_count=%d, frame_size=%f",
                    self.config_value, self.stereo, self.framepacking, self.frame_count, self.frame_size)
 
-    def write(self, filehandle):
+    def write(self, filehandle) -> None:
         """
         Write the packet data to a file.
         
@@ -159,7 +159,7 @@ class OpusPacket:
             logger.trace("Writing %d bytes of packet data to file", len(self.data))
             filehandle.write(self.data)
 
-    def convert_to_framepacking_three(self):
+    def convert_to_framepacking_three(self) -> None:
         """
         Convert the packet to use framepacking mode 3.
         
@@ -182,12 +182,12 @@ class OpusPacket:
         self.framepacking = 3
         logger.debug("Packet successfully converted to framepacking mode 3")
 
-    def set_pad_count(self, count):
+    def set_pad_count(self, count: int) -> None:
         """
         Set the padding count for this packet.
         
         Args:
-            count: Number of padding bytes to add
+            count (int): Number of padding bytes to add
             
         Raises:
             AssertionError: If the packet is not using framepacking mode 3 or is already padded