MusicDirectory

This module provides a set of methods to manage the Music Directory. The MusicDirectory is derived from musicdb.lib.filesystem.Filesystem.

MusicDirectory Class

class musicdb.mdbapi.musicdirectory.MusicDirectory(config)[source]

This class provides an interface to the Music Directory. The whole class assumes that it is used with an Unicode capable UNIX-style filesystem. It is derived from musicdb.lib.fileprocessing.Fileprocessing.

In comparison to the MusicDBMusic, only the files are on focus, not the music database. Keep in mind that applying some of the methods of this class can harm the connection between the database entries and their associated files.

Parameters

config – MusicDB configuration object

AnalyseAlbumDirectoryName(albumdirname: str) → dict[source]

This method analyses the name of an album directory. If it does not follow the scheme of an album directory name, None gets returned, otherwise the albumname and release year.

The scheme is the following: {releaseyear} - {albumname}.

The return value is a dictionay with the following keys:

release:

An integer with the release year

name:

A string with the album name

Parameters

albumdirname (str) – Directory name of an album without any "/".

Returns

A dictionary with release year and the album name, or None

Example

infos = fs.AnalyseAlbumDirectoryName("2000 - Testalbum")
if infos:
    print(infos["name"])    # 2000
    print(infos["release"]) # Testalbum
AnalysePath(musicpath)[source]

This method analyses a path to an artist, and album, a song or video and extracts all the information encoded in the path. For songs, path must consist of three parts: The artist directory, the album directory and the song file. For alums and videos only two parts are expected: The artist directory and the video file. For artist only one part.

A valid path has one the following structures:

  • {artistname}/{albumrelease} - {albumname}/{songnumber} {songname}.{extension}

  • {artistname}/{albumrelease} - {albumname}/{cdnumber}-{songnumber} {songname}.{extension}

  • {artistname}/{videorelease} - {videoname}.{extension}

  • {artistname}/{albumrelease} - {albumname}

  • {artistname}

The returned dictionary holds all the extracted information from the scheme listed above. The following entries exists but may be None depending if the path addresses a video or song.

  • artist

  • release

  • album

  • song

  • video

  • songnumber

  • cdnumber

  • extension

In case there is no cdnumber specified for a song, this entry is 1. The names can have all printable Unicode characters and of cause spaces.

If an error occurs because the path does not follow the scheme, None gets returned. This method also checks if the file or directory exists!

The path must also address a file or directory inside the music directory. Anyway the path can be relative or absolute.

Parameters

musicpath (str/Path) – A path of a song including artist and album directory or a video including the artists directory.

Returns

On success, a dictionary with information about the artist, album and song or video is returned. Otherwise None gets returned.

AnalyseSongFileName(songfilename: str) → dict[source]

This method analyses the name of a song file. If it does not follow the scheme, None gets returned, otherwise all information encoded in the name as dictionary.

The scheme is the following: {songnumber} {songname}.{extension} or {cdnumber}-{songnumber} {songname}.{extension}

The return value is a dictionary with the following keys:

cdnumber:

CD number as integer or 1 if not given in the name

number:

Number of the song as integer

name:

A string with the song name

extension:

file extension as string

Parameters

songfilename (str) – File name of an song without any "/".

Returns

A dictionary on success, otherwise None

Example

infos = fs.AnalyseSongFileName("05 This is a Song.mp3")
if infos:
    print(infos["cdnumber"])    # 1
    print(infos["number"])      # 5
    print(infos["name"])        # This is a Song
    print(infos["extension"])   # mp3
AnalyseVideoFileName(videofilename: str) → dict[source]

This method analyses the name of a video file. Only the file name is expected, not a whole path! If it does not follow the scheme, None gets returned, otherwise all information encoded in the name as dictionary.

The scheme is the following: {release} - {videoname}.{extension}

The return value is a dictionary with the following keys:

release:

Release year as integer

name:

A string with the video name

extension:

file extension as string

Parameters

videofilename (str) – File name of an video without any "/".

Returns

A dictionary on success, otherwise None

Example

infos = fs.AnalyseVideoFileName("2000 - This is a Video.m4v")
if infos:
    print(infos["release"])     # 2000
    print(infos["name"])        # "This is a Video"
    print(infos["extension"])   # "m4v"
EstimateContentTypeByPath(path)[source]

This method tries to figure out if the path addresses an Artist, Album, Song or Video by analyzing the path. If is not checked if the path fulfills the Music Naming Scheme (See: Music Naming Scheme).

The path must be relative. It is not checked if the file or directory exists. The result is just a guess an must be checked in detail for further processing. For example with TryAnalysePathFor().

Parameters

path (str) – Possible relative path for an Artist, Album, Song or Video

Returns

A string "artist", "album", "song", "video" or None if none can be guessed.

EvaluateAlbumDirectory(albumpath)[source]

This method checks if a directory path is a valid album directory. Despite TryAnalysePath() and AnalyseAlbumDirectoryName() this method does not care about the naming scheme. It checks the actual content and directory inside the file system. A valid album directory must fulfill the following criteria:

  • It must be an existing directory

  • MusicDB must have read and write access to this directory

  • The directory must only contain files, no sub directories

  • All files inside the directory must be readable and writable

  • At least one file inside the directory must be a song file

Parameters

albumpath (str) – Path to the album to check

Returns

True if the directory is a valid album directory. Otherwise ``False.

EvaluateArtistDirectory(artistpath)[source]

This method checks if a directory is a valid artist directory. In contrast to TryAnalysePath() this method does not care about the naming scheme. It checks the actual content, directory and sub directories inside the file system.

A valid artist directory must fulfill the following criteria:

  • It must be an existing directory

  • MusicDB must have read and write access to this directory

  • All sub directories and files must be writable

  • There must be at least one valid album directory (Checked via EvaluateAlbumDirectory() or a video file

Parameters

artistpath (str) – Path to the artist to check

Returns

True if the directory is a valid artist directory. Otherwise ``False.

EvaluateMusicFile(musicpath)[source]

This method checks if a file is a valid music file. In contrast to TryAnalysePath() this method does not care about the naming scheme. It checks the actual content inside the file system.

A valid music file must fulfill the following criteria:

  • It must be an existing file

  • MusicDB must have read and write access to this file

Parameters

musicpath (str) – Path to the music file to check

Returns

True if the file is a valid music file. Otherwise ``False.

FixAttributes(path: Union[str, pathlib.Path])[source]

This method changes the access permissions and ownership of a file or directory. Only the addressed files or directory’s permissions gets changed, not their parents.

  • File permissions: rw-rw-r--

  • Directory permissions: rwxrwxr-x

To update the access permissions the method musicdb.lib.filesystem.Filesystem.SetAttributes() is used.

Parameters

path (str/Path) – Path to an artist, album or song, relative to the music directory

Returns

True on success, otherwise False

Raises

ValueError – if path is neither a file nor a directory.

RenameAlbumDirectory(oldpath, newpath)[source]

Renames an album directory. In general it is not checked if the new path fulfills the Music Naming Scheme (See Music Naming Scheme). The position of the album should be plausible anyway. So it must be placed inside an artist directory.

The complete path, relative to the Music Directory must be given. Anyway, the artist directories must not be different. Only the album directory name can be different.

If the old path does not address a directory, the Method returns False. If the new path does address an already existing file or directory, the method returns False as well. No files will be overwritten.

Parameters

  • oldpath (str) – Path to the directory that shall be renamed

  • newpath (str) – New name of the file

Returns

True on success, otherwise False

Example

// Will succeed
oldpath = "Artist/2021 - Old Album Name"
newpath = "Artist/2021 - New Album Name"
musicdirectory.RenameAlbumDirectory(oldpath, newpath)

// Will succeed even if the album name does not fulfill the naming requirements
oldpath = "Artist/Old Album Name"
newpath = "Artist/New Album Name"
musicdirectory.RenameAlbumDirectory(oldpath, newpath)

// Will fail because artist name changed as well.
oldpath = "Artist/Old Album Name"
newpath = "New Artist/2021 - New Album Name"
musicdirectory.RenameAlbumDirectory(oldpath, newpath)
RenameArtistDirectory(oldpath, newpath)[source]

Renames an artist directory. In general it is not checked if the new path fulfills the Music Naming Scheme (See Music Naming Scheme). The position of the artist should be plausible anyway.

The complete path, relative to the Music Directory must be given. Anyway, the artist directories must not be different. Only the album directory name can be different. So it must be placed inside the music directory and not being a sub directory.

If the old path does not address a directory, the Method returns False. If the new path does address an already existing file or directory, the method returns False as well. No files will be overwritten.

Parameters

  • oldpath (str) – Path to the directory that shall be renamed

  • newpath (str) – New name of the file

Returns

True on success, otherwise False

Example

oldpath = "Old Artist"
newpath = "New Artist"
musicdirectory.RenameArtistDirectory(oldpath, newpath)
RenameSongFile(oldpath, newpath)[source]

Renames a song inside the Music Directory. In general it is not checked if the new path fulfills the Music Naming Scheme (See Music Naming Scheme). The position of the file should be plausible anyway. So a song file should be inside a artist/album/-directory.

The complete path, relative to the Music Directory must be given. The artist and album directories must not be different. Only the file name can be different.

If the old path does not address a file, the Method returns False. If the new path does address an already existing file, the method returns False as well. No files will be overwritten.

Parameters

  • oldpath (str) – Path to the file that shall be renamed

  • newpath (str) – New name of the file

Returns

True on success, otherwise False

Example

// Will succeed
oldpath = "Artist/2021 - Album Name/01 old file name.mp3"
newpath = "Artist/2021 - Album Name/01 new file name.mp3"
musicdirectory.RenameSongFile(oldpath, newpath)

// Will succeed even when the song name does not fulfill the naming scheme for song files
oldpath = "Artist/2021 - Album Name/old file name.mp3"
newpath = "Artist/2021 - Album Name/new file name.mp3"
musicdirectory.RenameSongFile(oldpath, newpath)

// Will fail if because album name changed as well
oldpath = "Artist/Old Album Name/Old Song Name.flac",
newpath = "Artist/2021 - New Album Name/01 New Song Name.flac"
musicdirectory.RenameSongFile(oldpath, newpath)
RenameVideoFile(oldpath, newpath)[source]

Renames a video inside the Music Directory. In general it is not checked if the new path fulfills the Music Naming Scheme (See Music Naming Scheme). The position of the file should be plausible anyway. So a song file should be inside a artist-directory.

The complete path, relative to the Music Directory must be given. The artist and album directories must not be different. Only the file name can be different.

If the old path does not address a file, the Method returns False. If the new path does address an already existing file, the method returns False as well. No files will be overwritten.

Parameters

  • oldpath (str) – Path to the file that shall be renamed

  • newpath (str) – New name of the file

Returns

True on success, otherwise False

Example

// Will succeed
oldpath = "Artist/2021 - old file name.m4v"
newpath = "Artist/2021 - new file name.m4v"
musicdirectory.RenameVideoFile(oldpath, newpath)

// Will succeed even when the video name does not fulfill the naming scheme for video files
oldpath = "Artist/old file name.m4v"
newpath = "Artist/new file name.m4v"
musicdirectory.RenameVideoFile(oldpath, newpath)

// Will fail if because artist name changed as well
oldpath = "Artist/Old Video Name.m4v",
newpath = "Different Artist/2020 - New Video Name.m4v"
musicdirectory.RenameVideoFile(oldpath, newpath)
TryAnalysePathFor(target='all', path=None)[source]

This method checks if a path is valid for a specific target.

The check is done in the following steps:

  1. Get all song paths

  2. Apply an information extraction on all found song paths using AnalysePath()

This guarantees, that all files are valid to process with MusicDB.

Parameters

  • target (str) – Optional, default value is "all". One of the following targets: "all", "artist", "album" or "song"

  • path (str) – Optional, default value is None. Path to an artist, album or song. If target is "all", path can be None.

Returns

True If the path is valid for the given target. Otherwise False gets returned.

Raises

ValueError – when target is not "all", "artist", "album" or "song"