additional_artists_variables.ps1

# =====================================
# SCRIPT CREDITS
# =====================================
# Author: Benjamin Ohene-Adu (PowerShell conversion)
# Name of Script: additional_artists_variables.ps1
# Creation Date: October 31, 2025
# Intent of script: PowerShell library for extracting and processing artist variables from music metadata. Converts Python/MusicBrainz Picard plugin for artist separation and standardization.
# =====================================

# -*- coding: utf-8 -*-
#
# Copyright (C) 2018-2023 Bob Swift (rdswift)
# Copyright (C) 2023 Ruud van Asseldonk (ruuda)
# Converted to PowerShell 2025
#
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; either version 2
# of the License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
# 02110-1301, USA.

param(
    [Parameter(Mandatory=$false)]
    [string]$ConfigPath = "config.json",
    
    [Parameter(Mandatory=$false)]
    [int]$MaxGenres = 10,
    
    [Parameter(Mandatory=$false)]
    [switch]$Verbose
)

# Plugin metadata
$PLUGIN_NAME = 'Additional Artists Variables'
$PLUGIN_AUTHOR = 'Bob Swift (rdswift)'
$PLUGIN_DESCRIPTION = @"
This PowerShell script provides specialized album and track variables for use in
naming scripts. It is based on the "Album Artist Extension" plugin, but
expands the functionality to also include track artists. Note that it
cannot be used as a direct drop-in replacement for the "Album Artist
Extension" plugin because the variables are provided with different
names.
"@
$PLUGIN_VERSION = '1.0-PS'
$PLUGIN_LICENSE = 'GPL-2.0-or-later'
$PLUGIN_LICENSE_URL = 'https://www.gnu.org/licenses/gpl-2.0.html'

# Constants
$ID_ALIASES_ARTIST_NAME = '894afba6-2816-3c24-8072-eadb66bd04bc'
$ID_ALIASES_LEGAL_NAME = 'd4dcd0c0-b341-3612-a332-c0ce797b25cf'

# Configuration object
$global:Config = @{
    MaxGenres = $MaxGenres
    Verbose = $Verbose.IsPresent
}

# Logging function
function Write-MetadataError {
    param(
        [string]$AlbumId,
        [string]$MetadataElement,
        [string]$MetadataGroup
    )
    
    $message = "$PLUGIN_NAME`: '$AlbumId': Missing '$MetadataElement' in $MetadataGroup metadata."
    Write-Error $message
    
    if ($global:Config.Verbose) {
        Write-Host $message -ForegroundColor Red
    }
}

