# TTMusic 开发者文档

## 1. 项目简介
TTMusic 是基于 OpenHarmony（鸿蒙）平台开发的本地音乐播放器，支持本地音频文件的管理、播放、歌单、歌词、封面、批量操作等功能。适配多种鸿蒙设备，代码结构清晰，易于二次开发和功能扩展。

## 2. 环境准备
- 操作系统：Windows、Linux 或 macOS
- 开发工具：DevEco Studio（建议 4.0 及以上版本）
- **OpenHarmony SDK：API 12（5.0.0(12)）及以上**
  - 说明：本项目在 `build-profile.json5` 文件的 `compatibleSdkVersion` 字段中声明了所需 API 版本号为 `5.0.0(12)`，即 API 12。
- 设备：支持鸿蒙系统的真机或模拟器
- Node.js（部分脚本依赖）

## 3. 主要目录与代码结构说明
```
TTMusic/
├── entry/                  # 主工程目录
│   ├── src/main/ets/      # 主要业务代码
│   │   ├── view/          # 主要UI与音乐播放逻辑（如 LocalMusic.ets）
│   │   ├── viewmodel/     # 数据模型与业务逻辑
│   │   ├── common/        # 常量、工具类
│   │   ├── controller/    # 控制器
│   │   ├── resources/     # 资源文件（图片、音频、布局等）
│   ├── oh_modules/        # 三方依赖
├── ijkplayer/             # 播放器内核及native模块
├── lib/                   # 公共库
├── doc/                   # 相关文档
├── README.md              # 简要说明
├── README_zh.md           # 中文说明
├── 开发者文档.md          # 开发者文档（本文件）
```

## 4. 核心模块与功能说明
- **LocalMusic.ets**：音乐播放器主界面，负责本地音频文件的浏览、播放、歌单管理、批量操作等。
- **viewmodel/**：如 `VideoItem`、`MainViewModel`，负责数据结构和业务逻辑。
- **controller/**：如 `AvSessionController`，负责音频会话、播放控制等。
- **common/**：常量、工具类、通用方法。
- **ijkplayer/**：播放器内核，基于 FFmpeg，支持多种音频格式。
- **oh_modules/**：三方依赖库，如歌词、弹窗、广告等。

### 主要功能点
- 本地音频扫描与导入（支持自动、手动、批量）
- 歌单管理、收藏、最近播放、历史记录
- 歌词同步显示、歌词导入
- 音乐封面自动提取与自定义
- 艺术家、专辑、媒体库分组浏览
- 批量操作（剪切、复制、删除、重命名）
- 支持倍速播放、音频焦点、循环播放

## 5. 如何本地调试与运行
1. 使用 DevEco Studio 打开项目根目录。
2. 配置好 OpenHarmony SDK，**API 版本需为 12（5.0.0(12)）及以上**。
3. 连接鸿蒙真机或启动模拟器。
4. 点击"运行"按钮，选择目标设备，编译并安装应用。
5. 首次启动会自动扫描 Download 目录下的音频文件。
6. 可在 UI 上进行导入、播放、歌单管理等操作。

## 6. 常见开发问题与建议
- **依赖缺失/编译报错**：请确认 SDK、ohpm 依赖已正确安装，必要时重新同步依赖。
- **真机调试无响应**：请检查设备已解锁、连接正常，且已允许安装调试应用。
- **音频无法播放**：请确认音频格式受支持，或查看日志排查 IjkMediaPlayer 初始化问题。
- **歌词/封面不显示**：请确保歌词文件与音频同名同目录，封面图片格式受支持。
- **批量操作异常**：建议先单独测试单个文件操作，排查路径、权限等问题。
- **UI适配问题**：本项目已适配多种屏幕，若需自定义可参考 BreakpointSystem 相关代码。

## 7. 参与贡献方式
- 欢迎通过 Issue 反馈 bug 或建议。
- 欢迎提交 Pull Request 参与代码共建。
- 代码风格建议遵循现有结构，注释清晰，命名规范。
- 重要变更请先与维护者沟通。

---
如有更多问题，欢迎查阅源码或联系维护者。祝开发愉快！