صفحهٔ اصلی گشت‌و‌گذار راهنما
ورود
onecold
/
TTMusic
1
0
انشعاب 0
پرونده‌ها مشکلات 0 درخواست واکشی 0 ویکی
درخت: 202b94e054
شاخه‌ها تگ‌ها
TTMusic
/
开发者文档.md

开发者文档.md 3.9 KB
تاريخچه خام

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

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