Live Music API - WebSockets API reference

A geração de música do Lyria RealTime usa uma conexão de streaming persistente, bidirecional e de baixa latência com WebSockets. Nesta seção, você vai encontrar mais detalhes sobre a API WebSockets.

Sessões

Uma conexão WebSocket estabelece uma sessão para manter uma comunicação em tempo real com o modelo. Depois que um cliente inicia uma nova conexão, a sessão pode trocar mensagens com o servidor para:

  • Envie comandos e controles para direcionar a geração de música.
  • Enviar controles de mídia.
  • Receber blocos de áudio.

Conexão WebSocket

Para iniciar uma sessão, conecte-se a este endpoint do WebSocket:

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

Configuração da sessão

A mensagem inicial após a conexão define o modelo a ser usado durante a sessão.

Confira o exemplo de configuração a seguir. As letras maiúsculas e minúsculas nos nomes dos SDKs podem variar. Confira as opções de configuração do SDK para Python aqui.


{
  "model": string
}

Enviar mensagens

Para trocar mensagens pela conexão WebSocket, o cliente precisa enviar um objeto JSON por uma conexão WebSocket aberta. O objeto JSON precisa ter exatamente um dos campos do seguinte conjunto de objetos:


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

Mensagens de cliente compatíveis

Confira as mensagens de cliente compatíveis na tabela a seguir:

Mensagem Descrição
BidiGenerateMusicSetup Configuração da sessão a ser enviada apenas na primeira mensagem
BidiGenerateMusicClientContent Comandos ponderados como entrada do modelo
BidiGenerateMusicGenerationConfig Configuração para geração de música
BidiGenerateMusicPlaybackControl Indicadores de controle de mídia para geração de modelos

Receber mensagens

Para receber mensagens do servidor, detecte o evento "message" do WebSocket e analise o resultado de acordo com a definição das mensagens de servidor compatíveis.

Confira estes guias:

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

As mensagens do servidor incluem exatamente um dos outros campos da mensagem BidiGenerateMusicServerMessage. A união messageType não é expressa em JSON, então o campo vai aparecer no nível superior da mensagem.

Mensagens e eventos

AudioChunk

Representação de um trecho de áudio.

Campos

Campo de união content.

content pode ser apenas de um dos tipos a seguir:
data

bytes

Bytes brutos do bloco de áudio.
mimeType

string

O tipo MIME do conteúdo do bloco de áudio, como "audio/wav".
sourceMetadata

SourceMetadata

Apenas saída. Comandos e configurações usados para gerar este trecho de áudio.

SourceMetadata

Metadados sobre a fonte de entrada usada para gerar esse trecho de áudio.

Campos
clientContent

BidiGenerateMusicClientContent

Comandos ponderados para gerar esse trecho de áudio.
musicGenerationConfig

BidiGenerateMusicGenerationConfig

Configuração de geração de música para criar este trecho de áudio.

BidiGenerateMusicClientContent

Entrada do usuário para iniciar ou direcionar a música.

Campos
weightedPrompts[]

WeightedPrompt

Obrigatório. Comandos ponderados como entrada do modelo.

BidiGenerateMusicClientMessage

Mensagens enviadas pelo cliente na chamada BidiGenerateMusic.

Campos

Campo de união messageType.

messageType pode ser apenas de um dos tipos a seguir:
setup

BidiGenerateMusicSetup

Opcional. Configuração da sessão enviada na primeira e única mensagem do cliente.
clientContent

BidiGenerateMusicClientContent

Opcional. Comandos ponderados e configurações de geração de música como entrada para a geração de música.
musicGenerationConfig

BidiGenerateMusicGenerationConfig

Opcional. Configuração para geração de música.
playbackControl

BidiGenerateMusicPlaybackControl

Opcional. Sinal de controle de mídia para a geração de música.

BidiGenerateMusicFilteredPrompt

Comando filtrado com motivo.

Campos
filteredReason

string

Apenas saída. O motivo pelo qual o comando foi filtrado.
Campo de união prompt. O comando que foi filtrado. prompt pode ser apenas de um dos tipos a seguir:
text

string

Opcional. Comando de texto.

BidiGenerateMusicGenerationConfig

Configuração para geração de música.

Campos
temperature

float

Opcional. Controla a variância na geração de áudio.

Valores mais altos produzem uma variância maior. O intervalo é [0.0, 3.0]. O padrão é 1.1.
topK

int32

Opcional. Controla como o modelo seleciona tokens para saída.

Amostra os tokens topK com as maiores probabilidades. O intervalo é [1, 1000]. O padrão é 40.
seed

int32

Opcional. Inicia a geração de áudio. Se não for definida, a solicitação vai usar uma semente gerada aleatoriamente.
guidance

float

Opcional. Controla o quanto o modelo segue os comandos. Um valor mais alto segue as instruções de forma mais precisa, mas torna as transições mais abruptas. O intervalo é [0.0, 6.0]. O padrão é 4.0.
bpm

int32

Opcional. Batimentos por minuto. O intervalo é [60, 200].
density

float

Opcional. Densidade de sons. O intervalo é [0.0, 1.0].
brightness

