Live Music API - WebSockets API reference

Для генерации музыки в реальном времени Lyria использует постоянное двунаправленное потоковое подключение с низкой задержкой через WebSockets. В этом разделе вы найдете дополнительную информацию о WebSockets API.

Сеансы

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

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

Подключение WebSocket

Чтобы начать сеанс, подключитесь к этой конечной точке WebSocket:

wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.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 Сигналы управления воспроизведением для генерации модели

Получение сообщений

Чтобы получать сообщения от сервера, отслеживайте событие 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, поэтому поле будет находиться на верхнем уровне сообщения.)

Сообщения и события

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

Необязательное поле. Определяет, как модель выбирает токены для выходных данных.

Выбирает токены topK с наибольшей вероятностью. Допустимый диапазон: [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 До мажор или ля минор
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 Остановить генерацию музыки и сбросить контекст (запросы сохраняются). Чтобы перезапустить создание музыки, используйте команду "Воспроизведи".
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

Текстовый запрос.

Подробнее о типах

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