Live Music API - WebSockets API reference

Lyria RealTime 音樂生成功能會使用 WebSockets,建立永久、雙向、低延遲的串流連線。本節將進一步說明 WebSockets API。

工作階段

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

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

WebSocket 連線

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

wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.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 訊息中剛好一個其他欄位。(messageType 聯集不會以 JSON 表示,因此欄位會顯示在訊息的頂層)。

訊息和事件

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

(選用步驟) 控制模型選取輸出詞元的方式。

對機率最高的前 K 個詞元取樣。範圍為 [1, 1000]。預設值為 40。

seed

int32

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

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 暫停生成音樂。使用 PLAY 即可從目前位置繼續播放。
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。