WWDC Quick Look 💓 By SwiftGGTeam
中文 EN 日本語
Meet Apple Music API and MusicKit

Meet Apple Music API and MusicKit

Apple MusicMusicKitAPIAudio
观看原视频

Highlight

Apple Music API 和 MusicKit 让开发者可以在 iOS、Web 和 Android 三个平台上集成 Apple Music 功能，包括目录搜索、内容发现、播放控制和订阅用户的个性化推荐。

核心内容

一套 API，三个平台

以前，如果你想在 App 里集成音乐流媒体，需要自建曲库、处理版权、搭建 CDN。这对中小型开发者几乎不可能。

Apple Music API 提供了一套 RESTful JSON 接口，可以直接访问 Apple Music 的完整目录。配合 MusicKit 客户端框架，开发者可以在 iOS、Web 和 Android 上实现一致的音乐体验。

（00:51）

MusicKit 在各平台的分工：

  • Apple 平台：MusicKit 处理认证、播放控制和 API 调用，开发者几乎不需要直接操作底层网络请求。
  • Web：提供 JavaScript SDK 和内置组件（包括完整功能的媒体播放器）。
  • Android：提供 SDK 支持订阅者认证、播放控制和完整 API 访问。

获取访问权限

调用 Apple Music API 需要 Developer Token。不同平台的获取方式不同。

（03:42）

Apple 平台：在 Apple Developer Portal 的 App ID 中启用 MusicKit 服务，系统会自动管理 Token。

其他平台：在 Apple Developer Portal 注册为 MusicKit 开发者，下载私钥，然后生成 JWT（JSON Web Token）。

JWT 需要以下字段：

  • Header：alg 必须是 ES256，kid 是私钥标识符
  • Claims：iss（Team ID）、iat（签发时间）、exp（过期时间，最长 6 个月）
  • Web 应用建议加上 origin claim，限制 Token 只能在指定域名使用

请求资源

Apple Music API 的 URL 采用 RESTful 结构：

https://api.music.apple.com/v1/catalog/{storefront}/{resource-type}/{id}

（05:36）

  • v1 是 API 版本，保持向后兼容
  • {storefront} 是两字母国家代码，如 us、cn
  • {resource-type} 如 playlists、albums、songs
  • {id} 是资源的唯一标识

可选参数：

  • l：语言标签，如 en-US、es-MX
  • extend：请求扩展属性
  • include：包含关联资源的完整元数据

详细内容

获取播放列表

curl "https://api.music.apple.com/v1/catalog/us/playlists/pl.u-55D6ZEMId7y" \
  -H "Authorization: Bearer YOUR_DEVELOPER_TOKEN"

响应结构：

{
  "data": [
    {
      "id": "pl.u-55D6ZEMId7y",
      "type": "playlists",
      "href": "/v1/catalog/us/playlists/pl.u-55D6ZEMId7y",
      "attributes": {
        "name": "Today's Hits",
        "curatorName": "Apple Music",
        "description": {
          "standard": "The biggest songs right now."
        },
        "artwork": {
          "width": 1200,
          "height": 1200,
          "url": "https://example.mzstatic.com/image/{w}x{h}bb.jpg"
        },
        "playParams": {
          "id": "pl.u-55D6ZEMId7y",
          "kind": "playlist"
        }
      },
      "relationships": {
        "curator": {
          "href": "/v1/catalog/us/playlists/pl.u-55D6ZEMId7y/curator",
          "data": [{ "id": "123456789", "type": "apple-curators" }]
        },
        "tracks": {
          "href": "/v1/catalog/us/playlists/pl.u-55D6ZEMId7y/tracks",
          "data": [
            {
              "id": "1234567890",
              "type": "songs",
              "attributes": {
                "name": "Song Title",
                "artistName": "Artist Name",
                "durationInMillis": 234000
              }
            }
          ]
        }
      }
    }
  ]
}

关键点：

  • data 数组包含请求的资源
  • attributes 存放元数据（名称、描述、 artwork）
  • playParams 表示内容是否可供订阅者播放
  • relationships 包含关联资源（curator、tracks）
  • artwork.url 中的 {w} 和 {h} 需要替换为实际分辨率

加载 artwork

