Live Music API - WebSockets API reference

La generazione di musica in tempo reale di Lyria utilizza una connessione di streaming persistente, bidirezionale 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 avvia una nuova connessione, la sessione può scambiare messaggi con il server per:

  • Inviare 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 del 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 Indicatori 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:
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 di 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:
setup

BidiGenerateMusicSetup

(Facoltativo) Configurazione della sessione inviata solo nel primo messaggio del client.
clientContent

BidiGenerateMusicClientContent

(Facoltativo) Prompt ponderati e configurazioni di generazione musicale come input della generazione musicale.

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:
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ù alti 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 dell'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 segue più da vicino, ma renderà le transizioni 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 della musica. Il valore predefinito è QUALITY.

MusicGenerationMode

Enum
MUSIC_GENERATION_MODE_UNSPECIFIED Questo valore non viene utilizzato.
QUALITY Questa modalità indirizza i prompt di testo verso regioni dello spazio latente con musica di qualità superiore.
DIVERSITY Questa modalità indirizza i prompt di testo verso regioni dello spazio latente con una maggiore diversità di musica.
VOCALIZATION Questa modalità indirizza i prompt di testo 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

Controllo della riproduzione per la generazione di musica.

Enum
PLAYBACK_CONTROL_UNSPECIFIED Questo valore non viene utilizzato.
PLAY Inizia a generare la musica.
PAUSE Metti in attesa la generazione di musica. Usa RIPRODUCI per riprendere dalla posizione corrente.
STOP Interrompi la generazione di musica e reimposta il contesto (i prompt vengono conservati). Usa PLAY 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:
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 client.
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 client devono attendere un messaggio BidiGenerateMusicSetupComplete prima di inviare altri messaggi.

Campi
model

string

Obbligatorio. Il nome della risorsa del modello. che funge da ID da utilizzare per il modello.

Formato: models/{model}

BidiGenerateMusicSetupComplete

Questo tipo non contiene campi.

Inviato in risposta a un messaggio BidiGenerateMusicSetup del cliente.

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 0. I pesi di tutti i weighted_prompts in questo messaggio BidiGenerateMusicClientContent verranno normalizzati.

Campo unione prompt.

prompt può essere solo uno dei seguenti:
text

string

Prompt di testo.

Ulteriori informazioni sui tipi

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