music - PythonIDE Docs

Apple Music 播放控制与曲库搜索：播放/暂停、切歌、当前曲目、目录检索（MusicKit）。

边界：控制系统 Apple Music 播放与目录搜索，不播放本地文件。需 MusicKit 授权；无订阅时搜索仍可用，播放需要有效 Apple Music 订阅。必须先 play_song() / play_songs() 设置队列，再 play() 继续播放。

#模块概览

项	说明
导入	`import music`
适合做什么	播放控制面板、曲库搜索、显示正在播放
调用时机	播放/搜索放在按钮回调
推荐顺序	`request_authorization()` → `search()` → `play_song(id)`
授权	`authorization_status()` 查询；`request_authorization()` 弹窗

#快速开始

申请授权、搜索并播放第一首：

python

import music

print("授权状态:", music.authorization_status())
if music.request_authorization():
    results = music.search("Beatles", limit=5)
    if results:
        music.play_song(results[0]["id"])
        print("正在播放:", music.current_track())

暂停与继续：

python

import music

music.pause()
music.play()   # 仅当队列里已有曲目时可用

#AppUI 示例

先搜索保存曲目 ID，再播放；play() 只用于暂停后继续。

python

import appui
import music

state = appui.State(
    auth="—",
    track="—",
    search_hit="—",
    queued_song_id="",
)


def refresh_auth():
    state.auth = music.authorization_status()


def request_auth():
    ok = music.request_authorization()
    refresh_auth()
    state.search_hit = "已授权" if ok else "未授权"


def search_demo():
    refresh_auth()
    if state.auth != "authorized":
        state.search_hit = "请先授权"
        return

    songs = music.search("钢琴", limit=3) or []
    if not songs:
        state.search_hit = "无结果"
        state.queued_song_id = ""
        return

    first = songs[0]
    state.queued_song_id = str(first.get("id") or "")
    state.search_hit = f"{first.get('title')} — {first.get('artist')}"


def play_selected():
    refresh_auth()
    if state.auth != "authorized":
        state.search_hit = "请先授权"
        return
    if not state.queued_song_id:
        state.search_hit = "请先搜索曲目"
        return

    try:
        music.play_song(state.queued_song_id)
        track = music.current_track()
        if track:
            state.track = f"{track.get('title')} — {track.get('artist')}"
        else:
            state.track = "已开始播放"
        state.search_hit = "播放中"
    except music.MusicError as err:
        state.search_hit = str(err)
        if err.code == "subscription_required":
            state.track = "需要 Apple Music 订阅"


def resume_playback():
    try:
        music.play()
        track = music.current_track()
        if track:
            state.track = f"{track.get('title')} — {track.get('artist')}"
        state.search_hit = "继续播放"
    except music.MusicError as err:
        state.search_hit = str(err)


def pause_track():
    music.pause()
    state.track = "已暂停"


def body():
    return appui.NavigationStack(
        appui.Form([
            appui.Section("授权", [
                appui.Button("申请 MusicKit 授权", action=request_auth)
                .button_style("bordered_prominent"),
            ]),
            appui.Section("控制", [
                appui.Button("搜索「钢琴」", action=search_demo),
                appui.Button("播放搜索结果", action=play_selected)
                .button_style("bordered_prominent"),
                appui.Button("继续播放", action=resume_playback),
                appui.Button("暂停", action=pause_track),
            ]),
            appui.Section("状态", [
                appui.LabeledContent("授权", value=state.auth),
                appui.LabeledContent("正在播放", value=state.track),
                appui.LabeledContent("搜索", value=state.search_hit),
            ], footer="播放前需先搜索；无订阅时可能返回 subscription_required。"),
        ]).navigation_title("Apple Music")
    )


appui.run(body, state=state)

#API 参考

#速查

API	作用
`authorization_status()`	`not_determined` / `denied` / `restricted` / `authorized`
`request_authorization()`	申请授权 → `bool`
`search(term, limit=25)`	曲库搜索 → `[{id, title, artist, album}, ...]`
`play_song(song_id)`	用目录 ID 建队列并播放（推荐）
`play_songs(song_ids)`	多首入队并播放
`play_search_result(song)`	播放 `search()` 返回的单条 dict
`play()`	继续播放当前队列（队列空 → `empty_queue`）
`pause()`	暂停
`skip_to_next()` / `skip_to_previous()`	切歌
`current_track()`	`{'id','title','artist','album','duration'}` 或 `None`

#授权

python

status = music.authorization_status()
if music.request_authorization():
    ...

#搜索与播放

python

songs = music.search("Beatles", limit=10)
music.play_song(songs[0]["id"])
# 或
music.play_search_result(songs[0])

music.pause()
music.play()   # resume
track = music.current_track()

失败抛 MusicError，常见 code：

code	含义
`denied`	未授权
`empty_queue`	队列空时调用了 `play()`
`not_found`	目录 ID 无效
`subscription_required`	可能需要 Apple Music 订阅
`playback_failed`	其他播放错误

#常见错误

错误写法	后果	修正
未授权就 `search` / `play_song`	`MusicError: denied`	先 `request_authorization()`
直接 `play()` 不搜歌	`empty_queue`	先 `play_song(id)`
期望播放本地 MP3	能力不匹配	用 avplayer
无订阅强行播放	`subscription_required`	开通 Apple Music 或只展示搜索结果

#相关文档

文档	用途
avplayer	本地/网络音视频播放
audio_session	音频会话配置

#预期效果

运行示例后，界面应出现文档描述的目标结果；若与预期不符，先看「失败路径」并按返回值或日志排查。