Live Music API - WebSockets API reference

تستخدم ميزة "إنشاء الموسيقى في الوقت الفعلي" من Lyria اتصالاً دائمًا وثنائي الاتجاه وبمعدّل تأخير منخفض للبث المباشر باستخدام WebSockets. في هذا القسم، ستجد تفاصيل إضافية حول WebSockets API.

الجلسات

يُنشئ اتصال WebSocket جلسة للحفاظ على التواصل في الوقت الفعلي مع النموذج. بعد أن يبدأ العميل عملية ربط جديدة، يمكن للجلسة تبادل الرسائل مع الخادم لتنفيذ ما يلي:

  • إرسال طلبات وعناصر تحكّم لتوجيه عملية إنشاء الموسيقى
  • إرسال عناصر التحكّم في تشغيل الموسيقى
  • تلقّي أجزاء من الصوت

اتصال WebSocket

لبدء جلسة، اتّصِل بنقطة نهاية websocket هذه:

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

إعدادات الجلسة

تحدّد الرسالة الأولية بعد الاتصال النموذج الذي سيتم استخدامه خلال الجلسة.

اطّلِع على مثال الإعداد التالي. يُرجى العِلم أنّ طريقة كتابة الاسم قد تختلف في حِزم SDK. يمكنك البحث عن خيارات إعداد حزمة تطوير البرامج (SDK) في Python هنا.


{
  "model": string
}

إرسال الرسائل

لتبادل الرسائل عبر اتصال WebSocket، يجب أن يرسل العميل عنصر JSON عبر اتصال WebSocket مفتوح. يجب أن يحتوي عنصر JSON على حقل واحد فقط من مجموعة العناصر التالية:


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

رسائل العميل المتوافقة

اطّلِع على رسائل العميل المتوافقة في الجدول التالي:

الرسالة الوصف
BidiGenerateMusicSetup إعدادات الجلسة التي سيتم إرسالها فقط في الرسالة الأولى
BidiGenerateMusicClientContent طلبات مرجّحة كمدخلات للنموذج
BidiGenerateMusicGenerationConfig إعدادات إنشاء الموسيقى
BidiGenerateMusicPlaybackControl إشارات التحكّم في التشغيل لإنشاء النماذج

تلقي الرسائل

لتلقّي رسائل من الخادم، استمع إلى حدث WebSocket "message"، ثم حلِّل النتيجة وفقًا لتعريف رسائل الخادم المتوافقة.

يُرجى الاطّلاع على ما يلي:

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]. القيمة التلقائية هي 1.1.
topK

int32

اختيارية: تتحكّم هذه السمة في كيفية اختيار النموذج للرموز المميزة في الإخراج.

يأخذ عيّنات من أعلى K من الرموز المميزة ذات الاحتمالات الأعلى. النطاق هو [1, 1000]. القيمة التلقائية هي 40.

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.

MusicGenerationMode

عمليات التعداد
MUSIC_GENERATION_MODE_UNSPECIFIED هذه القيمة غير مستخدَمة.
QUALITY يوجّه هذا الوضع طلبات النص إلى مناطق في المساحة الكامنة تتضمّن موسيقى بجودة أعلى.
DIVERSITY يوجّه هذا الوضع طلبات النص إلى مناطق في المساحة الكامنة تتضمّن تنوّعًا أكبر في الموسيقى.
VOCALIZATION يوجه هذا الوضع طلبات النص إلى مناطق في المساحة الكامنة من المرجّح أن تنشئ موسيقى صوتية.

التطور

مقياس الموسيقى التي تم إنشاؤها

عمليات التعداد
SCALE_UNSPECIFIED القيمة التلقائية هذه القيمة غير مستخدَمة.
C_MAJOR_A_MINOR C major or A minor
D_FLAT_MAJOR_B_FLAT_MINOR D flat major or B flat minor
D_MAJOR_B_MINOR D major or B minor
E_FLAT_MAJOR_C_MINOR مي بيمول كبير أو دو صغير
E_MAJOR_D_FLAT_MINOR مقام "مي" الكبير أو مقام "ري بيمول" الصغير
F_MAJOR_D_MINOR مفتاح F الكبير أو مفتاح D الصغير
G_FLAT_MAJOR_E_FLAT_MINOR G flat major or E flat minor
G_MAJOR_E_MINOR السلم الموسيقي G الكبير أو السلم الموسيقي E الصغير
A_FLAT_MAJOR_F_MINOR مفتاح مسطّح رئيسي أو مفتاح F ثانوي
A_MAJOR_G_FLAT_MINOR مقام كبير أو مقام صغير ذو علامة خفض
B_FLAT_MAJOR_G_MINOR B flat major or G minor
B_MAJOR_A_FLAT_MINOR B major or A flat minor

BidiGenerateMusicPlaybackControl

عناصر التحكّم في تشغيل الموسيقى التي تم إنشاؤها

عمليات التعداد
PLAYBACK_CONTROL_UNSPECIFIED هذه القيمة غير مستخدَمة.
PLAY ابدأ بإنشاء الموسيقى.
PAUSE إيقاف إنشاء الموسيقى مؤقتًا استخدِم PLAY لاستئناف التشغيل من الموضع الحالي.
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

مطلوب. وزن الطلب

يتم استخدام عامل الترجيح للتحكّم في الأهمية النسبية للطلب. تكون الأوزان الأعلى أكثر أهمية من الأوزان الأقل.

يجب ألا تكون أوزان جميع weighted_prompts في BidiGenerateMusicClientContent كلها 0. سيتم تعديل أوزان جميع طلبات weighted_prompts في رسالة BidiGenerateMusicClientContent هذه.

حقل الدمج prompt

يمكن أن تكون prompt إحدى القيم التالية فقط:
text

string

طلب نصي

مزيد من المعلومات حول الأنواع

للحصول على مزيد من المعلومات حول الأنواع التي تستخدمها واجهة برمجة التطبيقات، راجِع حزمة تطوير البرامج (SDK) للغة Python.