PY-XIAOZHI

简体中文

English

简体中文

English

Appearance

音乐播放工具 (Music Tools) ​

音乐播放工具是一个功能丰富的 MCP 音乐播放器，支持在线搜索播放、本地音乐管理、歌词显示等功能。

常见使用场景 ​

搜索播放在线音乐:

  • "播放周杰伦的青花瓷"
  • "我想听邓紫棋的歌"
  • "放一首轻音乐"
  • "播放最新的流行歌曲"

播放控制:

  • "暂停音乐"
  • "继续播放"
  • "停止播放"
  • "音乐播放到一半了"

本地音乐管理:

  • "查看本地音乐"
  • "播放本地的那首歌"
  • "在本地音乐中搜索周杰伦"

播放状态查询（AI 会根据内部状态回答，暂无独立工具）:

  • "现在播放的是什么歌"
  • "播放进度怎么样"
  • "这首歌还有多长时间"

歌词功能:

  • "显示歌词"
  • "当前歌词是什么"
  • "有歌词吗"

高级功能:

  • "跳转到1分30秒"
  • "快进到高潮部分"
  • "回到开头"

使用提示 ​

  1. 明确歌曲信息: 提供歌名、歌手名或专辑名有助于更准确的搜索
  2. 网络连接: 在线搜索和播放需要稳定的网络连接
  3. 本地缓存: 播放过的歌曲会自动缓存，下次播放更快
  4. 音量控制: 可以要求调整音量或静音
  5. 歌词同步: 支持实时歌词显示，增强听歌体验

AI 助手会根据您的需求自动调用音乐播放工具，为您提供流畅的音乐体验。

功能概览 ​

在线音乐功能 ​

  • 智能搜索: 支持歌名、歌手、专辑等多种搜索方式
  • 高品质播放: 支持高品质音频流播放
  • 歌词显示: 实时同步歌词显示
  • 自动缓存: 播放过的歌曲自动缓存到本地

本地音乐管理 ​

  • 本地扫描: 自动扫描本地音乐文件
  • 元数据提取: 自动提取歌曲标题、艺术家、专辑等信息
  • 格式支持: 支持MP3、M4A、FLAC、WAV、OGG等多种格式
  • 智能搜索: 在本地音乐中快速搜索

播放控制功能 ​

  • 基础控制: 播放、暂停、停止
  • 进度控制: 跳转到指定时间位置
  • 状态同步: 通过控制工具返回值与事件推送同步播放进度
  • 错误处理: 完善的错误处理和恢复机制

用户体验功能 ​

  • UI集成: 与应用界面无缝集成
  • 实时反馈: 实时显示播放状态和歌词
  • 智能缓存: 优化存储空间使用
  • 后台播放: 支持后台持续播放

工具列表 ​

1. 在线音乐工具 ​

music_player.search_and_play - 搜索并播放在线音乐 ​

根据歌名、歌手或关键词调用在线音乐接口，下载并播放目标歌曲。若当前正在播放，会先停止再播放新歌。

参数:

  • song_name (必需): 要搜索的歌曲名称、歌手或关键词

使用场景:

  • 播放指定歌曲
  • 搜索歌手的全部或最新歌曲
  • 让 AI 推荐或播放流行歌曲

2. 播放控制工具 ​

music_player.pause - 暂停播放 ​

暂停当前歌曲并保留当前位置，适用于手动暂停或用户主动要求暂定的情况。

参数: 无

使用场景:

  • 暂停当前播放
  • 与 TTS 播报配合，提前手动暂停
  • 需要暂时静音的场景

music_player.resume - 恢复播放 ​

从暂停位置继续播放，仅在手动暂停后才会触发，避免与 TTS 的自动暂停冲突。

参数: 无

使用场景:

  • 用户说“继续播放”“恢复播放”
  • TTS 自动暂停后需要人工恢复
  • 确认音乐已经手动暂停

music_player.stop - 停止播放 ​

结束当前歌曲并重置播放进度，属于彻底停止操作。

参数: 无

使用场景:

  • 用户明确要求“停止/关闭音乐”
  • 切换会话或场景时需要清空播放状态
  • 避免后台继续播放

music_player.seek - 跳转播放位置 ​

