Giggle Generation Music

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)

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

python3 scripts/giggle_music_api.py --prompt "user description"

B: Custom Mode

python3 scripts/giggle_music_api.py --custom \
  --prompt "lyrics content" \
  --style "pop, ballad" \
  --title "Song Title" \
  --vocal-gender female

C: Instrumental

python3 scripts/giggle_music_api.py --prompt "user description" --instrumental

Response example:

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

Store task_id in memory (addMemory):

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

Step 2: Query Until Done (default: proactive polling)

After each submit for the current task, repeatedly run (every ~15–30s until terminal or timeout), without waiting for the user to ask:

python3 scripts/giggle_music_api.py --query --task-id <task_id>

Between queries, use sleep in shell or separate invocations with delay—do not go silent; summarize each result to the user.

Output handling:

If the user asks while you are polling, answer with the latest status (extra --query if needed).

Link return rule: Audio links in stdout must be full signed URLs (with Policy, Key-Pair-Id, Signature query params). Do not strip response-content-disposition=attachment when the API returns it; forward links as-is (script only encodes ~ → %7E).

Recovery

In-flight task: use proactive polling as above.

When the user asks about previous music (older task_id):

1. task_id in memory → Run --query --task-id xxx directly. Do not resubmit; poll until done if they want continuous updates on that task.
2. No task_id in memory → Tell the user, ask if they want to regenerate

Parameter Reference