Core#

Add#

moe.add

Adds music to the library.

exception AddAbortError#: Add process has been aborted by the user.

exception AddError#: Error adding an item to the library.

add_item(session: Session, item: LibItem)#

Adds a LibItem to the library.

Parameters:

session – Library db session.
item – Item to be added.

Raises:

AddError – Unable to add the item to the library.

Config#

moe.config

User configuration of moe.

Each instance of Moe should only create a single Config object. This object will contain all user settings and other related information and is set upon initializing the configuration for the first time i.e. calling Config(). Once initialized, the config can be accessed through import and should be treated as a constant:

from moe import config
print(config.CONFIG.settings.library_path)

Any application requiring use of the database should initiate a single sqlalchemy ‘session’. This session should use moe_sessionmaker to instantiate a session to connect to the database:

with moe_sessionmaker.begin() as session:
    # do work

Duplicate#

moe.duplicate

Handles duplicate detection and resolution in the library.

exception DuplicateError#: Duplicate items could not be resolved.

get_duplicates(session: Session, item: LibItem, others: Sequence[LibItem] | None = None) → list[LibItem]#

Returns items considered duplicates of item.

Parameters:

session – Library db session.
item – Library item to get duplicates of.
others – Items to compare against. If not given, will query the database and compare against all items in the library.

Returns:

Any items considered a duplicate as defined by is_unique().

resolve_duplicates(session: Session, items: Sequence[LibItem])#: Search for and resolve any duplicates of items in items.

Edit#

moe.edit

Edits music in the library.

exception EditError#: Error editing an item in the library.

edit_item(item: LibItem, field: str, value: str)#

Sets a LibItem’s field to value.

Parameters:

item – Library item to edit.
field – Item field to edit.
value – Value to set the item’s field to.

Raises:

EditError – field is not a valid attribute or is not editable.

Import#

moe.moe_import

Imports metadata for music in your library.

class CandidateAlbum(album: ~moe.library.album.MetaAlbum, match_value: float, plugin_source: str, source_id: str, disambigs: list[str] = <factory>)#

A single candidate for the import process.

album#

The candidate album.

Type:: Album

disambigs#

Any additional source-specific values that may be used to disambiguate or identify the candidate from others.

Type:: list[str]

match_value#

0 to 1 scale of how well the candidate album matches with the album being imported.

Type:: float

match_value_pct#

match_value as a percentage.

Type:: str

plugin_source#

String identifying the plugin this candidate came from e.g “musicbrainz”.

Type:: str

source_id#

A unique string identifying the release within the source e.g. musicbrainz’ release id.

Type:: str

candidate_prompt(new_album: Album, candidates: list[CandidateAlbum])#

Runs the interactive prompt for a user to select a candidate to import.

Parameters:

new_album – Album being added to the library.
candidates – List of candidates to choose from.

Raises:

AbortImport – Import prompt was aborted by the user.

import_album(album: Album)#: Imports album metadata for an album.

import_prompt(new_album: Album, candidate: CandidateAlbum)#

Runs the interactive prompt for the given album changes.

Parameters:

new_album – Album being added to the library. Any changes will be applied to this album.
candidate – New candidate album with all metadata changes. Will be compared against old_album.

Raises:

AbortImport – Import prompt was aborted by the user.

Library#

moe.library

Moe database/library functionality.

class Album(path, artist, title, date, barcode=None, catalog_nums=None, country=None, disc_total=1, label=None, media=None, original_date=None, track_total=None, **kwargs)#

Bases: LibItem, SABase, MetaAlbum

An album is a collection of tracks and represents a specific album release.

Albums also house any attributes that are shared by tracks e.g. albumartist.

artist#

AKA albumartist.

Type:: str

barcode#

UPC barcode.

Type:: Optional[str]

catalog_nums#

Set of all catalog numbers.

Type:: Optional[set[str]]

country#

Country the album was released in (two character identifier).

Type:: Optional[str]

custom#

Dictionary of custom fields.

Type:: dict[str, Any]

date#

Album release date.

Type:: datetime.date

