Flow Music (fmusic)

flowmusic-cli

从终端、脚本或 AI Agent 使用 Google Flow Music（Lyria）创作音乐。

fmusic 是用于 flowmusic.app 的命令行客户端和 MCP 服务。你只需使用自己的 Google 账号登录一次。之后无需浏览器即可使用：描述一首歌曲，几分钟后就能获得 WAV 文件以及包含详细信息的 JSON 文件。

mcp-name: io.github.JvanLeeuwen4/flowmusic-cli

重要

非官方项目。 本项目与 Google 无关，也未获得 Google 的认可或支持。它使用与 flowmusic.app 网站相同的端点，因此网站变更时可能无法使用。你使用自己的账号和额度。请遵守 Flow Music 条款和生成式 AI 使用政策，并且不要将其用于垃圾信息或批量生成。

---

快速开始

uv tool install flowmusic-cli        # 1. install (or: pipx install flowmusic-cli)
fmusic auth login                    # 2. a browser opens once: sign in with Google
fmusic generate "dreamy synthwave, airy female vocals, 100 bpm"   # 3. make a song

输出示例：

♪ take 1 (audio__create_song) Dreamy synthwave, airy female vocals, lush pads, 100 bpm
  queued "Neon Drift" 3e2b2139-… (~35s)
  ✓ rendered "Neon Drift"
⬇ ~/Music/flowmusic-cli/2026-11-04/neon-drift_3e2b2139.wav
Neon Drift  1:44  3e2b2139-2783-4171-a2b4-a51d03bc4504
continue with: fmusic chat 13001945-… "…"

所需条件：

• Python 3.10+，通过 uv 或 pipx 安装。
• Google Chrome 或 Edge，用于一次性登录。
• 可使用 Flow Music 的 Google 账号。订阅 Google AI 可获得最多额度。

---

你可以做什么

我想要……	命令
根据描述创作歌曲	fmusic generate "folk ballad about the sea, male vocals"
使用自己的歌词	fmusic generate "upbeat k-pop" --lyrics lyrics.txt
创作纯音乐	fmusic generate "lofi beat, 80 bpm" --instrumental
修改刚创作的歌曲	fmusic chat <conversation_id> "make it faster, add a bridge"
为自己的音频重新编曲	fmusic generate "turn this into a jazz trio" --audio demo.mp3
将歌曲拆分为分轨	fmusic stems <clip_id>（人声、鼓、贝斯、其他）
查看自己的歌曲	fmusic clips list
下载、重命名或删除歌曲	fmusic clips download/rename/delete <clip_id>
创作循环播放的游戏音乐	fmusic generate "cozy village theme" --instrumental --loop（更多信息）
循环播放已有歌曲	fmusic loop <clip_id or file>（不消耗额度）
查看自己的额度	fmusic credits

每个命令和标志的完整参考见 docs/commands.md。

生成原理

Flow Music 配有一位 AI 联合制作人。你的提示词会发送给它，由它决定创作内容：通常会生成一到两段小样。它会将你的提示词改写成详细的“声音提示词”，并可能建议后续步骤。每次生成都属于一个对话，你可以使用 fmusic chat <conversation_id> "…" 继续该对话，例如调整、延长或混音某段小样。

如果你想绕过联合制作人进行精确控制，请使用实验性的 --direct 模式。你的提示词会原样发送给歌曲模型，而 -n 用于设置小样数量：

fmusic generate "minimal techno, 126 bpm, hypnotic" --direct -n 2 --title "Night Drive"

游戏音乐：无缝循环

Lyria 歌曲有前奏和完整的结尾，因此直接循环原始文件时，会从最后一个和弦跳回开头。--loop 可以解决这个问题：

试听 1 分钟 Lyria 片段在接缝前后各 8 秒的效果：🔊 循环播放原始文件 · 🔊 fmusic loop。接缝位于 0:08。

uv tool install --force "flowmusic-cli[game]"     # once: adds numpy + soundfile (no ffmpeg needed)
fmusic generate "cozy pixel-art village theme, acoustic guitar, 90 bpm" --instrumental --loop

⬇ ~/Music/flowmusic-cli/2026-11-05/peaceful-village_467c790b.wav
  ⟳ loop 0:24 → 1:44 (length 80.0s, similarity 0.96 good)
⬇ ~/Music/flowmusic-cli/2026-11-05/peaceful-village_467c790b_loop.ogg

• 提示词会加入一条简短指令：“可循环：节奏稳定，不要前奏，不要结尾”。
• <name>_loop.ogg 经过剪辑和交叉淡化，开启任意引擎（Godot、Unity、网页音频）的循环功能后都能流畅循环。使用 --loop-format wav|both 可生成 WAV。
• 完整 WAV 保留前奏，并以 smpl 块记录循环点。在 Godot 中，导入时选择 Loop Mode: Detect From WAV，即可先播放一次前奏，再开始循环。
• JSON 会加入 loop: {start_s, end_s, length_s, start_sample, end_sample, similarity, quality}。当 quality 为 poor 时，接缝可能听得出来；可以试试另一个版本。
• 已有歌曲不会消耗额度：使用 fmusic loop <clip_id> 或 fmusic loop theme.wav。

