TonieToolbox 0.2.1__tar.gz → 0.2.3__tar.gz

{tonietoolbox-0.2.1/TonieToolbox.egg-info → tonietoolbox-0.2.3}/PKG-INFO

@@ -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.1 → tonietoolbox-0.2.3}/README.md

@@ -19,6 +19,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)
@@ -40,15 +41,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
 
@@ -139,7 +142,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).
@@ -171,6 +175,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
@@ -242,6 +252,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.1 → tonietoolbox-0.2.3}/TonieToolbox/__init__.py

@@ -2,4 +2,4 @@
 TonieToolbox - Convert audio files to Tonie box compatible format
 """
 
-__version__ = '0.2.1'
+__version__ = '0.2.3'

{tonietoolbox-0.2.1 → tonietoolbox-0.2.3}/TonieToolbox/__main__.py

@@ -17,6 +17,7 @@ from .logger import setup_logging, get_logger
 from .filename_generator import guess_output_filename
 from .version_handler import check_for_updates, clear_version_cache
 from .recursive_processor import process_recursive_folders
+from .media_tags import is_available as is_media_tags_available, ensure_mutagen
 
 def main():
     """Entry point for the TonieToolbox application."""
@@ -45,11 +46,22 @@ def main():
     parser.add_argument('-A', '--auto-download', action='store_true', help='Automatically download FFmpeg and opusenc if needed')
     parser.add_argument('-k', '--keep-temp', action='store_true', 
                        help='Keep temporary opus files in a temp folder for testing')
+    parser.add_argument('-u', '--use-legacy-tags', action='store_true',
+                       help='Use legacy hardcoded tags instead of dynamic TonieToolbox tags')
     parser.add_argument('-C', '--compare', action='store', metavar='FILE2', 
                        help='Compare input file with another .taf file for debugging')
     parser.add_argument('-D', '--detailed-compare', action='store_true',
                        help='Show detailed OGG page differences when comparing files')
     
+    # Media tag options
+    media_tag_group = parser.add_argument_group('Media Tag Options')
+    media_tag_group.add_argument('-m', '--use-media-tags', action='store_true',
+                       help='Use media tags from audio files for naming')
+    media_tag_group.add_argument('--name-template', metavar='TEMPLATE', action='store',
+                       help='Template for naming files using media tags. Example: "{album} - {artist}"')
+    media_tag_group.add_argument('--show-tags', action='store_true',
+                       help='Show available media tags from input files')
+    
     # Version check options
     version_group = parser.add_argument_group('Version Check Options')
     version_group.add_argument('-S', '--skip-update-check', action='store_true',
@@ -83,14 +95,12 @@ def main():
     logger = get_logger('main')
     logger.debug("Starting TonieToolbox v%s with log level: %s", __version__, logging.getLevelName(log_level))
     
-    # Handle version cache operations
     if args.clear_version_cache:
         if clear_version_cache():
             logger.info("Version cache cleared successfully")
         else:
             logger.info("No version cache to clear or error clearing cache")
     
-    # Check for updates
     if not args.skip_update_check:
         logger.debug("Checking for updates (force_refresh=%s)", args.force_refresh_cache)
         is_latest, latest_version, message, update_confirmed = check_for_updates(
@@ -117,10 +127,24 @@ def main():
             sys.exit(1)
         logger.debug("Using opusenc binary: %s", opus_binary)
 
+    # Check for media tags library and handle --show-tags option
+    if (args.use_media_tags or args.show_tags or args.name_template) and not is_media_tags_available():
+        if not ensure_mutagen(auto_install=args.auto_download):
+            logger.warning("Media tags functionality requires the mutagen library but it could not be installed.")
+            if args.use_media_tags or args.show_tags:
+                logger.error("Cannot proceed with --use-media-tags or --show-tags without mutagen library")
+                sys.exit(1)
+        else:
+            logger.info("Successfully enabled media tag support")
+
     # Handle recursive processing
     if args.recursive:
         logger.info("Processing folders recursively: %s", args.input_filename)
-        process_tasks = process_recursive_folders(args.input_filename)
+        process_tasks = process_recursive_folders(
+            args.input_filename,
+            use_media_tags=args.use_media_tags,
+            name_template=args.name_template
+        )
         
         if not process_tasks:
             logger.error("No folders with audio files found for recursive processing")
@@ -143,7 +167,7 @@ def main():
             
             create_tonie_file(task_out_filename, audio_files, args.no_tonie_header, args.user_timestamp,
                            args.bitrate, not args.cbr, ffmpeg_binary, opus_binary, args.keep_temp, 
-                           args.auto_download)
+                           args.auto_download, not args.use_legacy_tags)
             logger.info("Successfully created Tonie file: %s", task_out_filename)
             
         logger.info("Recursive processing completed. Created %d Tonie files.", len(process_tasks))
@@ -176,8 +200,104 @@ def main():
         logger.error("No files found for pattern %s", args.input_filename)
         sys.exit(1)
 
+    # Show tags for input files if requested
+    if args.show_tags:
+        from .media_tags import get_file_tags
+        logger.info("Showing media tags for input files:")
+        
+        for file_index, file_path in enumerate(files):
+            tags = get_file_tags(file_path)
+            if tags:
+                print(f"\nFile {file_index + 1}: {os.path.basename(file_path)}")
+                print("-" * 40)
+                for tag_name, tag_value in sorted(tags.items()):
+                    print(f"{tag_name}: {tag_value}")
+            else:
+                print(f"\nFile {file_index + 1}: {os.path.basename(file_path)} - No tags found")
+        
+        sys.exit(0)
+        
+    # Use media tags for file naming if requested
+    guessed_name = None
+    if args.use_media_tags:
+        # If this is a single folder, try to get consistent album info
+        if len(files) > 1 and os.path.dirname(files[0]) == os.path.dirname(files[-1]):
+            folder_path = os.path.dirname(files[0])
+            
+            from .media_tags import extract_album_info, format_metadata_filename
+            logger.debug("Extracting album info from folder: %s", folder_path)
+            
+            album_info = extract_album_info(folder_path)
+            if album_info:
+                # Use album info for naming the output file
+                template = args.name_template or "{album} - {artist}"
+                new_name = format_metadata_filename(album_info, template)
+                
+                if new_name:
+                    logger.info("Using album metadata for output filename: %s", new_name)
+                    guessed_name = new_name
+                else:
+                    logger.debug("Could not format filename from album metadata")
+        
+        # For single files, use the file's metadata
+        elif len(files) == 1:
+            from .media_tags import get_file_tags, format_metadata_filename
+            
+            tags = get_file_tags(files[0])
+            if tags:
+                template = args.name_template or "{title} - {artist}"
+                new_name = format_metadata_filename(tags, template)
+                
+                if new_name:
+                    logger.info("Using file metadata for output filename: %s", new_name)
+                    guessed_name = new_name
+                else:
+                    logger.debug("Could not format filename from file metadata")
+        
+        # For multiple files from different folders, try to use common tags if they exist
+        elif len(files) > 1:
+            from .media_tags import get_file_tags, format_metadata_filename
+            
+            # Try to find common tags among files
+            common_tags = {}
+            for file_path in files:
+                tags = get_file_tags(file_path)
+                if tags:
+                    for key, value in tags.items():
+                        if key in ['album', 'albumartist', 'artist']:
+                            if key not in common_tags:
+                                common_tags[key] = value
+                            # Only keep values that are the same across files
+                            elif common_tags[key] != value:
+                                common_tags[key] = None
+            
+            # Remove None values
+            common_tags = {k: v for k, v in common_tags.items() if v is not None}
+            
+            if common_tags:
+                template = args.name_template or "Collection - {album}" if 'album' in common_tags else "Collection"
+                new_name = format_metadata_filename(common_tags, template)
+                
+                if new_name:
+                    logger.info("Using common metadata for output filename: %s", new_name)
+                    guessed_name = new_name
+                else:
+                    logger.debug("Could not format filename from common metadata")
+
     if args.output_filename:
         out_filename = args.output_filename
+    elif guessed_name:
+        if args.output_to_source:
+            source_dir = os.path.dirname(files[0]) if files else '.'
+            out_filename = os.path.join(source_dir, guessed_name)
+            logger.debug("Using source location for output with media tags: %s", out_filename)
+        else:
+            output_dir = './output'
+            if not os.path.exists(output_dir):
+                logger.debug("Creating default output directory: %s", output_dir)
+                os.makedirs(output_dir, exist_ok=True)
+            out_filename = os.path.join(output_dir, guessed_name)
+            logger.debug("Using default output location with media tags: %s", out_filename)
     else:
         guessed_name = guess_output_filename(args.input_filename, files)    
         if args.output_to_source:
@@ -207,7 +327,8 @@ def main():
     
     logger.info("Creating Tonie file: %s with %d input file(s)", out_filename, len(files))
     create_tonie_file(out_filename, files, args.no_tonie_header, args.user_timestamp,
-                     args.bitrate, not args.cbr, ffmpeg_binary, opus_binary, args.keep_temp, args.auto_download)
+                     args.bitrate, not args.cbr, ffmpeg_binary, opus_binary, args.keep_temp, 
+                     args.auto_download, not args.use_legacy_tags)
     logger.info("Successfully created Tonie file: %s", out_filename)
 
 

{tonietoolbox-0.2.1 → tonietoolbox-0.2.3}/TonieToolbox/dependency_manager.py

@@ -52,6 +52,10 @@ DEPENDENCIES = {
         'darwin': {
             'package': 'opus-tools'
         }
+    },
+    'mutagen': {
+        'package': 'mutagen',
+        'python_package': True
     }
 }
 
@@ -365,6 +369,92 @@ def install_package(package_name):
         logger.error("Failed to install %s: %s", package_name, e)
         return False
 
+def install_python_package(package_name):
+    """
+    Attempt to install a Python package using pip.
+    
+    Args:
+        package_name (str): Name of the package to install
+        
+    Returns:
+        bool: True if installation was successful, False otherwise
+    """
+    logger.info("Attempting to install Python package: %s", package_name)
+    try:
+        import subprocess
+        import sys
+        
+        # Try to install the package using pip
+        subprocess.check_call([sys.executable, "-m", "pip", "install", package_name])
+        logger.info("Successfully installed Python package: %s", package_name)
+        return True
+    except Exception as e:
+        logger.error("Failed to install Python package %s: %s", package_name, str(e))
+        return False
+
+def check_python_package(package_name):
+    """
+    Check if a Python package is installed.
+    
+    Args:
+        package_name (str): Name of the package to check
+        
+    Returns:
+        bool: True if the package is installed, False otherwise
+    """
+    logger.debug("Checking if Python package is installed: %s", package_name)
+    try:
+        __import__(package_name)
+        logger.debug("Python package %s is installed", package_name)
+        return True
+    except ImportError:
+        logger.debug("Python package %s is not installed", package_name)
+        return False
+
+def ensure_mutagen(auto_install=True):
+    """
+    Ensure that the Mutagen library is available, installing it if necessary and allowed.
+    
+    Args:
+        auto_install (bool): Whether to automatically install Mutagen if not found (defaults to True)
+        
+    Returns:
+        bool: True if Mutagen is available, False otherwise
+    """
+    logger.debug("Checking if Mutagen is available")
+    
+    try:
+        import mutagen
+        logger.debug("Mutagen is already installed")
+        return True
+    except ImportError:
+        logger.debug("Mutagen is not installed")
+        
+        if auto_install:
+            logger.info("Auto-install enabled, attempting to install Mutagen")
+            if install_python_package('mutagen'):
+                try:
+                    import mutagen
+                    logger.info("Successfully installed and imported Mutagen")
+                    return True
+                except ImportError:
+                    logger.error("Mutagen was installed but could not be imported")
+            else:
+                logger.error("Failed to install Mutagen")
+        else:
+            logger.warning("Mutagen is not installed and --auto-download is not used.")
+        
+        return False
+
+def is_mutagen_available():
+    """
+    Check if the Mutagen library is available.
+    
+    Returns:
+        bool: True if Mutagen is available, False otherwise
+    """
+    return check_python_package('mutagen')
+
 def ensure_dependency(dependency_name, auto_download=False):
     """
     Ensure that a dependency is available, downloading it if necessary.
