了解目录

快速了解

QueMusic 是一款用 C++20 + Qt 6 + QML 从零写起的跨平台桌面音乐播放器。 它没有走「Electron / Web 内核套壳」的常见路线,而是把音频、渲染、界面三条链路都做成了原生实现。

10个月

古法手搓,慢慢打磨

QueMusic 从第一行代码到现在,已经走了 10 个月。没有现成的轮子可以直接套, 绝大多数代码都是一个人手写出来的 —— 音频链路、GPU 着色器、插件运行时, 一行一行刻出来,再一遍一遍打磨。

C++20 Qt 6 QML 纯手写实现

它是什么

QueMusic 的定位很明确:一个愿意长期做下去的桌面音乐播放器。 本地曲库、WebDAV、多平台在线音乐、逐字歌词与桌面歌词、均衡器与音效、歌单收藏与下载管理, 这些「播放器该有的东西」都是内置实现的,而不是靠插件东拼西凑。

架构上分三层:C++ 核心负责解码、DSP、标签解析、目录扫描与网络; QML 界面只负责呈现与交互;Qt RHI 把绘制直接交给平台 GPU 后端。 三条链路各自独立,界面再忙也不会拖累声音。

项目内容
框架Qt 6.10 · Qt Quick · Qt RHI
语言C++20 / QML / JavaScript
渲染D3D11 / Metal / Vulkan / OpenGL(由 RHI 自动选择)
音频FFmpeg 解码 + 自研 DSP 全链路
平台Windows 10+ · macOS 11+ · 主流 Linux 发行版
许可Apache-2.0,永久免费开源,无任何付费内容
版本v0.7.1-Beta(Beta 阶段,功能持续补齐)

它能做什么

多平台在线音乐

网易云(QCloudMusicApi)、酷狗、哔哩哔哩统一接入:搜索、私人漫游、分类歌单、排行榜、歌手页、音质选择,操作方式完全一致。

本地曲库与 WebDAV

本地文件夹多选扫描、排序、加入播放列表;WebDAV 服务器带鉴权直连播放,听过的曲目自动缓存,离线也能播。

歌词与沉浸体验

逐字卡拉 OK、对唱歌词、桌面歌词、四套歌词主题(默认 / 极简 / 自由 / 3D),歌词界面还能整体换成插件。

音频与音效

10 段参数均衡器、0.25×–4× 变速保持音调、±12 半音移调、声道处理、ReplayGain 响度归一与限幅。

和「Web 套壳播放器」的区别

维度QueMusicWeb 内核套壳
运行时C++ 原生进程,无浏览器内核内嵌 Chromium,常驻数百 MB
音频链路自研引擎,音频线程内逐样本处理受限于 <audio> 与 JS 调度
渲染Scene Graph 批处理 + GPU 着色器DOM + CSS 合成,层数多
低配表现核显 1080P 稳定 60 FPS滚动、切页易掉帧
包体100-200MB左右300MB+或依赖系统WebView
永久免费 · 没有 Pro、会员、充值、内购。 如果发现你的 QueMusic 需要付费,请立刻告诉开发者。

为什么选择 QueMusic

四个理由,说白了就是「能长期用、敢放心用」。每一条都可以自己去验证。

01 / PERFORMANCE

性能强大

在QML框架方面尽可能做到简洁,前端渲染性能快;后端基于C++引擎,效率超高

02 / LONG TERM

长期更新

QueMusic Project是长线项目,将会持续更新,持续完善,持续进行维护,更新可靠。

03 / RELIABLE

稳定安全可靠

QueMusic是永久开源免费的软件,其代码均可到GitHub或Gitee查看,代码基于QtQuick框架稳定开发,保障可靠安全性,并且没有任何病毒、后门与隐私查看器,值得可靠

04 / TRUST

开发者水平值得信赖

BroNekoX拥有多年编程经验,对QtWidgets、QtQuick等框架基本熟练掌握,技术值得信赖,用技术一点点刻出更完美的QueMusic软件

