Exploring Freelancing
Navigate freelancing as a developer; find clients, manage contracts, ensure timely payment, and learn from experiences!
Exploring MusicKit
I wrote this book to fill in the gap for the documentation, filled with examples so that you do not have to spend time experimenting yourself.
I hope this book provides value to you and your app, and you enjoy working with MusicKit and integrating Apple Music into your app!
Use the discount code “early” for a massive 75% discount!
If you’re creating an app that displays the local resources in your library, there are chances that you may want to implement a search functionality as well. In the Yours tab of my app, Musadora, I added the search functionality using the latest searchable
modifier in SwiftUI 3.0, leveraging the simplicity offered by MusicKit.
Endpoint
Apple Music API offers us the following endpoint to search the library using a query -
GET https://api.music.apple.com/v1/me/library/search
For example, I want to search for the song “Twenty Eight” by The Weeknd while writing this post. I append the required term
query to the endpoint to search for a particular term. As there’s a space between the term, I’ll have to convert the spaces into a plus sign(+) as well. The endpoint will look like this -
GET https://api.music.apple.com/v1/me/library/search?term=twenty+eight
The search can return different resources, so I’ve to be specific about the resources to include in the results. For this, we’ve required query parameter, types,
which is an array of strings. The possible values are -
- library-albums
- library-songs
- library-playlists
- library-artists
- library-music-videos
As I know I’m looking for a song, I’ll append it to the endpoint -
GET https://api.music.apple.com/v1/me/library/search?term=twenty+eight&types=library-songs
There are a few optional query parameters like limit
to return a particular number of objects or the number of objects in the specified relationship. The default value is 5, with a maximum limit of 25. There’s another, offset,
to fetch the next page or group of objects.
Now that we know the URL, it’s time to get the response!
Response
First, I created a mock function to see the data that we’re getting from the response. Based on that, I’ll create the data model. I love the new concurrency model in Swift 5.5, so I will use the async/await syntax.
private func search(term: String) async throws {
let termValue = term.replacingOccurrences(of: " ", with: "+")
var requestURLComponents = URLComponents()
requestURLComponents.scheme = "https"
requestURLComponents.host = "api.music.apple.com"
requestURLComponents.path = "/v1/me/library/search"
requestURLComponents.queryItems = [
URLQueryItem(name: "term", value: termValue),
URLQueryItem(name: "types", value: "library-songs")
]
guard let url = requestURLComponents.url else { return }
let request = MusicDataRequest(urlRequest: URLRequest(url: url))
let response = try await request.response()
print(response.debugDescription)
}
The debugDescription
variable of MusicDataResponse
gives a detailed description of the URL response and the JSON in a pretty printed format. (Thanks for the tip @Joel!)
The response we get back is LibrarySearchResponse
, which has the results property containing all the different resources. In our case, we get back a library-songs
property containing the library songs results.
Earlier, we used to create our own data model for the Song
object, but fortunately, MusicKit provides a far better way. We can model it as a MusicItemCollection<Song>
that is a collection of songs. It benefits us from using the native structures defined in MusicKit like Song
and Artwork.
The data model looks like -
struct LibrarySearchResponse: Codable {
let results: LibrarySearchResults
}
struct LibrarySearchResults: Codable {
let librarySongs: MusicItemCollection<Song>
enum CodingKeys: String, CodingKey {
case librarySongs = "library-songs"
}
}
Now, I want to search for “The Weeknd” and fetch both the library-songs and library-artists. The endpoint will be -
GET https://api.music.apple.com/v1/me/library/search?term=weeknd&types=library-songs,library-artists
If we run the code and try to decode it -
let model = try JSONDecoder().decode(LibrarySearchResponse.self, from: response.data)
print(model)
We’ll get an error as I constrained LibrarySearchResults
for songs items only. To overcome this limitation and fetch any resource type, I’ll update LibrarySearchResults
with the different library resource types.
For convenience, I created a few typealias
for better readability.
public typealias Songs = MusicItemCollection<Song>
public typealias Artists = MusicItemCollection<Artist>
public typealias Albums = MusicItemCollection<Album>
public typealias MusicVideos = MusicItemCollection<MusicVideo>
public typealias Playlists = MusicItemCollection<Playlist>
public enum MusicLibrarySearchType: String, CodingKey {
case songs = "library-songs"
case artists = "library-artists"
case albums = "library-albums"
case musicVideos = "library-music-videos"
case playlists = "library-playlists"
}
public struct MusicLibrarySearchResponse {
public let songs: Songs
public let artists: Artists
public let albums: Albums
public let musicVideos: MusicVideos
public let playlists: Playlists
}
extension MusicLibrarySearchResponse: Decodable {
public init(from decoder: Decoder) throws {
let container = try decoder.container(keyedBy: MusicLibrarySearchType.self)
songs = try container.decodeIfPresent(Songs.self, forKey: .songs) ?? []
artists = try container.decodeIfPresent(Artists.self, forKey: .artists) ?? []
albums = try container.decodeIfPresent(Albums.self, forKey: .albums) ?? []
musicVideos = try container.decodeIfPresent(MusicVideos.self, forKey: .musicVideos) ?? []
playlists = try container.decodeIfPresent(Playlists.self, forKey: .playlists) ?? []
}
}
struct MusicLibrarySearchResponseResults: Decodable {
var results: MusicLibrarySearchResponse
}
Now, if we decode using MusicLibrarySearchResponseResults
, we’ll get the songs and artists as well!
While there’s a MusicCatalogSearchRequest
for searching the Apple Music catalog, there’s nothing for natively searching the local library. I’m working on a framework, MusadoraKit
, for bridging the gap and providing a more accessible wrapper over MusicKit. I created MusicLibrarySearchRequest
which works similar to MusicCatalogSearchRequest
-
let request = MusicLibrarySearchRequest(term: "the weeknd", types: [Artist.self, Song.self])
let response = try await request.response()
print(response.songs)
print(response.artists)
You can find the detailed documentation - MusicCatalogSearchRequest
Note: This framework is in alpha state.
Thanks for reading this post!
Exploring Freelancing
Navigate freelancing as a developer; find clients, manage contracts, ensure timely payment, and learn from experiences!