Supporting local and music streaming service (remote) libraries.
- Extract data for all item types from remote libraries, including following/saved items, such as: playlists, tracks, albums, artists, users, podcasts, audiobooks
- Load local audio files, programmatically manipulate, and save tags/metadata/embedded images
- Synchronise local tracks metadata with its matching track's metadata on supported music streaming services
- Synchronise local playlists with playlists on supported music streaming services
- Backup and restore track tags/metadata and playlists for local and remote libraries
- Extract and save images from remote tracks or embedded in local tracks
- Quick Guides
- Currently Supported
- Motivation and Aims
- Release History
- Contributing and Reporting Issues
- Author Notes
Note
This readme provides a brief overview of the program. Read the docs for full reference documentation.
Install through pip using one of the following commands:
pip install musifypython -m pip install musifyThere are optional dependencies that you may install for optional functionality. For the current list of optional dependency groups, read the docs
These quick guides will help you get set up and going with Musify in just a few minutes. For more detailed guides, check out the documentation.
Tip
Set up logging to ensure you can see all info reported by the later operations.
Libraries log info about loaded objects to the custom STAT level.
import logging
import sys
from musify.logger import STAT
logging.basicConfig(format="%(message)s", level=STAT, stream=sys.stdout)In this example, you will:
- Authorise access to the Spotify Web API
- Load your Spotify library
- Load some other Spotify objects
- Add some tracks to a playlist
-
If you don't already have one, create a Spotify for Developers account.
-
If you don't already have one, create an app. Select "Web API" when asked which APIs you are planning on using. To use this program, you will only need to take note of the client ID and client secret.
-
Create a
SpotifyAPIobject and authorise the program access to Spotify data as follows:The scopes listed in this example will allow access to read your library data and write to your playlists. See Spotify Web API documentation for more information about scopes
from musify.libraries.remote.spotify.api import SpotifyAPI spotify_api = SpotifyAPI( client_id="<YOUR CLIENT ID>", client_secret="<YOUR CLIENT SECRET>", scope=[ "user-library-read", "user-follow-read", "playlist-read-collaborative", "playlist-read-private", "playlist-modify-public", "playlist-modify-private" ], # providing a `token_file_path` will save the generated token to your system # for quicker authorisations in future token_file_path="<PATH TO JSON TOKEN>" )
-
Define helper functions for loading your
SpotifyLibrarydata:from musify.libraries.remote.spotify.library import SpotifyLibrary async def load_library(library: SpotifyLibrary) -> None: """Load the objects for a given ``library``. Does not enrich the loaded data.""" # authorise the program to access your Spotify data in your web browser async with library: # if you have a very large library, this will take some time... await library.load() async def load_library_by_parts(library: SpotifyLibrary) -> None: """Load the objects for a given ``library`` by each of its distinct parts. Does not enrich the loaded data.""" # authorise the program to access your Spotify data in your web browser async with library: # load distinct sections of your library await library.load_playlists() await library.load_tracks() await library.load_saved_albums() await library.load_saved_artists() async def enrich_library(library: SpotifyLibrary) -> None: """Enrich the loaded objects in the given ``library``""" # authorise the program to access your Spotify data in your web browser async with library: # enrich the loaded objects; see each function's docstring for more info on arguments # each of these will take some time depending on the size of your library await library.enrich_tracks(features=True, analysis=False, albums=False, artists=False) await library.enrich_saved_albums() await library.enrich_saved_artists(tracks=True, types=("album", "single")) def log_library(library: SpotifyLibrary) -> None: """Log stats about the loaded ``library``""" library.log_playlists() library.log_tracks() library.log_albums() library.log_artists() # pretty print an overview of your library print(library)
-
Define helper functions for loading some Spotify objects using any of the supported identifiers:
from musify.libraries.remote.spotify.object import SpotifyTrack, SpotifyAlbum, SpotifyPlaylist, SpotifyArtist async def load_playlist(api: SpotifyAPI) -> SpotifyPlaylist: # authorise the program to access your Spotify data in your web browser async with api as a: playlist = await SpotifyPlaylist.load("spotify:playlist:37i9dQZF1E4zg1xOOORiP1", api=a, extend_tracks=True) return playlist async def load_tracks(api: SpotifyAPI) -> list[SpotifyTrack]: tracks = [] # authorise the program to access your Spotify data in your web browser async with api as a: # load by ID tracks.append(await SpotifyTrack.load("6fWoFduMpBem73DMLCOh1Z", api=a)) # load by URI tracks.append(await SpotifyTrack.load("spotify:track:4npv0xZO9fVLBmDS2XP9Bw", api=a)) # load by open/external style URL tracks.append(await SpotifyTrack.load("https://open.spotify.com/track/1TjVbzJUAuOvas1bL00TiH", api=a)) # load by API style URI tracks.append(await SpotifyTrack.load("https://api.spotify.com/v1/tracks/6pmSweeisgfxxsiLINILdJ", api=api)) return tracks async def load_album(api: SpotifyAPI) -> SpotifyAlbum: # authorise the program to access your Spotify data in your web browser async with api as a: album = await SpotifyAlbum.load( "https://open.spotify.com/album/0rAWaAAMfzHzCbYESj4mfx", api=a, extend_tracks=True ) return album async def load_artist(api: SpotifyAPI) -> SpotifyArtist: # authorise the program to access your Spotify data in your web browser async with api as a: artist = await SpotifyArtist.load("1odSzdzUpm3ZEEb74GdyiS", api=a, extend_tracks=True) return artist async def load_objects(api: SpotifyAPI) -> None: playlist = await load_playlist(api) tracks = await load_tracks(api) album = await load_album(api) artist = await load_artist(api) # pretty print information about the loaded objects print(playlist, *tracks, album, artist, sep="\n")
-
Define helper function for adding some tracks to a playlist in your library, synchronising with Spotify, and logging the results:
NOTE: This step will only work if you chose to load either your playlists or your entire library in step 4.
async def update_playlist(name: str, library: SpotifyLibrary) -> None: """Update a playlist with the given ``name`` in the given ``library``""" tracks = await load_tracks(library.api) album = await load_album(library.api) await load_library(library) my_playlist = library.playlists[name] # add a track to the playlist my_playlist.append(tracks[0]) # add an album to the playlist using either of the following my_playlist.extend(album) my_playlist += album # sync the object with Spotify and log the results async with library: result = await my_playlist.sync(dry_run=False) library.log_sync(result) asyncio.run(update_playlist(spotify_api))
-
Run the program:
import asyncio asyncio.run(load_objects(api)) asyncio.run(update_playlist("<YOUR PLAYLIST'S NAME>", api)) # case sensitive
In this example, you will:
- Load a local library
- Modify the tags of some local tracks and save them
- Modify a local playlist and save it
-
Create one of the following supported
LocalLibraryobjects:from musify.libraries.local.library import LocalLibrary library = LocalLibrary( library_folders=["<PATH TO YOUR LIBRARY FOLDER>", ...], playlist_folder="<PATH TO YOUR PLAYLIST FOLDER", )
You will need to install the
musicbeeoptional dependency to work with MusicBee objects. Read the docs for more info.from musify.libraries.local.library import MusicBee library = MusicBee(musicbee_folder="<PATH TO YOUR MUSICBEE FOLDER>")
-
Load your library:
# if you have a very large library, this will take some time... library.load() # ...or you may also just load distinct sections of your library library.load_tracks() library.load_playlists() # optionally log stats about these sections library.log_tracks() library.log_playlists() # pretty print an overview of your library print(library)
-
Get collections from your library:
playlist = library.playlists["<NAME OF YOUR PLAYLIST>"] # case sensitive album = next(album for album in library.albums if album.name == "<ALBUM NAME>") artist = next(artist for artist in library.artists if artist.name == "<ARTIST NAME>") folder = next(folder for folder in library.folders if folder.name == "<FOLDER NAME>") genre = next(genre for genre in library.genres if genre.name == "<GENRE NAME>") # pretty print information about the loaded objects print(playlist, album, artist, folder, genre, sep="\n")
-
Get a track from your library using any of the following identifiers:
# get a track via its title # if multiple tracks have the same title, the first matching one if returned track = library["<TRACK TITLE>"] # get a track via its path track = library["<PATH TO YOUR TRACK>"] # must be an absolute path # get a track according to a specific tag track = next(track for track in library if track.artist == "<ARTIST NAME>") track = next(track for track in library if "<GENRE>" in (track.genres or [])) # pretty print information about this track print(track)
-
Change some tags:
from datetime import date track.title = "new title" track.artist = "new artist" track.album = "new album" track.track_number = 200 track.genres = ["super cool genre", "awesome genre"] track.key = "C#" track.bpm = 120.5 track.date = date(year=2024, month=1, day=1) track.compilation = True track.image_links.update({ "cover front": "https://i.scdn.co/image/ab67616d0000b2737f0918f1560fc4b40b967dd4", "cover back": "<PATH TO AN IMAGE ON YOUR LOCAL DRIVE>" }) # see the updated information print(track)
-
Save the tags to the file:
from musify.libraries.local.track.field import LocalTrackField # you don't have to save all the tags you just modified # select which you wish to save first like so tags = [ LocalTrackField.TITLE, LocalTrackField.GENRES, LocalTrackField.KEY, LocalTrackField.BPM, LocalTrackField.DATE, LocalTrackField.COMPILATION, LocalTrackField.IMAGES ] track.save(tags=tags, replace=True, dry_run=False)
-
Add some tracks to one of your playlists and save it:
my_playlist = library.playlists["<NAME OF YOUR PLAYLIST>"] # case sensitive # add a track to the playlist my_playlist.append(track) # add album's and artist's tracks to the playlist using either of the following my_playlist.extend(album) my_playlist += artist result = my_playlist.save(dry_run=False) print(result)
- Music Streaming Services:
Spotify - Audio filetypes:
.flac.m4a.mp3.wma - Local playlist filetypes:
.m3u.xautopf - Local Libraries:
MusicBee
The key aim of this package is to provide a seamless framework for interoperability between all types of music
libraries whether local or remote.
This framework should allow for the following key functionality between libraries:
- Synchronise saved user data including:
- playlists data (e.g. name, description, tracks)
- saved tracks/albums/artists etc.
- Synchronise metadata by allowing users to pull metadata from music streaming services and save this to local tracks
- Provide tools to allow users to move from music streaming services to a local library by semi-automating the process of purchasing songs.
With this functionality, user's should then have the freedom to:
- Switch between music streaming services with a few simple commands
- Share local playlists and other local library data with friends over music streaming services without ever having to use them personally
- Easily maintain a high-quality local library with complete metadata
Users should have the freedom to choose how and where they want to listen to their favourite artists.
Given the near non-existence of income these services provide to artists, user's should have the choice to compensate their favourite artists fairly for their work, choosing to switch to other services that do and/or choosing not to use music streaming services altogether because of this. Hopefully, by reintroducing this choice to users, the music industry will be forced to re-evaluate their complete devaluing of creative work in the rush to chase profits, and instead return to a culture of nurturing talent by providing artists with a basic income to survive on the work of their craft. One can dream.
For change and release history, check out the documentation.
If you have any suggestions, wish to contribute, or have any issues to report, please do let me know via the issues tab or make a new pull request with your new feature for review.
For more info on how to contribute to Musify, check out the documentation.
I initially developed this program for my own use so that I can share my local playlists with friends online. I have always maintained my own local library well and never saw the need to switch to music streaming services after their release. However, as an artist who has released music on all streaming services and after listening to the concerns many of the artists I follow have regarding these services, I started to refocus this project to be one that aims to break down the barriers between listening experiences for users. The ultimate aim being to make managing a local library as easy as any of the major music streaming services, allowing users the same conveniences while compensating artists fairly for their work.
I hope you enjoy using Musify!