Skip to content

005-music_metadata_scanner_simple_README.md

Latest commit

 

History

History
326 lines (246 loc) · 10.9 KB

005-music_metadata_scanner_simple_README.md

File metadata and controls

326 lines (246 loc) · 10.9 KB
Raw

Music Metadata Scanner

A powerful PowerShell script for scanning, analysing, and cleaning music metadata with advanced artist variable processing capabilities.

File: music_metadata_scanner_simple.ps1

Overview

This script provides comprehensive music metadata scanning and processing functionality, including the ability to read metadata from music files, process complex artist information, and optionally write cleaned metadata back to files. It's designed to handle multi-artist collaborations, featured artists, and various naming conventions commonly found in music collections.

Features

  • 🎵 Multi-Format Support: Supports MP3, FLAC, M4A, WAV, WMA, and OGG files
  • 🔍 Advanced Artist Processing: Intelligently parses complex artist strings like "Bob Marley & The Wailers" or "Eminem feat. Dr. Dre"
  • 📊 Multiple Export Formats: Generate reports in JSON, CSV, HTML, or all formats
  • ✏️ Metadata Writing: Write processed artist variables back to music files
  • 🛡️ Backup Protection: Automatic backup creation before modifying files
  • 📈 Statistical Analysis: Artist and genre distribution statistics
  • 🎯 Demo Mode: Test functionality with sample data
  • 🔄 Dry Run Mode: Preview changes without modifying files

Requirements

  • PowerShell 5.0+
  • TagLib# Library: Required for reading/writing music metadata
    • Location: .\Libraries\taglib\src\TaglibSharp\bin\Debug\net462\TagLibSharp.dll
    • Download from: TagLib# GitHub

Reference Knowledge

This project incorporates knowledge and techniques from various sources and technical domains:

Audio Metadata Standards

  • ID3 Tags: MP3 metadata standard for artist, album, title, and custom fields
  • Vorbis Comments: Metadata standard used in FLAC and OGG files
  • MP4 Metadata: iTunes-compatible metadata for M4A files
  • APE Tags: Alternative metadata format support

Artist Processing Algorithms

  • Regex Pattern Matching: Complex patterns for parsing artist collaborations
  • String Normalisation: Unicode handling and text standardisation
  • Artist Separation Logic: Based on MusicBrainz Picard plugin patterns
  • Featured Artist Detection: Recognition of "feat.", "ft.", "featuring" patterns

PowerShell Advanced Techniques

  • CmdletBinding: Advanced function parameter binding and validation
  • Parameter Sets: Mutually exclusive parameter combinations
  • Progress Reporting: Write-Progress for long-running operations
  • Error Handling: Comprehensive try-catch-finally blocks
  • Pipeline Processing: PowerShell object pipeline optimization

File System & I/O Operations

  • Recursive Directory Traversal: Efficient file system scanning
  • File Backup Strategies: Timestamp-based backup creation
  • Path Manipulation: Cross-platform path handling
  • File Locking: Safe concurrent file access patterns

Data Export & Reporting

  • JSON Serialization: ConvertTo-Json with proper depth handling
  • CSV Generation: Export-Csv with UTF-8 encoding
  • HTML Report Generation: Dynamic table creation with CSS styling
  • Statistical Analysis: Artist frequency and distribution calculations

Music Industry Standards

  • Multi-Artist Conventions: Industry-standard collaboration notation
  • Genre Classification: Standard music genre categorization
  • Album Artist vs Track Artist: Distinction handling for compilations
  • Metadata Completeness: Industry best practices for music metadata

External Libraries & Dependencies

  • TagLib# (.NET): C# wrapper for the TagLib audio metadata library
  • MusicBrainz Concepts: Artist credit and relationship modeling
  • Unicode Support: International character set handling for global music collections

Installation

  1. Clone or download this repository
  2. Install TagLib# library in the expected directory structure: 
    MusicLibCleaner/
├── music_metadata_scanner_simple.ps1
└── Libraries/
    └── taglib/
        └── src/
            └── TaglibSharp/
                └── bin/
                    └── Debug/
                        └── net462/
                            └── TagLibSharp.dll

.\music_metadata_scanner_simple.ps1

# Scan specific directory
.\music_metadata_scanner_simple.ps1 -SourceDirectory "C:\Music"

# Recursive scan with detailed output
.\music_metadata_scanner_simple.ps1 -SourceDirectory "C:\Music" -Recursive -DetailedOutput

Advanced Usage

# Generate all export formats
.\music_metadata_scanner_simple.ps1 -ExportFormat All

# Write metadata back to files with backups
.\music_metadata_scanner_simple.ps1 -WriteMetadata -CreateBackups

# Test metadata writing without changes
.\music_metadata_scanner_simple.ps1 -WriteMetadata -DryRun

# Demo mode for testing
.\music_metadata_scanner_simple.ps1 -DemoMode

Parameters

