While I love the XDG directory specification, I've seen it cause a lot of trouble in other open-source projects due to backward compatibility issues. I expect that anybody who sets $XDG_MUSIC_DIR to something other than $HOME/Music will not have a $HOME/Music directory. There are two options here:

1. Immediately use the proposed directory order. This could potentially break things for a very, very small proportion of users.
2. Release a minor version which shows a warning for users for whom things would break, and actually adopt the proposed directory order in the next minor version.
   I'm happy to try implementing either case but I want input from maintainers first.

Those users who have set this variable will use a non-standard configuration anyways, so I would not be concerned with backwards compatibility - that is only a problem if the fallback is not reasonable or the config options are not properly prioritised.

However, the right directory to use for xdg is xdg-user-dir MUSIC - I have never seen a $XDG_MUSIC_DIR variable. I think you are referencing https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html while the right one is https://www.freedesktop.org/wiki/Software/xdg-user-dirs/

Those users who have set this variable will use a non-standard configuration anyways, so I would not be concerned with backwards compatibility - that is only a problem if the fallback is not reasonable or the config options are not properly prioritised.

However, the right directory to use for xdg is xdg-user-dir MUSIC - I have never seen a $XDG_MUSIC_DIR variable. I think you are referencing https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html while the right one is https://www.freedesktop.org/wiki/Software/xdg-user-dirs/

XDG_MUSIC_DIR is a part of the standard.
man 5 user-dirs.dirs

DESCRIPTION
       The $HOME/.config/user-dirs.dirs file is a text file that contains the user-specific values for
       the XDG user dirs. It is created and updated by the xdg-user-dirs-update command.

       This file contains lines of the form

           XDG_NAME_DIR=VALUE

       The following names are recognised:

           VALUE must be of the form "$HOME/Path" or "/Path".

           Lines beginning with a # character are ignored.

           The format of user-dirs.dirs is designed to allow direct sourcing of this file in shell
           scripts.

cat /etc/xdg/user-dirs.defaults

# Default settings for user directories
#
# The values are relative pathnames from the home directory and
# will be translated on a per-path-element basis into the users locale
DESKTOP=Desktop
DOWNLOAD=Downloads
TEMPLATES=Templates
PUBLICSHARE=Public
DOCUMENTS=Documents
MUSIC=Music
PICTURES=Pictures
VIDEOS=Videos
# Another alternative is:
#MUSIC=Documents/Music
#PICTURES=Documents/Pictures
#VIDEOS=Documents/Videos

I expect that anybody who sets $XDG_MUSIC_DIR to something other than $HOME/Music will not have a $HOME/Music directory. There are two options here:

If they set XDG_MUSIC_DIR to something other than $HOME/Music then under the preference order I recommended, it would not matter as XDG_MUSIC_DIR would be used and $HOME/Music would never be considered.

XDG_MUSIC_DIR is a part of the standard.

yes, but by default it is not an environment variable unlike the XDG base dirs, as explained in the spec too:

❯ xdg-user-dir MUSIC
/home/janek/data/4-media/music
❯ echo $XDG_MUSIC_DIR

just to keep in mind when implementing

Oh that makes sense. Thanks for the clarification!

If they set XDG_MUSIC_DIR to something other than $HOME/Music then under the preference order I recommended, it would not matter as XDG_MUSIC_DIR would be used and $HOME/Music would never be considered.

@sebastianrasor to be more explicit, here's an example:

A user has set XDG_MUSIC_DIR (through xdg-user-dir, thanks @xeruf) to $HOME/AllTheMusic, and uses $HOME/Music for beets without explicitly putting it in the beets config. This may happen, for example, if the user has some untagged music they don't want beets messing with, and they didn't know that they could change the directory beets uses. Now, with this change, beets will implicitly start using $HOME/AllTheMusic, leading to some possibly confusing errors. I agree that it's far-fetched, but I wanted it at least noted before this feature goes through (and to be clear, I want this feature).

I haven't been able to find any utility to parse user-dirs.dirs(5), so I'll probably write a small utility module to parse it into a dict[str, pathlib.Path]. The only other change would be to change Library.__init__'s default value for directory.

The $HOME/.config/user-dirs.dirs file is a text file that [...]

Note the user-dirs.dirs(5) manpage is wrong/incomplete on the file location.

The xdg-user-dir shell script reads from $XDG_CONFIG_HOME/user-dirs.dirs (falling back to ~/.config/user-dirs.dirs if $XDG_CONFIG_HOME is undefined). Please do the same in your implementation.