MusicDBDatabase¶

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

MusicDBDatabase Class¶

class mdbapi.database.MusicDBDatabase(config, database)[source]¶

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.

FixAttributes(): Change the access mode and ownership of the music to match the configutation

AnalysePath(): Extract song information from its file path

TyrAnalysePathFor(): Check if the given path is valid for an artist, album or song

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

UpdateServerCache(): Signals the WebSocket Server to refresh its internal caches

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 lib.metatags.MetaTags.GetAllMetadata()

Analyze the path of one of those songs 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 directory 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 directory 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 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 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

AnalysePath(path)[source]¶

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

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}

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 does not check if the path exists!

Parameters: path (str) – 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.

FindLostPaths()[source]¶

This method checks all artist, album and song entries if the paths to their related directories and files are still valid. Entries with invalid paths gets returned in three lists: artists, albums, songs

This method does not check if the song is cached in the Song Cache.

Returns: A three lists of database entries with invalid paths. Empty lists if there is no invalid entrie.

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.

This method is very optimistic. It will also list empty directories. The user may want to check if the results of this method are valid for him.

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" 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 4 entries

FixAttributes(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

Ownership as configured in the settings: [music]->owner:[music]->group

Parameters: path (str) – Path to an artist, album or song, relative to the music directory
Returns: Nothing
Raises: ValueError if path is neither a file nor a directory. –

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

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:

Get all song paths

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"

UpdateAlbum(albumid, newpath)[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

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

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

UpdateServerCache()[source]¶

This method signals the MusicDB Websocket Server to update its caches by writing refresh into its named pipe. This should always be called when there are new artists, albums or songs added to the database.

Returns: Nothing

UpdateSong(songid, newpath)[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 album to the new path

Reading the song files meta data

Analyse the path to collect further information from the filesystem

Update database entry with the new collected information

Updates information are:

path

name

song number

cd number

playtime

bitrate

checksum

Further more the following album information get updted:

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