Live Music API - WebSockets API reference

Generowanie muzyki w czasie rzeczywistym za pomocą Lyrii wykorzystuje trwałe, dwukierunkowe połączenie strumieniowe o małym 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 nawiązaniu 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.

Zapoznaj się z 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 na potrzeby 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 formacie JSON, więc pole pojawi się na najwyższym poziomie wiadomości).

Wiadomości i wydarzenia

AudioChunk

Reprezentacja fragmentu audio.

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 użyte do wygenerowania tego fragmentu audio.
musicGenerationConfig

BidiGenerateMusicGenerationConfig

Konfiguracja generowania muzyki dla 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 do generowania 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ę generowanego 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. Włącza generowanie dźwięku na podstawie nasion. Jeśli nie zostanie ustawiony, żądanie użyje losowo wygenerowanego numeru początkowego.

guidance

float

Opcjonalnie. Określa, jak dokładnie model ma postępować zgodnie z promptami. Bardziej szczegółowe wytyczne są dokładniejsze, ale przejścia będą 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. Wyjście audio nie powinno zawierać perkusji.
onlyBassAndDrums

bool

Opcjonalnie. Wyjście audio powinno 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. Kliknij ODTWÓRZ, aby wznowić od bieżącej pozycji.
STOP Zatrzymuje generowanie muzyki i resetuje kontekst (prompty są zachowywane). Użyj przycisku PLAY, 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. Wysył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 modelu.

Format: models/{model}

BidiGenerateMusicSetupComplete

Ten typ nie ma pól.

Wysł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ć wszystkie 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.