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

TonieToolbox/__init__.py

@@ -2,4 +2,4 @@
 TonieToolbox - Convert audio files to Tonie box compatible format
 """
 
-__version__ = '0.2.2'
+__version__ = '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."""
@@ -52,6 +53,15 @@ def main():
     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',
@@ -85,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(
@@ -119,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")
@@ -178,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:

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.

TonieToolbox/media_tags.py

@@ -0,0 +1,471 @@
+"""
+Media tag processing functionality for the TonieToolbox package
+
+This module handles reading and processing metadata tags from audio files,
+which can be used to enhance Tonie file creation with proper track information.
+"""
+
+import os
+from typing import Dict, Any, Optional, List
+import logging
+from .logger import get_logger
+from .dependency_manager import is_mutagen_available, ensure_mutagen
+
+# Global variables to track dependency state and store module references
+MUTAGEN_AVAILABLE = False
+mutagen = None
+ID3 = None
+FLAC = None
+MP4 = None
+OggOpus = None
+OggVorbis = None
+
+def _import_mutagen():
+    """
+    Import the mutagen modules and update global variables.
+    
+    Returns:
+        bool: True if import was successful, False otherwise
+    """
+    global MUTAGEN_AVAILABLE, mutagen, ID3, FLAC, MP4, OggOpus, OggVorbis
+    
+    try:
+        import mutagen as _mutagen
+        from mutagen.id3 import ID3 as _ID3
+        from mutagen.flac import FLAC as _FLAC
+        from mutagen.mp4 import MP4 as _MP4
+        from mutagen.oggopus import OggOpus as _OggOpus
+        from mutagen.oggvorbis import OggVorbis as _OggVorbis
+        
+        # Assign to global variables
+        mutagen = _mutagen
+        ID3 = _ID3
+        FLAC = _FLAC
+        MP4 = _MP4
+        OggOpus = _OggOpus
+        OggVorbis = _OggVorbis
+        MUTAGEN_AVAILABLE = True
+        return True
+    except ImportError:
+        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:
+    """
+    Normalize tag values by replacing special characters or known patterns
+    with more file-system-friendly alternatives.
+    
+    Args:
+        value: The original tag value
+        
+    Returns:
+        Normalized tag value
+    """
+    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]
+    
+    # Check for partial matches and replacements
+    result = value
+    for pattern, replacement in TAG_VALUE_REPLACEMENTS.items():
+        if pattern in result:
+            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:
+    """
+    Check if tag reading functionality is available.
+    
+    Returns:
+        bool: True if mutagen is available, False otherwise
+    """
+    return MUTAGEN_AVAILABLE or is_mutagen_available()
+
+def get_file_tags(file_path: str) -> Dict[str, Any]:
+    """
+    Extract metadata tags from an audio file.
+    
+    Args:
+        file_path: Path to the audio file
+        
+    Returns:
+        Dictionary containing standardized tag names and values
+    """
+    global MUTAGEN_AVAILABLE
+    
+    if not MUTAGEN_AVAILABLE:
+        # Try to ensure mutagen is available
+        if ensure_mutagen(auto_install=True):
+            # If successful, import the necessary modules
+            if not _import_mutagen():
+                logger.warning("Mutagen library not available. Cannot read media tags.")
+                return {}
+        else:
+            logger.warning("Mutagen library not available. Cannot read media tags.")
+            return {}
+        
+    logger.debug("Reading tags from file: %s", file_path)
+    tags = {}
+    
+    try:
+        # Use mutagen to identify and load the file
+        audio = mutagen.File(file_path)
+        if audio is None:
+            logger.warning("Could not identify file format: %s", file_path)
+            return tags
+            
+        # Process different file types
+        if isinstance(audio, ID3) or hasattr(audio, 'ID3'):
+            # MP3 files
+            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:
+                    tag_value_str = str(tag_value)
+                    tags[TAG_MAPPING[tag_name]] = normalize_tag_value(tag_value_str)
+        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:
+                    # 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)
+        elif isinstance(audio, MP4):
+            # MP4 files
+            for tag_key, tag_value in audio.items():
+                if tag_key in TAG_MAPPING:
+                    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])
+                        else:
+                            tag_value_str = str(tag_value[0]) if tag_value else ''
+                            tags[TAG_MAPPING[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)
+        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 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)
+                    else:
+                        tag_value_str = str(tag_value)
+                        tags[TAG_MAPPING[tag_key_lower]] = normalize_tag_value(tag_value_str)
+                        
+        logger.debug("Successfully read %d tags from file", len(tags))
+        return tags
+    except Exception as e:
+        logger.error("Error reading tags from file %s: %s", file_path, str(e))
+        return tags
+
+def extract_first_audio_file_tags(folder_path: str) -> Dict[str, str]:
+    """
+    Extract tags from the first audio file in a folder.
+    
+    Args:
+        folder_path: Path to folder containing audio files
+        
+    Returns:
+        Dictionary containing standardized tag names and values
+    """
+    from .audio_conversion import filter_directories
+    import glob
+    
+    logger.debug("Looking for audio files in %s", folder_path)
+    files = filter_directories(glob.glob(os.path.join(folder_path, "*")))
+    
+    if not files:
+        logger.debug("No audio files found in folder")
+        return {}
+        
+    # Get tags from the first file
+    first_file = files[0]
+    logger.debug("Using first audio file for tags: %s", first_file)
+    
+    return get_file_tags(first_file)
+
+def extract_album_info(folder_path: str) -> Dict[str, str]:
+    """
+    Extract album information from audio files in a folder.
+    Tries to get consistent album, artist and other information.
+    
+    Args:
+        folder_path: Path to folder containing audio files
+        
+    Returns:
+        Dictionary with extracted metadata (album, albumartist, etc.)
+    """
+    from .audio_conversion import filter_directories
+    import glob
+    
+    logger.debug("Extracting album information from folder: %s", folder_path)
+    
+    # Get all audio files in the folder
+    audio_files = filter_directories(glob.glob(os.path.join(folder_path, "*")))
+    if not audio_files:
+        logger.debug("No audio files found in folder")
+        return {}
+    
+    # Collect tag information from all files
+    all_tags = []
+    for file_path in audio_files:
+        tags = get_file_tags(file_path)
+        if tags:
+            all_tags.append(tags)
+    
+    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']
+    
+    for tag_name in key_tags:
+        # Count occurrences of each value
+        value_counts = {}
+        for tags in all_tags:
+            if tag_name in tags:
+                value = tags[tag_name]
+                if value in value_counts:
+                    value_counts[value] += 1
+                else:
+                    value_counts[value] = 1
+        
+        # Use the most common value, or the first one if there's a tie
+        if value_counts:
+            most_common_value = max(value_counts.items(), key=lambda x: x[1])[0]
+            result[tag_name] = most_common_value
+    
+    logger.debug("Extracted album info: %s", str(result))
+    return result
+
+def get_file_metadata(file_path: str) -> Dict[str, str]:
+    """
+    Get comprehensive metadata about a single audio file,
+    including both file tags and additional information.
+    
+    Args:
+        file_path: Path to the audio file
+        
+    Returns:
+        Dictionary containing metadata information
+    """
+    metadata = {}
+    
+    # Get basic file information
+    try:
+        basename = os.path.basename(file_path)
+        filename, extension = os.path.splitext(basename)
+        
+        metadata['filename'] = filename
+        metadata['extension'] = extension.lower().replace('.', '')
+        metadata['path'] = file_path
+        
+        # Get file size
+        metadata['filesize'] = os.path.getsize(file_path)
+        
+        # Add tags from the file
+        tags = get_file_tags(file_path)
+        metadata.update(tags)
+        
+        return metadata
+    except Exception as e:
+        logger.error("Error getting file metadata for %s: %s", file_path, str(e))
+        return metadata
+
+def get_folder_metadata(folder_path: str) -> Dict[str, Any]:
+    """
+    Get comprehensive metadata about a folder of audio files.
+    
+    Args:
+        folder_path: Path to folder containing audio files
+        
+    Returns:
+        Dictionary containing metadata information and list of files
+    """
+    folder_metadata = {}
+    
+    # Get basic folder information
+    folder_metadata['folder_name'] = os.path.basename(folder_path)
+    folder_metadata['folder_path'] = folder_path
+    
+    # Try to extract album info
+    album_info = extract_album_info(folder_path)
+    folder_metadata.update(album_info)
+    
+    # Also get folder name metadata using existing function
+    from .recursive_processor import extract_folder_meta
+    folder_name_meta = extract_folder_meta(folder_path)
+    
+    # Combine the metadata, prioritizing tag-based over folder name based
+    for key, value in folder_name_meta.items():
+        if key not in folder_metadata or not folder_metadata[key]:
+            folder_metadata[key] = value
+    
+    # Get list of audio files with their metadata
+    from .audio_conversion import filter_directories
+    import glob
+    
+    audio_files = filter_directories(glob.glob(os.path.join(folder_path, "*")))
+    files_metadata = []
+    
+    for file_path in audio_files:
+        file_metadata = get_file_metadata(file_path)
+        files_metadata.append(file_metadata)
+    
+    folder_metadata['files'] = files_metadata
+    folder_metadata['file_count'] = len(files_metadata)
+    
+    return folder_metadata
+
+def format_metadata_filename(metadata: Dict[str, str], template: str = "{tracknumber} - {title}") -> str:
+    """
+    Format a filename using metadata and a template string.
+    
+    Args:
+        metadata: Dictionary of metadata tags
+        template: Template string with placeholders matching metadata keys
+        
+    Returns:
+        Formatted string, or empty string if formatting fails
+    """
+    try:
+        # Format track numbers correctly (e.g., "1" -> "01")
+        if 'tracknumber' in metadata:
+            track = metadata['tracknumber']
+            if '/' in track:  # Handle "1/10" format
+                track = track.split('/')[0]
+            try:
+                metadata['tracknumber'] = f"{int(track):02d}"
+            except (ValueError, TypeError):
+                pass  # Keep original value if not a simple number
+                
+        # Format disc numbers the same way
+        if 'discnumber' in metadata:
+            disc = metadata['discnumber']
+            if '/' in disc:  # Handle "1/2" format
+                disc = disc.split('/')[0]
+            try:
+                metadata['discnumber'] = f"{int(disc):02d}"
+            except (ValueError, TypeError):
+                pass
+        
+        # Substitute keys in template
+        result = template
+        for key, value in metadata.items():
+            placeholder = "{" + key + "}"
+            if placeholder in result:
+                result = result.replace(placeholder, str(value))
+                
+        # Clean up any remaining placeholders for missing metadata
+        import re
+        result = re.sub(r'\{[^}]+\}', '', result)
+        
+        # Clean up consecutive spaces, dashes, etc.
+        result = re.sub(r'\s+', ' ', result)
+        result = re.sub(r'[-_\s]*-[-_\s]*', ' - ', result)
+        result = re.sub(r'^\s+|\s+$', '', result)  # trim
+        
+        # Replace characters that aren't allowed in filenames
+        result = re.sub(r'[<>:"/\\|?*]', '-', result)
+        
+        return result
+    except Exception as e:
+        logger.error("Error formatting metadata: %s", str(e))
+        return ""

