# MusicPlayer

**Repository Path**: KillBugX/music-player

## Basic Information

- **Project Name**: MusicPlayer
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-17
- **Last Updated**: 2026-03-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HarmonyOS 音乐播放器

一款基于 **HarmonyOS NEXT** 开发的原生音乐播放器，支持本地音乐、NAS/WebDAV、百度网盘、阿里云盘、夸克云盘等多种音乐来源，提供类网易云音乐的完整播放体验。

---

## 功能特性

### 核心播放
- AVPlayer 完整状态机封装，支持 MP3 / FLAC / AAC / OGG / WAV / APE
- 顺序播放 / 随机播放 / 单曲循环 / 列表循环
- 播放队列管理（增删改、拖拽排序）
- LRC 歌词解析与同步滚动
- 10 段均衡器 + 音效预设

### 后台与系统集成
- AVSession 后台播放保活
- 锁屏通知栏媒体控制（上一曲 / 暂停 / 下一曲）
- 音频焦点自动处理（来电/通知打断）
- 桌面小组件（播放控制卡片）

### 音乐来源
| 来源 | 协议 | 说明 |
|------|------|------|
| 本地文件 | MediaLibrary API | 自动扫描设备音频文件 |
| NAS / 私有云 | WebDAV | 支持群晖、威联通等 |
| 百度网盘 | OAuth2 + REST API | 官方开放平台 |
| 阿里云盘 | OAuth2 + REST API | 官方开放平台 |
| 夸克网盘 | Web API | 非官方，需评估合规性 |

### 音乐库管理
- 歌曲 / 专辑 / 艺术家三维度视图
- 歌单创建、编辑、删除
- 全局搜索（本地 + 云盘）
- 智能缓存（WiFi 环境自动预缓存）

---

## 技术栈

| 层级 | 技术 |
|------|------|
| 语言 | ArkTS |
| UI 框架 | ArkUI（Stage 模型，声明式） |
| 状态管理 | `@ObservedV2` / `AppStorageV2` / `PersistenceV2` |
| 播放引擎 | `ohos.multimedia.media.AVPlayer` |
| 后台控制 | `ohos.multimedia.avsession` |
| 本地数据库 | `ohos.data.relationalStore`（RDB） |
| 键值存储 | `ohos.data.preferences` |
| 网络请求 | `ohos.net.http` |
| 目标系统 | HarmonyOS NEXT（API 12+） |
| 开发工具 | DevEco Studio 5.x |

---

## 项目结构

```
MusicPlayer/
├── AppScope/                        # 应用级配置
├── entry/
│   └── src/main/
│       ├── module.json5             # 权限 / Ability / 路由配置
│       └── ets/
│           ├── entryability/        # 应用入口（初始化 DB / 播放器）
│           ├── model/               # 数据模型（Song / Playlist / CloudAccount / AppSettings）
│           ├── database/            # RDB 数据库层
│           │   ├── MusicDatabase.ets
│           │   ├── SongDao.ets
│           │   ├── PlaylistDao.ets
│           │   └── CloudAccountDao.ets
│           ├── service/             # 业务服务层
│           │   ├── AVPlayerWrapper.ets   # AVPlayer 状态机封装
│           │   ├── AVSessionManager.ets  # 锁屏 / 通知栏控制
│           │   ├── PlayerService.ets     # 播放队列 / 模式（核心单例）
│           │   ├── LibraryService.ets    # 本地音乐扫描
│           │   └── LyricsService.ets     # 歌词加载 / 同步
│           ├── cloud/               # 云盘驱动层（可扩展）
│           │   ├── ICloudDriver.ets
│           │   ├── WebDAVDriver.ets
│           │   ├── BaiduDiskDriver.ets
│           │   ├── AliDriveDriver.ets
│           │   ├── QuarkDiskDriver.ets
│           │   └── CloudService.ets
│           ├── components/          # 复用 UI 组件
│           │   ├── MiniPlayer.ets   # 底部迷你播放器
│           │   ├── SongItem.ets     # 歌曲列表项
│           │   ├── LyricsView.ets   # 歌词滚动视图
│           │   └── AlbumCover.ets   # 黑胶旋转封面
│           ├── pages/               # 页面
│           │   ├── Index.ets        # 主页（Tab 导航）
│           │   ├── PlayerPage.ets   # 播放详情页
│           │   ├── LibraryPage.ets  # 音乐库
│           │   ├── PlaylistPage.ets # 歌单管理
│           │   ├── CloudPage.ets    # 云盘浏览
│           │   ├── CloudAccountPage.ets # 云盘授权（WebView OAuth）
│           │   ├── SearchPage.ets   # 全局搜索
│           │   ├── EqualizerPage.ets# 均衡器
│           │   └── SettingsPage.ets # 设置
│           ├── utils/               # 工具类（Logger / AudioUtils / LrcParser / CacheManager）
│           └── widget/              # 桌面小组件
├── build-profile.json5
├── hvigorfile.ts
└── oh-package.json5
```