float

Opcional. Um valor mais alto produz um áudio mais brilhante. O intervalo é [0.0, 1.0].
scale

Scale

Opcional. Escala da música gerada.
muteBass

bool

Opcional. A saída de áudio não deve conter graves.
muteDrums

bool

Opcional. A saída de áudio não pode conter bateria.
onlyBassAndDrums

bool

Opcional. A saída de áudio deve conter apenas baixo e bateria.
musicGenerationMode

MusicGenerationMode

Opcional. O modo de geração de música. O padrão é QUALITY.

MusicGenerationMode

Tipos enumerados
MUSIC_GENERATION_MODE_UNSPECIFIED Esse valor não é usado.
QUALITY Esse modo direciona os comandos de texto para regiões de espaço latente com músicas de maior qualidade.
DIVERSITY Esse modo direciona os comandos de texto para regiões de espaço latente com uma maior diversidade de músicas.
VOCALIZATION Esse modo direciona os comandos de texto para regiões do espaço latente com maior probabilidade de gerar música vocal.

Escala

Escala da música gerada.

Tipos enumerados
SCALE_UNSPECIFIED Valor padrão. Esse valor não é usado.
C_MAJOR_A_MINOR Dó maior ou Lá menor
D_FLAT_MAJOR_B_FLAT_MINOR Ré bemol maior ou si bemol menor
D_MAJOR_B_MINOR Ré maior ou Si menor
E_FLAT_MAJOR_C_MINOR Mi bemol maior ou dó menor
E_MAJOR_D_FLAT_MINOR Mi maior ou ré bemol menor
F_MAJOR_D_MINOR Fá maior ou Ré menor
G_FLAT_MAJOR_E_FLAT_MINOR Sol bemol maior ou mi bemol menor
G_MAJOR_E_MINOR Sol maior ou Mi menor
A_FLAT_MAJOR_F_MINOR Lá bemol maior ou fá menor
A_MAJOR_G_FLAT_MINOR Lá maior ou sol bemol menor
B_FLAT_MAJOR_G_MINOR Si bemol maior ou sol menor
B_MAJOR_A_FLAT_MINOR Si maior ou Sol bemol menor

BidiGenerateMusicPlaybackControl

Controle de mídia para a geração de música.

Tipos enumerados
PLAYBACK_CONTROL_UNSPECIFIED Esse valor não é usado.
PLAY Comece a gerar a música.
PAUSE A geração de música está em pausa. Use PLAY para retomar da posição atual.
STOP Interrompe a geração de música e redefine o contexto (os comandos são mantidos). Use PLAY para reiniciar a geração de música.
RESET_CONTEXT Redefina o contexto (os comandos são mantidos) sem interromper a geração de música.

BidiGenerateMusicServerContent

Atualização incremental do servidor gerada pelo modelo em resposta às mensagens do cliente.

O conteúdo é gerado o mais rápido possível, e não em tempo real. Os clientes podem optar por armazenar em buffer e reproduzir em tempo real.

Campos
audioChunks[]

AudioChunk

Apenas saída. Partes de áudio que o modelo gerou.

BidiGenerateMusicServerMessage

Mensagem de resposta para a chamada BidiGenerateMusic.

Campos
Campo de união messageType. Tipo da mensagem. messageType pode ser apenas de um dos tipos a seguir:
setupComplete

BidiGenerateMusicSetupComplete

Apenas saída. Enviada em resposta a uma mensagem BidiGenerateMusicSetup do cliente quando a configuração é concluída.
serverContent

BidiGenerateMusicServerContent

Apenas saída. Conteúdo gerado pelo modelo em resposta às mensagens do cliente.
filteredPrompt

BidiGenerateMusicFilteredPrompt

Apenas saída. Comando filtrado com motivo.
warning

string

Apenas saída. A mensagem de aviso do servidor. Os avisos não encerram o stream.

BidiGenerateMusicSetup

Mensagem a ser enviada no primeiro (e apenas no primeiro) BidiGenerateMusicClientMessage.

Os clientes precisam esperar uma mensagem de BidiGenerateMusicSetupComplete antes de enviar outras.

Campos
model

string

Obrigatório. O nome do recurso do modelo. Isso serve como um ID para o modelo usar.

Formato: models/{model}

BidiGenerateMusicSetupComplete

Esse tipo não tem campos.

Enviada em resposta a uma mensagem BidiGenerateMusicSetup do cliente.

WeightedPrompt

Comando ponderado como entrada do modelo.

Campos
weight

float

Obrigatório. Peso do comando.

O peso é usado para controlar a importância relativa do comando. Pesos maiores são mais importantes do que pesos menores.

Os pesos de todos os weighted_prompts neste BidiGenerateMusicClientContent não podem ser todos 0. Os pesos de todos os weighted_prompts nesta mensagem BidiGenerateMusicClientContent serão normalizados.

Campo de união prompt.

prompt pode ser apenas de um dos tipos a seguir:
text

string

Comando de texto.

Mais informações sobre tipos

Para mais informações sobre os tipos usados pela API, consulte o SDK para Python.