SuperAPI AI 工具集

apple-music-2

通用与其它

查看项目

更新于 10-16 06:00

技能介绍

Apple Music 集成指南

本文档介绍如何与 Apple Music 进行集成,覆盖两种技术路径:AppleScript(macOS)与 MusicKit API(跨平台),并强调一条关键规则——曲库优先。

使用场景

当用户提出以下需求时适用:管理播放列表(创建、添加或移除曲目、列出);控制播放(播放、暂停、跳过、音量);搜索目录或曲库;将歌曲添加到曲库;访问收听历史或推荐内容。

关键规则:曲库优先工作流

不能将目录歌曲直接添加到播放列表。歌曲必须先存在于用户曲库中:

错误:目录 ID → 播放列表(失败) 正确:目录 ID → 曲库 → 播放列表(可行)

原因:播放列表使用曲库 ID(i.abc123),而非目录 ID(1234567890)。此规则对 AppleScript 和 API 两种方式均适用。

平台对比

配置要求:AppleScript 无需配置;MusicKit API 需要开发者账号与令牌。 播放列表管理:AppleScript 支持完整操作;MusicKit API 仅支持 API 创建的播放列表。 播放控制:AppleScript 支持完整控制;MusicKit API 不支持。 目录搜索:AppleScript 不支持;MusicKit API 支持。 曲库访问:AppleScript 即时可用;MusicKit API 需令牌。 跨平台:AppleScript 仅 macOS;MusicKit API 支持跨平台。

AppleScript(macOS)

零配置,可直接与 Music 应用配合使用。通过 Bash 运行,例如使用 osascript 命令控制播放暂停或获取当前曲目名称,也支持多行脚本。

可执行操作类别包括:播放控制(播放、暂停、停止、恢复、下一曲、上一曲、快进、快退);播放器状态(播放位置、播放状态、音量、静音、随机播放开关与模式、重复模式);当前曲目信息(名称、艺术家、专辑、时长、评分、喜爱/不喜欢状态、流派、年份、曲目编号);曲库(搜索、列出曲目、获取曲目属性、设置评分);播放列表(列出、创建、删除、重命名、添加曲目、移除曲目、获取曲目);AirPlay(列出设备、选择设备、当前设备)。

曲目属性支持读取与写入,包括名称、艺术家、专辑、作曲、流派、年份、时长、曲目编号、评分(0-100,每星 20)、喜爱与不喜欢标记、播放次数、跳过次数、持久 ID 与数据库 ID 等。播放器状态属性如播放位置、音量、静音、随机模式、重复模式可读可写。

曲库查询支持按名称、艺术家、专辑、流派、年份、评分、喜爱状态、最近播放日期等条件筛选。播放列表操作支持创建、删除、重命名、获取曲目、添加与移除曲目,并可通过复制曲库曲目实现添加。AirPlay 部分支持列出设备、获取与设置输出设备,以及多设备输出。

字符串转义:始终需要转义用户输入,文档提供了 Python 转义示例。

限制:无目录访问权限,仅能操作曲库内容;仅限 macOS,不支持 Windows/Linux。

MusicKit API

跨平台,但需要 Apple 开发者账号(每年 99 美元)和令牌配置。鉴权要求包括开发者账号、开发者门户的 MusicKit 密钥(.p8 文件)、开发者令牌(JWT,最长 180 天)、用户音乐令牌(浏览器 OAuth)。文档给出了开发者令牌的生成代码示例,并说明用户令牌通过浏览器 OAuth 获取,以及所有请求所需请求头与基础 URL。

可用端点分为:目录(公开,仅需开发者令牌,含搜索、歌曲/专辑/艺术家详情、专辑曲目、艺术家专辑与热门歌曲、相似艺术家、播放列表、排行榜、流派、搜索建议、电台);曲库(需用户令牌,含歌曲、专辑、艺术家、播放列表、播放列表曲目、曲库搜索、添加到曲库、由目录 ID 获取曲库 ID);播放列表管理(创建、添加曲目);个性化(推荐、高频播放、最近播放、最近添加);评分(歌曲/专辑/播放列表的查询、设置、删除评分);以及商店地区(Storefronts)相关端点。

常用查询参数包括 term、types、limit(最大 25)、offset、include、extend、l。文档给出了搜索请求与响应示例。

曲库优先工作流(完整):将目录歌曲添加到播放列表需要 4 次 API 调用——搜索目录、添加到曲库、获取曲库 ID、添加到播放列表。文档提供了完整 Python 请求示例。此外还给出了创建播放列表和设置评分的请求格式。

限制:无播放控制(API 无法播放/暂停/跳过);播放列表编辑仅限 API 创建的播放列表;令牌管理(开发者令牌每 180 天过期);Apple 实施请求速率限制。

常见错误:在播放列表中使用目录 ID;通过 AppleScript 播放目录歌曲;未转义的 AppleScript 字符串;令牌过期。

更简便的方式:mcp-applemusic

mcp-applemusic MCP 服务器可自动处理 AppleScript 转义、令牌管理、曲库优先工作流和 ID 转换等复杂环节。文档提供了克隆、安装与 Claude Desktop 配置示例,并说明在 macOS 上大部分功能可立即使用,目录功能或 Windows/Linux 需参考仓库 README。