Musicbee

An implementation of LocalLibrary for the MusicBee library manager. Reads library/settings files from MusicBee to load and enrich playlist/track etc. data.

Classes:

MusicBee(musicbee_folder[, playlist_filter, ...])	Represents a local MusicBee library, providing various methods for manipulating tracks and playlists across an entire local library collection.
XMLLibraryParser(path[, path_keys])	Parses MusicBee XML files to and from iTunes style XML.

class musify.libraries.local.library.musicbee.MusicBee(musicbee_folder, playlist_filter=(), path_mapper=PathMapper({}), remote_wrangler=None, name=None)

Bases: LocalLibrary, File

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

Parameters:

• musicbee_folder (str | Path) – The absolute path of the musicbee folder containing settings and library files.

• 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 (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:

valid_extensions	Extensions of files that can be loaded by this class.
xml_library_path	The path of the MusicBee library file relative the musicbee_folder provided on initialisation.
xml_library_path_keys	A list of keys for the XML library that need to be processed as system paths.
xml_settings_path	The path of the MusicBee settings file relative the musicbee_folder provided on initialisation.
playlists_path	The path to the playlists folder relative the musicbee_folder provided on initialisation.
path	The path to the file.
musicbee_folder	The absolute path of the musicbee folder containing settings and library files.
library_xml	A map representation of the loaded XML library data
settings_xml	A map representation of the loaded XML settings data

Methods:

load_tracks()	Load all tracks from all the valid paths in this library, replacing currently loaded tracks.
save([dry_run])	Generate and save the XML library file for this MusicBee library.
generate_persistent_id([value, id_])	Generates a valid persistent ID from a given value or validates a given persistent ID as given by id_,
track_to_xml(track, track_id[, persistent_id])	Convert a local track into a dict representation of XML data for a MusicBee library file
playlist_to_xml(playlist, tracks, playlist_id)	Convert a local playlist into a dict representation of XML data for a MusicBee library file.

valid_extensions: frozenset[str] = frozenset({'.xml'})

Extensions of files that can be loaded by this class.

xml_library_path = PosixPath('iTunes Music Library.xml')

The path of the MusicBee library file relative the musicbee_folder provided on initialisation.

xml_library_path_keys = {'Location', 'Music Folder'}

A list of keys for the XML library that need to be processed as system paths.

xml_settings_path = PosixPath('MusicBeeLibrarySettings.ini')

The path of the MusicBee settings file relative the musicbee_folder provided on initialisation.

playlists_path = PosixPath('Playlists')

The path to the playlists folder relative the musicbee_folder provided on initialisation.

property path: Path

The path to the file.

musicbee_folder

The absolute path of the musicbee folder containing settings and library files.

library_xml: dict[str, Any]

A map representation of the loaded XML library data

settings_xml: dict[str, Any]

A map representation of the loaded XML settings data

async load_tracks()

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

Return type:

None

async save(dry_run=True, *_, **__)

Generate and save the XML library file for this MusicBee library.

Parameters:

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

Returns:

dict[str, Any] – Map representation of the saved XML file.

static generate_persistent_id(value=None, id_=None)

Generates a valid persistent ID from a given value or validates a given persistent ID as given by id_,

Parameters:

• id – A persistent ID to validate

• value (str | Path | None (default: None)) – A value to generate a persistent ID from.

Returns:

str – The valid persistent ID.

Raises:

MusicBeeIDError – When no id_ and no value is given, or the given id_ is invalid.

classmethod track_to_xml(track, track_id, persistent_id=None)

Convert a local track into a dict representation of XML data for a MusicBee library file

Parameters:

• track (LocalTrack) – The track to convert.

• track_id (int) – An incremental ID to assign to the track.

• persistent_id (str | None (default: None)) – An 16-character unique ID to assign to the track.

Returns:

dict[str, Any] – A dict representation of XML data for the given track.

Raises:

MusicBeeIDError – When the given persistent_id is invalid.

classmethod playlist_to_xml(playlist, tracks, playlist_id, persistent_id=None)

Convert a local playlist into a dict representation of XML data for a MusicBee library file.

Parameters:

• playlist (LocalPlaylist) – The playlist to convert.

• tracks (Mapping[LocalTrack, int | Sequence[int, str]] | list[LocalTrack]) – A map of all available tracks in the library to their track IDs, or a simple list of tracks. If a map is given and the values are Sequence, take the first index as the Track ID. If a list is given, the function will use the track’s index as the Track ID.

• playlist_id (int) – An incremental ID to assign to the playlist.

• persistent_id (str | None (default: None)) – An 16-character unique ID to assign to the playlist.

Returns:

dict[str, Any] – A dict representation of XML data for the given playlist.

Raises:

MusicBeeIDError – When the given persistent_id is invalid.

class musify.libraries.local.library.musicbee.XMLLibraryParser(path, path_keys=None)

Bases: object

Parses MusicBee XML files to and from iTunes style XML.

Parameters:

• path (str | Path) – Path to the XML file.

• path_keys (Iterable[str] | None (default: None)) – A list of keys in the XML file that need to be processed as system paths.

Attributes:

timestamp_format	The string representation of the timestamp format when parsing.
path	Path to the XML file.
path_keys	A list of keys in the XML file that need to be processed as system paths.

Methods:

to_xml_timestamp(timestamp)	Convert timestamp string as found in the MusicBee XML library file to a datetime object
from_xml_timestamp(timestamp_str)	Convert timestamp string as found in the MusicBee XML library file to a datetime object
to_xml_path(path)	Convert a standard system path to a file path as found in the MusicBee XML library file
from_xml_path(path)	Clean the file paths as found in the MusicBee XML library file to a standard system path
parse()	Parse the XML file from the currently stored path to a dictionary
unparse(data[, dry_run])	Un-parse a map of XML data to XML and save to file.

timestamp_format = '%Y-%m-%dT%H:%M:%SZ'

The string representation of the timestamp format when parsing.

path: Path

Path to the XML file.

path_keys: frozenset[str]

A list of keys in the XML file that need to be processed as system paths.

classmethod to_xml_timestamp(timestamp)

Convert timestamp string as found in the MusicBee XML library file to a datetime object

Return type:

str | None

classmethod from_xml_timestamp(timestamp_str)

Convert timestamp string as found in the MusicBee XML library file to a datetime object

Return type:

datetime | None

static to_xml_path(path)

Convert a standard system path to a file path as found in the MusicBee XML library file

Return type:

str

static from_xml_path(path)

Clean the file paths as found in the MusicBee XML library file to a standard system path

Return type:

str

parse()

Parse the XML file from the currently stored path to a dictionary

Return type:

dict[str, Any]

unparse(data, dry_run=True)

Un-parse a map of XML data to XML and save to file.

Parameters:

• data (Mapping[str, Any]) – Map of XML data to export.

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

Return type:

None