# xmusic

**Repository Path**: openkylin/xmusic

## Basic Information

- **Project Name**: xmusic
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-27
- **Last Updated**: 2026-05-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# XMusic - Modern Cross-Platform Music Player

一个基于 SDL3、SDL_mixer3 和 SOUI4 的现代化跨平台音乐播放器。

A modern cross-platform music player based on SDL3, SDL_mixer3, and SOUI4.

## 功能特性 / Features

### 核心播放功能 / Core Playback
- ✅ 支持多种音频格式：MP3、WAV、OGG、FLAC、MOD、OPUS、M4A/AAC、WMA等
- ✅ 播放控制：播放、暂停、停止
- ✅ 音量调节与静音控制
- ✅ 播放进度显示与跳转
- ✅ 播放列表管理（添加、删除、排序）
- ✅ 专辑封面显示（占位符）

### 高级功能 / Advanced Features
- ✅ **元数据提取**：读取 ID3 标签、艺术家、专辑、年份等信息
- ✅ **标签编辑器**：编辑音频文件的元数据标签
- ✅ **批量格式转换**：将非 MP3 格式转换为 MP3（内置 LAME 编码器）
- ✅ **在线歌词搜索**：通过 API 获取并显示歌词
- ✅ **歌词显示**：支持 LRC 格式歌词，当前行高亮
- ✅ **音频均衡器**：多频段 EQ 调节
- ✅ **频谱可视化**：实时音频频谱动画显示
- ✅ **系统托盘**：最小化到托盘，支持托盘菜单控制
- ✅ **收藏功能**：标记和管理喜爱的歌曲

### UI 特性 / UI Features
- ✅ 现代化暗色调界面设计（深色背景 #1a1a1a，强调色 #e60026）
- ✅ 响应式布局，适配不同屏幕尺寸
- ✅ 高 DPI 支持
- ✅ 多语言支持（中文/英文自动切换）
- ✅ 平滑动画过渡效果

### 跨平台支持 / Cross-Platform Support
- ✅ Windows (7/8/10/11)
- ✅ Linux (Ubuntu, Fedora, Arch 等)
- ✅ macOS (10.15+)

---

Supports multiple audio formats: MP3, WAV, OGG, FLAC, MOD, OPUS, M4A/AAC, etc.
Playback controls: Play, Pause, Stop, Replay, Fast forward/Rewind
Volume adjustment and mute control
Playback progress display and seeking
Playlist management (add, remove, reorder)
Album cover display (placeholder)

**Metadata extraction**: Read ID3 tags, artist, album, year, etc.
**Tag editor**: Edit audio file metadata tags
**Batch format conversion**: Convert non-MP3 formats to MP3 (built-in LAME encoder)
**Online lyrics search**: Fetch and display lyrics via API
**Lyrics display**: Support LRC format with current line highlighting
**Audio equalizer**: Multi-band EQ adjustment
**Spectrum visualization**: Real-time audio spectrum animation
**System tray**: Minimize to tray with tray menu control
**Favorites**: Mark and manage favorite songs

