音乐英雄 (Music Hero)

一款基于 Web 的音乐节奏游戏，让你通过键盘按键演奏和弦，跟随音乐节奏享受弹奏的乐趣。

✨ 特性

• 🎵 真实音色合成 - 基于 Web Audio API 的吉他音色合成器
• 🎮 多种游戏模式 - 支持自动演奏和手动演奏两种模式
• 🎹 键盘映射 - 使用 Q/W/E/R/T/Y 键演奏不同和弦
• 🎼 调式转换 - 支持将歌曲转换到不同调式
• 📊 实时评分系统 - 准确率、连击数、评级等完整的评分机制
• 🎶 歌词同步 - 歌词与和弦实时同步显示
• ⚙️ 自定义设置 - 可调节 BPM、伴奏、歌词滚动速度等
• 📱 响应式设计 - 适配桌面端和移动端

🚀 快速开始

环境要求

• Node.js 16.x 或更高版本
• pnpm 9.x（推荐）或 npm

安装

# 克隆项目
git clone <repository-url>
cd chord

# 安装依赖（推荐使用 pnpm）
pnpm install
# 或使用 npm
npm install

开发

# 启动开发服务器
pnpm dev
# 或
npm run dev

访问 http://localhost:3000 查看应用。

构建

# 构建生产版本
pnpm build
# 或
npm run build

# 启动生产服务器
pnpm start
# 或
npm run start

代码检查

# 运行 ESLint
pnpm lint
# 或
npm run lint

🎮 游戏玩法

键盘控制

按键	功能	默认和弦
Q	第一个和弦	C
W	第二个和弦	G
E	第三个和弦	Am
R	第四个和弦	F
T	第五个和弦	Em
Y	第六个和弦	Dm

游戏流程

1. 选择歌曲 - 在歌曲库中浏览并选择你喜欢的歌曲
2. 设置参数 - 调整调式、速度、伴奏等游戏设置
3. 开始游戏 - 跟随提示按键演奏和弦
4. 查看结果 - 游戏结束后查看得分、准确率和评级

评分系统

• SSS - 完美演奏（95%+ 准确率）
• SS - 优秀（90-95%）
• S - 良好（85-90%）
• A - 不错（80-85%）
• B - 及格（70-80%）
• C - 需要练习（<70%）

🏗️ 技术架构

技术栈

• 框架: Next.js 14 (App Router)
• UI 库: React 18
• 语言: TypeScript
• 样式: Tailwind CSS 4
• 组件库: shadcn/ui
• 音频: Web Audio API
• 包管理: pnpm

项目结构

chord/
├── app/                    # Next.js App Router
│   ├── page.tsx           # 主应用入口（游戏状态机）
│   ├── layout.tsx         # 根布局
│   └── globals.css        # 全局样式
├── components/            # React 组件
│   ├── ui/               # shadcn/ui 基础组件
│   ├── SongLibrary.tsx   # 歌曲库组件
│   ├── SongSetupScreen.tsx   # 设置界面
│   ├── GameScreen.tsx    # 游戏主界面
│   └── ResultScreen.tsx  # 结果界面
├── lib/                  # 核心逻辑
│   ├── audio.ts         # 音频合成器和管理器
│   ├── songData.ts      # 歌曲数据加载和处理
│   └── utils.ts         # 工具函数
├── hooks/               # 自定义 React Hooks
├── data/                # 歌曲数据
│   ├── songlist01.json  # 歌单列表
│   └── *.json          # 各歌曲详细数据
├── public/              # 静态资源
└── reference/           # 原版实现参考

核心模块

音频系统 (lib/audio.ts)

• ChordSynth - 和弦合成器

  • 支持 10 种基本和弦：C, G, Am, F, Em, D, Dm, Bm, E, A
  • 使用多振荡器 + ADSR 包络模拟真实吉他音色
  • 内置节拍器功能

