Live Music API - WebSockets API reference

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

セッション

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

  • プロンプトとコントロールを送信して、音楽生成を操作します。
  • 音楽再生コントロールを送信する。
  • 音声チャンクを受信する。

WebSocket 接続

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

wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.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 ニ長調またはロ短調
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

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

形式: models/{model}

BidiGenerateMusicSetupComplete

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

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

WeightedPrompt

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

フィールド
weight

float

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

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

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

共用体フィールド prompt。

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

string

テキスト プロンプト。

型の詳細

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