Modern dark-themed UI design (dark background #1a1a1a, accent color #e60026)
Responsive layout for different screen sizes
High DPI support
Multi-language support (Chinese/English auto-switching)
Smooth animation transitions

Cross-platform support: Windows (7/8/10/11), Linux (Ubuntu, Fedora, Arch, etc.), macOS (10.15+)

## 构建说明 / Build Instructions

### 前置要求 / Prerequisites

- CMake 3.16 或更高版本 / CMake 3.16 or higher
- C++17 兼容的编译器 / C++17 compatible compiler
  - Windows: MSVC 2019+ 或 MinGW-w64
  - Linux: GCC 7+ 或 Clang 5+
  - macOS: Clang (Xcode Command Line Tools)
- Git（用于子模块管理）/ Git (for submodule management)
- Python 3（部分构建脚本需要）/ Python 3 (required for some build scripts)

### Windows

```bash
# 克隆项目（包含子模块）/ Clone repository with submodules
git clone --recursive https://gitee.com/setoutsoft/xmusic.git
cd XMusic

# 构建 / Build
mkdir build
cd build
cmake ..
cmake --build . --config Release

# 可执行文件位置 / Executable location
..\bin\Release\XMusic.exe
```

**可选配置 / Optional Configuration:**

如果使用已安装的 SOUI4（版本 >= 5.2.0.5），设置环境变量：
If using pre-installed SOUI4 (version >= 5.2.0.5), set environment variable:

```bash
set SOUI4_INSTALL_64=C:\path\to\soui4
```

否则会自动从 submodule 编译 SOUI4。
Otherwise, SOUI4 will be compiled from submodule automatically.

### Linux

```bash
# 克隆项目 / Clone repository
git clone --recursive https://gitee.com/setoutsoft/xmusic.git
cd XMusic

# 安装依赖（Debian/Ubuntu）/ Install dependencies (Debian/Ubuntu)
sudo apt-get install build-essential cmake git libasound2-dev \
    libpulse-dev libdbus-1-dev libx11-dev libxext-dev \
    libxcursor-dev libxrandr-dev libxi-dev libxinerama-dev \
    libgl1-mesa-dev libegl1-mesa-dev

# 构建 / Build
mkdir build
cd build
cmake ..
make -j$(nproc)

# 可执行文件位置 / Executable location
./bin/xmusic_player
```

**SOUI4 配置 / SOUI4 Configuration:**

如果已安装 SOUI4，设置环境变量：
If SOUI4 is pre-installed, set environment variable:

```bash
export SOUI4_INSTALL=/path/to/soui4
```

### macOS

```bash
# 克隆项目 / Clone repository
git clone --recursive https://gitee.com/setoutsoft/xmusic.git
cd XMusic

# 安装依赖（使用 Homebrew）/ Install dependencies (using Homebrew)
brew install cmake

# 构建 / Build
mkdir build
cd build
cmake ..
make -j$(sysctl -n hw.ncpu)

# 可执行文件位置 / Executable location
./bin/xmusic_player
```

## 使用方法 / Usage

### 启动程序 / Launch Application

```bash
# Windows
.\bin\Release\XMusic.exe

# Linux/macOS
./bin/xmusic_player
```

### 主要功能操作 / Main Feature Operations

#### 播放控制 / Playback Controls
- 点击播放列表中的歌曲开始播放
- 使用底部控制栏：播放/暂停、上一首、下一首、停止
- 拖动进度条跳转到指定位置
- 鼠标滚轮或 +/- 键调节音量

Click a song in the playlist to start playback
Use bottom control bar: Play/Pause, Previous, Next, Stop
Drag progress bar to seek to specific position
Mouse wheel or +/- keys to adjust volume

#### 播放列表管理 / Playlist Management
- 拖拽文件到窗口添加歌曲
- 右键菜单：添加文件夹、清空列表、删除选中
- 双击歌曲立即播放
- 支持拖拽排序

Drag and drop files to window to add songs
Right-click menu: Add folder, Clear list, Remove selected
Double-click song to play immediately
Support drag-and-drop reordering

#### 歌词显示 / Lyrics Display
- 自动加载同名 LRC 文件
- 在线搜索歌词（右键歌曲 → "搜索歌词"）
- 当前演唱行高亮显示
- 支持逐字卡拉 OK 效果

Auto-load LRC file with same name
Search lyrics online (right-click song → "Search Lyrics")
Current singing line highlighted
Support word-by-word karaoke effect

#### 标签编辑 / Tag Editing
- 右键歌曲 → "编辑标签"
- 修改标题、艺术家、专辑、年份、流派
- 保存更改到文件

Right-click song → "Edit Tags"
Modify title, artist, album, year, genre
Save changes to file

#### 批量转换 / Batch Conversion
- 菜单：工具 → 批量转换为 MP3
- 添加文件或文件夹
- 选择输出目录和质量设置
- 开始转换

Menu: Tools → Batch Convert to MP3
Add files or folders
Select output directory and quality settings
Start conversion

#### 均衡器调节 / Equalizer Adjustment
- 点击 EQ 按钮展开均衡器面板
- 调节各频段增益
- 预设模式选择（流行、摇滚、古典等）
- 重置为默认值

Click EQ button to expand equalizer panel
Adjust gain for each frequency band
Preset mode selection (Pop, Rock, Classical, etc.)
Reset to default

#### 系统托盘 / System Tray
- 最小化窗口自动隐藏到托盘
- 右键托盘图标显示控制菜单
- 支持播放控制、音量调节、退出

Minimize window to automatically hide to tray
Right-click tray icon to show control menu
Support playback control, volume adjustment, exit

## 项目结构 / Project Structure

```
XMusic/
├── src/                          # 主程序源代码 / Main program source
│   ├── AudioPlayer.cpp/h         # 音频播放引擎 / Audio playback engine
│   ├── AudioEqualizer.cpp/h      # 音频均衡器 / Audio equalizer
│   ├── MetadataExtractor.cpp/h   # 元数据提取（基于 TagLib）/ Metadata extraction (TagLib-based)
│   ├── Mp3Encoder.cpp/h          # MP3 编码（基于 LAME）/ MP3 encoding (LAME-based)
│   ├── PlaylistAdapter.cpp/h     # 播放列表适配器 / Playlist adapter
│   ├── ConfigManager.cpp/h       # 配置管理器 / Configuration manager
│   ├── LyricsApiManager.cpp/h    # 歌词 API 管理 / Lyrics API management
│   ├── MainDlg.cpp/h             # 主对话框 / Main dialog
│   ├── TagEditorDlg.cpp/h        # 标签编辑对话框 / Tag editor dialog
│   ├── BatchConvertDlg.cpp/h     # 批量转换对话框 / Batch convert dialog
│   ├── main.cpp                  # 程序入口 / Program entry point
│   ├── res/                      # UI 资源文件 / UI resource files
│   └── uires/                    # UI 布局定义 / UI layout definitions
├── SDL/                          # SDL3 库子模块 / SDL3 library submodule
├── SDL_mixer/                    # SDL_mixer3 库子模块 / SDL_mixer3 library submodule
├── soui4/                        # SOUI4 UI 框架子模块 / SOUI4 UI framework submodule
├── taglib/                       # TagLib 元数据库子模块 / TagLib metadata library submodule
├── lame/                         # LAME MP3 编码器子模块 / LAME MP3 encoder submodule
├── config/                       # 配置文件示例 / Configuration file examples
├── website/                      # 项目网站源码 / Project website source
├── CMakeLists.txt                # 顶层构建配置 / Top-level build configuration
├── BUILD_GUIDE.md                # 详细构建指南 / Detailed build guide
└── README.md                     # 本文件 / This file
```

## 技术架构 / Technical Architecture

### 分层设计 / Layered Design

1. **表现层 (UI Layer)**
   - SOUI4 框架，XML/HTML 布局
   - 自定义控件：歌词视图、频谱显示、均衡器滑块
   - 事件驱动的消息处理

2. **业务逻辑层 (Business Logic)**
   - 播放列表管理 (`PlaylistAdapter`)
   - 配置持久化 (`ConfigManager`)
   - 歌词网络接口 (`LyricsApiManager`)

3. **核心引擎层 (Core Engine)**
   - SDL3 + SDL_mixer3 音频解码与输出
   - 自定义 `AudioPlayer` 封装
   - 环形缓冲区 (`ring_buffer`) 优化性能

4. **工具层 (Utilities)**
   - TagLib 元数据提取
   - LAME MP3 编码
   - 文件格式转换

### 关键技术决策 / Key Technical Decisions

- **全静态链接**：所有依赖库以静态库形式编译，减少部署依赖
- **模块化依赖管理**：Git Submodules + CMake `add_subdirectory`
- **UI 与逻辑分离**：XML/HTML 定义界面，C++ 处理逻辑
- **跨平台兼容**：条件编译隔离平台特定代码

---

1. **UI Layer**
   - SOUI4 framework with XML/HTML layout
   - Custom controls: lyrics view, spectrum display, equalizer sliders
   - Event-driven message handling

2. **Business Logic Layer**
   - Playlist management (`PlaylistAdapter`)
   - Configuration persistence (`ConfigManager`)
   - Lyrics network interface (`LyricsApiManager`)

3. **Core Engine Layer**
   - SDL3 + SDL_mixer3 for audio decoding and output
   - Custom `AudioPlayer` wrapper
   - Ring buffer (`ring_buffer`) for performance optimization

4. **Utilities Layer**
   - TagLib metadata extraction
   - LAME MP3 encoding
   - File format conversion

**Key Technical Decisions:**
- **Full static linking**: All dependencies compiled as static libraries to reduce deployment dependencies
- **Modular dependency management**: Git Submodules + CMake `add_subdirectory`
- **UI and logic separation**: XML/HTML defines interface, C++ handles logic
- **Cross-platform compatibility**: Conditional compilation isolates platform-specific code

## 依赖库 / Dependencies

| 库 / Library | 版本 / Version | 用途 / Purpose |
|-------------|---------------|---------------|
| SDL3 | Latest (submodule) | 跨平台多媒体底层 / Cross-platform multimedia foundation |
| SDL_mixer3 | Latest (submodule) | 音频混音与解码 / Audio mixing and decoding |
| SOUI4 | >= 5.2.0.5 (submodule) | Windows/Linux UI 框架 / UI framework |
| TagLib | Latest (submodule) | 音频元数据读写 / Audio metadata read/write |
| LAME | Latest (submodule) | MP3 编码 / MP3 encoding |
| dr_mp3 | Vendored in SDL_mixer | MP3 解码 / MP3 decoding |
| stb_vorbis | Vendored in SDL_mixer | OGG/Vorbis 解码 / OGG/Vorbis decoding |
| libFLAC | Vendored in SDL_mixer | FLAC 解码 / FLAC decoding |
| libxmp | Vendored in SDL_mixer | MOD 格式支持 / MOD format support |
| FAAD2 | Vendored in SDL_mixer | AAC/M4A 解码 / AAC/M4A decoding |

**注意 / Note:** 所有第三方库均通过 Git Submodules 管理，首次构建时自动下载和编译。
All third-party libraries are managed via Git Submodules and automatically downloaded and compiled during first build.

## 克隆项目 / Clone the Repository

本项目使用 Git 子模块管理所有依赖库。克隆时请使用以下命令：

This project uses Git submodules to manage all dependency libraries. Please use the following command when cloning:

```bash
# 方式 1：递归克隆（推荐）/ Method 1: Recursive clone (recommended)
git clone --recursive https://gitee.com/setoutsoft/xmusic.git

# 方式 2：分步初始化 / Method 2: Step-by-step initialization
git clone https://gitee.com/setoutsoft/xmusic.git
cd XMusic
git submodule init
git submodule update
```

**国内用户加速 / Acceleration for users in China:**

可以使用 Gitee 镜像加速子模块下载（如 LAME）：
You can use Gitee mirror to accelerate submodule downloads (e.g., LAME):

```bash
git submodule set-url lame https://gitee.com/setoutsoft/lame.git
git submodule sync
git submodule update
```

## 编译选项 / Build Options

### CMake 配置选项 / CMake Configuration Options

```bash
# 使用静态运行时库（Windows）/ Use static runtime library (Windows)
cmake .. -DUSE_STATIC_RUNTIME=ON

# 指定 SOUI4 安装路径 / Specify SOUI4 installation path
cmake .. -DSOUI4_INSTALL=/path/to/soui4

# 启用调试日志 / Enable debug logging
cmake .. -DCMAKE_BUILD_TYPE=Debug
```

### 构建类型 / Build Types

- **Debug**：包含调试符号，启用断言，适合开发
- **Release**：优化编译，strip 符号（Linux），适合发布

**Debug**: Includes debug symbols, enables assertions, suitable for development
**Release**: Optimized compilation, strips symbols (Linux), suitable for distribution

## 常见问题 / FAQ

### Q: 首次构建时间很长怎么办？ / Q: First build takes too long?

A: 首次构建需要编译 SDL3、SDL_mixer、TagLib、LAME、SOUI4 等多个大型库，可能需要 10-30 分钟。后续构建会显著加快。
A: First build needs to compile multiple large libraries (SDL3, SDL_mixer, TagLib, LAME, SOUI4), which may take 10-30 minutes. Subsequent builds will be significantly faster.

### Q: 如何添加新的音频格式支持？ / Q: How to add support for new audio formats?

A: SDL_mixer3 已通过 vendored 库支持主流格式。如需额外格式，需在 SDL_mixer 中启用相应解码器并重新编译。
A: SDL_mixer3 already supports mainstream formats through vendored libraries. For additional formats, enable corresponding decoders in SDL_mixer and recompile.

### Q: 歌词不显示怎么办？ / Q: Lyrics not displaying?

A: 确保存在同名 `.lrc` 文件，或通过右键菜单"搜索歌词"在线获取。检查歌词文件编码是否为 UTF-8。
A: Ensure a `.lrc` file with the same name exists, or search online via right-click menu "Search Lyrics". Check if the lyrics file encoding is UTF-8.

### Q: 如何在 Linux 上获得更好的音频性能？ / Q: How to get better audio performance on Linux?

A: 安装 PulseAudio 或 PipeWire，并确保用户有权限访问音频设备。
A: Install PulseAudio or PipeWire, and ensure the user has permission to access audio devices.

## 贡献指南 / Contributing

欢迎提交 Issue 和 Pull Request！在贡献代码前，请：

Welcome to submit Issues and Pull Requests! Before contributing code, please:

1. 遵循 C++17 标准 / Follow C++17 standard
2. 保持代码风格一致 / Maintain consistent code style
3. 添加必要的注释 / Add necessary comments
4. 测试跨平台兼容性 / Test cross-platform compatibility
5. 更新相关文档 / Update relevant documentation

## 许可证 / License

本项目基于以下开源许可证：

This project is based on the following open source licenses:

- **SDL3**: zlib License
- **SDL_mixer3**: zlib License
- **SOUI4**: SOUI License
- **TagLib**: LGPL 2.1+ / MPL 1.1
- **LAME**: LGPL 2.0+

详细许可信息请参阅各子模块的 LICENSE 文件。
For detailed license information, please refer to the LICENSE files in each submodule.

## 联系方式 / Contact

- 项目主页 / Project Homepage: [GitHub Repository](https://gitee.com/setoutsoft/xmusic)
- 问题反馈 / Issue Tracker: [GitHub Issues](https://gitee.com/setoutsoft/xmusic/issues)
- 网站 / Website: [XMusic Official Site](https://soui.com.cn/xmusic)

---