Jellyfin2HQPlayer – 基于本地文件直读的 HQPlayer 控制方案（Bit-perfect）

ytsam

Jellyfin2HQPlayer – 基于本地文件直读的 HQPlayer 控制方案（Bit-perfect）

一直在找一个方案：

• 能用开源音乐库管理（像 Roon 那样浏览方便）
• 又能保持 HQPlayer 的纯播放链路（不走流媒体、不被改动）
  

市面上其实一直没有一个“干净”的解法。

所以做了这个项目：Jellyfin2HQPlayer

--------------------------------------------------

一、这是个什么东西？

一句话：

• 用 Jellyfin 做音乐库
• 用 HQPlayer 做播放
• 中间用 Jellyfin2HQPlayer 做控制桥
  

核心不是播放器，而是：

• 控制 + 对接 + 保持播放链路纯净
  

--------------------------------------------------

二、一个很重要的点

• 支持 HQPlayer 所有版本
  

包括：

- HQPlayer Desktop
- HQPlayer Embedded

统一通过 XML 接口控制，无区别使用。

--------------------------------------------------

三、为什么选 Jellyfin？

Jellyfin 在音乐库这块其实做得相当不错：

- 专辑 / 艺术家 / 曲目 / 播放列表结构清晰
- 元数据支持完整（专辑信息 / 年份 / 分类等）
- 封面、图片管理完善（多图类型支持）
- 支持歌词（本地 / 插件）
- 搜索体验很好

本质上：

• 它已经是一个成熟的本地音乐库管理系统
  

另外：

• 开源 + 免费
  

但是问题在于：

• 可以通过DLNA插件支持推送到HQPlayer播放，但官方播放链路（UPnP / 转码）不够纯
• 不符合 HQPlayer 的 HiFi 使用方式
  

所以才有这个项目。

--------------------------------------------------

四、核心思路

这个项目和常见方案最大的不同：

• 不走 streaming
• 不走转码
• 不走 HTTP
  

而是：

• HQPlayer 直接读取本地文件（File Mode）
  

也就是说：

- 文件路径直接交给 HQPlayer
- Jellyfin 只负责浏览和元数据
- 不参与音频数据传输

最终效果：

✔ 没有额外性能开销
✔ 没有音质损失
✔ 等同 HQPlayer 本地播放（Bit-perfect）

--------------------------------------------------

五、能干什么？

1）音乐库浏览（基于 Jellyfin）

- 专辑 / 艺术家 / 曲目 / 播放列表
- 封面 / 元数据完整支持
- 搜索 / 收藏

2）HQPlayer 控制

- 播放 / 暂停 / 上一首 / 下一首
- 添加到 HQPlayer 队列
- 专辑 / 单曲播放
- 实时播放状态（WebSocket）

显示信息：

- 当前曲目
- PCM / DSD
- 采样率 / 比特率

3）歌词（可选）

- 基于 Jellyfin 插件
- 支持滚动歌词

4）Path → ID 映射（插件实现，可选）

- 解决封面 / 歌词匹配问题
- 保证 metadata 精确对应

--------------------------------------------------

六、使用前必须知道的限制

当前版本：

• 只支持同机部署
  

也就是说：

- Jellyfin 和 HQPlayer 必须在同一台机器
- Jellyfin2HQPlayer 可独立部署（Linux / macOS / Windows）
- 不支持直接跨主机文件访问（NAS需映射到本机）

原因：

• 依赖本地文件路径（File Mode）
  

--------------------------------------------------

七、适合什么人？

这个项目定位比较明确：

✔ 已经在用 HQPlayer
✔ 有本地音乐库（FLAC / WAV / DSD）
✔ 不想用 Roon（或不想付费）
✔ 想要更“纯”的播放链路

一句话：

• 音质优先的人
  

--------------------------------------------------

八、整体架构（非常简单）

[Jellyfin 音乐库]
        ↓