# Function to process artists
function Process-Artists {
    param(
        [string]$AlbumId,
        [hashtable]$SourceMetadata,
        [hashtable]$DestinationMetadata,
        [string]$SourceType
    )
    
    # Test for valid metadata node
    if (-not $SourceMetadata.ContainsKey('artist-credit')) {
        Write-MetadataError -AlbumId $AlbumId -MetadataElement 'artist-credit' -MetadataGroup $SourceType
        return
    }
    
    # Initialize variables to default values
    $sortPriArtist = ''
    $sortPriArtistCred = ''
    $stdArtist = ''
    $credArtist = ''
    $sortArtist = ''
    $credSortArtist = ''
    $legalArtist = ''
    $additionalStdArtist = ''
    $additionalCredArtist = ''
    $additionalSortArtist = ''
    $additionalCredSortArtist = ''
    $additionalLegalArtist = ''
    
    $stdArtistList = @()
    $credArtistList = @()
    $sortArtistList = @()
    $credSortArtistList = @()
    $legalArtistList = @()
    $artistIds = @()
    $artistTypes = @()
    $artistJoinPhrases = @()
    
    $artistCount = 0
    
    foreach ($artistCredit in $SourceMetadata['artist-credit']) {
        # Initialize temporary variables for each loop
        $tempStdName = ''
        $tempSortName = ''
        $tempCredName = ''
        $tempCredSortName = ''
        $tempLegalName = ''
        $tempLegalSortName = ''
        $tempPhrase = ''
        $tempId = ''
        $tempType = ''
        
        # Check if there is a 'joinphrase' specified
        if ($artistCredit.ContainsKey('joinphrase')) {
            $tempPhrase = $artistCredit['joinphrase']
        } else {
            Write-MetadataError -AlbumId $AlbumId -MetadataElement 'artist-credit.joinphrase' -MetadataGroup $SourceType
        }
        
        # Check if there is a 'name' specified
        if ($artistCredit.ContainsKey('name')) {
            $tempCredName = $artistCredit['name']
        } else {
            Write-MetadataError -AlbumId $AlbumId -MetadataElement 'artist-credit.name' -MetadataGroup $SourceType
        }
        
        # Check if there is an 'artist' specified
        if ($artistCredit.ContainsKey('artist')) {
            $artist = $artistCredit['artist']
            
            if ($artist.ContainsKey('id')) {
                $tempId = $artist['id']
            } else {
                Write-MetadataError -AlbumId $AlbumId -MetadataElement 'artist-credit.artist.id' -MetadataGroup $SourceType
            }
            
            if ($artist.ContainsKey('name')) {
                $tempStdName = $artist['name']
            } else {
                Write-MetadataError -AlbumId $AlbumId -MetadataElement 'artist-credit.artist.name' -MetadataGroup $SourceType
            }
            
            if ($artist.ContainsKey('sort-name')) {
                $tempSortName = $artist['sort-name']
                $tempCredSortName = $tempSortName
            } else {
                Write-MetadataError -AlbumId $AlbumId -MetadataElement 'artist-credit.artist.sort-name' -MetadataGroup $SourceType
            }
            
            if ($artist.ContainsKey('type')) {
                $tempType = $artist['type']
            } else {
                Write-MetadataError -AlbumId $AlbumId -MetadataElement 'artist-credit.artist.type' -MetadataGroup $SourceType
            }
            
            # Process aliases
            if ($artist.ContainsKey('aliases')) {
                foreach ($item in $artist['aliases']) {
                    if ($item.ContainsKey('type-id') -and $item['type-id'] -eq $ID_ALIASES_LEGAL_NAME) {
                        if ($item.ContainsKey('ended') -and -not $item['ended']) {
                            if ($item.ContainsKey('name')) {
                                $tempLegalName = $item['name']
                            }
                            if ($item.ContainsKey('sort-name')) {
                                $tempLegalSortName = $item['sort-name']
                            }
                        }
                    }
                    if ($item.ContainsKey('type-id') -and $item['type-id'] -eq $ID_ALIASES_ARTIST_NAME) {
                        if ($item.ContainsKey('name') -and $item.ContainsKey('sort-name') -and 
                            $item['name'].ToLower() -eq $tempCredName.ToLower()) {
                            $tempCredSortName = $item['sort-name']
                        }
                    }
                }
            }
            
            # Process tags/genres
            $tagList = @()
            if ($global:Config.MaxGenres -gt 0) {
                $tagTypes = @('user-genres', 'genres', 'user-tags', 'tags')
                foreach ($tagType in $tagTypes) {
                    if ($artist.ContainsKey($tagType)) {
                        $sortedTags = $artist[$tagType] | 
                            Where-Object { $_.count -gt 0 } |
                            Sort-Object name |
                            Sort-Object count -Descending
                        
                        foreach ($item in $sortedTags) {
                            $tagList += $item.name
                        }
                    }
                }
                $tagList = $tagList | Select-Object -First $global:Config.MaxGenres
            }
        } else {
            Write-MetadataError -AlbumId $AlbumId -MetadataElement 'artist-credit.artist' -MetadataGroup $SourceType
        }
        
        # Build combined strings
        $stdArtist += $tempStdName + $tempPhrase
        $credArtist += $tempCredName + $tempPhrase
        $sortArtist += $tempSortName + $tempPhrase
        $credSortArtist += $tempCredSortName + $tempPhrase
        
        $artistTypes += if ($tempType) { $tempType } else { 'unknown' }
        $artistJoinPhrases += if ($tempPhrase) { $tempPhrase } else { "`u{200B}" }
        
        if ($tempLegalName) {
            $legalArtist += $tempLegalName + $tempPhrase
            $legalArtistList += $tempLegalName
        } else {
            $legalArtist += $tempStdName + $tempPhrase
            $legalArtistList += 'n/a'
        }
        
        # Add to lists
        if ($tempStdName) { $stdArtistList += $tempStdName }
        if ($tempSortName) { $sortArtistList += $tempSortName }
        if ($tempCredName) { $credArtistList += $tempCredName }
        if ($tempCredSortName) { $credSortArtistList += $tempCredSortName }
        if ($tempId) { $artistIds += $tempId }
        
        # Handle primary artist (first one)
        if ($artistCount -eq 0) {
            if ($tempId) {
                $DestinationMetadata["~artists_${SourceType}_primary_id"] = $tempId
            }
            $DestinationMetadata["~artists_${SourceType}_primary_std"] = $tempStdName
            $DestinationMetadata["~artists_${SourceType}_primary_cred"] = $tempCredName
            $DestinationMetadata["~artists_${SourceType}_primary_sort"] = $tempSortName
            $DestinationMetadata["~artists_${SourceType}_primary_cred_sort"] = $tempCredSortName
            $DestinationMetadata["~artists_${SourceType}_primary_legal"] = $tempLegalName
            $DestinationMetadata["~artists_${SourceType}_primary_sort_legal"] = $tempLegalSortName
            
            $sortPriArtist += $tempSortName + $tempPhrase
            $sortPriArtistCred += $tempCredSortName + $tempPhrase
            
            if ($tagList -and $SourceType -eq 'album') {
                $DestinationMetadata["~artists_${SourceType}_primary_tags"] = $tagList
            }
        } else {
            $sortPriArtist += $tempStdName + $tempPhrase
            $additionalStdArtist += $tempStdName + $tempPhrase
            $additionalCredArtist += $tempCredName + $tempPhrase
            $additionalSortArtist += $tempSortName + $tempPhrase
            
            if ($tempLegalName) {
                $additionalLegalArtist += $tempLegalName + $tempPhrase
            } else {
                $additionalLegalArtist += $tempStdName + $tempPhrase
            }
            
            if ($tempCredSortName) {
                $additionalCredSortArtist += $tempCredSortName + $tempPhrase
                $sortPriArtistCred += $tempCredSortName + $tempPhrase
            } else {
                $additionalCredSortArtist += $tempSortName + $tempPhrase
                $sortPriArtistCred += $tempSortName + $tempPhrase
            }
        }
        
        $artistCount++
    }
    
    # Set additional artist variables
    $additionalStdArtistList = $stdArtistList | Select-Object -Skip 1
    $additionalCredArtistList = $credArtistList | Select-Object -Skip 1
    $additionalSortArtistList = $sortArtistList | Select-Object -Skip 1
    $additionalCredSortArtistList = $credSortArtistList | Select-Object -Skip 1
    $additionalLegalArtistList = $legalArtistList | Select-Object -Skip 1
    $additionalArtistIds = $artistIds | Select-Object -Skip 1
    
    # Set destination metadata
    if ($additionalArtistIds) {
        $DestinationMetadata["~artists_${SourceType}_additional_id"] = $additionalArtistIds
    }
    if ($additionalStdArtist) {
        $DestinationMetadata["~artists_${SourceType}_additional_std"] = $additionalStdArtist
    }
    if ($additionalCredArtist) {
        $DestinationMetadata["~artists_${SourceType}_additional_cred"] = $additionalCredArtist
    }
    if ($additionalSortArtist) {
        $DestinationMetadata["~artists_${SourceType}_additional_sort"] = $additionalSortArtist
    }
    if ($additionalCredSortArtist) {
        $DestinationMetadata["~artists_${SourceType}_additional_cred_sort"] = $additionalCredSortArtist
    }
    if ($additionalLegalArtist) {
        $DestinationMetadata["~artists_${SourceType}_additional_legal"] = $additionalLegalArtist
    }
    if ($additionalStdArtistList) {
        $DestinationMetadata["~artists_${SourceType}_additional_std_multi"] = $additionalStdArtistList
    }
    if ($additionalCredArtistList) {
        $DestinationMetadata["~artists_${SourceType}_additional_cred_multi"] = $additionalCredArtistList
    }
    if ($additionalSortArtistList) {
        $DestinationMetadata["~artists_${SourceType}_additional_sort_multi"] = $additionalSortArtistList
    }
    if ($additionalCredSortArtistList) {
        $DestinationMetadata["~artists_${SourceType}_additional_cred_sort_multi"] = $additionalCredSortArtistList
    }
    if ($additionalLegalArtistList) {
        $DestinationMetadata["~artists_${SourceType}_additional_legal_multi"] = $additionalLegalArtistList
    }
    
    # Set "all" variables
    if ($stdArtist) {
        $DestinationMetadata["~artists_${SourceType}_all_std"] = $stdArtist
    }
    if ($credArtist) {
        $DestinationMetadata["~artists_${SourceType}_all_cred"] = $credArtist
    }
    if ($credSortArtist) {
        $DestinationMetadata["~artists_${SourceType}_all_cred_sort"] = $credSortArtist
    }
    if ($sortArtist) {
        $DestinationMetadata["~artists_${SourceType}_all_sort"] = $sortArtist
    }
    if ($legalArtist) {
        $DestinationMetadata["~artists_${SourceType}_all_legal"] = $legalArtist
    }
    if ($stdArtistList) {
        $DestinationMetadata["~artists_${SourceType}_all_std_multi"] = $stdArtistList
    }
    if ($credArtistList) {
        $DestinationMetadata["~artists_${SourceType}_all_cred_multi"] = $credArtistList
    }
    if ($sortArtistList) {
        $DestinationMetadata["~artists_${SourceType}_all_sort_multi"] = $sortArtistList
    }
    if ($credSortArtistList) {
        $DestinationMetadata["~artists_${SourceType}_all_cred_sort_multi"] = $credSortArtistList
    }
    if ($legalArtistList) {
        $DestinationMetadata["~artists_${SourceType}_all_legal_multi"] = $legalArtistList
    }
    if ($sortPriArtist) {
        $DestinationMetadata["~artists_${SourceType}_all_sort_primary"] = $sortPriArtist
    }
    if ($artistTypes) {
        $DestinationMetadata["~artists_${SourceType}_all_types"] = $artistTypes
    }
    if ($artistJoinPhrases) {
        $DestinationMetadata["~artists_${SourceType}_all_join_phrases"] = $artistJoinPhrases
    }
    if ($artistCount -gt 0) {
        $DestinationMetadata["~artists_${SourceType}_all_count"] = $artistCount
    }
}

