Live Music API - WebSockets API reference

Generowanie muzyki za pomocą Lyria RealTime wykorzystuje trwałe, dwukierunkowe połączenie strumieniowe o niskim opóźnieniu, które korzysta z WebSockets. W tej sekcji znajdziesz dodatkowe informacje o interfejsie WebSockets API.

Sesje

Połączenie WebSocket ustanawia sesję, aby utrzymać komunikację z modelem w czasie rzeczywistym. Po zainicjowaniu nowego połączenia przez klienta sesja może wymieniać wiadomości z serwerem w celu:

  • wysyłać prompty i sterować generowaniem muzyki;
  • wysyłać elementy sterujące odtwarzaniem muzyki;
  • Odbieranie fragmentów dźwięku.

Połączenie WebSocket

Aby rozpocząć sesję, połącz się z tym punktem końcowym WebSocket:

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

Konfiguracja sesji

Pierwsza wiadomość po połączeniu ustawia model, który będzie używany podczas sesji.

Zobacz przykładową konfigurację poniżej. Pamiętaj, że wielkość liter w nazwach w pakietach SDK może się różnić. Opcje konfiguracji pakietu SDK Pythona znajdziesz tutaj.


{
  "model": string
}

Wysyłanie wiadomości

Aby wymieniać wiadomości przez połączenie WebSocket, klient musi wysłać obiekt JSON przez otwarte połączenie WebSocket. Obiekt JSON musi zawierać dokładnie jedno z pól z tego zestawu obiektów:


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

Obsługiwane wiadomości klienta

W tabeli poniżej znajdziesz obsługiwane komunikaty klienta:

Wiadomość Opis
BidiGenerateMusicSetup Konfiguracja sesji do wysłania tylko w pierwszej wiadomości
BidiGenerateMusicClientContent Prompty z wagami jako dane wejściowe modelu
BidiGenerateMusicGenerationConfig Konfiguracja generowania muzyki
BidiGenerateMusicPlaybackControl Sygnały sterujące odtwarzaniem na potrzeby generowania modelu

Odbieranie wiadomości

Aby otrzymywać wiadomości z serwera, nasłuchuj zdarzenia „message” protokołu WebSocket, a następnie przeanalizuj wynik zgodnie z definicją obsługiwanych wiadomości serwera.

Zobacz:

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

Wiadomości serwera zawierają dokładnie jedno z pozostałych pól z wiadomości BidiGenerateMusicServerMessage. (Unia messageType nie jest wyrażona w formacie JSON, więc pole pojawi się na najwyższym poziomie wiadomości).

Wiadomości i zdarzenia

AudioChunk

Reprezentacja fragmentu audio.

Pola

Pole zbiorcze content.

Pole content może mieć tylko jedną z tych wartości:
data

bytes

Nieprzetworzone bajty fragmentu audio.
mimeType

string

Typ MIME treści fragmentu audio, np. „audio/wav”.
sourceMetadata

SourceMetadata

Tylko dane wyjściowe. Prompty i konfiguracja użyte do wygenerowania tego fragmentu audio.

SourceMetadata

Metadane dotyczące źródła danych wejściowych użytego do wygenerowania tego fragmentu audio.

Pola
clientContent

BidiGenerateMusicClientContent

Prompty z wagami do wygenerowania tego fragmentu audio.
musicGenerationConfig

BidiGenerateMusicGenerationConfig

Konfiguracja generowania muzyki na potrzeby wygenerowania tego fragmentu audio.

BidiGenerateMusicClientContent

Dane wejściowe użytkownika, które pozwalają rozpocząć lub sterować muzyką.

Pola
weightedPrompts[]

WeightedPrompt

Wymagane. Prompty z wagami jako dane wejściowe modelu.

BidiGenerateMusicClientMessage

Wiadomości wysyłane przez klienta w wywołaniu BidiGenerateMusic.

Pola

Pole zbiorcze messageType.

Pole messageType może mieć tylko jedną z tych wartości:
setup

BidiGenerateMusicSetup

