Live Music API - WebSockets API reference

La génération de musique en temps réel Lyria 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 requêtes et des commandes pour orienter la génération de musique.
  • Envoyer des commandes de lecture de musique
  • Recevez des blocs audio.

Connexion WebSocket

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

wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1alpha.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 à envoyer uniquement dans le premier message
BidiGenerateMusicClientContent Requêtes pondérées 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, donc le champ apparaîtra au niveau supérieur du message.)

Messages et événements

AudioChunk

Représentation d'un bloc audio.

Champs

Champ d'union content.

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

bytes

Octets bruts du segment audio.
mimeType

string

Type MIME du contenu du bloc audio, tel que "audio/wav".
sourceMetadata

SourceMetadata

Uniquement en sortie. Requêtes et configuration utilisées pour générer ce segment audio.

SourceMetadata

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

Champs
clientContent

BidiGenerateMusicClientContent

Pondération des requêtes pour générer ce segment audio.
musicGenerationConfig

BidiGenerateMusicGenerationConfig

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

BidiGenerateMusicClientContent

Saisie utilisateur pour démarrer 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. Configurations de génération de musique et requêtes pondérées en tant qu'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. Requête filtrée. prompt ne peut être qu'un des éléments suivants :
text

string

Facultatif. Requête textuelle.

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 plus fortes probabilités. La plage est [1, 1000]. La valeur par défaut est 40.

seed

int32

Facultatif. Génère l'audio des graines. Si elle n'est pas définie, la requête utilise une graine générée de manière aléatoire.

guidance

float

Facultatif. Contrôle la précision avec laquelle le modèle suit les requêtes. Plus le degré d'orientation est élevé, plus le suivi est précis, mais les transitions sont 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. Plus la valeur est élevée, plus le son est 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 des basses et des percussions.
musicGenerationMode

MusicGenerationMode

Facultatif. Mode de génération de la 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 requêtes textuelles vers des régions de l'espace latent avec de la musique de meilleure qualité.
DIVERSITY Ce mode oriente les requêtes textuelles vers des régions de l'espace latent présentant une plus grande diversité musicale.
VOCALIZATION Ce mode oriente les requêtes textuelles 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 Fa 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 bémol majeur ou la bémol mineur

BidiGenerateMusicPlaybackControl

Contrôle de la lecture pour la génération de musique.

Enums
PLAYBACK_CONTROL_UNSPECIFIED Cette valeur n'est pas utilisée.
PLAY Commencez à générer la musique.
PAUSE Mets la génération de musique en pause. Utilisez PLAY pour reprendre la lecture à partir de la position actuelle.
STOP Arrête la génération de musique et réinitialise le contexte (les requêtes sont conservées). Utilisez PLAY pour redémarrer 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 ne mettent pas fin au flux.

BidiGenerateMusicSetup

Message à envoyer dans le premier message client (et 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.

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 comme entrée du modèle.

Champs
weight

float

Obligatoire. Pondération du prompt.

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

Les pondérations de tous les weighted_prompts de ce BidiGenerateMusicClientContent ne doivent pas être toutes nulles. 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

Requête textuelle.

En savoir plus sur les types

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