HummingKit

public class HummingKit

Main entry class of HummingKit framework

  • Initializer of HummingKit()

    Declaration

    Swift

    public init(developerToken: String, userToken: String)

    Parameters

    developerToken

    Apple Music Developer Token fetched beforehand using developer key issued by developer.apple.com

    userToken

    Apple Music User Token fetched on user-end device using Apple Music Developer Token

  • Function to customize maximum time of retrying an segmental fetching request within an expensive request.

    Declaration

    Swift

    public func setMaximumRequestRetryCount(_ retryCount: Int)

    Parameters

    retryCount

    The upper limit of time of retrying.

Storefonts

  • Fetch user’s Apple Music account default storefront information.

    Declaration

    Swift

    public func fetchUserStorefront(completion: @escaping (_ result: Swift.Result<Storefront, Error>) -> Void)

    Parameters

    completion

    Completion handler of request result of type Swift.Result

    result

    Result of request, .success(Storefront) or .failure(Error)

  • Fetch a storefront from Apple Music server using its identifier.

    Declaration

    Swift

    public func fetchAStorefront(storefrontID: String, completion: @escaping (_ result: Swift.Result<Storefront, Error>) -> Void)

    Parameters

    storefrontID

    The identifier (an ISO 3166 alpha-2 country code) of the storefront to be fetched.

    completion

    Completion handler of request result of type Swift.Result

    result

    Result of request, .success(Storefront) or .failure(Error)

  • Fetch an array of storefronts from Apple Music server using their identifiers.

    Declaration

    Swift

    public func fetchMultipleStorefronts(storefrontIDs: [String], completion: @escaping (_ result: Swift.Result<[Storefront], Error>) -> Void)

    Parameters

    storefrontIDs

    An array of the identifiers (ISO 3166 alpha-2 country codes) of the storefronts to be fetched.

    completion

    Completion handler of request result of type Swift.Result<[Storefront], Error>

    result

    Result of request, .success([Storefront]) or .failure(Error)

  • Fetch all storefronts available from Apple Music server all at once.

    Declaration

    Swift

    public func fetchAllStorefronts(completion: @escaping (_ result: Swift.Result<[Storefront], Error>) -> Void)

    Parameters

    completion

    Completion handler of request result of type Swift.Result<[Storefront], Error>

    result

    Result of request, .success([Storefront]) or .failure(Error)

Add Resources to Library

  • Add resources (playlists, albums, songs, MVs) to user library.

    Declaration

    Swift

    public func addResourcesToLibrary(playlistsIDs: [String], albumsIDs: [String], songsIDs: [String], musicVideosIDs: [String], completion: @escaping (_ result: Swift.Result<String, Error>) -> Void)

    Parameters

    playlistsIDs

    An array of unique catalog identifiers of playlists to be added to user library

    albumsIDs

    An array of unique catalog identifiers of albums to be added to user library

    songsIDs

    An array of unique catalog identifiers of songs to be added to user library

    musicVideosIDs

    An array of unique catalog identifiers of music videos to be added to user library

    completion

    Completion handler of request result of type Swift.Result

    result

    Result of request, .success(status) or .failure(Error)

