使用 Lyria RealTime 即時生成音樂

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

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

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

生成及控制音樂

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': 'v1beta'})

  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: "v1beta" ,
});

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 (實際提示) 和 weightweight 可以是 0 以外的任何值。1.0 通常是不錯的起點。

Python

  from google.genai import types

  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.setWeightedPrompts({
    weightedPrompts: [
      { text: 'Harmonica', weight: 0.3 },
      { text: 'Afrobeat', weight: 0.7 }
    ],
  });

請注意,大幅變更提示時,模型轉換可能會有些突然,因此建議傳送中間權重值給模型,實作某種淡入淡出效果。

更新設定

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

由於更新 BPM 或音階會大幅改變模型,您也需要使用 reset_context() 重設模型的情境,才能將新設定納入考量。這不會停止串流,但會是硬性轉換。其他參數則不需要。

Python

  from google.genai import types

  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 會使用加權提示詞,動態融合音樂類型、樂器和情緒。如要瞭解提示詞引導策略、關鍵字標記詞彙和完整提示詞範例,請參閱 Lyria 提示詞指南

最佳做法

  • 用戶端應用程式必須實作完善的音訊緩衝區,確保播放過程順暢。這有助於考量網路抖動和生成延遲的微小變化。
  • 有效提示:
    • 文意要明確。使用形容詞描述情境、曲風和樂器。
    • 逐步迭代和引導。請嘗試新增或修改元素,讓音樂更流暢地變形,而不是完全變更提示。
    • 實驗 WeightedPrompt 的權重,瞭解新提示對持續生成作業的影響程度。

技術詳細資料

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

規格

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

控制項

傳送含有下列內容的訊息,即可即時影響音樂生成:

  • WeightedPrompt:描述音樂概念、類型、樂器、情緒或特徵的文字字串。您可以提供多個提示,混合不同風格的影響。如要進一步瞭解如何以最佳方式提示 Lyria RealTime,請參閱上文
  • MusicGenerationConfig:音樂生成程序的設定,會影響輸出音訊的特徵。參數 include:
    • 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。 引導模型只輸出貝斯和鼓聲。
    • music_generation_mode:(列舉) 指出模型應著重於QUALITY (預設值) 或DIVERSITY。也可以設為 VOCALIZATION,讓模型將人聲生成為另一種樂器 (新增為提示)。
  • PlaybackControl:控制播放作業的指令,例如播放、暫停、停止或重設內容。

如果沒有提供 bpmdensitybrightnessscale 的值,模型會根據初始提示決定最佳做法。

您也可以在 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 技術 原則,輸出音訊一律會加上浮水印,以利識別。

後續步驟

如需更多程式碼範例和教學課程,請參閱教戰手冊