Live Music API - WebSockets API reference

La génération de musique Lyria RealTime utilise une connexion de streaming persistante, bidirectionnelle et à faible latence à l'aide de WebSockets. Dans cette section, vous trouverez des informations supplémentaires sur l'API WebSockets.

Sessions

Une connexion WebSocket établit une session pour maintenir une communication en temps réel avec le modèle. Une fois qu'un client a établi une nouvelle connexion, la session peut échanger des messages avec le serveur pour :

  • Envoyez des prompts et des commandes pour orienter la génération de musique.
  • Envoyer des commandes de lecture de musique.
  • Recevoir des fragments audio.

Connexion WebSocket

Pour démarrer une session, connectez-vous à ce point de terminaison WebSocket :

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

Configuration de la session

Le message initial après la connexion définit le modèle à utiliser pendant la session.

Consultez l'exemple de configuration suivant. Notez que la casse des noms peut varier dans les SDK. Vous pouvez consulter les options de configuration du SDK Python ici.


{
  "model": string
}

Envoyer des messages

Pour échanger des messages via la connexion WebSocket, le client doit envoyer un objet JSON via une connexion WebSocket ouverte. L'objet JSON doit comporter exactement l'un des champs de l'ensemble d'objets suivant :


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

Messages client acceptés

Consultez les messages client acceptés dans le tableau suivant :

Message Description
BidiGenerateMusicSetup Configuration de la session envoyée uniquement dans le premier message
BidiGenerateMusicClientContent Prompts pondérés comme entrée du modèle
BidiGenerateMusicGenerationConfig Configuration pour la génération de musique
BidiGenerateMusicPlaybackControl Signaux de contrôle de la lecture pour la génération de modèles

Recevoir des messages

Pour recevoir des messages du serveur, écoutez l'événement "message" de WebSocket, puis analysez le résultat en fonction de la définition des messages serveur acceptés.

Consultez les références suivantes :

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

Les messages serveur incluent exactement l'un des autres champs du message BidiGenerateMusicServerMessage. (L'union messageType n'est pas exprimée en JSON, de sorte que le champ apparaît au niveau supérieur du message.)

Messages et événements

AudioChunk

Représentation d'un segment audio.

Champs

Champ d'union content.

content ne peut être qu'un des éléments suivants :
data

bytes

Octets bruts du fragment audio.
mimeType

string

Type MIME du contenu du fragment audio, par exemple "audio/wav".
sourceMetadata

SourceMetadata

Uniquement en sortie. Prompts et configuration utilisés pour générer ce fragment audio.

SourceMetadata

Métadonnées sur la source d'entrée utilisée pour générer ce fragment audio.

Champs
clientContent

BidiGenerateMusicClientContent

Requêtes pondérées pour générer ce segment audio.
musicGenerationConfig

BidiGenerateMusicGenerationConfig

Configuration de la génération de musique pour générer ce segment audio.

BidiGenerateMusicClientContent

Saisie de l'utilisateur pour lancer ou orienter la musique.

Champs
weightedPrompts[]

WeightedPrompt

Obligatoire. Requêtes pondérées comme entrée du modèle.

BidiGenerateMusicClientMessage

Messages envoyés par le client dans l'appel BidiGenerateMusic.

Champs

Champ d'union messageType.

messageType ne peut être qu'un des éléments suivants :
setup

BidiGenerateMusicSetup

Facultatif. Configuration de la session envoyée uniquement dans le premier message client.
clientContent

BidiGenerateMusicClientContent

Facultatif. Prompts pondérés et configurations de génération de musique comme entrée de la génération de musique.
musicGenerationConfig

BidiGenerateMusicGenerationConfig

Facultatif. Configuration pour la génération de musique.
playbackControl

BidiGenerateMusicPlaybackControl

Facultatif. Signal de contrôle de la lecture pour la génération de musique.

BidiGenerateMusicFilteredPrompt

Requête filtrée avec motif.

Champs
filteredReason

string

Uniquement en sortie. Raison pour laquelle la requête a été filtrée.
Champ d'union prompt. Prompt qui a été filtré. prompt ne peut être qu'un des éléments suivants :
text

string

Facultatif. Prompt textuel.

BidiGenerateMusicGenerationConfig

Configuration pour la génération de musique.

Champs
temperature

float

Facultatif. Contrôle la variance dans la génération audio.

Des valeurs plus élevées produisent une variance plus élevée. La plage est [0.0, 3.0]. La valeur par défaut est 1.1.
topK

int32

Facultatif. Contrôle la façon dont le modèle sélectionne les jetons pour la sortie.

Échantillonne les jetons topK ayant les probabilités les plus élevées. La plage est [1, 1000]. La valeur par défaut est 40.
seed

int32

Facultatif. Amorce la génération audio. Si ce paramètre n'est pas défini, la requête utilise une graine générée de manière aléatoire.
guidance

float

Facultatif. Contrôle dans quelle mesure le modèle respecte les prompts. Une valeur plus élevée permet de suivre plus fidèlement les instructions, mais rend les transitions plus abruptes. La plage est [0.0, 6.0]. La valeur par défaut est 4.0.
bpm

int32

Facultatif. Battements par minute. La plage est [60, 200].
density

float

Facultatif. Densité des sons. La plage est [0.0, 1.0].
brightness

float

