Track

Compositely combine reader and writer classes for metadata/tags/properties operations on Track files.

Classes:

LocalTrack(file[, remote_wrangler])

Generic track object for extracting, modifying, and saving metadata/tags/properties for a given file.

class musify.libraries.local.track.track.LocalTrack(file, remote_wrangler=None)

Bases: LocalItem, Track, Generic

Generic track object for extracting, modifying, and saving metadata/tags/properties for a given file.

Parameters:

• file (Union[str, Path, TypeVar(T, bound= FileType)]) – The path or Mutagen object of the file to load.

• remote_wrangler (RemoteDataWrangler (default: None)) – Optionally, provide a RemoteDataWrangler object for processing URIs. This object will be used to check for and validate a URI tag on the file. The tag that is used for reading and writing is set by the uri_tag class attribute. If no remote_wrangler is given, no URI processing will occur.

Attributes:

name	A name for this object
tag_map	The map of tag names to tag IDs for the given file type.
title	This track's title
artist	Joined string representation of all artists featured on this track
artists	List of all artists featured on this track.
album	The album this track is featured on
album_artist	The artist of the album this track is featured on
track_number	The position this track has on the album it is featured on
track_total	The track number of tracks on the album this track is featured on
genres	List of genres associated with this track
date	A date object representing the release date of this track
year	The year this track was released
month	The month this track was released
day	The day this track was released
bpm	The tempo of this track
key	The key of this track in alphabetical musical notation format
disc_number	The number of the disc from the album this track is featured on
disc_total	The total number the discs from the album this track is featured on
compilation	Is the album this track is featured on a compilation
comments	Comments associated with this track set by the user
has_uri	Does this track have a valid associated URI.
image_links	The images associated with the album this track is featured on in the form {<image name/type>: <image link>}
has_image	Does the album this track is associated with have an image
length	Total duration of this track in seconds
rating	The rating for this track
path	The path to the file.
filename	The filename without extension.
type	The type of audio file of this track
channels	The number of channels in this audio file i.e. 1 for mono, 2 for stereo, .
bit_rate	The bit rate of this track in kilobytes per second
bit_depth	The bit depth of this track in bits
sample_rate	The sample rate of this track in kHz
date_added	The timestamp for when this track was added to the associated collection
last_played	The timestamp when this track was last played
play_count	The total number of times this track has been played

Methods:

load()	Load local file from scratch using mutagen from the path stored in this object.
refresh()	Extract update tags for this object from the loaded mutagen object.
save([tags, replace, dry_run])	Update file's tags from given dictionary of tags.
move(path)	Move the file on the drive.
rename(filename)	Rename the file on the drive.
delete_tags([tags, dry_run])	Remove tags from file.
merge(track[, tags])	Set the tags of this track equal to the given track.
extract_images_to_file(output_folder)	Reload the file, extract and save all embedded images from file.
as_dict()	Return a dictionary representation of the key attributes of this object.

property name

A name for this object

abstract property tag_map: TagMap

The map of tag names to tag IDs for the given file type.

property title

This track’s title

property artist

Joined string representation of all artists featured on this track

property artists: list[str]

List of all artists featured on this track.

property album

The album this track is featured on

property album_artist

The artist of the album this track is featured on

property track_number

The position this track has on the album it is featured on

property track_total

The track number of tracks on the album this track is featured on

property genres

List of genres associated with this track

property date

A date object representing the release date of this track

property year

The year this track was released

property month

The month this track was released

property day

The day this track was released

property bpm

The tempo of this track

property key

The key of this track in alphabetical musical notation format

property disc_number

The number of the disc from the album this track is featured on

property disc_total

The total number the discs from the album this track is featured on

property compilation

Is the album this track is featured on a compilation

property comments

Comments associated with this track set by the user

property has_uri

Does this track have a valid associated URI. When None, answer is unknown.

property image_links

The images associated with the album this track is featured on in the form {<image name/type>: <image link>}

property has_image

Does the album this track is associated with have an image

property length

Total duration of this track in seconds

property rating

The rating for this track

property path

The path to the file.

property filename

The filename without extension.

property type

The type of audio file of this track

property channels: int

The number of channels in this audio file i.e. 1 for mono, 2 for stereo, …

property bit_rate: float

The bit rate of this track in kilobytes per second

property bit_depth: int | None

The bit depth of this track in bits

property sample_rate: float

The sample rate of this track in kHz

property date_added: datetime | None

The timestamp for when this track was added to the associated collection

property last_played: datetime | None

The timestamp when this track was last played

property play_count: int | None

The total number of times this track has been played

async load()

Load local file from scratch using mutagen from the path stored in this object. Refreshes the metadata loaded into this object and returns self.

Returns:

Self – Self.

Raises:

• FileDoesNotExistError – If the file cannot be found.

• InvalidFileType – If the file type is not supported.

refresh()

Extract update tags for this object from the loaded mutagen object.

Return type:

None

async save(tags=LocalTrackField.ALL, replace=False, dry_run=True)

Update file’s tags from given dictionary of tags.

Parameters:

• tags (GenericAlias[LocalTrackField] (default: <LocalTrackField.ALL: 0>)) – Tags to be updated.

• replace (bool (default: False)) – Destructively replace tags in each file.

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

Returns:

SyncResultTrack – List of tags that have been updated.

async move(path)

Move the file on the drive.

Updates the path properties of this object to represent the new file path. Creates parent directories at the new location if necessary.

Parameters:

path (str | Path) – The path to move the file to.

Return type:

None

async rename(filename)

Rename the file on the drive.

Updates the path properties of this object to represent the new file path. Creates parent directories at the new location if necessary.

Parameters:

filename (str | Path) – The filename to move the file to. Argument may be a path from which the filename will be extracted.

Return type:

None

async delete_tags(tags=(), dry_run=True)

Remove tags from file.

Parameters:

• tags (GenericAlias[LocalTrackField] (default: ())) – Tags to remove.

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

Returns:

SyncResultTrack – List of tags that have been removed.

merge(track, tags=TrackField.ALL)

Set the tags of this track equal to the given track. Give a list of tags to limit which are set

Return type:

None

extract_images_to_file(output_folder)

Reload the file, extract and save all embedded images from file. Returns the number of images extracted.

Return type:

int

as_dict()

Return a dictionary representation of the key attributes of this object.

The results of this function are used to produce the following:

• A JSON representation of the object when calling json()

• The string representation of the object when calling str() on the object

• The representation of the object when calling repr() on the object