Albums

  • Fetch a catalog album using its identifier.

    Declaration

    Swift

    public func fetchACatalogAlbum(storefront: String, albumID: String, completion: @escaping (_ result: Swift.Result<CatalogAlbum, Error>) -> Void)

    Parameters

    storefront

    An identifier (ISO 3166 alpha-2 country codes) of the storefront which to perform request in

    albumID

    The unique identifier of the album

    completion

    Completion handler of request result of type Swift.Result

    result

    Result of request, .success(CatalogAlbum) or .failure(Error)

  • Fetch multiple catalog albums using their identifiers.

    Declaration

    Swift

    public func fetchMultipleCatalogAlbums(storefront: String, albumIDs: [String], completion: @escaping (_ result: Swift.Result<[CatalogAlbum], Error>) -> Void)

    Parameters

    storefront

    An identifier (ISO 3166 alpha-2 country codes) of the storefront which to perform request in

    albumIDs

    An array of the identifiers of the albums. Maximum fetch limit is 100.

    completion

    Completion handler of request result of type Swift.Result<[CatalogAlbum], Error>

    result

    Result of request, .success([CatalogAlbum]) or .failure(Error)

  • Fetch the relationship of specified catalog album using its identifier and relationship tag.

    Declaration

    Swift

    public func fetchACatalogAlbumRelationship(storefront: String, albumID: String, relationship: String, completion: @escaping (_ result: Swift.Result<JSON, Error>) -> Void)

    Parameters

    storefront

    An identifier (ISO 3166 alpha-2 country codes) of the storefront which to perform request in

    albumID

    The unique identifier of the album

    relationship

    The name tag of the relationship to fetch for this catalog album

    completion

    Completion handler of request result of type Swift.Result

    result

    Result of request, .success(JSON) or .failure(Error)

  • Fetch a library album using its identifier.

    Declaration

    Swift

    public func fetchALibraryAlbum(albumID: String, completion: @escaping (_ result: Swift.Result<LibraryAlbum, Error>) -> Void)

    Parameters

    albumID

    The unique identifier of the album

    completion

    Completion handler of request result of type Swift.Result

    result

    Result of request, .success(LibraryAlbum) or .failure(Error)

  • Fetch the relationship of specified library album using its identifier and relationship tag.

    Declaration

    Swift

    public func fetchALibraryAlbumRelationship(albumID: String, relationship: String, completion: @escaping (_ result: Swift.Result<JSON, Error>) -> Void)

    Parameters

    albumID

    The unique identifier of the album

    relationship

    The name tag of the relationship to fetch for this library album

    completion

    Completion handler of request result of type Swift.Result

    result

    Result of request, .success(JSON) or .failure(Error)

  • Fetch multiple library albums using their identifiers.

    Declaration

    Swift

    public func fetchMultipleLibraryAlbums(albumIDs: [String], completion: @escaping (_ result: Swift.Result<[LibraryAlbum], Error>) -> Void)

    Parameters

    albumIDs

    An array of the identifiers of albums. Maximum fetch limit is 100.

    completion

    Completion handler of request result of type Swift.Result<[LibraryAlbum], Error>

    result

    Result of request, .success([LibraryAlbum]) or .failure(Error)

  • Fetch all library albums by segments.

    Declaration

    Swift

    public func fetchAllLibraryAlbums(completion: @escaping (_ result: Swift.Result<([LibraryAlbum], FetchingStatus), Error>) -> Void)

    Parameters

    completion

    Completion handler of request result of type Swift.Result<([LibraryAlbum], FetchingStatus), Error>

    result

    Result of request, .success([LibraryAlbum], FetchingStatus) or .failure(Error)

