🎵 Keyonica

Key + Harmonica = Keyonica — 用键盘演奏口琴，让音乐触手可及！

一款基于 Rust 开发的口琴模拟器，支持键盘实时演奏、和弦演奏、移调功能，并内置自动演示曲目。无论你是音乐爱好者还是编程学习者，都能在这里找到乐趣！

✨ 特性亮点

• 🎹 三排键盘布局 - 覆盖低音、中音、高音三个八度，26个音符任你弹奏
• 🎸 多模式真实音色 - 支持复音、蓝调、半音阶等多种专业口琴音色模拟
• 🎶 演奏 - 同时按下多键演奏和弦，体验口琴魅力
• 🎼 移调功能 - 支持 ±12 半音移调，轻松切换调性
• 🤖 演示模式 - 内置《小星星》《两只老虎》等经典曲目自动演奏
• 🖥️ 跨平台 - Windows、macOS、Linux 全平台支持

🎮 快速开始

编译运行

# 克隆项目后进入目录
cd keyonica

# 编译并运行
cargo run --release

🎹 键位映射

键盘分为三排，对应口琴的三个音区：

第一排 (低音 + 中音)

按键	Q	W	E	R	T	Y	U	I	O	P
唱名	1.	2.	3.	4.	5.	6.	7.	1	2	3
音区	低	低	低	低	低	低	低	中	中	中

第二排 (中音 + 高音)

按键	A	S	D	F	G	H	J	K	L
唱名	1	2	3	4	5	6	7	1'	2'
音区	中	中	中	中	中	中	中	高	高

第三排 (高音)

按键	Z	X	C	V	B	N	M
唱名	1'	2'	3'	4'	5'	6'	7'
音区	高	高	高	高	高	高	高

💡 提示：第二排 A-J 与第一排 I-P 部分重叠，方便不同指法习惯

⌨️ 快捷键

按键	功能
Space	开始/停止 演示播放
← →	切换演示曲目
↑	升调 (+1 半音)
↓	降调 (-1 半音)
Esc	重置为原调

🏗️ 技术架构

keyonica/
├── src/
│   ├── main.rs        # 主程序入口 & UI 界面
│   ├── constants.rs   # 音符频率常量 & 键位映射
│   ├── envelope.rs    # ADSR 包络 & 口琴音色合成
│   └── demo.rs        # 演示曲目数据
├── fonts/
│   └── SimSun.ttf     # 中文字体（编译时嵌入）
└── Cargo.toml         # 项目配置

核心设计

1. 音频引擎

• 基于 rodio 实现低延迟音频播放
• 每个按键独立 Sink，支持真正的演奏
• 采用 mixer 混音，多音同时播放无冲突

2. ADSR 包络

音量
  ^
1 |    /\
  |   /  \____
  |  /        \
0 |_/          \___
  +--A--D--S----R--> 时间

• Attack (30ms): 柔和起音，避免爆破音
• Decay (80ms): 自然衰减
• Sustain (60%): 持续按住时的音量
• Release (150ms): 松开后平滑消音

3. 口琴音色合成 (多模式支持)

Keyonica 不仅仅是简单的正弦波叠加，它根据声学物理特征模拟了三种经典口琴的音色：

• 🎵 标准模式 (Standard)：

  • 经典合成算法：基频 + 2次泛音×0.3 + 3次泛音×0.2 + 4次泛音×0.1 + 5次泛音×0.05。
  • 平衡且通用的口琴音色。

• 🎼 复音口琴 (Tremolo)：

  • 声学特征：典型的东方口琴，每个音符由两个簧片同时发声，频率有微小差异，产生“颤音”拍频效果。
  • 核心算法：双振荡器干涉模型。叠加两个频率相差 10 音分 (Cents) 的正弦波，产生物理拍频。

• 🎸 蓝调口琴 (Blues / Diatonic)：

  • 声学特征：音色粗犷、干脆，富含中频能量，常伴随演奏时的过载感。
  • 核心算法：频谱塑形 + 饱和度失真。大幅增强 3次/5次 奇次泛音模拟闭管特性，并引入 Tanh (双曲正切) 软剪切模拟簧片过载。

• 🎷 半音阶口琴 (Chromatic)：

  • 声学特征：音色圆润厚重，起音时有明显的防漏气膜片 (Windsaver) 震动声。
  • 核心算法：瞬态噪声 + 低通滤波。在起音前 40ms 叠加一段线形衰减的白噪声模拟防漏气膜片（Windsaver）的震动声。 基频为主，但保留丰富的偶次泛音以增加厚度，以及适量的奇次泛音以模拟金属簧片质感，避免音色过于单薄。

4. 移调算法

基于十二平均律，每个半音频率比为 2^(1/12)：

实际频率 = 基准频率 × 2^(移调半音数/12)

🎼 内置曲目

曲目	描述
音阶测试	中音区上下行音阶
小星星	经典儿歌完整版
两只老虎	欢快的童谣旋律

🎵 按 Space 开始自动演奏，观看按键高亮跟随音乐跳动！

📦 依赖说明

依赖	版本	用途
eframe	0.33	GUI 框架 (egui)
rodio	0.21	音频播放

🤝 贡献

欢迎提交 Issue 和 Pull Request！

---

🎵 用代码奏响音乐，用键盘演绎旋律 🎵