# 張多少的鍵盤

**Repository Path**: FlowerCN/MoLKeyboard

## Basic Information

- **Project Name**: 張多少的鍵盤
- **Description**: 为小朋友设计的可演奏音乐键盘，让每一次按键都成为探索音乐的开始。
A playable musical keyboard designed for children, turning every keypress into an exploration of music.
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-09-14
- **Last Updated**: 2026-03-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MoL Keyboard

**为小朋友设计的可演奏音乐键盘，让每一次按键都成为探索音乐的开始。**  
*A playable musical keyboard designed for children, turning every keypress into an exploration of music.*

## 背景故事 / Background Story

這個項目起源於一個很簡單的想法。張多少 27 個月大時，想要一把新的鍵盤。作為爸爸，我覺得它不應該只是用來亂按，也可以成為音樂和互動的起點。當時我很快完成了框架設計和技術選型，只是一直因工作繁忙未能做完。直到最近，藉助 AI coding 工具，才終於把它實現並開源。

---

This project began with a simple idea. When MoreOrLess Zhang was 27 months old, he wanted a new keyboard. As his father, I felt that it should be more than something to press randomly — it could also become a starting point for music and interaction. I finished the framework design and technical planning early on, but work kept me from completing it. Only recently, with the help of AI coding tools, was I finally able to build and open-source it.

## ✨ 特性 / Features

### 🎵 乐器音色 / Instruments (18种)
- **钢琴类 / Piano**: 大钢琴 Grand Piano、电钢琴 Electric Piano、羽管键琴 Harpsichord
- **风琴类 / Organ**: 教堂风琴 Church Organ、爵士风琴 Jazz Organ
- **吉他类 / Guitar**: 尼龙弦吉他 Nylon Guitar、钢弦吉他 Steel Guitar
- **弦乐类 / Strings**: 小提琴 Violin、大提琴 Cello
- **管乐类 / Winds**: 长笛 Flute、单簧管 Clarinet
- **合成器 / Synth**: 合成主音 Synth Lead、合成铺底 Synth Pad、合成贝斯 Synth Bass
- **特色乐器 / Others**: 合唱 Choir、颤音琴 Vibraphone、竖琴 Harp、音乐盒 Music Box

### 🎛️ 实时效果 / Real-time Effects
- **混响 / Reverb** - 空间感模拟
- **合唱 / Chorus** - 声音加厚
- **延迟 / Delay** - 回声效果

### 🎹 演奏功能 / Performance Features
- **琶音器 / Arpeggiator** - 自动琶音演奏
- **延音踏板 / Sustain Pedal** - 模拟钢琴踏板
- **滑音 / Portamento** - 音符间平滑过渡
- **录音/回放 / Recording** - 录制和播放演奏
- **节拍器 / Metronome** - 节奏练习
- **和弦模式 / Chord Mode** - 一键演奏完整和弦

### ⌨️ 键盘布局 / Keyboard Layout
- **30键 / 30 Keys** 覆盖 C4-F6 (2.5八度)
- 支持黑键（半音）/ Black keys (semitones)
- 实时八度切换 (±3) / Real-time octave shift

## 🚀 快速开始 / Quick Start

### 1. 安装依赖 / Install Dependencies

**Ubuntu/Debian/Raspberry Pi:**
```bash
sudo apt-get install -y build-essential cmake libsdl2-dev
```

**macOS:**
```bash
brew install cmake sdl2
```

**Windows (MSYS2):**
```bash
pacman -S mingw-w64-x86_64-cmake mingw-w64-x86_64-SDL2
```

### 2. 构建 / Build

```bash
./build.sh
```

### 3. 运行 / Run

**无头模式（推荐）/ Headless mode (recommended):**
```bash
./build/molkeyboard --headless
```

## 🍓 树莓派 + 蓝牙音箱 / Raspberry Pi + Bluetooth

