giggle-generation-speech

文本转音频

通过 giggle.pro 将文本合成为 AI 语音／配音。支持多种音色、情绪和语速。

⚠️ 安装前请先查看

安装前请先查看以下内容。 此技能将会：

1. 写入 ~/.openclaw/skills/giggle-generation-speech/logs/ – 用于 Cron 去重的任务状态文件
2. 注册 Cron（间隔 30s）– 用户发起语音生成时进行异步轮询；完成后移除
3. 转发原始 stdout – 脚本输出（音频链接、状态）将原样传递给用户

要求：python3、GIGGLE_API_KEY（系统环境变量）、pip 包：requests

---

API Key：设置系统环境变量 GIGGLE_API_KEY。登录 giggle.pro 后获取：左侧边栏 → API Key（API 密钥）。如果未配置，脚本会提示用户。

禁止内联 Python：所有命令都必须通过 exec 工具执行。绝不使用 heredoc 内联代码。

出错后不重试：如果脚本执行出错，不要重试。直接向用户报告错误并停止。

执行流程（阶段 1 提交 + 阶段 2 Cron + 阶段 3 同步回退）

语音生成通常需要 10–30 秒。采用“快速提交 + Cron 轮询 + 同步回退”的三阶段架构。

重要：绝不要在 exec 的 env 参数中传入 GIGGLE_API_KEY。API Key 从系统环境变量中读取。

---

持续更新进度（默认；用户无需在提示词中提出）

TTS 通常需要 10–30 秒；阶段 3 的同步等待最长可达 --max-wait（默认 120s）。用户无需催促即可获得进度更新。

1. 阶段 1 提交后，告知用户任务已提交，提供 task_id，并说明预期耗时：通常为 10–30 秒，运行较慢时可能需要约 2 分钟。
2. 持续轮询，无需用户询问：为 --query 注册约每 30s 运行一次的 Cron，并始终运行阶段 3 的 --query --poll 作为回退——不要等用户说“现在检查”。
3. 每次轮询时（Cron 或 --query）：如果仍返回 JSON／processing，换种说法告知用户仍在等待；从第 2 次 JSON 轮询开始，每隔一次 Cron 触发时可发送一条简短消息（例如“仍在生成……”），避免对话长时间没有消息。
4. 任务完成时：转发完整的已签名音频链接（脚本返回纯文本成功结果）；如果失败，则转发错误。如果经过约 15 分钟的实际时间重试／Cron 轮询后仍未完成，向用户说明情况，提供 task_id，移除 Cron，并建议重试。
5. 如果用户明确选择不接收 Cron 提醒，则跳过 Cron，但仍在用户询问时运行 --query；如合适，可继续以阶段 3 的 --poll 作为主要方式。

---

阶段 0：引导用户选择音色和情绪（必需）

提交前，必须引导用户选择音色和情绪。不要使用默认值。

1. 运行 --list-voices 获取可用音色：

python3 scripts/text_to_audio_api.py --list-voices

2. 以易读的格式向用户展示音色列表（voice_id、名称、风格、性别等），并引导他们选择
3. 询问用户偏好的情绪（例如 joy、sad、neutral、angry、surprise）。如果用户没有偏好，则使用 neutral
4. 只有在用户确认音色和情绪后，才能进入阶段 1 提交

---

阶段 1：提交任务（exec 约 10 秒后完成）

先向用户发送消息：语音任务已提交；通常会在 10–30 秒内完成。你会自动查询，并在准备好后立即发送链接——无需催促进度。

# Must specify user-selected voice and emotion
python3 scripts/text_to_audio_api.py \
  --text "The weather is nice today" \
  --voice-id "Calm_Woman" \
  --emotion "joy" \
  --speed 1.2 \
  --no-wait --json

# View available voices
python3 scripts/text_to_audio_api.py --list-voices

响应示例：

{"status": "started", "task_id": "xxx"}

立即将 task_id 存入记忆（addMemory）：

