使用 Lyria RealTime 產生音樂

Gemini API 使用 Lyria RealTime，提供即時串流音樂生成模型的最新技術。開發人員可以利用這項 API 建構應用程式，讓使用者可以透過互動方式創作、持續調整及演奏樂器音樂。

如要體驗 Lyria RealTime 的建構功能，請在 AI Studio 中使用 Prompt DJ 或 MIDI DJ 應用程式！

音樂生成功能的運作方式

Lyria RealTime 音樂產生工具會使用 WebSocket 建立持續、雙向、低延遲的串流連線。

生成及控制音樂

Lyria RealTime 的運作方式與 Live API 類似，都是使用 WebSocket 與模型保持即時通訊。但這仍與對話式 AI 不太一樣，因為您無法與模型對話，必須使用特定格式才能提示模型。

以下程式碼示範如何產生音樂：

Python

這個範例會使用 client.aio.live.music.connect() 初始化 Lyria RealTime 工作階段，然後透過 session.set_weighted_prompts() 傳送初始提示，並使用 session.set_music_generation_config 傳送初始設定，啟動使用 session.play() 產生的音樂，並設定 receive_audio() 來處理收到的音訊區塊。

  import asyncio
  from google import genai
  from google.genai import types

  client = genai.Client(api_key=API_KEY, http_options={'api_version': 'v1alpha'})

  async def main():
      async def receive_audio(session):
        """Example background task to process incoming audio."""
        while True:
          async for message in session.receive():
            audio_data = message.server_content.audio_chunks[0].data
            # Process audio...
            await asyncio.sleep(10**-12)

      async with (
        client.aio.live.music.connect(model='models/lyria-realtime-exp') as session,
        asyncio.TaskGroup() as tg,
      ):
        # Set up task to receive server messages.
        tg.create_task(receive_audio(session))

        # Send initial prompts and config
        await session.set_weighted_prompts(
          prompts=[
            types.WeightedPrompt(text='minimal techno', weight=1.0),
          ]
        )
        await session.set_music_generation_config(
          config=types.LiveMusicGenerationConfig(bpm=90, temperature=1.0)
        )

        # Start streaming music
        await session.play()
  if __name__ == "__main__":
      asyncio.run(main())

JavaScript

這個範例會使用 client.live.music.connect() 初始化 Lyria RealTime 工作階段，然後透過 session.setWeightedPrompts() 傳送初始提示，並使用 session.setMusicGenerationConfig 傳送初始設定，使用 session.play() 啟動音樂產生作業，並設定 onMessage 回呼，以便處理收到的音訊區塊。

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({
  apiKey: API_KEY, // Do not store your API client-side!
  apiVersion: 'v1alpha',
});

// Create session object to control music generation.
const session: MusicSession = client.live.music.connect({
  model: 'models/lyria-realtime-exp',
  callbacks: {
    onMessage: (message) => {
      // Application logic: buffer and play using Web Audio API etc.
    },
    onError: (error) => {
      console.error('music session error:', error);
    },
    onClose: () => {
      console.log('Lyria RealTime stream closed.');
    }
  }
}); 

// Send initial prompts and config
await session.setWeightedPrompts({
  weightedPrompts: [{ text: 'minimal techno', weight: 1.0 }],
});
await session.setMusicGenerationConfig({
  musicGenerationConfig: { bpm: 90, temperature: 1.0 },
});

// Start generation
await session.play();

接著，您可以使用 session.play()、session.pause()、session.stop() 和 session.reset_context() 來啟動、暫停、停止或重設工作階段。

即時控制音樂

提示 Lyria RealTime

在串流活動期間，您隨時可以傳送新的 WeightedPrompt 訊息，以便變更產生的音樂。模型會根據新輸入內容流暢地轉換。

提示訊息必須採用正確的格式，並包含 text (實際提示訊息) 和 weight。weight 可以接受 0 以外的任何值。1.0 通常是個不錯的起點。

Python

  await session.set_weighted_prompts(
    prompts=[
      {"text": "Piano", "weight": 2.0},
      types.WeightedPrompt(text="Meditation", weight=0.5),
      types.WeightedPrompt(text="Live Performance", weight=1.0),
    ]
  )

JavaScript

  await session.setMusicGenerationConfig({
    weightedPrompts: [
      { text: 'Harmonica', weight: 0.3 },
      { text: 'Afrobeat', weight: 0.7 }
    ],
  });