1. **配对蓝牙音箱 / Pair Bluetooth speaker:**
```bash
bluetoothctl
[bluetooth]# scan on
[bluetooth]# pair XX:XX:XX:XX:XX:XX
[bluetooth]# trust XX:XX:XX:XX:XX:XX
[bluetooth]# connect XX:XX:XX:XX:XX:XX
```

2. **设置默认音频输出 / Set default audio:**
```bash
pactl set-default-sink <蓝牙音箱名称>
```

3. **运行 / Run:**
```bash
./build/molkeyboard --headless
```

## 🎮 使用指南 / Usage Guide

### 键盘布局 / Keyboard Layout

```
上排 (C5-F6) / Upper row:
┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐
│ 1 │ 2 │ 3 │   │ 5 │ 6 │ 7 │   │ 9 │ 0 │  ← 黑键 Black keys
└───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘
┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐
│ Q │ W │ E │ R │ T │ Y │ U │ I │ O │ P │  ← 白键 White keys
└───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘

下排 (C4-E5) / Lower row:
    ┌───┬───┐   ┌───┬───┬───┐   ┌───┬───┐
    │ S │ D │   │ G │ H │ J │   │ L │ ; │  ← 黑键 Black keys
    └───┴───┘   └───┴───┴───┘   └───┴───┘
┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐
│ Z │ X │ C │ V │ B │ N │ M │ , │ . │ / │  ← 白键 White keys
└───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘
```

### 控制键 / Controls

| 按键 / Key | 功能 / Function |
|-----------|----------------|
| `[` / `]` | 上一个/下一个乐器 / Prev/Next instrument |
| `P` | 切换预设 / Cycle preset |
| `<` / `>` | 八度减/加 / Octave down/up |
| `-` / `=` | 音量减/加 / Volume down/up |
| `←` / `→` | 调整效果器 / Adjust effect |
| `Tab` | 切换效果器类型 / Cycle effect type |
| `` ` `` | 开关效果器 / Toggle effect |
| `Space` | 紧急停止 / Panic (all notes off) |
| `Enter` | 延音踏板 / Sustain pedal |
| `\` | 滑音 / Portamento |
| `A` | 切换演奏模式 / Toggle play mode |
| `C` | 切换和弦类型 (和弦模式) / Cycle chord type |
| `M` | 开关节拍器 / Toggle metronome |
| `↑` / `↓` | 调整BPM / Adjust BPM |
| `F5` | 开始/停止录音 / Start/Stop recording |
| `F6` | 播放/停止回放 / Play/Stop playback |
| `Esc` | 退出 / Quit |

## 📁 项目结构 / Project Structure

```
MoLKeyboard/
├── src/
│   ├── main.cpp              # 程序入口 Entry point
│   ├── app.cpp/h             # 应用逻辑 Application logic
│   ├── audio_engine.cpp/h    # 音频引擎 Audio engine
│   ├── synthesizer.cpp/h     # 合成器 Synthesizer
│   ├── metronome.cpp/h       # 节拍器 Metronome
│   ├── chord_library.cpp/h   # 和弦库 Chord library
│   ├── preset_manager.cpp/h  # 预设管理 Preset manager
│   └── note.h                # 音符定义 Note definitions
├── CMakeLists.txt            # CMake配置
├── build.sh                  # 构建脚本
└── README.md                 # 本文件
```

## 🌐 跨平台支持 / Cross-Platform

- ✅ Linux (x64, ARM)
- ✅ macOS (Intel/Apple Silicon)
- ✅ Windows (MSYS2/MinGW)
- ✅ Raspberry Pi (所有型号 / all models)

## 📜 许可证 / License

MIT License - 详见 [LICENSE](LICENSE)  
Copyright (c) 2026 Peixuan Zhang

## 🤝 贡献 / Contributing

欢迎贡献！请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)  
Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md)

## 📞 支持 / Support

遇到问题？查看 [SUPPORT.md](SUPPORT.md) 或提交 Issue  
Need help? See [SUPPORT.md](SUPPORT.md) or open an issue.