Opcjonalnie: Konfiguracja sesji wysłana w pierwszej i tylko pierwszej wiadomości klienta.
clientContent

BidiGenerateMusicClientContent

Opcjonalnie: Prompty z wagami i konfiguracje generowania muzyki jako dane wejściowe do generowania muzyki.
musicGenerationConfig

BidiGenerateMusicGenerationConfig

Opcjonalnie: Konfiguracja generowania muzyki.
playbackControl

BidiGenerateMusicPlaybackControl

Opcjonalnie: Sygnał sterowania odtwarzaniem na potrzeby generowania muzyki.

BidiGenerateMusicFilteredPrompt

Odfiltrowany prompt z powodem.

Pola
filteredReason

string

Tylko dane wyjściowe. Powód odfiltrowania prompta.
Pole zbiorcze prompt. Prompt, który został odfiltrowany. prompt może mieć tylko jedną z tych wartości:
text

string

Opcjonalnie: Prompt tekstowy.

BidiGenerateMusicGenerationConfig

Konfiguracja generowania muzyki.

Pola
temperature

float

Opcjonalnie: Kontroluje wariancję w generowaniu dźwięku.

Wyższe wartości dają większą wariancję. Zakres to [0.0, 3.0]. Wartość domyślna to 1.1.
topK

int32

Opcjonalnie: Określa, jak model wybiera tokeny w celu wygenerowania odpowiedzi.

Próbkuje tokeny topK o najwyższym prawdopodobieństwie. Zakres to [1, 1000]. Wartość domyślna to 40.
seed

int32

Opcjonalnie: Generowanie dźwięku na podstawie promptu. Jeśli nie zostanie ustawiony, żądanie użyje losowo wygenerowanego ziarna.
guidance

float

Opcjonalnie: Określa, jak dokładnie model ma postępować zgodnie z promptami. Bardziej szczegółowe wytyczne będą dokładniej przestrzegane, ale przejścia będą bardziej gwałtowne. Zakres: [0.0, 6.0]. Wartość domyślna to 4.0.
bpm

int32

Opcjonalnie: Uderzenia na minutę. Zakres to [60, 200].
density

float

Opcjonalnie: gęstość dźwięków, Zakres to [0,0; 1,0].
brightness

float

Opcjonalnie: Wyższa wartość daje jaśniejszy dźwięk. Zakres to [0.0, 1.0].
scale

Scale

Opcjonalnie: Skala wygenerowanej muzyki.
muteBass

bool

Opcjonalnie: Dane wyjściowe audio nie powinny zawierać basów.
muteDrums

bool

Opcjonalnie: Dane wyjściowe audio nie powinny zawierać bębnów.
onlyBassAndDrums

bool

Opcjonalnie: Dane wyjściowe audio powinny zawierać tylko bas i perkusję.
musicGenerationMode

MusicGenerationMode

Opcjonalnie: Tryb generowania muzyki. Wartość domyślna to QUALITY.

MusicGenerationMode

Wartości w polu enum
MUSIC_GENERATION_MODE_UNSPECIFIED Ta wartość nie jest używana.
QUALITY Ten tryb kieruje prompty tekstowe do regionów przestrzeni ukrytej z muzyką o wyższej jakości.
DIVERSITY Ten tryb kieruje prompty tekstowe do regionów przestrzeni ukrytej z większą różnorodnością muzyki.
VOCALIZATION Ten tryb kieruje prompty tekstowe do regionów przestrzeni ukrytej, które z większym prawdopodobieństwem wygenerują muzykę wokalną.

Skaluj

Skala wygenerowanej muzyki.

