Live Music API - WebSockets API reference

Pembuatan musik Lyria RealTime menggunakan koneksi streaming dua arah yang persisten dan berlatensi rendah menggunakan WebSockets. Di bagian ini, Anda akan menemukan detail tambahan terkait WebSockets API.

Sesi

Koneksi WebSocket membuat sesi untuk mempertahankan komunikasi real-time dengan model. Setelah klien memulai koneksi baru, sesi dapat bertukar pesan dengan server untuk:

  • Mengirim perintah dan kontrol untuk mengarahkan pembuatan musik.
  • Mengirim kontrol pemutaran musik.
  • Menerima potongan audio.

Koneksi WebSocket

Untuk memulai sesi, hubungkan ke endpoint websocket ini:

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

Konfigurasi sesi

Pesan awal setelah koneksi menetapkan model yang akan digunakan selama sesi.

Lihat contoh konfigurasi berikut. Perhatikan bahwa casing nama di SDK dapat bervariasi. Anda dapat mencari opsi konfigurasi Python SDK di sini.


{
  "model": string
}

Mengirim pesan

Untuk bertukar pesan melalui koneksi WebSocket, klien harus mengirim objek JSON melalui koneksi WebSocket yang terbuka. Objek JSON harus memiliki tepat satu kolom dari set objek berikut:


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

Pesan klien yang didukung

Lihat pesan klien yang didukung dalam tabel berikut:

Pesan Deskripsi
BidiGenerateMusicSetup Konfigurasi sesi yang hanya akan dikirim dalam pesan pertama
BidiGenerateMusicClientContent Perintah berbobot sebagai input model
BidiGenerateMusicGenerationConfig Konfigurasi untuk pembuatan musik
BidiGenerateMusicPlaybackControl Sinyal kontrol pemutaran untuk pembuatan model

Menerima pesan

Untuk menerima pesan dari server, dengarkan peristiwa 'message' WebSocket, lalu parsing hasilnya sesuai dengan definisi pesan server yang didukung.

Lihat referensi berikut:

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

Pesan server mencakup tepat satu kolom lain dari pesan BidiGenerateMusicServerMessage. (Gabungan messageType tidak dinyatakan dalam JSON sehingga kolom akan muncul di level teratas pesan.)

Pesan dan acara

AudioChunk

Representasi potongan audio.

Kolom

Kolom union content.

content hanya dapat berupa salah satu dari hal berikut:
data

bytes

Byte mentah potongan audio.
mimeType

string

Jenis MIME konten potongan audio, seperti "audio/wav".
sourceMetadata

SourceMetadata

Hanya output. Perintah dan konfigurasi yang digunakan untuk membuat potongan audio ini.

SourceMetadata

Metadata tentang sumber input yang digunakan untuk membuat potongan audio ini.

Kolom
clientContent

BidiGenerateMusicClientContent

Perintah berbobot untuk membuat potongan audio ini.
musicGenerationConfig

BidiGenerateMusicGenerationConfig

Konfigurasi pembuatan musik untuk membuat potongan audio ini.

BidiGenerateMusicClientContent

Input pengguna untuk memulai atau mengarahkan musik.

Kolom
weightedPrompts[]

WeightedPrompt

Wajib. Perintah berbobot sebagai input model.

BidiGenerateMusicClientMessage

Pesan yang dikirim oleh klien dalam panggilan BidiGenerateMusic.

Kolom

Kolom union messageType.

messageType hanya dapat berupa salah satu dari hal berikut:
setup

BidiGenerateMusicSetup

Opsional. Konfigurasi sesi hanya dikirim dalam pesan klien pertama.
clientContent

BidiGenerateMusicClientContent

Opsional. Perintah berbobot dan konfigurasi pembuatan musik sebagai input pembuatan musik.

musicGenerationConfig

BidiGenerateMusicGenerationConfig

Opsional. Konfigurasi untuk pembuatan musik.
playbackControl

BidiGenerateMusicPlaybackControl

Opsional. Sinyal kontrol pemutaran untuk pembuatan musik.

BidiGenerateMusicFilteredPrompt

Perintah yang difilter dengan alasan.

Kolom
filteredReason

string

Hanya output. Alasan perintah difilter.
Kolom union prompt. Perintah yang difilter. prompt hanya dapat berupa salah satu dari berikut ini:
text

string

Opsional. Perintah teks.

BidiGenerateMusicGenerationConfig

Konfigurasi untuk pembuatan musik.

Kolom
temperature

float

Opsional. Mengontrol varians dalam pembuatan audio.

Nilai yang lebih tinggi menghasilkan varians yang lebih tinggi. Rentangnya adalah [0.0, 3.0]. Nilai defaultnya adalah 1.1.
topK

int32

Opsional. Mengontrol cara model memilih token untuk output.

Mengambil sampel token topK dengan probabilitas tertinggi. Rentangnya adalah [1, 1000]. Defaultnya adalah 40.

seed

int32

Opsional. Menyemai pembuatan audio. Jika tidak disetel, permintaan akan menggunakan seed yang dibuat secara acak.

guidance

float

Opsional. Mengontrol seberapa dekat model mengikuti perintah. Panduan yang lebih tinggi akan mengikuti lebih cermat, tetapi akan membuat transisi lebih tiba-tiba. Rentangnya adalah [0.0, 6.0]. Defaultnya adalah 4.0.

bpm

int32

Opsional. Detak per menit. Rentangnya adalah [60, 200].
density