Facultatif. Une valeur plus élevée produit un son plus clair. La plage est [0.0, 1.0].
scale

Scale

Facultatif. Gamme de la musique générée.
muteBass

bool

Facultatif. La sortie audio ne doit pas contenir de basses.
muteDrums

bool

Facultatif. La sortie audio ne doit pas contenir de batterie.
onlyBassAndDrums

bool

Facultatif. La sortie audio ne doit contenir que la basse et la batterie.
musicGenerationMode

MusicGenerationMode

Facultatif. Mode de génération de musique. La valeur par défaut est QUALITY.

MusicGenerationMode

Enums
MUSIC_GENERATION_MODE_UNSPECIFIED Cette valeur n'est pas utilisée.
QUALITY Ce mode oriente les prompts textuels vers des régions de l'espace latent contenant de la musique de meilleure qualité.
DIVERSITY Ce mode oriente les prompts textuels vers des régions de l'espace latent offrant une plus grande diversité musicale.
VOCALIZATION Ce mode oriente les prompts textuels vers des régions de l'espace latent plus susceptibles de générer de la musique vocale.

Échelle

Gamme de la musique générée.

Enums
SCALE_UNSPECIFIED Valeur par défaut. Cette valeur n'est pas utilisée.
C_MAJOR_A_MINOR Do majeur ou La mineur
D_FLAT_MAJOR_B_FLAT_MINOR Ré bémol majeur ou si bémol mineur
D_MAJOR_B_MINOR Ré majeur ou Si mineur
E_FLAT_MAJOR_C_MINOR Mi bémol majeur ou do mineur
E_MAJOR_D_FLAT_MINOR Mi majeur ou ré bémol mineur
F_MAJOR_D_MINOR Fa majeur ou Ré mineur
G_FLAT_MAJOR_E_FLAT_MINOR Sol bémol majeur ou mi bémol mineur
G_MAJOR_E_MINOR Sol majeur ou Mi mineur
A_FLAT_MAJOR_F_MINOR La bémol majeur ou Fa mineur
A_MAJOR_G_FLAT_MINOR La majeur ou Sol bémol mineur
B_FLAT_MAJOR_G_MINOR Si bémol majeur ou sol mineur
B_MAJOR_A_FLAT_MINOR Si majeur ou Sol bémol mineur

BidiGenerateMusicPlaybackControl

Commande de lecture pour la génération de musique.

Enums
PLAYBACK_CONTROL_UNSPECIFIED Cette valeur n'est pas utilisée.
PLAY Lancez la génération de la musique.
PAUSE Mettre en pause la génération de musique. Utilisez PLAY pour reprendre la lecture à partir de la position actuelle.
STOP Arrêtez la génération de musique et réinitialisez le contexte (les prompts sont conservés). Utilisez PLAY pour relancer la génération de musique.
RESET_CONTEXT Réinitialisez le contexte (les requêtes sont conservées) sans arrêter la génération de musique.

BidiGenerateMusicServerContent

Mise à jour incrémentielle du serveur générée par le modèle en réponse aux messages client.

Le contenu est généré aussi rapidement que possible, et non en temps réel. Les clients peuvent choisir de le mettre en mémoire tampon et de le lire en temps réel.

Champs
audioChunks[]

AudioChunk

Uniquement en sortie. Fragments audio générés par le modèle.

BidiGenerateMusicServerMessage

Message de réponse pour l'appel BidiGenerateMusic.

Champs
Champ d'union messageType. Type du message. messageType ne peut être qu'un des éléments suivants :
setupComplete

BidiGenerateMusicSetupComplete

Uniquement en sortie. Il est envoyé en réponse à un message BidiGenerateMusicSetup du client une fois la configuration terminée.
serverContent

BidiGenerateMusicServerContent

Uniquement en sortie. Contenu généré par le modèle en réponse aux messages client.
filteredPrompt

BidiGenerateMusicFilteredPrompt

Uniquement en sortie. Requête filtrée avec motif.
warning

string

Uniquement en sortie. Message d'avertissement du serveur. Les avertissements n'entraînent pas l'arrêt de la diffusion.

BidiGenerateMusicSetup

Message à envoyer uniquement dans le premier BidiGenerateMusicClientMessage.

Les clients doivent attendre un message BidiGenerateMusicSetupComplete avant d'envoyer d'autres messages.

Champs
model

string

Obligatoire. Nom de ressource du modèle. Il sert d'ID pour le modèle à utiliser.

Format : models/{model}

BidiGenerateMusicSetupComplete

Ce type ne comporte aucun champ.

Il est envoyé en réponse à un message BidiGenerateMusicSetup du client.

WeightedPrompt

Requête pondérée en tant qu'entrée du modèle.

Champs
weight

float

Obligatoire. Poids du prompt.

La pondération permet de contrôler l'importance relative de la requête. Les pondérations les plus élevées sont plus importantes que les plus faibles.

Les pondérations de tous les weighted_prompts de ce BidiGenerateMusicClientContent ne doivent pas toutes être égales à 0. Les pondérations de tous les weighted_prompts de ce message BidiGenerateMusicClientContent seront normalisées.

Champ d'union prompt.

prompt ne peut être qu'un des éléments suivants :
text

string

Prompt textuel.

En savoir plus sur les types

Pour en savoir plus sur les types utilisés par l'API, consultez le SDK Python.