// 替换 artwork URL 中的尺寸占位符
let width = 400
let height = 400
let artworkURL = artwork.url
    .replacingOccurrences(of: "{w}", with: "\(width)")
    .replacingOccurrences(of: "{h}", with: "\(height)")

关键点：

  • artwork URL 包含 {w} 和 {h} 占位符
  • 替换为所需分辨率即可获取对应尺寸图片
  • 小尺寸图片文件更小，加载更快

分页处理

播放列表的 tracks 关系默认只返回前 100 首。如果超过 100 首，响应中会包含 next 字段：

{
  "relationships": {
    "tracks": {
      "href": "/v1/catalog/us/playlists/pl.xxx/tracks",
      "data": [...],
      "next": "/v1/catalog/us/playlists/pl.xxx/tracks?offset=100"
    }
  }
}

关键点：

  • 通过 next URL 获取下一页
  • 可以添加 limit 参数自定义每页大小
  • 始终使用响应中的 next URL，不要自己计算 offset
  • 当没有更多数据时，next 字段不存在

搜索目录

curl "https://api.music.apple.com/v1/catalog/us/search?term=pop&types=albums,songs&limit=10" \
  -H "Authorization: Bearer YOUR_DEVELOPER_TOKEN"

响应包含 results 对象，每个请求的类型对应一个结果组：

{
  "results": {
    "albums": {
      "href": "/v1/catalog/us/search?term=pop&types=albums",
      "data": [...],
      "next": "/v1/catalog/us/search?term=pop&types=albums&offset=10"
    },
    "songs": {
      "href": "/v1/catalog/us/search?term=pop&types=songs",
      "data": [...]
    }
  },
  "meta": {
    "results": {
      "order": ["albums", "songs"]
    }
  }
}

关键点：

  • types 参数限制搜索的内容类型
  • limit 控制每类型返回数量
  • meta.results.order 提供基于相关性的推荐排序
  • 每个结果组有自己的 next 分页链接

访问个性化功能

订阅用户可以通过 Music User Token 访问个性化数据：

curl "https://api.music.apple.com/v1/me/library/albums" \
  -H "Authorization: Bearer YOUR_DEVELOPER_TOKEN" \
  -H "Music-User-Token: USER_TOKEN"

关键点：

  • Music User Token 通过 MusicKit 的认证流程获取
  • 需要用户明确授权访问音乐数据
  • Token 与设备和 App 绑定，不能跨设备共享
  • Token 可能因订阅变化、密码修改或权限撤销而失效

核心启发

做一个跨平台音乐发现 App

  • 做什么：一个帮助用户发现新音乐的 Web App，结合 Apple Music 目录和社交推荐
  • 为什么值得做：Apple Music API 提供了完整的目录数据和搜索能力，开发者只需要专注发现算法和 UI
  • 怎么开始：用 JavaScript MusicKit SDK 初始化，调用 /v1/catalog/{storefront}/search 搜索，用 playParams 判断内容是否可播放

做一个音乐知识问答游戏

  • 做什么：通过播放歌曲片段让用户猜歌名、歌手或专辑的 trivia 游戏
  • 为什么值得做：Apple Music API 提供 artwork、歌曲元数据和预览片段，游戏内容天然丰富
  • 怎么开始：用搜索 API 获取歌曲，提取 artwork 和 artistName 作为题目素材，集成 MusicKit 播放器播放预览

做一个智能播放列表生成器

  • 做什么：根据用户的心情、活动或天气自动生成 Apple Music 播放列表
  • 为什么值得做：可以结合 Apple Music 的目录数据和用户的 library 数据，生成高度个性化的列表
  • 怎么开始：调用 /v1/me/recommendations 获取推荐，结合 /v1/catalog/{storefront}/search 按关键词补充歌曲，用 /v1/me/library/playlists 创建播放列表

做一个音乐学习辅助工具

  • 做什么：帮助音乐学生学习曲目，显示歌词、和弦、和歌曲结构
  • 为什么值得做：Apple Music API 提供准确的歌曲时长、艺术家信息，可以和学习内容精准匹配
  • 怎么开始：用搜索 API 定位歌曲，获取 durationInMillis 计算段落位置，集成播放器实现同步滚动

关联 Session

评论

GitHub Issues · utterances