DdMusic 音乐播放器

DdMusic 是一个基于 JavaFX 开发的现代化桌面音乐播放器应用，提供流畅的用户体验和丰富的音乐播放功能。

项目概述

DdMusic 采用模块化设计，通过 JavaFX 框架构建用户界面，支持本地音乐播放、播放列表管理、音量控制等核心功能。项目结构清晰，代码遵循良好的面向对象设计原则，便于维护和扩展。

核心功能

1. 音乐播放控制

• 播放/暂停控制：支持基本的播放和暂停功能
• 上一曲/下一曲：快速切换音乐曲目
• 进度控制：支持拖拽进度条精确控制播放位置
• 音量调节：通过弹出式音量滑块调节播放音量
• 播放状态同步：自动同步播放状态与界面图标

2. 用户界面设计

• 现代化界面：采用扁平化设计风格，界面简洁美观
• 响应式布局：支持窗口大小调整，自动适配不同分辨率
• 菜单导航：左侧导航菜单支持发现音乐、我的音乐等多种分类
• 底部播放控制栏：固定在底部的播放控制区域，方便随时操作

3. 音频处理

• 多媒体支持：基于 JavaFX MediaPlayer 实现音频播放
• 格式兼容：支持主流音频格式（MP3等）
• 资源管理：完善的 MediaPlayer 资源释放机制
• 播放列表：支持音乐列表管理和播放队列控制

技术架构

1. 核心组件

• HomePage：主页面容器，整合各个功能模块
• BottomMusicContainer：底部音乐播放控制栏，包含播放控制、进度条、音量控制等
• HomePageMenuItem：左侧导航菜单项，支持 ToggleGroup 单选机制
• SvgIcon：自定义 SVG 图标组件，支持动态修改图标内容

2. 自定义控件

• RedVerticalSliderSkin：自定义红色垂直滑块皮肤，用于音量控制
• RXMediaProgressBar：媒体进度条，提供直观的播放进度显示
• SvgIcon：支持 SVG 图标的自定义控件，可动态修改图标路径

3. 样式管理

• CSS 样式表：通过外部 CSS 文件管理界面样式
• 主题配色：采用中国红作为主色调，营造音乐播放氛围
• 响应式设计：支持不同屏幕尺寸的自适应布局

项目特色

1. 用户体验优化

• 流畅交互：界面响应迅速，操作流畅自然
• 视觉反馈：提供丰富的视觉反馈，如悬停效果、选中状态等
• 快捷操作：支持鼠标点击、拖拽等多种交互方式

2. 代码质量

• 模块化设计：功能模块分离，代码结构清晰
• 面向对象：遵循面向对象设计原则，便于维护和扩展
• 异常处理：完善的异常处理机制，提高应用稳定性

3. 可扩展性

• 插件化架构：支持功能模块的灵活扩展
• 配置化管理：通过配置文件管理应用参数
• 国际化支持：预留国际化接口，支持多语言扩展

使用说明

系统要求

• Java 17 或更高版本
• 支持 JavaFX 的操作系统（Windows、macOS、Linux）

运行方式

1. 确保系统已安装 Java 运行环境
2. 编译项目源代码
3. 运行 App 主类启动应用程序

功能操作

• 点击左侧菜单项切换不同功能模块
• 使用底部播放控制栏进行音乐播放控制
• 点击音量按钮调节播放音量
• 拖拽进度条控制播放位置

项目结构

src/main/
├── java/com/stickpoint/ddmusic/
│   ├── App.java              # 应用主入口
│   ├── common/               # 通用工具类
│   ├── page/                 # 页面组件
│   │   ├── node/             # UI 组件
│   │   └── skin/             # 自定义皮肤
│   └── utils/                # 工具类
└── resources/
    ├── css/                  # 样式文件
    ├── font/                 # 字体文件
    ├── img/                  # 图片资源
    └── media/                # 音频文件

开发特点

