Live Music API - WebSockets API reference

تولید موسیقی Lyria RealTime از یک اتصال استریمینگ پایدار، دو طرفه و با تأخیر کم با استفاده از WebSockets استفاده می‌کند. در این بخش، جزئیات بیشتری در مورد API WebSockets خواهید یافت.

جلسات

یک اتصال WebSocket یک جلسه (session) برای حفظ ارتباط بلادرنگ با مدل برقرار می‌کند. پس از اینکه کلاینت یک اتصال جدید را آغاز می‌کند، جلسه می‌تواند پیام‌هایی را با سرور رد و بدل کند تا:

  • برای هدایت تولید موسیقی، دستورات و کنترل‌هایی ارسال کنید.
  • کنترل‌های پخش موسیقی را ارسال کنید.
  • دریافت تکه‌های صوتی.

اتصال وب‌سوکت

برای شروع یک جلسه، به این نقطه پایانی وب سوکت متصل شوید:

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

پیکربندی جلسه

پیام اولیه پس از اتصال، مدل مورد استفاده در طول جلسه را تعیین می‌کند.

به مثال پیکربندی زیر توجه کنید. توجه داشته باشید که نحوه‌ی نام‌گذاری در SDKها ممکن است متفاوت باشد. می‌توانید گزینه‌های پیکربندی SDK پایتون را اینجا جستجو کنید.


{
  "model": string
}

ارسال پیام

برای تبادل پیام از طریق اتصال WebSocket، کلاینت باید یک شیء JSON را از طریق یک اتصال WebSocket باز ارسال کند. شیء JSON باید دقیقاً یکی از فیلدهای مجموعه شیء زیر را داشته باشد:


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

پیام‌های کلاینت پشتیبانی‌شده

پیام‌های کلاینت پشتیبانی‌شده را در جدول زیر مشاهده کنید:

پیام توضیحات
BidiGenerateMusicSetup پیکربندی جلسه فقط در اولین پیام ارسال شود
BidiGenerateMusicClientContent اعلان‌های وزن‌دار به عنوان ورودی مدل
BidiGenerateMusicGenerationConfig پیکربندی برای تولید موسیقی
BidiGenerateMusicPlaybackControl سیگنال‌های کنترل پخش برای تولید مدل

دریافت پیام‌ها

برای دریافت پیام‌ها از سرور، به رویداد 'message' در WebSocket گوش دهید و سپس نتیجه را طبق تعریف پیام‌های پشتیبانی‌شده‌ی سرور تجزیه کنید.

موارد زیر را ببینید:

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

پیام‌های سرور دقیقاً شامل یکی از فیلدهای دیگر پیام BidiGenerateMusicServerMessage هستند. (اتحادیه messageType در JSON بیان نشده است، بنابراین این فیلد در سطح بالای پیام ظاهر می‌شود.)

پیام‌ها و رویدادها

آدیوچانک

نمایش یک قطعه صوتی.

فیلدها

content فیلد اتحادیه.

content می‌تواند فقط یکی از موارد زیر باشد:

data

bytes

بایت‌های خام از قطعه صوتی.

mimeType

string

نوع MIME محتوای قطعه صوتی، مانند "audio/wav".

sourceMetadata

SourceMetadata

فقط خروجی. اعلان‌ها و پیکربندی مورد استفاده برای تولید این قطعه صوتی.

منبعفراداده

فراداده‌ای درباره منبع ورودی مورد استفاده برای تولید این قطعه صوتی.

فیلدها
clientContent

BidiGenerateMusicClientContent

دستورات وزن‌دار برای تولید این قطعه صوتی.

musicGenerationConfig

BidiGenerateMusicGenerationConfig

پیکربندی تولید موسیقی برای تولید این قطعه صوتی.

BidiGenerateMusicClientContent

ورودی کاربر برای شروع یا هدایت موسیقی.

فیلدها
weightedPrompts[]

WeightedPrompt

الزامی. اعلان‌های وزن‌دار به عنوان ورودی مدل.

BidiGenerateMusicClientMessage

پیام‌های ارسال‌شده توسط کلاینت در فراخوانی BidiGenerateMusic.

فیلدها

فیلد اتحادیه messageType .

messageType فقط می‌تواند یکی از موارد زیر باشد:

setup

BidiGenerateMusicSetup