性能强大,具体强在哪

  • 主线程只做界面:文件扫描、标签解析、封面提取、网络请求都不在主线程执行
  • 音频链路独立:解码线程 → 无锁环形缓冲 → 音频回调线程,界面掉帧不影响声音
  • 渲染克制:在QML框架中,做到极简的框架、完美废弃Qt5图形模块,使用基于QtRHI的着色器实现超高的渲染效率
  • 实测数据:i5-12400 + UHD 730 核显、1080P 歌词界面,CPU ≈4%、GPU ≈15%、稳定 60 FPS

长期更新,不是口号

承诺做法
版本可追溯每次发布都写 CHANGELOG,分类记录新增 / 重构 / 优化 / 修复
方向可预期功能优先级公开讨论,插件体系承接长尾需求,避免主程序膨胀
不锁死平台Windows / macOS / Linux 同步发布,Linux 适配 Wayland 与中文输入法
不做「最终版」Beta 阶段持续修复已知问题,不靠换皮发新版本

稳定、安全、可靠

  • 错误隔离:统一错误层,网络异常、解码失败、文件缺失都不会让界面崩溃
  • 开源免费:QueMusic 永久开源免费,我承诺永远不会跑路和圈钱喵!
  • 凭据本地保存:账号 Cookie 与播放配置存于本机系统目录,不上传任何服务器
  • 安全软件:QueMusic 没有病毒,没有后门,也不会有,QueMusic不会查看大家的隐私
  • 可回滚:Release 保留历史版本,出问题可以直接退回上一版