disc_total#

Number of discs in the album.

Type:: int

extras#

Extra non-track files associated with the album.

Type:: list[Extra]

label#

Album release label.

Type:: Optional[str]

media#

Album release format (e.g. CD, Digital, etc.)

Type:: Optional[str]

original_date#

Date of the original release of the album.

Type:: Optional[datetime.date]

path#

Filesystem path of the album directory.

Type:: pathlib.Path

title#

Type:: str

track_total#

Number of tracks that should be in the album. If an album is missing tracks, then len(tracks) < track_total.

Type:: Optional[int]

tracks#

Album’s corresponding tracks.

Type:: list[Track]

__init__(path, artist, title, date, barcode=None, catalog_nums=None, country=None, disc_total=1, label=None, media=None, original_date=None, track_total=None, **kwargs)#: Creates an Album object with any additional custom fields as kwargs.

property fields: set[str]#: Returns any editable, track-specific fields.

classmethod from_dir(album_path: Path) → Album#

Creates an album from a directory.

Parameters:: album_path – Album directory path. The directory will be scanned for any files to be added to the album. Any non-track files will be added as extras.
Returns:: Created album.
Raises:: AlbumError – No tracks found in the given directory.

get_extra(rel_path: PurePath) → Extra | None#: Gets an Extra by its path.

get_track(track_num: int, disc: int = 1) → Track | None#: Gets a Track by its track number.

is_unique(other: Album) → bool#: Returns whether an album is unique in the library from other.

merge(other: Album | MetaAlbum, overwrite: bool = False) → None#

Merges another album into this one.

Parameters:

other – Other album to be merged with the current album.
overwrite – Whether or not to overwrite self if a conflict exists.

original_year#: Returns a year at the sql level.

year#: Returns a year at the sql level.

exception AlbumError#

Bases: LibraryError

Error performing some operation on an Album.

class Extra(album, path, **kwargs)#

Bases: LibItem, SABase

An Album can have any number of extra files such as logs, cues, etc.

album#

Album the extra file belongs to.

Type:: Album

custom#

Dictionary of custom fields.

Type:: dict[str, Any]

path#

Filesystem path of the extra file.

Type:: pathlib.Path

__init__(album, path, **kwargs)#

Creates an Extra.

Parameters:

album – Album the extra file belongs to.
path – Filesystem path of the extra file.
**kwargs – Any custom fields to assign to the extra.

property fields: set[str]#: Returns any editable, extra fields.

is_unique(other: LibItem) → bool#: Returns whether an extra is unique in the library from other.

merge(other: Extra, overwrite: bool = False)#

Merges another extra into this one.

Parameters:

other – Other extra to be merged with the current extra.
overwrite – Whether or not to overwrite self if a conflict exists.

property rel_path: PurePath#: Returns the extra’s path relative to its album’s path.

class LibItem#

Bases: MetaLibItem

Base class for library items i.e. Albums, Extras, and Tracks.

is_unique(other) → bool#: Returns whether an item is unique in the library from other.

exception LibraryError#

Bases: Exception

General library error.

Bases: MetaLibItem

A album containing only metadata.

It does not exist on the filesystem nor in the library. It can be used to represent information about a album to later be merged into a full Album instance.

There are no guarantees about information present in a MetaAlbum object i.e. all attributes may be None.

artist#

AKA albumartist.

Type:: Optional[str]

barcode#

UPC barcode.

Type:: Optional[str]

catalog_nums#

Set of all catalog numbers.

Type:: Optional[set[str]]

country#

Country the album was released in (two character identifier).

Type:: Optional[str]

custom#

Dictionary of custom fields.

Type:: dict[str, Any]

date#

Album release date.

Type:: Optional[datetime.date]

disc_total#

Number of discs in the album.

Type:: Optional[int]

label#

Album release label.

Type:: Optional[str]

media#

Album release format (e.g. CD, Digital, etc.)

Type:: Optional[str]

original_date#

Date of the original release of the album.

Type:: Optional[datetime.date]

title#

Type:: Optional[str]

