# 音乐播放器

**Repository Path**: deepin20/localmusic

## Basic Information

- **Project Name**: 音乐播放器
- **Description**: 音乐播放器 (LocalMusic)：基于 **C++17 + Qt5 + DTK5** 开发的本地音乐播放器，适配**统信 UOS 20 桌面专业版**（eagle）。
开发者士无双的LocalMusic仓库：https://gitee.com/shiwushuang9/localmusic/
- **Primary Language**: C++
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-10
- **Last Updated**: 2026-09-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🎵 音乐播放器 (LocalMusic)

基于 **C++17 + Qt5 + DTK5** 开发的本地音乐播放器，适配**统信 UOS 20 桌面专业版**（eagle）。

开发者士无双的LocalMusic仓库地址：https://gitee.com/shiwushuang9/localmusic

> v1.5.1-uos1 起从 Qt6+Dtk6 移植到 Qt5.11+Dtk5（UOS 系统自带版本）：
> 多媒体后端使用 gstreamer，音量/静音改由 QMediaPlayer 直接控制，
> 编码探测改用 QTextCodec，`QPalette::PlaceholderText` 等 Qt5.12+ API 已替换。

## 功能特性

- 📁 **多文件夹音乐库** — 左侧文件夹列表，可添加多个音乐文件夹，右侧显示所选文件夹的歌曲
- 🔄 **重新扫描** — 支持对单个文件夹重新扫描（按钮或右键菜单）
- 🗑️ **文件夹管理** — 右键移除文件夹，自动记忆文件夹列表
- 🏷️ **标签解析** — 内置 ID3v2/v1 (MP3)、Vorbis Comment (FLAC/OGG)、RIFF (WAV) 解析器
- 📋 **播放列表** — 四列展示（标题/歌手/专辑/时长），支持搜索过滤、右键菜单
- ▶️ **播放控制** — 播放/暂停/上一首/下一首，双击播放，空格快捷键
- 🎚️ **进度控制** — 可拖动进度条 + 实时时间显示
- 🔊 **音量控制** — 音量滑块（带图标）+ 静音切换，自动记忆音量
- 🔁 **播放模式** — 顺序播放 / 列表循环 / 单曲循环 / 随机播放
- 🎨 **DTK 原生界面** — 自动适配系统浅色/深色主题，标题栏带应用图标

## 更新记录

### v1.4.8
- 打开应用时歌曲列表默认为空，点击左侧文件夹后才显示对应歌曲
- 修复：添加文件夹按钮回退左留白，图标与文件夹图标恢复对齐
- 修复：刷新按钮右边缘与数量列右边缘共用同一留白常量，消除 12px 偏移
- 歌曲列表滚动条移至白色底框右边缘（搜索框保持 8px 内缩）
- 滚动条单独占最右一列；表头宽度同步让出滚动条列（搜索框保持原宽度不变）
- 歌曲列表悬停仅保留高亮，不再显示文件路径提示；间隔色调浅

### v1.4.7
- 按钮行与文件夹行共用 4 列结构（左留白/图标/名称/数量列/右留白），刷新按钮精确落位数量列
- 文件夹列表增加悬停高亮效果，与按钮悬停标识一致

### v1.4.6
- 文件夹图标统一为固定 20px 位图（按钮与列表渲染完全一致）
- 刷新按钮与歌曲数量列共享布局常量，宽度和位置精确对齐

### v1.4.5
- 添加文件夹按钮改用与文件夹列表相同的图标并靠左对齐；重新扫描按钮与歌曲数量列对齐

### v1.4.4
- 布局对齐重构：添加文件夹按钮行与搜索框同高对齐；文件夹列表下移"歌曲表头高度"与歌曲列表精确对齐

### v1.4.3
- 文件夹列表与歌曲列表行高统一为 36px，对齐更稳定

### v1.4.2
- 文件夹列表首行对齐微调：测量前先复位边距避免重复计算，并向上移动歌曲列表半行高度

### v1.4.1
- 修复文件夹列表首行对齐：直接测量两个列表首行实际偏移精确补偿
- 歌曲数量改为固定括号布局（"[" 数字 "]" 上下对齐），不再截断

### v1.4.0
- 文件夹列表优化：前加文件夹图标，名称靠左、歌曲数量靠右
- 文件夹列表首行与右侧歌曲列表首行对齐

### v1.3.9
- 歌曲列表优化：加大行间距，间隔色更明显，自动适配深浅主题

### v1.3.8
- 换回 ffmpeg 多媒体后端（gstreamer 后端在本机无法 seek，进度条点击/拖动失效）
- 修复进度条：点击从点击位置播放、可正常拖动、不再回弹
- 暂停改为"停止并记住位置"，恢复时重新加载并跳回暂停位置（避免 ffmpeg 长暂停恢复无声）

