feat: add artist_initials, artists, explicit, release template variables#301
Open
np3ir wants to merge 5 commits into
Open
feat: add artist_initials, artists, explicit, release template variables#301np3ir wants to merge 5 commits into
np3ir wants to merge 5 commits into
Conversation
feat: add artist_initials, artists, explicit, release template variables
Adds four new template variables and one config option:
- {artist_initials}: first letter of album_artist (ASCII-normalized, # for
non-alpha). Useful for grouping artists into letter buckets (A/, B/, ...).
- {artists}: artist string with configurable separator (see artist_separator).
Splits the combined artistName on " & " and ", " and rejoins with the
configured separator. The original {artist} is unchanged.
- {explicit}: "(explicit)" when the track is rated explicit, empty string
otherwise. Allows appending the marker to filenames.
- {release}: album release type — "ALBUM", "SINGLE", or "COMPILATION".
Derived from the compilation flag and track count. Allows distinguishing
release types in folder names.
- artist_separator (config / CLI): separator used when building {artists}
and {album_artist} from multi-artist strings. Default: " & " (backward
compatible). Set to " / " to match tools like OrpheusDL.
MediaTags gains a release_type field populated by AppleMusicSongInterface
and AppleMusicMusicVideoInterface.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@
feat: add music_video_output_path for separate video output directory When music_video_output_path is set, music videos are saved there instead of output_path. Songs and other media still use output_path. Allows routing audio and video to different library roots without separate config files. Example config: output_path = Z:/ music_video_output_path = G:/Artistas @
feat: add use_fullwidth_replacements option for Unicode char substitution When use_fullwidth_replacements=True (default), forbidden Windows filename characters are replaced with their Unicode full-width equivalents instead of underscores: : → : * → * ? → ? " → " / → / \ → \ < → < > → > | → | ; → ; This matches the behaviour of tools like OrpheusDL and produces cleaner filenames where punctuation is visually preserved. Set use_fullwidth_replacements = false to restore the previous _ behaviour. @
feat: add artist_views config and album deduplication for artist downloads - artist_views: configurable views sent to the artist API endpoint. Default keeps current behaviour. Set to "full-albums,singles" to skip compilations and avoid duplicate folders when Apple Music catalogues the same compilation under multiple IDs/years across storefronts. - artist_deduplicate_albums (default true): skip albums whose normalised name has already been seen in the current artist download session. Prevents downloading "The Best of Me" (1987), "The Best of Me" (1991), "The Best of Me" (2002)... as separate folders when they are effectively the same compilation with different regional IDs. @
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds four new template variables and one config option to improve filename/folder customization:
{artist_initials}— first letter ofalbum_artist(ASCII-normalized,#for non-alpha). Useful for grouping artists into letter buckets (A/,B/, ...).{artists}— artist string with configurable separator. Splits the combinedartistNameon" & "and", "and rejoins withartist_separator. The original{artist}is unchanged for backward compatibility.{explicit}—"(explicit)"when the track is rated explicit, empty string otherwise.{release}— album release type:"ALBUM","SINGLE", or"COMPILATION". Derived from thecompilationflag andtrackCount.artist_separator(config/CLI) — separator used for{artists}. Default:" & "(backward compatible).music_video_output_path(config/CLI) — separate output directory for music videos. When set, music videos go here instead ofoutput_path.use_fullwidth_replacements(config/CLI, defaulttrue) — replace forbidden Windows filename characters with Unicode full-width equivalents (:,*,?, etc.) instead of underscores, producing cleaner filenames where punctuation is visually preserved.Example config
produces:
Changes
gamdl/interface/types.py—MediaTags.release_type: str = Nonegamdl/interface/song.py— populaterelease_typeinget_tags()gamdl/interface/music_video.py— populaterelease_typeinget_tags()gamdl/downloader/constants.py—FULLWIDTH_REPLACEMENTSmapgamdl/downloader/base.py— all new params, helper methods, formatter varsTest plan
{artist_initials}= correct letter,{release}=ALBUM{release}=SINGLE{release}=COMPILATION{artists}splits and rejoins with configured separator{explicit}="(explicit)", clean track —{explicit}="":— produces:not_music_video_output_pathset — goes to separate directoryartist_separator=" & "— existing templates unchanged