track_total#

Number of tracks that should be in the album. If an album is missing tracks, then len(tracks) < track_total.

Type:: Optional[int]

tracks#

Album’s corresponding tracks.

Type:: list[Track]

__init__(artist: str | None = None, barcode: str | None = None, catalog_nums: set[str] | None = None, country: str | None = None, date: date | None = None, disc_total: int | None = None, label: str | None = None, media: str | None = None, original_date: date | None = None, title: str | None = None, track_total: int | None = None, tracks: list[MetaTrack] | None = None, **kwargs)#: Creates a MetaAlbum object with any additional custom fields as kwargs.

property catalog_num: str | None#: Returns a string of all catalog_nums concatenated with ‘;’.

property fields: set[str]#: Returns any editable album fields.

get_track(track_num: int, disc: int = 1) → MetaTrack | None#: Gets a MetaTrack by its track number.

merge(other: MetaAlbum, overwrite: bool = False) → None#

Merges another album into this one.

Parameters:

other – Other album to be merged with the current album.
overwrite – Whether or not to overwrite self if a conflict exists.

class MetaLibItem#

Bases: object

Base class for MetaTrack and MetaAlbum objects representing metadata-only.

These objects do not exist on the filesystem nor in the library.

property fields: set[str]#: Returns the editable fields of an item.

merge(other, overwrite: bool = False) → None#: Merges another item into this one.

class MetaTrack(album: MetaAlbum, track_num: int, artist: str | None = None, artists: set[str] | None = None, disc: int = 1, genres: set[str] | None = None, title: str | None = None, **kwargs)#

Bases: MetaLibItem

A track containing only metadata.

It does not exist on the filesystem nor in the library. It can be used to represent information about a track to later be merged into a full Track instance.

album#

Corresponding Album object.

Type:: Optional[Album]

artist#

Type:: Optional[str]

artists#

Set of all artists.

Type:: Optional[set[str]]

custom#

Dictionary of custom fields.

Type:: dict[str, Any]

disc#

Disc number the track is on.

Type:: Optional[int]

genres#

Set of all genres.

Type:: Optional[set[str]]

title#

Type:: Optional[str]

track_num#

Type:: Optional[int]

__init__(album: MetaAlbum, track_num: int, artist: str | None = None, artists: set[str] | None = None, disc: int = 1, genres: set[str] | None = None, title: str | None = None, **kwargs)#: Creates a MetaTrack object with any additional custom fields as kwargs.

property fields: set[str]#: Returns any editable, track-specific fields.

property genre: str | None#: Returns a string of all genres concatenated with ‘;’.

merge(other: MetaTrack, overwrite: bool = False)#

Merges another track into this one.

Parameters:

other – Other track to be merged with the current track.
overwrite – Whether or not to overwrite self if a conflict exists.

class Track(album, path, title, track_num, artist=None, artists=None, disc=None, genres=None, **kwargs)#

Bases: LibItem, SABase, MetaTrack

A single track in the library.

album#

Corresponding Album object.

Type:: Album

artist#

Type:: str

artists#

Set of all artists.

Type:: Optional[set[str]]

custom#

Dictionary of custom fields.

Type:: dict[str, Any]

disc#

Disc number the track is on.

Type:: int

genres#

Set of all genres.

Type:: Optional[set[str]]

path#

Filesystem path of the track file.

Type:: Path

title#

Type:: str

track_num#

Type:: int

Note

Altering any album-related property attributes, will result in changing the album field and thus all other tracks in the album as well.

__init__(album, path, title, track_num, artist=None, artists=None, disc=None, genres=None, **kwargs)#

Creates a Track.

Parameters:

album – Album the track belongs to.
path – Filesystem path of the track file.
title – Title of the track.
track_num – Track number.
artist – Track artist. Defaults to the album artist if not given.
artists – Set of all artists.
disc – Disc the track belongs to. If not given, will try to guess the disc based on the path of the track.
genres (Optional[set[str]]) – Set of all genres.
**kwargs – Any custom fields to assign to the track.

property audio_format: str#