Artists

  • Fetch a catalog artist using their identifier.

    Declaration

    Swift

    public func fetchACatalogArtist(storefront: String, artistID: String, completion: @escaping (_ result: Swift.Result<CatalogArtist, Error>) -> Void)

    Parameters

    storefront

    An identifier (ISO 3166 alpha-2 country codes) of the storefront which to perform request in

    artistID

    The unique identifier of the artist

    completion

    Completion handler of request result of type Swift.Result

    result

    Result of request, .success(CatalogArtist) or .failure(Error)

  • Fetch multiple catalog artists using their identifiers.

    Declaration

    Swift

    public func fetchMultipleCatalogArtists(storefront: String, artistIDs: [String], completion: @escaping (_ result: Swift.Result<[CatalogArtist], Error>) -> Void)

    Parameters

    storefront

    An identifier (ISO 3166 alpha-2 country codes) of the storefront which to perform request in

    artistIDs

    The unique identifiers of the artists. Maximum fetch limit is 25.

    completion

    Completion handler of request result of type Swift.Result<[CatalogArtist], Error>

    result

    Result of request, .success([CatalogArtist]) or .failure(Error)

  • Fetch the relationship of specified catalog artist using its identifier and relationship tag.

    Declaration

    Swift

    public func fetchACatalogArtistRelationship(storefront: String, artistID: String, relationship: String, completion: @escaping (_ result: Swift.Result<JSON, Error>) -> Void)

    Parameters

    storefront

    An identifier (ISO 3166 alpha-2 country codes) of the storefront which to perform request in

    artistID

    The unique identifier of the artist

    relationship

    The name tag of the relationship to fetch for this catalog artist

    completion

    Completion handler of request result of type Swift.Result

    result

    Result of request, .success(JSON) or .failure(Error)

  • Fetch a library artist using their identifier.

    Declaration

    Swift

    public func fetchALibraryArtist(artistID: String, completion: @escaping (_ result: Swift.Result<LibraryArtist, Error>) -> Void)

    Parameters

    artistID

    The unique identifier of the artist.

    completion

    Completion handler of request result of type Swift.Result

    result

    Result of request, .success(LibraryArtist) or .failure(Error)

  • Fetch the relationship of specified library artist using its identifier and relationship tag.

    Declaration

    Swift

    public func fetchALibraryArtistRelationship(artistID: String, relationship: String, completion: @escaping (Swift.Result<JSON, Error>) -> Void)

    Parameters

    artistID

    The unique identifier of the artist.

    relationship

    The name tag of the relationship to fetch for this library artist

    completion

    Completion handler of request result of type Swift.Result

    result

    Result of request, .success(JSON) or .failure(Error)

  • Fetch multiple library artists using their identifiers.

    Declaration

    Swift

    public func fetchMultipleLibraryArtists(artistIDs: [String], completion: @escaping (Swift.Result<[LibraryArtist], Error>) -> Void)

    Parameters

    artistIDs

    The unique identifiers of the artists. Maximum fetch limit is 25.

    completion

    Completion handler of request result of type Swift.Result<[LibraryArtist], Error>

    result

    Result of request, .success([LibraryArtist]) or .failure(Error)

  • Fetch all library artists by segments.

    Declaration

    Swift

    public func fetchAllLibraryArtists(completion: @escaping (_ result: Swift.Result<([LibraryArtist], FetchingStatus), Error>) -> Void)

    Parameters

    completion

    Completion handler of request result of type Swift.Result<([LibraryArtist], FetchingStatus), Error>

    result

    Result of request, .success([LibraryArtist], FetchingStatus) or .failure(Error)

