giggle-generation-music

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: giggle-generation-music
description: "Use when the user wants to create, generate, or compose music—whether from text description, custom lyrics, or instrumental background music. After submit, proactively poll task status every ~15–30s and message the user each time until completed/failed/timeout—do not wait for the user to ask for progress. Triggers: generate music, write a song, compose, create music, AI music, background music, instrumental, beats."
version: "0.0.10"
license: MIT
author: giggle-official
homepage: https://github.com/giggle-official/skills
requires:
  bins: [python3]
  env: [GIGGLE_API_KEY]
  pip: [requests]
metadata:
  openclaw:
    emoji: "📂"
    requires:
      bins: [python3]
      env: [GIGGLE_API_KEY]
      pip: [requests]
    primaryEnv: GIGGLE_API_KEY
---

# Giggle Music

**Source**: [giggle-official/skills](https://github.com/giggle-official/skills) · API: [giggle.pro](https://giggle.pro/)

Generates AI music via giggle.pro. Supports simplified and custom modes. Submit task → **agent proactively polls** with `--query` until done (see **Continuous progress updates**). No Cron.

**API Key**: Set system environment variable `GIGGLE_API_KEY`. Log in to [giggle.pro](https://giggle.pro/) → **left sidebar** → **API Key** (**API 密钥**) to create or copy your key.

> **Important**: **Never** pass `GIGGLE_API_KEY` in exec's `env` parameter. API Key is read from system environment variable.

> **No Retry on Error**: If script execution encounters an error, **do not retry**. Report the error to the user directly and stop.

---

## Interaction Guide

### Mode Selection (priority: high to low)

| User input | Mode | Description |
|------------|------|-------------|
| User provides full **lyrics** | Custom mode (B) | Must be lyrics, not description |
| User requests instrumental/background music | Instrumental mode (C) | No vocals |
| Other cases (description, style, vocals, etc.) | **Simplified mode (A)** | Use user description as prompt; AI composes |

> **Key rule**: If the user does not provide lyrics, always use **simplified mode A**. Use the user's description exactly as `--prompt`; **do not add or rewrite**. E.g. user says "female voice, 1 min, ancient romance", use `--prompt "female voice, 1 min, ancient romance"` directly.

### Guidance when info is lacking

Only when the user input is very vague (e.g. "generate music" with no description), ask:

```
Question: "What type of music would you like to generate?"
Options: AI compose (describe style) / Use my lyrics / Instrumental
```

---

## Execution Flow: Submit and Query

Music generation is asynchronous (typically 1–3 minutes). **Submit** a task to get `task_id`, then **query** until the task reaches a terminal state.

---

## Continuous progress updates (default; user need not put this in their prompt)

Music generation usually takes **~1–3 minutes**. The user does **not** need to ask you to check progress.

1. **Right after submit**, say you submitted, give `task_id`, and expect ~1–3 minutes (longer if the service is busy).
2. **Poll proactively**: run `--query` about every **15–30 seconds** until terminal—**do not** wait for the user to ask.
3. **After each query**, report status; for `processing` JSON, paraphrase and say you will keep checking—**do not** go silent.
4. **When done**: forward full **signed audio** links on success; explain failures. If still non-terminal after **~25 minutes**, explain, give `task_id`, and suggest retry or follow-up.
5. **If the user explicitly opts out** of polling, submit once + `task_id`, then query only when they ask.

---

### Step 1: Submit Task

**First send a message to the user**: Music generation is submitted; you will poll on a schedule and report updates—no need to nag. Include `task_id` from the JSON response.

#### A: Simplified Mode
```bash
python3 scripts/giggle_music_api.py --prompt "user description"
```

#### B: Custom Mode
```bash
python3 scripts/giggle_music_api.py --custom \
  --prompt "ly