Merge Lyria music generation skill

.agents/skills/lyria/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: lyria
+description: Generate and validate music with Google Lyria 3 through the Gemini Interactions API. Use before calling OpenMontage `google_music`, designing Lyria 3 Clip or Pro prompts, using image-to-music or custom lyrics, choosing between Lyria 3 and Lyria RealTime, diagnosing Google music-generation failures, or preparing exact-duration music for a video.
+---
+
+# Google Lyria 3
+
+Use Lyria 3 as a single-turn music generator. Keep it distinct from Lyria RealTime, which is an experimental WebSocket model for continuously steered instrumental performance.
+
+Read [references/api-and-prompting.md](references/api-and-prompting.md) when choosing a model, designing vocals or custom lyrics, using image inputs, debugging the response, or checking current limits and pricing.
+
+## Required Workflow
+
+1. Confirm the intended role: underscore, loop, instrumental cue, or full song.
+2. Confirm vocals, language, target duration, musical structure, and delivery format.
+3. Announce the provider, exact model, estimated per-request cost, and whether the call is exploratory or final.
+4. Write one structured prompt using the contract below.
+5. Make one approved generation call. Treat a retry as another potentially billable stochastic generation.
+6. Preserve the returned provider source unchanged.
+7. Probe the actual file and listen before recording duration, format, or approval metadata.
+8. Derive a separate production master when the edit requires an exact duration.
+
+## Choose The Model Deliberately
+
+| Need | Model | Contract |
+|---|---|---|
+| Prompt iteration, preview, loop, exact 30-second source | `lyria-3-clip-preview` | Always generates a 30-second MP3; currently $0.04/request |
+| Full song, vocals, longer structure, image-conditioned score | `lyria-3-pro-preview` | Prompt-influenced duration up to roughly three minutes; currently $0.08/request |
+| Live, continuously steered instrumental performance | `lyria-realtime-exp` | Separate WebSocket workflow; do not route through `google_music` |
+
+The current OpenMontage `google_music` adapter is locked to `lyria-3-pro-preview`. It does not expose Clip, WAV response selection, multiple images, or RealTime controls. Surface that limitation rather than implying those options are available through the adapter.
+
+Do not change models silently. For a 30-second video, either obtain approval for Pro plus exact-duration mastering or use Clip through an explicitly supported path.
+
+## Build The Prompt
+
+Specify, in this order:
+
+1. **Purpose and duration** — what the music supports and the requested length.
+2. **Genre and era** — use musical vocabulary, not a living artist imitation.
+3. **Tempo and harmony** — BPM or tempo range, meter, key or tonal center.
+4. **Instrumentation and texture** — name lead, rhythm, bass, and ambient layers.
+5. **Structure** — timestamped sections or `[Intro]`, `[Verse]`, `[Chorus]`, `[Bridge]`, `[Outro]`.
+6. **Dynamics and synchronization** — entrances, rests, builds, hits, and holds tied to edit times.
+7. **Vocal policy** — instrumental-only constraints, a vocal profile, or clearly separated custom lyrics.
+8. **Mix and ending** — density, foreground/background role, headroom character, and final decay.
+9. **Exclusions** — unwanted vocals, instruments, gestures, clichés, abrupt endings, or copyrighted material.
+
+For video underscore, use timestamp windows that cover the full requested duration. Ask for one primary change per window and identify the exact synchronization moment.
+
+For instrumental-only output, say all of the following when they matter:
+
+```text
+Instrumental only. No lead or backing vocals, speech, choir, humming,
+vocal chops, spoken samples, lyrical fragments, or recognizable quotations.
+```
+
+For custom lyrics, put performance direction before a separate `Lyrics:` block and use section labels. Prompt in the language the singer should use.
+
+## Direct Vocals Deliberately
+
+When vocals are requested, define these before writing the prompt:
+
+1. **Vocal role** — solo lead, duet, call-and-response, backing ensemble, or vocal texture.
+2. **Language and script** — name the sung language and keep the custom lyrics in one intentional script; do not silently transliterate or code-switch.
+3. **Singer profile** — voice type or range, timbre, intensity, diction, ornamentation, and emotional distance. Do not imitate a named artist.
+4. **Section behavior** — state where the lead enters, where harmonies or echoes appear, and which sections remain instrumental.
+5. **Lyric contract** — separate directions from a `Lyrics:` block, use `[Verse]`, `[Chorus]`, `[Bridge]`, and `[Outro]`, and reserve parentheses for intentional backing-vocal echoes.
+
+Treat the returned vocal as untrusted until auditioned. Check lyric adherence, language drift, pronunciation, intelligibility, unwanted backing vocals, vocal/instrument balance, and whether the performance follows the requested emotional arc. A technically valid file with poor diction or altered lyrics is not an approved vocal result.
+
+## Treat Duration As Untrusted Until Probed
+
+Lyria 3 Pro duration is controlled through prompt instructions and timestamps, not an exact API parameter. The OpenMontage adapter appends a target-duration instruction, but its returned `duration_seconds` field is the request, not a media probe.
+
+Always inspect the generated file:
+
+```bash
+ffprobe -v error -show_entries \
+  format=duration,format_name,bit_rate:stream=codec_name,sample_rate,channels \
+  -of json output.mp3
+```
+
+If exact duration is required:
+
+- keep the provider source untouched;
+- record requested and measured durations separately;
+- derive a new master by trimming at a musically sensible boundary and applying a short fade;
+- do not stretch, loop, or regenerate without the approved production plan;
+- record the derivation and probe the master again.
+
+## Authenticate And Diagnose Safely
+
+The Gemini API commonly uses `GEMINI_API_KEY`. OpenMontage also supports `GOOGLE_API_KEY` and Vertex service-account credentials.
+
+- Use one known credential path per run.
+- Never print keys or edit credential files while debugging.
+- Do not assume a rejected first key will fall through to a second configured key.
+- In the current OpenMontage resolver, `GOOGLE_API_KEY` takes precedence over `GEMINI_API_KEY` when both are non-empty.
+- Treat `403`, `API_KEY_SERVICE_BLOCKED`, and project/service restrictions as authentication or Google-project configuration failures, not prompt-quality failures.
+- Do not spend retries on permission failures. Resolve the credential/project path first.
+- Retry only transient rate-limit or timeout failures within the approved retry and budget policy.
+
+## Parse And Record The Result
+
+Prefer `interaction.output_audio`. For interleaved responses, traverse `model_output` steps and select the audio block; capture output text separately if lyrics or a structure description are relevant.
+
+Record:
+
+- provider and exact model;
+- original prompt and any image provenance;
+- requested duration and probed duration;
+- actual codec, sample rate, channels, and file path;
+- cost per call and total attempts;
+- whether vocals were requested and whether any were detected by listening;
+- the provider source and any separately derived production master.
+
+## Quality Checklist
+
+- The prompt states purpose, tempo, instruments, structure, dynamics, vocal policy, and ending.
+- Timestamp windows cover the intended runtime without contradictions.
+- No artist impersonation or copyrighted lyrics are requested.
+- The output file exists, is non-empty, decodes, and contains an audio stream.
+- Actual duration and technical properties come from a probe, not request metadata.
+- Instrumental output is checked for accidental vocal material.
+- The opening, synchronization moments, transitions, and ending are auditioned.
+- The untouched source is preserved and any production master has explicit provenance.
+- SynthID watermarking and preview-model instability are acknowledged where provenance matters.