Songs

  • Fetch a catalog song using its identifier

    Declaration

    Swift

    public func fetchACatalogSong(storefront: String, songID: String, completion: @escaping (_ result: Swift.Result<CatalogSong, Error>) -> Void)

    Parameters

    storefront

    An identifier (ISO 3166 alpha-2 country codes) of the storefront which to perform request in

    songID

    The unique identifier of the song.

    completion

    Completion handler of request result of type Swift.Result

    result

    Result of request, .success(CatalogSong) or .failure(Error)

  • Fetch multiple catalog songs using their identifiers.

    Declaration

    Swift

    public func fetchMultipleCatalogSongs(storefront: String, songIDs: [String], completion: @escaping (_ result: Swift.Result<[CatalogSong], Error>) -> Void)

    Parameters

    storefront

    An identifier (ISO 3166 alpha-2 country codes) of the storefront which to perform request in

    songIDs

    An array of the identifiers of the albums. Maximum fetch limit is 300.

    completion

    Completion handler of request result of type Swift.Result<[CatalogSong], Error>

    result

    Result of request, .success([CatalogSong]) or .failure(Error)

  • Fetch the relationship of specified catalog song using its identifier and relationship tag.

    Declaration

    Swift

    public func fetchACatalogSongRelationship(storefront: String, songID: String, relationship: String, completion: @escaping (_ result: Swift.Result<JSON, Error>) -> Void)

    Parameters

    storefront

    An identifier (ISO 3166 alpha-2 country codes) of the storefront which to perform request in

    songID

    The unique identifier of the song

    relationship

    The name tag of the relationship to fetch for this catalog song

    completion

    Completion handler of request result of type Swift.Result

    result

    Result of request, .success(JSON) or .failure(Error)

  • Fetch a library song using its identifier.

    Declaration

    Swift

    public func fetchALibrarySong(songID: String, completion: @escaping (_ result: Swift.Result<LibrarySong, Error>) -> Void)

    Parameters

    songID

    The unique identifier of the song

    completion

    Completion handler of request result of type Swift.Result

    result

    Result of request, .success(LibrarySong) or .failure(Error)

  • Fetch the relationship of specified library song using its identifier and relationship tag.

    Declaration

    Swift

    public func fetchALibrarySongRelationship(songID: String, relationship: String, completion: @escaping (_ result: Swift.Result<JSON, Error>) -> Void)

    Parameters

    songID

    The unique identifier of the song

    relationship

    The name tag of the relationship to fetch for this library song

    completion

    Completion handler of request result of type Swift.Result

    result

    Result of request, .success(JSON) or .failure(Error)

  • Fetch multiple library songs using their identifiers.

    Declaration

    Swift

    public func fetchMultipleLibrarySongs(songIDs: [String], completion: @escaping (_ result: Swift.Result<[LibrarySong], Error>) -> Void)

    Parameters

    songIDs

    An array of the identifiers of library songs. Maximum fetch limit is 300.

    completion

    Completion handler of request result of type Swift.Result<[LibrarySong], Error>

    result

    Result of request, .success([LibrarySong]) or .failure(Error)

  • Fetch all library songs by segments.

    Declaration

    Swift

    public func fetchAllLibrarySongs(completion: @escaping (_ result: Swift.Result<([LibrarySong], FetchingStatus), Error>) -> Void)

    Parameters

    completion

    Completion handler of request result of type Swift.Result<([LibrarySong], FetchingStatus), Error>

    result

    Result of request, .success([LibrarySong], FetchingStatus) or .failure(Error)

