# python-MIDI-piano-v2.0

**Repository Path**: YHN282615109/python-midi-piano-v2.0

## Basic Information

- **Project Name**: python-MIDI-piano-v2.0
- **Description**: 一款功能强大的专业级MIDI钢琴模拟软件，支持49键钢琴演奏、系统内录、MIDI/WAV导出，并提供简谱显示功能。无论是音乐学习、创作还是娱乐，都能满足您的需求。
- **Primary Language**: Python
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: https://gitee.com/YHN282615109/python-midi-piano-v2.0
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-01
- **Last Updated**: 2026-08-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: MIDI钢琴

## README



# 🎹 MIDI钢琴 V2.0

[![Version](https://img.shields.io/badge/version-2.0.0-blue.svg)](https://github.com/YHN282615109)
[![Python](https://img.shields.io/badge/python-3.7+-green.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)

一款功能强大的专业级MIDI钢琴模拟软件，支持49键钢琴演奏、系统内录、MIDI/WAV导出，并提供简谱显示功能。无论是音乐学习、创作还是娱乐，都能满足您的需求。

---

## ✨ 核心亮点

- 🎹 **49键专业钢琴**（C2-B5，3个完整八度）
- 🎙️ **双模式录音**（系统内录 + 麦克风录音）
- 📀 **多格式导出**（MIDI文件 + WAV音频）
- 🎵 **128种GM音色**（完整乐器库）
- 🔢 **智能简谱显示**（自动标注音高）
- 🔊 **最大音量输出**（MIDI力度127 + WAV 3倍增益）
- ⌨️ **全键盘映射**（支持F5-F8录音快捷键）

---

## 📸 界面预览

> 💡 *主界面预览：49键钢琴布局、简谱显示、录音控制面板*

---

## 🚀 快速开始

### 系统要求

- Windows 7/10/11 | macOS | Linux
- Python 3.7 或更高版本

### 安装步骤

#### 1. 克隆或下载项目

```bash
git clone https://github.com/YHN282615109/midi-piano.git
cd midi-piano
```

#### 2. 安装依赖

```bash
pip install pygame pillow soundcard soundfile numpy
# 可选（增强录音兼容性）
pip install pyaudio mido
```

#### 3. 运行程序

```bash
python midi_piano_v2.py
```

> **首次运行提示**：如遇到MIDI设备错误，请安装 [VirtualMIDISynth](https://coolsoft.altervista.org/en/virtualmidisynth)

---

## 🎮 使用指南

### 演奏方式

| 方式 | 说明 |
|------|------|
| 🖱️ **鼠标点击** | 直接点击琴键演奏，有3D动画效果 |
| ⌨️ **键盘映射** | 使用电脑键盘演奏（见下方映射表） |

### 键盘映射表（简谱版）

#### 低音区（C2-B2）
| 按键 | 音名 | 简谱 |
|------|------|------|
| Z | C2 | 1· |
| X | C#2 | 1#· |
| C | D2 | 2· |
| V | D#2 | 2#· |
| B | E2 | 3· |
| N | F2 | 4· |
| M | F#2 | 4#· |
| , | G2 | 5· |
| . | G#2 | 5#· |
| / | A2 | 6· |

#### 中音区（C3-B3）
| 按键 | 音名 | 简谱 |
|------|------|------|
| A | C3 | 1 |
| W | C#3 | 1# |
| S | D3 | 2 |
| E | D#3 | 2# |
| D | E3 | 3 |
| F | F3 | 4 |
| T | F#3 | 4# |
| G | G3 | 5 |
| Y | G#3 | 5# |
| H | A3 | 6 |
| U | A#3 | 6# |
| J | B3 | 7 |

#### 高音区（C4-B4）
| 按键 | 音名 | 简谱 |
|------|------|------|
| K | C4 | 1' |
| O | C#4 | 1#' |
| L | D4 | 2' |
| P | D#4 | 2#' |
| ; | E4 | 3' |
| ' | F4 | 4' |
| ] | F#4 | 4#' |
| \ | G4 | 5' |

### 录音功能

| 快捷键 | 功能 | 说明 |
|--------|------|------|
| **F5** | 开始录音 | 开始录制演奏和音频 |
| **F6** | 停止录音 | 结束录音并保存数据 |
| **F7** | 暂停录音 | 临时暂停录音 |
| **F8** | 恢复录音 | 继续录音 |

**录音类型**：
- 🎧 **系统内录**：录制电脑播放的声音（需启用立体声混音）
- 🎤 **麦克风录音**：录制麦克风输入的声音

### 导出功能

通过 **文件** 菜单：
- 📁 **导出MIDI文件**：保存音符序列（最大力度）
- 🔊 **导出WAV文件**：保存音频录音（自动3倍增益）

### 音色切换

- 从下拉菜单选择128种GM音色
- 数字键 **0-9** 快速切换音色组（每组13种音色）

---

## 📁 项目结构

```
midi-piano/
├── midi_piano_v2.py          # 主程序
├── 微信收款码.png             # 捐赠二维码（可选）
├── 支付宝收款码.jpg           # 捐赠二维码（可选）
├── requirements.txt          # Python依赖列表
├── README.md                 # 项目说明文档
└── LICENSE                   # 开源协议
```

---

## 🛠️ 技术架构

| 模块 | 技术选型 | 用途 |
|------|----------|------|
| GUI框架 | Tkinter | 界面绘制与交互 |
| MIDI输出 | Pygame.midi | 音符播放与控制 |
| 音频录音 | SoundCard / PyAudio | 系统内录/麦克风录音 |
| MIDI导出 | Mido / 自定义 | 保存MIDI文件 |
| WAV导出 | SoundFile + NumPy | 保存音频文件 |
| 图像处理 | Pillow | 二维码显示 |

---

## 📊 版本对比

| 功能 | V1.0 | V2.0 |
|------|------|------|
| 琴键数量 | 30键 | **49键（3个八度）** |
| 简谱显示 | ❌ | ✅ |
| 录音功能 | ❌ | ✅（双模式） |
| MIDI导出 | ❌ | ✅ |
| WAV导出 | ❌ | ✅ |
| 录音暂停/恢复 | ❌ | ✅ |
| 3D琴键效果 | 基础 | **增强版** |
| 音量输出 | 可调 | **最大化（127）** |

---

## ❓ 常见问题

### Q1: 没有声音怎么办？

**A:** 请检查：
1. 是否安装了MIDI驱动（推荐VirtualMIDISynth）
2. MIDI设备是否在"设置/选项"中正确选择
3. 系统音量是否开启

### Q2: WAV导出没有声音？

**A:** 请确保：
1. 录音时选择了正确的设备
2. 系统内录需启用"立体声混音"
   - Windows：声音控制面板 → 录制 → 启用立体声混音
3. 录音过程中有声音输入

### Q3: 简谱显示乱码？

**A:** 程序使用Unicode组合字符，现代操作系统均支持。如显示异常，请更新系统字体。

### Q4: 如何获得更好音质？

**A:** 
1. 安装VirtualMIDISynth
2. 下载高质量SoundFont（如FluidR3、GeneralUserGS）
3. 在VirtualMIDISynth中加载SoundFont

---

## 📝 更新日志

### V2.0.0（2026-05-25）

#### 🎉 新增功能
- ✨ 琴键扩展至49键（C2-B5，3个完整八度）
- ✨ 完整录音功能（支持MIDI/WAV导出）
- ✨ 系统内录 + 麦克风录音双模式
- ✨ 录音暂停/恢复功能
- ✨ 琴键简谱数字显示
- ✨ 3D琴键增强动画

#### 🔊 音量优化
- 钢琴演奏音量最大化（力度127）
- MIDI导出使用最大力度
- WAV导出3倍音量增益 + 自动归一化

#### 🐛 问题修复
- 修复WAV导出无声问题
- 优化音频录音稳定性

---

### V1.0.0（2026-05-23）
- 首次正式发布
- 30键钢琴键盘
- 128种GM音色
- 鼠标/键盘双重演奏

---

## 👨‍💻 开发者信息

- **作者**：叶海宁
- **邮箱**：791687349@qq.com
- **微信**：17876586815
- **QQ**：791687349 / 282615109
- **GitHub**：[YHN282615109](https://github.com/YHN282615109)
- **Gitee**：[YHN282615109](https://gitee.com/YHN282615109)
- **CSDN博客**：[点击访问](https://blog.csdn.net/qq_32257509)

---

## 💝 支持项目

如果您喜欢这个项目，欢迎通过以下方式支持：

1. ⭐ **Star项目** - 在GitHub上给我们一个Star
2. 🐛 **反馈问题** - 提交Issue帮助我们改进
3. 💰 **捐赠赞助** - 通过微信/支付宝支持开发

> 将 `微信收款码.png` 和 `支付宝收款码.jpg` 放入程序目录，即可在"捐赠/赞助"菜单中显示二维码。

---

## 📄 开源协议

本项目采用 **MIT License + 附加条款**：

- ✅ 个人免费使用、学习、修改
- ✅ 保留版权信息即可二次开发
- ❌ 禁止商业用途
- ❌ 禁止倒卖或冒充原创

详见 [LICENSE](LICENSE) 文件。

---

## 📞 联系与交流

- **意见反馈**：GitHub Issues 或发送邮件
- **交流群**：添加微信 `17876586815` 备注"MIDI钢琴"
- **技术支持**：优先通过GitHub Issues处理

---

## 🙏 致谢

感谢所有使用和支持本项目的朋友！  
感谢以下开源项目：Pygame、SoundCard、PyAudio、Mido、NumPy、Pillow

---

<p align="center">
  <b>🎹 让音乐更简单，让创作更自由 🎵</b><br>
  <sub>Made with ❤️ by Ye Haining</sub>
</p>
```

---