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

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

Выбирает 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 Удерживайте воспроизведение музыки. Нажмите кнопку 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}

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

Этот тип не имеет полей.

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

WeightedPrompt

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

Поля
weight

float

Обязательно. Вес подсказки.

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

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

prompt поля Союза.

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

text

string

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

Дополнительная информация о типах

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