now_playing - PythonIDE Docs

锁屏与控制中心「正在播放」元数据：标题、艺术家、封面、进度。配合 sound 或 avplayer 播放自有音频时使用。

边界：只发布元数据到系统 Now Playing 卡片，不替代音频播放本身。未实际播放时卡片可能不出现；远程流媒体优先用 avplayer 自带控制。

#模块概览

项	说明
导入	`import now_playing`
适合做什么	播客/音乐 App 锁屏信息、进度条同步
调用时机	开始播放后 `set_info`；进度变化时 `update_elapsed`
推荐顺序	开始播放 → `set_info` → 定时/回调 `update_elapsed` → 结束 `clear`
封面	`artwork_path` 为本地图片路径，无效则只显示文字

#快速开始

发布元数据并更新进度：

python

import now_playing

try:
    now_playing.set_info(
        title="第一集",
        artist="播客名称",
        album="第一季",
        duration=3600,
        elapsed=120,
        artwork_path="/path/cover.jpg",
    )
    now_playing.update_elapsed(180)
finally:
    now_playing.clear()

#AppUI 示例

元数据发布与进度更新放在按钮回调；配合本地播放时卡片更稳定。

python

import appui
import now_playing

state = appui.State(
    title="PythonIDE 演示",
    artist="播客",
    elapsed="120",
    status="未发布",
)

session = {"elapsed": 120.0, "duration": 3600.0}


def publish_card():
    session["elapsed"] = float(state.elapsed) if state.elapsed else 0.0
    now_playing.set_info(
        title=state.title,
        artist=state.artist,
        duration=session["duration"],
        elapsed=session["elapsed"],
    )
    state.status = "已发布到锁屏卡片"


def advance_progress():
    session["elapsed"] = min(session["elapsed"] + 30, session["duration"])
    state.elapsed = str(int(session["elapsed"]))
    now_playing.update_elapsed(session["elapsed"])
    state.status = f"进度 {int(session['elapsed'])}s"


def clear_card():
    now_playing.clear()
    state.status = "已清除"


def body():
    return appui.NavigationStack(
        appui.Form([
            appui.Section("元数据", [
                appui.TextField("标题", text=state.title),
                appui.TextField("艺术家", text=state.artist),
                appui.TextField("进度（秒）", text=state.elapsed),
            ]),
            appui.Section("控制", [
                appui.Button("发布到锁屏", action=publish_card)
                .button_style("bordered_prominent"),
                appui.Button("进度 +30 秒", action=advance_progress),
                appui.Button("清除", action=clear_card, role="destructive"),
            ]),
            appui.Section("状态", [
                appui.Text(state.status).foreground_color("secondaryLabel"),
            ], footer="需配合 sound/avplayer 实际播放，锁屏卡片才稳定出现。"),
        ]).navigation_title("正在播放")
    )


appui.run(body, state=state)

#API 参考

#速查

API	作用
`set_info(title, artist='', album='', duration=0, elapsed=0, artwork_path=None, playback_rate=1.0)`	发布完整元数据
`update_elapsed(seconds, playback_rate=1.0)`	仅更新已播放秒数
`clear()`	清除锁屏卡片信息
`NowPlayingError`	原生能力入口失败异常

#set_info

python

now_playing.set_info(
    title="曲目名",
    artist="歌手",
    album="专辑",
    duration=240.0,
    elapsed=12.0,
    artwork_path="/path/cover.jpg",
    playback_rate=1.0,
)

参数	说明
`duration` / `elapsed`	总时长与当前进度（秒）
`artwork_path`	本地封面图路径，可选
`playback_rate`	播放速率，暂停时可设 `0`

#update_elapsed / clear

python

now_playing.update_elapsed(95.5)
now_playing.clear()

#常见错误

错误写法	后果	修正
只 `set_info` 不播放音频	锁屏卡片可能不出现	配合 `sound.Player` 或 `avplayer`
封面路径无效	无封面图	检查沙盒内文件路径
忘记 `clear()`	停止后仍显示旧信息	播放结束或页面关闭时清除
在 `body()` 里自动发布	每次刷新重复设置	放进按钮或播放回调

#相关文档

文档	用途
sound	本地音频播放
avplayer	音视频流播放
audio_session	音频会话类别

#预期效果

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