| name | music |
| description | 播放音乐、控制播放。当用户想听歌、播放歌曲、暂停/继续/切歌、调节音量、单曲循环等音乐相关操作时触发。支持搜索 YouTube 音乐并用 mpv 播放。适配 opencode、codex、OpenClaw、Cursor、Gemini 等智能体编码助手。 |
| license | MIT |
Music Player Skill
在线音乐播放和播放控制技能。模型直接调用 yt-dlp 和 mpv CLI，music.mjs 仅用于播放控制。
支持平台：Git Bash (Windows)、Linux、macOS。不支持 PowerShell。
依赖检查（首次使用）
在首次使用前，在终端尝试运行以下命令。如果提示"找不到命令"，则说明未安装：
yt-dlp --version
mpv --version
如果缺少依赖，提示用户安装：
意图识别与处理
| 意图 | 判断依据 | 处理流程 |
|---|
| 明确搜索 | 含歌曲名、艺人、心情、场景、曲风等 | 清洗输入 → 搜索 → 选择 → 播放 |
| 需要澄清 | 只说"放点歌""来首音乐"，没有具体偏好 | 先问 1-2 个问题 |
| 播放控制 | 暂停、继续、下一首、音量等 | 调用 music.mjs |
澄清优先级：先问心情或场景 → 再问偏中文还是英文 → 不问播放器、脚本等技术细节。
推荐澄清句：想听什么心情或场景的？偏中文还是英文？
输入清洗
搜索前，模型先将用户输入清洗并构造为干净的搜索词：去除命令词（播放/play/来点等）、标点和多余空格，必要时补全艺人信息。
搜索策略
| 场景 | 策略 | 示例 |
|---|
| 歌曲名明确 | 直接用清洗后的歌曲名 + 艺人名 | yt-dlp "ytsearch5:泡沫 邓紫棋" |
| 心情/场景明确 | 转成自然搜索词 | yt-dlp "ytsearch5:适合写代码的轻快中文歌" |
| 曲风明确 | 曲风 + 语言/节奏偏好 | yt-dlp "ytsearch5:city pop Japanese song" |
| 片名/作品名明确 | 搜索主题曲、插曲或 OST | yt-dlp "ytsearch5:双城之战 主题曲" |
注意：所有搜索词都必须先经过"输入清洗"步骤，不能直接使用用户原始输入。
播放流程
步骤 1：搜索 YouTube
yt-dlp "ytsearch5:泡沫 邓紫棋" --dump-json --flat-playlist --no-warnings
输出为 JSON lines 格式（每行一个视频），包含字段：
id: YouTube 视频 IDtitle: 视频标题duration: 时长（秒）uploader: 上传者url: YouTube URL
步骤 2：选择最佳匹配
模型根据以下标准选择最佳视频：
- 标题匹配：标题包含歌曲名和艺人名
- 时长合理：120-420 秒（2-7 分钟）
- 优先选择：official、album、artist 版本
- 兜底播放：如果没有官方版本，live、cover、remix 版本也可以播放（总比没声音好）
步骤 3：停止旧播放并启动 mpv
重要：在启动新播放前，必须先停止当前正在运行的 mpv 进程，避免多实例冲突。
注意：stop 命令会强制关闭当前所有 mpv 进程。如果您正在使用 mpv 播放本地文件，可能会被意外关闭。
Windows (PowerShell)：
node <skill-dir>/scripts/dist/music.mjs stop
Start-Process mpv -ArgumentList "--no-video","--ytdl","--ytdl-format=bestaudio","--input-ipc-server=\\.\pipe\mpv-ipc","https://www.youtube.com/watch?v=VIDEO_ID" -WindowStyle Hidden
Linux/macOS (Bash)：
node <skill-dir>/scripts/dist/music.mjs stop
nohup mpv --no-video --ytdl --ytdl-format=bestaudio --input-ipc-server=/tmp/mpv-ipc "https://www.youtube.com/watch?v=VIDEO_ID" > /dev/null 2>&1 &
参数说明：
--no-video: 只播放音频，不显示视频--ytdl: 启用 yt-dlp 支持（mpv 内部自动调用 yt-dlp 提取音频流）--ytdl-format=bestaudio: 优先选择最佳音质--input-ipc-server: 指定 IPC 路径（必须加，否则 music.mjs 无法控制）- 后台运行，脱离终端
步骤 4：确认播放
立即响应用户："正在播放：[歌曲名] - [艺人名]"
播放控制
所有控制命令通过 music.mjs 调用：
node <skill-dir>/scripts/dist/music.mjs <command>
| 用户输入 | 命令 | 说明 |
|---|
播放 歌曲名、play 歌曲名、我想听 歌曲名 | - | 清洗 → 搜索 → 选择 → 播放 |
暂停、pause | pause | 暂停播放 |
继续播放、resume | resume | 恢复播放 |
下一首、next | next | 下一首 |
上一首、prev | prev | 上一首 |
声音大一点、volume up | volume-up | 音量 +10 |
声音小一点、volume down | volume-down | 音量 -10 |
静音、mute | mute | 切换静音 |
单曲循环、loop | loop | 开启单曲循环 |
关闭循环、loop-off | loop-off | 关闭单曲循环 |
退出音乐、停止播放、stop | stop | 停止播放并退出 |
播放状态、status | status | 查看播放状态 |
输出格式：所有命令输出 JSON 格式。
{ "status": "success", "action": "pause" }
{ "status": "ok", "state": "playing" }
{ "error": "mpv not running" }
回复要求
- 播放成功：转述歌曲信息（
正在播放：Numb - Linkin Park）+ 1 段 2-4 句歌曲简介
- 播放失败：告知
未找到匹配的歌曲，建议 可以尝试更具体的歌曲名或艺人名
- 控制命令：简洁确认（
已暂停、已继续播放、已切换到下一首）