اختیاری. پیکربندی جلسه فقط در اولین پیام کلاینت ارسال می‌شود.

clientContent

BidiGenerateMusicClientContent

اختیاری. اعلان‌های وزن‌دار و پیکربندی‌های تولید موسیقی به عنوان ورودی تولید موسیقی.

musicGenerationConfig

BidiGenerateMusicGenerationConfig

اختیاری. پیکربندی برای تولید موسیقی.

playbackControl

BidiGenerateMusicPlaybackControl

اختیاری. سیگنال کنترل پخش برای تولید موسیقی.

BidiGenerateMusicFilteredPrompt

درخواست فیلتر شده با دلیل.

فیلدها
filteredReason

string

فقط خروجی. دلیل فیلتر شدن اعلان.

فیلد Union prompt . اعلانی که فیلتر شده است. prompt می‌تواند فقط یکی از موارد زیر باشد:
text

string

اختیاری. متن درخواست.

BidiGenerateMusicGenerationConfig

پیکربندی برای تولید موسیقی.

فیلدها
temperature

float

اختیاری. واریانس تولید صدا را کنترل می‌کند.

مقادیر بالاتر واریانس بالاتری ایجاد می‌کنند. محدوده [0.0، 3.0] است. پیش‌فرض 1.1 است.

topK

int32

اختیاری. نحوه انتخاب توکن‌ها برای خروجی توسط مدل را کنترل می‌کند.

از بین K توکن برتر با بالاترین احتمال، نمونه‌برداری می‌کند. محدوده [۱، ۱۰۰۰] است. مقدار پیش‌فرض ۴۰ است.

seed

int32

اختیاری. تولید صدا را سید می‌کند. اگر تنظیم نشود، درخواست از یک سید تولید شده تصادفی استفاده می‌کند.

guidance

float

اختیاری. کنترل می‌کند که مدل چقدر از دستورالعمل‌ها پیروی کند. راهنمایی بالاتر، دستورالعمل‌ها را دقیق‌تر دنبال می‌کند، اما انتقال‌ها را ناگهانی‌تر می‌کند. محدوده [0.0، 6.0] است. پیش‌فرض 4.0 است.

bpm

int32

اختیاری. ضربان در دقیقه. محدوده [60، 200] است.

density

float

اختیاری. تراکم صداها. محدوده [0.0، 1.0] است.

brightness

float

اختیاری. مقدار بالاتر صدای روشن‌تری تولید می‌کند. محدوده [0.0، 1.0] است.

scale

Scale

اختیاری. مقیاس موسیقی تولید شده.

muteBass

bool

اختیاری. خروجی صدا نباید حاوی بیس باشد.

muteDrums

bool

اختیاری. خروجی صدا نباید حاوی درام باشد.

onlyBassAndDrums

bool

اختیاری. خروجی صدا فقط باید شامل بیس و درام باشد.

musicGenerationMode

MusicGenerationMode

اختیاری. حالت تولید موسیقی. پیش‌فرض QUALITY است.

حالت تولید موسیقی

انوم‌ها
MUSIC_GENERATION_MODE_UNSPECIFIED این مقدار بلااستفاده است.
QUALITY این حالت، پیام‌های متنی را به مناطقی از فضای پنهان با موسیقی با کیفیت بالاتر هدایت می‌کند.
DIVERSITY این حالت، متن‌های راهنما را به مناطقی از فضای پنهان با تنوع موسیقی بیشتر هدایت می‌کند.
VOCALIZATION این حالت، پیام‌های متنی را به مناطقی از فضای پنهان هدایت می‌کند که احتمال تولید موسیقی صوتی در آنها بیشتر است.

مقیاس

مقیاس موسیقی تولید شده.

انوم‌ها
SCALE_UNSPECIFIED مقدار پیش‌فرض. این مقدار استفاده نشده است.
C_MAJOR_A_MINOR دو ماژور یا لا مینور
D_FLAT_MAJOR_B_FLAT_MINOR ر بمل ماژور یا سی بمل مینور
D_MAJOR_B_MINOR رِ ماژور یا سی مینور
E_FLAT_MAJOR_C_MINOR می بمل ماژور یا دو مینور
E_MAJOR_D_FLAT_MINOR می ماژور یا ر بمل مینور
F_MAJOR_D_MINOR فا ماژور یا ر مینور
G_FLAT_MAJOR_E_FLAT_MINOR سل بمل ماژور یا می بمل مینور
G_MAJOR_E_MINOR سل ماژور یا می مینور
A_FLAT_MAJOR_F_MINOR یک ماژور بمل یا فا مینور
A_MAJOR_G_FLAT_MINOR یک ماژور یا سل بمل مینور
B_FLAT_MAJOR_G_MINOR سی بمل ماژور یا سل مینور
B_MAJOR_A_FLAT_MINOR سی ماژور یا لا بمل مینور

