Library

The core, basic library implementation which is just a simple set of folders.

Classes:

LocalLibrary([library_folders, ...])

Represents a local library, providing various methods for manipulating tracks and playlists across an entire local library collection.

class musify.libraries.local.library.library.LocalLibrary(library_folders=None, playlist_folder=None, playlist_filter=(), path_mapper=PathMapper({}), remote_wrangler=None, name=None)

Bases: LocalCollection[LocalTrack], Library[LocalTrack]

Represents a local library, providing various methods for manipulating tracks and playlists across an entire local library collection.

Parameters:

• library_folders (GenericAlias[str | Path] | None (default: None)) – The absolute paths of the library folders containing all tracks. The intialiser will check for the existence of these paths and only store them if they exist.

• playlist_folder (str | Path | None (default: None)) – The absolute path of the playlist folder containing all playlists or the relative path within one of the available library_folders. If a relative path is given and many library folders are given, only the first path that gives an existing result is processed. The setter will check for the existence of this path and only store the absolute path if it exists.

• playlist_filter (Union[Collection[str], Filter[str]] (default: ())) – An optional Filter to apply or collection of playlist names to include when loading playlists. Playlist names will be passed to this filter to limit which playlists are loaded.

• path_mapper (PathMapper (default: PathMapper({}))) – Optionally, provide a PathMapper for paths stored in the playlist files. Useful if the playlist files contain relative paths and/or paths for other systems that need to be mapped to absolute, system-specific paths to be loaded and back again when saved.

• remote_wrangler (RemoteDataWrangler | None (default: None)) – Optionally, provide a RemoteDataWrangler object for processing URIs on tracks. If given, the wrangler can be used when calling __get_item__ to get an item from the collection from its URI. The wrangler is also used when loading tracks to allow them to process URI tags. For more info on this, see LocalTrack.

• name (str (default: None)) – A name to assign to this library.

Attributes:

name	A name for this object
source
tracks	The tracks in this collection
playlists	The playlists in this library mapped as {<name>: <playlist>}
folders	Dynamically generate a set of folder collections from the tracks in this library.
albums	Dynamically generate a set of album collections from the tracks in this library
artists	Dynamically generate a set of artist collections from the tracks in this library
genres	Dynamically generate a set of genre collections from the tracks in this library
path_mapper	Passed to playlist objects when loading playlists to map paths stored in the playlist file.
library_folders	Path to the library folder
playlist_filter	Filter to filter out the playlists loaded by name.
playlist_folder	Path to the playlist folder
errors	Stores the paths that caused errors when loading/enriching

Methods:

load()	Loads all tracks and playlists in this library from scratch and log results.
load_track(path)	Wrapper for load_track() which automatically loads the track at the given path and assigns optional arguments using this library's attributes.
load_tracks()	Load all tracks from all the valid paths in this library, replacing currently loaded tracks.
log_tracks()	Log stats on currently loaded tracks
load_playlist(path)	Wrapper for load_playlist() which automatically loads the playlist at the given path and assigns optional arguments using this library's attributes.
load_playlists()	Load all playlists found in this library's playlist_folder, filtered down using the playlist_filter if given, replacing currently loaded playlists.
log_playlists()	Log stats on currently loaded playlists
save_playlists([dry_run])	For each Playlist in this Library, saves its associate tracks and its settings (if applicable) to file.
merge_playlists(playlists[, reference])	Merge playlists from given list/map/library to this library.
restore_tracks(backup[, tags])	Restore track tags from a backup to loaded track objects.
json()	Return a dictionary representation of the key attributes of this object that is safe to output to JSON

property name: str

A name for this object

class property source: str

The type of local library loaded

property tracks: list[LocalTrack]

The tracks in this collection

property playlists: dict[str, LocalPlaylist]

The playlists in this library mapped as {<name>: <playlist>}

property folders: list[LocalFolder]

Dynamically generate a set of folder collections from the tracks in this library. Folder collections are generated relevant to the library folder it is found in.

property albums: list[LocalAlbum]

Dynamically generate a set of album collections from the tracks in this library

property artists: list[LocalArtist]

Dynamically generate a set of artist collections from the tracks in this library

property genres: list[LocalGenres]

Dynamically generate a set of genre collections from the tracks in this library

path_mapper

Passed to playlist objects when loading playlists to map paths stored in the playlist file.

property library_folders: list[Path]

Path to the library folder

playlist_filter: Filter[str]

Filter to filter out the playlists loaded by name.

property playlist_folder: Path

Path to the playlist folder

errors: list[str]

Stores the paths that caused errors when loading/enriching

async load()

Loads all tracks and playlists in this library from scratch and log results.

Return type:

None

async load_track(path)

Wrapper for load_track() which automatically loads the track at the given path and assigns optional arguments using this library’s attributes.

Handles exceptions by logging paths which produce errors to internal list of errors.

Return type:

LocalTrack | None

async load_tracks()

Load all tracks from all the valid paths in this library, replacing currently loaded tracks.

Return type:

None

log_tracks()

Log stats on currently loaded tracks

Return type:

None

async load_playlist(path)

Wrapper for load_playlist() which automatically loads the playlist at the given path and assigns optional arguments using this library’s attributes.

Handles exceptions by logging paths which produce errors to internal list of errors.

Return type:

LocalPlaylist

async load_playlists()

Load all playlists found in this library’s playlist_folder, filtered down using the playlist_filter if given, replacing currently loaded playlists.

Returns:

None – The loaded playlists.

Raises:

LocalCollectionError – If a given playlist name cannot be found.

log_playlists()

Log stats on currently loaded playlists

Return type:

None

async save_playlists(dry_run=True)

For each Playlist in this Library, saves its associate tracks and its settings (if applicable) to file.

Parameters:

dry_run (bool (default: True)) – Run function, but do not modify the file on the disk.

Returns:

dict[LocalPlaylist, Result] – A map of the playlist name to the results of its sync as a Result object.

merge_playlists(playlists, reference=None)

Merge playlists from given list/map/library to this library.

See Playlist.merge() for more info.

Parameters:

• playlists (GenericAlias[LocalTrack]) – The playlists to merge onto this library’s playlists. If a given playlist is not found in this library, simply add the playlist to this library.

• reference (GenericAlias[LocalTrack] | None (default: None)) – Optionally, provide a reference playlist to compare both the current playlist and the other items to. The function will determine tracks to remove from this playlist based on the reference. Useful for using this function as a synchronizer where the reference refers to the playlist at the previous sync.

Return type:

None

restore_tracks(backup, tags=LocalTrackField.ALL)

Restore track tags from a backup to loaded track objects. This does not save the updated tags.

Parameters:

• backup (TypeAliasType) – Backup data in the form {<path>: {<Map of JSON formatted track data>}}

• tags (GenericAlias[LocalTrackField] (default: <LocalTrackField.ALL: 0>)) – Set of tags to restore.

Returns:

int – The number of tracks restored

json()

Return a dictionary representation of the key attributes of this object that is safe to output to JSON