TTMusic/开发者文档.md

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 参与代码共建。
• 代码风格建议遵循现有结构，注释清晰，命名规范。
• 重要变更请先与维护者沟通。

---

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