BidiGenerateMusicPlaybackControl

کنترل پخش برای تولید موسیقی.

انوم‌ها
PLAYBACK_CONTROL_UNSPECIFIED این مقدار بلااستفاده است.
PLAY شروع به تولید موسیقی کنید.
PAUSE تولید موسیقی را متوقف کنید. از PLAY برای ادامه از موقعیت فعلی استفاده کنید.
STOP تولید موسیقی را متوقف کنید و زمینه را مجدداً تنظیم کنید (دستورالعمل‌ها حفظ می‌شوند). از PLAY برای شروع مجدد تولید موسیقی استفاده کنید.
RESET_CONTEXT بدون توقف تولید موسیقی، زمینه (دستورالعمل‌ها حفظ می‌شوند) را مجدداً تنظیم کنید.

BidiGenerateMusicServerContent

به‌روزرسانی افزایشی سرور که توسط مدل در پاسخ به پیام‌های کلاینت ایجاد می‌شود.

محتوا در سریع‌ترین زمان ممکن تولید می‌شود و نه به صورت بلادرنگ. مشتریان می‌توانند آن را ذخیره کرده و به صورت بلادرنگ پخش کنند.

فیلدها
audioChunks[]

AudioChunk

فقط خروجی. تکه‌های صوتی که مدل تولید کرده است.

BidiGenerateMusicServerMessage

پیام پاسخ برای فراخوانی BidiGenerateMusic.

فیلدها
فیلد union messageType . نوع پیام. messageType فقط می‌تواند یکی از موارد زیر باشد:
setupComplete

BidiGenerateMusicSetupComplete

فقط خروجی. در پاسخ به پیام BidiGenerateMusicSetup از کلاینت، پس از اتمام راه‌اندازی، ارسال می‌شود.

serverContent

BidiGenerateMusicServerContent

فقط خروجی. محتوایی که توسط مدل در پاسخ به پیام‌های کلاینت تولید می‌شود.

filteredPrompt

BidiGenerateMusicFilteredPrompt

فقط خروجی. دستور فیلتر شده با دلیل.

warning

string

فقط خروجی. پیام هشدار از سرور. هشدارها جریان را خاتمه نمی‌دهند.

تنظیمات موسیقی BidiGenerate

پیامی که قرار است در اولین (و فقط در اولین) BidiGenerateMusicClientMessage ارسال شود.

کلاینت‌ها باید قبل از ارسال هرگونه پیام اضافی، منتظر پیام BidiGenerateMusicSetupComplete باشند.

فیلدها
model

string

الزامی. نام منبع مدل. این به عنوان شناسه‌ای برای استفاده مدل عمل می‌کند.

قالب: models/{model}

BidiGenerateMusicSetupComplete

این نوع هیچ فیلدی ندارد.

در پاسخ به پیام BidiGenerateMusicSetup از کلاینت ارسال شده است.

WeightedPrompt

اعلان وزن‌دار به عنوان ورودی مدل.

فیلدها
weight

float

الزامی. وزن درخواست.

وزن برای کنترل اهمیت نسبی سوال استفاده می‌شود. وزن‌های بالاتر از وزن‌های پایین‌تر مهم‌تر هستند.

وزن همه weighted_prompts ها در این BidiGenerateMusicClientContent نباید همگی 0 باشد. وزن همه weighted_prompts ها در این پیام BidiGenerateMusicClientContent نرمال سازی خواهد شد.

prompt فیلد اتحادیه.

prompt فقط می‌تواند یکی از موارد زیر باشد:

text

string

متن درخواست.

اطلاعات بیشتر در مورد انواع

برای اطلاعات بیشتر در مورد انواع مورد استفاده توسط API، به Python SDK مراجعه کنید.