基于JUCE的吉他音高检测与本地LLM语音反馈插件开发-平芜编程栈

在音频插件开发中，一个比较有挑战的综合场景是：让真实乐器输入驱动一个本地语言模型，再通过语音合成反馈给演奏者。以吉他为例，把拾音器信号接入 JUCE 插件，经过音高检测得到当前音符，把音符序列构造成提示词，交给本机运行的本地 LLM 生成一段演奏点评或对话文本，最后通过 TTS 让吉他“开口说话”。这条链路涉及实时音频处理、跨线程通信、HTTP 调用、JSON 解析和音频回放，并非用一个库就能解决，而是需要在架构层面把不同子系统拼接起来。

这篇文章会带着你从零搭一个最小可复现的原型。适合有 JUCE 基础、对本地大模型感兴趣、想在 DAW 生态里做语音交互实验的开发者。学习完你会得到三个结果：一个能探测吉他音高并在界面上显示音符的插件；一个能按检测结果向本地 LLM 发起请求的后台线程；一个把 LLM 文本转成语音并播放的 TTS 通道。整个流程不依赖云端 API，数据不离开本机，适合做离线音乐教育工具、舞台互动装置或音频玩具。

1. 先理解“吉他开口说话”需要哪几层能力

1.1 从弹奏到语音反馈的完整数据链路

“吉他开口说话”不是一个单一功能，而是若干模块按顺序协作。吉他琴弦振动会产生模拟信号，经过音频接口变成数字音频进入 DAW，DAW 把音频块送给 JUCE 插件。插件首先要做音频采集和降噪预处理，然后从缓冲中提取音高或和弦信息，得到类似“C4”“E4”“G4”的音乐事件。

这些音乐事件会被组装成文本提示词，发给本地运行的 LLM 服务。本地 LLM 理解提示词中的演奏信息，输出一句自然语言回应。比如“你这次弹的 C 和弦很稳定，转换到 G 的时候手指可以提前半拍准备”。最后,系统把这段文本交给 TTS 引擎转换成语音波形，输送给扬声器或耳机，让演奏者听到一句由乐器“说出”的反馈。

这个链路最需要注意的是延迟和阻塞。音频线程对实时性要求很高，一旦在音频回调里执行网络请求、读取大文件或长时间计算，就会导致音频爆音甚至界面卡死。因此从音频采集到 LLM 请求，核心设计原则是把“实时采集”和“非实时处理”彻底分开：采样只在音频线程做，检测、推理、合成都在后台完成。

1.2 JUCE 在链路中的职责边界

JUCE 是整个原型的骨架。它负责提供音频插件框架、跨平台 GUI、音频输入输出、FIFO 缓冲、JSON 解析、URL 请求和消息线程机制。这些能力刚好覆盖从“拿到音频数据”到“展示状态和结果”的过程。

但 JUCE 不负责真正的大模型推理，也不负责合成高自然度的语音。本地 LLM 通常以独立服务形式运行，例如 Ollama 就是一个很好的选择。插件侧只需要通过 HTTP API 向它发送 prompt，并接收返回的文本，不需要知道模型内部是 Transformer、状态空间还是其他架构。同样地，TTS 可以由系统命令、外部进程或独立 TTS 服务完成，插件负责把语音音频播放到输出设备即可。

这样划分职责有几个好处。第一，插件体积不会因为捆绑模型而膨胀。第二，模型更换时只需要改配置，不需要重新编译插件。第三，调试时可以先单独测模型服务，再测插件，最后联调，定位问题更快。

1.3 本地 LLM 和在线 API 的取舍

在线大模型接口自然能生成更丰富的点评，但会把音频数据相关的上下文发送到外部服务器，这存在隐私和延迟问题。本地 LLM 的优势是数据不出机器，响应速度受本机资源限制，但完全可控，适合乐器练习这种需要低延迟、可重复测试的场景。

从开发角度说，本地模型可以让调试过程更稳定。在线 API 容易受到网络波动、限流、版本升级的影响，而本地模型只要版本固定，输出就相对可复现。作者建议原型阶段优先使用本地小模型，例如 3B 或 7B 的量化版本，而不是直接接入云端大模型。因为项目早期真正要验证的是链路能不能跑通，而不是模型生成效果有多惊艳。