跳转到歌曲的指定秒数位置，内部会重启解码器确保播放同步。

参数:

  • position (必需): 跳转位置（秒，>=0 的整数）

使用场景:

  • 快进到指定时间点
  • 回到歌曲开头或副歌
  • 按用户要求定位到特定片段

3. 歌词工具 ​

music_player.get_lyrics - 获取当前歌曲歌词 ​

返回带有时间戳的歌词文本列表，若无歌词则给出提示信息。

参数: 无

使用场景:

  • 用户想查看或跟唱歌词
  • 展示当前播放句子
  • 检查歌词是否可用

提示：播放器内部仍维护播放进度、暂停来源等状态，但 MCP 目前仅暴露控制类工具和歌词查询。

4. 本地音乐工具 ​

music_player.get_local_playlist - 获取本地缓存歌单 ​

扫描本地缓存目录，返回已下载歌曲列表。结果中的每一项形如“歌名 - 歌手”，可再次传给 music_player.search_and_play 播放。

参数:

  • force_refresh (可选): 是否强制重新扫描缓存目录，默认 false

使用场景:

  • 查看本地缓存内容
  • 根据缓存歌曲快速发起播放
  • 调试或验证缓存状态

使用示例 ​

在线音乐播放示例 ​

python
# 搜索并播放歌曲
result = await mcp_server.call_tool("music_player.search_and_play", {
    "song_name": "周杰伦 青花瓷"
})

# 暂停与恢复
await mcp_server.call_tool("music_player.pause", {})
await mcp_server.call_tool("music_player.resume", {})

# 停止播放
await mcp_server.call_tool("music_player.stop", {})

# 跳转到指定位置（单位：秒）
await mcp_server.call_tool("music_player.seek", {
    "position": 90
})

本地音乐管理示例 ​

python
# 获取本地音乐列表
playlist = await mcp_server.call_tool("music_player.get_local_playlist", {
    "force_refresh": True
})

# 从本地歌单中选择歌曲再次播放
if playlist.get("playlist"):
    first_song = playlist["playlist"][0].split(" - ")[0]
    await mcp_server.call_tool("music_player.search_and_play", {
        "song_name": first_song
    })

歌词查询示例 ​

python
lyrics = await mcp_server.call_tool("music_player.get_lyrics", {})

当前 MCP 接口尚未暴露独立的状态查询工具，播放进度类问题依赖 AI 助手维护的上下文和事件回调。

技术架构 ​

音乐播放器核心 ​

  • 单例模式: 通过 get_music_player_instance() 提供全局唯一实例，避免并发创建多个播放器。
  • FFmpeg + AudioCodec: 使用 MusicDecoder(FFmpeg) 解码音频，再交给统一的 AudioCodec 播放链路，保证采样率与声道配置一致。
  • 异步任务队列: 解码后的 PCM 数据通过 asyncio.Queue 传递给播放循环，避免阻塞主线程。
  • 事件驱动控制: 内置 EventBus 订阅暂停/恢复事件，AI 或系统可通过事件实现自动让路与恢复。

音频处理 ​

  • 高精度解码: MusicDecoder 按需拉起 FFmpeg 解码器，支持 MP3/M4A/FLAC/WAV/OGG 等主流格式。
  • 时间轴维护: 通过 ffprobe + 歌词时间戳获取准确时长，并在跳转/恢复时重新初始化解码器。
  • PCM 规范化: 解码输出保持 float32，并在写入 AudioCodec 前统一处理多声道为单声道。
  • 歌词同步: 独立的歌词任务根据当前时间动态推送歌词事件，保证显示同步。

在线服务集成 ​

  • TuneFree API: 统一通过 https://music-dl.sayqz.com/api/ 访问在线搜索、播放链接、歌词与歌曲信息。
  • 多平台支持: DEFAULT_SOURCE 可配置为 kuwo、netease 等平台，SEARCH_LIMIT 控制搜索数量。
  • 高码率播放: 默认 DEFAULT_BR=320k，也可切换为 flac 等更高音质。
  • 网络稳健性: 请求封装为 asyncio.to_thread + requests，内置超时与错误日志。

