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) → None¶

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]) → None¶: 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, *, create_field: bool = False) → None¶

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.
create_field – Whether to create field as a new custom field if it doesn’t already exist.

Raises:

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

Import¶

moe.moe_import

Core api for importing albums.

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

import_album(album: Album) → None¶: Imports album metadata for an album.

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:: str | None

catalog_nums¶

Set of all catalog numbers.

Type:: set[str] | None

country¶

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

Type:: str | None

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:: str | None

media¶

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

Type:: str | None

original_date¶

Date of the original release of the album.

Type:: datetime.date | None

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:: int | None

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: LibItem) → bool¶: Returns whether an album is unique in the library from other.

merge(other: Self | MetaAlbum, merge_strategy: MergeStrategy = MergeStrategy.KEEP_EXISTING) → None¶

Merges another album into this one.

Parameters:

other – Other album to be merged with the current album.
merge_strategy – Which MergeStrategy to use when 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: Self, merge_strategy: MergeStrategy = MergeStrategy.KEEP_EXISTING) → None¶

Merges another extra into this one.

Parameters:

other – Other extra to be merged with the current extra.
merge_strategy – Which MergeStrategy to use when 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: Self) → bool¶: Returns whether an item is unique in the library from other.

exception LibraryError¶

Bases: Exception

General library error.

class MergeStrategy(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: Enum

Defines how to resolve conflicts when merging items.

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:: str | None

barcode¶

UPC barcode.

Type:: str | None

catalog_nums¶

Set of all catalog numbers.

Type:: Optional[set[str]]

country¶

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

Type:: str | None

custom¶

Dictionary of custom fields.

Type:: dict[str, Any]

date¶

Album release date.

Type:: datetime.date | None

disc_total¶

Number of discs in the album.

Type:: int | None

label¶

Album release label.

Type:: str | None

media¶

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

Type:: str | None

original_date¶

Date of the original release of the album.

Type:: datetime.date | None

title¶

Type:: str | None

track_total¶

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

Type:: int | None

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: datetime.date | None = None, disc_total: int | None = None, label: str | None = None, media: str | None = None, original_date: datetime.date | None = None, title: str | None = None, track_total: int | None = None, tracks: list[MetaTrack] | None = None, **kwargs: object) → None¶: 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: Self, merge_strategy: MergeStrategy = MergeStrategy.KEEP_EXISTING) → None¶

Merges another album into this one.

Parameters:

other – Other album to be merged with the current album.
merge_strategy – Which MergeStrategy to use when a conflict exists.

class MetaLibItem¶

Bases: Generic[T]

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: T, merge_strategy: MergeStrategy = MergeStrategy.KEEP_EXISTING) → None¶: Merges another item into this one.

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:: Album | None

artist¶

Type:: str | None

artists¶

Set of all artists.

Type:: set[str] | None

composer¶

Track composer.

Type:: str | None

composer_sort¶

Composer sort field.

Type:: str | None

custom¶

Dictionary of custom fields.

Type:: dict[str, Any]

disc¶

Disc number the track is on.

Type:: int | None

duration¶

Duration of the track in seconds.

Type:: float | None

genres¶

Set of all genres.

Type:: set[str] | None

title¶

Type:: str | None

track_num¶

Type:: int | None

__init__(album: MetaAlbum, track_num: int, artist: str | None = None, artists: set[str] | None = None, composer: str | None = None, composer_sort: str | None = None, disc: int = 1, duration: float | None = None, genres: set[str] | None = None, title: str | None = None, **kwargs: object) → None¶: 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 | Track, merge_strategy: MergeStrategy = MergeStrategy.KEEP_EXISTING) → None¶

Merges another track into this one.

Parameters:

other – Other track to be merged with the current track.
merge_strategy – Which MergeStrategy to use when a conflict exists.

class Track(album, path, title, track_num, artist=None, artists=None, composer=None, composer_sort=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:: set[str] | None

composer¶

Track composer.

Type:: str | None

composer_sort¶

Composer sort field.

Type:: str | None

custom¶

Dictionary of custom fields.

Type:: dict[str, Any]

disc¶

Disc number the track is on.

Type:: int

genres¶

Set of all genres.

Type:: set[str] | None

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, composer=None, composer_sort=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.
composer – Track composer.
composer_sort – Composer sort field.
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 duration: float¶: Returns the duration of the track in seconds.

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

classmethod from_file(track_path: Path, album: Album | None = None, album_path: Path | 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 None, the album will be created using the parent directory of track_path, unless album_path is also given.
album_path – When album is None, this is the path of the created album. If None it defaults to the parent directory of track_path.

Returns:

Track instance.

Raises:

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

is_unique(other: LibItem) → 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) → None¶

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.

Raises:

NotImplementedError – If item is not an Album, Extra, or Track.

move_item(item: LibItem) → None¶

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.

class QueryType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)¶

The type of library item to query for.

ALBUM = 'album'¶

EXTRA = 'extra'¶

TRACK = 'track'¶

query(session: Session, query_str: str, query_type: QueryType) → 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.

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) → None¶

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) → None¶: Removes an item from the library.

Util¶

moe.util.core

This package contains shared functionality for the core API.

class MatchType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: str, Enum

Which matching logic to apply when comparing values.

BOOL¶: Only checks if the values are equal or not.

DURATION¶: Uses a tolerance-based penalty system where a duration mismatch of 2.5% or less is not penalized, and the penalty increases linearly from 0 at 2.5% to 1.0 at 10% mismatch. This MatchType expects both values to be floats.

STRING¶: Compares the similarity between two strings.

get_field_match_penalty(value_a: Any, value_b: Any, match_type: MatchType = MatchType.BOOL) → float¶

Returns an unweighted penalty value between two field values.

Parameters:

value_a – First field value to compare.
value_b – Second field value to compare.
match_type – The type of matching logic to use.

Returns:

Penalty value between 0.0 (perfect match) and 1.0 (complete mismatch). If both values are empty, a small penalty of 0.1 is returned. If one value is empty, a slightly larger 0.2 penalty is returned.

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) → None¶: Write tags to a track’s file.