# RndBeat-android

**Repository Path**: xaek/rnd-beat-android

## Basic Information

- **Project Name**: RndBeat-android
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 随机鼓点 Android（rnd-beat-android）

[rnd-beat-web](https://gitee.com/xaek/rnd-beat-web) 的 Android 完整移植版：Kotlin + Jetpack Compose + Oboe，功能与 Web 版 1:1 对齐。

## 功能特性

- **节奏模式**：整拍模式（仅整拍）、拍内随机模式（每拍 0~3 个均匀分布的拍内点）
- **速度控制**：BPM 数字输入（无功能上下限）+ 滑块（40~200 视觉范围，超出范围时滑块顶格显示）
- **无限循环**：每次生成 4 拍序列，播完自动生成下一组
- **音色区分**：整拍底鼓（Kick）、拍内军鼓（Snare），拍内带轻微随机音高
- **可视化**：红/蓝条形指示灯，当前鼓点高亮跳动（±80ms 窗口）

## 技术选型

| 类别 | 选型 |
| --- | --- |
| 语言 | Kotlin 2.x |
| UI | Jetpack Compose + Material 3 |
| 架构 | 单 Activity + ViewModel + StateFlow |
| 音频 | Oboe + 程序化 PCM 合成 |
| 最低 SDK | 24 (Android 7.0) |
| 目标 SDK | 35 |

详细需求见 [docs/PRD.md](./docs/PRD.md)。

## 快速开始

### 环境要求

- Android Studio Ladybug (2024.2.1) 或更高版本
- JDK 17
- Android SDK 35

### 构建与运行

```bash
git clone https://gitee.com/xaek/rnd-beat-android.git
cd rnd-beat-android

# 推荐使用 Android Studio 打开项目（会自动补全 Gradle Wrapper）
# 命令行构建需先确保 gradle/wrapper/gradle-wrapper.jar 存在：
./gradlew assembleDebug
./gradlew installDebug   # 需连接真机或模拟器
```

在真机上运行以获得最佳音频延迟体验（模拟器可用于 UI 验证）。

## 项目结构

```
rnd-beat-android/
├── app/src/main/kotlin/com/xaek/rndbeat/
│   ├── MainActivity.kt
│   ├── domain/              # BeatGenerator、RhythmMode、DrumHit
│   ├── audio/               # Oboe AudioEngine、DrumSynthesizer
│   ├── playback/            # PlaybackViewModel、BPM 工具
│   └── ui/                  # Compose 界面与可视化
├── app/src/test/            # 单元测试
├── docs/                    # 产品需求文档
└── README.md
```

## 与 Web 版功能对照

| 功能 | Web (rnd-beat-web) | Android (rnd-beat-android) |
| --- | --- | --- |
| 整拍模式 | `beatGenerator.js` | `BeatGenerator.kt` |
| 拍内随机模式 | `beatGenerator.js` | `BeatGenerator.kt` |
| BPM 输入 + 滑块联动 | `main.js` | `RndBeatScreen.kt` + `BpmUtils.kt` |
| 无限 4 拍循环 | `main.js` | `PlaybackViewModel.kt` |
| 底鼓 / 军鼓合成 | Web Audio API | Oboe + `DrumSynthesizer.kt` |
| 红蓝条形高亮 | `visualizer.js` | `BeatVisualizer.kt` |
| 播放中调参下组生效 | `main.js` | `PlaybackViewModel.kt` |
| 停止清空可视化 | `main.js` | `PlaybackViewModel.stopPlayback()` |

## 测试

```bash
./gradlew test
```

单元测试覆盖：

- `BeatGeneratorTest`：模式输出、排序、每拍必有整拍
- `BpmUtilsTest`：无效 BPM 回退 120、滑块 clamp

### 手动验收清单

1. 整拍模式：每拍 1 个红条 + 1 声底鼓
2. 拍内随机：每拍 0~3 蓝条 + 固定红条
3. BPM 滑块 40~200 联动；输入 300 时滑块顶在 200
4. 播放中改 BPM/模式，下一组 4 拍生效
5. 停止后指示灯清空，再开始为新序列
6. 可视化高亮与听觉同步

## 许可证

[MIT](./LICENSE)