对比项	在线 API	本地 LLM
延迟	受网络影响，通常 500ms 以上	取决于本机 CPU/GPU，3B 模型约 1-5 秒
隐私	需要发送数据到服务商	数据不离开本机
成本	按 token 计费	一次性硬件/下载成本
离线能力	依赖网络	完全离线
模型更换	换 API 或换 key 即可	需要本地下载模型文件

这个对比说明，对“吉他开口说话”这类工具型产品，本地 LLM 更合适。如果后续对生成质量要求提高，可以在插件里预留一个抽象接口，让 LLM 后端可以在本地服务和远程 API 之间切换。

2. 环境准备：从开发工具到本地模型服务

2.1 开发环境清单

开始写代码之前，先把环境确认清楚。这里会涉及四类组件：编译器与构建工具、JUCE 框架、音频宿主、本地模型服务。

类别	推荐工具	用途
插件框架	JUCE 6.1 以上	开发音频插件和界面
构建工具	Projucer 或 CMake 3.20+	生成工程、管理依赖
编译器	Xcode / MSVC / GCC	编译 C++ 代码
音频宿主	Ableton Live、REAPER、Logic 等	加载 VST3/AU 插件
本地模型服务	Ollama 0.1.x 以上	启动本地 LLM HTTP API
语言模型	qwen2.5:3b 或 llama3.2:3b	文本生成

如果计算机内存只有 8GB，建议选择 3B 模型。16GB 内存可以尝试 7B 模型。插件本身不会占用大量资源，资源主要消耗在模型推理和 TTS 合成。

2.2 安装并启动本地 LLM 服务

以 Ollama 为例，先安装并启动服务。安装命令在不同系统上有差异，下面给出常见 Linux/macOS 方式：

# 安装 Ollama curl -fsSL https://ollama.com/install.sh | sh # 启动服务 ollama serve

安装完成后，Ollama 默认在127.0.0.1:11434监听 HTTP 请求。接着下载一个适合 CPU 推理的模型：

ollama pull qwen2.5:3b

这一步会从模型仓库下载文件，需要一点时间和磁盘空间。下载完成后，可以通过ollama list确认模型已经存在。如果环境里已经有 Ollama 和模型，可以跳过安装，直接进入接口验证。

注意：ollama serve启动后会在前台运行，也可以设置成后台服务。调试阶段建议保持前台运行，方便观察日志和确认端口监听状态。

2.3 用 curl 验证接口

在写插件代码之前，先用 curl 调用一次接口，确认模型能返回文本。这个验证步骤很重要，它能把“LLM 服务问题”和“插件代码问题”隔离开来。

curl -s http://127.0.0.1:11434/api/generate \ -H "Content-Type: application/json" \ -d '{ "model": "qwen2.5:3b", "prompt": "你是一个吉他教练。学生刚刚弹了 C 大三和弦，请用一句话鼓励他。", "stream": false }'

正常情况会返回一段 JSON，类似：

{ "model": "qwen2.5:3b", "response": "很好，C 和弦的根音很清楚，继续保持稳定的时值。", "done": true }

如果得到connection refused，需要检查ollama serve是否在运行；如果返回model not found，说明模型名写错或还没有下载完成。这一步通过后，插件只需向相同地址发送 HTTP 请求即可。

3. 搭建 JUCE 插件工程

3.1 用 Projucer 创建插件工程

启动 Projucer，选择 “Audio Plug-in” 模板，设置插件名称为GuitarVoice，插件类型选择 Effect。这样插件会被加载到音频轨道的插入槽里，而不是作为虚拟乐器。

需要填写的几个关键字段：

Plugin Name：GuitarVoice。
Plugin Code：四位字符，比如Gvce。
Manufacturer Name：你的公司或个人标识。
Plugin Formats：根据需要勾选 VST3、AU、AAX。
Is Synth：关掉，保持false。

保存后，Projucer 会生成一个跨平台工程。你可以导出为 Xcode、Visual Studio 或 CMake 工程。这里建议使用 CMake，因为后续要加入第三方依赖或调整编译参数更方便。

3.2 CMake 方式的关键配置

如果使用 CMake，最小配置如下：