循环点的查找方式详见 docs/how-it-works.md。

---

安装

方式	命令
uv（推荐）	uv tool install flowmusic-cli
pipx	pipx install flowmusic-cli
支持游戏循环（--loop）	uv tool install "flowmusic-cli[game]"
从 GitHub 安装最新版	uv tool install git+https://github.com/JvanLeeuwen4/flowmusic-cli
更新	uv tool upgrade flowmusic-cli

此软件包会安装两个等效命令：fmusic 和 flowmusic。

登录

fmusic auth login      # opens Chrome/Edge: sign in with Google; the window closes by itself
fmusic auth status     # shows email, subscription tier, credits (exit code 0 = OK)
fmusic auth logout

• 只需登录一次。令牌会自动刷新，因此除非你退出登录或会话被撤销，否则无需再次登录。
• 如需使用多个账号，可在任意命令中添加 --profile work（或设置 FMUSIC_PROFILE=work）。
• 无法打开浏览器（例如在服务器上）？请在另一台设备上登录 flowmusic.app。在浏览器的开发者工具中打开 Network 标签页，复制任意 __api 请求的 Cookie 标头，然后运行：

  fmusic auth import "sb-sb-auth-token.0=base64-…; sb-sb-auth-token.1=…"
  

---

在 AI Agent 中使用

fmusic 专为 Agent 调用而设计。有三种方式：

1. Claude Code 插件（技能 + MCP 服务）

/plugin marketplace add JvanLeeuwen4/flowmusic-cli
/plugin install fmusic@flowmusic-cli

然后在终端中运行一次 fmusic auth login。该插件会通过 uvx 启动 MCP 服务，因此无需安装其他内容。

2. 任意 MCP 客户端（Claude Desktop、Cursor、VS Code、Codex 等）

将以下内容添加到客户端的 MCP 配置中。只需要 uv：

{
  "mcpServers": {
    "fmusic": { "command": "uvx", "args": ["--from", "flowmusic-cli[game]", "fmusic", "mcp", "run"] }
  }
}

如果已安装 fmusic，运行此命令即可自动写入配置：

fmusic mcp setup --target claude-code      # or: claude-desktop, print

工具及其参数详见 docs/mcp.md。

3. 使用 --json 的 CLI

每个命令都支持 --json：

• 结果会以一个 JSON 对象的形式输出到 stdout：{"status":"ok","data":…} 或 {"status":"fail","error":{…}}。
• 进度消息会输出到 stderr。
• 退出代码保持稳定。详见 docs/troubleshooting.md。

fmusic --json generate "calm piano, 70 bpm" --instrumental | jq '.data.clips[].files'

在此代码仓库中开展工作的 Agent 应阅读 AGENTS.md。

---

文件保存位置

默认情况下，歌曲会保存到 ~/Music/flowmusic-cli/<date>/。使用 -o DIR 可指定文件夹；文件会直接保存到该文件夹中。每个片段会生成：

neon-drift_3e2b2139.wav     # audio (or .m4a with --format m4a; both with --format both)
neon-drift_3e2b2139.json    # title, duration, sound prompt, lyrics, ids, URLs
neon-drift_3e2b2139.jpg     # cover art (only with --cover)

配置

所有设置均为可选环境变量。

变量	默认值	用途
FMUSIC_PROFILE	default	要使用的已保存账号
FMUSIC_OUTPUT_DIR	~/Music/flowmusic-cli	下载文件的保存位置
FMUSIC_HOME	OS user-data dir	会话的存储位置
FMUSIC_TIMEOUT	60	HTTP 超时时间（秒）

故障排除

最常见的问题：

• 上传包含人声的曲目时，提示「在你所在的地区不可用」。 在包括欧盟在内的一些地区，Flow Music 不允许上传含人声的曲目或从中移除人声。请改为上传纯伴奏曲目。
• Session expired（退出代码 3）。 重新运行 fmusic auth login。
• Google 不允许你登录。 请确保已安装 Chrome 或 Edge。你也可以改用 fmusic auth import。

其他内容请参阅 docs/troubleshooting.md。

---

文档

文档	适用对象
docs/commands.md	所有命令、标志和 JSON 结构
docs/mcp.md	MCP 工具和客户端设置
docs/troubleshooting.md	错误、退出代码和解决方法
docs/how-it-works.md	架构和 flowmusic.app API
AGENTS.md	贡献者和编码 Agent
llms.txt	面向大模型的简明摘要

参与贡献

欢迎提交问题和拉取请求。布局和测试命令请参阅 AGENTS.md：

uv run --extra dev pytest

登录方式的设计灵感来自 gflow-cli。采用 MIT 许可证。