Live Music API - WebSockets API reference

La generazione di musica Lyria RealTime utilizza una connessione di streaming bidirezionale, persistente e a bassa latenza tramite WebSockets. In questa sezione troverai ulteriori dettagli sull'API WebSockets.

Sessioni

Una connessione WebSocket stabilisce una sessione per mantenere una comunicazione in tempo reale con il modello. Dopo che un client ha avviato una nuova connessione, la sessione può scambiare messaggi con il server per:

  • Invia prompt e controlli per guidare la generazione di musica.
  • Inviare i controlli di riproduzione musicale.
  • Ricevere segmenti audio.

Connessione WebSocket

Per avviare una sessione, connettiti a questo endpoint websocket:

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

Configurazione sessione

Il messaggio iniziale dopo la connessione imposta il modello da utilizzare durante la sessione.

Vedi la seguente configurazione di esempio. Tieni presente che la distinzione tra maiuscole e minuscole nei nomi negli SDK può variare. Puoi cercare le opzioni di configurazione dell'SDK Python qui.


{
  "model": string
}

Inviare messaggi

Per scambiare messaggi tramite la connessione WebSocket, il client deve inviare un oggetto JSON tramite una connessione WebSocket aperta. L'oggetto JSON deve avere esattamente uno dei campi del seguente insieme di oggetti:


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

Messaggi dei clienti supportati

Consulta i messaggi client supportati nella tabella seguente:

Messaggio Descrizione
BidiGenerateMusicSetup Configurazione della sessione da inviare solo nel primo messaggio
BidiGenerateMusicClientContent Prompt ponderati come input del modello
BidiGenerateMusicGenerationConfig Configurazione per la generazione di musica
BidiGenerateMusicPlaybackControl Segnali di controllo della riproduzione per la generazione del modello

Ricevere messaggi

Per ricevere messaggi dal server, ascolta l'evento "message" di WebSocket e poi analizza il risultato in base alla definizione dei messaggi del server supportati.

Vedi quanto segue:

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

I messaggi del server includono esattamente uno degli altri campi del messaggio BidiGenerateMusicServerMessage. L'unione messageType non è espressa in JSON, quindi il campo verrà visualizzato nel livello superiore del messaggio.

Messaggi ed eventi

AudioChunk

Rappresentazione di un blocco audio.

Campi

Campo unione content.

content può essere solo uno dei seguenti tipi:
data

bytes

Byte non elaborati del blocco audio.
mimeType

string

Il tipo MIME dei contenuti del blocco audio, ad esempio "audio/wav".
sourceMetadata

SourceMetadata

Solo output. Prompt e configurazione utilizzati per generare questo blocco audio.

SourceMetadata

Metadati sull'origine dell'input utilizzata per generare questo blocco audio.

Campi
clientContent

BidiGenerateMusicClientContent

Prompt ponderati per la generazione di questo blocco audio.
musicGenerationConfig

BidiGenerateMusicGenerationConfig

Configurazione della generazione di musica per generare questo blocco audio.

BidiGenerateMusicClientContent

Input dell'utente per avviare o controllare la musica.

Campi
weightedPrompts[]

WeightedPrompt

Obbligatorio. Prompt ponderati come input del modello.

BidiGenerateMusicClientMessage

Messaggi inviati dal client nella chiamata BidiGenerateMusic.

Campi

Campo unione messageType.

messageType può essere solo uno dei seguenti tipi:
setup

BidiGenerateMusicSetup

Facoltativo. Configurazione della sessione inviata nel primo e unico messaggio del client.
clientContent

BidiGenerateMusicClientContent

Facoltativo. Prompt ponderati e configurazioni di generazione di musica come input della generazione di musica.
musicGenerationConfig

BidiGenerateMusicGenerationConfig

Facoltativo. Configurazione per la generazione di musica.
playbackControl

BidiGenerateMusicPlaybackControl

Facoltativo. Segnale di controllo della riproduzione per la generazione di musica.

BidiGenerateMusicFilteredPrompt

Prompt filtrato con motivo.

Campi
filteredReason

string

Solo output. Il motivo per cui il prompt è stato filtrato.
Campo unione prompt. Il prompt che è stato filtrato. prompt può essere solo uno dei seguenti tipi:
text

string

Facoltativo. Prompt di testo.

BidiGenerateMusicGenerationConfig

Configurazione per la generazione di musica.

Campi
temperature

float

Facoltativo. Controlla la varianza nella generazione dell'audio.

Valori più elevati producono una varianza maggiore. L'intervallo è [0.0, 3.0]. Il valore predefinito è 1,1.
topK

int32

Facoltativo. Controlla il modo in cui il modello seleziona i token per l'output.

Campiona i token Top-K con le probabilità più alte. L'intervallo è [1, 1000]. Il valore predefinito è 40.
seed

int32

Facoltativo. Generazione audio dei semi. Se non viene impostato, la richiesta utilizza un seme generato in modo casuale.
guidance

float

Facoltativo. Controlla la precisione con cui il modello segue i prompt. Una guida più elevata viene seguita più da vicino, ma le transizioni saranno più brusche. L'intervallo è [0.0, 6.0]. Il valore predefinito è 4.0.
bpm

int32

Facoltativo. Battiti al minuto. L'intervallo è [60, 200].
density

float

