TTS语音生成插件 (astrbot_plugin_local_TTS)

本插件为 AstrBot 设计，通过调用本地部署的文本转语音（TTS）API（如 CosyVoice），将机器人的文本回复或指定文本转换为语音消息发送。

✨ 功能特性

• 指令驱动：通过 TTS 指令，快速将任意文本转换为语音。
• 参数灵活：支持在指令中临时指定情绪/风格（instruct）和音色（speaker）。
• 自动转换：可配置机器人发出的文本消息，按一定概率自动转为语音发送。
• 会话绑定：可为不同群聊或私聊配置专属的默认音色和风格。
• 全局配置：支持配置全局音色，作为所有会话的兜底选项。
• 情绪感知 (实验性)：可利用大语言模型（LLM）判断文本情绪，并将其应用于语音生成。
• 管理功能：支持配置管理员权限，仅限管理员使用 TTS 指令；支持仅针对 LLM 回复进行转换。
• 缓存管理：支持手动或自动定期清理生成的语音缓存，节约存储空间。

⚙️ 前置要求

• 一个正在运行的、兼容 GET /?text=...&speaker=...&instruct=... 格式的本地TTS服务。
• 推荐使用 CosyVoice 等项目的本地部署版本。
• 确保您的TTS服务支持通过URL参数指定音色（speaker）和风格/情感（instruct）。

📝 命令说明

插件提供以下命令来使用各项功能：

1. 文本转语音

基础命令格式: TTS [【风格】][【音色】] <要转换的文本>

• 【风格】 (可选): 用于控制语音的情绪、语调或风格（对应API的instruct参数）。
• 【音色】 (可选): 强制本次转换使用的音色（对应API的speaker参数）。
• <要转换的文本>: 必填，需要转换成语音的具体内容。

注意:

• 【】 标签必须严格位于指令的开头。
• 如果要指定 【音色】，则必须在其前面提供 【风格】 标签，即使内容为空（即 【】）。

使用示例:

• 简单转换 (使用会话默认音色)

  TTS 早上好呀
  

  插件将使用当前会话配置的音色（或全局音色）生成语音。

• 指定风格

  TTS 【愤怒】 你为什么要骗我
  

  使用当前会话音色，但强制指定“愤怒”风格。

• 同时指定风格和音色

  TTS 【高兴】【小妹妹】 今天天气真不错
  

  强制使用“小妹妹”音色和“高兴”风格。

• 仅指定音色 (风格留空)

  TTS 【】【小妹妹】 今天天气真不错
  

  强制使用“小妹妹”音色，不指定任何风格。

2. 清理缓存

该命令用于删除所有已生成的语音文件，释放磁盘空间。

命令:

TTS清理

回复:

TTS缓存已清理...个文件，共...MB。

🔧 插件配置

您可以在 AstrBot 的插件管理页面找到该插件并进行详细配置。

• TTS提供商

  • 功能: 选择TTS服务类型。
  • 说明: 目前仅支持 CosyVoice3 本地部署，此选项为将来扩展保留。

• 基础配置

  • API的URL:
    • 功能: 设置您的本地TTS服务的完整URL地址。
    • 默认值: http://localhost:9880
    • 示例: 如果您的服务运行在另一台机器的9881端口，可修改为 http://192.168.1.10:9881。

• 启用的会话

  • 功能: 以白名单模式管理插件生效的会话，并为每个会话指定音色和风格。
  • 说明: 这是一个列表，每一项代表一个会话的配置。如果此列表为空，插件将在所有会话中启用，并统一使用“全局音色”。
  • 格式: 会话SID:音色[:风格]
    • 会话SID: AstrBot中的会话唯一标识符，如 napcat:GroupMessage:12345678。
    • 音色 (可选): 该会话默认使用的音色名称。
    • 风格 (可选): 该会话默认的风格/指令。
  • 示例:
    • napcat:GroupMessage:87654321:雷军:武汉话：在指定群聊中，默认使用“雷军”音色和“武汉话”风格。
    • napcat:GroupMessage:12345678:小妹妹：在指定群聊中，默认使用“小妹妹”音色，无默认风格。
    • napcat:GroupMessage:12345678::高兴：在指定群聊中，使用“全局音色”作为兜底，但默认风格为“高兴”。
    • napcat:GroupMessage:87654321：在指定群聊中，使用“全局音色”和默认风格（若有）。

• 全局音色

  • 功能: 设置一个全局默认音色。
  • 说明: 当“启用的会话”列表为空，或匹配到的会话配置中没有指定音色时，将使用此音色作为兜底。

• TTS命令仅允许管理员使用

  • 功能: 开启后，只有管理员才能使用TTS指令。在白名单会话中，非管理员会收到提示；在非白名单会话中，则静默忽略。

• TTS仅对LLM回复生效

  • 功能: 开启后，只有由大模型（LLM）生成的回复才会触发自动转语音。

• 主动调用配置

  • 主动转语音发送的概率:
    • 功能: 设置机器人发出的文本消息被自动转换为语音的概率。
    • 范围: 0.0 到 1.0 之间。0 表示关闭此功能。
    • 默认值: 0.4 (即40%的概率)。
  • 文本长度限制:
    • 功能: 只有当待发送文本的长度小于或等于此值时，才可能触发自动转语音。
    • 默认值: 75。

• 情绪配置

  • 功能: 让插件在生成语音时，有一定概率借助LLM来判断文本的情绪，并附加到instruct参数中。
  • 情绪判断LLM:
    • 说明: 选择一个已在AstrBot中配置好的大语言模型提供商。插件将使用它来分析情绪。
    • 提示词: 判断“{...}”这句话的情绪，只返回一个词，不要加任何多余说明。
  • 情绪判断概率:
    • 功能: 触发LLM情绪判断的概率。
    • 范围: 0.0 到 1.0 之间。0 表示关闭此功能。
    • 默认值: 0.5。

• 缓存自动清理频率

  • 功能: 设置自动清理语音缓存文件的时间间隔。
  • 单位: 分钟。
  • 说明: 输入 0 或负数表示关闭自动清理，插件重载或重启后生效。此时只能通过 TTS清理 命令手动清理。

⚠️ 常见问题

• TTS失败，当前会话未配置音色或配置有误...:
  • 原因: 插件已触发，但根据配置（会话配置和全局配置）未能找到一个可用的音色名称。请检查“启用的会话”或“全局音色”配置项。
• TTS失败，音色配置或API有误...:
  • 原因: 已成功向TTS API发出请求，但API返回了错误或非音频内容。
  • 排查:
    1. 确认您的TTS服务正在正常运行。
    2. 确认您指定的音色名称（如“小妹妹”）对于您的TTS服务是有效的。
    3. 检查AstrBot的后台日志，获取更详细的API错误信息。