Live Music API - WebSockets API reference

Генерация музыки Lyria RealTime использует постоянное, двунаправленное потоковое соединение с низкой задержкой с помощью WebSockets . В этом разделе вы найдете дополнительные сведения об API WebSockets.

Сессии

Соединение WebSocket устанавливает сессию для поддержания связи с моделью в режиме реального времени. После того, как клиент инициирует новое соединение, сессия может обмениваться сообщениями с сервером, чтобы:

  • Отправляйте подсказки и элементы управления для управления процессом создания музыки.
  • Отправка элементов управления воспроизведением музыки.
  • Принимать аудиофрагменты.

WebSocket-соединение

Для начала сеанса подключитесь к следующему адресу веб-сокета:

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

Настройки сессии

Первоначальное сообщение после установления соединения задает модель, которая будет использоваться в течение сессии.

См. следующий пример конфигурации. Обратите внимание, что регистр имен в SDK может различаться. Параметры конфигурации Python SDK можно найти здесь .


{
  "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

Только вывод. Подсказки и конфигурация, использованные для генерации этого аудиофрагмента.

Исходные метаданные

Метаданные об источнике входного сигнала, использованном для генерации этого аудиофрагмента.

Поля
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

Необязательный параметр. Режим генерации музыки. По умолчанию — КАЧЕСТВО.

Режим генерации музыки

Перечисления
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 Приостановите воспроизведение музыки. Используйте кнопку ВОСПРОИЗВЕДЕНИЕ, чтобы продолжить с текущей позиции.
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}

BidiСоздатьМузыкуНастройкаЗавершить

Этот тип не содержит полей.

Отправлено в ответ на сообщение BidiGenerateMusicSetup от клиента.

ВзвешенныйПодсказка

Взвешенная подсказка в качестве входных данных для модели.

Поля
weight

float

Обязательно. Вес запроса.

Вес используется для регулирования относительной важности подсказки. Более высокие значения веса соответствуют более важным подсказкам, чем более низкие.

Веса всех переменных weighted_prompts в этом сообщении BidiGenerateMusicClientContent не должны быть равны нулю. Веса всех переменных weighted_prompts в этом сообщении BidiGenerateMusicClientContent будут нормализованы.

prompt поля объединения.

prompt может быть выбран только один из следующих вариантов:

text

string

Текстовая подсказка.

Более подробная информация о типах

Для получения дополнительной информации о типах данных, используемых API, см. Python SDK .