@@ -532,4 +622,49 @@ def get_opus_binary(auto_download=False):
     Returns:
         str: Path to the opusenc binary if available, None otherwise
     """
-    return ensure_dependency('opusenc', auto_download)
+    return ensure_dependency('opusenc', auto_download)
+
+def get_opus_version(opus_binary=None):
+    """
+    Get the version of opusenc.
+    
+    Args:
+        opus_binary: Path to the opusenc binary
+        
+    Returns:
+        str: The version string of opusenc, or a fallback string if the version cannot be determined
+    """
+    import subprocess
+    import re
+    
+    logger = get_logger('dependency_manager')
+    
+    if opus_binary is None:
+        opus_binary = get_opus_binary()
+    
+    if opus_binary is None:
+        logger.debug("opusenc binary not found, using fallback version string")
+        return "opusenc from opus-tools XXX"  # Fallback
+    
+    try:
+        # Run opusenc --version and capture output
+        result = subprocess.run([opus_binary, "--version"], 
+                                capture_output=True, text=True, check=False)
+        
+        # Extract version information from output
+        version_output = result.stdout.strip() or result.stderr.strip()
+        
+        if version_output:
+            # Try to extract just the version information using regex
+            match = re.search(r"(opusenc.*)", version_output)
+            if match:
+                return match.group(1)
+            else:
+                return version_output.splitlines()[0]  # Use first line
+        else:
+            logger.debug("Could not determine opusenc version, using fallback")
+            return "opusenc from opus-tools XXX"  # Fallback
+    
+    except Exception as e:
+        logger.debug(f"Error getting opusenc version: {str(e)}")
+        return "opusenc from opus-tools XXX"  # Fallback