在音频插件开发中一个比较有挑战的综合场景是让真实乐器输入驱动一个本地语言模型再通过语音合成反馈给演奏者。以吉他为例把拾音器信号接入 JUCE 插件经过音高检测得到当前音符把音符序列构造成提示词交给本机运行的本地 LLM 生成一段演奏点评或对话文本最后通过 TTS 让吉他“开口说话”。这条链路涉及实时音频处理、跨线程通信、HTTP 调用、JSON 解析和音频回放并非用一个库就能解决而是需要在架构层面把不同子系统拼接起来。这篇文章会带着你从零搭一个最小可复现的原型。适合有 JUCE 基础、对本地大模型感兴趣、想在 DAW 生态里做语音交互实验的开发者。学习完你会得到三个结果一个能探测吉他音高并在界面上显示音符的插件一个能按检测结果向本地 LLM 发起请求的后台线程一个把 LLM 文本转成语音并播放的 TTS 通道。整个流程不依赖云端 API数据不离开本机适合做离线音乐教育工具、舞台互动装置或音频玩具。1. 先理解“吉他开口说话”需要哪几层能力1.1 从弹奏到语音反馈的完整数据链路“吉他开口说话”不是一个单一功能而是若干模块按顺序协作。吉他琴弦振动会产生模拟信号经过音频接口变成数字音频进入 DAWDAW 把音频块送给 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/GPU3B 模型约 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 NameGuitarVoice。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_CURL0 )juce_add_plugin里的FORMATS决定最终生成 AU 还是 VST3。IS_SYNTH FALSE保证插件被识别为效果器。JUCE_USE_CURL0这个宏不是必须的但如果你的环境中 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::AudioBufferfloat 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_uniqueDetectionWorker (*this); detectionThread-startThread(); } void processBlock (juce::AudioBufferfloat 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_ptrDetectionWorker 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/generateJUCE 的URL类可以发起 HTTP 请求。下面函数从后台线程调用juce::String queryOllama (const juce::String prompt) { juce::URL url (http://127.0.0.1:11434/api/generate); std::mapjuce::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.8num_predict最大生成 token 数100 - 300top_p核心采样概率0.9repeat_penalty重复惩罚1.1这些参数在curl里也可以直接验证方便先试出满意的效果再写进插件。5.3 解析返回 JSON 并抽取正文Ollama/api/generate在streamfalse时返回的 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 模块需要依赖外部组件。常见方案对比方案优点缺点macOSsay命令无需额外安装中文语音可用平台限定阻塞式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::AudioBufferfloat 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 更稳妥。