Parameter Type Default Description
SourceDirectory String C:\OrganizedMusic\DUPLICATES\Reggae\L1 Directory containing music files
OutputDirectory String .\metadata_output Output directory for reports
Extensions String[] @('.mp3', '.flac', '.m4a', '.wav', '.wma', '.ogg') File extensions to process
ExportFormat String HTML Export format: JSON, CSV, HTML, or All
Recursive Switch False Process subdirectories recursively
DetailedOutput Switch False Enable detailed console output
DryRun Switch False Preview mode without changes
DemoMode Switch False Use sample data for testing
WriteMetadata Switch False Write processed metadata back to files
CreateBackups Switch False Create backup files before writing
MetadataFields String[] @("artist", "albumartist") Metadata fields to update

Artist Processing

The script intelligently processes complex artist strings:

Examples

Original Artist Primary Artist Additional Artists
Bob Marley & The Wailers Bob Marley The Wailers
Eminem feat. Dr. Dre Eminem Dr. Dre
Queen ft. David Bowie Queen David Bowie
Simon & Garfunkel Simon Garfunkel
Johnny Cash with June Carter Johnny Cash June Carter

Supported Separators

  • & (ampersand)
  • feat. / ft. (featuring)
  • with
  • + (plus)

Configuration

The script includes a hardcoded configuration section that can be customised:

$HARDCODED_CONFIG = @{
    UseDemoMode = $false
    UseDryRun = $false
    DefaultSourceDirectory = "C:\OrganizedMusic\DUPLICATES\Reggae\L1"
    DefaultExportFormat = "HTML"
    ProcessRecursively = $true
    ShowDetailedOutput = $true
    # ... more settings
}

Output Formats

HTML Report

  • Interactive web-based report
  • Artist and genre statistics
  • Detailed file listings with processed variables
  • Visual highlighting of primary artists

JSON Export

  • Machine-readable format
  • Complete metadata and processed variables
  • Suitable for further processing or API integration

CSV Export

  • Spreadsheet-compatible format
  • Tabular data with all key fields
  • Easy to import into data analysis tools

Text Report

  • Simple, readable format
  • Summary statistics
  • File-by-file breakdown

Metadata Writing

When enabled, the script can write processed artist variables back to music files:

Safety Features

  • Backup Creation: Original files are backed up before modification
  • Dry Run Mode: Preview changes without writing
  • Selective Fields: Choose which metadata fields to update
  • Error Handling: Detailed error reporting for failed writes

Example Workflow

# 1. Test with dry run
.\music_metadata_scanner_simple.ps1 -WriteMetadata -DryRun

# 2. Write with backups
.\music_metadata_scanner_simple.ps1 -WriteMetadata -CreateBackups

# 3. Verify results
.\music_metadata_scanner_simple.ps1 -ExportFormat HTML

Sample Output

MUSIC METADATA SCANNING SUMMARY
======================================================================
Start Time: 2025-10-31 22:36:36
End Time: 2025-10-31 22:36:39
Duration: 00:00:03
Source Directory: C:\OrganizedMusic\DUPLICATES\Reggae\L1
Output Directory: .\metadata_output

RESULTS:
   Total files found: 880
   Files processed: 880
   Files with errors: 0
   Unique artists found: 255
   Unique genres found: 5
   Processing rate: 31.85 files/sec

TOP ARTISTS:
   Eric Donaldson: 85 tracks
   Beres Hammond: 52 tracks
   Bob Marley: 52 tracks
   Gregory Isaacs: 51 tracks
   Various Artists: 184 tracks

Error Handling

The script includes comprehensive error handling:

  • File Access Errors: Graceful handling of locked or inaccessible files
  • Metadata Errors: Continues processing when individual files fail
  • Library Errors: Fallback to basic file information if TagLib fails
  • Write Errors: Detailed reporting of metadata write failures

Troubleshooting

Common Issues

  1. TagLib Not Found

    Error: TagLib not found. Using basic file information only.

    Solution: Ensure TagLib# DLL is in the correct location

  2. Permission Denied

    Error: Access to the path 'file.mp3' is denied.

    Solution: Run PowerShell as Administrator or check file permissions

  3. No Files Found

    Found 0 music files

    Solution: Check source directory path and file extensions

Debug Mode

Enable detailed output for troubleshooting:

.\music_metadata_scanner_simple.ps1 -DetailedOutput -Verbose

Performance

  • Processing Speed: ~30-35 files per second
  • Memory Usage: Efficient processing of large collections
  • Scalability: Tested with 800+ files successfully

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Test with both demo mode and real files
  5. Submit a pull request

License

This project is open source. Please check the repository for license details.

Version History

  • v1.0: Initial release with basic scanning
  • v1.1: Added metadata writing capabilities
  • v1.2: Fixed single-letter artist bug
  • Current: Enhanced error handling and documentation

Support

For issues, feature requests, or questions:

  1. Check the troubleshooting section above
  2. Review existing GitHub issues
  3. Create a new issue with detailed information
  4. Include sample files (if possible) and error messages

Related Tools

  • TagLib#: Core metadata library
  • additional_artists_variables.ps1: Related artist processing utilities
  • MusicBrainz Picard: Alternative metadata editing tool
  • Mp3tag: GUI-based metadata editor

Note: This script is designed for personal use with legally owned music collections. Ensure you have appropriate rights to modify metadata of music files.