Live Music API - WebSockets API reference

Lyria RealTime 音乐生成功能使用基于 WebSockets 的持久性双向低延迟流式传输连接。在本部分中，您将找到有关 WebSockets API 的更多详细信息。

会话

WebSocket 连接会建立会话，以保持与模型的实时通信。在客户端发起新连接后，会话可以与服务器交换消息，以执行以下操作：

  • 发送提示和控制指令来引导音乐生成。
  • 发送音乐播放控制指令。
  • 接收音频块。

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 消息中的其他字段（仅限一个）。 （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

可选。控制模型选择输出 token 的方式。

对概率最高的 topK 词元进行采样。范围为 [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 降调大调或 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。