請注意，當您大幅變更提示時，模型轉換可能會有些突然，因此建議您透過向模型傳送中間權重值，實作某種交叉淡出效果。

更新設定

您也可以即時更新音樂產生參數。您無法只更新一個參數，必須設定整個設定，否則其他欄位會重設為預設值。

由於更新 bpm 或比例會對模型造成重大變更，因此您���需要使用 reset_context() 告知模型重設其內容，以便考量新設定。這不會停止串流，但會造成嚴重的轉換。您不需要為其他參數執行這項操作。

Python

  await session.set_music_generation_config(
    config=types.LiveMusicGenerationConfig(
      bpm=128,
      scale=types.Scale.D_MAJOR_B_MINOR,
    )
  )
  await session.reset_context();

JavaScript

  await session.setMusicGenerationConfig({
    musicGenerationConfig: { bpm: 120, density: 0.75 },
  });
  await session.reset_context();

Lyria RealTime 提示指南

以下列舉可用於提示 Lyria RealTime 的提示 (僅列舉部分提示)：

  • 付款方式：303 Acid Bass, 808 Hip Hop Beat, Accordion, Alto Saxophone, Bagpipes, Balalaika Ensemble, Banjo, Bass Clarinet, Bongos, Boomy Bass, Bouzouki, Buchla Synths, Cello, Charango, Clavichord, Conga Drums, Didgeridoo, Dirty Synths, Djembe, Drumline, Dulcimer, Fiddle, Flamenco Guitar, Funk Drums, Glockenspiel, Guitar, Hang Drum, Harmonica, Harp, Harpsichord, Hurdy-gurdy, Kalimba, Koto, Lyre, Mandolin, Maracas, Marimba, Mbira, Mellotron, Metallic Twang, Moog Oscillations, Ocarina, Persian Tar, Pipa, Precision Bass, Ragtime Piano, Rhodes Piano, Shamisen, Shredding Guitar, Sitar, Slide Guitar, Smooth Pianos, Spacey Synths, Steel Drum, Synth Pads, Tabla, TR-909 Drum Machine, Trumpet, Tuba, Vibraphone, Viola Ensemble, Warm Acoustic Guitar, Woodwinds, ...
  • 音樂類型：Acid Jazz, Afrobeat, Alternative Country, Baroque, Bengal Baul, Bhangra, Bluegrass, Blues Rock, Bossa Nova, Breakbeat, Celtic Folk, Chillout, Chiptune, Classic Rock, Contemporary R&B, Cumbia, Deep House, Disco Funk, Drum & Bass, Dubstep, EDM, Electro Swing, Funk Metal, G-funk, Garage Rock, Glitch Hop, Grime, Hyperpop, Indian Classical, Indie Electronic, Indie Folk, Indie Pop, Irish Folk, Jam Band, Jamaican Dub, Jazz Fusion, Latin Jazz, Lo-Fi Hip Hop, Marching Band, Merengue, New Jack Swing, Minimal Techno, Moombahton, Neo-Soul, Orchestral Score, Piano Ballad, Polka, Post-Punk, 60s Psychedelic Rock, Psytrance, R&B, Reggae, Reggaeton, Renaissance Music, Salsa, Shoegaze, Ska, Surf Rock, Synthpop, Techno, Trance, Trap Beat, Trip Hop, Vaporwave, Witch house, ...
  • 心情/說明：Acoustic Instruments, Ambient, Bright Tones, Chill, Crunchy Distortion, Danceable, Dreamy, Echo, Emotional, Ethereal Ambience, Experimental, Fat Beats, Funky, Glitchy Effects, Huge Drop, Live Performance, Lo-fi, Ominous Drone, Psychedelic, Rich Orchestration, Saturated Tones, Subdued Melody, Sustained Chords, Swirling Phasers, Tight Groove, Unsettling, Upbeat, Virtuoso, Weird Noises, ...

以上只是其中幾個例子，Lyria RealTime 還能做更多事情。您可以嘗試使用自己的提示！

最佳做法

  • 用戶端應用程式必須實作完善的音訊緩衝功能，確保順暢的播放效果。這有助於考量網路抖動和產生延遲時間的輕微變化。
  • 有效提示：
    • 文意要明確。使用形容詞描述情緒、類型和樂器。
    • 逐步重複實驗並調整方向。請勿完全變更提示，而是嘗試新增或修改元素，讓音樂轉換得更流暢。
    • 嘗試調整 WeightedPrompt 的權重，影響新提示對目前產生內容的影響程度。

