Live Music API - WebSockets API reference

A geração de música em tempo real da Lyria usa uma conexão de streaming persistente, bidirecional e de baixa latência usando WebSockets. Nesta seção, você encontra 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:

  • Enviar comandos e controles para direcionar a criação de músicas.
  • Enviar controles de reprodução de música.
  • Receber partes de áudio.

Conexão WebSocket

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

wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1alpha.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. A capitalização do nome nos SDKs pode variar. Confira as opções de configuração do SDK do Python.


{
  "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 clientes compatíveis

Confira as mensagens do 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, ouça o evento "message" do WebSocket e analise o resultado de acordo com a definição das mensagens compatíveis do servidor.

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 trecho de áudio.
mimeType

string

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

SourceMetadata

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

SourceMetadata

Metadados sobre a origem 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 gerar este trecho de áudio.

BidiGenerateMusicClientContent

Interação 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. A configuração da sessão é enviada apenas na primeira mensagem do cliente.
clientContent

BidiGenerateMusicClientContent

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

musicGenerationConfig

BidiGenerateMusicGenerationConfig

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

BidiGenerateMusicPlaybackControl

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

BidiGenerateMusicFilteredPrompt

Solicitação filtrada 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 uma das seguintes opções:
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 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.

Faz a amostragem dos 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 definido, a solicitação usará uma seed gerada aleatoriamente.

guidance

float

Opcional. Controla o quanto o modelo segue os comandos. Uma orientação maior segue mais de perto, 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 dos sons. O intervalo é [0.0, 1.0].
brightness

float

Opcional. Valores mais altos produzem 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 pode ter graves.
muteDrums

bool

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

bool

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

MusicGenerationMode

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

MusicGenerationMode

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

Escala

Escala da música gerada.

Enums
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 Um ré bemol maior ou fá menor
A_MAJOR_G_FLAT_MINOR Um acorde de lá maior ou sol bemol menor
B_FLAT_MAJOR_G_MINOR Si bemol maior ou sol menor
B_MAJOR_A_FLAT_MINOR B maior ou A bemol menor

BidiGenerateMusicPlaybackControl

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

Enums
PLAYBACK_CONTROL_UNSPECIFIED Esse valor não é usado.
PLAY Comece a gerar a música.
PAUSE Suspenda a geração de música. Use PLAY para retomar da posição atual.
STOP Interrompe a geração de música e redefine o contexto (comandos mantidos). Use PLAY para reiniciar a geração de música.
RESET_CONTEXT Redefina o contexto (comandos 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 fazer buffer e reproduzir em tempo real.

Campos
audioChunks[]

AudioChunk

Apenas saída. Trechos de áudio gerados pelo modelo.

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. Solicitação filtrada com motivo.
warning

string

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

BidiGenerateMusicSetup

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

Os clientes precisam aguardar uma mensagem BidiGenerateMusicSetupComplete antes de enviar outras mensagens.

Campos
model

string

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

Formato: models/{model}

BidiGenerateMusicSetupComplete

Esse tipo não tem campos.

Enviado em resposta a uma mensagem BidiGenerateMusicSetup do cliente.

WeightedPrompt

Prompt 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.