# Function to process album variables
function Set-AlbumVariables {
    param(
        [hashtable]$AlbumMetadata,
        [hashtable]$ReleaseMetadata
    )
    
    $albumId = if ($ReleaseMetadata -and $ReleaseMetadata.ContainsKey('id')) { 
        $ReleaseMetadata['id'] 
    } else { 
        'No Album ID' 
    }
    
    Process-Artists -AlbumId $albumId -SourceMetadata $ReleaseMetadata -DestinationMetadata $AlbumMetadata -SourceType 'album'
}

# Function to process track variables
function Set-TrackVariables {
    param(
        [hashtable]$AlbumMetadata,
        [hashtable]$TrackMetadata,
        [hashtable]$ReleaseMetadata
    )
    
    $albumId = if ($ReleaseMetadata -and $ReleaseMetadata.ContainsKey('id')) { 
        $ReleaseMetadata['id'] 
    } else { 
        'No Album ID' 
    }
    
    Process-Artists -AlbumId $albumId -SourceMetadata $TrackMetadata -DestinationMetadata $AlbumMetadata -SourceType 'track'
}

# Function to process JSON metadata file
function Process-MetadataFile {
    param(
        [string]$FilePath
    )
    
    if (-not (Test-Path $FilePath)) {
        Write-Error "Metadata file not found: $FilePath"
        return
    }
    
    try {
        $metadata = Get-Content $FilePath -Raw | ConvertFrom-Json -AsHashtable
        $resultMetadata = @{}
        
        # Process album metadata
        if ($metadata.ContainsKey('release')) {
            Set-AlbumVariables -AlbumMetadata $resultMetadata -ReleaseMetadata $metadata['release']
        }
        
        # Process track metadata
        if ($metadata.ContainsKey('tracks')) {
            foreach ($track in $metadata['tracks']) {
                Set-TrackVariables -AlbumMetadata $resultMetadata -TrackMetadata $track -ReleaseMetadata $metadata['release']
            }
        }
        
        return $resultMetadata
    }
    catch {
        Write-Error "Error processing metadata file: $_"
        return $null
    }
}

