Live Music API - WebSockets API reference

Lyria RealTime 音樂生成功能會使用 WebSockets，建立持續性的雙向低延遲串流連線。本節將提供 WebSockets API 的其他詳細資料。

工作階段

WebSocket 連線會建立工作階段，與模型保持即時通訊。用戶端啟動新連線後，工作階段可以與伺服器交換訊息，以便：

  • 傳送提示和控制項，引導 AI 生成音樂。
  • 傳送音樂播放控制項。
  • 接收音訊區塊。

WebSocket 連線

如要啟動工作階段，請連線至這個 WebSocket 端點：

wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1alpha.GenerativeService.BidiGenerateMusic

工作階段設定

連線後的第一則訊息會設定工作階段期間使用的模型。

請參閱以下設定範例。請注意，SDK 中的名稱大小寫可能有所不同。您可以在這裡查詢 Python SDK 設定選項。


{
  "model": string
}

傳送訊息

如要透過 WebSocket 連線交換訊息，用戶端必須透過開啟的 WebSocket 連線傳送 JSON 物件。JSON 物件必須只包含下列物件集中的一個欄位：


{
  "setup": BidiGenerateMusicSetup,
  "client_content": BidiGenerateMusicClientContent,
  "music_generation_config": BidiGenerateMusicGenerationConfig,
  "playback_control": BidiGenerateMusicPlaybackControl
}

支援的用戶端訊息

下表列出支援的用戶端訊息：

訊息 說明
BidiGenerateMusicSetup 工作階段設定，只能在第一則訊息中傳送
BidiGenerateMusicClientContent 加權提示做為模型輸入內容
BidiGenerateMusicGenerationConfig 音樂生成設定
BidiGenerateMusicPlaybackControl 模型生成作業的播放控制信號

接收訊息

如要接收伺服器傳送的訊息，請監聽 WebSocket「message」事件，然後根據支援的伺服器訊息定義剖析結果。

請參閱以下資訊：

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()

伺服器訊息包含來自 BidiGenerateMusicServerMessage 訊息的其他欄位，且只能有一個。(JSON 中不會表示 messageType 聯集，因此欄位會出現在訊息的頂層)。

訊息和活動

AudioChunk

音訊區塊的表示法。

欄位

聯集欄位 content。

content 只能是下列其中一項：
data

bytes

音訊區塊的原始位元組。
mimeType

string

音訊區塊內容的 MIME 類型，例如「audio/wav」。
sourceMetadata

SourceMetadata

僅供輸出。生成這段音訊時使用的提示和設定。

SourceMetadata

用於生成這個音訊區塊的輸入來源相關中繼資料。

欄位
clientContent

BidiGenerateMusicClientContent

生成這個音訊區塊的加權提示。
musicGenerationConfig

BidiGenerateMusicGenerationConfig

生成這個音訊區塊的音樂生成設定。

BidiGenerateMusicClientContent

使用者輸入內容來開始或引導音樂播放。

欄位
weightedPrompts[]

WeightedPrompt

必要欄位。加權提示做為模型輸入內容。

BidiGenerateMusicClientMessage

用戶端在 BidiGenerateMusic 呼叫中傳送的訊息。

欄位

聯集欄位 messageType。

messageType 只能是下列其中一項：
setup

BidiGenerateMusicSetup

(選用步驟) 工作階段設定只會在第一則用戶端訊息中傳送。
clientContent

BidiGenerateMusicClientContent

(選用步驟) 加權提示和音樂生成設定，做為音樂生成的輸入內容。

musicGenerationConfig

BidiGenerateMusicGenerationConfig

(選用步驟) 音樂生成設定。
playbackControl

BidiGenerateMusicPlaybackControl

(選用步驟) 生成音樂的播放控制訊號。

BidiGenerateMusicFilteredPrompt

遭篩除的提示和原因。

欄位
filteredReason

string

僅供輸出。提示遭到篩除的原因。
聯集欄位 prompt。遭篩除的提示。prompt 只能是下列其中一項：
text

string

(選用步驟) 文字提示。

BidiGenerateMusicGenerationConfig

音樂生成設定。

欄位
temperature

float

(選用步驟) 控制音訊生成過程中的變異數。

值越大，變異數就越大。範圍為 [0.0, 3.0]。預設值為 1.1。
topK

int32

(選用步驟) 控管模型選取輸出符記的方式。

對機率最高的 Top-K 符記取樣。範圍為 [1, 1000]。預設值為 40。
seed

