shazam - PythonIDE Docs

听歌识曲（ShazamKit）：通过麦克风识别正在播放的歌曲，或从本地音频片段匹配曲库。

边界：需要 iOS 17+，并在 Apple Developer 为 app.pythonide 的 App Services 中开启 ShazamKit（与 Capabilities 是两项配置）。实时识曲需要麦克风权限；recognize_file() 只需可读音频文件。与 speech_recognition（语音转文字）和 music（Apple Music 播放控制）用途不同。

#模块概览

项	说明
导入	`import shazam`
适合做什么	「这是什么歌」、哼唱/外放识曲、短音频片段匹配
调用时机	`recognize()` / `recognize_file()` 放在按钮回调
推荐顺序	`is_available()` → 申请麦克风（实时模式）→ `recognize()`
音频建议	实时模式默认听 8 秒；文件模式建议 3–12 秒清晰片段
联网	需要网络访问 Shazam 曲库

#快速开始

下面脚本检查能力并尝试识曲（需在安静环境、有音乐播放时测试）：

python

import shazam

print("可用:", shazam.is_available())

try:
    song = shazam.recognize(duration=8)
    print(song["title"], "-", song["artist"])
    if song.get("apple_music_url"):
        print("Apple Music:", song["apple_music_url"])
except shazam.ShazamError as exc:
    print("识曲失败:", exc, f"(code={exc.code})")

从本地短音频识曲（不需麦克风）：

python

import shazam

try:
    song = shazam.recognize_file("/path/to/clip.m4a")
    print(song["title"], song.get("album", ""))
except shazam.ShazamError as exc:
    print(exc.code, exc)

#AppUI 示例

识曲请求放在按钮回调；进行中可显示状态，成功后展示歌名与封面链接字段。

python

import appui
import shazam

state = appui.State(
    title="—",
    artist="—",
    status="点击按钮开始识曲",
    artwork_url="",
)


def _show_song(song):
    state.title = song.get("title") or "—"
    state.artist = song.get("artist") or "—"
    state.artwork_url = song.get("artwork_url") or ""
    state.status = "识别成功"


def listen_now():
    if not shazam.is_available():
        state.status = "当前系统不支持 ShazamKit（需 iOS 17+）"
        return

    state.status = "聆听中…请播放音乐"

    try:
        song = shazam.recognize(duration=8)
        _show_song(song)
    except shazam.ShazamError as exc:
        if exc.code == "denied":
            state.status = "需要麦克风权限，请在系统设置中允许"
        elif exc.code == "no_match":
            state.status = "未识别到匹配歌曲，请靠近音源重试"
        elif exc.code == "shazamkit_auth":
            state.status = "ShazamKit 未在开发者后台开启，请配置后重装"
        else:
            state.status = f"识曲失败: {exc} (code={exc.code})"


def cancel_listen():
    shazam.cancel()
    state.status = "已取消"


def body():
    return appui.NavigationStack(
        appui.Form([
            appui.Section("结果", [
                appui.LabeledContent("歌曲", value=state.title),
                appui.LabeledContent("歌手", value=state.artist),
                appui.Text(state.status).font("caption").foreground_color("secondaryLabel"),
            ]),
            appui.Section("操作", [
                appui.Button("开始识曲（8 秒）", action=listen_now)
                .button_style("bordered_prominent"),
                appui.Button("取消", action=cancel_listen, role="destructive"),
            ], footer="需要 ShazamKit App Service、网络与麦克风；真机测试最可靠。"),
        ]).navigation_title("听歌识曲")
    )


appui.run(body, state=state)

#API 参考

#速查

API	作用
`is_available()`	是否支持 ShazamKit 实时识曲
`status()`	当前识别状态 `{recognizing, state}`
`recognize(duration=8)`	麦克风识曲 → `dict`
`recognize_file(path)`	本地音频文件识曲 → `dict`
`cancel()`	取消进行中的 `recognize()`
`ShazamError`	识曲失败时抛出

#识别结果字段

成功时返回字典，常见键：

键	说明
`matched`	是否匹配成功（`True`）
`title`	歌曲名
`artist`	艺术家
`album`	专辑（可能为空）
`shazam_id`	Shazam 媒体 ID
`genres`	风格列表
`apple_music_url`	Apple Music 链接（有则返回）
`artwork_url`	封面图 URL（有则返回）
`isrc`	ISRC（有则返回）
`web_url` / `video_url`	其他关联链接（有则返回）

#实时识曲

python

import shazam

song = shazam.recognize(duration=10)
print(song["title"], song["artist"])

参数	说明
`duration`	聆听秒数，自动限制在 3–20 秒

首次调用时系统可能弹出麦克风授权；拒绝后会抛 ShazamError(code="denied")。

#文件识曲

python

song = shazam.recognize_file("recording.m4a")

建议使用 3–12 秒、单声道/立体声均可的常见格式（m4a、wav、mp3 等）。片段太短会报 invalid_input。

#异常

失败时抛出 ShazamError，可通过 exc.code 区分：

`code`	含义
`unavailable`	系统版本低于 iOS 17，或 ShazamKit 不可用
`shazamkit_auth`	开发者后台未开启 ShazamKit App Service
`denied`	麦克风未授权（`recognize`）
`no_match`	未在曲库中找到匹配
`timeout`	聆听超时仍未匹配
`cancelled`	调用了 `cancel()`
`already_recognizing`	上一次 `recognize()` 尚未结束
`invalid_input`	文件路径无效、格式不支持或音频过短
`network_error`	网络或 Shazam 服务异常

python

try:
    shazam.recognize()
except shazam.ShazamError as exc:
    print(exc.code, exc)

#常见错误

错误写法	后果	修正
在 `body()` 里调 `recognize()`	每次刷新都开麦/联网	放进按钮回调，结果写进 `State`
未开 ShazamKit App Service	`shazamkit_auth`	在 Developer → App Services 勾选 ShazamKit 并重装
环境太吵或歌太短	`no_match` / `timeout`	靠近音源、延长 `duration` 或换更清晰的片段
用 1 秒文件去匹配	`invalid_input`	提供约 3–12 秒音频
不捕获 `ShazamError`	异常直接打断流程	用 `try/except` 并给出兜底 UI

#相关文档

文档	用途
music	Apple Music 播放与搜索
speech_recognition	语音转文字（非识曲）
audio_recorder	录制音频后再 `recognize_file`
permission	查询其他权限状态
原生能力入口	MiniApp 场景配方

#预期效果

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