Lyria music

Music gives a professional film warmth and pace, if it stays under the voice. One bed per film costs $0.08.

Use it

"music": {
  "model": "lyria-3.5",
  "prompt": "Minimal modern ambient, soft felt piano, warm analog pads, a very light pulse",
  "bpm": 80, "key": "D major", "volume": 0.2,
  "arc": { "The forecast": "Intro: a single felt-piano figure over a soft pad.", "Recap": "Resolve on a sustained chord." }
}

clearframe music <dir> --draft   # free synthesized pad, for timing and mix checks
clearframe plan <dir>            # ≈ $0.08
clearframe music <dir>           # → assets/music/bed.mp3 (+ bed.json with prompt and model notes)
node packages/engine/dist/skills/lyria-music/scripts/music.mjs --style "…" --bpm 80 --key "D major" --seconds 60 --section "0:00-0:08|sparse intro" --dry-run

The engine writes the structure for you. It groups beats by chapter, converts them to timestamps ([0:00 - 0:09] Intro: …), asks for about the film's length plus 2 s, adds "Instrumental only, no vocals" and a mix note ("sits under a spoken voiceover"), and asks for a clean ending on a sustained chord. Override per chapter with music.arc or fully with music.sections.

Contract: Lyria 3.5 / 3 Clip (MP3 path checked 2026-09-28)

POST https://generativelanguage.googleapis.com/v1beta/interactions with header x-goog-api-key

{ "model": "lyria-3.5",
  "input": "Minimal modern ambient, 80 BPM, in D major.\nInstrumental only, no vocals.\nDuration: about 48 seconds.\n[0:00 - 0:09] Intro: …\nEnding: end cleanly on a sustained chord, no fade-out.",
  "response_format": { "type": "audio" } }

• The response holds steps[type="model_output"].content[]: a text block (structure or lyrics) and an audio block { mime_type, data }.
• Output is 44.1 kHz stereo. Use the MP3 default without a MIME override. The Google music guide mentions WAV in prose but its request examples omit mime_type; WAV requests have failed in this project. The script accepts --format mp3 only. Convert locally with FFmpeg if WAV is needed; changing a filename does not convert audio.
• Save using the response MIME type (audio/mpeg and audio/mp3 both mean .mp3). Unknown formats fail explicitly. Draft music and RealTime still produce WAV locally.
• bed.json records the active generated file. Cache reuse requires both matching musical intent and a nonempty audio file; clearframe plan uses the same check. A format-default change alone does not regenerate an existing paid bed.
• input may also be an array with up to 10 images (mood references).
• Duration is steered in the prompt ("about 60 seconds") and by timestamped sections. lyria-3-clip-preview is always 30 s.
• There is no negative prompt and no seed, and identical calls vary. Everything is SynthID-watermarked. Named-artist prompts are blocked.

Lyria RealTime (experimental)

Use it when you need an exact BPM or scale, or a bed longer than a song. Set "model": "lyria-realtime" with weightedPrompts, bpm, density, brightness and scale, or run scripts/realtime.mjs.

• Endpoint: wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1alpha.GenerativeService.BidiGenerateMusic
• Protocol: send {setup:{model:"models/lyria-realtime-exp"}} and wait for setupComplete. Then send {clientContent:{weightedPrompts:[…]}}, {musicGenerationConfig:{bpm, density, brightness, scale, guidance, …}} and {playbackControl:"PLAY"}. Collect serverContent.audioChunks[].data: raw s16le PCM, 48 kHz, stereo.
• Each client message carries exactly one field. A config message replaces the whole config, and bpm or scale changes need RESET_CONTEXT.
• Unverified in the docs: raw-socket API-key auth (?key=, the Live API convention) and a v1beta URL. Prefer Lyria 3.5 unless you need RealTime's control.

Prompt recipes

Lead with genre, then instruments, tempo, key and mood. Keep it spare: the voice is the lead.

Useful Lyria vocabulary: Chillout, Minimal Techno, Deep House, Synthpop, Trip Hop, Orchestral Score, Piano Ballad. Instruments: Rhodes Piano, Synth Pads, Moog Oscillations, Cello, Harp, Marimba, Vibraphone, Kalimba, Precision Bass. Moods: Ambient, Chill, Dreamy, Relaxed, Upbeat, Triumphant (sparingly), Ethereal.

Mixing (the engine does this)

• The bed sits at volume 0.18–0.22 (about −14 dB) and is sidechain-ducked under the narration by a further ~4–6 dB.
• 1.5 s fade in, 2.5 s fade out, loudness-normalised master (−14 LUFS web, −16 internal via mix.loudness).
• If the film has no narration, raise volume to about 0.5 and let the music carry the rhythm; cut on bars (60 / bpm × 4 s).
• Short films: on 2026-10-04, Lyria returned 60–70 s songs for a 20 s request and put the timestamped drop about 17 s late, though it honoured the BPM. Splice bar-aligned pieces (open + the bars before the drop) rather than re-rolling. See docs/google-generation-field-notes.md.
• Land the drop. A composed bed's sections are a request, not a measurement. Run beatmap DIR on the MP3 that came back: it measures the tempo (listing half and double, since a 74 BPM half-time track reads as 148) and the drop (the bass jumping in 20 ms windows). Then music.drop: {"beat": "title"} (optionally at: "word:now", or song: 12.96 to override the measurement) starts the track so the drop plays on that beat. A drop later in the film than in the song delays the song's start. qa DIR confirms it is heard there in the final mix.