huangquan-bgm

LLM-Driven Adaptive Guqin + Xiao BGM Prototype

这是一个低显存游戏 BGM 原型：运行时不生成 WAV 波形，而是实时生成 MIDI / 音符事件，再交给古琴、箫音源渲染。

当前版本是纯 Python、无第三方依赖的规则生成器，方便先把游戏流程跑通。后续可以把 bgm_midi/generator.py 里的规则生成逻辑替换成训练好的 tiny Transformer / LSTM / MusicVAE。

为什么用 MIDI

• 运行时几乎不占 GPU 显存，适合只给 BGM 留 3-4GB 甚至 0GB 的场景。
• 可以按小节生成、循环、变奏和转场。
• 音质由 Kontakt 采样库决定。当前项目优先使用 D:\Code\BGM\kontakt_libraries 下的龙吟古琴和箫库，F 盘原始库保留为备份。主音源目录使用拼音路径；少量 Wallpaper 皮肤图片保留原文件名，因为 Kontakt Player 的 .nki 内部会引用它们。

快速生成

生成约 2 分钟平静探索 BGM：

python -m bgm_midi.cli --mood calm --duration 120 --out out/calm_2min.mid

生成带剧情变化的 BGM：

python -m bgm_midi.cli --timeline calm:12,tense:12,battle:16,victory:8 --transition-bars 4 --out out/story_transition.mid

Kontakt 实时试听

已经创建了 conda 环境脚本：

powershell -ExecutionPolicy Bypass -File scripts\create_conda_env.ps1

启动 Web UI：

powershell -ExecutionPolicy Bypass -File scripts\run_web_ui.ps1

打开：

http://127.0.0.1:8765/?v=19&demo=1

Web UI 只生成 MIDI 结构，不再渲染替代音色 WAV。要听声音，需要：

• loopMIDI 里创建 BGM_TO_KONTAKT
• Kontakt 里加载 D:\Code\BGM\kontakt_libraries\longyin_guqin_3_0_2025\LongYin_GuQin_3.0_B_Nature.nki
• Kontakt 里加载 D:\Code\BGM\kontakt_libraries\xiao_v3_0a\Xiao_V3.0_Leg_3.nki
• 古琴设 MIDI Ch 1，箫设 MIDI Ch 2
• Web UI 选择 BGM_TO_KONTAKT 后点 Kontakt

固定 seed 可以复现同一段音乐；不传 seed 每次都会生成不同版本：

python -m bgm_midi.cli --mood tense --duration 120 --seed 42 --out out/tense_seed42.mid

情绪标签

当前支持：

• calm：平静、山水、探索
• sad：离别、回忆、失败
• tense：潜行、悬疑、危机
• battle：战斗、追逐、冲突
• victory：胜利、解谜成功

游戏内集成思路

LLM 剧情系统
  -> mood / intensity / scene
  -> BGM Planner 决定调式、BPM、密度、声部
  -> MIDI Generator 生成 4-8 小节
  -> Kontakt 加载项目内古琴/箫采样库实时播放
  -> 小节边界 crossfade / 变奏 / 循环

音色说明

MIDI 文件里轨道会标成 Guqin 和 Xiao，但不会再写 General MIDI 占位程序号。音色完全由 Kontakt 当前加载的 .nki 决定。

当前推荐音源：

• 古琴：D:\Code\BGM\kontakt_libraries\longyin_guqin_3_0_2025\LongYin_GuQin_3.0_B_Nature.nki
• 箫：D:\Code\BGM\kontakt_libraries\xiao_v3_0a\Xiao_V3.0_Leg_3.nki

真实音源接入说明见：

docs\KONTAKT_LIVE_MIDI.md

后续替换成训练模型

保留运行时接口：

{
  "mood": "tense",
  "intensity": 0.7,
  "bars": 8,
  "seed": 1234,
  "previous_state": {
    "bpm": 72,
    "scale": "A yu pentatonic",
    "last_pitch": 57
  }
}

模型输出仍然是音符事件：

{
  "instrument": "guqin",
  "pitch": 69,
  "start_beat": 1.5,
  "duration_beat": 0.75,
  "velocity": 72
}

这样训练阶段可以很重，运行阶段仍然轻。