---
name: music
description: 音乐播放器卡片完整规范——用 dsh-music 围栏在回复中渲染可交互播放器（网易云/QQ 双后端、多主题、悬浮歌词与气泡特效）。
---

# 音乐播放器卡片（dsh-music 围栏）

在回复里输出如下围栏，即可在对话中渲染一个**可交互的音乐播放器卡片**。围栏必须放在回复末尾，一段回复最多一个。

```dsh-music
{"theme":"glass","backend":"netease","keyword":"周杰伦 晴天","autoplay":true,"lyricMode":"bubble"}
```

## 字段规范

| 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `theme` | string \| object | `"glass"` | `glass`（玻璃拟态 + 悬浮歌词气泡）/ `neon`（霓虹）/ `paper`（纸感）/ `vapor`（蒸汽波），或自定义对象 |
| `backend` | string | `"netease"` | `netease` 网易云（搜索+播放+歌词最全）；`qq` QQ 音乐（搜索/歌词/封面可用，免登录时多数歌曲无直链，卡片会自动跨后端降级到网易云播放） |
| `keyword` | string | — | 初始搜索词：单曲用「歌手 歌名」；歌单用主题词（「深夜 lo-fi」「粤语经典」「学习专注白噪音」） |
| `playlist` | array | — | 直接给曲目；**不需要 id**，卡片自动搜索解析。给了 `playlist` 就不必给 `keyword` |
| `autoplay` | boolean | `false` | 仅当用户明确说「播放/来听」时为 `true`（浏览器可能要求用户再点一次） |
| `lyricMode` | string | `"bubble"` | `bubble` 悬浮歌词气泡（随播放浮动）/ `bar` 内嵌滚动歌词栏 / `none` |
| `title` | string | — | 卡片标题，给歌单起名字（「深夜电台」「你的年度歌单」）会更有氛围 |

### playlist 曲目格式

```dsh-music
{"title":"深夜电台","theme":"vapor","playlist":[
  {"title":"晴天","artist":"周杰伦"},
  {"title":"Lemon","artist":"米津玄師"},
  {"title":"Here We Are Again","artist":"City of Prague Philharmonic"}
]}
```

- 只给 `title` + `artist`（可选 `album`）最稳；卡片按「歌名+歌手」搜索解析。
- 可以指定单个曲目走某个后端：`{"title":"晴天","artist":"周杰伦","backend":"netease"}`。
- **不要杜撰歌曲 id**——不写 `id` 字段，交给卡片解析；你只负责选歌。
- 数量建议 3–8 首；用户没要求歌单时不要硬塞 `playlist`，给 `keyword` 即可。

### 自定义主题（theme 传对象）

```dsh-music
{"theme":{"accent":"#f472b6","bg":"#1e1b4b","text":"#fef3c7","bubbles":true,"coverBlur":true,"radius":24},"keyword":"lo-fi"}
```

- `accent`：主色（按钮、进度条、气泡描边）；`bg`/`text`：底色/文字色；`radius`：圆角 px
- `bubbles`：气泡特效开关；`coverBlur`：是否用封面做卡片背景氛围光
- 只写想覆盖的字段，其余继承 `glass` 基底

## 后端说明（诚实转述给用户）

- **netease**：免费歌曲可直接播放（默认 320kbps）；VIP/灰色歌曲无直链，卡片会标出并自动用 QQ 侧搜索结果兜底。
- **qq**：搜索、歌词、封面全可用；免登录环境多数歌曲拿不到播放直链（需版权签名）。卡片遇到空直链会**自动在网易云搜索同名同歌手曲目并切换播放**，状态栏会注明来源。
- 两个后端都失败时卡片显示错误提示并自动跳下一曲——不需要你在文字里解释这些细节。

## 行为准则

1. **围栏即交付**：用户说「放一首 X」「来点 Y 风格的歌」「帮我建个 Z 歌单」，正文一两句引入 + 围栏收尾，不要罗列曲目清单（曲目就在卡片里）。
2. **LOCAL-FIRST**：搜索、播放、暂停、切歌、换主题、切后端都在卡片内完成，零模型往返。不要把播放器操作写成步骤指引。
3. **什么时候再发新围栏**：用户要求换歌单/换风格/推荐类似歌 → 发新围栏（新 playlist 或 keyword）。单首切歌之类用户自己点。
4. **主题品味**：氛围向（深夜、雨声、lo-fi）配 `glass` 或 `vapor`；运动/游戏配 `neon`；歌词向分享配 `glass` + `lyricMode:"bubble"`；读书笔记/安静场景配 `paper`。
5. 不索取账号、密码、Cookie；VIP/版权失败由卡片自行提示，不要重复道歉。