• AudioManager - 音频上下文管理器（单例模式）

  • 管理全局音频上下文
  • 确保音频在用户交互后初始化

歌曲数据系统 (lib/songData.ts)

• loadSongList() - 加载歌单列表
• loadSongDetail(songId) - 加载歌曲详细数据
• convertSongDetailToGameFormat() - 转换为游戏格式
• transposeSongToKey(song, targetKey) - 调式转换
• generateChordKeyMapping(chords) - 生成键盘映射

游戏状态机 (app/page.tsx)

library → setup → playing → results
   ↑                           ↓
   └───────────────────────────┘

📝 数据格式

歌单列表 (data/songlist01.json)

[
  {
    "id": "song_001",
    "title": "南山南",
    "artist": "马頔",
    "bpm": 80,
    "genre": "民谣",
    "instruments": "吉他",
    "difficulty": "Lv.3",
    "order": 1
  }
]

歌曲详细数据 (data/{songId}.json)

{
  "title": "南山南",
  "artist": "马頔",
  "key": "C",
  "timeSignature": "4/4",
  "tempo": 80,
  "sections": [
    {
      "lineNumber": 1,
      "chords": [
        {
          "position": 1,
          "chord": "C",
          "lyrics": "你在南方的艳阳里",
          "isRest": false,
          "isPreChord": false
        }
      ]
    }
  ],
  "totalBars": 64,
  "totalChords": 120
}

🎵 添加新歌曲

步骤

1. 准备歌曲数据

   • 创建 data/{歌曲名}.json 文件
   • 按照数据格式填写和弦、歌词、时间轴等信息

2. 更新歌单列表

   • 在 data/songlist01.json 中添加歌曲信息

3. 注册歌曲映射

   • 在 lib/songData.ts 的 songFileMap 中添加映射：

   const songFileMap: Record<string, string> = {
     'song_001': '南山南.json',
     'song_002': '你的歌曲.json',  // 新增
   }

支持的和弦

目前支持以下基本和弦及其变体：

• 大调：C, D, E, F, G, A
• 小调：Am, Dm, Em, Bm
• 七和弦：C7, G7, D7, A7, E7
• 其他：sus4, add9 等（会自动简化为基本和弦）

🎨 自定义组件

项目使用 shadcn/ui 组件库，可以轻松添加新组件：

# 添加新的 UI 组件
npx shadcn-ui@latest add [component-name]

# 例如添加对话框组件
npx shadcn-ui@latest add dialog

🔧 配置文件

• next.config.mjs - Next.js 配置
• tailwind.config.ts - Tailwind CSS 配置
• tsconfig.json - TypeScript 配置
• components.json - shadcn/ui 配置

📚 开发指南

代码规范

• 使用 TypeScript 保证类型安全
• 遵循 ESLint 规则
• 使用 @/ 路径别名引用文件
• 组件使用函数式组件 + Hooks
• 使用 cn() 函数合并 Tailwind 类名

音频开发注意事项

• 音频上下文必须在用户交互后初始化
• 使用 AudioManager.getInstance() 获取全局单例
• 参考 reference/music-hero-app (1).html 了解原始实现

提交规范

• 使用清晰的 commit message
• 每次提交确保代码可编译
• 保持增量式开发
• 更新相关文档

🐛 常见问题

Q: 为什么没有声音？

A: 现代浏览器要求音频上下文必须在用户交互（如点击按钮）后才能启动。确保在开始游戏前已初始化音频。

Q: 如何修改键盘映射？

A: 在 lib/songData.ts 的 generateChordKeyMapping() 函数中修改键位映射逻辑。

Q: 支持哪些浏览器？

A: 支持所有现代浏览器（Chrome、Firefox、Safari、Edge 最新版本）。需要支持 Web Audio API。

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📞 联系方式

如有问题或建议，请通过 Issue 联系。

---

享受音乐，享受编程！ 🎵🎸