Skip to content

feat: add artist_initials, artists, explicit, release template variables#301

Open
np3ir wants to merge 5 commits into
glomatico:mainfrom
np3ir:feat/artist-initials-release-type-explicit-separator
Open

feat: add artist_initials, artists, explicit, release template variables#301
np3ir wants to merge 5 commits into
glomatico:mainfrom
np3ir:feat/artist-initials-release-type-explicit-separator

Conversation

@np3ir
Copy link
Copy Markdown

@np3ir np3ir commented May 12, 2026

Summary

Adds four new template variables and one config option to improve filename/folder customization:

  • {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. Splits the combined artistName on " & " and ", " and rejoins with artist_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 the compilation flag and trackCount.
  • 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 of output_path.
  • use_fullwidth_replacements (config/CLI, default true) — replace forbidden Windows filename characters with Unicode full-width equivalents (, , , etc.) instead of underscores, producing cleaner filenames where punctuation is visually preserved.

Example config

output_path = Z:/Music
music_video_output_path = G:/Videos
artist_separator = " / "
use_fullwidth_replacements = true
album_folder_template = {artist_initials}/{album_artist}/({date:%Y}) {album} ({release})
single_disc_file_template = {track:02d}. {artists} - {title}{explicit}

produces:

Z:/Music/A/Alex Cuba/(2020) Solo Mía (SINGLE)/01. Alex Cuba / Leonel García - Amor Secreto (explicit).m4a
G:/Videos/A/Alex Cuba/(2020) Solo Mía (SINGLE)/01. Alex Cuba / Leonel García - Solo Mía (explicit).mp4

Changes

  • gamdl/interface/types.pyMediaTags.release_type: str = None
  • gamdl/interface/song.py — populate release_type in get_tags()
  • gamdl/interface/music_video.py — populate release_type in get_tags()
  • gamdl/downloader/constants.pyFULLWIDTH_REPLACEMENTS map
  • gamdl/downloader/base.py — all new params, helper methods, formatter vars

Test plan

  • Download a single-artist album — {artist_initials} = correct letter, {release} = ALBUM
  • Download a single-track release — {release} = SINGLE
  • Download a compilation — {release} = COMPILATION
  • Download a multi-artist track — {artists} splits and rejoins with configured separator
  • Explicit track — {explicit} = "(explicit)", clean track — {explicit} = ""
  • Album name with : — produces not _
  • Music video URL with music_video_output_path set — goes to separate directory
  • Default artist_separator = " & " — existing templates unchanged

np3ir and others added 5 commits May 12, 2026 03:24
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>
@
@
fix: strip surrounding quotes from artist_separator config value

configparser strips leading/trailing whitespace but preserves quote
characters. A config value like `artist_separator = " / "` is read as
`" / "` (with quotes). Strip them so the actual separator is ` / `.
@
@
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.
@
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant