Music Management¶

This module is the core of the music handling of MusicDB. It is the interface between the music and its entries in the database (musicdb.lib.db.musicdb).

MusicDBMusic Class¶

class musicdb.mdbapi.music.MusicDBMusic(config, database)[source]¶

This class provides tools to manage the music database and its files. The main purpose is to act as interface between the database and the files associated to the entries inside the database.

In comparison to the MusicDirectory a link between a file and the database is assumed.

This class supports the following features

File management

FindLostPaths(): Check if all paths in the songs, albums and artists table are valid.

FindNewPaths(): Check if there are new songs, albums or artists in the music collection that are not in the database.

FindNewSongs():

Database management

AddArtist(), AddAlbum(), AddSong(), AddVideo(): Adds a new artist, album, song video to the database

UpdateArtist(), UpdateAlbum(), UpdateSong(): Updates a artist, album or song path in the database

RemoveArtist(), RemoveAlbum(), RemoveSong(): Removes a artist, album or song from the database

Add information into the database

AddLyricsFromFile(): Read lyrics from the meta data of a song file into the database

UpdateChecksum(): Calculates and adds the checksum of a song file into the database

Other

Parameters

config – MusicDB configuration object
database – MusicDB database

Raises

TypeError – when config or database not of type MusicDBConfig or MusicDatabase

AddAlbum(albumpath, artistid=None)[source]¶

This method adds an album to the database in the following steps:

Check if the album already exists in the database

Get all songs of the album by getting all files inside the directory except those on the ignoresongs-list.

Load the metadata from one of those songs using musicdb.lib.metatags.MetaTags.GetAllMetadata()

Analyze the path of one of the song using AnalysePath()

If artistid is not given as parameter, it gets read from the database identifying the artist by its path.

Get modification date using GetModificationDate()

Set file attributes and ownership using FixAttributes()

Create new entry for the new album in the database and get the default values

Add each song of the album to the database by calling AddSong()

Write all collected information of the album into the database

If adding the songs to the database raises an exception, that song gets skipped. The numofsongs value for the album is the number of actual existing songs for this album in the database. It is save to add the failed song later by using the AddSong() method.

Parameters

albumpath (str) – Absolute path, or path relative to the music root directory, to the album that shall be added to the database.
artistid (int) – Optional, default value is None. The ID of the artist this album belongs to.

Returns

None

Raises

ValueError – If the path does not address a directory
ValueError – If album already exists in the database
AssertionError – If there is no artist for this album in the database
AssertionError – If loading metadata from one of the song files failed

AddArtist(artistpath)[source]¶

The AddArtist method adds a new artist to the database. This is done in the following steps:

Check if the artist path is inside the music root directory

Check if the artist is already in the database

Extract the artist name from the path

Set file attributes and ownership using FixAttributes()

Add artist to database

Call AddAlbum() for all subdirectories of the artistpath. (Except for the directory-names in the ignorealbum list)

Parameters

artistpath (str) – Absolute or relative (to the music directory) path to the artist that shall be added to the database.

Returns

None

Raises

ValueError – If the path does not address a directory
ValueError – If artist is already in the database

AddLyricsFromFile(songpath)[source]¶

This method can be used to add lyrics from the file of a song into the database. It tries to load the metadata from the song file. If that succeeds, the song entry gets loaded from the database and the lyrics state of that entry gets checked. The lyrics from the file gets stored in the song database in case the current lyrics state is empty. Otherwise the files lyrics get rejected.

This method returns True when new lyrics were added. If there already exist lyrics False gets returned.

Parameters: songpath (str) – Absolute song path, or relative to the music root directory.
Returns: True on success, otherwise False

AddSong(songpath, artistid=None, albumid=None)[source]¶

This method adds a song to the MusicDB database. To do so, the following steps were done:

Check if the song already exists in the database

Load the metadata from the song using musicdb.lib.metatags.MetaTags.GetAllMetadata()

Analyze the path of one of the song using AnalysePath()

If artistid is not given as parameter, it gets read from the database identifying the artist by its path.

If albumid is not given as parameter, it gets read from the database identifying the album by its path.

Set file attributes and ownership using FixAttributes()

Add song to database

If the parameter albumid was None the numofsongs entry of the determined album gets incremented

If there are lyrics in the song file, they get also inserted into the database

In case the album ID is set, this method assumes that its database entry gets managed by the AddAlbum() method. So, nothing will be changed regarding the album. If album ID was None, this method also updates the album-entry, namely the numofsongs value gets incremented.

Parameters

songpath (str) – Absolute path, or path relative to the music root directory, to the song that shall be added to the database.
artistid (int) – Optional, default value is None. The ID of the artist this song belongs to.
albumid (int) – Optional, default value is None. The ID of the album this song belongs to.

Returns

None

Raises

ValueError – If song already exists in the database
AssertionError – If analyzing the path fails
AssertionError – If there is no album for this song in the database

AddVideo(videopath, artistid=None)[source]¶

This method adds a video to the MusicDB database. To do so, the following steps were done:

Check if the video already exists in the database

Load the metadata from the video using musicdb.lib.metatags.MetaTags.GetAllMetadata()

Analyze the path of one of the video using AnalysePath()

If artistid is not given as parameter, it gets read from the database identifying the artist by its path.

Set file attributes and ownership using FixAttributes()

Add video to database

This method assumes that the artist the video belongs to exists in the database. If not, an AssertionError exception gets raised.

Parameters

videopath (str) – Absolute path, or path relative to the music root directory, to the video that shall be added to the database.
artistid (int) – Optional, default value is None. The ID of the artist this video belongs to.

Returns

True on success, otherwise False (or it raises an exception)

Raises

ValueError – If video already exists in the database
AssertionError – If analyzing the path fails
AssertionError – If artist does not exists in the database
AssertionError – If adding the video to the database fails

ChangeAlbumArtist(albumid, newartist)[source]¶

This method changes the artist associated to an album. It is expected that the album addressed by its album ID exists in the database as well as in the file system.

If newartist is an integer, it is assumed to be an existing artist (existing in the database and the file system).

If newartist is a string, it is assumed that this string is the name, and so the directory of the new artist. In this case, a new artist entry will be created via CreateNewArtist() if it does not exist in the database. If it also does not exist in the Music Directory, a new artist directory will be created as well.

The album directory will be moved into the new artist directory and all paths of the album and its songs will be updated. If the album directory already is inside the new artist directory this is also fine. In this case it is important that the album directory name is still the same! Otherwise the process gets canceled and False returned. Then only the database entry will be updated. This situation can happen if the user renamed the artist directory with the album sub-directory inside.

Parameters

albumid (int) – ID of the album that shall be associated to a new artist.
newartist (int/str) – Artist ID if of type int or artist name if of type str.

Returns

True on success, otherwise False

Raises

TypeError – If albumid is not an integer or newartist is not an integer or a string
ValueError – If albumid does not address an existing database entry

Examples

music.ChangeAlbumArtist(albumid_a, 42)
music.ChangeAlbumArtist(albumid_b, "New Artist")

CreateNewArtist(name)[source]¶

This method creates a new Artist with the name name.

If there is no directory with the same name in the music root directory, a new directory will be created. When creating the directory fails, so that there exists no directory with the artist name, None will be returned.

If there is already an artist with the same name existing in the database, its database entry will be returned. If there the artist is unknown, a new entry will be created as well. The new entry will be returned.

Parameters: name (str) – Name of the new artist.
Returns: The artist entry, or None on error.

FindLostPaths()[source]¶

This method checks all artist, album song and video entries if the paths to their related directories and files are still valid. Entries with invalid paths gets returned in as a list inside a dictionary.

Returns: "artists", "albums", "songs" and "videos".
Return type: A dictionary with 4 entries

FindNewPaths()[source]¶

This method searches inside the music directory for valid artist, album song and video paths. If those paths are not in the database, they will be returned. So this method returns four lists: artist-, album-, song-, and video- paths. Each representing an artist, album, song or video that is not known by the database yet. Files and directories in the configured ignore-list will be ignored.

If a new directory was found, the subdirectories will also be added! So for a new album, the new songs are explicit added as well. There is a special list called "filteredsongs" that is a subset of the songs list, only listing new songs of known albums. So if you rename a song inside an album that is imported in the database, this song gets listed in the "songs" and "filteredsongs" list. Songs inside a new album directory are only listed in the "songs" list.

All directories are checked if they are valid album or artist directories. This does not address their naming scheme which might be violated. It is checked via musicdb.mdbapi.musicdirectory.MusicDirectory.EvaluateArtistDirectory() and musicdb.mdbapi.musicdirectory.MusicDirectory.EvaluateAlbumDirectory() if MusicDB has write access to the content of those directories and if they fulfill certain criteria.

Furthermore this method is error tolerant. This means, if in the database has an invalid entry, it does not lead to errors. For example, if an album path gets renamed, this path will be returned. It does not lead to an error that the old path is still in the database.

Returns: "artists", "albums", "songs", "filteredsongs" and "videos". Each a list of paths that are valid but unknown by the database. Empty lists if there is no valid entry.
Return type: A dictionary with 5 entries

FindNewSongs(albumpath: str) → list[source]¶

This method searches inside a given album path for new songs. The album part can address an album that is known by the MusicDB, but it can also be an unknown one.

The songs are filtered by the configured ignore list (see MusicDB Configuration).

Songs that can not be managed by MusicDB are also filtered out. The files are checked via musicdb.mdbapi.musicdirectory.MusicDirectory.EvaluateMusicFile().

Furthermore the songs are filtered by their extension. Only the following files are considered: .aac, .m4a, .mp3, .flac

If the song path in already known (can be found in the database), then the song is ignored as well.

Parameters: albumpath (str) – path to an album that may have new/unknown songs. The path must be relative to the music directory.
Returns: A list of new, unknown song paths. If no new songs have be found, an empty list gets returned.

RemoveAlbum(albumid)[source]¶

This method removes an album from the database. The files gets not touched, and so it does not matter if they even exists. All related information will also be removed.

Warning

For all songs in this album, the RemoveSong() method gets called!

Warning

This is not a “set the deleted flag” method. The data gets actually removed from the database. No recovery possible!

Parameters: albumid (int) – ID of the album that shall be removed from database
Returns: None

RemoveArtist(artistid)[source]¶

This method removes an artist from the database. The files gets not touched, and so it does not matter if they even exists. All related information will also be removed.

Warning

For all artists albums, the RemoveAlbum() method gets called!

Warning

This is not a “set the deleted flag” method. The data gets actually removed from the database. No recovery possible!

Parameters: artistid (int) – ID of the artist that shall be removed from database
Returns: None

RemoveSong(songid)[source]¶

This method removed a song from the database. The file gets not touched, and so it does not matter if it even exists. All related information will also be removed.

Warning

This is not a “set the deleted flag” method. The data gets actually removed from the database. No recovery possible!

Parameters: songid (int) – ID of the song that shall be removed from database
Returns: None

UpdateAlbum(albumid, newpath, artistid=None)[source]¶

This method updates an already existing album entry in the database. So in case some information in the filesystem were changed (renaming, new files, …) the database gets updated. The following steps will be done to do this:

Update the path entry of the album to the new path

Reading a song file inside the directory to load meta data

Analyse the path to collect further information from the filesystem

Update database entry for the album with the new collected information

Updates information are:

path

name

release date

origin

artistid

All albums and songs of this artist will also be updated using UpdateSong().

Parameters

albumid (int) – ID of the album entry that shall be updated
newpath (str) – Relative path to the new album
artistid (int) – Optional, default value is None. The ID of the artist this song belongs to.

Returns

None

Raises

AssertionError – When the new path is invalid

UpdateArtist(artistid, newpath)[source]¶

This method updates an already existing artist entry in the database.

Updates information are:

path

name

All albums and songs of this artist will also be updated using UpdateAlbum() and UpdateSong().

Parameters

artistid (int) – ID of the artist entry that shall be updated
newpath (str) – Relative path to the new artist

Returns

None

UpdateChecksum(songpath)[source]¶

This method can be used to add or update the checksum of the file of a song into the database. The method does not care if there is already a checksum.

Note

AddSong() and UpdateSong() also update the checksum. So after calling that methods, calling this AddChecksum method is not necessary.

Parameters: songpath (str) – Absolute song path, or relative to the music root directory.
Returns: True on success, otherwise False

UpdateSong(songid, newpath, artistid=None)[source]¶

This method updates a song entry and parts of the related album entry. The following steps will be done to do this:

Update the path entry of the song to the new path

Reading the song files meta data

Analyse the path to collect further information from the file system

Update database entry with the new collected information including number of songs and CDs of the album entry.

Updates information are:

path

name

song number

cd number

playtime

bitrate

checksum

artistid

Further more the following album information get updated:

numofsongs

numofcds

Parameters

songid (int) – ID of the song entry that shall be updated
newpath (str) – Relative path to the new album

Returns

None

Raises

AssertionError – When the new path is invalid
Exception – When loading the meta data failes

UpdateVideo(videoid, newpath)[source]¶

This method updates a video entry in the database. The following steps will be done to do this:

Update the path entry of the video to the new path (in case the file name is different)

Reading the video files meta data

Analyse the path to collect further information from the file system

Update database entry with the new collected information

Updates information are:

path

name

playtime

origin

release

date the file was added

codec

x/y resolution

video begin/end

checksum

Parameters

videoid (int) – ID of the video entry that shall be updated
newpath (str) – Relative path to the new album

Returns

None

Raises

AssertionError – When the new path is invalid
Exception – When loading the meta data failes