# QMusic

**Repository Path**: KillBugX/qmusic

## Basic Information

- **Project Name**: QMusic
- **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

# 鸿蒙音乐播放器 (Harmony Music Player)

一款基于 HarmonyOS NEXT 的高品质音乐播放应用，支持本地音乐、NAS 远程播放、网盘集成等功能。

## 技术栈

- **操作系统**: HarmonyOS NEXT
- **开发语言**: ArkTS
- **架构模型**: Stage 模型
- **SDK API**: API 12+
- **IDE**: DevEco Studio 5.0+

## 功能特性

### 已实现功能

✅ **核心播放功能**
- AVPlayer 音频播放引擎封装
- 播放/暂停、上一曲/下一曲
- 进度控制与跳转
- 播放模式切换（顺序/随机/单曲）
- 后台播放支持
- 锁屏控制（AVSession）

✅ **音乐管理**
- 本地音乐扫描与管理
- 歌曲元数据解析
- 播放列表管理
- 收藏功能
- 播放历史记录
- 搜索功能

✅ **数据存储**
- RDB 关系型数据库（歌曲库、播放列表等）
- Preferences 轻量存储（配置、播放进度等）

✅ **UI 界面**
- 首页（推荐/最近播放/收藏）
- 播放页面（封面、控制按钮、进度条）
- 播放列表页面
- 搜索页面
- 本地音乐页面
- 网盘页面
- 设置页面

### 待实现功能

🔲 **网络音源**
- SMB/NFS协议支持（需要 NAPI 实现）
- DLNA设备发现与播放
- 百度网盘 API 接入
- 阿里云盘 API 接入
- 夸克云盘 API 接入

🔲 **高级功能**
- 音频均衡器（EQ）
- 歌词显示与同步
- 音乐下载管理
- 分布式音频投送
- 多设备协同播放

## 项目结构

```
entry/src/main/ets/
├── entryability/          # 应用入口
│   └── EntryAbility.ts
├── common/                # 公共模块
│   ├── di/               # 依赖注入
│   │   └── DependencyInjection.ts
│   ├── preferences/      # 偏好设置
│   │   └── PlayerPreferences.ts
│   ├── Constants.ts      # 常量定义
│   ├── EventBus.ts       # 事件总线
│   └── Utils.ts          # 工具函数
├── models/               # 数据模型
│   ├── Song.ts          # 歌曲
│   ├── Playlist.ts      # 播放列表
│   ├── Album.ts         # 专辑
│   └── Artist.ts        # 歌手
├── repositories/         # 数据仓库
│   ├── MusicRepository.ts
│   └── LocalMusicRepository.ts
├── services/            # 服务层
│   ├── PlaybackService.ts      # 播放服务
│   └── AVSessionManager.ts     # 媒体会话管理
├── viewmodels/          # 视图模型
│   └── PlayerViewModel.ts
├── database/            # 数据库
│   └── DatabaseHelper.ts
├── navigation/          # 路由导航
│   └── Router.ts
├── pages/              # 页面
│   ├── Index.ets       # 首页
│   ├── PlayerPage.ets  # 播放页
│   ├── PlaylistPage.ets # 播放列表页
│   ├── SearchPage.ets  # 搜索页
│   ├── SettingsPage.ts # 设置页
│   ├── LocalMusicPage.ets # 本地音乐页
│   ├── CloudDrivePage.ets # 网盘页
│   ├── ArtistPage.ets  # 歌手页
│   └── AlbumPage.ets   # 专辑页
└── resources/          # 资源文件
    └── base/
        ├── element/    # 元素资源
        ├── media/      # 媒体资源
        └── profile/    # 配置文件
```

## 架构设计

采用分层架构设计：

```
UI Layer (Pages & Components)
    ↓
ViewModel Layer (PlayerViewModel)
    ↓
Service Layer (PlaybackService, AVSessionManager)
    ↓
Repository Layer (MusicRepository, LocalMusicRepository)
    ↓
Data Source Layer (RDB, Preferences, File System)
```

## 快速开始

### 环境要求

- DevEco Studio 5.0+
- HarmonyOS SDK API 12+
- Node.js 14+

### 运行步骤

1. **克隆项目**
   ```bash
   git clone <repository-url>
   cd QMusic
   ```

2. **安装依赖**
   ```bash
   ohpm install
   ```

3. **配置签名**
   - 在 DevEco Studio 中配置自动签名或手动签名证书

4. **运行应用**
   - 连接鸿蒙设备或启动模拟器
   - 点击 Run 按钮运行应用

## 权限说明

应用需要以下权限：

- `ohos.permission.READ_MEDIA`: 读取本地音乐文件
- `ohos.permission.INTERNET`: 访问在线音乐资源
- `ohos.permission.KEEP_BACKGROUND_RUNNING`: 后台播放音乐

## 开发计划

### 第一阶段（已完成）
- ✅ 项目基础框架搭建
- ✅ 播放引擎封装
- ✅ 数据库和存储
- ✅ 基础 UI 页面

### 第二阶段（进行中）
- 🔲 完善 UI 组件和交互
- 🔲 实现完整的 ID3 标签解析
- 🔲 优化播放性能

### 第三阶段（待开发）
- 🔲 NAS 远程播放（SMB/DLNA/NFS）
- 🔲 网盘 API 接入
- 🔲 歌词显示
- 🔲 均衡器

### 第四阶段（待开发）
- 🔲 分布式能力
- 🔲 下载管理
- 🔲 测试和优化
- 🔲 上架发布

## 注意事项

1. **资源文件**: 项目中的图片资源（如 `$r('app.media.ic_play')`）需要在 DevEco Studio 中添加实际的图片文件

2. **NAPI 开发**: SMB/NFS协议支持需要通过 NAPI 调用 C++ 库实现

3. **网盘 API**: 各网盘的 API 可能需要企业认证或存在使用限制

4. **真机测试**: 部分功能（如后台播放、锁屏控制）需要在真机上测试

## 许可证

Apache License 2.0

## 贡献

欢迎提交 Issue 和 Pull Request！

---

**注意**: 这是一个开发中的项目，部分功能尚未完成。请在实际使用前仔细测试。