Installation

To use tunesynctool in your projects, you have to first install it via PIP. To do so, use pip install tunesynctool or add tunesynctool to your requirements.txt file.

Overview

Tunesynctool provides abstractions for various music streaming services. It defines a set of functions that can be used with all implemented services. These are called drivers internally. You use drivers to fetch data and send requests to services. Drivers always return a Track or Playlist object depending on the method called. Please note that not all streaming services return the same amount of data. Spotify for example returns a lot of data, while YouTube barely does. Tunesynctool does not populate missing fields, so that's why depending on the service, the returned objects may have more or less fields with actual values than others.

You can import all classes from the tunesynctool package.

You can currently import these drivers:

• DeezerDriver
• YouTubeDriver
• SubsonicDriver
• SpotifyDriver

You can import the following models:

• Track
• Playlist

And this feature class:

• TrackMatcher

Working with drivers

When instantiating a new driver object, you have to provide a Configuration object.

from tunesynctool import SubsonicDriver, Configuration

my_config = Configuration(...)
# my_config = Configuration.from_env()

subsonic = SubsonicDriver(
    config=my_config
)

As mentioned before, all drivers implement the same interface, meaning you can use the same set of methods with all of them. Due to limitations and lack of support for similar features, some methods might raise an exception indicating a feature not available. For example, only Subsonic compatible APIs support returning a random track, while others don't, so they raise an appropriate exception.

get_user_playlists(self, limit: int = 25) -> List[Playlist]:

Fetches the authenticated user's playlist in their library. The definition of "playlists in library" varies from service to service, but you should expect playlists created by the user and the ones they are subscribed to be returned in most cases.

By default, the limit is set to 25, but you can provide a higher value as long as the service API doesn't reject it.

get_playlist_tracks(self, playlist_id: str, limit: int = 100) -> List[Track]

Fetches tracks and returns a list ofTrack objects for the given playlist identifier. By default, the limit is set to 100, but you can provide a higher value as long as the service API doesn't reject it.

create_playlist(self, name: str) -> Playlist

Creates a new playlist with the given name and returns a Playlist afterwards.

add_tracks_to_playlist(self, playlist_id: str, track_ids: List[str]) -> None

Updates the playlist with the given ID by telling the streaming service to add the tracks associated with the provided IDs to the playlist.

get_random_track(self) -> Optional[Track]

Returns a random track. Most services don't support this functionality so in most cases this raises an exception.

get_playlist(self, playlist_id: str) -> Playlist

Fetches metadata of the playlist associated with the provided ID.

get_track(self, track_id: str) -> Track

Fetches metadata of the track associated with the provided ID.

search_tracks(self, query: str, limit: int = 10) -> List[Track]

Uses the search functionality of the streaming service and returns a list of tracks if results are found. If none are found, an empty list is returned. This is the only method that also fetches extra information to populate the returned Tracks because it is used by the TrackMatcher feature too.

By default, the limit is set to 10, but you can provide a higher value as long as the service API doesn't reject it.

get_track_by_isrc(self, isrc: str) -> Track

Retrieves a track by its International Standard Recording Code (ISRC). However, not all drivers support this method, as not all streaming services provide a direct method to query tracks by their ISRC codes.