cmake_minimum_required(VERSION 3.20) project(GuitarVoice VERSION 0.1.0 LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) find_package(JUCE CONFIG REQUIRED) juce_add_plugin(GuitarVoice COMPANY_NAME "YourCompany" PLUGIN_MANUFACTURER_CODE Your PLUGIN_CODE Gvce FORMATS AU VST3 PRODUCT_NAME "GuitarVoice" VERSION "0.1.0" IS_SYNTH FALSE NEEDS_MIDI_INPUT FALSE NEEDS_MIDI_OUTPUT FALSE IS_MIDI_EFFECT FALSE EDITOR_WANTS_KEYBOARD_FOCUS FALSE ) target_compile_definitions(GuitarVoice PUBLIC JUCE_USE_CURL=0 )

juce_add_plugin里的FORMATS决定最终生成 AU 还是 VST3。IS_SYNTH FALSE保证插件被识别为效果器。JUCE_USE_CURL=0这个宏不是必须的，但如果你的环境中 JUCE 的 URL 模块想用系统原生的网络实现，可以显式关闭 curl。

3.3 插件类型与音频 IO 配置

Juce 插件默认输入输出通道数由宿主导入。吉他通常单声道进入声卡，然后 DAW 把单声道信号送给插件，插件输出可以是立体声。因此音频回调里要处理输入通道可能为 1、输出通道可能为 2 的情况。

在prepareToPlay中需要根据sampleRate和blockSize初始化检测器。下面是一个简化模板：