Jellyfin2HQPlayer（控制层）
        ↓
[HQPlayer]
        ↓
[NAA / DAC]

--------------------------------------------------

九、为什么要做这个？

长期用 HQPlayer，但有两个痛点：

1）HQPlayer 本地界面太简单
2）现有方案要么复杂，要么收费，要么会动播放链路

所以目标很简单：

• 让 Jellyfin 管库
• 让 HQPlayer 专心播放
  

--------------------------------------------------

十、当前状态

- 已可稳定使用
- 支持 Linux / macOS / Windows
- Web 界面控制

插件：

• Jellyfin 插件为跨平台统一包（所有系统通用）
  

--------------------------------------------------

十一、截图



--------------------------------------------------

结尾

纯属个人项目，水平有限，敬请包涵。

欢迎测试
欢迎交流

ytsam

Windows版 Jellyfin2HQPlayer 试用 Quick Start

1、安装 Jellyfin（与 HQPlayer 同一台机器）

详见：https://jellyfin.org/downloads/server

--------------------------
Windows
--------------------------

- 下载并安装 Jellyfin（Windows 版本）
- 启动 Jellyfin 服务
- 浏览器访问：
  http://<IP>:8096

- 完成初始化：
  - 创建管理员账号
  - 添加音乐库（FLAC / WAV / DSD 等）

--------------------------
Linux（Debian / Ubuntu）
--------------------------

- 安装：

  curl -s https://repo.jellyfin.org/install-debuntu.sh | sudo bash

- 启动服务：

  sudo systemctl start jellyfin
  sudo systemctl enable jellyfin

- 浏览器访问：
  http://<IP>:8096

- 完成初始化：
  - 创建管理员账号
  - 添加音乐库（FLAC / WAV / DSD 等）

--------------------------
Linux（Fedora）
--------------------------

- 安装：

  sudo dnf install \
  https://download1.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm \
  https://download1.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm

  sudo dnf install jellyfin

- 启动服务：

  sudo systemctl start jellyfin
  sudo systemctl enable jellyfin

- 浏览器访问：
  http://<IP>:8096

- 完成初始化：
  - 创建管理员账号
  - 添加音乐库（FLAC / WAV / DSD 等）

--------------------------
macOS
--------------------------

- 下载 Jellyfin macOS 安装包（.dmg）
- 拖入 Applications 并启动 Jellyfin.app

- 浏览器访问：
  http://<IP>:8096

- 完成初始化：
  - 创建管理员账号
  - 添加音乐库（FLAC / WAV / DSD 等）

注意：

- Jellyfin 必须与 HQPlayer 在同一台机器
- 音乐库路径需为本地路径（供 HQPlayer 直接读取）
--------------------------------------------------

2、部署 Windows 版 Jellyfin2HQPlayer（主程序）

- 下载发布包
--jellyfin2hqplayer-windows-1.1.0.rar
【https://audiophilestyle.com/applications/core/interface/file/attachment.php?id=133296&key=a94d27134a65d53e48714f534dd83478】

- 解压到目录，例如：
  C:\jellyfin2hqplayer\

目录示例：
  C:\jellyfin2hqplayer\jellyfin2hqplayer-win-x64.exe

- 运行：
  双击 exe 或命令行启动

（可选）指定端口：
  set PORT=8080
  jellyfin2hqplayer-win-x64.exe

- 浏览器访问：
  http://<IP>:3000

--------------------------------------------------

3、部署 Jellyfin 插件（可选）
    ！！先安装 Jellyfin LrcLib Lyrics 插件：在 Jellyfin 插件库中安装并启用 “LrcLib Lyrics”

- 准备文件：
  - deploy-jellyfin-plugin-windows-x64.ps1   
【https://audiophilestyle.com/applications/core/interface/file/attachment.php?id=133297&key=fba076019bc6bf305209aa47f8c103ad】
  - Jellyfin2HQPlayerPlugin-1.0.0.tar.gz
