{"id":13995042,"url":"https://github.com/rryam/MusadoraKit","last_synced_at":"2025-07-22T21:31:56.306Z","repository":{"id":37254288,"uuid":"392431254","full_name":"rryam/MusadoraKit","owner":"rryam","description":"The ultimate companion to MusicKit.","archived":false,"fork":false,"pushed_at":"2024-11-25T00:41:23.000Z","size":14035,"stargazers_count":344,"open_issues_count":0,"forks_count":22,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-11-29T17:14:02.322Z","etag":null,"topics":["apple-music-api","applemusic","ios","ios-swift","musickit","musickit-ios","swift","swift-library","swift5","swiftpackage"],"latest_commit_sha":null,"homepage":"http://exploringmusickit.com","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rryam.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"rryam"}},"created_at":"2021-08-03T19:24:28.000Z","updated_at":"2024-11-25T00:41:27.000Z","dependencies_parsed_at":"2023-02-15T11:15:34.555Z","dependency_job_id":"777e6014-8628-4528-a6fa-d26feabe7b3a","html_url":"https://github.com/rryam/MusadoraKit","commit_stats":{"total_commits":437,"total_committers":4,"mean_commits":109.25,"dds":"0.013729977116704761","last_synced_commit":"5cb3db81cef3afb45fe99c4c35b84166ba6319ea"},"previous_names":[],"tags_count":74,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rryam%2FMusadoraKit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rryam%2FMusadoraKit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rryam%2FMusadoraKit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rryam%2FMusadoraKit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rryam","download_url":"https://codeload.github.com/rryam/MusadoraKit/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227174083,"owners_count":17742400,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apple-music-api","applemusic","ios","ios-swift","musickit","musickit-ios","swift","swift-library","swift5","swiftpackage"],"created_at":"2024-08-09T14:03:13.504Z","updated_at":"2024-11-29T17:30:53.936Z","avatar_url":"https://github.com/rryam.png","language":"Swift","funding_links":["https://github.com/sponsors/rryam"],"categories":["Swift"],"sub_categories":[],"readme":"# MusadoraKit\n\nMusadoraKit (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.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src= \"https://github.com/rryam/MusadoraKit/blob/main/MusadoraKitIcon.png\" alt=\"MusadoraKit Logo\" width=\"256\"/\u003e\n\u003c/p\u003e\n\nMusadoraKit 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.\n\nIt goes well with my book on [*Exploring MusicKit and Apple Music API*](https://rudrank.gumroad.com/l/musickit), as all the documentation and references are mentioned in the book. Otherwise, the code itself is well documented.\n\nAlso, join the [Discord Community](https://discord.gg/6KaKCKds) for discussing anything about MusadoraKit, the book \"Exploring MusicKit\", MusicKit or your favorite music!\n\n## Exploring MusicKit and Apple Music API Book \n\nYou can support my open-source by buying my book, [\"Exploring MusicKit and Apple Music API\"](http://exploringmusickit.com). 2 books a day, and I can happily continue working on MusadoraKit.\n\n## Sponsors\n\n\u003cp align=\"leading\"\u003e\n  \u003cimg src= \"https://is3-ssl.mzstatic.com/image/thumb/Purple116/v4/cd/40/fe/cd40fe7c-b0f8-30aa-0b41-4a76e7968766/AppIcon-1x_U007emarketing-0-0-0-10-0-0-85-220.png/246x0w.webp\" alt=\"PlaylistAI Logo\" width=\"64\"/\u003e\n\u003c/p\u003e\n\n[PlaylistAI](https://twitter.com/playlist_ai) by [Brett Bauman](https://twitter.com/brettunhandled)\n\n## [Documentation using DocC](https://rryam.github.io/MusadoraKit/documentation/musadorakit/)\n\n## Musadora Sample App\nI am open-sourcing an app I worked on last year called Musadora. (MusadoraKit started as RRMusicKit for the Musadora app!) \n\nI 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.\n\n## Apps Using MusadoraKit\n\n- [Music Mate](https://apps.apple.com/app/musicmate-music-map-friends/id1605379758): Meet music friends on the world map.\n- [Sonar](https://apps.apple.com/ca/app/sonar-music-community/id1626147292): Music \u0026 Community. Stream, Share \u0026 Discover\n- [Tuneder](https://apps.apple.com/us/app/tuneder-song-discovery/id6450867856?itsct=apps_box_badge\u0026itscg=30200): An [open-source](https://github.com/adityasaravana/Tuneder) iOS app that helps Apple Music users discover new songs with a Tinder-like UI.\n- Musadora: Apple Music client focused on playlists\n- Musadora Labs: A companion app to explore MusicKit\n- Euphonic: Apple Music client focused on recommendations\n- [bijou.fm](https://apps.apple.com/app/bijou-fm/id6450460066?platform=iphone): Last.fm client with Apple Music integration\n\n## Start Working with MusicKit \nFollow the steps below to setup MusicKit for your app:\n\n### Step 1: Enable MusicKit for Your Bundle Identifier\n1. Visit the [Apple Developer Portal](https://developer.apple.com/account).\n2. Navigate to `Certificates, Identifiers \u0026 Profiles`.\n3. Select `Identifiers` from the left panel.\n4. Find your App's Bundle Identifier from the list and select it.\n5. Under `Services`, ensure `MusicKit` is enabled. If not, enable it.\n\n### Step 2: Add `NSAppleMusicUsageDescription` to `Info.plist`\nTo inform the user why your app requires access to their media library, add `NSAppleMusicUsageDescription` to your `Info.plist` file.\n1. Open your project in Xcode.\n2. Select `Info.plist` from the Project Navigator.\n3. Click on the `+` button to add a new key.\n4. Add `NSAppleMusicUsageDescription` as a key.\n5. 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.`.\n\n### Step 3: Request Authorization for Apple Music\nBefore your app can interact with Apple Music, it needs to request the user's authorization. This can be done using `MusicAuthorization.request()`. \n\nHere's a Swift code example:\n\n```swift\nimport MusicKit\n\nclass MusicAuthorizationManager: ObservableObject {\n    @Published var isAuthorizedForMusicKit = false\n    @Published var musicKitError: MusicKitError?\n\n    func requestMusicAuthorization() async {\n        let status = await MusicAuthorization.request()\n\n        switch status {\n        case .authorized:\n            isAuthorizedForMusicKit = true\n        case .restricted:\n            musicKitError = .restricted\n        case .notDetermined:\n            musicKitError = .notDetermined\n        case .denied:\n            musicKitError = .denied\n        @unknown default:\n            musicKitError = .notDetermined\n        }\n    }\n}\n```\n\nThis `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.\n\nRemember to call `requestMusicAuthorization()` at an appropriate time in your application flow to request the user's authorization.\n\n## Catalog \n\nTo easily access the Apple Music Catalog, you can use pre-defined methods from MusadoraKit. The methods are similar across the music items. \n\nExample of working with fetching a catalog song by its identifier: \n\n```swift \nlet song = try await MCatalog.song(id: \"1613834314\", with: [.albums])\n```\n\n## Searching the Catalog\n\nExample of searching the catalog: \n\n```swift \nlet searchResponse = try await MCatalog.search(for: \"the weeknd\", types: [.songs, .stations, .albums, .playlists, .artists], limit: 10)\n\nprint(searchResponse.songs)\nprint(searchResponse.artists)\n```\n\n## Library \n\nWhile 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. \n\nExample of fetching all library songs in alphabetical order: \n\n```swift \nlet songs = try await MLibrary.songs()\n```\n\nExample of searching the user's library: \n\n```swift \nlet searchResponse = try await MLibrary.search(for: \"hello\", types: [Song.self])\n\nprint(searchResponse.songs)\n```\n\n## Recommendations \n\nYou can take advantage of Apple's Music recommendation system and use it in your app. For example, to fetch the default recommendations: \n\n```swift \nlet recommendations = try await MRecommendation.default()\n\nguard let recommendation = recommendations.first else { return }\n\nprint(recommendation.albums)\nprint(recommendation.playlists)\nprint(recommendation.stations)\n```\n\n## History \n\nYou can also fetch historial data from the user's library. For example, to get the recently played resources: \n\n```swift \nlet recentlyPlayedItems = try await MLibrary.recentlyPlayed()\n\nlet recentlyPlayedAlbums = try await MLibrary.recentlyPlayedAlbums()\n}\n```\n\n## Referencing content across different geographical regions\n\nIn the example below, the target storefront is \"jp\" for Japan:\n\n```swift\nlet album = MCatalog.album(id: \"1223618217\")\nlet equivalentAlbum = try await album.equivalent(for: \"jp\")\n\nlet albums = MCatalog.albums(ids: [\"1223618217\", \"1603171516\"])\nlet equivalentAlbums = try await albums.equivalents(for: \"jp\")\n```\n\n## Explicit to clean-equivalent content:\n\n```swift\nlet song = MCatalog.song(id: \"1603171970\")\nlet cleanSong = try await song.clean\n\nlet songs = MCatalog.songs(ids: [\"1603171970\", \"1531327246\"])\nlet cleanSongs = try await songs.clean\n```\n\n## MusicCatalogResourcesRequest: \n\nTo fetch multiple catalog music items by their identifiers in the same request. For example:\n\n```swift \nlet request = MusicCatalogResourcesRequest(types: [.songs: [\"1456313177\"], .albums: [\"1531125029\", \"1575203352\"]])\nlet response = try await request.response()\n\nprint(response.songs)\nprint(response.albums)\n```\n\n## MusicLibraryResourcesRequest:\n\nTo fetch multiple library music items by their identifiers in the same request. For example:\n\n```swift\nlet request = MusicLibraryResourcesRequest(types: [.songs: [\"i.pmzqzM0S2rl5N4L\"], .playlists: [\"p.PkxVBgps2zOdV3r\"]])\nlet response = try await request.response()\n\nprint(response.songs)\nprint(response.playlists)\n```\n\nI hope you love working with MusadoraKit!\n\n\u003e To my future self, and to every developer whose life my code may touch:  \nI just have a lot to write, and will keep writing until the end, hoping to leave something good behind.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frryam%2FMusadoraKit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frryam%2FMusadoraKit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frryam%2FMusadoraKit/lists"}