class GuitarVoiceAudioProcessor : public juce::AudioProcessor { public: GuitarVoiceAudioProcessor() { } void prepareToPlay (double sampleRate, int samplesPerBlock) override { currentSampleRate = sampleRate; // 这里初始化音高检测器、FIFO 等 } void processBlock (juce::AudioBuffer<float>& buffer, juce::MidiBuffer&) override { // 实时线程，绝对不能做阻塞操作 } juce::AudioProcessorEditor* createEditor() override { return nullptr; } bool hasEditor() const override { return false; } const juce::String getName() const override { return "GuitarVoice"; } private: double currentSampleRate = 44100.0; };

这个基类结构是 JUCE 插件的入口。真正的处理逻辑会放在processBlock之外的线程里，但音频数据必须先从processBlock读取出来，这一步是整个项目的地基。

4. 实现音频采集、音高检测和异步事件分发

4.1 音频回调只做采集，不碰网络和 UI

入门者最容易犯的错误是在processBlock里写网络请求或 UI 更新。音频回调会被系统以高优先级实时调度，任何阻塞都会让缓冲区欠载，轻则爆音，重则 DAW 界面卡死。

正确写法是：在processBlock中只把输入样本放入一个线程安全的 FIFO，检测和后续处理放到后台线程。

class GuitarVoiceAudioProcessor : public juce::AudioProcessor { public: void prepareToPlay (double sampleRate, int samplesPerBlock) override { currentSampleRate = sampleRate; inputFifo.setTotalSize ((int) sampleRate * 2); // 缓存最多 2 秒 inputFifo.reset(); detectionThread = std::make_unique<DetectionWorker> (*this); detectionThread->startThread(); } void processBlock (juce::AudioBuffer<float>& buffer, juce::MidiBuffer&) override { if (buffer.getNumChannels() < 1) return; const float* inputChannel = buffer.getReadPointer (0); for (int i = 0; i < buffer.getNumSamples(); ++i) { // 这里可以做一些轻量缓冲；具体 push 由 FIFO 实现 if (inputFifo.getFreeSpace() > 0) inputFifo.write (inputChannel[i]); } } private: double currentSampleRate = 44100.0; juce::AbstractFifo inputFifo { 44100 * 2 }; std::unique_ptr<DetectionWorker> detectionThread; };

AbstractFifo是 JUCE 提供的无锁单生产者单消费者环形缓冲。音频线程只调用write，后台线程只调用read，可以避免用std::mutex阻塞实时线程。

4.2 音高与和弦检测的最小实现思路

音高检测算法很多，最基础的是自相关函数。自相关的原理是：把信号和延迟了若干个采样点的自身信号做乘积求和，当延迟等于基频周期时，相关性最大。

下面是一个简化的实现，用于演示思路，不追求精度：

float estimatePitch (const float* data, int numSamples, double sampleRate) { const float minHz = 80.0f; const float maxHz = 1000.0f; int minLag = (int) std::ceil (sampleRate / maxHz); int maxLag = (int) std::floor (sampleRate / minHz); float bestLag = 0.0f; float bestScore = 0.0f; for (int lag = minLag; lag <= maxLag; ++lag) { float score = 0.0f; float energy = 0.0f; for (int i = 0; i + lag < numSamples; ++i) { float product = data[i] * data[i + lag]; score += product; energy += data[i] * data[i]; } if (energy == 0.0f) continue; float normalized = score / energy; if (normalized > bestScore) { bestScore = normalized; bestLag = (float) lag; } } if (bestLag > 0.0f) return (float) (sampleRate / bestLag); return 0.0f; }

这个版本没有做中心削波和归一化，直接在生产环境用会误判。更稳的方案是使用 YIN 算法或 pYIN，但最小原型可以先跑通流程。得到频率之后，把它转成 MIDI 音高和音名：

juce::String noteNameFromPitch (float pitch) { if (pitch <= 0.0f) return "Silence"; int midiNote = std::lround (69.0 + 12.0 * std::log2 (pitch / 440.0)); int pitchClass = (midiNote % 12 + 12) % 12; static const char* names[] = { "C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B" }; return names[pitchClass] + juce::String (midiNote / 12 - 1); }

例如 440Hz 会转成 A4。对于普通单音演奏，这个转换够用。和弦检测更复杂，需要 FFT 和多音高估计，这里不再展开。

4.3 通过 FIFO 将检测结果交给后台线程

后台线程每隔固定时间从 FIFO 读取一定长度的样本，调用estimatePitch。如果连续若干次都检测到同一个音高，就认为“当前音是稳定的”，这时才触发后续逻辑。这样可以避免噪声和换和弦瞬间的抖动。

class DetectionWorker : public juce::Thread { public: explicit DetectionWorker (GuitarVoiceAudioProcessor& p) : Thread ("GuitarDetection"), processor (p) { } void run() override { while (! threadShouldExit()) { // 从 sharedFifo 中读取 2048 个样本 // estimatePitch(...) // 如果音高稳定，构造事件并发送给 LLM sleep (100); } } private: GuitarVoiceAudioProcessor& processor; };

这里有一个很关键的点：不要在后台线程里直接修改 UI 控件。JUCE 的 UI 操作必须回到消息线程。正确做法是调用juce::MessageManager::callAsync，把更新 UI 的 lambda 派发到消息线程执行。LLM 请求和 TTS 可以留在后台线程，因为它们本身就是耗时的。

juce::MessageManager::callAsync ([note = detectedNote]() { // 更新 Label、TextEditor 等控件 });

5. 接入本地 LLM 并生成文本

5.1 用 JUCE URL 调用 Ollama 的 /api/generate

JUCE 的URL类可以发起 HTTP 请求。下面函数从后台线程调用：

juce::String queryOllama (const juce::String& prompt) { juce::URL url ("http://127.0.0.1:11434/api/generate"); std::map<juce::String, juce::String> headers; headers["Content-Type"] = "application/json"; auto body = juce::JSON::toString ( juce::var (new juce::DynamicObject()) ); // 构造 JSON 字符串更推荐用 DynamicObject，而不是手工拼接 auto jsonObj = new juce::DynamicObject(); jsonObj->setProperty ("model", "qwen2.5:3b"); jsonObj->setProperty ("prompt", prompt); jsonObj->setProperty ("stream", false); auto optionsObj = new juce::DynamicObject(); optionsObj->setProperty ("temperature", 0.7); optionsObj->setProperty ("num_predict", 200); jsonObj->setProperty ("options", juce::var (optionsObj)); auto bodyJson = juce::JSON::toString (juce::var (jsonObj)); auto* stream = url.createInputStream ( true, // 使用 POST nullptr, // 不发送文件 nullptr, // 不用小部件 headers, 15000 // 超时 15 秒 ); if (stream == nullptr) return {}; auto allText = stream->readEntireStreamAsString(); delete stream; auto json = juce::JSON::parse (allText); if (auto* obj = json.getDynamicObject()) return obj->getProperty ("response").toString(); return {}; }

url.createInputStream的第二个参数在 JUCE 不同版本中可能有差异。若你的 JUCE 版本比较新，可能需要传juce::URL::InputStreamOptions作为最后一个参数。遇到编译错误时，优先查看本机 JUCE 的头文件，以实际 API 为准。

5.2 构造 Prompt 和参数

本地 LLM 对 prompt 非常敏感。为了稳定输出，最好在提示词里明确角色、输入信息和输出格式。这里给出一个示例：

你是一位吉他助教。用户刚刚弹奏了以下音符序列： C4, E4, G4 请用两句话评价这段演奏，并提出一个具体的练习建议。不要输出超过两句话。

这个 prompt 有三个关键部分：角色、上下文、输出约束。角色帮助模型选择语气，上下文告诉模型发生了什么，输出约束控制生成长度。temperature可以设置为 0.5 到 0.8，太高会让输出飘忽不定，太低会让点评重复。

Ollama 的请求参数支持options字段，常用的包括：

参数	含义	推荐值
temperature	采样温度	0.5 - 0.8
num_predict	最大生成 token 数	100 - 300
top_p	核心采样概率	0.9
repeat_penalty	重复惩罚	1.1

这些参数在curl里也可以直接验证，方便先试出满意的效果，再写进插件。

5.3 解析返回 JSON 并抽取正文

Ollama/api/generate在stream=false时返回的 JSON 结构如下：

{ "model": "qwen2.5:3b", "created_at": "2025-01-01T12:00:00.000Z", "response": "C 和弦的根音很清楚，转换到 G 和弦时可以试试提前把手型准备好。", "done": true, "context": [...] }

所以插件只需要读取response字段。上面queryOllama函数已经做了这个抽取。如果response为空，但done是true，大概率是 prompt 太短或者模型被输出规则限制，可以打开日志打印原始 JSON 辅助排查。

还有一点要注意，JSON 字符串里的英文双引号、换行符需要转义。用juce::JSON构造 body，可以避免手工拼字符串的转义问题。

6. 让结果真正“说出来”：TTS 合成与播放

6.1 在 JUCE 插件里选择 TTS 方案

文本生成之后，下一步是语音合成。在 JUCE 里没有内置 TTS 模块，需要依赖外部组件。常见方案对比：

方案	优点	缺点
macOS`say`命令	无需额外安装，中文语音可用	平台限定，阻塞式
Windows PowerShell 语音合成	Windows 自带	中文语音包可能缺失
espeak / espeak-ng	轻量，跨平台	音质机械
Piper TTS	本地推理，音质较好	需要下载模型
预生成 WAV 文件	稳定性最高	不能动态生成

最小原型里，为了快速看到效果，可以使用系统命令。若要做成产品，建议采用 Piper 或类似的本地 TTS 服务，返回 WAV 文件再播放。

6.2 使用系统语音合成或外部程序播放

下面这段程序可以在后台线程中调用系统命令来播放文本。必须强调，这段代码不能在音频线程执行，否则会严重阻塞。

void speakText (const juce::String& text) { #if JUCE_MAC auto escaped = text.replace ("'", "\\'"); juce::ChildProcess process; process.start ("say -v Tingting '" + escaped + "'"); process.waitForProcessToFinish (30000); #elif JUCE_WINDOWS auto escaped = text.replace ("'", "''"); juce::ChildProcess process; process.start ( "powershell.exe -Command \"" "Add-Type -AssemblyName System.Speech; " "(New-Object System.Speech.Synthesis.SpeechSynthesizer).Speak('" + escaped + "')\""); process.waitForProcessToFinish (30000); #endif }

macOS 的-v Tingting是中文普通话语音。如果机器上没有，可以先在终端里执行say -v '?'查看可用语音列表。Windows 需要确认系统已经安装中文语音包。

6.3 播放音频与 DAW 输出的同步方式

直接把系统say的音频播放到系统扬声器，和 DAW 的工程并不完全混合。如果希望 TTS 声音和吉他声音同时从 DAW 输出，更稳的方式是让 TTS 引擎先合成 WAV 文件，然后读取到内存，在processBlock里把 TTS 采样叠加到输出缓冲。

一个简化版本：

void processBlock (juce::AudioBuffer<float>& buffer, juce::MidiBuffer&) override { const auto numSamples = buffer.getNumSamples(); const auto numChannels = buffer.getNumChannels(); int playPosition = ttsPlayPosition; for (int channel = 0; channel < numChannels; ++channel) { auto* writePtr = buffer.getWritePointer (channel); for (int i = 0; i < numSamples; ++i) { if (ttsBuffer.size() > 0) { float ttsSample = ttsBuffer[playPosition % ttsBuffer.size()]; writePtr[i] += ttsSample * ttsVolume; ++playPosition; } } } // 用跨线程原子变量更新 ttsPlayPosition ttsPlayPosition = playPosition; }

这种方案需要在后台线程读取 WAV，使用juce::AudioFormatManager打开文件，再把采样复制到ttsBuffer。核心优势是 TTS 音频作为 DAW 工程的一部分被渲染，可以用宿主自带的录音功能导出最终效果。

7. 运行验证与整链路调试

7.1 最小验证步骤

整个流程最好分成四步验证，避免一次调试多个未知问题。

第一步，验证 LLM 服务：用 curl 请求一次，确认能返回文本。

第二步，验证音高检测：在插件界面加一个 Label，显示最近检测到的音符。不需要接 LLM 也能看到效果。

第三步，验证 LLM 请求：添加一个“测试按钮”，按钮点击后直接发送C4, E4, G4这样的模拟音符给模型，观察返回文本。

第四步，验证 TTS：单独调用speakText，确保系统能发出声音。

四步都通过后，再开启自动检测到 LLM 再到 TTS 的完整链路。这样可以最大程度减少联调时的变量。

7.2 预期输出与日志格式

调试阶段要善用JUCE_LOG或DBG输出。示例日志格式如下：

[GuitarVoice] Detected: C4 (261.63 Hz) [GuitarVoice] Prompt: 你是一位吉他助教。用户弹奏了 C4, E4, G4... [GuitarVoice] LLM response: C 和弦整体很稳定，转换到 G 时提前准备手型。 [GuitarVoice] TTS started [GuitarVoice] TTS finished

在本地 3B 模型上，完整的 LLM 推理时间通常在 1 到 5 秒之间，具体取决于 CPU 和内存。音高检测延迟则在 50 到 200ms 级别。如果 LLM 响应超过 10 秒，需要检查是不是模型太大，或者电脑在运行其他高负载任务。

7.3 用日志和状态面板定位卡点

在 UI 上增加一个状态文本，显示当前阶段：Idle、Listening、Detected、WaitingLLM、TTS。状态切换时同时写日志。这样当用户反馈“没声音”时，可以先看状态停在哪一阶段，再决定检查 LLM、TTS 还是音频回放。

enum class Stage { Idle, Listening, Detected, WaitingLLM, TTS }; void setStage (Stage s) { stage = s; juce::MessageManager::callAsync ([this]() { statusLabel.setText (stageToText (stage), juce::dontSendNotification); }); }

记住，statusLabel.setText必须发生在消息线程，所以要用callAsync。如果在检测线程里直接更新 UI，最典型的表现是程序偶发崩溃或者控件不刷新。

8. 常见问题与排查清单

8.1 插件崩溃或 DAW 卡死

现象：加载插件后 DAW 无响应，或播放几秒后崩溃。

可能原因：

在processBlock中执行了 HTTP 请求或 TTS。
后台线程访问了已经被释放的插件对象。
FIFO 写入越界。

检查方式：

在processBlock中设置断点，看是否进入网络函数。
查看崩溃调用栈，确认是否停在URL::createInputStream或sleep附近。
检查后台线程是否在processor析构后还在运行。

解决方案：把耗时操作全部移到后台线程；在destroyEditor或析构函数中调用detectionThread->stopThread (1000)。

8.2 LLM 请求超时或没有响应

现象：状态停在WaitingLLM，长时间不进入 TTS。

检查方式：

# 确认 Ollama 进程存在 ps aux | grep ollama # 确认接口可用 curl -s http://127.0.0.1:11434/api/tags

如果curl /api/tags正常，但插件请求失败，可能是插件中的 URL 地址拼写错误、请求超时时间太短或 JSON body 格式不对。建议打印queryOllama返回的原始文本，和curl返回值对比。

另一个常见现象是模型第一次请求时冷启动，会等待模型从磁盘加载到内存，可能超过 15 秒。可以在 Ollama 中使用keep_alive参数，让模型在首次请求后保持驻留。

{ "model": "qwen2.5:3b", "prompt": "...", "stream": false, "keep_alive": "5m" }

8.3 音高检测误判

现象：没有演奏时也触发“唱歌”，或弹的 C 被识别成 D。

可能原因：

环境噪声过大，自相关函数把噪声周期当成基频。
吉他失真效果导致信号过饱和。
采样窗口太短，低频信号周期检测不完整。

解决思路：

在检测前加入高通滤波，滤掉 80Hz 以下的交流声和脚步声。
设置置信度阈值，只有归一化自相关分数高于阈值才认为检测到音高。
增大检测样本数，例如从 1024 提升到 2048。
连续多帧得到同一个音名才触发事件，而不是每个采样块都触发。

8.4 TTS 无声音或延迟大

现象：LLM 文本已经出现在日志里，但扬声器没有任何声音。

检查步骤：

单独运行 TTS 命令，确认系统语音可用。
检查 TTS 调用是否发生在后台线程，而不是音频线程。
如果使用系统命令，确认等待时间充足；waitForProcessToFinish超时可以改成 60 秒。
如果输出设备是 DAW 监控，确认 TTS 的音频被叠加到插件输出，而不是单独走系统扬声器。

一个更稳定的方案是把 TTS 从“播放系统命令”改成“先合成 WAV，再通过插件播放”。虽然开发量稍大，但可控性高很多。

9. 最佳实践：从实验原型走向可用插件

9.1 学习版与生产版架构差异

学习版可以把所有逻辑直接写进 JUCE 插件：插件发起 LLM 请求，调用系统 TTS。这样做优点是代码少、调试直观，缺点是不稳定、不可扩展。

生产版应该把 LLM 和 TTS 都抽象成独立服务。插件只负责音频采集、界面状态、缓冲区和播放。模型服务可以单独重启，TTS 可以换成更高质量的引擎，插件不需要重新编译。还要增加缓存和降级策略：当 LLM 请求失败时，使用一组固定规则返回提示文本，保证用户体验不中断。

9.2 线程模型和资源管理

三种线程的职责要分清楚：

线程类型	负责内容
音频线程	读取输入样本、写入 FIFO、叠加 TTS 采样
检测/后台线程	音高检测、LLM 请求、TTS 合成、读取 WAV
消息线程	更新 Label、按钮、Slider 和状态文本

跨线程共享数据时，优先使用AbstractFifo或std::atomic。不要在 UI 线程里等待后台任务结束；不要用Thread::sleep阻塞消息线程。后台线程退出前必须调用stopThread，否则插件卸载时可能访问已经析构的AudioProcessor。

9.3 模型选择与提示词设计

本地模型不是越大越好。对于“弹奏一个音符，生成两句点评”这种任务，3B 模型完全够用。选择模型时优先看量化大小和推理速度，而不是模型总参数量。

Prompt 设计要保持稳定。不要在每次请求时大幅度改变提示词结构。建议把系统提示词放在常量文件或配置项里，便于调整。例如：

SYSTEM_PROMPT = "你是一个吉他助教，只输出两句中文点评。第一句评价演奏，第二句给出练习建议。" USER_PROMPT = "用户弹奏了音符序列：{notes}"

运行时再替换{notes}占位符，比手写拼接更不容易出错。

9.4 可复用检查清单

发布或继续开发前，建议对照下面清单走一遍：

音频回调内没有网络、文件、TTS、锁。
FIFO 和共享状态由无锁结构或原子变量保护。
LLM 请求设置超时，并在失败时给出兜底文本。
TTS 在非实时线程执行，且能取消等待。
UI 更新全部通过MessageManager。
音高检测有置信度阈值，避免乱触发。
日志记录每个阶段耗时和错误信息。
模型、端口、温度、超时时间全部可配置。
插件卸载时后台线程先退出，再释放资源。
LLM 和 TTS 作为独立服务可单独替换。

把这个原型跑通之后，下一步可以做的方向很多：把音高识别换成更准确的多音检测，增加和弦与节奏事件队列，让 LLM 不仅点评演奏，还能根据演奏结果推荐音阶或自动修改效果器参数。无论是做音乐教育工具，还是做舞台互动装置，核心架构都没有变化：音频线程不阻塞，异步处理事件，模型服务可替换，状态可视化。先保证这三个点，再继续叠加功能，会比一开始就把所有逻辑塞进 plugin 更稳妥。