TonieToolbox 0.2.1__py3-none-any.whl → 0.2.3__py3-none-any.whl

TonieToolbox/tonie_analysis.py

@@ -72,7 +72,8 @@ def get_header_info(in_file):
         
     Returns:
         tuple: Header size, Tonie header object, file size, audio size, SHA1 sum,
-               Opus header found flag, Opus version, channel count, sample rate, bitstream serial number
+               Opus header found flag, Opus version, channel count, sample rate, bitstream serial number,
+               Opus comments dictionary
                
     Raises:
         RuntimeError: If OGG pages cannot be found
@@ -112,17 +113,64 @@ def get_header_info(in_file):
     logger.debug("Opus header found: %s, Version: %d, Channels: %d, Sample rate: %d Hz, Serial: %d", 
                 opus_head_found, opus_version, channel_count, sample_rate, bitstream_serial_no)
 
+    # Read and parse Opus comments from the second page
+    opus_comments = {}
     found = OggPage.seek_to_page_header(in_file)
     if not found:
         logger.error("Second OGG page not found")
         raise RuntimeError("Second ogg page not found")
     
-    OggPage(in_file)
+    second_page = OggPage(in_file)
     logger.debug("Read second OGG page")
+    
+    try:
+        # Combine all segments data for the second page
+        comment_data = bytearray()
+        for segment in second_page.segments:
+            comment_data.extend(segment.data)
+        
+        if comment_data.startswith(b"OpusTags"):
+            pos = 8  # Skip "OpusTags"
+            # Extract vendor string
+            if pos + 4 <= len(comment_data):
+                vendor_length = struct.unpack("<I", comment_data[pos:pos+4])[0]
+                pos += 4
+                if pos + vendor_length <= len(comment_data):
+                    vendor = comment_data[pos:pos+vendor_length].decode('utf-8', errors='replace')
+                    opus_comments["vendor"] = vendor
+                    pos += vendor_length
+                    
+                    # Extract comments count
+                    if pos + 4 <= len(comment_data):
+                        comments_count = struct.unpack("<I", comment_data[pos:pos+4])[0]
+                        pos += 4
+                        
+                        # Extract individual comments
+                        for i in range(comments_count):
+                            if pos + 4 <= len(comment_data):
+                                comment_length = struct.unpack("<I", comment_data[pos:pos+4])[0]
+                                pos += 4
+                                if pos + comment_length <= len(comment_data):
+                                    comment = comment_data[pos:pos+comment_length].decode('utf-8', errors='replace')
+                                    pos += comment_length
+                                    
+                                    # Split comment into key/value if possible
+                                    if "=" in comment:
+                                        key, value = comment.split("=", 1)
+                                        opus_comments[key] = value
+                                    else:
+                                        opus_comments[f"comment_{i}"] = comment
+                                else:
+                                    break
+                            else:
+                                break
+    except Exception as e:
+        logger.error("Failed to parse Opus comments: %s", str(e))
 
     return (
         header_size, tonie_header, file_size, audio_size, sha1sum,
-        opus_head_found, opus_version, channel_count, sample_rate, bitstream_serial_no
+        opus_head_found, opus_version, channel_count, sample_rate, bitstream_serial_no,
+        opus_comments
     )
 
 
@@ -204,7 +252,7 @@ def check_tonie_file(filename):
     
     with open(filename, "rb") as in_file:
         header_size, tonie_header, file_size, audio_size, sha1, opus_head_found, \
-        opus_version, channel_count, sample_rate, bitstream_serial_no = get_header_info(in_file)
+        opus_version, channel_count, sample_rate, bitstream_serial_no, opus_comments = get_header_info(in_file)
 
         page_count, alignment_okay, page_size_okay, total_time, \
         chapters = get_audio_info(in_file, sample_rate, tonie_header, header_size)
@@ -254,6 +302,20 @@ def check_tonie_file(filename):
     print("")
     print("[{}] File is {}valid".format("OK" if all_ok else "NOT OK", "" if all_ok else "NOT "))
     print("")
