# 使用 Lyria RealTime 实时生成音乐

{% callout type="note" %}
Lyria RealTime 是 [实验模型](/docs/models#experimental).
{% /callout %}

Gemini API，使用 [Lyria Realtime](https://deepmind.google/technologies/lyria/realtime/)，提供对最先进的实时流媒体音乐生成模型的访问。它允许开发人员构建应用程序，用户可以在其中交互地创作、持续引导和演奏器乐。

Lyria Realtime 音乐生成使用持久、双向、低延迟的流连接 [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API).

要体验使用 Lyria Realtime 可以构建的内容，请使用 AI Studio 进行尝试 [提示 DJ](https://aistudio.google.com/apps/bundled/promptdj) 或 [MIDI DJ](https://aistudio.google.com/apps/bundled/promptdj-midi) 应用程序。

{% callout type="note" %}
寻找非流媒体音乐生成？看 [使用 Lyria 3.5 生成音乐](/docs/music-generation).
{% /callout %}

## 生成和控制音乐  {% #generate-music %}

Lyria Realtime 的工作原理与 [多式联运 Live API](/docs/live-api)
因为它使用 Websockets 来保持与模型的实时通信。

以下代码演示了如何生成音乐：

{% tabs %}
{% tab filename="sample.py" label="Python" %}
此示例使用以下命令初始化 Lyria Realtime 会话 `client.aio.live.music.connect()`，然后发送初始提示 `session.set_weighted_prompts()` 以及使用的初始配置 `session.set_music_generation_config`，使用开始音乐生成 `session.play()` 并设置 `receive_audio()` 处理它接收到的音频块。

```python
  import asyncio
  from google import genai
  from google.genai import types

  client = genai.Client(http_options={'api_version': 'v1beta'})

  async def main():
      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()
  if __name__ == "__main__":
      asyncio.run(main())
```

目标：有关更完整的代码示例，请参阅 [Lyria RealTime - 开始](https://colab.sandbox.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Get_started_LyriaRealTime.ipynb)
食谱存储库中的文件。
{% /tab %}

{% tab filename="sample.js" label="JavaScript" %}
此示例使用以下命令初始化 Lyria Realtime 会话 `client.live.music.connect()`，然后发送初始提示 `session.setWeightedPrompts()` 以及使用的初始配置 `session.setMusicGenerationConfig`，使用开始音乐生成 `session.play()` 并设立一个 `onMessage` 回调来处理它接收到的音频块。

```javascript
import { GoogleGenAI } from "@google/genai";
import Speaker from "speaker";

const client = new GoogleGenAI({
  apiKey: GEMINI_API_KEY,
    apiVersion: "v1beta" ,
});

async function main() {
  const speaker = new Speaker({
    channels: 2,       // stereo
    bitDepth: 16,      // 16-bit PCM
    sampleRate: 44100, // 44.1 kHz
  });

  const session = await client.live.music.connect({
    model: "models/lyria-realtime-exp",
    callbacks: {
      onmessage: (message) => {
        if (message.serverContent?.audioChunks) {
          for (const chunk of message.serverContent.audioChunks) {
            if (chunk.data) {
              const audioBuffer = Buffer.from(chunk.data, "base64");
              speaker.write(audioBuffer);
            }
          }
        }
      },
      onerror: (error) => console.error("music session error:", error),
      onclose: () => console.log("Lyria RealTime stream closed."),
    },
  });

  await session.setWeightedPrompts({
    weightedPrompts: [
      { text: "Minimal techno with deep bass, sparse percussion, and atmospheric synths", weight: 1.0 },
    ],
  });

  await session.setMusicGenerationConfig({
    musicGenerationConfig: {
      bpm: 90,
      temperature: 1.0,
    },
  });

  await session.play();
}

await main();
```

目标：要获得更完整的代码示例，请尝试 [提示 DJ](https://aistudio.google.com/apps/bundled/promptdj)
和 [MIDI DJ](https://aistudio.google.com/apps/bundled/promptdj-midi) AI Studio 上的应用程序

然后您可以使用 `session.play()`, `session.pause()`, `session.stop()` 和 `session.reset_context()` 启动、暂停、停止或重置会话。
{% /tab %}
{% /tabs %}

## 实时控制音乐  {% #steer-music %}

您可以通过发送提示和实时更新生成参数来实时引导音乐生成。

### 提示 Lyria Realtime  {% #prompting-lyria %}

当流处于活动状态时，您可以发送新的 `WeightedPrompt` 随时更改生成的音乐的消息。该模型将根据新的输入平稳过渡。

提示需要遵循正确的格式并带有 `text` （实际的提示），以及 `weight`。的 `weight` 可以取任何值，除了 `0`. `1.0`
通常是一个很好的起点。

{% tabs %}
{% tab filename="sample.py" label="Python" %}
```python
  from google.genai import types

  await session.set_weighted_prompts(
    prompts=[
      {"text": "Piano", "weight": 2.0},
      types.WeightedPrompt(text="Meditation", weight=0.5),
      types.WeightedPrompt(text="Live Performance", weight=1.0),
    ]
  )
```
{% /tab %}

{% tab filename="sample.js" label="JavaScript" %}
```javaScript
  await session.setWeightedPrompts({
    weightedPrompts: [
      { text: 'Harmonica', weight: 0.3 },
      { text: 'Afrobeat', weight: 0.7 }
    ],
  });
```

请注意，当大幅更改提示时，模型转换可能会有点突然，因此建议通过向模型发送中间权重值来实现某种交叉淡入淡出。
{% /tab %}
{% /tabs %}

### 更新配置  {% #steer-config %}

您可以通过实时更新音乐生成参数来控制音乐生成。您不能只更新一个参数，您需要设置整个配置，否则其他字段将重置回默认值。

由于更新 bpm 或比例对模型来说是一个巨大的变化，因此您还需要告诉它使用以下命令重置其上下文 `reset_context()` 考虑新的配置。它不会停止直播，但这将是一个艰难的过渡。您不需要对其他参数执行此操作。

{% tabs %}
{% tab filename="sample.py" label="Python" %}
```python
  from google.genai import types

  await session.set_music_generation_config(
    config=types.LiveMusicGenerationConfig(
      bpm=128,
      scale=types.Scale.D_MAJOR_B_MINOR,
      music_generation_mode=types.MusicGenerationMode.QUALITY
    )
  )
  await session.reset_context();
```
{% /tab %}

{% tab filename="sample.js" label="JavaScript" %}
```javaScript
  await session.setMusicGenerationConfig({
    musicGenerationConfig: {
      bpm: 120,
      density: 0.75,
      musicGenerationMode: MusicGenerationMode.QUALITY
    },
  });
  await session.reset_context();
```
{% /tab %}
{% /tabs %}

## 提示Lyria RealTime  {% #prompting-lyria-realtime %}

Lyria RealTime 使用加权提示动态地混合音乐流派、乐器和情绪。要探索提示引导策略、关键字标签词汇和完整的提示示例，请参阅 [Lyria 提示指南](/docs/lyria-prompt-guide#realtime-prompting).

## 最佳实践  {% #best-practices-music %}

* 客户端应用程序必须实现强大的音频缓冲以确保流畅播放。这有助于解决网络抖动和生成延迟的轻微变化。
* 有效的提示： * 具有描述性。使用形容词来描述情绪、流派和乐器。
  * 逐步迭代和引导。不要完全改变提示，而是尝试添加或修改元素以使音乐更流畅地变化。
  * 尝试负重 `WeightedPrompt` 影响新提示对下一代的影响程度。

## 技术细节  {% #technical-details-music %}

本节详细介绍如何使用Lyria Realtime音乐生成。

### 规格  {% #audio-specs %}

* 输出格式：原始16位PCM音频
* 采样率：48kHz
* 通道：2（立体声）

### 控制  {% #controls %}

可以通过发送包含以下内容的消息来实时影响音乐生成：

* `WeightedPrompt`：描述音乐理念、流派、乐器、情绪或特征的文本字符串。可以提供多个提示来混合影响。参见 [上面](/docs/realtime-music-generation#steer-music) 有关如何最好地提示 Lyria Realtime 的更多详细信息。

* `MusicGenerationConfig`：音乐生成过程的配置，影响输出音频的特性。）。参数包括：* `guidance`：（浮点数）范围： `[0.0, 6.0]`。默认值： `4.0`。控制模型遵循提示的严格程度。更高的指导可以提高对提示的遵守程度，但也会使过渡更加突然。

  * `bpm`：（整数）范围： `[60, 200]`。设置生成音乐所需的每分钟节拍数。您需要停止/播放或重置模型的上下文，以考虑新的 bpm。
  * `density`：（浮点数）范围： `[0.0, 1.0]`。控制音符/声音的密度。较低的值会产生较稀疏的音乐；较高的值会产生“更繁忙”的音乐。
  * `brightness`：（浮点数）范围： `[0.0, 1.0]`。调整音质。较高的值会产生“更明亮”的声音音频，通常强调更高的频率。
  * `scale`：（枚举）设置生成的音阶（调和模式）。使用 [`Scale` 枚举值](/docs/realtime-music-generation#scale-enum) 由 SDK 提供。您需要停止/播放或重置模型的上下文，以考虑新的比例。
  * `mute_bass`：（布尔）默认值： `False`。控制模型是否降低输出的低音。
  * `mute_drums`：（布尔）默认值： `False`。控制模型输出是否减少输出的鼓声。
  * `only_bass_and_drums`：（布尔）默认值： `False`。引导模型尝试仅输出低音和鼓。
  * `music_generation_mode`：（枚举）指示模型是否应该关注 `QUALITY` （默认值）或 `DIVERSITY` 的音乐。也可以设置为 `VOCALIZATION` 让模型作为另一种乐器生成发声（将它们添加为新的提示）。

* `PlaybackControl`：控制播放方面的命令，例如播放、暂停、停止或重置上下文。

对于 `bpm`, `density`, `brightness` 和 `scale`，如果未提供任何值，模型将根据您的初始提示决定最好的选择。

更经典的参数，例如 `temperature` （0.0 到 3.0, 默认为 1.1）， `top_k`
（1 到 1000, 默认为 40），以及 `seed` （默认随机选择0到2 147 483 647,）也可以在 `MusicGenerationConfig`.

#### 缩放枚举值  {% #scale-enum %}

以下是模型可以接受的所有比例值：

| 枚举值                         | 音阶/调            |
| --------------------------- | --------------- |
| `C_MAJOR_A_MINOR`           | C大调/A小调         |
| `D_FLAT_MAJOR_B_FLAT_MINOR` | D♭ 大调 / B♭ 小调   |
| `D_MAJOR_B_MINOR`           | D大调/B小调         |
| `E_FLAT_MAJOR_C_MINOR`      | E♭ 大调 / C 小调    |
| `E_MAJOR_D_FLAT_MINOR`      | E 大调 / C♯/D♭ 小调 |
| `F_MAJOR_D_MINOR`           | F大调/D小调         |
| `G_FLAT_MAJOR_E_FLAT_MINOR` | G♭ 大调 / E♭ 小调   |
| `G_MAJOR_E_MINOR`           | G大调/E小调         |
| `A_FLAT_MAJOR_F_MINOR`      | A♭ 大调 / F 小调    |
| `A_MAJOR_G_FLAT_MINOR`      | A大调/F♯/G♭小调     |
| `B_FLAT_MAJOR_G_MINOR`      | B♭ 大调 / G 小调    |
| `B_MAJOR_A_FLAT_MINOR`      | B 大调 / G♯/A♭ 小调 |
| `SCALE_UNSPECIFIED`         | 默认/型号决定         |

该模型能够指导演奏的音符，但不区分相关的键。因此，每个枚举都对应于相对的主要和次要。例如， `C_MAJOR_A_MINOR` 将对应于钢琴的所有白键，并且 `F_MAJOR_D_MINOR` 将是除降 B 之外的所有白键。

### 限制  {% #limitations %}

* 仅乐器：模型仅生成乐器音乐。
* 安全：通过安全过滤器检查提示。触发过滤器的提示将被忽略，在这种情况下，将在输出中写入解释 `filtered_prompt` 场。
* 水印：输出音频始终带有水印，以便按照我们的要求进行识别 [负责任的人工智能](https://ai.google/responsibility/principles/) 原则。

## 后续步骤  {% #next-steps %}

* 请参阅 [Lyria 提示指南](/docs/lyria-prompt-guide) 用于提示策略和关键词词汇，
* 生成完整的歌曲和声乐曲目 [Lyria 3.5](/docs/music-generation),
* 除了音乐之外，学习如何使用 [TTS 模型](/docs/speech-generation),
* 了解如何生成 [图片](/docs/image-generation) 或 [视频](/docs/video),
* 了解 Gemini 如何生成音乐或音频，而不是生成音乐或音频 [了解音频文件](/docs/audio),
* 使用 Gemini 进行实时对话 [多式联运 Live API](/docs/live-api).

探索 [食谱](https://github.com/google-gemini/cookbook) 了解更多代码示例和教程。
