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.
`OfflineTrack`	A offline (in memory) track with attached service.

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 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.

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.

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

class plistsync.core.track.OfflineTrack(info: TrackInfo, local_ids: LocalTrackIDs | None = None, global_ids: GlobalTrackIDs | None = None)¶

Bases: Track

A offline (in memory) track with attached service.

This class provides a concrete implementation of Track for managing tracks in memory without any connection to online music services. It is useful as an intermediate representation during matching or syncing.

property info: TrackInfo¶: Get this tracks information.

property global_ids: GlobalTrackIDs¶: The globally unique identifiers of this track.

property local_ids: LocalTrackIDs¶: The locally unique identifiers of this track.

merge(track: Track) → OfflineTrack¶

Merge another track into this one.

This operation returns a new offline track with the merged data.

classmethod from_track(track: Track) → OfflineTrack¶: Create a offline track from arbitrary other track.