【https://audiophilestyle.com/applications/core/interface/file/attachment.php?id=133298&key=44307269fffb873a3cc695ab3eff983e】
- 在当前目录打开 PowerShell

- 执行：
  Set-ExecutionPolicy -Scope Process Bypass
  .\deploy-jellyfin-plugin-windows-x64.ps1

- 安装完成后重启 Jellyfin

说明：
- 该插件用于建立 Path → ItemId 映射
- 可用于封面、歌词等更准确匹配

--------------------------------------------------

4、连接与使用

- 打开 Jellyfin2HQPlayer Web 页面
- 登录 Jellyfin 服务器
- 选择 HQPlayer 设备
- 开始浏览音乐库并播放

--------------------------------------------------

注意事项

- Jellyfin 与 HQPlayer 必须在同一台机器
- 必须使用本地路径（File Mode）
- 使用前必须先启动 HQPlayer Desktop，否则无法选择播放设备到这里找下载文件包

更多

Jellyfin2HQPlayer – Control HQPlayer from Jellyfin (File-Based, Bit-Perfect Playback) - Software - Audiophile Style

【https://audiophilestyle.com/forums/topic/71901-jellyfin2hqplayer-%E2%80%93-control-hqplayer-from-jellyfin-file-based-bit-perfect-playback/#comment-1337850】

prodomo

好思路，有需求的时候研究一下。

何伯077

谢谢分享，测试中。

ytsam

何伯077 发表于 2026-4-15 15:16
谢谢分享，测试中。

自己做着玩的，主要试用 codex，有问题可以反馈，有工夫就改

何伯077

ytsam 发表于 2026-4-15 15:52
自己做着玩的，主要试用 codex，有问题可以反馈，有工夫就改

听了几首曲。可能心理作用，觉得比ROON+HQplayer音质更好。手机也不用装APP，直接用浏览器操作。

ytsam

何伯077 发表于 2026-4-15 16:03
听了几首曲。可能心理作用，觉得比ROON+HQplayer音质更好。手机也不用装APP，直接用浏览器操作。

和 hqplayer本地播放 完全一样，jellyfin2hqplayer 只是告诉 hqplayer 绝对路径，hqplayer自己去取。

ytsam

补充说明一下：目前除了 Windows 版本外，Linux x64 和 macOS arm64 版本也都已经可用，可按对应平台直接部署使用。
https://audiophilestyle.com/forums/topic/71901-jellyfin2hqplayer-%E2%80%93-control-hqplayer-from-jellyfin-file-based-bit-perfect-playback/#comment-1337850

何伯077

新增专辑。不会自动扫描添加。

ytsam

何伯077 发表于 2026-4-15 20:49
新增专辑。不会自动扫描添加。

设置jellyfin自动扫描
<ip>:8096

路径：
Dashboard → Libraries → 你的音乐库 → Edit

关键选项：

• ✅ Enable real-time monitoring（实时监控）
  
  
  这个受限于jellyfin的自动扫描机制，无效的话只能手动扫描
  

实测 ubuntu server 24.04LTS下的jellyfin 能自动扫描添加

902letter

这个挺好的啊，2个问题请教下，一个是nas映射本地硬盘之后，那还是走的steam/http串流协议；另一个，控制端是web，那么就是手机也可以操作，对吧？

ytsam

902letter 发表于 2026-4-16 10:36
这个挺好的啊，2个问题请教下，一个是nas映射本地硬盘之后，那还是走的steam/http串流协议；另一个，控制端 ...

1、NAS 映射成本地之后走什么协议？
如果 NAS 挂载为本地路径（如 /mnt/music、Z:\music），Jellyfin实际管理的就是 文件路径（Path）；
HQPlayer 实际走的是文件读取（file I/O）
本地和NAS区别就是 本地磁盘和 网络磁盘
2、控制端是 Web，只要有浏览器可以访问Web UI（http://<IP>:3000），任何设备都可以。
手机 Pad 电脑 ....
# Jellyfin2HQPlayer 架构与存储说明