Facoltativo. Densità dei suoni. L'intervallo è [0.0, 1.0].
brightness

float

Facoltativo. Un valore più alto produce un audio più brillante. L'intervallo è [0.0, 1.0].
scale

Scale

Facoltativo. Scala della musica generata.
muteBass

bool

Facoltativo. L'output audio non deve contenere bassi.
muteDrums

bool

Facoltativo. L'output audio non deve contenere batteria.
onlyBassAndDrums

bool

Facoltativo. L'output audio deve contenere solo basso e batteria.
musicGenerationMode

MusicGenerationMode

Facoltativo. La modalità di generazione di musica. Il valore predefinito è QUALITY.

MusicGenerationMode

Enum
MUSIC_GENERATION_MODE_UNSPECIFIED Questo valore non viene utilizzato.
QUALITY Questa modalità indirizza i prompt testuali verso regioni dello spazio latente con musica di qualità superiore.
DIVERSITY Questa modalità indirizza i prompt testuali verso regioni dello spazio latente con una maggiore diversità musicale.
VOCALIZATION Questa modalità indirizza i prompt testuali verso regioni dello spazio latente più propense a generare musica vocale.

Scala

Scala della musica generata.

Enum
SCALE_UNSPECIFIED Valore predefinito. Questo valore non viene utilizzato.
C_MAJOR_A_MINOR Do maggiore o La minore
D_FLAT_MAJOR_B_FLAT_MINOR Re bemolle maggiore o Si bemolle minore
D_MAJOR_B_MINOR Re maggiore o Si minore
E_FLAT_MAJOR_C_MINOR Mi bemolle maggiore o Do minore
E_MAJOR_D_FLAT_MINOR Mi maggiore o Re bemolle minore
F_MAJOR_D_MINOR Fa maggiore o re minore
G_FLAT_MAJOR_E_FLAT_MINOR Sol bemolle maggiore o Mi bemolle minore
G_MAJOR_E_MINOR Sol maggiore o Mi minore
A_FLAT_MAJOR_F_MINOR La bemolle maggiore o fa minore
A_MAJOR_G_FLAT_MINOR La maggiore o Sol bemolle minore
B_FLAT_MAJOR_G_MINOR Si bemolle maggiore o Sol minore
B_MAJOR_A_FLAT_MINOR Si maggiore o La bemolle minore

BidiGenerateMusicPlaybackControl

Controlli di riproduzione per la generazione di musica.

Enum
PLAYBACK_CONTROL_UNSPECIFIED Questo valore non viene utilizzato.
PLAY Inizia a generare la musica.
PAUSE Metti in pausa la generazione di musica. Utilizza PLAY per riprendere dalla posizione corrente.
STOP Interrompe la generazione di musica e reimposta il contesto (i prompt vengono conservati). Usa RIPRODUCI per riavviare la generazione di musica.
RESET_CONTEXT Reimposta il contesto (i prompt vengono mantenuti) senza interrompere la generazione di musica.

BidiGenerateMusicServerContent

Aggiornamento incrementale del server generato dal modello in risposta ai messaggi del client.

I contenuti vengono generati il più rapidamente possibile e non in tempo reale. I client possono scegliere di memorizzarlo nel buffer e riprodurlo in tempo reale.

Campi
audioChunks[]

AudioChunk

Solo output. I segmenti audio generati dal modello.

BidiGenerateMusicServerMessage

Messaggio di risposta per la chiamata BidiGenerateMusic.

Campi
Campo unione messageType. Il tipo di messaggio. messageType può essere solo uno dei seguenti tipi:
setupComplete

BidiGenerateMusicSetupComplete

Solo output. Inviato in risposta a un messaggio BidiGenerateMusicSetup del cliente al termine della configurazione.
serverContent

BidiGenerateMusicServerContent

Solo output. Contenuti generati dal modello in risposta ai messaggi del cliente.
filteredPrompt

BidiGenerateMusicFilteredPrompt

Solo output. Prompt filtrato con motivo.
warning

string

Solo output. Il messaggio di avviso del server. Gli avvisi non interrompono lo stream.

BidiGenerateMusicSetup

Messaggio da inviare nel primo (e solo nel primo) BidiGenerateMusicClientMessage.

I clienti devono attendere un messaggio BidiGenerateMusicSetupComplete prima di inviare altri messaggi.

Campi
model

string

Obbligatorio. Il nome della risorsa del modello. Viene utilizzato come ID per il modello.

Formato: models/{model}

BidiGenerateMusicSetupComplete

Questo tipo non ha campi.

Inviato in risposta a un messaggio BidiGenerateMusicSetup del client.

WeightedPrompt

Prompt ponderato come input del modello.

Campi
weight

float

Obbligatorio. Peso del prompt.

Il peso viene utilizzato per controllare l'importanza relativa del prompt. Le ponderazioni più elevate sono più importanti di quelle inferiori.

I pesi di tutti i weighted_prompts in questo BidiGenerateMusicClientContent non devono essere tutti pari a 0. I pesi di tutti i weighted_prompts in questo messaggio BidiGenerateMusicClientContent verranno normalizzati.

Campo unione prompt.

prompt può essere solo uno dei seguenti tipi:
text

string

Prompt di testo.

Scopri di più sui tipi

Per ulteriori informazioni sui tipi utilizzati dall'API, consulta l'SDK Python.