Live Music API - WebSockets API reference

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

جلسات

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

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

اتصال WebSocket

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

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

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

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

پیکربندی نمونه زیر را ببینید. توجه داشته باشید که حروف نام در کیت‌های توسعه نرم‌افزار ممکن است متفاوت باشد. می‌توانید گزینه‌های پیکربندی کیت توسعه نرم‌افزار Python را در اینجا جستجو کنید.


{
  "model": string
}

ارسال کردن پیام‌ها

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


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

پیام‌های کارخواه پشتیبانی‌شده

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

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

دریافت پیام

برای دریافت پیام از سرور، رویداد 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 بیان نشده است، بنابراین این فیلد در سطح بالای پیام نشان داده خواهد شد.)

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

AudioChunk

نمایش یک بخش صوتی.

فیلدها

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

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

bytes

بایت‌های خام بخش صدا.
mimeType

string

نوع MIME محتوای بخش صوتی، مانند «audio/wav».
sourceMetadata

SourceMetadata

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

SourceMetadata

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

فیلدها
clientContent

BidiGenerateMusicClientContent

پیام‌واره‌های وزن‌دار برای تولید این بخش صوتی.
musicGenerationConfig

BidiGenerateMusicGenerationConfig

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

BidiGenerateMusicClientContent

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

فیلدها
weightedPrompts[]

WeightedPrompt

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

BidiGenerateMusicClientMessage

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

فیلدها

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

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

BidiGenerateMusicSetup

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

BidiGenerateMusicClientContent

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

BidiGenerateMusicGenerationConfig

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

BidiGenerateMusicPlaybackControl

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

BidiGenerateMusicFilteredPrompt

پیام‌واره فیلترشده با دلیل.

فیلدها
filteredReason

string

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

string

اختیاری. پیام‌واره نوشتاری.

BidiGenerateMusicGenerationConfig

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

فیلدها
temperature

float

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

مقادیر بالاتر باعث ایجاد واریانس بالاتر می‌شود. محدوده [0.0, 3.0] است. پیش‌فرض ۱٫۱ است.
topK

int32

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

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

int32

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

float

اختیاری. کنترل می‌کند که مدل تا چه اندازه از پیام‌واره‌ها پیروی کند. راهنمای بالاتر دقیق‌تر دنبال می‌کند، اما انتقال‌ها را ناگهانی‌تر می‌کند. محدوده [۰٫۰، ۶٫۰] است. پیش‌فرض ۴٫۰ است.
bpm

int32

اختیاری. ضربان در دقیقه. محدوده [۶۰، ۲۰۰] است.
density

float

اختیاری. تراکم صداها. محدوده [۰٫۰، ۱٫۰] است.
brightness

float

اختیاری. مقدار بالاتر صدای روشن‌تری تولید می‌کند. محدوده [۰٫۰، ۱٫۰] است.
scale

Scale

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

bool

اختیاری. برونداد صدا نباید شامل صدای بم باشد.
muteDrums

bool

اختیاری. برونداد صوتی نباید شامل درام باشد.
onlyBassAndDrums

bool

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

MusicGenerationMode

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

MusicGenerationMode

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

مقیاس

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

شمارشی‌ها
SCALE_UNSPECIFIED مقدار پیش‌فرض. از این مقدار استفاده نمی‌شود.
C_MAJOR_A_MINOR دو ماژور یا لا مینور
D_FLAT_MAJOR_B_FLAT_MINOR ماژور ر بمل یا مینور سی بمل
D_MAJOR_B_MINOR ماژور D یا مینور B
E_FLAT_MAJOR_C_MINOR می بمل ماژور یا دو مینور
E_MAJOR_D_FLAT_MINOR می‌ماژور یا رِ بِمُل مینور
F_MAJOR_D_MINOR فا ماژور یا ر مینور
G_FLAT_MAJOR_E_FLAT_MINOR سُل ماژور یا می مینور
G_MAJOR_E_MINOR ماژور G یا مینور E
A_FLAT_MAJOR_F_MINOR ماژور مسطح یا مینور اف
A_MAJOR_G_FLAT_MINOR ماژور یا مینور سل بمل
B_FLAT_MAJOR_G_MINOR ماژور سی بمل یا مینور سل
B_MAJOR_A_FLAT_MINOR ماژور B یا مینور A فلت

BidiGenerateMusicPlaybackControl

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

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

BidiGenerateMusicServerContent

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

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

فیلدها
audioChunks[]

AudioChunk

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

BidiGenerateMusicServerMessage

پیام پاسخ برای تماس BidiGenerateMusic.

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

BidiGenerateMusicSetupComplete

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

BidiGenerateMusicServerContent

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

BidiGenerateMusicFilteredPrompt

فقط برونداد. پیام‌واره فیلترشده با دلیل.
warning

string

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

BidiGenerateMusicSetup

پیام در BidiGenerateMusicClientMessage اول (و فقط در اول) ارسال می‌شود.

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

فیلدها
model

string

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

قالب: models/{model}

BidiGenerateMusicSetupComplete

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

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

WeightedPrompt

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

فیلدها
weight

float

الزامی. وزن پیام‌واره.

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

وزن همه پیام‌واره‌های وزن‌دار در این BidiGenerateMusicClientContent نباید همه ۰ باشد. وزن همه weighted_prompts در این پیام BidiGenerateMusicClientContent عادی‌سازی خواهد شد.

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

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

string

پیام‌واره نوشتاری.

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

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