MusadoraKit (pronounced 'myu' za' 'do' 'ra') is the ultimate companion to MusicKit. Working with MusicKit and Apple Music API is much easier, with one-liner APIs for effortless implementation.
MusadoraKit is a Swift framework that uses the latest MusicKit and Apple Music API, making it easy to integrate Apple Music into your app. It uses the new async/await pattern introduced in Swift 5.5. Currently, it is available for iOS 15.0+, macOS 12.0+, watchOS 8.0+ and tvOS 15.0+. There are new methods coming every month to support iOS 16, macOS 13, watchOS 9 and tvOS 16 features. The framework now also supports iOS 17, macOS 14, watchOS 10, tvOS 17 and visionOS 1.0.
It goes well with my book on Exploring MusicKit and Apple Music API, as all the documentation and references are mentioned in the book. Otherwise, the code itself is well documented.
Also, join the Discord Community for discussing anything about MusadoraKit, the book "Exploring MusicKit", MusicKit or your favorite music!
You can support my open-source by buying my book, "Exploring MusicKit and Apple Music API". 2 books a day, and I can happily continue working on MusadoraKit.
I am open-sourcing an app I worked on last year called Musadora. (MusadoraKit started as RRMusicKit for the Musadora app!)
I am slowly adding all the methods used in MusadoraKit to it, so you can refer to how easy it is to use the Swift package.
- Music Mate: Meet music friends on the world map.
- Sonar: Music & Community. Stream, Share & Discover
- Tuneder: An open-source iOS app that helps Apple Music users discover new songs with a Tinder-like UI.
- Musadora: Apple Music client focused on playlists
- Musadora Labs: A companion app to explore MusicKit
- Euphonic: Apple Music client focused on recommendations
- bijou.fm: Last.fm client with Apple Music integration
Follow the steps below to setup MusicKit for your app:
- Visit the Apple Developer Portal.
- Navigate to
Certificates, Identifiers & Profiles. - Select
Identifiersfrom the left panel. - Find your App's Bundle Identifier from the list and select it.
- Under
Services, ensureMusicKitis enabled. If not, enable it.
To inform the user why your app requires access to their media library, add NSAppleMusicUsageDescription to your Info.plist file.
- Open your project in Xcode.
- Select
Info.plistfrom the Project Navigator. - Click on the
+button to add a new key. - Add
NSAppleMusicUsageDescriptionas a key. - Set its value to the reason why your app needs access to Apple Music, e.g.,
Our app uses Music access to play music and create a pleasant experience..
Before your app can interact with Apple Music, it needs to request the user's authorization. This can be done using MusicAuthorization.request().
Here's a Swift code example:
import MusicKit
class MusicAuthorizationManager: ObservableObject {
@Published var isAuthorizedForMusicKit = false
@Published var musicKitError: MusicKitError?
func requestMusicAuthorization() async {
let status = await MusicAuthorization.request()
switch status {
case .authorized:
isAuthorizedForMusicKit = true
case .restricted:
musicKitError = .restricted
case .notDetermined:
musicKitError = .notDetermined
case .denied:
musicKitError = .denied
@unknown default:
musicKitError = .notDetermined
}
}
}This MusicAuthorizationManager class checks the authorization status for MusicKit. If the user grants authorization, isAuthorizedForMusicKit is set to true. If access is denied or restricted, or if the status is not determined, an appropriate MusicKitError is set.
Remember to call requestMusicAuthorization() at an appropriate time in your application flow to request the user's authorization.
Test your Apple Music API setup and developer token validity with a simple connectivity check.
Task {
do {
try await MusadoraKit.testConnectivity()
print("Successfully connected to Apple Music API!")
} catch {
print("Failed to connect: \(error.localizedDescription)")
// Check for specific error types
if let urlError = error as? URLError {
switch urlError.code {
case .userAuthenticationRequired:
print("Issue with developer token or MusicKit setup")
case .badServerResponse:
print("Server error - check your configuration")
default:
print("Network or other error")
}
}
}
}This method performs a GET request to Apple's test endpoint and validates:
- Developer token is valid
- MusicKit capabilities are properly configured
- Network connectivity to Apple Music API
- Basic API communication works
To easily access the Apple Music Catalog, you can use pre-defined methods from MusadoraKit. The methods are similar across the music items.
Example of working with fetching a catalog song by its identifier:
let song = try await MCatalog.song(id: "1613834314", with: [.albums])Example of searching the catalog:
let searchResponse = try await MCatalog.search(for: "the weeknd", types: [.songs, .stations, .albums, .playlists, .artists], limit: 10)
print(searchResponse.songs)
print(searchResponse.artists)While this is natively not available in MusicKit, you can fetch library resources using MusadoraKit that uses Apple Music API under the hood. The method are similar across the music items.
Example of fetching all library songs in alphabetical order:
let songs = try await MLibrary.songs()Example of searching the user's library:
let searchResponse = try await MLibrary.search(for: "hello", types: [Song.self])
print(searchResponse.songs)You can take advantage of Apple's Music recommendation system and use it in your app. For example, to fetch the default recommendations:
let recommendations = try await MRecommendation.default()
guard let recommendation = recommendations.first else { return }
print(recommendation.albums)
print(recommendation.playlists)
print(recommendation.stations)You can also fetch historial data from the user's library. For example, to get the recently played resources:
let recentlyPlayedItems = try await MLibrary.recentlyPlayed()
let recentlyPlayedAlbums = try await MLibrary.recentlyPlayedAlbums()
}Convenient extensions for Apple's ApplicationMusicPlayer to easily play songs, albums, playlists, and stations with simple one-liner methods.
// Play a single song
try await player.play(song: song)
// Play multiple songs
try await player.play(songs: songs)
// Play an album
try await player.play(album: album)
// Play a playlist
try await player.play(playlist: playlist)// Insert and play a song at a specific position in queue
try await player.play(song: song, at: .afterCurrentEntry)
// Play a personalized recommendation item
try await player.play(item: musicPersonalRecommendation)// Play a radio station
try await player.play(station: station)
// Play a music video (available on iOS 16+, tvOS 16+)
try await player.play(musicVideo: musicVideo)You can also fetch your users' Apple Music Replay data. It is limited to their yearly music summary for the latest year. It will return their top artists, albums, and songs all in one request.
let summary = try await MSummary.latest()
print(summary.topArtists)
print(summary.topAlbums)
print(summary.topSongs)// Get only top artists
let topArtists = try await MSummary.latestTopArtists()
// Get only top albums
let topAlbums = try await MSummary.latestTopAlbums()
// Get only top songs
let topSongs = try await MSummary.latestTopSongs()// Get only top artists and albums (skip songs)
let summary = try await MSummary.latest(views: [.topArtists, .topAlbums])Add, retrieve, and manage ratings for your users' favorite Apple Music content. Support for songs, albums, playlists, music videos, and stations.
// Rate a song as "liked"
let rating = try await MCatalog.addRating(for: song, rating: .like)
// Rate an album as "disliked"
let rating = try await MCatalog.addRating(for: album, rating: .dislike)
// Rate a playlist
let rating = try await MCatalog.addRating(for: playlist, rating: .love)// Get rating for a song
let rating = try await MCatalog.rating(for: song)
// Get rating for an album
let rating = try await MCatalog.rating(for: album)// Remove rating from a song
try await MCatalog.deleteRating(for: song)
// Remove rating from a playlist
try await MCatalog.deleteRating(for: playlist).like- Like content.dislike- Dislike content.love- Love content (hearted)
Access Apple's curated collection of the 100 Best Albums of all time. Get individual albums by position or fetch the entire collection.
// Get the #1 album
let album = try await MRecommendation.hundredBestAlbum(at: 1)
print("Top album: \(album.title) by \(album.artistName)")// Get the complete collection
let allAlbums = try await MRecommendation.allHundredBestAlbums()
for album in allAlbums {
print("\(album.title) - \(album.artistName)")
}// Get albums for a specific region
let albums = try await MRecommendation.allHundredBestAlbums(storefront: "gb")Add songs, albums, playlists, artists, music videos, and stations to your users' Apple Music favorites.
// Favorite a song
let success = try await MCatalog.favorite(song: song)
// Favorite an album
let success = try await MCatalog.favorite(album: album)
// Favorite a playlist
let success = try await MCatalog.favorite(playlist: playlist)
// Favorite an artist
let success = try await MCatalog.favorite(artist: artist)let success = try await MCatalog.favorite(musicVideo: musicVideo)let success = try await MCatalog.favorite(station: station)Access Apple Music storefront information and manage regional content availability.
let storefronts = try await MCatalog.storefronts()
for storefront in storefronts {
print("\(storefront.name) (\(storefront.id))")
}let usStorefront = try await MCatalog.storefront(id: "us")
print("US Storefront: \(usStorefront.name)")let current = try await MStorefront.current()
print("Current region: \(current.id)")In the example below, the target storefront is "jp" for Japan:
let album = MCatalog.album(id: "1223618217")
let equivalentAlbum = try await album.equivalent(for: "jp")
let albums = MCatalog.albums(ids: ["1223618217", "1603171516"])
let equivalentAlbums = try await albums.equivalents(for: "jp")let song = MCatalog.song(id: "1603171970")
let cleanSong = try await song.clean
let songs = MCatalog.songs(ids: ["1603171970", "1531327246"])
let cleanSongs = try await songs.cleanTo fetch multiple catalog music items by their identifiers in the same request. For example:
let request = MusicCatalogResourcesRequest(types: [.songs: ["1456313177"], .albums: ["1531125029", "1575203352"]])
let response = try await request.response()
print(response.songs)
print(response.albums)To fetch multiple library music items by their identifiers in the same request. For example:
let request = MusicLibraryResourcesRequest(types: [.songs: ["i.pmzqzM0S2rl5N4L"], .playlists: ["p.PkxVBgps2zOdV3r"]])
let response = try await request.response()
print(response.songs)
print(response.playlists)Create stunning animated backgrounds from music artwork with dynamic mesh gradients. Available on iOS 18, macOS 15, watchOS 11, tvOS 18, and visionOS 2 or later.
struct ContentView: View {
@ObservedObject private var queue = ApplicationMusicPlayer.shared.queue
var body: some View {
AnimatedArtworkView(queue: queue)
.ignoresSafeArea()
}
}AnimatedArtworkView(
queue: ApplicationMusicPlayer.shared.queue,
artwork: customArtwork,
width: 400,
height: 400
)let customPoints: [SIMD2<Float>] = [
SIMD2<Float>(0.0, 0.0), SIMD2<Float>(0.5, 0.0), SIMD2<Float>(1.0, 0.0),
SIMD2<Float>(0.0, 0.5), SIMD2<Float>(0.8, 0.2), SIMD2<Float>(0.2, 0.8),
SIMD2<Float>(1.0, 0.5), SIMD2<Float>(0.0, 1.0), SIMD2<Float>(0.5, 1.0),
SIMD2<Float>(1.0, 1.0), SIMD2<Float>(0.3, 0.7), SIMD2<Float>(0.7, 0.3),
SIMD2<Float>(0.1, 0.9), SIMD2<Float>(0.9, 0.1), SIMD2<Float>(0.4, 0.6),
SIMD2<Float>(0.6, 0.4)
]
AnimatedArtworkView(
queue: queue,
points: customPoints
)This view automatically extracts dominant colors from the current playing song's artwork and creates a beautiful animated mesh gradient background that responds to the music.
I hope you love working with MusadoraKit!
To my future self, and to every developer whose life my code may touch:
I just have a lot to write, and will keep writing until the end, hoping to leave something good behind.