### v1.3.7
- 修复：进度条拖动时持续 seek 导致卡顿、点击跳转后无法正常拖动的问题
  （拖动中仅更新显示，松开才定位；点击立即从点击位置播放且可继续拖动）

### v1.3.6
- 修复：单曲循环模式下歌曲播完不自动重播的问题
  （gstreamer 后端在歌曲结束后无法 seek 回 0，改为重新加载整首歌曲重播）

### v1.3.5
- 修复：暂停较长时间后恢复播放无声的问题
  （Qt6 FFmpeg 多媒体后端 bug，改为优先使用 gstreamer 后端）

### v1.3.4
- 修复：单曲循环模式下"上一首/下一首"按钮失效的问题
  （单曲循环只影响歌曲播完自动重播，手动切换歌曲始终生效）

### v1.3.3
- 播放模式记忆：记住上次选择的播放方式（顺序播放 / 列表循环 / 单曲循环 / 随机播放），重启后自动恢复

### v1.3.1
- 修复：最大化窗口后自定义歌词背景图消失的问题
- 修复：大尺寸背景图在最大化/缩放时导致卡顿甚至崩溃
  （背景图加载时预缩放 + 绘制时缓存缩放结果）

### v1.3.0
- **歌词功能**：点击正在播放的歌曲名查看歌词详情页
  - 支持同名 `.lrc` 歌词文件（放在歌曲同目录）
  - 支持内嵌歌词（MP3 USLT / FLAC LYRICS）
  - 歌词随播放进度高亮并自动滚动，无歌词时显示提示
- **自定义歌词背景图**：右键歌曲名 → "设置歌词背景图…" 选择图片
  - 图片覆盖整个歌词区域（含歌曲名），所有歌曲共用
  - 或直接放置到 `~/.local/share/localmusic/background.{jpg,png}`

### v1.2.3
- 界面美化：分区使用不同柔和背景色，自动适配深浅主题
- 正在播放歌曲名移到进度条上方居中

### v1.2.2
- 搜索框左边缘对齐到"歌手"列
- 歌手/专辑/时长三列等宽并加宽

### v1.2.1
- 歌曲列表列宽调整：标题列加宽，歌手/专辑列收窄

### v1.2.0

- 底部控制栏改为**居中布局**（模式/上一首/播放/下一首/静音/音量 全部居中）
- 播放、上一首、下一首、静音图标改为**程序自绘**（不再依赖系统图标主题）
- 修复 ID3v1 空标签导致部分 MP3 歌曲名显示为空的问题
- 增加 GBK/UTF-8 中文标签识别，兼容更多中文歌曲文件
- 进度条支持**点击跳转**

## 构建（统信 UOS 20）

```bash
cd /home/UOS/Desktop/localmusic
cmake -B build-uos -DCMAKE_BUILD_TYPE=Release
cmake --build build-uos -j$(nproc)
```

依赖（UOS 源直接安装）：`qtbase5-dev qt5-qmake libqt5multimedia5-dev libqt5svg5-dev libdtkcore-dev libdtkgui-dev libdtkwidget-dev`

## 打包 deb

```bash
# 组装 staging 目录：usr/bin/localmusic、usr/share/applications/localmusic.desktop、
# usr/share/icons/hicolor/scalable/apps/localmusic.svg、DEBIAN/control、usr/share/doc/localmusic/copyright
dpkg-deb --build --root-owner-group <staging> localmusic_<版本>_amd64.deb
sudo dpkg -i localmusic_1.5.1-uos1_amd64.deb
```

## 使用

1. 点击左侧 **添加文件夹** 或按 `Ctrl+O` 添加音乐文件夹
2. 单击左侧文件夹切换歌曲列表，双击右侧歌曲播放
3. 右键文件夹可 **重新扫描** / **打开所在文件夹** / **从列表移除**
4. 空格键播放/暂停，`Ctrl+O` 添加文件夹

## 项目结构

```
localmusic/
├── CMakeLists.txt
├── resources.qrc           # 资源清单
├── resources/appicon.svg   # 应用图标
├── src/
│   ├── main.cpp            # 程序入口（DApplication 单实例）
│   ├── mainwindow.h/cpp    # 主窗口（文件夹栏 + 歌曲列表 + 控制栏 + 歌词页切换）
│   ├── musiclibrary.h/cpp  # 多文件夹音乐库 + 标签解析
│   ├── foldermodel.h/cpp   # 左侧文件夹列表模型
│   ├── playlistmodel.h/cpp # 歌曲列表模型
│   ├── player.h/cpp        # 播放核心（QMediaPlayer）
│   ├── lyrics.h/cpp        # LRC 解析 + 内嵌歌词/封面提取
│   ├── lyricsview.h/cpp    # 歌词详情视图（背景图 + 高亮滚动）
│   └── song.h              # 歌曲数据结构
```

## 开源许可

本项目基于 **GPL-3.0-or-later** 协议完全开源，详见 [LICENSE](LICENSE)。