技術詳細資料

本節將說明如何使用 Lyria RealTime 音樂產生功能。

規格

  • 輸出格式：原始 16 位元 PCM 音訊
  • 取樣率：48kHz
  • 聲道：2 (立體聲)

控制項

傳送含有以下內容的訊息，即可即時影響音樂產生：

  • WeightedPrompt：描述音樂構想、類型、樂器、情緒或特徵的文字字串。您可以提供多個提示，以便混合影響力。如要進一步瞭解如何最佳化提示 Lira RealTime，請參閱上文。
  • MusicGenerationConfig：音樂產生程序的設定，會影響輸出音訊的特性。參數包括：
    • guidance：(浮點值) 範圍：[0.0, 6.0]。預設值：4.0。控制模型遵循提示的嚴謹程度。較高的引導程度可提高使用者遵循提示的程度，但會讓轉場變得更突兀。
    • bpm：(int) 範圍：[60, 200]。設定要為產生的音樂設定每分鐘心跳數。您需要停止/播放或重設模型的上下文，才能考量新的 bpm。
    • density：(浮點值) 範圍：[0.0, 1.0]。控制音符/音效的密度。值越低，音樂就會越稀疏；值越高，音樂就會越「繁忙」。
    • brightness：(浮點值) 範圍：[0.0, 1.0]。調整音調品質。值越高，音效就會越「明亮」，通常會強調較高的頻率。
    • scale：(列舉) 設定產生的音階 (音階和模式)。使用 SDK 提供的 Scale 列舉值。您需要停止/播放或重設模型的上下文，才能考量新的比例。
    • mute_bass：(bool) 預設值：False。控制模型是否減少輸出的低音。
    • mute_drums：(bool) 預設值：False。控制模型輸出內容是否會減少輸出音訊的鼓聲。
    • only_bass_and_drums：(bool) 預設值：False。引導模型嘗試只輸出低音和鼓聲。
  • PlaybackControl：用於控制播放功能的指令，例如播放、暫停、停止或重設內容。

對於 bpm、density、brightness 和 scale，如果未提供值，模型會根據您最初的提示決定最適合的值。

您也可以在 MusicGenerationConfig 中自訂其他傳統參數，例如 temperature (0.0 到 3.0，預設為 1.1)、top_k (1 到 1000，預設為 40) 和 seed (0 到 2 147 483 647，預設為隨機選取)。

縮放列舉值

以下是模型可接受的所有縮放值：

列舉值 音階 / 調性
C_MAJOR_A_MINOR 升 C 大調 / A 小調
D_FLAT_MAJOR_B_FLAT_MINOR D♭ 大調 / B♭ 小調
D_MAJOR_B_MINOR D 大調 / B 小調
E_FLAT_MAJOR_C_MINOR 降 E 大調 / C 小調
E_MAJOR_D_FLAT_MINOR E 大調 / C♯/D♭ 小調
F_MAJOR_D_MINOR F 大調 / D 小調
G_FLAT_MAJOR_E_FLAT_MINOR G♭ 大調 / E♭ 小調
G_MAJOR_E_MINOR G 大調 / E 小調
A_FLAT_MAJOR_F_MINOR A♭ 大調 / F 小調
A_MAJOR_G_FLAT_MINOR A 大調 / F♯/G♭ 小調
B_FLAT_MAJOR_G_MINOR B♭ 大調 / G 小調
B_MAJOR_A_FLAT_MINOR B 大調 / G♯/A♭ 小調
SCALE_UNSPECIFIED 預設 / 由模型決定

該模型可引導播放的音符，但不會區分相對音階。因此，每個列舉都會對應至相對主要和次要版本。舉例來說，C_MAJOR_A_MINOR 會對應到鋼琴的所有白鍵，而 F_MAJOR_D_MINOR 則會對應到所有白鍵 (除了降 B 音)。

限制

  • 僅有純音樂：模型只會產生純音樂。
  • 安全性：系統會透過安全篩選機制檢查提示。系統會忽略觸發篩選器的提示，並在輸出的 filtered_prompt 欄位中寫入說明。
  • 浮水印：輸出音訊一律會加上浮水印，以便辨識，這符合我們的負責任 AI 原則。

後續步驟

如需更多程式碼範例和教學課程，請瀏覽食譜。