int32

(選用步驟) 生成 Seeds 音訊。如未設定，要求會使用隨機產生的種子。

guidance

float

(選用步驟) 控管模型遵循提示的程度。較高的引導值會更緊密地追蹤，但會使轉場效果更為突兀。範圍為 [0.0, 6.0]。預設值為 4.0。

bpm

int32

(選用步驟) 每分鐘心跳數。範圍為 [60, 200]。
density

float

(選用步驟) 聲音密度。範圍為 [0.0, 1.0]。
brightness

float

(選用步驟) 值越大，音訊越明亮。範圍為 [0.0, 1.0]。
scale

Scale

(選用步驟) 生成音樂的音階。
muteBass

bool

(選用步驟) 音訊輸出內容不應包含低音。
muteDrums

bool

(選用步驟) 音訊輸出內容不得包含鼓聲。
onlyBassAndDrums

bool

(選用步驟) 音訊輸出內容應只包含低音和鼓聲。
musicGenerationMode

MusicGenerationMode

(選用步驟) 音樂生成模式。預設值為 QUALITY。

MusicGenerationMode

列舉
MUSIC_GENERATION_MODE_UNSPECIFIED 這個值不會使用。
QUALITY 這個模式會將文字提示導向潛在空間中音樂品質較高的區域。
DIVERSITY 這個模式會將文字提示導向潛在空間區域，產生更多元的音樂。
VOCALIZATION 這個模式會將文字提示導向潛在空間區域，更可能生成人聲音樂。

規模

生成音樂的音階。

列舉
SCALE_UNSPECIFIED 預設值。這個值不會使用。
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 大調或降 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 大調或降 G 小調
B_FLAT_MAJOR_G_MINOR 降 B 大調或 G 小調
B_MAJOR_A_FLAT_MINOR B 大調或降 A 小調

BidiGenerateMusicPlaybackControl

控制生成的音樂播放。

列舉
PLAYBACK_CONTROL_UNSPECIFIED 這個值不會使用。
PLAY 開始生成音樂。
PAUSE 暫停生成音樂。使用「播放」鍵從目前位置繼續播放。
STOP 停止生成音樂並重設情境 (保留提示)。使用 PLAY 重新啟動音樂生成功能。
RESET_CONTEXT 重設情境 (保留提示)，但不會停止生成音樂。

BidiGenerateMusicServerContent

模型根據用戶端訊息產生的伺服器更新增量。

系統會盡快生成內容，但不會即時生成。用戶端可以選擇緩衝處理並即時播放。

欄位
audioChunks[]

AudioChunk

僅供輸出。模型生成的音訊區塊。

BidiGenerateMusicServerMessage

BidiGenerateMusic 呼叫的回應訊息。

欄位
聯集欄位 messageType。訊息類型。 messageType 只能是下列其中一項：
setupComplete

BidiGenerateMusicSetupComplete

僅供輸出。設定完成後，系統會傳送這則訊息，以回應用戶端的 BidiGenerateMusicSetup 訊息。
serverContent

BidiGenerateMusicServerContent

僅供輸出。模型根據用戶端訊息生成的內容。
filteredPrompt

BidiGenerateMusicFilteredPrompt

僅供輸出。遭篩除的提示和原因。
warning

string

僅供輸出。伺服器傳回的警告訊息。警告不會終止串流。

BidiGenerateMusicSetup

要在第一個 (且僅限第一個) BidiGenerateMusicClientMessage中傳送的訊息。

用戶端應等待 BidiGenerateMusicSetupComplete 訊息，再傳送任何其他訊息。

欄位
model

string

必要欄位。模型的資源名稱。這是模型使用的 ID。

格式：models/{model}

BidiGenerateMusicSetupComplete

這個類型沒有任何欄位。

用來回覆用戶端的 BidiGenerateMusicSetup 訊息。

WeightedPrompt

加權提示詞做為模型輸入內容。

欄位
weight

float

必要欄位。提示的權重。

權重是用來控管提示的相對重要性。權重越高越重要。

這個 BidiGenerateMusicClientContent 中所有 weighted_prompts 的權重不得全為 0。系統會將這則 BidiGenerateMusicClientContent 訊息中所有 weighted_prompts 的權重標準化。

聯集欄位 prompt。

prompt 只能是下列其中一項：
text

string

文字提示。

進一步瞭解類型

如要進一步瞭解 API 使用的型別，請參閱 Python SDK。