# Agent 使用示例
本文档展示了当用户提出各种文本转语音请求时，Agent应如何调用 MCP MeloTTS 工具。
## 何时调用 `mcp_melotts_generate_audio` 工具
当用户请求以下类型的内容时，Agent 必须调用该工具：
- 将文本生成语音音频
- 朗读一段文字，指定语言与语速
- 将长文自动分段生成语音并合并为一个文件
- 生成语音文件供后续使用（如配音、旁白）
## 使用场景示例
### 1. 文本到语音生成
**用户请求**: "把这段中文生成音频文件"
**Agent 调用**:
```json
{
"name": "mcp_melotts_generate_audio",
"arguments": {
"text": "我最近在学习machine learning，希望能够在未来的artificial intelligence领域有所建树。",
"language": "ZH",
"speed": 1.0,
"output_dir": "./audio"
}
}
```
### 2. 指定设备与说话人
**用户请求**: "用日语朗读，使用 GPU，加快语速"
**Agent 调用**:
```json
{
"name": "mcp_melotts_generate_audio",
"arguments": {
"text": "こんにちは、今日はいい天気ですね。",
"language": "JP",
"speaker": "JP",
"speed": 1.2,
"device": "cuda:0",
"output_dir": "./audio"
}
}
```
### 3. 长文本自动分段与合并
**用户请求**: "将下面长文生成一个完整的音频文件"
**Agent 调用**:
```json
{
"name": "mcp_melotts_generate_audio",
"arguments": {
"text": "......这里是很长很长的文本......",
"split_sentences": true,
"output_dir": "./audio",
"target_filename": "full.wav"
}
}
```
### 4. 通过 Docker Gradio HTTP 接口生成
**用户请求**: "用已启动的 MeloTTS 服务生成音频"
**Agent 调用**:
```json
{
"name": "mcp_melotts_generate_audio",
"arguments": {
"text": "请将以下内容朗读为音频……",
"language": "ZH",
"speed": 1.0,
"output_dir": "./audio",
"use_http_api": true,
"api_base_url": "http://localhost:8888",
"fn_index": 1
}
}
```
## 常见用户请求模式
### 描述性请求
- "朗读这段文字并生成音频"
- "用英文/日语/中文生成语音文件"
- "语速稍慢/稍快朗读并保存为 wav"
### 细化参数
- 指定语言与说话人标签
- 指定设备（cpu 或 cuda:0）
- 指定输出文件名与保存目录
## 注意事项
1. 启动前确保 Docker 容器在本机 8888 端口运行（若使用 HTTP 模式）
2. 启动前确保系统可调用 ffmpeg（用于无损拼接）
3. 工具输出为最终 WAV 文件的本地路径文本
