使用 Lyria RealTime 產生音樂

Gemini API 採用 Lyria RealTime，可存取最先進的即時串流音樂生成模型。開發人員可運用這項技術建構應用程式，讓使用者以互動方式創作、持續引導及演奏樂器音樂。

如要體驗 Lyria RealTime 的功能，請在 AI Studio 中使用「提示 DJ」或「MIDI DJ」應用程式！

音樂生成功能的運作方式

Lyria RealTime 音樂生成功能會使用 WebSocket，建立持續性的雙向低延遲串流連線。

生成及控制音樂

Lyria RealTime 的運作方式與 Live API 有點類似，都是使用 WebSocket 與模型保持即時通訊。但這與模型對話仍有差異，因為你無法與模型對話，而且必須使用特定格式提示模型。

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

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(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";
import Speaker from "speaker";
import { Buffer } from "buffer";

const client = new GoogleGenAI({
  apiKey: GEMINI_API_KEY,
    apiVersion: "v1alpha" ,
});

async function main() {
  const speaker = new Speaker({
    channels: 2,       // stereo
    bitDepth: 16,      // 16-bit PCM
    sampleRate: 44100, // 44.1 kHz
  });

  const session = await client.live.music.connect({
    model: "models/lyria-realtime-exp",
    callbacks: {
      onmessage: (message) => {
        if (message.serverContent?.audioChunks) {
          for (const chunk of message.serverContent.audioChunks) {
            const audioBuffer = Buffer.from(chunk.data, "base64");
            speaker.write(audioBuffer);
          }
        }
      },
      onerror: (error) => console.error("music session error:", error),
      onclose: () => console.log("Lyria RealTime stream closed."),
    },
  });

  await session.setWeightedPrompts({
    weightedPrompts: [
      { text: "Minimal techno with deep bass, sparse percussion, and atmospheric synths", weight: 1.0 },
    ],
  });

  await session.setMusicGenerationConfig({
    musicGenerationConfig: {
      bpm: 90,
      temperature: 1.0,
      audioFormat: "pcm16",  // important so we know format
      sampleRateHz: 44100,
    },
  });

  await session.play();
}

main().catch(console.error);

然後使用 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,
      music_generation_mode=types.MusicGenerationMode.QUALITY
    )
  )
  await session.reset_context();

JavaScript

  await session.setMusicGenerationConfig({
    musicGenerationConfig: { 
      bpm: 120,
      density: 0.75,
      musicGenerationMode: MusicGenerationMode.QUALITY
    },
  });
  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：描述音樂概念、類型、樂器、情緒或特徵的文字字串。您可以提供多個提示，混合不同風格的影響。如要進一步瞭解如何以最佳方式提示 Lyria RealTime，請參閱上文。
  • MusicGenerationConfig：音樂生成程序的設定，會影響輸出音訊的特徵。參數 include:
    • guidance：(浮點數) 範圍：[0.0, 6.0]。預設值：4.0。 控制模型遵循提示的嚴格程度。指導值越高，越能按照提示詞生成內容，但轉場效果會更突兀。
    • bpm：(int) 範圍：[60, 200]。 設定要生成的音樂每分鐘節拍數。您需要停止/播放或重設模型的脈搏數，模型才會將新的每分鐘心跳數納入考量。
    • 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。 引導模型只輸出貝斯和鼓聲。
    • music_generation_mode：(列舉) 向模型指出是否應著重於QUALITY (預設值) 或DIVERSITY。也可以設為 VOCALIZATION，讓模型將人聲生成為另一種樂器 (將人聲新增為新的提示)。
  • PlaybackControl：控制播放作業的指令，例如播放、暫停、停止或重設內容。

如果沒有提供 bpm、density、brightness 和 scale 的值，模型會根據初始提示決定最佳做法。

您也可以在 MusicGenerationConfig 中自訂更多傳統參數，例如 temperature (0.0 至 3.0，預設為 1.1)、top_k (1 至 1000，預設為 40) 和 seed (0 至 2147483647，預設為隨機選取)。

縮放列舉值

模型可接受的所有比例值如下：

列舉值 音階 / 調性
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 原則。

後續步驟

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