Live Music API - WebSockets API reference

Lyria RealTime の音楽生成では、WebSockets を使用して、永続的で双方向の低レイテンシ ストリーミング接続を使用します。このセクションでは、WebSockets API に関する詳細について説明します。

セッション

WebSocket 接続は、モデルとのリアルタイム通信を維持するためのセッションを確立します。クライアントが新しい接続を開始すると、セッションがサーバーとメッセージを交換し、次のことを実行できます。

  • 音楽生成を制御するためのプロンプトとコントロールを送信します。
  • 音楽再生コントロールを送信します。
  • 音声チャンクを受信します。

WebSocket 接続

セッションを開始するには、次の WebSocket エンドポイントに接続します。

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

セッション構成

接続後の最初のメッセージで、セッション中に使用するモデルを設定します。

次の構成例をご覧ください。SDK の名前のケースは異なる場合があります。Python SDK の構成オプションはこちらで確認できます。


{
  "model": string
}

メッセージを送信する

WebSocket 接続を介してメッセージを交換するには、クライアントはオープンな WebSocket 接続を介して JSON オブジェクトを送信する必要があります。JSON オブジェクトには、次のオブジェクト セットのフィールドを 1 つだけ含める必要があります。


{
  "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 メッセージの他のフィールドが 1 つだけ含まれます。（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

省略可。1 分あたりの心拍数。範囲は [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 D major または B minor
E_FLAT_MAJOR_C_MINOR E フラット長調または C 短調
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 A major または G flat minor
B_FLAT_MAJOR_G_MINOR 変ロ長調またはト短調
B_MAJOR_A_FLAT_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 で送信されるメッセージ（最初の 1 回のみ）。

クライアントは、BidiGenerateMusicSetupComplete メッセージを待って、追加メッセージを送信する必要があります。

フィールド
model

string

必須。モデルのリソース名。これは、モデルが使用する ID として機能します。

形式: models/{model}

BidiGenerateMusicSetupComplete

この型にはフィールドがありません。

クライアントからの BidiGenerateMusicSetup メッセージに応答して送信されます。

WeightedPrompt

モデル入力としての重み付けされたプロンプト。

フィールド
weight

float

必須。プロンプトの重み。

重みは、プロンプトの相対的な重要度を制御するために使用されます。重みが大きいほど重要度が高くなります。

この BidiGenerateMusicClientContent 内のすべての weighted_prompts の重みがすべて 0 であってはなりません。この BidiGenerateMusicClientContent メッセージ内のすべての weighted_prompts の重みが正規化されます。

共用体フィールド prompt。

prompt は次のいずれかになります。
text

string

テキスト プロンプト。

型の詳細

API で使用される型については、Python SDK をご覧ください。