music-tools

name: music_tools description: "AI music generation. Provides the generate_music tool for creating music clips and full songs from text prompts with optional image references using Google Lyria 3 models." metadata: builtin_skill_version: "1.0"

Music Tools

Use this skill when the user asks to create, generate, compose, or produce music, songs, audio tracks, or soundtracks.

Loading this skill activates the generate_music tool.

IMPORTANT: After loading this skill, you MUST call the generate_music tool to perform music operations. Do NOT call music_tools directly - it is NOT a tool name.

Important: Music generation is asynchronous and takes 30-120 seconds. The tool returns a task ID immediately; the user will be notified when the result is ready.

Tool: generate_music

Generate a music clip or full song from a text prompt, with optional reference images for style guidance.

When to Use

• User asks to create, generate, compose, or produce music, a song, an audio track, or a soundtrack.
• User wants background music for a video, scene, or project.
• User wants to generate music inspired by reference images.

Parameters

Model Capabilities

Examples

Generate a short music clip:

generate_music(
  prompt="An upbeat electronic dance track with pulsing synths, heavy bass drops, and energetic drums at 128 BPM"
)

Generate a full song with lyrics (Pro model):

generate_music(
  prompt="A melancholic indie folk ballad with acoustic guitar and soft vocals. Lyrics: 'Walking through the autumn leaves, memories fall like rain...'",
  output_format="wav"
)

Generate music inspired by an image:

generate_music(
  prompt="Compose a cinematic orchestral piece that matches the mood of this scene - epic and mysterious",
  reference_images=["/api/media/dark_forest_scene.jpg"]
)

Tips

• Write detailed prompts describing genre, mood, instruments, tempo, and style for best results.
• For songs with lyrics, include the full lyrics in the prompt. The model will generate vocals.
• Use output_format="wav" with Pro model for higher audio quality (lossless).
• Reference images can influence the musical mood and style - use scene images for soundtrack generation.
• Music generation is async - inform the user it will take 30-120 seconds.
• The generated audio will automatically be added as an audio node on the canvas.

Canvas Integration

Generated music is automatically created as an audio node on the active canvas. To use canvas images as references:

Step 1: Call list_canvas_nodes to discover available image nodes:

list_canvas_nodes(node_type="image")  -> returns [{id: "uuid-a", name: "Scene"}, ...]

Step 2: Call get_canvas_node(node_id="uuid-a") to get the media URL:

• Image nodes -> data.imageUrl (e.g. /api/media/scene.jpg)

Step 3: Pass URLs to generate_music:

generate_music(
  prompt="Compose background music matching the atmosphere of this scene",
  reference_images=["/api/media/scene.jpg"]
)

Error Handling