path format

replace:
    #fake comment and fake tab options
    '\#.*zxc': ''
    #fake tab (4+ spaces) to have tabs in paths. will still match to any path that really should have 4+ spaces in it. Ex. an album called "Trouble    Maker"
    ' {4,}': ''

paths:
    #regex to match all items. (avoid having to separately define compilations and singletons.)
    title::.*: "$i_test %if{\
                   $alb_artist,\
                       %the{\
                             $alb_artist\
                            } - ,\
                   No Artist - \
                 }\
    %if{\
      $alb_promo_boot,\
      $alb_promo_boot%if{\
                          $alb_exotic_type,\
                          #add literal comma and space if promo_boot and exotic_type exist for the same album. zxc\
                          #for example Promo comma Spoken Word zxc\
                          $, , - \
                        }\
       }\
    %if{\
    $alb_exotic_type,\
    $alb_exotic_type - \
        }\
    $alb_orig_year - \
    $alb_title\
    %aunique{\
              album $alb_orig_year_mm_dd albumartist albumstatus albumtype,\
              albumdisambig country label catalognum,\
              ()\
            }\
    $i_cust_catalog%if{\
                                   $alb_subset_bitrate, \
                                   [$alb_subset_bitrate]\
                      }\
    /%if{\
         $i_disc_layer,\
         $i_disc_layer-\
        }\
    %if{\
        $track,\
        $i_track. ,\
        [no track number]. \
        }\
    %if{\
        $title,\
        $title,\
        [unknown]\
        }"

album_fields:

    alb_promo_boot: |
        #official, promo, bootleg, and pseudo-release. we only note the middle two. https://musicbrainz.org/doc/Release#Status
        if 'Promo' in albumstatus:
            return 'Promo'
        elif 'Bootleg' in albumstatus:
            return 'Bootleg'
        else:
            return ''
    alb_exotic_type: |
        #no special noting of albums, EPs, and soundtracks
        if albumtype in {'album', 'ep', 'soundtrack'}:
           return ''
        #special case for proper spacing and caps
        elif 'spokenword' in albumtype:
           return 'Spoken Word'
        else:
           return str.title(albumtype)
    alb_subset_bitrate: |
        #return bitrate information for albums <150kbps.
        #do nothing for higher-bitrate albums, because they are assumed to be perceptually lossless.
        br_threshhold = 150
        max_tracks_to_check = 10
        def sample_tracks(tracks):
            #reproducible randomness for debugging. should be excluded for optimal randomness from album to album.
            #otherwise, any album with same number of tracks will get same sample of track numbers, I think
            from random import seed, sample
            seed(25)
            num_items = len(tracks)
            sample_size = min(max_tracks_to_check, num_items)
            test_tracks = sample(tracks, sample_size)
            return(test_tracks)
        test_tracks = sample_tracks(items)
        sample_size = len(test_tracks)
        total = 0
        for item in test_tracks:
            total += item.bitrate
        album_br_bits_ps = total / sample_size
        # music bitrates are base 10:
        # https://hydrogenaud.io/index.php/topic,12633.0.html
        album_br_kbps = album_br_bits_ps / 1000
        if album_br_kbps > br_threshhold:
            out_text = ''
        else:
            #return Opus, MP3, "Mixed", etc.
            #uses same test_tracks from earlier sample
            alb_format = set()
            for item in test_tracks[0:sample_size]:
                alb_format.add(item.format)
            if len(alb_format) != 1:
                alb_format = 'Mixed'
            else:
                alb_format = alb_format.pop()
            out_text = str(int(album_br_kbps)) + 'kbps ' + str(alb_format)
        return out_text
    alb_title: |
        #convert long allcaps titles to title case, while leaving other titles alone
        allowed_length = 3
        allowed_allcaps_artists = ['573fd3e2-3f61-4329-a6c1-89e20620b0b9']
        if album.isupper and len(album) > allowed_length:
            if mb_albumartistid not in allowed_allcaps_artists:
                from titlecase import titlecase
                return titlecase(album)
        if len(album) < 1:
            return "[untitled]"
        return album
    alb_artist: |
        VA_STR = "Various Artists"
        if albumartist:
            return albumartist
        else:
            # the album probably has no MBid
            # return VA_STR if multiple artists are found on the album
            my_artists = set()
            for item in items:
                my_artists.add(item.artist)
                if len(my_artists) > 1:
                    return VA_STR
            # every artist is the same
            return my_artists.pop()

item_fields:

    i_track: |
        # untested
        if not track:
            return None
        # hotfix for beets' hardcoded 2-digit track numbers
        # https://github.com/beetbox/beets/issues/3352
        str_track = str(track)
        # pad based on length of highest track number (per disc).
        # may interact with per_disc_numbering, not sure
        pad_length = len(str(tracktotal))
        if pad_length < 2:
            pad_length = 2
        return str_track.zfill(pad_length)

    i_disc_layer: |
        #do nothing for single-disc releases
        if disctotal > 1:
            if disc != '':
                str_disc = str(disc)
                #pad based on length of highest disc number.
                #ex. if total discs = 2 digits, pad 1 zero for discs 1-9 (01-09)
                legth_to_pad_to = len(str(disctotal))
                return str_disc.zfill(legth_to_pad_to)
        return ''
    i_condition: |
        #set as a flex attribute(?) elsewhere
        return ''
    i_cust_catalog: |
        #omit uninteresting formats
        #these formats are bit-identical to CD
        snake_oil_formats = ['Blu-spec CD', 'SHM-CD', 'HQCD']
        media_types_to_omit = snake_oil_formats + ['CD', 'CD-R', 'Enhanced CD', 'CDDA', 'Digital Media', '']

        def item_cust_media():
            #see https://musicbrainz.org/doc/Release/Format
            if media in media_types_to_omit:
                return ''
            #combine hybrid SACD with SACD, see https://en.wikipedia.org/wiki/Super_Audio_CD#Technology
            elif 'SACD' in media:
                return 'SACD'
            #combine all vinyl types into "Vinyl"
            elif 'Vinyl' in media:
                #https://en.wikipedia.org/wiki/VinylDisc
                if media == 'VinylDisc':
                    return 'VinylDisc'
                else:
                    return 'Vinyl'
            elif "USB" in media:
                return 'USB'
            elif media == 'HD-DVD':
                return 'HD-DVD'
            # note: DualDisc contains a DVD side and a CD side.
            elif media == "DualDisc":
                return "DVD"
            elif 'DVD' in media:
                return 'DVD'
            else:
                return media

        def reissue():
            if year > original_year:
                if original_year > 0:
                    return str(year)
            return ''
        # condition = custom attribute to note (mostly) vinyl skips
        # and other seriously noticable artifacts.
        result = reissue() + ' ' + item_cust_media() # + i_condition()
        result = result.strip(' ')
        if result != '':
            return ' (' + result + ')'
        return result