使用教程

认识界面、摸清脾气，把 QueMusic 用得得心应手。

界面导览

主界面四个区域，对应 layout/ 下的 QML 文件：

在线音乐与搜索

网易云、酷狗、哔哩哔哩在界面里的操作完全一致 —— 音质高档缺失时还会自动降级回退，很贴心：

• 搜索：歌曲、歌手、歌单，支持搜索历史
• 私人漫游：基于收听偏好的每日推荐
• 分类歌单 / 排行榜 / 歌手页：滚动到底自动翻页
• 音质选择：标准 128k / 高清 320k / 无损 FLAC（需对应平台权限）
• 下载管理：多任务下载、进度、重试

歌词与沉浸体验

• 逐字歌词：逐音节时间轴驱动的卡拉 OK 高亮 + 逐行弹簧动画
• 桌面歌词 / 桌面小窗：悬浮于其他窗口之上
• 对唱歌词：多人歌曲按角色分行
• 歌词界面可换：内置「默认 / 极简 / 自由 / 3D」四种主题，播放页左上角第二个按钮随时切换
• 3D 主题：GPU 点云舞台 + 真透视歌词平面，相机由鼠标驱动，场景随音乐增亮

均衡器与音频处理

全部 DSP 在音频线程内逐样本完成，界面再忙也不影响音质：

• 10 段参数均衡器：±24 dB、10 组预设、可调 Q 值与自动余量
• 变速与变调：0.25×–4× 倍速（可保持音调），±12 半音独立移调，可叠加
• 声道处理：平衡、单声道折叠、立体声宽度、声道互换
• ReplayGain：响度归一 + 限幅防削波；切歌淡入淡出逐样本完成
• 输出可调：采样率、缓冲（10–100 ms）、输出设备播放中热切换

本地歌词匹配规则

• 同目录同名 .lrc（或 .txt）文件
• 内嵌歌词 — ID3v2 SYLT / USLT 与 TagLib LYRICS（FLAC、Ogg/Opus、MP4/M4A 常见）
• 在线匹配（含翻译）
• 「纯音乐，请欣赏」占位

设置、外观与快捷键

设置页分为主题、界面、功能、播放、快捷键、插件等模块：浅色 / 深色 / 跟随系统，封面主色实时驱动自适应主题。播放页「播放器样式」弹窗可调歌词大小与位置校准。快捷键在「设置 → 快捷键」中自定义。

插件开发

界面里能换的、能加的，都是插件。一个文件夹就是一个插件，放进去即被扫描到 —— 不用编译、不用改主程序喵。

安装插件

• 下载 QuePlugins 仓库（或某个插件文件夹）
• 歌词界面插件：设置 → 插件 → 歌词界面 → 安装插件，选文件夹后点「启用」
• 功能插件：设置 → 插件 → 功能 → 安装插件，装好即启用，列表里可开关
• 加载失败的插件会被自动停用；停用 / 卸载时宿主回收插件挂出的一切

目录结构与 info.json

两类插件目录约定一致，文件夹名即插件 id（小写字母、数字、-、_）：

lyrics/example/               歌词界面插件
  info.json                   插件信息（必要）
  example.qml                 入口 QML（必要，文件名在 info.json 指定）
  info.png                    预览图（建议，列表里显示）
  shaders/wave.frag.qsb       自定义着色器（可选，需预编译为 .qsb）
Tools/example/                功能插件（目录约定相同）

{
  "apiVersion": 1,
  "name": "波浪示例",
  "author": "QueMusic",
  "version": "1.0.0",
  "description": "着色器波浪背景 + 逐字高亮 + 双语翻译",
  "entry": "example.qml",
  "preview": "info.png"
}

歌词界面插件契约

入口根类型为 Item。声明同名属性，宿主就会自动绑定；没写的自动跳过，只实现自己需要的部分就好：

import QtQuick

Item {
    // ---- 播放状态 ----
    property real position          // 播放位置（毫秒）
    property bool playing           // 是否正在播放
    property bool mediaActive       // 是否有媒体

    // ---- 歌词数据 ----
    property var  lyricsModel       // 歌词行（time / text / info / isOther）
    property var  translateModel    // 翻译行，与 lyricsModel 同下标对应
    property int  currentIndex      // 当前行下标（宿主按进度持有）

    // ---- 歌曲信息与外观 ----
    property string title
    property string artist
    property url    coverUrl
    property color  mainColor       // 封面取色主题主色

    // 可选：宿主约每 320ms 调一次，用于推进自定义动画
    function timerFunction() { }

    // 可选：在「播放器样式」弹窗里追加自定义选项
    property Component styleOptions
}

样式改动一律走 requestStyle(key, value) 白名单接口；逐字高亮用每行的 info 时间轴数组。

功能插件契约

入口根类型为 QtObject 或 Item，声明 property QtObject api，宿主在 Component.onCompleted 之前注入：

import QtQuick
import QueMusic 1.0

QtObject {
    id: plugin
    property QtObject api        // 宿主注入

    function activate() {
        var btn = api.mount("player.right", btnComp)          // 挂到播放控制栏右侧
        var panel = api.loader(api.pluginUrl + "panel.qml",
                               { width: 240, height: 160 })   // 自建面板
    }

    property Component btnComp: Component {
        // import QueMusic 1.0 可用 Style / SButton 等宿主组件
    }
}

扩展点：titlebar.left / titlebar.right、player.left / player.right、sidebar.bottom、window.overlay。插件还有 api.settings 私有配置与 api.toast() 可用。

着色器注意事项

Qt 6 的 ShaderEffect 不编译运行时 .frag，插件自带着色器必须预编译成 .qsb，否则效果会静默消失喵：