开发者水平值得信赖

  • BroNekoX:QueMusic软件的主要开发者,成立QueMusic Project项目
  • 拥有多年编程经验,熟练掌握开发QueMusic的QtQuick框架,并且会C++、Python、JavaScript等多门编程语言,掌握QtWidgets、QtQuick、Flutter、WebView等框架。
  • 这个项目的难度不在于「把界面画出来」,而在于自研音频引擎、GPU 着色器渲染与插件运行时。
  • 这些问题没有现成轮子可以直接套:音频要处理解码、重采样、EQ、变速变调、响度与限幅;
  • 渲染要处理模糊、渐进模糊、3D 点云与真透视歌词平面;插件要设计一套稳定契约,还要保证插件出错不影响宿主。
  • 代码、提交记录、更新日志、第三方许可证声明全部公开。你可以直接翻到任意一次修复, 看它究竟改在哪一行 —— 这比任何「我很靠谱」的说辞都更有说服力。

    行业领先的性能

    QueMusic基于QtQuick框架打造,在具有顶级性能的QtRHI渲染下具有非常高的UI渲染性能,后端更是使用顶级性能的C++,经过多线程极致优化,性能几乎遥遥领先。

    ~70MB启动 内存 占用
    ≈4%平均 CPU 占用
    ≈10%核显 GPU 占用

    一、架构:把计算移出主线程

    界面线程只做两件事:处理输入、提交绘制。所有耗时操作都在 C++ 工作线程里完成。

    • 解码:FFmpeg 在独立解码线程运行,通过无锁环形缓冲交给音频回调
    • 标签与封面:TagLib 解析、封面提取与磁盘缓存全部后台执行
    • 目录扫描:本地曲库扫描分批进行,边扫边显示,不阻塞列表滚动
    • 网络:QNetworkAccessManager 在独立线程,接口数据在 C++ 侧完成解析与模型更新
    • 数据库:DbService 单线程串行化,避免 SQLite 并发写入竞争

    二、音频线程:零分配、无锁

    • 音频回调中不分配内存、不加锁、不触发信号槽的同步派发
    • EQ、音量、淡入淡出逐样本处理,系数预计算,回调里只做乘加
    • 播放状态由原子量传递,界面读状态不打断音频线程
    • 输出缓冲 10–100 ms 可调,切歌与设备切换不会产生爆音

    三、渲染:少画一层

    • 着色器合并:模糊卡片把「取样 → 模糊 → 提饱和 → 圆角裁剪」合成单个 pass
    • 减少 clip:避免层层嵌套裁剪,让 Scene Graph 能真正合批
    • 频谱同步帧:歌词页频谱跟随渲染帧刷新,不做无意义的高频重绘
    • 列表优化:滚动使用预定义函数与固定高度委托,减少布局计算

    四、编译期与加载期

    • QML / JS 标注静态类型,交由 qmlcachegen 编译,减少运行时解析
    • Release 开启 LTO、函数分节与 PCH,二进制更小、启动更快
    • 页面使用异步 Loader 按需加载,重对象在后台线程构建完成后一次性交换
    • 启动阶段只装配必要单例,其余模块首次使用时才初始化

    五、实测数据

    场景CPUGPU帧率
    1080P 沉浸歌词界面≈4%≈15%60 FPS
    常规列表浏览≈2%≈8%60 FPS
    后台播放(窗口隐藏)<1%≈0%—

    测试环境:i5-12400 + UHD 730 核显,Windows 11,缓冲区 40 ms。

    低配也友好 · 上述数据是核显平台的结果。老 CPU 上帧率可能下降,但音频链路不受影响, 仍可保持连续播放 —— 因为声音根本不在界面线程里算。

    QueAudio Engine

    音频引擎自己握着整条链路,不依赖系统播放器:解码线程 → 无锁环形缓冲 → 音频回调线程, DSP 全在音频线程内逐样本完成喵。

    数据流

    text音频链路
    文件 / 网络流
       ↓  FFmpeg(libavformat / libavcodec)
    解码线程  →  重采样到设备格式
       ↓  无锁环形缓冲(SPSC)
    音频回调线程(QAudioSink 拉模式 + 自定义 QIODevice)
       ↓  DSP 链:声道 → EQ → 变速/变调 → 响度 → 限幅 → 淡变
       ↓
    声卡输出            ↘ 频谱采样 → 界面可视化

    解码与输出

    • FFmpeg 负责解码,兼容常见封装(MP3 / FLAC / AAC / OGG / Opus / WAV / M4A / APE 等)
    • 输出走 QAudioSink 拉模式,自定义 QIODevice 从环形缓冲取数据
    • 缓冲时长 10–100 ms 可调;输出设备、采样率支持播放中热切换
    • 支持 WebDAV 等带鉴权的远程流,边播边缓存,避免重复下载

    DSP 链

    模块能力参数范围
    均衡器10 段参数 EQ,10 组预设,前置增益与自动余量±24 dB,Q 可调
    变速保持音调的时间伸缩0.25× – 4×
    变调独立半音移调,可与变速叠加±12 半音
    声道平衡、单声道折叠、立体声宽度、声道互换、左右独立增益0 – 200%
    响度ReplayGain 归一 + 峰值限幅,防削波自动
    淡变切歌 / 暂停淡入淡出,逐样本计算0 – 1 s

    频谱与状态

    • 频谱数据与音频同源采样,避免界面自造假波形
    • 播放状态(播放 / 暂停 / 缓冲 / 结束)通过原子量同步,界面只读
    • 上一首 / 下一首连续失败 2 次自动停止,不会陷入跳歌死循环
    • 切歌时清空缓冲并重建解码器,旧数据不残留

    可靠性设计

    • 解码器异常不抛出到界面,统一返回错误码并自动尝试下一个音源
    • 缓冲欠载时静音填充而非断续重采样,避免爆音
    • 播放位置以已消费样本数计算,拖动进度条后重新定位解码位置

    SqueUI Next

    SqueUI Next是新一代QtQuick组件库,具有美丽丝滑的效果,其渲染性能非常好, QueMusic基于SqueUI深度优化,渲染性能高效。 注意:SqueUI是QueMusic主要开发者开发,目前还处于预览阶段(github.com/bronekox/squeui)

    组件与主题

    • 自研 QML 组件库(按钮、卡片、列表、对话框、滑块等)统一样式与交互反馈
    • 全局 Style 单例集中管理颜色、圆角、间距、字号,界面里没有硬编码色值
    • 封面主色提取驱动自适应主题:主色 / 次色 / 第三色,随歌曲变化
    • 浅色 / 深色 / 跟随系统三种模式,切换即时生效

    动画与手感

    • 统一使用自定义贝塞尔曲线,转场有节奏但不浮夸
    • 歌词逐行弹簧动画、封面切换交叉淡入、列表进入交错淡入
    • 动画只改 transform / opacity,避免触发布局重排
    • 支持系统「减少动态效果」偏好,自动降级为淡入淡出

    着色器渲染

    效果实现方式
    毛玻璃卡片单 pass:取样 → 模糊 → 提饱和 → 圆角裁剪
    歌词渐进模糊按距中心距离调整模糊强度,随滚动实时更新
    流体背景GPU 噪声 + 封面取色,替代旧版着色器实现
    3D 点云舞台点云几何 + 真透视歌词平面,相机由鼠标驱动

    布局与加载

    • 布局优先级:x/y → anchors → Row/Column → Layouts
    • 页面通过异步 Loader 按需加载,切页不阻塞主线程
    • 列表委托固定高度 + 预定义滚动函数,长列表依然顺滑
    • 无边框窗口支持拖拽、缩放、贴边与系统按钮,各平台使用对应材质

    适配与细节

    • 桌面歌词、迷你播放器、托盘菜单与系统媒体控件(SMTC / MPRIS)
    • Linux 适配 Wayland 与 fcitx 输入法;macOS 红绿灯按钮左置
    • 键盘快捷键可自定义,常用操作无需鼠标
    • 字体与缩放跟随系统 DPI,避免高分屏模糊

    QuePlugins Engine

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

    歌词界面插件

    换掉沉浸播放页的整套歌词界面。宿主注入播放进度、歌词数据与配色,插件只负责呈现;同时只用一个,播放页随时切换。

    功能插件

    往界面里加东西:标题栏、底栏、侧栏、整窗覆盖层都是开放扩展点;插件用 api.mount() 挂按钮、api.loader() 挂面板。

    目录结构

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

    info.json

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

    歌词界面插件契约

    入口根类型为 Item,声明同名属性即由宿主自动绑定;没写的会被跳过。

    属性含义
    position当前播放位置(毫秒)
    playing / mediaActive是否正在播放 / 是否有媒体
    lyricsModel歌词行列表(time / text / info / isOther)
    translateModel翻译行列表,与歌词行同下标对应
    currentIndex当前行下标
    title / artist / coverUrl歌曲信息
    mainColor 等封面取色得到的主色 / 次色 / 第三色
    timerFunction()可选,宿主约每 320 ms 调用一次
    styleOptions可选,在「播放器样式」弹窗中追加自定义项

    功能插件 API

    qmlTools/example/example.qml
    import QtQuick
    import QueMusic 1.0
    
    QtObject {
        property QtObject api        // 宿主注入
    
        function activate() {
            api.mount("player.right", btnComp)                    // 挂按钮
            api.loader(api.pluginUrl + "panel.qml", { width: 240 }) // 挂面板
            api.toast("插件已就绪")                                // 提示
        }
    
        property Component btnComp: Component { }
    }

    扩展点

    扩展点位置
    titlebar.left / titlebar.right标题栏左右
    player.left / player.right播放控制栏左右
    sidebar.bottom左侧导航栏底部
    window.overlay整窗覆盖层

    安装与容错

    • 设置 → 插件:安装、启用、打开目录、重新扫描、删除
    • 歌词界面插件安装后需在播放页切换选中,选择结果跨启动保留
    • 加载失败的插件自动停用,不会影响主程序启动
    • 停用 / 卸载时自动回收插件挂出的组件、样式与配置
    • 自带着色器必须预编译为 .qsb,否则效果会静默失效
    开始写插件 · 完整规范与可安装示例见 QuePlugins 仓库, 详细契约与构建说明见 文档 · 插件开发。

    项目展望

    QueMusic Project 作为长线开源项目,未来会持续迭代与开发,并做出更多的成就

    01 / Library

    SqueUI

    高性能 QtQuick 组件库,把 QueMusic 里打磨出来的组件沉淀下来,拥有高度的自定义功能和流畅的性能

    02 / Global

    QueMusic Global

    面向全球发布的 QueMusic,让更多地区和语言的用户也能用上它,使用全球的音乐平台API

    03 / Runtime

    SqueUI Next

    基于 Qt 框架开发、用来代替 QML 的新式 GPU 渲染框架。

    都还在路上 · 这三项都还没有明确的时间表,做一点算一点。 想一起推进的话,可以看看 加入我们。