float

Opsional. Kepadatan suara. Rentangnya adalah [0.0, 1.0].
brightness

float

Opsional. Nilai yang lebih tinggi menghasilkan audio yang lebih cerah. Rentangnya adalah [0.0, 1.0].
scale

Scale

Opsional. Skala musik yang dihasilkan.
muteBass

bool

Opsional. Output audio tidak boleh berisi bass.
muteDrums

bool

Opsional. Output audio tidak boleh berisi drum.
onlyBassAndDrums

bool

Opsional. Output audio hanya boleh berisi bass dan drum.
musicGenerationMode

MusicGenerationMode

Opsional. Mode pembuatan musik. Default-nya adalah KUALITAS.

MusicGenerationMode

Enum
MUSIC_GENERATION_MODE_UNSPECIFIED Nilai ini tidak digunakan.
QUALITY Mode ini mengarahkan perintah teks ke wilayah ruang laten dengan musik berkualitas lebih tinggi.
DIVERSITY Mode ini mengarahkan perintah teks ke wilayah ruang laten dengan keragaman musik yang lebih besar.
VOCALIZATION Mode ini mengarahkan perintah teks ke area ruang laten yang lebih mungkin menghasilkan musik vokal.

Skala

Skala musik yang dihasilkan.

Enum
SCALE_UNSPECIFIED Nilai default. Nilai ini tidak digunakan.
C_MAJOR_A_MINOR C mayor atau A minor
D_FLAT_MAJOR_B_FLAT_MINOR D flat mayor atau B flat minor
D_MAJOR_B_MINOR D mayor atau B minor
E_FLAT_MAJOR_C_MINOR E flat mayor atau C minor
E_MAJOR_D_FLAT_MINOR E mayor atau D flat minor
F_MAJOR_D_MINOR F mayor atau D minor
G_FLAT_MAJOR_E_FLAT_MINOR G flat mayor atau E flat minor
G_MAJOR_E_MINOR G mayor atau E minor
A_FLAT_MAJOR_F_MINOR A mayor datar atau F minor
A_MAJOR_G_FLAT_MINOR A mayor atau G flat minor
B_FLAT_MAJOR_G_MINOR B flat mayor atau G minor
B_MAJOR_A_FLAT_MINOR B mayor atau A flat minor

BidiGenerateMusicPlaybackControl

Kontrol pemutaran untuk pembuatan musik.

Enum
PLAYBACK_CONTROL_UNSPECIFIED Nilai ini tidak digunakan.
PLAY Mulai buat musik.
PAUSE Menahan pembuatan musik. Gunakan PLAY untuk melanjutkan dari posisi saat ini.
STOP Hentikan pembuatan musik dan reset konteks (perintah tetap ada). Gunakan PLAY untuk memulai ulang pembuatan musik.
RESET_CONTEXT Mereset konteks (perintah tetap ada) tanpa menghentikan pembuatan musik.

BidiGenerateMusicServerContent

Update server inkremental yang dihasilkan oleh model sebagai respons terhadap pesan klien.

Konten dibuat secepat mungkin, dan tidak secara real time. Klien dapat memilih untuk melakukan buffering dan memutarnya secara real time.

Kolom
audioChunks[]

AudioChunk

Hanya output. Potongan audio yang dihasilkan model.

BidiGenerateMusicServerMessage

Pesan respons untuk panggilan BidiGenerateMusic.

Kolom
Kolom union messageType. Jenis pesan. messageType hanya dapat berupa salah satu dari berikut:
setupComplete

BidiGenerateMusicSetupComplete

Hanya output. Dikirim sebagai respons terhadap pesan BidiGenerateMusicSetup dari klien saat penyiapan selesai.

serverContent

BidiGenerateMusicServerContent

Hanya output. Konten yang dihasilkan oleh model sebagai respons terhadap pesan klien.
filteredPrompt

BidiGenerateMusicFilteredPrompt

Hanya output. Perintah yang difilter dengan alasan.
warning

string

Hanya output. Pesan peringatan dari server. Peringatan tidak akan menghentikan streaming.

BidiGenerateMusicSetup

Pesan yang akan dikirim dalam BidiGenerateMusicClientMessage pertama (dan hanya dalam BidiGenerateMusicClientMessage pertama).

Klien harus menunggu pesan BidiGenerateMusicSetupComplete sebelum mengirim pesan tambahan.

Kolom
model

string

Wajib. Nama resource model. Ini berfungsi sebagai ID yang akan digunakan model.

Format: models/{model}

BidiGenerateMusicSetupComplete

Jenis ini tidak memiliki kolom.

Dikirim sebagai respons terhadap pesan BidiGenerateMusicSetup dari klien.

WeightedPrompt

Perintah berbobot sebagai input model.

Kolom
weight

float

Wajib. Bobot perintah.

Bobot digunakan untuk mengontrol kepentingan relatif perintah. Bobot yang lebih tinggi lebih penting daripada bobot yang lebih rendah.

Bobot semua weighted_prompts dalam BidiGenerateMusicClientContent ini tidak boleh semuanya 0. Bobot semua weighted_prompts dalam pesan BidiGenerateMusicClientContent ini akan dinormalisasi.

Kolom union prompt.

prompt hanya dapat berupa salah satu dari hal berikut:
text

string

Perintah teks.

Informasi selengkapnya tentang jenis

Untuk mengetahui informasi selengkapnya tentang jenis yang digunakan oleh API, lihat Python SDK.