py_xiaozhi/documents/docs/mcp/music.md

音乐播放工具 (Music Tools)

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

常见使用场景

搜索播放在线音乐:

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

播放控制:

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

本地音乐管理:

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

播放状态查询:

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

歌词功能:

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

高级功能:

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

使用提示

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

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

功能概览

在线音乐功能

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

本地音乐管理

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

播放控制功能

• 基础控制: 播放、暂停、停止
• 进度控制: 跳转到指定时间位置
• 状态查询: 获取播放状态、进度等信息
• 错误处理: 完善的错误处理和恢复机制

用户体验功能

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

工具列表

1. 在线音乐工具

search_and_play - 搜索并播放

搜索在线音乐并开始播放。

参数:

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

使用场景:

• 播放指定歌曲
• 搜索歌手的歌曲
• 播放流行音乐

2. 本地音乐工具

get_local_playlist - 获取本地音乐列表

获取本地缓存的音乐文件列表。

参数:

• force_refresh (可选): 是否强制刷新，默认false

使用场景:

• 查看本地音乐
• 管理音乐库
• 选择播放列表

search_local_music - 搜索本地音乐

在本地音乐中搜索指定歌曲。

参数:

• query (必需): 搜索关键词

使用场景:

• 查找本地歌曲
• 艺术家搜索
• 专辑搜索

play_local_song_by_id - 播放本地歌曲

根据歌曲ID播放本地音乐。

参数:

• file_id (必需): 本地音乐文件ID

使用场景:

• 播放指定本地歌曲
• 从播放列表选择
• 快速播放缓存音乐

3. 播放控制工具

play_pause - 播放/暂停切换

切换播放和暂停状态。

参数: 无

使用场景:

• 暂停当前播放
• 恢复播放
• 播放控制

stop - 停止播放

停止当前播放。

参数: 无

使用场景:

• 完全停止播放
• 结束音乐会话
• 清除播放状态

seek - 跳转到指定位置

跳转到歌曲的指定时间位置。

参数:

• position (必需): 跳转位置（秒）

使用场景:

• 快进到高潮部分
• 重复播放某段
• 跳过不喜欢的部分

4. 信息查询工具

get_status - 获取播放状态

获取当前播放器的详细状态信息。

参数: 无

使用场景:

• 查看播放进度
• 检查播放状态
• 获取歌曲信息

get_lyrics - 获取歌词

获取当前播放歌曲的歌词。

参数: 无

使用场景:

• 显示歌词
• 跟唱歌曲
• 学习歌词

使用示例

在线音乐播放示例

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

# 播放/暂停控制
result = await mcp_server.call_tool("play_pause", {})

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

# 跳转到指定位置
result = await mcp_server.call_tool("seek", {
    "position": 90.5
})

本地音乐管理示例

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

# 搜索本地音乐
result = await mcp_server.call_tool("search_local_music", {
    "query": "周杰伦"
})

# 播放本地歌曲
result = await mcp_server.call_tool("play_local_song_by_id", {
    "file_id": "song_123"
})

状态查询示例

# 获取播放状态
result = await mcp_server.call_tool("get_status", {})

# 获取歌词
result = await mcp_server.call_tool("get_lyrics", {})

技术架构

音乐播放器核心

• 单例模式: 全局唯一的播放器实例
• 异步设计: 支持异步操作，不阻塞主线程
• 状态管理: 完善的播放状态管理
• 错误处理: 健壮的错误处理机制

音频处理

• Pygame集成: 使用Pygame Mixer进行音频播放
• 格式支持: 支持多种音频格式
• 缓存机制: 智能缓存策略，减少重复下载
• 音质优化: 高品质音频播放

在线服务集成

• API接口: 集成在线音乐搜索API
• 下载管理: 异步下载和缓存管理
• 歌词服务: 实时歌词获取和显示
• 网络优化: 网络请求优化和重试机制

本地音乐管理

• 文件扫描: 自动扫描本地音乐文件
• 元数据提取: 使用Mutagen库提取音乐元数据
• 索引建立: 建立音乐文件索引，提高搜索效率
• 格式识别: 智能识别音乐文件格式

数据结构

播放状态信息

{
    "status": "success",
    "current_song": "青花瓷 - 周杰伦",
    "is_playing": true,
    "paused": false,
    "duration": 237.5,
    "position": 89.2,
    "progress": 37.6,
    "has_lyrics": true
}

音乐元数据

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

歌词数据

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

配置说明

音频配置

音频播放相关配置：

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

缓存配置

缓存目录配置：

cache_dir = Path(project_root) / "cache" / "music"
temp_cache_dir = cache_dir / "temp"

API配置

在线音乐服务配置：

config = {
    "SEARCH_URL": "http://search.kuwo.cn/r.s",
    "PLAY_URL": "http://api.xiaodaokg.com/kuwo.php",
    "LYRIC_URL": "http://m.kuwo.cn/newh5/singles/songinfoandlrc"
}

支持的音频格式

播放格式

• 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. 定期清理临时文件

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