# Function to export processed metadata
function Export-ProcessedMetadata {
    param(
        [hashtable]$Metadata,
        [string]$OutputPath
    )
    
    try {
        $Metadata | ConvertTo-Json -Depth 10 | Out-File -FilePath $OutputPath -Encoding UTF8
        Write-Host "Processed metadata exported to: $OutputPath" -ForegroundColor Green
    }
    catch {
        Write-Error "Error exporting metadata: $_"
    }
}

# Main execution block
if ($MyInvocation.InvocationName -ne '.') {
    Write-Host "$PLUGIN_NAME v$PLUGIN_VERSION" -ForegroundColor Cyan
    Write-Host "Author: $PLUGIN_AUTHOR" -ForegroundColor Gray
    Write-Host ""
    
    # Example usage
    if ($args.Count -gt 0) {
        $inputFile = $args[0]
        $outputFile = if ($args.Count -gt 1) { $args[1] } else { "processed_metadata.json" }
        
        Write-Host "Processing metadata file: $inputFile" -ForegroundColor Yellow
        $processedMetadata = Process-MetadataFile -FilePath $inputFile
        
        if ($processedMetadata) {
            Export-ProcessedMetadata -Metadata $processedMetadata -OutputPath $outputFile
            
            if ($global:Config.Verbose) {
                Write-Host "`nProcessed Variables:" -ForegroundColor Green
                $processedMetadata.GetEnumerator() | Sort-Object Name | ForEach-Object {
                    Write-Host "  $($_.Key): $($_.Value)" -ForegroundColor White
                }
            }
        }
    } else {
        Write-Host "Usage: .\additional_artists_variables.ps1 <input_metadata.json> [output_file.json]" -ForegroundColor Yellow
        Write-Host "       .\additional_artists_variables.ps1 -MaxGenres 5 -Verbose metadata.json" -ForegroundColor Yellow
    }
}

# Export functions for module usage
Export-ModuleMember -Function Process-Artists, Set-AlbumVariables, Set-TrackVariables, Process-MetadataFile, Export-ProcessedMetadata