giggle-generation-speech task_id: xxx (submitted: YYYY-MM-DD HH:mm)

---

Phase 2：注册 Cron（间隔 30 秒）

使用 cron 工具注册轮询任务。严格遵循参数格式：

{
  "action": "add",
  "job": {
    "name": "giggle-generation-speech-<first 8 chars of task_id>",
    "schedule": {
      "kind": "every",
      "everyMs": 30000
    },
    "payload": {
      "kind": "systemEvent",
      "text": "Speech task poll: exec python3 scripts/text_to_audio_api.py --query --task-id <full task_id>, handle stdout per Cron logic. If stdout is non-JSON plain text, forward to user and remove Cron. If stdout is JSON (still processing), keep Cron; from the 2nd JSON poll onward, alternate: every other poll send user one brief line (e.g. Speech still generating…). If stdout is empty, remove Cron immediately, do not send message."
    },
    "sessionTarget": "main"
  }
}

Cron 触发处理（基于 exec 标准输出）：

标准输出模式	操作
非空纯文本（不以 { 开头）	原样转发给用户，移除 Cron
标准输出为空	已推送，立即移除 Cron，不发送消息
JSON（以 { 开头，且有 "status" 字段）	保留 Cron；根据本节，从第 2 次 JSON 轮询开始，每隔一次轮询发送一条简短消息

---

Phase 3：同步等待（乐观路径，Cron 尚未触发时的回退方案）

无论 Cron 是否注册成功，都要执行此步骤。

在执行此 exec 之前立即，给用户发送一条简短消息：正在等待合成（通常很快，最长约 2 分钟）——请稍候。

python3 scripts/text_to_audio_api.py --query --task-id <task_id> --poll --max-wait 120

处理逻辑：

• 返回纯文本（语音已就绪／失败消息）→ 原样转发给用户，移除 Cron
• 标准输出为空 → Cron 已推送，移除 Cron，不发送消息
• exec 超时 → Cron 继续轮询

---

查看语音列表

用户想查看可用语音时，运行：

python3 scripts/text_to_audio_api.py --list-voices

该脚本调用 GET /api/v1/project/preset_tones，并向用户展示 voice_id、name、style、gender、age、language。

---

链接返回规则

返回给用户的音频链接必须是完整的签名 URL（带有 Policy、Key-Pair-Id、Signature 查询参数）。如果 API 返回 response-content-disposition=attachment，请勿删除。该脚本只会将 ~ 规范化为 %7E；除此之外，原样转发 URL。

---

新请求与查询旧任务

用户发起新的语音生成请求时，必须运行 Phase 1 提交新任务。不要复用记忆中的旧 task_id。

对于正在进行的任务，遵循 Phase 2–3 和本节的说明——不要等用户询问。对于较早的任务，在用户询问时查询该 task_id（或者在用户想获取更新时进行轮询）。

---

参数参考

参数	必填	默认值	说明
--text	是	-	要合成的文本
--voice-id	是	-	语音 ID；必须通过 --list-voices 获取，并引导用户选择
--emotion	是	-	情绪：joy、sad、neutral、angry、surprise 等。引导用户选择
--speed	否	1	语速倍率
--list-voices	-	-	获取可用语音列表
--query	-	-	查询任务状态
--task-id	查询时必填	-	任务 ID
--poll	否	-	使用 --query 进行同步轮询
--max-wait	否	120	最大等待秒数

---

交互指南

每次生成语音前，都要完成以下交互：

1. 如果用户未提供文本，询问：“您想将哪些文本转换为语音？”
2. 必须引导用户选择语音：运行 --list-voices，展示列表，并让用户选择。不要使用默认语音
3. 必须引导用户选择情绪：询问用户偏好的情绪（joy、sad、neutral、angry、surprise 等）。
4. 用户确认文本、语音和情绪后，运行 Phase 1 提交任务 → Phase 2 注册 Cron → Phase 3 同步等待