TonieToolbox/recursive_processor.py

@@ -204,12 +204,101 @@ def extract_folder_meta(folder_path: str) -> Dict[str, str]:
     return meta
 
 
-def process_recursive_folders(root_path: str) -> List[Tuple[str, str, List[str]]]:
+def get_folder_name_from_metadata(folder_path: str, use_media_tags: bool = False, template: str = None) -> str:
+    """
+    Generate a suitable output filename for a folder based on folder name
+    and optionally audio file metadata.
+    
+    Args:
+        folder_path: Path to folder
+        use_media_tags: Whether to use media tags from audio files if available
+        template: Optional template for formatting output name using media tags
+        
+    Returns:
+        String with cleaned output name
+    """
+    # Start with folder name metadata
+    folder_meta = extract_folder_meta(folder_path)
+    output_name = None
+    
+    # Try to get metadata from audio files if requested
+    if use_media_tags:
+        try:
+            # Import here to avoid circular imports
+            from .media_tags import extract_album_info, format_metadata_filename, is_available, normalize_tag_value
+            
+            if is_available():
+                logger.debug("Using media tags to generate folder name for: %s", folder_path)
+                
+                # Get album metadata from the files
+                album_info = extract_album_info(folder_path)
+                
+                if album_info:
+                    # Normalize all tag values to handle special characters
+                    for key, value in album_info.items():
+                        album_info[key] = normalize_tag_value(value)
+                    
+                    # Add folder metadata as fallback values
+                    if 'number' in folder_meta and folder_meta['number']:
+                        if 'tracknumber' not in album_info or not album_info['tracknumber']:
+                            album_info['tracknumber'] = folder_meta['number']
+                    
+                    if 'title' in folder_meta and folder_meta['title']:
+                        if 'album' not in album_info or not album_info['album']:
+                            album_info['album'] = normalize_tag_value(folder_meta['title'])
+                    
+                    # Use template or default format
+                    format_template = template or "{album}"
+                    if 'artist' in album_info and album_info['artist']:
+                        format_template = format_template + " - {artist}"
+                    if 'number' in folder_meta and folder_meta['number']:
+                        format_template = "{tracknumber} - " + format_template
+                    
+                    formatted_name = format_metadata_filename(album_info, format_template)
+                    
+                    if formatted_name:
+                        logger.debug("Generated name from media tags: %s", formatted_name)
+                        output_name = formatted_name
+        except Exception as e:
+            logger.warning("Error using media tags for folder naming: %s", str(e))
+    
+    # Fall back to folder name parsing if no media tags or if media tag extraction failed
+    if not output_name:
+        if folder_meta['number'] and folder_meta['title']:
+            # Apply normalization to the title from the folder name
+            try:
+                from .media_tags import normalize_tag_value
+                normalized_title = normalize_tag_value(folder_meta['title'])
+                output_name = f"{folder_meta['number']} - {normalized_title}"
+            except:
+                output_name = f"{folder_meta['number']} - {folder_meta['title']}"
+        else:
+            # Try to normalize the folder name itself
+            folder_name = os.path.basename(folder_path)
+            try:
+                from .media_tags import normalize_tag_value
+                output_name = normalize_tag_value(folder_name)
+            except:
+                output_name = folder_name
+    
+    # Clean up the output name (remove invalid filename characters)
+    output_name = re.sub(r'[<>:"/\\|?*]', '_', output_name)
+    output_name = output_name.replace("???", "Fragezeichen")
+    output_name = output_name.replace("!!!", "Ausrufezeichen")
+    
+    logger.debug("Final generated output name: %s", output_name)
+    return output_name
+
+
+def process_recursive_folders(root_path: str, use_media_tags: bool = False, 
+                            name_template: str = None) -> List[Tuple[str, str, List[str]]]:
     """
     Process folders recursively and prepare data for conversion.
     
     Args:
         root_path: Root directory to start processing from
+        use_media_tags: Whether to use media tags from audio files for naming
+        name_template: Optional template for formatting output names using media tags
         
     Returns:
         List of tuples: (output_filename, folder_path, list_of_audio_files)
@@ -230,17 +319,13 @@ def process_recursive_folders(root_path: str) -> List[Tuple[str, str, List[str]]
         # Use natural sort order to ensure consistent results
         audio_files = natural_sort(audio_files)
         
-        meta = extract_folder_meta(folder_path)
-        
         if audio_files:
-            # Create output filename from metadata
-            if meta['number'] and meta['title']:
-                output_name = f"{meta['number']} - {meta['title']}"
-            else:
-                output_name = os.path.basename(folder_path)
-                
-            # Clean up the output name (remove invalid filename characters)
-            output_name = re.sub(r'[<>:"/\\|?*]', '_', output_name)
+            # Generate output filename using metadata
+            output_name = get_folder_name_from_metadata(
+                folder_path, 
+                use_media_tags=use_media_tags, 
+                template=name_template
+            )
             
             results.append((output_name, folder_path, audio_files))
             logger.debug("Created processing task: %s -> %s (%d files)", 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TonieToolbox
-Version: 0.2.2
+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.2.dist-info → tonietoolbox-0.2.3.dist-info}/RECORD

@@ -1,21 +1,22 @@
-TonieToolbox/__init__.py,sha256=UhSjPdhrXyhaT47L1QQH8FMLyK-1ddkUIQWtXr71Dcs,96
-TonieToolbox/__main__.py,sha256=eumivCJXMmlGZJLk3bC61-NwQEq3x5lElSIsmb2ZKWE,11157
+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=fBojtYnzK-jN3zOj9ntwotJhnyJfv6a-iz8zivK6L_Q,25017
+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=vhQzC05bJVRPX8laj_5lxuRD40eLsZatzwCoCavMsmY,9304
+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.2.dist-info/licenses/LICENSE.md,sha256=rGoga9ZAgNco9fBapVFpWf6ri7HOBp1KRnt1uIruXMk,35190
-tonietoolbox-0.2.2.dist-info/METADATA,sha256=cm2XH96XGJR6OEL0Wc0yvldIIG0rVFZvhaBheKpuzjw,10514
-tonietoolbox-0.2.2.dist-info/WHEEL,sha256=lTU6B6eIfYoiQJTZNc-fyaR6BpL6ehTzU3xGYxn2n8k,91
-tonietoolbox-0.2.2.dist-info/entry_points.txt,sha256=oqpeyBxel7aScg35Xr4gZKnf486S5KW9okqeBwyJxxc,60
-tonietoolbox-0.2.2.dist-info/top_level.txt,sha256=Wkkm-2p7I3ENfS7ZbYtYUB2g-xwHrXVlERHfonsOPuE,13
-tonietoolbox-0.2.2.dist-info/RECORD,,
+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.2.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