qsb --glsl "100 es,120,150,300 es,310 es,320 es" --hlsl 50 --msl 12 \
    -o shaders/wave.frag.qsb shaders/wave.frag

项目结构

了解仓库的组织方式，是参与开发的第一步喵。

QueMusic/
├── CMakeLists.txt              # 顶层构建配置
├── CMakePresets.json           # 各平台构建预设
├── cmake/                      # CMake 模块（子模块集成 / 运行库部署 / FFmpeg 拉取）
├── main.cpp                    # C++ 程序入口
├── main.qml                    # QML 主入口（窗口 / 全局单例装配）
├── SettingsView.qml            # 设置页
├── cpp/                        # C++ 后端
│   ├── audio/                  # 音频引擎：AudioEngine / FfmpegDecoder / AudioDsp / AudioRing
│   ├── plugins/                # 插件存储：LyricsPluginStore / FunctionPluginStore
│   ├── webdav/                 # WebDAV：WebDavClient / WebDavModel / WebDavCache
│   ├── CoverHelper.cpp/h       # 封面提取与磁盘缓存
│   ├── ColorExtractor.cpp/h    # 封面取主色（自适应主题）
│   ├── LocalMusicScanner.cpp/h # 本地曲库扫描
│   ├── LocalLyricsReader.cpp/h # .lrc 与内嵌歌词读取
│   └── DbService.cpp/h         # 数据库线程化服务
├── api/                        # 在线媒体引擎
│   ├── MusicApiService.cpp/h   # 调度中枢（QML 单例 MusicApi）
│   ├── NeteaseCloudApi.cpp/h   # 网易云音乐
│   ├── KugouApi.cpp/h          # 酷狗音乐
│   └── BilibiliApi.cpp/h       # 哔哩哔哩
├── components/                 # 自研 QML 组件库（Style / Options / Q*** 控件）
├── layout/                     # 页面布局（侧栏 / 内容区 / 播放栏 / 沉浸歌词）
├── pages/                      # 功能页面（首页 / 搜索 / 歌单 / 收藏 / 文件 / 下载）
├── lyricsui/                   # 歌词界面主题（极简 / 自由 / 3D）
├── shaders/                    # GLSL 着色器与 C++ 材质
├── packaging/                  # 各平台打包脚本
├── tests/                      # 音频管线等离线自测
├── ThirdParty/qwindowkit/      # Git 子模块 —— 无边框窗口框架
├── CHANGELOG.md                # 更新日志
├── LICENSE                     # Apache License 2.0
└── README.md

模块职责速查

构建指南

从源码构建 QueMusic：需要 Qt 6.10+、CMake ≥ 3.24 与支持 C++20 的编译器。

前置条件

• Qt 6.10+（Core / Gui / Quick / Qml / Network / Multimedia / Sql / Concurrent / ShaderTools）
• CMake ≥ 3.24（需预设支持），推荐 Ninja
• 编译器：MSVC 2022 / GCC 13+ / MinGW 13+ / LLVM-MinGW 17+ / Clang
• FFmpeg 开发库：Windows 执行 cmake/fetch_ffmpeg.ps1；Debian/Ubuntu 装的是 libavcodec-dev libavformat-dev libavutil-dev libswresample-dev

克隆仓库（务必携带子模块）

git clone --recurse-submodules https://github.com/BroNekoX/QueMusic.git
cd QueMusic

# 忘了拉子模块的话补一条：
git submodule update --init --recursive

方式一 · 使用 just（推荐）

just setup  # 首次使用：拉取子模块
just b      # 构建
just r      # 运行

方式二 · 使用 CMake Presets

cmake --preset <preset-name>
cmake --build build/<preset-name> -j 8
./build/<preset-name>/bin/QueMusic       # Linux / macOS
./build/<preset-name>/bin/QueMusic.exe   # Windows

打包分发

• Windows：windeployqt + Inno Setup（可选）
• Linux：bash packaging/build-linux.sh 生成 AppImage
• macOS：just mac-bundle 生成 .dmg

贡献指南

欢迎任何形式的贡献 —— 从点亮一颗 Star 到提交 Pull Request，每一份心意都算数喵。

开发流程

• Fork 本仓库
• 创建功能分支：git checkout -b feat/your-feature
• 提交修改：git commit -m "feat: add xxx"
• 推送并发起 Pull Request

代码风格参考现有文件，遵循 C++20 / Qt 6 / QML best practices。动手前请读仓库中的 贡献指南。

故障排查

遇到问题先别慌，下面的情况八成能对号入座喵。

许可证与致谢

QueMusic 站在巨人的肩膀上，也把自由还给每一个使用者喵。

主体许可证

项目主体遵循 Apache License 2.0 —— 允许自由使用、修改、分发甚至商用，需保留版权声明与 NOTICE，专利授权条款明确。

关于背景着色器

• Fluid — 移植自 Paper-design/shaders（Apache-2.0，引用合规）
• Classic — 自研实现，参考 AMLL 思路但算法、代码与数值均未照搬

技术栈

致谢

• Qt Project — 强大的跨平台框架
• QWindowKit — 无边框窗口解决方案
• QCloudMusicApi — 网易云音乐在线接口实现
• Crypto++ / libqrencode / TagLib — 加解密、二维码与元数据解析
• SMTC-Bridge-Cpp / smtc_bridge_rust — Windows 系统媒体控件桥接参考
• Paper-design/shaders — 背景着色器 Fluid 的算法移植
• EvolveUI / AMLL-Core / ShaderToy — 组件设计与着色器灵感
• 所有贡献者与测试者

免责声明要点