+    
+    # Display Opus comments if available
+    if opus_comments:
+        print("[ii] Opus Comments:")
+        if "vendor" in opus_comments:
+            print("  Vendor: {}".format(opus_comments["vendor"]))
+            # Remove vendor from dict to avoid showing it twice
+            vendor = opus_comments.pop("vendor")
+            
+        # Sort remaining comments for consistent display
+        for key in sorted(opus_comments.keys()):
+            print("  {}: {}".format(key, opus_comments[key]))
+        print("")
+        
     print("[ii] Total runtime: {}".format(granule_to_time_string(total_time)))
     print("[ii] {} Tracks:".format(len(chapters)))
     for i in range(0, len(chapters)):

TonieToolbox/tonie_file.py

@@ -19,6 +19,33 @@ from .logger import get_logger
 logger = get_logger('tonie_file')
 
 
+def toniefile_comment_add(buffer, length, comment_str):
+    """
+    Add a comment string to an Opus comment packet buffer.
+    
+    Args:
+        buffer: Bytearray buffer to add comment to
+        length: Current position in the buffer
+        comment_str: Comment string to add
+        
+    Returns:
+        int: New position in the buffer after adding comment
+    """
+    logger.debug("Adding comment: %s", comment_str)
+    
+    # Add 4-byte length prefix
+    str_length = len(comment_str)
+    buffer[length:length+4] = struct.pack("<I", str_length)
+    length += 4
+    
+    # Add the actual string
+    buffer[length:length+str_length] = comment_str.encode('utf-8')
+    length += str_length
+    
+    logger.trace("Added comment of length %d, new buffer position: %d", str_length, length)
+    return length
+
+
 def check_identification_header(page):
     """
     Check if a page contains a valid Opus identification header.
@@ -52,37 +79,103 @@ def check_identification_header(page):
     logger.debug("Opus identification header is valid")
 
 
-def prepare_opus_tags(page):
+def prepare_opus_tags(page, custom_tags=False, bitrate=64, vbr=True, opus_binary=None):
     """
     Prepare standard Opus tags for a Tonie file.
     
     Args:
         page: OggPage to modify
