> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coze.cn/llms.txt
> Use this file to discover all available pages before exploring further.

[音乐搜索和播放插件](https://www.coze.cn/store/plugin/7524979011345236014)支持根据输入的提示词搜索并播放字节易颂曲库中的歌曲。插件后台集成了字节易颂曲库中的几万首歌曲，涵盖了各种风格和类型的歌曲，包括抖音热门歌曲等。用户可以在语音通话过程中，通过语音指令，使低代码智能体搜索并播放歌曲，为用户提供全新的音乐体验。
## 体验效果 {#771265e1}
以下展示了 [WebSocket 实时语音 Demo](https://www.coze.cn/open-platform/realtime/websocket)，在语音通话过程中通过语音指令使智能体播放歌曲的效果。
<Player src="https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/933ee8f39f3442869d0673a3da375dc4~tplv-goo7wpa0wc-image.image"></Player>
## 使用限制 {#da19ddc2}

* 仅扣子企业旗舰版用户支持使用音乐搜索和播放插件。
* 该音乐插件有版权协定，需要在添加插件时签署补充用户协议后才可以用。
* 扣子主账号内所有子账号共享**音乐搜索和播放插件**的并发限制为 10 。

## 计费说明 {#f187a44c}
音乐搜索和播放插件根据插件调用次数计费，对应的计费项及单价请参考[插件费用](/coze_pro/plugin_fee)。
## 配置说明 {#2cb02ab7}
在调用 **music_agent** 工具时，你需要输入提示词，播放指定风格的歌曲。
### 输入参数 {#c437d2a6}
输入参数说明如下表所示：
<!-- @cols-width: 173,100,643 -->
| | | | \
|**参数** |**是否必选** |**说明** |
|---|---|---|
| | | | \
|content |必选 |输入提示词内容，用于指定播放的歌曲风格或具体歌曲名称，例如：播放一首适合作为背景音的轻音乐。 |
| | | | \
|session_id |可选 |该参数用于关联对话上下文，帮助插件在多轮对话中更好的理解用户意图。如果未传入 `session_id`，每轮对话结束后上下文将自动清空。建议将 `session_id` 的值设置为扣子编程的 Conversation ID。 |\
| | |**示例说明**： |\
| | |假设用户在第一轮对话中说：“播放一首轻松的音乐。”在下一轮对话中说：“换一首音乐。”如果使用了上下文关联（即传入了 `session_id`），插件会理解“换一首音乐”仍然是指“轻松的音乐”。如果没有上下文关联，插件可能无法很好的理解用户的意图。 |\
| | |**使用方法**： |\
| | | |\
| | |1. 在开始节点的输入参数中添加 `session_id` 参数，在插件节点引用该参数。 |\
| | |2. 在语音通话时为自定义参数赋值。通过在`chat_config.parameters`中为`session_id` 赋值，传入 Conversation ID 的值，具体请参见[为自定义参数赋值](/tutorial/variable)。你可以在[发起对话](https://www.coze.cn/docs/developer_guides/chat_v3)接口 Response 中查看 Conversation ID 的值。 |

### 输出参数 {#7bbec7c4}
<!-- @cols-width: 190,672 -->
| | | \
|**参数** |**说明** |
|---|---|
| | | \
|code |执行插件时的状态码。 |
| | | \
|log_id |日志 ID。 |
| | | \
|msg |执行插件时的状态描述或错误提示信息。 |
| | | \
|data.songs.song_id |歌曲 ID。 |
| | | \
|data.songs.play_url |歌曲的 URL 链接，链接有效期为 1 小时。 |\
| |当插件返回多首歌曲时，语音通话中默认播放第一首歌曲。 |
| | | \
|data.songs.play_vid |歌曲的视频 ID。 |

## 示例 {#ac7bf457}
本文以搭建一个支持音乐播放与语音聊天的对话流模式智能体为例，通过意图识别精准判断用户需求，从而决定是播放音乐还是进入闲聊模式。

1. 搭建一个既支持播放音乐又支持闲聊的对话流，对话流的整体设计类似如下：
   ![Image=2227x517](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/4cb5b1302fcd436181dc3d36554a6d3a~tplv-goo7wpa0wc-image.image)
   配置节点如下：
   <!-- @cols-width: 141,422,343 -->
   | | | | \
   |**节点** |**说明** |**示例** |
   |---|---|---|
   | | | | \
   |开始节点 |如果需要插件更好的理解上下文，你可以在开始节点添加 `session_id` 参数，以便在插件节点引用该参数。 |![Image=200x138](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/731ab1a75ca74c61b4176b159e639cab~tplv-goo7wpa0wc-image.image) |
   | | | | \
   |意图识别节点 |智能体对用户输入的语音指令进行意图识别，判断用户是否需要播放音乐。如果是，则调用音乐搜索和播放插件。如果不是，则进入闲聊节点。 |![Image=200x244](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/2a6c6a56567a4b2792c1ee8f9b860fa2~tplv-goo7wpa0wc-image.image) |
   | | | | \
   |音乐搜索和播放插件 |添加音乐搜索和播放插件中的 `music_agent `工具，并设置相关参数的值，具体说明如下： |\
   | | |\
   | |* `content` 参数：引用开始节点的 USER_INPUT 变量，用于获取用户输入的提示词内容。 |\
   | |* `session_id` 参数：引用开始节点中的 `session_id` 参数，以便插件更好的理解上下文。如果不传入 `session_id`，则每轮对话时都会清空上下文。 |\
   | | |\
   | | |![Image=200x255](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/626fc2f5fe124aee878c9c02b1843e17~tplv-goo7wpa0wc-image.image) |
   | | | | \
   |延时安抚（输出节点） |由于音乐搜索链路耗时较长，可以在插件节点前，增加**输出**节点，流式输出安抚的内容，提升用户等待体验。 |\
   | |当用户发送完消息后，智能体会返回安抚话术，例如 ：`正在查询音乐。` |\
   | |:::tip 说明 |\
   | |安抚内容的结尾需要加标点符号，因为扣子编程语音合成需要识别到断句后才会将文本转换为语音。 |\
   | |::: |![Image=200x173](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/95a2dcec90ae4a05aff9f21a523d1500~tplv-goo7wpa0wc-image.image) |
   | | | | \
   |文本输出（输出节点） |在插件节点后，你还可以增加**输出**节点，引导用户进行下一轮对话。 |\
   | |当插件播放完音乐后，智能体会返回引导句，例如 ：`你还想听什么呢？`。 |![Image=200x171](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/c5a98f9a79994094950cedfa85ac3921~tplv-goo7wpa0wc-image.image) |
   | | | | \
   |闲聊（大模型节点） |根据实际需求设计闲聊节点的提示词，包括回复逻辑和风格等。 |\
   | | |![Image=200x343](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/40f0ea6acff44badb69a1d0a3ff3f313~tplv-goo7wpa0wc-image.image) |
   | | | | \
   |结束节点 |结束节点不需要设置输出变量，智能体直接获取插件或闲聊节点的输出。 |![Image=200x117](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/098e6dbdbf784f1388378ba86075b6ad~tplv-goo7wpa0wc-image.image) |

2. 测试并发布智能体。
   1. 试运行并发布对话流后，在智能体中添加对话流，在智能体右侧的调试页面打开语音通话，验证通过语音指令使智能体播放音乐。
      ![Image=600x390](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/8b88478bc91b43d7a535982a7ead8bb7~tplv-goo7wpa0wc-image.image)
   2. 发布智能体至 API 渠道。
      后续可以通过 WebSocket 或 RTC 等方式实现语音通话功能，具体请参见[智能音视频概述](/dev_how_to_guides/realtime_overview)。
3. 体验效果。
   在[体验智能音视频 Demo](/dev_how_to_guides/realtime_playground)页面，通过语音指令验证智能体播放音乐的实际效果。

## 常见问题 {#505b552e}
### 如果曲库中没有对应歌曲怎么办？ {#505b552e}
如果曲库中没有对应版权的歌曲，智能体会提示未找到对应版权的歌曲，请换一首。
此外，当插件未返回歌曲时，本次插件调用不会收取费用。


> * 音乐搜索和播放插件 ID：7524979194451935283