Live Music API - WebSockets API reference

Generowanie muzyki w czasie rzeczywistym w Lyrii 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 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 w pakietach SDK wielkość liter w nazwach 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 z pól z tego zestawu obiektów:


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

Obsługiwane wiadomości od klientów

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

Przedstawienie fragmentu dźwięku.

Pola

Pole unii content.

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 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 dla tego fragmentu audio.

BidiGenerateMusicClientContent

Użytkownik musi wykonać jakieś działanie, aby rozpocząć odtwarzanie muzyki lub nią sterować.

Pola
weightedPrompts[]

WeightedPrompt

Wymagany. Ważone prompty jako dane wejściowe modelu.

BidiGenerateMusicClientMessage

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

Pola

Pole unii messageType.

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ł sterujący odtwarzaniem generowanej muzyki.

BidiGenerateMusicFilteredPrompt

Odfiltrowany prompt z podaniem przyczyny.

Pola
filteredReason

string

Tylko dane wyjściowe. Powód odfiltrowania promptu.
Pole unii 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ększe odchylenie. 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. Generowanie dźwięku na podstawie nasion. Jeśli nie zostanie ustawiony, żądanie użyje losowo wygenerowanego ziarna.

guidance

float

Opcjonalnie. Określa, jak ściśle model ma się stosować do promptów. Bardziej szczegółowe wytyczne zapewniają dokładniejsze odzwierciedlenie treści prompta, 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. 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 obszaró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 częściej generowana jest muzyka z wokalem.

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 Zatrzymanie generowania muzyki i zresetowanie kontekstu (prompty zostaną zachowane). Użyj przycisku PLAY, aby ponownie rozpocząć 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 unii 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) kroku:BidiGenerateMusicClientMessage

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

Pola
model

string

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

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

Wymagany. 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 unii prompt.

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.