+        custom_tags: Whether to use custom TonieToolbox tags instead of default ones
+        bitrate: Actual bitrate used for encoding
+        vbr: Whether variable bitrate was used
+        opus_binary: Path to opusenc binary for version detection
         
     Returns:
         OggPage: Modified page with Tonie-compatible Opus tags
     """
     logger.debug("Preparing Opus tags for Tonie compatibility")
     page.segments.clear()
-    segment = OpusPacket(None)
-    segment.size = len(OPUS_TAGS[0])
-    segment.data = bytearray(OPUS_TAGS[0])
-    segment.spanning_packet = True
-    segment.first_packet = True
-    page.segments.append(segment)
-
-    segment = OpusPacket(None)
-    segment.size = len(OPUS_TAGS[1])
-    segment.data = bytearray(OPUS_TAGS[1])
-    segment.spanning_packet = False
-    segment.first_packet = False
-    page.segments.append(segment)
+    
+    if not custom_tags:
+        # Use the default hardcoded tags for backward compatibility
+        segment = OpusPacket(None)
+        segment.size = len(OPUS_TAGS[0])
+        segment.data = bytearray(OPUS_TAGS[0])
+        segment.spanning_packet = True
+        segment.first_packet = True
+        page.segments.append(segment)
+
+        segment = OpusPacket(None)
+        segment.size = len(OPUS_TAGS[1])
+        segment.data = bytearray(OPUS_TAGS[1])
+        segment.spanning_packet = False
+        segment.first_packet = False
+        page.segments.append(segment)
+    else:
+        # Use custom tags for TonieToolbox
+        # Create buffer for opus tags (similar to teddyCloud implementation)
+        logger.debug("Creating custom Opus tags")
+        comment_data = bytearray(0x1B4)  # Same size as in teddyCloud
+        
+        # OpusTags signature
+        comment_data_pos = 0
+        comment_data[comment_data_pos:comment_data_pos+8] = b"OpusTags"
+        comment_data_pos += 8
+        
+        # Vendor string
+        comment_data_pos = toniefile_comment_add(comment_data, comment_data_pos, "TonieToolbox")
+        
+        # Number of comments (3 comments: version, encoder info, and encoder options)
+        comments_count = 3
+        comment_data[comment_data_pos:comment_data_pos+4] = struct.pack("<I", comments_count)
+        comment_data_pos += 4
+        
+        # Add version information
+        from . import __version__
+        version_str = f"version={__version__}"
+        comment_data_pos = toniefile_comment_add(comment_data, comment_data_pos, version_str)
+        
+        # Get actual opusenc version
+        from .dependency_manager import get_opus_version
+        encoder_info = get_opus_version(opus_binary)
+        comment_data_pos = toniefile_comment_add(comment_data, comment_data_pos, f"encoder={encoder_info}")
+        
+        # Create encoder options string with actual settings
+        vbr_opt = "--vbr" if vbr else "--cbr"
+        encoder_options = f"encoder_options=--bitrate {bitrate} {vbr_opt}"
+        comment_data_pos = toniefile_comment_add(comment_data, comment_data_pos, encoder_options)
+        
+        # Add padding
+        remain = len(comment_data) - comment_data_pos - 4
+        comment_data[comment_data_pos:comment_data_pos+4] = struct.pack("<I", remain)
+        comment_data_pos += 4
+        comment_data[comment_data_pos:comment_data_pos+4] = b"pad="
+        
+        # Create segments - handle data in chunks of 255 bytes maximum
+        comment_data = comment_data[:comment_data_pos + remain]  # Trim to actual used size
+        
+        # Split large data into smaller segments (each <= 255 bytes)
+        remaining_data = comment_data
+        first_segment = True
+        
+        while remaining_data:
+            chunk_size = min(255, len(remaining_data))
+            segment = OpusPacket(None)
+            segment.size = chunk_size
+            segment.data = remaining_data[:chunk_size]
+            segment.spanning_packet = len(remaining_data) > chunk_size  # More data follows
+            segment.first_packet = first_segment
+            page.segments.append(segment)
+            
+            remaining_data = remaining_data[chunk_size:]
+            first_segment = False
+        
     page.correct_values(0)
     logger.trace("Opus tags prepared with %d segments", len(page.segments))
     return page
 
 
-def copy_first_and_second_page(in_file, out_file, timestamp, sha):
+def copy_first_and_second_page(in_file, out_file, timestamp, sha, use_custom_tags=True, bitrate=64, vbr=True, opus_binary=None):
     """
     Copy and modify the first two pages of an Opus file for a Tonie file.
     
@@ -91,9 +184,10 @@ def copy_first_and_second_page(in_file, out_file, timestamp, sha):
         out_file: Output file handle
         timestamp: Timestamp to use for the Tonie file
         sha: SHA1 hash object to update with written data
-        
-    Raises:
-        RuntimeError: If OGG pages cannot be found
+        use_custom_tags: Whether to use custom TonieToolbox tags
+        bitrate: Actual bitrate used for encoding
+        vbr: Whether VBR was used
+        opus_binary: Path to opusenc binary
     """
     logger.debug("Copying first and second pages with timestamp %d", timestamp)
     found = OggPage.seek_to_page_header(in_file)
@@ -116,7 +210,7 @@ def copy_first_and_second_page(in_file, out_file, timestamp, sha):
     page = OggPage(in_file)
     page.serial_no = timestamp
     page.checksum = page.calc_checksum()
-    page = prepare_opus_tags(page)
+    page = prepare_opus_tags(page, use_custom_tags, bitrate, vbr, opus_binary)
     page.write_page(out_file, sha)
     logger.debug("Second page written successfully")
 
@@ -277,7 +371,8 @@ def fix_tonie_header(out_file, chapters, timestamp, sha):
 
 
 def create_tonie_file(output_file, input_files, no_tonie_header=False, user_timestamp=None,
-                     bitrate=96, vbr=True, ffmpeg_binary=None, opus_binary=None, keep_temp=False, auto_download=False):
+                     bitrate=96, vbr=True, ffmpeg_binary=None, opus_binary=None, keep_temp=False, auto_download=False, 
+                     use_custom_tags=True):
     """
     Create a Tonie file from input files.
     