Wartości w polu enum
SCALE_UNSPECIFIED Wartość domyślna. Ta wartość nie jest używana.
C_MAJOR_A_MINOR C-dur lub a-moll
D_FLAT_MAJOR_B_FLAT_MINOR Des-dur lub b-moll
D_MAJOR_B_MINOR D-dur lub h-moll
E_FLAT_MAJOR_C_MINOR Es-dur lub c-moll
E_MAJOR_D_FLAT_MINOR E-dur lub des-moll
F_MAJOR_D_MINOR F-dur lub d-moll
G_FLAT_MAJOR_E_FLAT_MINOR Ges-dur lub es-moll
G_MAJOR_E_MINOR G-dur lub e-moll
A_FLAT_MAJOR_F_MINOR As-dur lub f-moll
A_MAJOR_G_FLAT_MINOR A-dur lub ges-moll
B_FLAT_MAJOR_G_MINOR B-dur lub g-moll
B_MAJOR_A_FLAT_MINOR H-dur lub as-moll

BidiGenerateMusicPlaybackControl

Elementy sterujące odtwarzaniem generowania muzyki.

Wartości w polu enum
PLAYBACK_CONTROL_UNSPECIFIED Ta wartość nie jest używana.
PLAY Zacznij generować muzykę.
PAUSE Wstrzymaj generowanie muzyki. Użyj przycisku ODTWÓRZ, aby wznowić od bieżącej pozycji.
STOP Zatrzymaj generowanie muzyki i zresetuj kontekst (prompty zostaną zachowane). Aby ponownie rozpocząć generowanie muzyki, użyj przycisku ODTWÓRZ.
RESET_CONTEXT Zresetuj kontekst (prompty zostaną zachowane) bez zatrzymywania generowania muzyki.

BidiGenerateMusicServerContent

Przyrostowa aktualizacja serwera wygenerowana przez model w odpowiedzi na wiadomości klienta.

Treści są generowane jak najszybciej, ale nie w czasie rzeczywistym. Klienci mogą zdecydować się na buforowanie i odtwarzanie w czasie rzeczywistym.

Pola
audioChunks[]

AudioChunk

Tylko dane wyjściowe. Fragmenty audio wygenerowane przez model.

BidiGenerateMusicServerMessage

Komunikat odpowiedzi na wywołanie BidiGenerateMusic.

Pola
Pole zbiorcze messageType. Typ wiadomości. messageType może mieć tylko jedną z tych wartości:
setupComplete

BidiGenerateMusicSetupComplete

Tylko dane wyjściowe. Wysyłany w odpowiedzi na wiadomość BidiGenerateMusicSetup od klienta po zakończeniu konfiguracji.
serverContent

BidiGenerateMusicServerContent

Tylko dane wyjściowe. Treści generowane przez model w odpowiedzi na wiadomości klienta.
filteredPrompt

BidiGenerateMusicFilteredPrompt

Tylko dane wyjściowe. Odfiltrowany prompt z powodem.
warning

string

Tylko dane wyjściowe. Ostrzeżenie z serwera. Ostrzeżenia nie spowodują zakończenia transmisji.

BidiGenerateMusicSetup

Wiadomość, która zostanie wysłana w pierwszym (i tylko w pierwszym) BidiGenerateMusicClientMessage.

Klient powinien poczekać na wiadomość BidiGenerateMusicSetupComplete, zanim wyśle kolejne wiadomości.

Pola
model

string

Wymagane. Nazwa zasobu modelu. Służy on jako identyfikator modelu.

Format: models/{model}

BidiGenerateMusicSetupComplete

Ten typ nie ma pól.

Wysyłane w odpowiedzi na wiadomość BidiGenerateMusicSetup od klienta.

WeightedPrompt

Prompt z wagą jako dane wejściowe modelu.

Pola
weight

float

Wymagane. Waga prompta.

Waga służy do kontrolowania względnego znaczenia prompta. Większe wagi są ważniejsze niż mniejsze.

Wagi wszystkich elementów weighted_prompts w tym BidiGenerateMusicClientContent nie mogą być równe 0. Wagi wszystkich elementów weighted_prompts w tej wiadomości BidiGenerateMusicClientContent zostaną znormalizowane.

Pole zbiorcze prompt.

Pole prompt może mieć tylko jedną z tych wartości:
text

string

Prompt tekstowy.

Więcej informacji o typach

Więcej informacji o typach używanych przez interfejs API znajdziesz w pakiecie SDK dla Pythona.