图示 Jellyfin2HQPlayer 的推荐部署方式、控制链路与音频数据路径。

--------------------------------------------------

【部署结构】

- Jellyfin 与 HQPlayer 必须部署在同一台机器（A机）
  → 确保 HQPlayer 能直接访问音频文件

- Jellyfin2HQPlayer Web 服务可以部署在：
  - A机（推荐）
  - 或独立的 B机（远程控制）

- 浏览器（手机 / 平板 / PC）仅作为控制界面
  → 不参与音频数据传输

--------------------------------------------------

【关键点】

控制走网络，音频走本地

- 不走 HTTP 串流
- 不经过 Jellyfin 转码
- HQPlayer 直接读取文件（file I/O）

--------------------------------------------------

【存储方式】

音频文件可以来自：

- 本地磁盘（例如 /local/music）
- NAS（挂载为本地路径，例如 /mnt/NASMusic）

--------------------------------------------------

【推荐顺序】

本地磁盘优先，其次使用 NAS 挂载

--------------------------------------------------

【本地优先的原因】

本地更稳、更低延迟

--------------------------------------------------

【NAS 可用前提】

网络稳定时，NAS ≈ 本地体验

- 有线网络（千兆及以上）
- 低延迟、无抖动
- NAS 不休眠
- 使用 NFS / 优化 SMB

--------------------------------------------------

【总结】

Jellyfin 管库，HQPlayer 本地直读播放，Web 负责控制

ytsam

Update: Jellyfin2HQPlayer Plugin v1.1.0

• Jellyfin 媒体库变化时自动更新路径索引（Path → Id）
• 所有平台统一插件包，按插件部署指南重新部署即可
  

Jellyfin2HQPlayer 插件安装
1、准备文件：
Jellyfin2HQPlayer 插件为跨平台通用包  
Linux / macOS / Windows 共用同一版本插件
- Jellyfin2HQPlayerPlugin-1.1.0.tar.gz
2、Linux x64
安装脚本：
- deploy-jellyfin-plugin-linux-x64.sh
执行：

chmod +x deploy-jellyfin-plugin-linux-x64.sh
sudo ./deploy-jellyfin-plugin-linux-x64.sh

3、macOS arm64
安装脚本：
- deploy-jellyfin-plugin-macos-arm64.sh
执行：

chmod +x deploy-jellyfin-plugin-macos-arm64.sh
./deploy-jellyfin-plugin-macos-arm64.sh

4、Windows
安装脚本：
- deploy-jellyfin-plugin-windows-x64.ps1
在当前目录打开 PowerShell，执行：

Set-ExecutionPolicy -Scope Process Bypass
.\deploy-jellyfin-plugin-windows-x64.ps1

5、验证
http://<IP>:8096  
Dashboard → Plugins → Jellyfin2HQPlayer


6、注意
⚠️ macOS 和 Windows 安装插件前需停止 Jellyfin Server  
⚠️ 安装后必须重启 Jellyfin Server，插件才会生效