@@ -292,6 +387,7 @@ def create_tonie_file(output_file, input_files, no_tonie_header=False, user_time
         opus_binary: Path to opusenc binary
         keep_temp: Whether to keep temporary opus files for testing
         auto_download: Whether to automatically download dependencies if not found
+        use_custom_tags: Whether to use dynamic comment tags generated with toniefile_comment_add
     """
     from .audio_conversion import get_opus_tempfile
     
@@ -369,7 +465,7 @@ def create_tonie_file(output_file, input_files, no_tonie_header=False, user_time
             try:
                 if next_page_no == 2:
                     logger.debug("Processing first file: copying first and second page")
-                    copy_first_and_second_page(handle, out_file, timestamp, sha1)
+                    copy_first_and_second_page(handle, out_file, timestamp, sha1, use_custom_tags, bitrate, vbr, opus_binary)
                 else:
                     logger.debug("Processing subsequent file: skipping first and second page")
                     other_size = max_size

{tonietoolbox-0.2.1.dist-info → tonietoolbox-0.2.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TonieToolbox
-Version: 0.2.1
+Version: 0.2.3
 Summary: Convert audio files to Tonie box compatible format
 Home-page: https://github.com/Quentendo64/TonieToolbox
 Author: Quentendo64
@@ -46,6 +46,7 @@ A Python tool for converting audio files to Tonie box compatible format (TAF - T
   - [Basic Usage](#basic-usage)
   - [Advanced Options](#advanced-options)
   - [Common Usage Examples](#common-usage-examples)
+  - [Media Tags](#media-tags)
 - [Technical Details](#technical-details)
   - [TAF File Structure](#taf-tonie-audio-format-file-structure)
   - [File Analysis](#file-analysis)
@@ -67,15 +68,17 @@ The tool provides several capabilities:
 - Split Tonie files into individual opus tracks
 - Compare two TAF files for debugging differences
 - Support various input formats through FFmpeg conversion
+- Extract and use audio media tags (ID3, Vorbis Comments, etc.) for better file naming
 
 ## Requirements
 
 - Python 3.6 or higher
-- FFmpeg (for converting non-opus audio files).
+- FFmpeg (for converting non-opus audio files)
 - opus-tools (specifically `opusenc` for encoding to opus format)
+- mutagen (for reading audio file metadata, auto-installed when needed)
 
 Make sure FFmpeg and opus-tools are installed on your system and accessible in your PATH.
-If the requirements are not found in PATH. TonieToolbox will download the missing requirements.
+If the requirements are not found in PATH. TonieToolbox will download the missing requirements with --auto-download.
 
 ## Installation
 
@@ -166,7 +169,8 @@ Output:
 ```
 usage: TonieToolbox.py [-h] [-v] [-t TIMESTAMP] [-f FFMPEG] [-o OPUSENC] 
                     [-b BITRATE] [-c] [-a TAG] [-n] [-i] [-s] [-r] [-O]
-                    [-A] [-k] [-C FILE2] [-D] [-d] [-T] [-q] [-Q]
+                    [-A] [-k] [-C FILE2] [-D] [-m] [--name-template TEMPLATE]
+                    [--show-tags] [-d] [-T] [-q] [-Q]
                     SOURCE [TARGET]
 
 Create Tonie compatible file from Ogg opus file(s).
@@ -198,6 +202,12 @@ optional arguments:
   -D, --detailed-compare
                         Show detailed OGG page differences when comparing files
 
+Media Tag Options:
+  -m, --use-media-tags  Use media tags from audio files for naming
+  --name-template TEMPLATE
+                        Template for naming files using media tags. Example: "{album} - {artist}"
+  --show-tags           Show available media tags from input files
+
 Version Check Options:
   -S, --skip-update-check
                         Skip checking for updates
@@ -269,6 +279,52 @@ Process a music collection with nested album folders and save TAF files alongsid
 tonietoolbox --recursive --output-to-source "\Hörspiele\"
 ```
 
+### Media Tags
+
+TonieToolbox can read metadata tags from audio files (such as ID3 tags in MP3 files, Vorbis comments in FLAC/OGG files, etc.) and use them to create more meaningful filenames or display information about your audio collection.
+
+#### View available tags in audio files:
+
+To see what tags are available in your audio files:
+
+```
+tonietoolbox --show-tags input.mp3
+```
+
+This will display all readable tags from the file, which can be useful for creating naming templates.
+
+#### Use media tags for file naming:
+
+To use the metadata from audio files when generating output filenames:
+
+```
+tonietoolbox input.mp3 --use-media-tags
+```
+
+For single files, this will use a default template of "{title} - {artist}" for the output filename.
+
+#### Custom naming templates:
+
+You can specify custom templates for generating filenames based on the audio metadata:
+
+```
+tonietoolbox input.mp3 --use-media-tags --name-template "{artist} - {album} - {title}"
+```
+
+#### Recursive processing with media tags:
+
+When processing folders recursively, media tags can provide more consistent naming:
+
+```
+tonietoolbox --recursive --use-media-tags "Music/Collection/"
+```
+
+This will attempt to use the album information from the audio files for naming the output files:
+
+```
+tonietoolbox --recursive --use-media-tags --name-template "{date} - {album} ({artist})" "Music/Collection/"
+```
+
 ## Technical Details
 
 ### TAF (Tonie Audio Format) File Structure

tonietoolbox-0.2.3.dist-info/RECORD

@@ -0,0 +1,22 @@
+TonieToolbox/__init__.py,sha256=mRuWBCYSLc6tAHyVDd70qM5LHgWH7R8ClFbFfILlEso,96
+TonieToolbox/__main__.py,sha256=Otltlkl9Cd36BYs5_23ufCkdxguFFVzuVDwSvWDSPfI,17078
+TonieToolbox/audio_conversion.py,sha256=ra72qsE8j2GEP_4kqDT9m6aKlnnREZhZAlpf7y83pA0,11202
+TonieToolbox/constants.py,sha256=QQWQpnCI65GByLlXLOkt2n8nALLu4m6BWp0zuhI3M04,2021
+TonieToolbox/dependency_manager.py,sha256=dRy8JxV3Dv1x8uWIXMonU0ArnCRknI1rkrj8MkJcyl4,27916
+TonieToolbox/filename_generator.py,sha256=RqQHyGTKakuWR01yMSnFVMU_HfLw3rqFxKhXNIHdTlg,3441
+TonieToolbox/logger.py,sha256=Up9fBVkOZwkY61_645bX4tienCpyVSkap-FeTV0v730,1441
+TonieToolbox/media_tags.py,sha256=T8osaU101iGC43NaMbbHD8mwNh-dGa_uPj7IPlhMIno,16091
+TonieToolbox/ogg_page.py,sha256=-ViaIRBgh5ayfwmyplL8QmmRr5P36X8W0DdHkSFUYUU,21948
+TonieToolbox/opus_packet.py,sha256=OcHXEe3I_K4mWPUD55prpG42sZxJsEeAxqSbFxBmb0c,7895
+TonieToolbox/recursive_processor.py,sha256=m70-oJ4MRXvI9OMy14sC9UsQIxwVEnEoA3hhLGdHhL4,13457
+TonieToolbox/tonie_analysis.py,sha256=kp4Wx4cTDddtF2AlS6IX4xs1vQ-mpZ0gsAy4-UdRAAM,23287
+TonieToolbox/tonie_file.py,sha256=vY0s8X4ln35ZXpdpGmBcIxgpTJAjduiVvBh34WObyrw,19647
+TonieToolbox/tonie_header.proto,sha256=WaWfwO4VrwGtscK2ujfDRKtpeBpaVPoZhI8iMmR-C0U,202
+TonieToolbox/tonie_header_pb2.py,sha256=s5bp4ULTEekgq6T61z9fDkRavyPM-3eREs20f_Pxxe8,3665
+TonieToolbox/version_handler.py,sha256=7Zx-pgzAUhz6jMplvNal1wHyxidodVxaNcAV0EMph5k,9778
+tonietoolbox-0.2.3.dist-info/licenses/LICENSE.md,sha256=rGoga9ZAgNco9fBapVFpWf6ri7HOBp1KRnt1uIruXMk,35190
+tonietoolbox-0.2.3.dist-info/METADATA,sha256=2LiL3ouh2jIdA3CD7i8nSZY-PStXbhkT8GNTZVvpgrM,12444
+tonietoolbox-0.2.3.dist-info/WHEEL,sha256=pxyMxgL8-pra_rKaQ4drOZAegBVuX-G_4nRHjjgWbmo,91
+tonietoolbox-0.2.3.dist-info/entry_points.txt,sha256=oqpeyBxel7aScg35Xr4gZKnf486S5KW9okqeBwyJxxc,60
+tonietoolbox-0.2.3.dist-info/top_level.txt,sha256=Wkkm-2p7I3ENfS7ZbYtYUB2g-xwHrXVlERHfonsOPuE,13
+tonietoolbox-0.2.3.dist-info/RECORD,,

{tonietoolbox-0.2.1.dist-info → tonietoolbox-0.2.3.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (78.1.1)
+Generator: setuptools (79.0.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

tonietoolbox-0.2.1.dist-info/RECORD

@@ -1,21 +0,0 @@
-TonieToolbox/__init__.py,sha256=141g35CQjQQB9-oCGkOKQkDV9GWkssN0IhK1vh1FBoc,96
-TonieToolbox/__main__.py,sha256=KE5x6KMLQZGd4nwjk71AmlxMZOgnN-lXLBNDi6XkHJc,10917
-TonieToolbox/audio_conversion.py,sha256=ra72qsE8j2GEP_4kqDT9m6aKlnnREZhZAlpf7y83pA0,11202
-TonieToolbox/constants.py,sha256=QQWQpnCI65GByLlXLOkt2n8nALLu4m6BWp0zuhI3M04,2021
-TonieToolbox/dependency_manager.py,sha256=fWtYp_UQDKrgIKcOyy95w7Grk_wYx5Fadyg8ulpb7nE,23451
-TonieToolbox/filename_generator.py,sha256=RqQHyGTKakuWR01yMSnFVMU_HfLw3rqFxKhXNIHdTlg,3441
-TonieToolbox/logger.py,sha256=Up9fBVkOZwkY61_645bX4tienCpyVSkap-FeTV0v730,1441
-TonieToolbox/ogg_page.py,sha256=-ViaIRBgh5ayfwmyplL8QmmRr5P36X8W0DdHkSFUYUU,21948
-TonieToolbox/opus_packet.py,sha256=OcHXEe3I_K4mWPUD55prpG42sZxJsEeAxqSbFxBmb0c,7895
-TonieToolbox/recursive_processor.py,sha256=vhQzC05bJVRPX8laj_5lxuRD40eLsZatzwCoCavMsmY,9304
-TonieToolbox/tonie_analysis.py,sha256=4eOzxHL_g0TJFhuexNHcZXivxZ7eb5xfb9-efUZ02W0,20344
-TonieToolbox/tonie_file.py,sha256=nIS4qhpBKIyPvTU39yYljRidpY6cz78halXlz3HJy9w,15294
-TonieToolbox/tonie_header.proto,sha256=WaWfwO4VrwGtscK2ujfDRKtpeBpaVPoZhI8iMmR-C0U,202
-TonieToolbox/tonie_header_pb2.py,sha256=s5bp4ULTEekgq6T61z9fDkRavyPM-3eREs20f_Pxxe8,3665
-TonieToolbox/version_handler.py,sha256=7Zx-pgzAUhz6jMplvNal1wHyxidodVxaNcAV0EMph5k,9778
-tonietoolbox-0.2.1.dist-info/licenses/LICENSE.md,sha256=rGoga9ZAgNco9fBapVFpWf6ri7HOBp1KRnt1uIruXMk,35190
-tonietoolbox-0.2.1.dist-info/METADATA,sha256=mMJ6-auDHNFK12NcDU_HNQlwiC6Y98fprLJICBihaxI,10514
-tonietoolbox-0.2.1.dist-info/WHEEL,sha256=lTU6B6eIfYoiQJTZNc-fyaR6BpL6ehTzU3xGYxn2n8k,91
-tonietoolbox-0.2.1.dist-info/entry_points.txt,sha256=oqpeyBxel7aScg35Xr4gZKnf486S5KW9okqeBwyJxxc,60
-tonietoolbox-0.2.1.dist-info/top_level.txt,sha256=Wkkm-2p7I3ENfS7ZbYtYUB2g-xwHrXVlERHfonsOPuE,13
-tonietoolbox-0.2.1.dist-info/RECORD,,