---

## 快速开始

### 环境要求

- **DevEco Studio** 5.x 及以上
- **HarmonyOS SDK** API 12+
- 鸿蒙真机或 API 12+ 模拟器

### 1. 克隆项目

```bash
git clone <repository-url>
cd MusicPlayer
```

### 2. 准备图标资源

在 `entry/src/main/resources/base/media/` 下放置以下图标文件（SVG 转换为鸿蒙支持格式）：

```
ic_home, ic_library_music, ic_cloud, ic_settings
ic_play_circle, ic_pause_circle, ic_skip_previous, ic_skip_next
ic_favorite, ic_shuffle, ic_repeat, ic_repeat_one
ic_music_note, ic_album, ic_person, ic_search
ic_equalizer, ic_folder, ic_audio_file, ic_close
startIcon, layered_image（应用图标）
```

### 3. 配置云盘 API Key

编辑 `entry/src/main/ets/cloud/BaiduDiskDriver.ets`：
```typescript
private readonly CLIENT_ID = 'YOUR_BAIDU_CLIENT_ID';
private readonly CLIENT_SECRET = 'YOUR_BAIDU_CLIENT_SECRET';
```

编辑 `entry/src/main/ets/cloud/AliDriveDriver.ets`：
```typescript
private readonly CLIENT_ID = 'YOUR_ALI_CLIENT_ID';
```

编辑 `entry/src/main/ets/cloud/QuarkDiskDriver.ets`：
```typescript
private readonly CLIENT_ID = 'YOUR_QUARK_CLIENT_ID';
```

### 4. 运行项目

用 DevEco Studio 打开工程目录，连接设备后点击 **Run** 按钮。

---

## 所需权限

| 权限 | 用途 |
|------|------|
| `ohos.permission.READ_MEDIA` | 读取设备媒体文件 |
| `ohos.permission.WRITE_MEDIA` | 写入媒体文件（下载缓存） |
| `ohos.permission.READ_AUDIO` | 扫描本地音频文件 |
| `ohos.permission.INTERNET` | 访问云盘 / NAS |
| `ohos.permission.GET_NETWORK_INFO` | 判断网络状态（WiFi 缓存策略） |
| `ohos.permission.KEEP_BACKGROUND_RUNNING` | 后台播放保活 |
| `ohos.permission.MANAGE_AUDIO_CONFIG` | 均衡器音效控制 |
| `ohos.permission.ACCESS_SERVICE_DM` | 分布式设备管理 |

---

## 开发计划

- [x] 项目架构搭建
- [x] AVPlayer 播放引擎封装
- [x] AVSession 后台播放
- [x] 本地音乐扫描
- [x] RDB 数据库层
- [x] 云盘驱动层（WebDAV / 百度 / 阿里 / 夸克）
- [x] LRC 歌词解析与同步
- [x] 均衡器
- [x] 桌面小组件
- [ ] FFmpeg NAPI 集成（APE/DSD 格式扩展）
- [ ] 分布式流转（手机 → 平板 → TV）
- [ ] 音频频谱可视化
- [ ] 智能播放列表

---

## License

[MIT License](LICENSE)