所需附件 移步 以下地址 下载
[https://audiophilestyle.com/forums/topic/71901-jellyfin2hqplayer-%E2%80%93-control-hqplayer-from-jellyfin-file-based-bit-perfect-playback/#findComment-1337949]

kentron2011

不采用推送的方式正是我想要的，一个管理，一个直读播放，安排测试

music_forever

在虚拟机ubuntu里试了一下，挺好玩的。
-------
有一点需注意：
Jellyfin与HQPlayer部署在A机后；
Jellyfin2HQPlayer也需要部署在A机，
否则playto无法识别hqplayer。

然后就简单了，在主机下也可以远程操控。
---------

抽空再在windows里试试，如果顺利，感觉可以换掉roon学习版了。

谢谢楼主~

ytsam

music_forever 发表于 2026-4-18 18:00
在虚拟机ubuntu里试了一下，挺好玩的。
-------
有一点需注意：

虚拟机不知道，理论上，hqplayer和jellyfin server必须同机部署；
jellyfin2hqplayer 只要部署在能同时访问hqplayer和jellyfin的节点就可以！

ytsam

music_forever 发表于 2026-4-18 18:00
在虚拟机ubuntu里试了一下，挺好玩的。
-------
有一点需注意：

Jellyfin LrcLib Lyrics 插件
Jellyfin2HQPlayer 插件


2个插件安装后，就可以用歌词。

music_forever

ytsam 发表于 2026-4-18 21:18
Jellyfin LrcLib Lyrics 插件
Jellyfin2HQPlayer 插件

在windows下试了试，可以安装、部署、播放。但是有2个问题求解答：


1.LrcLib Lyrics插件装上了，但是播放时没有歌词显示，server和jf2hq两个web页面里都没歌词啊，什么问题啊？

2.ellyfin2HQPlayer插件装不上。按提示安装流程走了，该重启也重启了，相应目录里也有plugins文件夹。但是在web页面的插件列表里，没有这个插件。不知什么原因...

以上是在win11家庭版下试的。

ytsam

music_forever 发表于 2026-4-18 22:16
在windows下试了试，可以安装、部署、播放。但是有2个问题求解答：

基本可以确定，是插件没有正确安装并加载。
歌词功能依赖两个部分：

• 官方插件：LrcLib
  
• 本项目插件：Jellyfin2HQPlayerPlugin
  
  

两者缺一不可。

---

问题原因：
Jellyfin 插件部署脚本 deploy-jellyfin-plugin-windows-x64.ps1 默认使用的插件目录为：
C:\ProgramData\Jellyfin\Server\plugins
但这个路径只是“默认路径”，在很多情况下，实际插件目录并不在这里，从而导致插件虽然复制了，但 Jellyfin 并没有加载。

---

解决方法：
直接定位 Jellyfin 当前实际使用的插件目录，然后手动部署插件。

---

具体操作：
1、定位插件目录
在文件浏览器中搜索以下任意一个文件：

• Jellyfin.Plugin.MusicBrainz.xml
  
• Jellyfin.Plugin.Tmdb.xml
  
• Jellyfin.Plugin.LrcLib.xml
  
  

找到类似路径：
...\plugins\configurations\Jellyfin.Plugin.MusicBrainz.xml
那么上一级目录：
...\plugins
就是 Jellyfin 实际加载插件的目录（例如：C:\ProgramData\Jellyfin\Server\plugins）

---

2、手动部署插件
在该 plugins 目录下新建新目录：
Jellyfin2HQPlayer
如：C:\ProgramData\Jellyfin\Server\plugins\Jellyfin2HQPlayer
将压缩包 Jellyfin2HQPlayerPlugin-1.1.0.tar.gz 解压后，把里面的文件（注意：！！！不要带外层目录）复制到：
...\plugins\Jellyfin2HQPlayer\
确保 dll 和 deps.json 文件直接在这一层。

---

3、重启 Jellyfin
完成后重启 Jellyfin 服务或程序。

---

总结：
这个问题的根本原因，大概率是“插件放错目录，导致 Jellyfin 根本没有加载到插件”。

music_forever

ytsam 发表于 2026-4-19 08:27
基本可以确定，是插件没有正确安装并加载。
歌词功能依赖两个部分：

感谢耐心解答，应该就是您说的没正确识别插件路径的问题。不想在windows下折腾了，感觉既然都打开HQ软件了，干脆直接浏览更方便。

------


感觉这个东东在linux下更有用，因为可以play to hq embedded ...
不过ubuntu虚拟机下尝试的结果，两个插件都可以安装和识别，但就是不显示歌词。
好在播放音乐没问题，回头继续琢磨琢磨