Music Videos(MV)

  • Fetch a catalog music video using its identifier.

    Declaration

    Swift

    public func fetchACatalogMV(storefront: String, mvID: String, completion: @escaping (_ result: Swift.Result<CatalogMV, Error>) -> Void)

    Parameters

    storefront

    An identifier (ISO 3166 alpha-2 country codes) of the storefront which to perform request in

    mvID

    The unique identifier of the music video

    completion

    Completion handler of request result of type Swift.Result

    result

    Result of request, .success(CatalogMV) or .failure(Error)

  • Fetch the relationship of specified catalog music video using its identifier and relationship tag.

    Declaration

    Swift

    public func fetchACatalogMVRelationship(storefront: String, mvID: String, relationship: String, completion: @escaping (_ result: Swift.Result<JSON, Error>) -> Void)

    Parameters

    storefront

    An identifier (ISO 3166 alpha-2 country codes) of the storefrontwhich to perform request in

    mvID

    The unique identifier of the music video

    relationship

    The name tag of the relationship to fetch for this catalog music video

    completion

    Completion handler of request result of type Swift.Result

    result

    Result of request, .success(JSON) or .failure(Error)

  • Fetch multiple catalog music videos using their identifiers.

    Declaration

    Swift

    public func fetchMultipleCatalogMVs(storefront: String, mvIDs: [String], completion: @escaping (_ result: Swift.Result<[CatalogMV], Error>) -> Void)

    Parameters

    storefront

    An identifier (ISO 3166 alpha-2 country codes) of the storefront which to perform request in

    mvIDs

    An array of the identifiers of the music videos. Maximum fetch limit is 100.

    completion

    Completion handler of request result of type Swift.Result<[CatalogMV], Error>

    result

    Result of request, .success([CatalogMV]) or .failure(Error)

  • Fetch a library music video using its identifier.

    Declaration

    Swift

    public func fetchALibraryMV(mvID: String, completion: @escaping (_ result: Swift.Result<LibraryMV, Error>) -> Void)

    Parameters

    mvID

    The unique identifier of the music video

    completion

    Completion handler of request result of type Swift.Result

    result

    Result of request, .success(LibraryMV) or .failure(Error)

  • Fetch the relationship of specified library music video using its identifier and relationship tag.

    Declaration

    Swift

    public func fetchALibraryMVRelationship(mvID: String, relationship: String, completion: @escaping (_ result: Swift.Result<JSON, Error>) -> Void)

    Parameters

    mvID

    The unique identifier of the music video

    relationship

    The name tag of the relationship to fetch for this library music video

    completion

    Completion handler of request result of type Swift.Result

    result

    Result of request, .success(JSON) or .failure(Error)

  • Fetch multiple library music videos using their identifiers.

    Declaration

    Swift

    public func fetchMultipleLibraryMVs(mvIDs: [String], completion: @escaping (_ result: Swift.Result<[LibraryMV], Error>) -> Void)

    Parameters

    mvIDs

    An array of the identifiers of music videos. Maximum fetch limit is 100.

    completion

    Completion handler of request result of type Swift.Result<[LibraryMV], Error>

    result

    Result of request, .success([LibraryMV]) or .failure(Error)

  • Fetch all library music videos by segments.

    Declaration

    Swift

    public func fetchAllLibraryMVs(completion: @escaping (_ result: Swift.Result<([LibraryMV], FetchingStatus), Error>) -> Void)

    Parameters

    completion

    Completion handler of request result of type Swift.Result<([LibraryMV], FetchingStatus), Error>

    result

    Result of request, .success([LibraryMV], FetchingStatus) or .failure(Error)