DdMusic 项目展示了现代化 JavaFX 应用开发的最佳实践：

• 采用 MVC 架构模式，分离业务逻辑与界面展示
• 自定义控件和皮肤，实现独特的视觉效果
• 完善的资源管理，避免内存泄漏
• 优雅的异常处理机制，提升用户体验

项目代码规范，注释完整，便于开发者理解和二次开发。通过合理的包结构设计和类职责划分，确保了代码的可维护性和可扩展性。

未来展望

DdMusic 作为一个基础音乐播放器框架，具备良好的扩展性，未来可以增加以下功能：

• 在线音乐播放支持
• 歌词同步显示
• 音效调节功能
• 播放列表自定义
• 主题切换功能

该项目为 JavaFX 桌面应用开发提供了有价值的参考实现。

2026-03-22 优化开发记录（播放内存 + 本地下载页）

1. 问题背景

• 播放音乐时内存从约 220MB 持续上涨到 400~600MB 后长时间不回落，表现出明显的资源滞留。
• 本地下载页面视觉风格与项目整体不一致，交互和观感偏旧，需要在不改功能的前提下现代化重写。

2. 分析与发现

1. 播放链路检查（BottomMusicContainer）

• loadMedia() 每次切歌都会重复调用 bindToMusicState()，导致 MusicState 监听器持续叠加。
• Media 对象存在缓存逻辑，切歌后重型媒体对象可能长期驻留，增加堆内存压力。
• 封面加载通过新建线程处理，频繁切歌时容易产生并发任务堆积。

2. 页面结构检查（LocalDownloadPage）

• 旧页面大量内联样式，结构和视觉分层不清晰。
• 与主站风格（卡片、分区、统一层次）不一致，缺少现代化布局与状态反馈。

3. 修复方案

1. 播放内存治理

• 监听器治理：将 MusicState 绑定改为“只绑定一次”，并在资源释放时显式解绑。
• 媒体对象治理：移除 Media 缓存，切歌时创建新 Media，保证旧 MediaPlayer 可及时回收。
• 绑定治理：在重新绑定进度前先 unbind，防止绑定链残留。
• 异步治理：封面加载改为单线程执行器 + 版本号校验，自动丢弃过期任务。
• 生命周期治理：disposeMediaPlayer() / disposeAll() 增强，统一回收监听器与线程池资源。

2. 本地下载页 UI 重写（功能不变）

• 采用“顶部信息卡 + 分段切换 + 内容卡片”结构重构页面。
• 保留原有功能：
  • 本地音乐面板与下载管理面板切换逻辑不变。
  • 业务数据与操作入口不变。
• 样式外置：新增 css/LocalDownloadPage.css，减少内联样式，提升维护性与一致性。

4. 关键改动文件

• src/main/java/com/stickpoint/ddmusic/page/node/BottomMusicContainer.java
• src/main/java/com/stickpoint/ddmusic/page/node/LocalDownloadPage.java
• src/main/resources/css/LocalDownloadPage.css

5. 验证结果

• 编译验证：mvn "-Dmaven.compiler.release=17" -DskipTests compile 通过。
• 功能验证点：
  • 播放/暂停、切歌、进度拖拽、音量调节可正常使用。
  • 本地音乐/下载管理切页行为保持不变。

6. 开发过程时间线（简版）

1. 读取项目结构并定位播放链路与下载页入口。
2. 复核监听器注册点与媒体对象生命周期，锁定内存上涨主因。
3. 完成播放器资源治理（监听器、Media 生命周期、封面异步队列）。
4. 重写本地下载页容器结构并新增独立样式文件。
5. 编译验证并收敛细节，确认功能保持与风格统一。

7. 备注

• 本次优化重点是“资源生命周期收敛 + UI 风格统一”，未改变业务功能和用户操作路径。
• 后续可结合 VisualVM/JFR 做长时播放压测，对比优化前后曲线（峰值/回落速度/稳定区间）。