Lyria RealTime 实时音乐生成上手记：3 步跑通第一条旋律，附 5 条避坑清单
【免费下载链接】cookbookExamples and guides for using the Gemini API项目地址: https://gitcode.com/GitHub_Trending/coo/cookbook
写 Demo 或做直播时，你大概率遇到过这种情况：想当场把曲风从爵士改成电子，或者把速度调快半拍，而不是重新生成一整首再等它播完。Lyria RealTime 就是为这种场景准备的实时音乐生成模型——它通过 websocket 双向流持续输出音乐，你可以随时打断它、改方向。这篇上手记带你用 Google 官方的 Gemini API Cookbook 仓库，快速把这条路走通。
先搞清楚 Cookbook 是什么、Lyria RealTime 在里面占什么位置
Gemini API Cookbook 是 Google 维护的示例仓库，按"quickstarts（单功能入门）+ examples（组合场景）"两层组织，每个功能都配了可直接运行的代码。Lyria RealTime 的实时音乐生成能力放在 quickstarts 目录下，有三个入口：Colab 版 Notebook、本地 Python 脚本、websocket 协议版 Notebook。注意两点前提：模型名是lyria-realtime-exp，属于实验功能，只通过v1alpha接口开放；另外它生成的是纯器乐，不含人声。
从 clone 到听到第一句旋律，只需要 3 步
获取项目。把仓库克隆到本地：
git clone https://gitcode.com/GitHub_Trending/coo/cookbook装依赖。本地脚本路线只需要两个包，SDK 要求 1.16 及以上版本：
pip install pyaudio websockets pip install -U "google-genai>=1.16"跑通首个示例。把在 Google AI Studio 申请的密钥放进环境变量（Colab 路线则写在名为GEMINI_API_KEY的 Colab Secret 里），然后执行：
python quickstarts/Get_started_LyriaRealTime.py脚本会先让你粘贴一次 API Key，随后以钢琴、BPM 120、A 小调起步，音乐直接从扬声器里流出来，同时终端等待你的输入。
拆开看：Lyria RealTime 的五个功能
用加权提示词开一段音乐
能做什么：用一组"提示词 + 权重"决定音乐风格。怎么触发：调用session.set_weighted_prompts，参数是{"text": ..., "weight": ...}的列表，本地脚本里则直接敲入一句提示词，等价于权重 1.0 的单条加权提示词。会看到什么：权重可以是任意实数，包括负数，唯独不能为 0；被内容过滤的提示词不会报错，而是返回一个filtered_prompt字段，需要自己留意。
边听边改：中途换风格
能做什么：音乐播放到一半时整体换风格，或叠加新的风格。怎么触发：脚本运行中输入形如indie pop:0.8, sitar:1.5的字符串，多个提示词用逗号分隔、权重跟在小数点后。会看到什么：解析器只按第一个冒号切分，提示词里再出现冒号也不会出错；格式不对的片段会被跳过，并打印一条 Error 日志，已解析出的合法部分照常发送。换风格不需要重置上下文，改动即时生效。
控制 BPM、调式和采样参数
能做什么：调整速度、调式这些硬性参数。怎么触发：输入bpm=90、scale=C_MAJOR（调式取值来自 SDK 的types.Scale枚举）、top_k=50，末尾写AUTO表示恢复自动。会看到什么：这三类改动和换风格不同，每次都会触发reset_context()，音乐会在新参数下重新展开，而不是延续之前的乐句。
播放、暂停、停止
能做什么：控制会话本身。怎么触发：输入play、pause继续或挂起，输入q发送停止命令并退出。会看到什么：pause 之后会话仍保留，再输入play即可接着播，不用重新建连。
把它接进自己的应用
能做什么：脱离脚本，用原始 websocket 协议把生成结果接进自己的应用。怎么触发：本地脚本用 PyAudio 以 48000 Hz、双声道、16 bit 播放接收到的音频块；想深入协议细节，看quickstarts/websockets/Get_started_LyriaRealTime_websockets.ipynb里的setup、send、recv流程，其中强调必须先等到setup_complete响应再发送其他消息。会看到什么：脚本里的BUFFER_SECONDS=1是防网络抖动的缓冲，调小它延迟更低但更容易断音，调大则相反——这是一个明确的延迟换稳定性的权衡点。
跟着走一遍：一条可以边听边改的钢琴曲
第 1 步，完成上面"只需要 3 步"里的安装与密钥设置，运行python quickstarts/Get_started_LyriaRealTime.py，听到钢琴声且终端出现>提示符，说明会话已建立。第 2 步，输入latin jazz:1.2, 808 hip hop beat:0.5，几秒内旋律走向从钢琴独白转向拉丁爵士，808 底鼓声加进来。第 3 步，输入bpm=140，音乐在重置上下文后以更快速度重新展开；满意后输入q结束。整个过程没有任何"等待生成完毕"的环节，每次改动都是在播放流上直接生效的。
Lyria RealTime 踩过的 5 个坑
- 输入一段长句描述后效果平平 → 模型对简短词汇的响应更准 → 提示词保持单个词级别，比如
meditation、eerie、harp，别写长句。 - 某个加权提示词写了
weight: 0→ 权重为 0 不被接受 → 改用非零值，想弱化某风格就给它一个小数值或负数。 - 在 Colab 里 Notebook 却听不到"实时"效果 → Colab 要把音频块全部收完才拼成 wav 播放 → 想要真正的实时体验，用本地脚本路线。
- 连接直接报错、模型不存在 → Lyria RealTime 是实验功能 → 确认客户端带了
http_options={'api_version': 'v1alpha'}且模型名是models/lyria-realtime-exp。 - 本地播放偶尔断音 → 网络抖动超过了缓冲 → 把脚本里的
BUFFER_SECONDS从 1 调大，代价是控制指令的延迟同步变大。
延伸资源
- quickstarts/Get_started_LyriaRealTime.ipynb：Colab 版入门，含日志与 wav 写入的完整实现
- quickstarts/Get_started_LyriaRealTime.py：本地实时交互脚本，线程与错误处理更完整
- quickstarts/websockets/Get_started_LyriaRealTime_websockets.ipynb：原生 websocket 协议版，适合想接自己后端的人
- quickstarts/Get_started_Lyria.ipynb：Lyria 3 一次性整曲生成，和 RealTime 版本互补
Lyria RealTime 目前是预览功能，暂时免费但有配额限制，接口可能变化；上面这套走法基于当前仓库版本，跑不通时先对照避坑清单，再看 notebook 里的日志输出定位问题。
【免费下载链接】cookbookExamples and guides for using the Gemini API项目地址: https://gitcode.com/GitHub_Trending/coo/cookbook
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