Playlist

  • Fetch a catalog playlist using its identifier

    Declaration

    Swift

    public func fetchACatalogPlaylist(storefront: String, playlistID: String, completion: @escaping (_ result: Swift.Result<CatalogPlaylist, Error>) -> Void)

    Parameters

    storefront

    An identifier (ISO 3166 alpha-2 country codes) of the storefront which to perform request in

    playlistID

    The unique identifier of the playlist

    completion

    Completion handler of request result of type Swift.Result

    result

    Result of request, .success(CatalogPlaylist) or .failure(Error)

  • Fetch the relationship of specified catalog album using its identifier and relationship tag.

    Declaration

    Swift

    public func fetchACatalogPlaylistRelationship(storefront: String, playlistID: String, relationship: String, completion: @escaping (_ result: Swift.Result<JSON, Error>) -> Void)

    Parameters

    storefront

    An identifier (ISO 3166 alpha-2 country codes) of the storefront which to perform request in

    playlistID

    The unique identifier of the playlist

    relationship

    The name tag of the relationship to fetch for this catalog playlist

    completion

    Completion handler of request result of type Swift.Result

    result

    Result of request, .success(JSON) or .failure(Error)

  • Fetch multiple catalog playlists using their identifiers.

    Declaration

    Swift

    public func fetchMultipleCatalogPlaylists(storefront: String, playlistIDs: [String], completion: @escaping (_ result: Swift.Result<[CatalogPlaylist], Error>) -> Void)

    Parameters

    storefront

    An identifier (ISO 3166 alpha-2 country codes) of the storefront which to perform request in

    playlistIDs

    An array of the identifiers of playlists. Maximum fetch limit is 25.

    completion

    Completion handler of request result of type Swift.Result<[CatalogPlaylist], Error>

    result

    Result of request, .success([CatalogPlaylist]) or .failure(Error)

  • Fetch a library playlist using its identifier

    Declaration

    Swift

    public func fetchALibraryPlaylist(playlistID: String, completion: @escaping (_ result: Swift.Result<LibraryPlaylist, Error>) -> Void)

    Parameters

    playlistID

    The unique identifier of the playlist.

    completion

    Completion handler of request result of type Swift.Result

    result

    Result of request, .success(LibraryPlaylist) or .failure(Error)

  • Fetch the relationship of specified library playlist using its identifier and relationship tag.

    Declaration

    Swift

    public func fetchALibraryPlaylistRelationship(playlistID: String, relationship: String, completion: @escaping (_ result: Swift.Result<JSON, Error>) -> Void)

    Parameters

    playlistID

    The unique identifier of the playlist

    relationship

    The name tag of the relationship to fetch for this library playlist

    completion

    Completion handler of request result of type Swift.Result

    result

    Result of request, .success(JSON) or .failure(Error)

  • Fetch multiple library playlists using their identifiers.

    Declaration

    Swift

    public func fetchMultipleLibraryPlaylists(storefront: String, playlistIDs: [String], completion: @escaping (_ result: Swift.Result<[LibraryPlaylist], Error>) -> Void)

    Parameters

    playlistIDs

    An array of the identifiers of playlists. Maximum fetch limit is 25.

    completion

    Completion handler of request result of type Swift.Result<[LibraryPlaylist], Error>

    result

    Result of request, .success([LibraryPlaylist]) or .failure(Error)

  • Fetch all library playlists by segments.

    Declaration

    Swift

    public func fetchAllLibraryPlaylists(completion: @escaping (_ result: Swift.Result<([LibraryPlaylist], FetchingStatus), Error>) -> Void)

    Parameters

    completion

    Completion handler of request result of type Swift.Result<([LibraryPlaylist], FetchingStatus), Error>

    result

    Result of request, .success([LibraryPlaylist], FetchingStatus) or .failure(Error)

  • Create a new library playlist.

    Declaration

    Swift

    public func createAPlaylist(name: String, description: String?, songsIDs: [String], completion: @escaping (_ result: Swift.Result<String, Error>) -> Void)

    Parameters

    name

    The name of playlist to be created

    description

    Optional. The description of the playlist to be created

    songsIDs

    An array of identifiers of songs to be contained in the playlist

    completion

    Completion handler of request result of type Swift.Result

    result

    Result of request, .success(status) or .failure(Error)

  • Add songs to a library playlist owned by the user, using their identifiers

    Declaration

    Swift

    public func addTracksToAPlaylist(playlistID: String, songsIDs: [String], completion: @escaping (_ result: Swift.Result<String, Error>) -> Void)

    Parameters

    playlistID

    The unique identifier of the playlist

    songsIDs

    An array of identifiers of songs to be added to the playlist

    completion

    Completion handler of request result of type Swift.Result

    result

    Result of request, .success(status) or .failure(Error)

Stations

  • Fetch a catalog station using its identifier.

    Declaration

    Swift

    public func fetchACatalogStation(storefront: String, stationID: String, completion: @escaping (_ result: Swift.Result<CatalogStation, Error>) -> Void)

    Parameters

    storefront

    An identifier (ISO 3166 alpha-2 country codes) of the storefront which to perform request in

    stationID

    The unique identifier of the station

    completion

    Completion handler of request result of type Swift.Result

    result

    Result of request, .success(CatalogStation) or .failure(Error)

  • Fetch multiple catalog stations using their identifiers.

    Declaration

    Swift

    public func fetchMultipleCatalogStations(storefront: String, stationIDs: [String], completion: @escaping (_ result: Swift.Result<[CatalogStation], Error>) -> Void)

    Parameters

    storefront

    An identifier (ISO 3166 alpha-2 country codes) of the storefront which to perform request in

    stationIDs

    An array of the identifiers of the stations. Maximum fetch limit is 100.

    completion

    Completion handler of request result of type Swift.Result<[CatalogStation], Error>

    result

    Result of request, .success([CatalogStation]) or .failure(Error)