.agents/skills/lyria/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Google Lyria"
+  short_description: "Generate and validate music with Lyria 3"
+  default_prompt: "Use $lyria to design a production-ready Lyria 3 music generation prompt and verification plan."

.agents/skills/lyria/references/api-and-prompting.md

@@ -0,0 +1,188 @@
+# Lyria 3 API and Prompting Reference
+
+Last verified: 2026-07-18.
+
+## Provider Families
+
+### Lyria 3 Clip
+
+- Model: `lyria-3-clip-preview`
+- Best for: prompt iteration, previews, loops, short cues
+- Input: text or images
+- Output: MP3 audio plus text containing lyrics or song structure
+- Duration: always 30 seconds
+- Gemini Developer API price: $0.04 per request; no free tier
+
+### Lyria 3 Pro
+
+- Model: `lyria-3-pro-preview`
+- Best for: full songs, vocals, verses, choruses, bridges, longer scores
+- Input: text or up to 10 images through the underlying API
+- Output: MP3 by default; the underlying Pro API can request audio/WAV response format
+- Duration: prompt-influenced, up to roughly three minutes; not an exact media contract
+- Gemini Developer API price: $0.08 per request; no free tier
+
+### Lyria RealTime
+
+- Model: `lyria-realtime-exp`
+- Experimental, instrumental, persistent WebSocket session
+- Supports continuous steering of BPM, scale, density, brightness, and guidance
+- Not the Interactions API and not the model used by OpenMontage `google_music`
+
+## Interactions API Shape
+
+Python:
+
+```python
+from google import genai
+
+client = genai.Client()
+interaction = client.interactions.create(
+    model="lyria-3-pro-preview",
+    input="A structured instrumental score ...",
+)
+
+audio = interaction.output_audio
+text = interaction.output_text
+```
+
+The convenience properties are preferred for ordinary responses. For interleaved responses, iterate `interaction.steps`; inspect `model_output` content blocks and keep `audio` and `text` blocks separate.
+
+The OpenMontage adapter currently:
+
+- sends a list containing one text block and optionally one image block;
+- appends `[Target Duration: N seconds]` to the text;
+- calls `client.interactions.create()` with `lyria-3-pro-preview`;
+- extracts audio through `output_audio`, then legacy outputs, then step traversal;
+- writes MP3 and reports the requested duration without probing the result.
+
+## Prompt Template: Video Underscore
+
+```text
+Create an original instrumental background score for [purpose], target [N] seconds.
+
+Style: [genre/blend/era], [mood], [foreground or background role].
+Tempo and harmony: [BPM], [meter], [key/scale or tonal behavior].
+Instrumentation: [lead], [rhythm], [bass], [texture].
+
+[0:00-0:06] [one musical state and entrance rule].
+[0:06-0:12] [one development].
+[0:12-0:15] [build or reduction that prepares the sync point].
+[0:15-0:18] [exact synchronization event and required hold].
+[0:18-0:30] [release and ending behavior].
+
+Mix: [density, space, transient character, dynamic range].
+Ending: [tail, final resonance, no abrupt cutoff].
+Instrumental only. No vocals, speech, choir, humming, vocal chops,
+spoken samples, lyrical fragments, or recognizable quotations.
+Avoid: [unwanted instruments, clichés, oversized hits, abrupt fade].
+```
+
+Use timestamps as structural instructions, not as proof that Pro will return an exact-length file.
+
+## Prompt Template: Song With Custom Lyrics
+
+```text
+Create a [duration] [genre] song in [key] at [BPM].
+Vocal profile: [range, tone, delivery, language].
+Instrumentation and production: [details].
+Structure: [Intro], [Verse], [Chorus], [Bridge], [Outro].
+
+Lyrics:
+[Verse 1]
+...
+
+[Chorus]
+...
+```
+
+Separate lyrics from production direction. Use round brackets only when backing-vocal echoes are desired.
+
+## Vocals And Custom Lyrics
+
+Lyria generates vocals and lyrics unless the prompt clearly requests an instrumental. Google recommends a detailed singer profile covering voice type or gender presentation, timbre, and vocal range. The model generates lyrics in the language of the prompt, and an explicit language instruction can override that default.
+
+For a vocal song, specify:
+
+- **Role:** solo lead, duet, call-and-response, backing ensemble, or wordless texture.
+- **Profile:** range, timbre, delivery, diction, intensity, ornamentation, and register changes.
+- **Language:** the sung language, intended register, and whether any code-switching is allowed.
+- **Section map:** where vocals begin, where harmonies enter, which passage is instrumental, and how the vocal exits.
+- **Backing policy:** use parentheses only for intentional echoes or backing singers.
+- **Exclusions:** unwanted choir, spoken phrases, ad-libs, humming, vocal chops, or named-artist imitation.
+
+Keep production direction outside the lyric block:
+
+```text
+Create a [duration] [genre] song in [key] at [BPM].
+Vocal role: [solo, duet, call-and-response, or ensemble].
+Singer profile: [range], [timbre], [delivery], and [diction].
+Sing in [language and intended register]. Use backing vocals only for words
+shown in parentheses. No [unwanted vocal gestures or effects], and do not
+imitate a named singer.
+
+Lyrics:
+[Verse 1]
+[custom lyrics in the selected language and script]
+
+[Chorus]
+[lead line] ([intentional backing-vocal echo])
+```
+
+### Multilingual Work
+
+- Name the sung language explicitly even when custom lyrics make it apparent.
+- Choose the writing system or transliteration deliberately; do not convert scripts without user approval.
+- Keep one script inside a lyric version so the model does not infer accidental language switches.
+- Describe the intended register, dialect, formality, and any intentional code-switching.
+- Preserve the approved lyric text separately from the generation prompt. Lyria may alter, omit, or repeat words, so compare the returned text and audible performance against that source.
+- Treat pronunciation and language coverage as output-level QA. The API documentation says Lyria follows the prompt language, but it does not promise perfect diction for every language or regional register.
+
+### Vocal QA
+
+Audition and record:
+
+1. Whether the requested lead, duet, or ensemble roles are present.
+2. Whether every approved lyric line is sung, omitted, altered, or repeated.
+3. Whether the language, script-derived pronunciation, and intended register remain consistent.
+4. Whether the requested range, timbre, dynamics, ornamentation, and section entrances are followed.
+5. Whether backing vocals appear only where requested.
+6. Whether the lead remains intelligible against the arrangement without clipping or masking.
+7. Whether the ending contains a complete final phrase and musically useful decay.
+
+Do not classify a diction or lyric-adherence failure as a file-format problem. It is a stochastic prompt/adherence failure; any retry is a new paid generation and requires the approved retry policy.
+
+## Image-To-Music
+
+The underlying API accepts up to 10 base64-encoded images with MIME types. Prompt for the musical interpretation explicitly: mood, palette-to-timbre mapping, motion-to-rhythm mapping, and the desired structure. The current OpenMontage adapter accepts one `image_path` or one `image_url`.
+
+## Limitations And Safety
+
+- Generation is stochastic; identical prompts can differ.
+- Lyria 3 is single-turn; generated tracks cannot currently be refined through a multi-turn edit chain.
+- Safety filters may reject artist-voice imitation, copyrighted lyrics, or other restricted content.
+- All generated audio contains an imperceptible SynthID watermark.
+- Preview models and rate limits can change before stable release.
+- Official pages currently disagree between 44.1 kHz and 48 kHz descriptions. Probe every returned file and record the observed value.
+
+## Failure Triage
+
+| Symptom | Class | Action |
+|---|---|---|
+| `401` or invalid key | Auth | Verify the selected credential without printing it |
+| `403`, `API_KEY_SERVICE_BLOCKED` | Auth/project policy | Stop retries; fix the Google key, project, API enablement, or service restriction |
+| `429` | Rate limit | Retry only within the approved retry/budget policy |
+| Timeout | Transient/provider | Use the tool timeout policy; do not launch parallel duplicate paid calls |
+| No `output_audio` | Response parsing | Traverse `model_output` step content for an `audio` block |
+| Output longer/shorter than requested | Model behavior | Preserve source, probe, and create a separate exact-duration master |
+| Accidental vocals | Prompt/adherence | Strengthen the full instrumental exclusion list; audition the next paid result |
+| Safety rejection | Policy/prompt | Remove artist imitation or copyrighted material; do not disguise the request |
+
+## Official Sources
+
+- Gemini API music generation: https://ai.google.dev/gemini-api/docs/music-generation
+- Gemini Interactions API: https://ai.google.dev/gemini-api/docs/interactions-overview
+- Gemini Developer API pricing: https://ai.google.dev/gemini-api/docs/pricing
+- Google DeepMind Lyria prompt guide: https://deepmind.google/models/lyria/prompt-guide/
+- Lyria RealTime: https://ai.google.dev/gemini-api/docs/realtime-music-generation
+- Google announcement for Lyria 3 Pro: https://blog.google/innovation-and-ai/technology/ai/lyria-3-pro/

tests/contracts/test_phase3_contracts.py

@@ -186,6 +186,7 @@ class TestGoogleMusic:
         assert info["tier"] == "generate"
         assert info["capability"] == "music_generation"
         assert info["provider"] == "google"
+        assert info["agent_skills"] == ["lyria"]
 
     def test_duration_validation(self):
         tool = GoogleMusic()

tools/audio/google_music.py

@@ -44,7 +44,7 @@ class GoogleMusic(BaseTool):
         "  - Or set GOOGLE_APPLICATION_CREDENTIALS for Vertex AI service account."
     )
     fallback_tools = ["music_gen"]
-    agent_skills = ["music"]
+    agent_skills = ["lyria"]
 
     capabilities = [
         "generate_background_music",