giggle-generation-speech

Text-to-Audio

giggle.pro を介して、テキストを AI 音声／ナレーションに合成します。複数の声のトーン、感情、話速に対応しています。

⚠️ インストール前に確認してください

インストールする前に、以下を確認してください。 このスキルは以下を行います。

1. ~/.openclaw/skills/giggle-generation-speech/logs/ に書き込みます – Cron の重複排除用のタスク状態ファイル
2. Cron を登録します（30 秒間隔）– ユーザーが音声生成を開始したときに非同期でポーリングし、完了後に削除します
3. 標準出力をそのまま転送します – スクリプトの出力（音声リンク、ステータス）をそのままユーザーに渡します

必要なもの：python3、GIGGLE_API_KEY（システム環境変数）、pip パッケージ：requests

---

API キー：システム環境変数 GIGGLE_API_KEY を設定します。ログインした状態で giggle.pro にアクセスし、左サイドバー → API Key（API 密钥）から取得してください。未設定の場合、スクリプトが入力を求めます。

Python をインラインで実行しないでください：すべてのコマンドは exec ツール経由で実行する必要があります。インラインコードで heredoc を使用しないでください。

エラー時に再試行しないでください：スクリプトの実行でエラーが発生した場合、再試行しないでください。エラーをそのままユーザーに報告し、処理を停止してください。

実行フロー（フェーズ 1 送信 + フェーズ 2 Cron + フェーズ 3 同期フォールバック）

音声生成には通常 10～30 秒かかります。「高速送信 + Cron ポーリング + 同期フォールバック」の 3 フェーズ構成を使用します。

重要：exec の env パラメーターに GIGGLE_API_KEY を渡さないでください。API キーはシステム環境変数から読み取られます。

---

継続的な進捗状況の更新（デフォルト。ユーザーがプロンプトに記載する必要はありません）

TTS は通常 10～30 秒かかります。フェーズ 3 の同期待機は、最大 **--max-wait（デフォルト 120s）**まで実行できます。ユーザーが進捗を催促する必要はありません。

1. フェーズ 1 の送信後、タスクが送信されたことを伝え、task_id を知らせ、通常は10～30 秒で完了するものの、処理が遅い場合は約 2 分かかることもあると説明します。
2. 求められなくてもポーリングを続けます：--query 用に約 30 秒間隔の Cron を登録し、フォールバックとしてフェーズ 3 の --query --poll も必ず実行します。ユーザーが「今確認して」と言うのを待たないでください。
3. ポーリングのたびに（Cron または --query）：引き続き JSON／processing の場合は、待機中であることを言い換えて伝えます。JSON のポーリングが 2 回目以降は、スレッドが無言のままにならないよう、Cron の実行 1 回おきに簡潔なメッセージを 1 行送ってもかまいません（例：「引き続き生成中です…」）。
4. 完了したら：署名付き音声リンクをすべて転送します（スクリプトの成功時のプレーンテキスト）。失敗した場合はエラーを転送します。実時間での再試行／Cron が約 15 分続いても完了しない場合は、その旨を説明し、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)

---

フェーズ 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 の stdout に基づく）：

stdout のパターン	アクション
空でないプレーンテキスト（{ で始まらない）	そのままユーザーに転送し、Cron を削除する
stdout が空	すでに送信済みです。ただちに Cron を削除し、メッセージを送信しないでください
JSON（{ で始まり、"status" フィールドを含む）	Cron を維持します。このセクションに従い、2 回目以降の JSON ポーリングでは、1 回おきに短いメッセージを送信します

---

フェーズ 3：同期して待機する（楽観パス。Cron がまだ実行されていない場合のフォールバック）

Cron の登録に成功したかどうかにかかわらず、このステップを実行してください。

この exec の直前に必ず、ユーザーに短いメッセージを送信してください：音声を合成しています（通常はすぐに完了しますが、最大 2 分ほどかかることがあります）。お待ちください。

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

処理ロジック：

• プレーンテキストが返された（音声の準備完了／失敗メッセージ）→ そのままユーザーに転送し、Cron を削除します
• stdout が空 → 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 をそのまま転送してください。

---

新しいリクエストと過去のタスクの照会

ユーザーが新しい音声生成をリクエストした場合は、必ずフェーズ 1 を実行して新しいタスクを送信してください。メモリ内の古い task_id を再利用しないでください。

進行中のタスクについては、フェーズ 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. ユーザーがテキスト、音声、感情を確認した後、フェーズ 1 の送信 → フェーズ 2 の Cron 登録 → フェーズ 3 の同期待機を実行します