本地音乐管理 ​

  • 缓存目录: 自动在 get_user_cache_dir()/music 下创建缓存与临时目录。
  • 定期扫描: 至少每 5 分钟刷新一次缓存索引，必要时可通过 force_refresh 强制扫描。
  • 元数据提取: 如果安装了 Mutagen，会自动读取标题、艺术家、专辑及时长。
  • 播放复用: 下载到缓存的歌曲再次播放时会直接命中本地文件，减少网络请求。

数据结构 ​

搜索播放响应 ​

python
{
    "status": "success",
    "message": "正在播放: 青花瓷 - 周杰伦",
    "song": "青花瓷 - 周杰伦",
    "duration": "03:57",
    "total_seconds": 237.5
}

本地歌单响应 ​

python
{
    "status": "success",
    "message": "找到 12 首本地音乐",
    "playlist": [
        "青花瓷 - 周杰伦",
        "光年之外 - 邓紫棋"
    ],
    "total_count": 12
}

音乐元数据（内部使用） ​

python
{
    "file_id": "song_123",
    "title": "青花瓷",
    "artist": "周杰伦",
    "album": "我很忙",
    "duration": "03:57",
    "file_size": 5242880,
    "format": "mp3"
}

歌词数据 ​

python
{
    "status": "success",
    "lyrics": [
        "[00:12] 素胚勾勒出青花笔锋浓转淡",
        "[00:18] 瓶身描绘的牡丹一如你初妆",
        "[00:24] 冉冉檀香透过窗心事我了然"
    ]
}

配置说明 ​

音频配置 ​

音频播放相关配置：

python
AudioConfig = {
    "OUTPUT_SAMPLE_RATE": 44100,
    "CHANNELS": 2,
    "BUFFER_SIZE": 1024
}

缓存配置 ​

缓存目录配置：

python
from src.utils.resource_finder import get_user_cache_dir

cache_dir = get_user_cache_dir() / "music"
temp_cache_dir = cache_dir / "temp"

API配置 ​

在线音乐服务配置：

python
config = {
    "BASE_URL": "https://music-dl.sayqz.com/api/",
    "DEFAULT_SOURCE": "kuwo",
    "DEFAULT_BR": "320k",
    "SEARCH_LIMIT": 20,
    "HEADERS": {
        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
        "Accept": "application/json, text/plain, */*",
        "Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8",
        "Connection": "keep-alive"
    }
}

支持的音频格式 ​

播放格式 ​

  • MP3: 最常见的音频格式
  • M4A: Apple音频格式
  • FLAC: 无损音频格式
  • WAV: 未压缩音频格式
  • OGG: 开源音频格式

元数据支持 ​

  • ID3 v1/v2: MP3元数据标准
  • MP4: M4A文件元数据
  • Vorbis: OGG文件元数据
  • FLAC: FLAC文件元数据

最佳实践 ​

1. 搜索优化 ​

  • 使用具体的歌名和歌手名
  • 避免使用过于模糊的关键词
  • 可以包含专辑名增加准确性

2. 缓存管理 ​

  • 定期清理不需要的缓存文件
  • 监控缓存目录大小
  • 使用强制刷新获取最新音乐列表

3. 网络优化 ​

  • 确保网络连接稳定
  • 在网络不佳时优先使用本地音乐
  • 设置合适的超时时间

4. 用户体验 ​

  • 提供清晰的播放状态反馈
  • 支持快速响应的控制操作
  • 优雅处理播放错误

故障排除 ​

常见问题 ​

  1. 无法搜索歌曲: 检查网络连接和API可用性
  2. 播放失败: 检查音频设备和文件格式
  3. 歌词不显示: 检查歌词服务和歌曲ID
  4. 本地音乐不显示: 检查文件权限和格式支持

调试方法 ​

  1. 查看日志输出获取详细错误信息
  2. 测试网络连接和API响应
  3. 验证音频文件完整性
  4. 检查缓存目录权限

性能优化 ​

  1. 合理设置缓存策略
  2. 优化网络请求频率
  3. 使用异步操作避免阻塞
  4. 定期清理临时文件

通过音乐播放工具，您可以享受丰富的音乐体验，包括在线搜索、本地播放、歌词显示等功能。