plistsync.core.track¶

Abstract representation of a music track.

Overview¶

Classes¶
`GlobalTrackIDs`	Global Unique identifiers for a track.
`LocalTrackIDs`	Locally scoped identifiers for a track.
`TrackInfo`	A serialized track.
`Track`	An abstract class representing a track.

Module Contents¶

class plistsync.core.track.GlobalTrackIDs¶

Bases: TypedDict

Global Unique identifiers for a track.

Each identifier in this collection should uniquely identify a track across all systems and collections. Unlike local identifiers, these are intended to allow unambiguous track matching across devices, libraries, or services.

Corresponds to collections-protocol GlobalLookup.

tidal_id: str¶

Tidal ID of the track.

Globally unique within the Tidal service.

isrc: str¶

International Standard Recording Code.

A standardized identifier intended to be globally unique for a recording. TODO: A track may have multiple ISRCs (e.g., different releases or regions), so this field may need to support multiple values in the future.

spotify_id: str¶

Spotify ID of the track.

Globally unique within the Spotify service.

class plistsync.core.track.LocalTrackIDs¶

Bases: TypedDict

Locally scoped identifiers for a track.

These identifiers are unique only within a specific collection or context, such as a local library, playlist, database, or device. They are intended for identifying a track within that local scope and may not be unique globally.

Corresponds to collections-protocol LocalLookup.

file_path: pathlib.PurePath¶

Local (pure) filesystem path to the track file.

This is not globally unique because file paths may differ across devices or mount points, even if the underlying track is the same. (This is also why we use PurePath, which is OS-agnostic, instead of Path.)

beets_id: int¶

Track ID from a local Beets library.

Unique only within a local Beets library. Different libraries may assign different IDs to the same track.

plex_id: str¶

Track ID from a Plex media server library.

Unique only within a single Plex library. The same track in another Plex server or library may have a different ID.

class plistsync.core.track.TrackInfo¶

Bases: TypedDict

A serialized track.

This is the dictionary representation of a track.

Corresponds to collections-protocol InfoLookup.

class plistsync.core.track.Track¶

Bases: abc.ABC

An abstract class representing a track.

A track is a piece of music. It has a title, artists, albums and identifiers. It can be used in a number of places where the generic information about a track is needed.

property title: str | None¶: The title of the track.

property artists: list[str]¶

The name of the artists.

The first artist is the main artist. If the track has no artist, return an empty list.

property albums: list[str]¶

The name of the albums the track is in.

If the track is not in any album, return empty list.

property path: pathlib.PurePath | None¶: The path to the file of the track.

property isrc: str | None¶: International Standard Recording Code.

property primary_artist: str | None¶

The main artist of the track.

If the track has no artist, return an empty string.

property info: TrackInfo¶

Abstractmethod:

Get this tracks information.

property global_ids: GlobalTrackIDs¶

Abstractmethod:

The globally unique identifiers of this track.

property local_ids: LocalTrackIDs¶

Abstractmethod:

The locally unique identifiers of this track.

diff(track2: Track) → dict¶: Return a dict of differences between this and another track.