Returns the audio format of the track.

One of [‘aac’, ‘aiff’, ‘alac’, ‘ape’, ‘asf’, ‘dsf’, ‘flac’, ‘ogg’, ‘opus’,: ‘mp3’, ‘mpc’, ‘wav’, ‘wv’].

property bit_depth: int#

Returns the number of bits per sample in the audio encoding.

The bit depth is an integer and zero when unavailable or when the file format does not support bit depth.

property fields: set[str]#: Returns any editable, track-specific fields.

classmethod from_file(track_path: Path, album: Album | None = None) → Track#

Alternate initializer that creates a Track from a track file.

Will read any tags from the given path and save them to the Track.

Parameters:

track_path – Filesystem path of the track.
album – Corresponding album for the track. If not given, the album will be created.

Returns:

Track instance.

Raises:

TrackError – Given path does not correspond to a track file.
ValueError – Track is missing required fields.

is_unique(other: Track) → bool#: Returns whether a track is unique in the library from other.

property sample_rate: int#

Returns the sampling rate of the track.

The sampling rate is in Hertz (Hz) as an integer and zero when unavailable.

exception TrackError#

Bases: LibraryError

Error performing some operation on a Track.

Move#

moe.move

Alters the location of items in your library.

copy_item(item: LibItem)#

Copies an item to a destination as determined by the user configuration.

Overwrites any existing files. Will create the destination if it does not already exist.

fmt_item_path(item: LibItem, parent: Path | None = None) → Path#

Returns a formatted item path according to the user configuration.

Parameters:

item – Item whose path will be formatted.
parent – Optional path the formatted path will be relative to. By default, this will be according to the configuration path settings.

Returns:

A formatted path as defined by the {album/extra/track}_path config template: settings relative to parent.

move_item(item: LibItem)#

Moves an item to a destination as determined by the user configuration.

Overwrites any existing files. Will create the destination if it does not already exist.

Query#

moe.query

Provides functionality to query the library for albums, extras, and tracks.

exception QueryError#: Error querying an item from the library.

query(session: Session, query_str: str, query_type: str) → list[Album] | list[Extra] | list[Track]#

Queries the database for items matching the given query string.

Parameters:

session – Library db session.
query_str – Query string to parse. See the query docs for more info.
query_type – Type of library item to return: either ‘album’, ‘extra’, or ‘track’.

Returns:

All items matching the query of type query_type.

Raises:

QueryError – Invalid query.

Read#

moe.read

Reads item files and updates moe with any changes.

read_item(item: LibItem)#

Reads an item’s file and updates the item with any changes.

Parameters:: item – Item to update.
Raises:: FileNotFoundError – Item’s path doesn’t exist.

Remove#

moe.remove

Removes music from the library.

remove_item(session: Session, item: LibItem)#: Removes an item from the library.

Util#

moe.util.core

This package contains shared functionality for the core API.

get_match_value(item_a: MetaAlbum | MetaTrack, item_b: MetaAlbum | MetaTrack) → float#

Returns a similarity value between two albums or tracks on a scale of 0 to 1.

Parameters:

item_a – First item to compare.
item_b – Second item to compare. Should be the same type as item_a or a subclass i.e. MetaAlbums and Albums can be compared.

Returns:

The match value is a weighted sum according to the defined weights for each applicable field.

get_matching_tracks(album_a: MetaAlbum, album_b: MetaAlbum, match_threshold: float = 0.7) → list[tuple[MetaTrack | None, MetaTrack | None]]#

Returns a list of tuples of track match pairs.

Parameters:

album_a – Album tracks will be matched against album_b.
album_b – Album tracks will be matched against album_a.
match_threshold – Threshold match value to consider a track a match with another. See get_track_match_value() for more info.

Returns:

A list of tuples of track match pairs. Each track in album_a and album_b will appear with its respective track match or None if no match was found. Each tuple represents a match and will be in the form (album_a_track, album_b_track).

Write#

moe.write

Writes tags to track files.

write_tags(track: Track)#: Write tags to a track’s file.