Live Music API - WebSockets API reference

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

Sesje

Połączenie WebSocket tworzy sesję, która umożliwia 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 elementy sterujące, aby kierować generowaniem muzyki;
  • wysyłać elementy sterujące odtwarzaniem muzyki;
  • Odbieranie fragmentów audio.

Połączenie WebSocket

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

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

Konfiguracja sesji

Pierwsza wiadomość po połączeniu określa 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 w Pythonie 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 pole z tego zestawu:


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

Obsługiwane wiadomości klienta

Obsługiwane wiadomości od klientów znajdziesz w tabeli poniżej:

Wiadomość Opis
BidiGenerateMusicSetup Konfiguracja sesji, która ma być wysyłana tylko w pierwszej wiadomości
BidiGenerateMusicClientContent Ważone prompty jako dane wejściowe modelu
BidiGenerateMusicGenerationConfig Konfiguracja generowania muzyki
BidiGenerateMusicPlaybackControl Sygnały sterujące odtwarzaniem dla generowania modelu

Odbieranie wiadomości

Aby odbierać wiadomości z serwera, nasłuchuj zdarzenia „message” WebSocket, a następnie analizuj 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 JSON, więc pole pojawi się na najwyższym poziomie wiadomości).

Wiadomości i wydarzenia

AudioChunk

Prezentacja fragmentu dźwięku.

Pola

Pole zbiorcze content.

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

bytes

Surowe 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 dźwięku.

SourceMetadata

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

Pola
clientContent

BidiGenerateMusicClientContent

Ważone prompty do wygenerowania tego fragmentu audio.
musicGenerationConfig

BidiGenerateMusicGenerationConfig

Konfiguracja generowania muzyki na potrzeby tego fragmentu audio.

BidiGenerateMusicClientContent

Dane wejściowe użytkownika do rozpoczęcia odtwarzania muzyki lub sterowania nią.

Pola
weightedPrompts[]

WeightedPrompt

Wymagane. ważone prompty 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 wysyłana tylko w pierwszej wiadomości klienta.
clientContent

BidiGenerateMusicClientContent

Opcjonalnie. Ważone prompty i konfiguracje generowania muzyki jako dane wejściowe generowania muzyki.

musicGenerationConfig

BidiGenerateMusicGenerationConfig

Opcjonalnie. Konfiguracja generowania muzyki.
playbackControl

BidiGenerateMusicPlaybackControl

Opcjonalnie. Sygnał sterowania odtwarzaniem generowanej muzyki.

BidiGenerateMusicFilteredPrompt

Odfiltrowany prompt z podaniem przyczyny.

Pola
filteredReason

string

Tylko dane wyjściowe. Powód odfiltrowania promptu.
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. Określa wariancję generowania dźwięku.

Wyższe wartości powodują większą wariancję. Zakres to [0,0, 3,0]. Wartość domyślna to 1,1.
topK

int32

Opcjonalnie. Określa sposób, w jaki 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. Inicjuje generowanie dźwięku. Jeśli nie zostanie ustawiony, żądanie użyje losowo wygenerowanego wartości początkowej.

guidance

float

Opcjonalnie. Określa, jak ściśle model ma się trzymać promptów. Wyższe wartości wskazówek zapewniają dokładniejsze śledzenie, ale sprawiają, że przejścia są bardziej nagłe. Zakres to [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. Wyjście audio nie powinno zawierać basów.
muteDrums

bool

Opcjonalnie. Dane wyjściowe audio nie powinny zawierać perkusji.
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 o większej różnorodności muzyki.
VOCALIZATION Ten tryb kieruje prompty tekstowe do regionów przestrzeni ukrytej, w których istnieje większe prawdopodobieństwo wygenerowania muzyki wokalnej.

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

Sterowanie odtwarzaniem wygenerowanej muzyki.

Wartości w polu enum
PLAYBACK_CONTROL_UNSPECIFIED Ta wartość nie jest używana.
PLAY Rozpocznij generowanie muzyki.
PAUSE Wstrzymaj generowanie muzyki. Użyj przycisku ODTWÓRZ, aby wznowić odtwarzanie od bieżącej pozycji.
STOP Zatrzymuje generowanie muzyki i resetuje kontekst (prompty są zachowywane). Użyj przycisku ODTWÓRZ, aby ponownie uruchomić generowanie muzyki.
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 tak szybko, jak to możliwe, a nie w czasie rzeczywistym. Klienci mogą buforować i odtwarzać je w czasie rzeczywistym.

Pola
audioChunks[]

AudioChunk

Tylko dane wyjściowe. fragmenty dźwięku wygenerowane przez model.

BidiGenerateMusicServerMessage

Wiadomość z 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. Wysłana w odpowiedzi na wiadomość BidiGenerateMusicSetup od klienta po zakończeniu konfiguracji.

serverContent

BidiGenerateMusicServerContent

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

BidiGenerateMusicFilteredPrompt

Tylko dane wyjściowe. Odfiltrowany prompt z podaniem przyczyny.
warning

string

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

BidiGenerateMusicSetup

Wiadomość do wysłania w pierwszym (i tylko w pierwszym)BidiGenerateMusicClientMessage.

Przed wysłaniem kolejnych wiadomości klient powinien poczekać na wiadomość BidiGenerateMusicSetupComplete.

Pola
model

string

Wymagane. Nazwa zasobu modelu. Służy on jako identyfikator, którego model może używać.

Format: models/{model}

BidiGenerateMusicSetupComplete

Ten typ nie ma pól.

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

WeightedPrompt

Ważony prompt jako dane wejściowe modelu.

Pola
weight

float

Wymagane. Waga promptu.

Waga służy do określania względnego znaczenia promptu. Większe wagi są ważniejsze niż mniejsze.

Wagi wszystkich elementów weighted_prompts w tym elemencie 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 Pythona.