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

Jellyfin2HQPlayer v1.3.5 发布

大家好，

我已经发布了 Jellyfin2HQPlayer v1.3.5。

该版本主要改善了Jellyfin与HQPlayer之间的浏览和播放体验，尤其适合偏好基于文件夹的音乐库导航的用户。

v1.3.5 的主要更新
1. 新文件夹视图
新增了一个基于文件夹的浏览视图，允许用户更接近原始文件夹结构的 Jellyfin 音乐库。

2. 改进专辑/曲目格式显示
专辑和曲目格式信息现在显示得更清晰，包括PCM / DSD格式详情（如有）。

3. 改进的播放视图/音量控制
播放视图和HQPlayer音量控制得到了改进，音量显示更加清晰。

4. 其他改进与漏洞修复
本次发布还包括多项用户界面改进和漏洞修复。

Jellyfin2HQPlayer 仍是一种变通式集成，因为 Jellyfin 与 HQPlayer 之间仍存在一些关联限制。我希望v1.3.5能提供更流畅的体验，尤其是在文件夹浏览和HQPlayer播放控制方面。

一些发烧友已经给出了非常积极的反馈，尤其是在Jellyfin2HQPlayer的本地文件推送模式上。

[https://github.com/YTSamLee/jellyfin2hqplayer/releases/tag/v1.3.2]
我希望这个版本对想将Jellyfin的音乐库管理与HQPlayer播放引擎结合起来的用户有所帮助。

ytsam

tjlp 发表于 2026-5-20 09:50
是的，不用管它也能正常播放。

windows 下可以建立 任务，开机后台运行。可以看windows下对应中文部署说明
【https://github.com/YTSamLee/jellyfin2hqplayer】

tjlp

ytsam 发表于 2026-5-20 08:24
erji.net 终于康复了
这个现象是正常的，第一次运行默认hqplayer 地址为本机，127.0.0.1

是的，不用管它也能正常播放。

ytsam

tjlp 发表于 2026-5-10 13:52
双击 jellyfin2hqplayer-win-x64.exe出现下情况是何原因
[hqp-config]:hqplayers.json 文件不存在，使用默 ...

erji.net 终于康复了
这个现象是正常的，第一次运行默认hqplayer 地址为本机，127.0.0.1

tjlp

双击 jellyfin2hqplayer-win-x64.exe出现下情况是何原因
[hqp-config]:hqplayers.json 文件不存在，使用默认 HQP_HOST
[hqp-status] start() host=127.0.0.1:4321
[hqp-status] connecting to 127.0.0.1:4321
13:41:42.737 [ws-status] ready
13:41:42.740 [ws-metering] ready
[server] http://0.0.0.0:3000
[server]:ws://0.0.0.0:3000/ws/status
[server]:ws://0.0.0.0:3000/ws/spectrogram?mode=json&topic=all
[hqp-status] connected, send <Status subscribe="1"/>
[hqp-status] state => connected (lastSeen=0ms)

ytsam

Jellyfin2HQPlayer v1.3.0 正式发布！

大家好，

很高兴向大家宣布 Jellyfin2HQPlayer v1.3.0 已经在 GitHub 正式发布！

&#128073; GitHub Release 页面（含下载和说明）：
YTSamLee/jellyfin2hqplayer: A web-based control interface designed for seamless integration between Jellyfin and HQPlayer.
【https://github.com/YTSamLee/jellyfin2hqplayer】
欢迎大家试用、反馈与讨论！

如果有任何问题或需要进一步帮助，随时联系我！

ytsam

Jellyfin2HQPlayer 下一个版本预告：

打通 Jellyfin 与 HQPlayer 的文件桥接：
完全整合 HQPlayer 的高品质音频播放与 Jellyfin 的丰富音乐元数据。
利用 Discogs 和 MusicBrainz 等插件，提供更加详细和丰富的音乐资料。
动态歌词支持，在播放过程中实时显示歌词，让您更好地沉浸在音乐世界中。
播放模式支持：
本地模式，提供无损从本地文件播放。
HTTP文件模式，复刻 UPnP + HQPlayer API 模式，通过 HTTP 文件流传输，使得在不同设备和环境下也能轻松享受 HQPlayer 的高品质音频播放。
HTTP流模式，支持流媒体播放，确保您能够在多种设置下获得最佳体验。

这个版本让您不仅能够体验到 HQPlayer 的高保真音质，还能通过灵活的播放模式，轻松连接到 Jellyfin 的丰富音乐库与元数据，带来更全面的音乐享受
https://audiophilestyle.com/forums/topic/19715-hq-player/page/1551/#findComment-1338837

ytsam

Jellyfin2HQPlayer Plugin 1.2.5 正式支持标准 Jellyfin Plugin Repository 部署方式

Jellyfin2HQPlayer Plugin 1.2.5 已上传至 GitHub。

现在已经完全采用 Jellyfin 官方标准插件安装与部署流程，无需再手动复制 DLL 文件到 plugins 目录。

============================================================

该插件用于建立：

Audio 文件路径 → Jellyfin ItemId

映射关系，并提供 REST API 查询路由供外部应用与 HQPlayer 集成调用。

GitHub 项目地址：
https://github.com/YTSamLee/Jellyfin2HQPlayer-plugin

安装步骤：

1. 打开 Jellyfin Dashboard → Plugins

2. 点击右上角：

Manage Repositories

3. 添加插件仓库

Repository Name：

Jellyfin2HQPlayer

Repository URL：

https://raw.githubusercontent.com/YTSamLee/Jellyfin2HQPlayer-plugin/main/manifest.json

4. 保存后刷新 Jellyfin 页面

5. 返回 Plugins 页面

6. 在 Available 中找到：

Jellyfin2HQPlayer

7. 点击 Install 安装插件

8. 安装完成后重启 Jellyfin

Linux：

sudo systemctl restart jellyfin

安装完成后：

Dashboard → Plugins → My Plugins → Jellyfin2HQPlayer

可以看到插件设置页面，包括：

* 插件 READY 状态
* 已索引 Audio 文件数量
* Total Audio Count
* Last Updated 时间
* Rebuild 重建索引按钮

ytsam

ytsam 发表于 2026-4-23 06:49
目前jellyfin2hqplayer不支持,除非将来jellyfin有原生支持sacd iso 的插件。
HQPlayer 本身不识别 SACD  ...

JRiver → HQPlayer
是HTTP Streaming 推送 HQPlayer

所以有所得 有所失
享受了 直读 sacd iso的便利，就得牺牲 不是最Hifi的推送模式 HTTP Streaming

ytsam

HQPlayer 播放方式汇总
==================================================

一、文件模式（File mode）
最干净、bit-perfect最佳

核心：
HQPlayer 自己读取数据（pull，可随机访问）

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

1）file:// 本地文件

file:///music/xxx.flac

✔ HQPlayer 直接读取本机磁盘
✔ 完整控制解码 / buffer / 时钟
✔ 100% bit-perfect
✔ 性能最稳定（无网络依赖）

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

2）file:// 挂载文件（NAS / 网络盘）

file:///mnt/nas/music/xxx.flac

✔ 本质仍是文件模式（与本地一致）
✔ 支持 NFS / SMB / SSHFS

差异点：
- IO 通过网络
- 性能取决于网络稳定性 / 带宽 / 延迟

✔ 音质层面仍为 bit-perfect（无转码前提下）

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

二、HTTP File stream

特征：
✔ 不转码（原始数据）
✔ HQPlayer 主动 pull
✔ HQPlayer 掌控读取（buffer / 节奏）
✔ 可按需读取（想读多少读多少）

本质：
✔ stream-like（传输是流）
✔ file-like（控制在 HQPlayer）

→ File mode

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

三、HTTP Generic stream

特征：
✔ HTTP pull（形式一样）

但：
❌ 可能转码 / 实时流
❌ HQPlayer 无法掌控读取
❌ 只能顺序跟随数据
❌ 通常不可 seek

本质：
✔ stream-like（传输是流）
❌ non-file-like（控制不在 HQPlayer）

→ Streaming mode

==================================================
常见播放器归类

1）本地播放
属于  模式一（file:// 本地）,bit-perfect

如HQPlayer Client 的 HQPlayerLibrary播放、HQPDcontrol的HQPlayer Library播放、HQPPorter的 Local+HQPlayer Library播放

2）Roon 推送
属于模式三（HTTP Generic stream），非 file-mode（不保证 bit-perfect）

（RAAT，本质 streaming）

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

3）UPnP资源浏览+HQPlayer API 推送
属于 模式二（HTTP File stream），file-mode，bit-perfect
  bit-perfect 前提：upnp server 不转码

如：JPlay HQPlayer API 推送模式、HQPPorter的UPnP资源浏览+HQPlayer API 推送模式

4）通用 UPnP Control Point 推送（Renderer）
属于 模式三（Streaming），不保证 bit-perfect
存在 bit-perfect 风险（取决于 upnp server）

如 BubbleUPnP、 mConnect 、JPlay传统模式

--------------------------------------------------
5）Jellyfin2HQPlayer
支持  Local file播放 + UPnP资源浏览+HQPlayer API 推送模式
支持 模式一  和 模式二， bit-perfect
jellyfin2hqplayer 基本确认支持 HTTP file stream 模式，
也就是 除 本地模式 （file://）之外， 第二 bit-perfect 的播放模式（类 JPlayer 的 HQPlayer API推送模式）

music_forever

ytsam 发表于 2026-4-23 06:49
目前jellyfin2hqplayer不支持,除非将来jellyfin有原生支持sacd iso 的插件。
HQPlayer 本身不识别 SACD  ...

嗯嗯，按说hq能播放dsf，而sacd-iso又能提取出dsf，技术上应该行得通啊。不知原创大佬们为啥不搞搞直读iso的功能...

现在是本地播flac，或者foobar推flac给HQ。

要想听sacd，只能用jriver推dsd到HQ了，费劲。

ytsam

music_forever 发表于 2026-4-22 20:28
将来有没有可能，让这个jellyfin帮助HQ识别并播放sacd-iso文件，太需要这个功能了

目前jellyfin2hqplayer不支持,除非将来jellyfin有原生支持sacd iso 的插件。
HQPlayer 本身不识别 SACD ISO；
Jellyfin 目前也无法以原始 DSD 方式按轨输出 ISO 内容。
目前如果要用，只能先把 ISO 转成 DSF/DFF。

music_forever

ytsam 发表于 2026-4-22 17:54
可以 但是异地有以下主要问题1、无法实现hqplayer的专辑播放模式
2、DSD大文件体验不好

将来有没有可能，让这个jellyfin帮助HQ识别并播放sacd-iso文件，太需要这个功能了

ytsam

kentron2011 发表于 2026-4-22 09:49
jellyfin2hqplayer有没有可能实现双机应用，一机jellyfin,一机hq。

可以 但是异地有以下主要问题1、无法实现hqplayer的专辑播放模式
2、DSD大文件体验不好

原来支持，让我把设置界面的设置卡片隐藏了。

异地模式 类似upnp/dlna+hqplayer API 模式（同jplay);

随后会和jussi沟通如何定位并落地异地模式

kentron2011

jellyfin2hqplayer有没有可能实现双机应用，一机jellyfin,一机hq。

ytsam

Jellyfin2HQPlayer – v1.2.0

==================================================
更新内容
==================================================

- 新增 Web 浏览器预览播放
  浏览器中预览，HQPlayer 中播放（Preview in browser, play in HQPlayer）

- 修复多个问题
  （播放控制、UI 交互、预览播放逻辑）


==================================================
快速开始（Linux x64）
==================================================

1. 安装并初始化 Jellyfin

按照 Jellyfin 官网指导完成 Jellyfin Server 安装：
https://jellyfin.org/downloads/linux

浏览器打开：
http://<IP>:8096

完成初始化（创建账号 + 添加音乐库）

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

2. 部署 Jellyfin2HQPlayer

准备文件：

- jellyfin2hqplayer-linux-x64-1.2.0.tar.gz
- deploy-jellyfin2hqplayer-linux-x64.sh

运行：

chmod +x deploy-jellyfin2hqplayer-linux-x64.sh
sudo ./deploy-jellyfin2hqplayer-linux-x64.sh

（可选端口）
sudo PORT=8080 ./deploy-jellyfin2hqplayer-linux-x64.sh

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

3. 打开 Web 界面

http://<IP>:3000

首次使用：

- 登录 Jellyfin
- 选择 HQPlayer（Play To）

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

4. 播放

- 浏览音乐库
- 选择曲目 / 专辑
- 点击 Play
- 支持浏览器预览播放（Preview play in browser）
- 由 HQPlayer 本地直读播放（File Mode）

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

5.（可选）插件

5.1 歌词插件（LrcLib Lyrics）

用于歌词显示

5.2 Jellyfin2HQPlayer 插件（Path → ID 映射）

准备文件：

- deploy-jellyfin-plugin-linux-x64.sh
- Jellyfin2HQPlayerPlugin-1.1.0.tar.gz

运行：

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

安装后重启 Jellyfin

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

注意

- 使用前必须先启动 HQPlayer 和 Jellyfin Server
- Jellyfin 与 HQPlayer 必须在同一台机器


==================================================
快速开始（Windows x64）
==================================================

1. 安装并初始化 Jellyfin

按照 Jellyfin 官网指导完成 Jellyfin Server 安装：
https://jellyfin.org/downloads/windows

浏览器打开：
http://<IP>:8096

完成初始化（创建账号 + 添加音乐库）

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

2. 部署 Jellyfin2HQPlayer

准备文件：

- jellyfin2hqplayer-windows-1.2.0.rar

解压到目录，例如：

C:\jellyfin2hqplayer\

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

3. 运行程序

双击运行：

jellyfin2hqplayer-win-x64.exe

或命令行：

.\jellyfin2hqplayer-win-x64.exe

（可选端口）

set PORT=8080
.\jellyfin2hqplayer-win-x64.exe

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

4. 打开 Web 界面

http://<IP>:3000

首次使用：

- 登录 Jellyfin
- 选择 HQPlayer（Play To）

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

5. 播放

- 浏览音乐库
- 选择曲目 / 专辑
- 点击 Play
- 支持浏览器预览播放（Preview play in browser）
- 由 HQPlayer 本地直读播放（File Mode）

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

6.（可选）插件

6.1 歌词插件（LrcLib Lyrics）

用于歌词显示

6.2 Jellyfin2HQPlayer 插件（Path → ID 映射）

准备文件：

- deploy-jellyfin-plugin-windows-x64.ps1
- Jellyfin2HQPlayerPlugin-1.1.0.tar.gz

PowerShell 运行：

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

安装后重启 Jellyfin

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

注意

- 使用前必须先启动 HQPlayer 和 Jellyfin Server
- Jellyfin 与 HQPlayer 必须在同一台机器
- 如无法访问，请检查 Windows 防火墙端口（默认 3000）


==================================================
快速开始（macOS ARM64）
==================================================

1. 安装并初始化 Jellyfin

按照 Jellyfin 官网指导完成 Jellyfin Server 安装：
https://jellyfin.org/downloads/macos

浏览器打开：
http://<IP>:8096

完成初始化（创建账号 + 添加音乐库）

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

2. 部署 Jellyfin2HQPlayer

准备文件：

- jellyfin2hqplayer-macos-arm64-1.2.0.tar.gz
- deploy-jellyfin2hqplayer-macos-arm64.sh

在终端执行：

chmod +x deploy-jellyfin2hqplayer-macos-arm64.sh
./deploy-jellyfin2hqplayer-macos-arm64.sh

!! 不要使用 sudo

（可选端口）

PORT=8080 ./deploy-jellyfin2hqplayer-macos-arm64.sh

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

3. 打开 Web 界面

http://<IP>:3000

首次使用：

- 登录 Jellyfin
- 选择 HQPlayer（Play To）

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

4. 播放

- 浏览音乐库
- 选择曲目 / 专辑
- 点击 Play
- 支持浏览器预览播放（Preview play in browser）
- 由 HQPlayer 本地直读播放（File Mode）

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

5.（可选）插件

5.1 歌词插件（LrcLib Lyrics）

用于歌词显示

5.2 Jellyfin2HQPlayer 插件（Path → ID 映射）

准备文件：

- deploy-jellyfin-plugin-macos-arm64.sh
- Jellyfin2HQPlayerPlugin-1.1.0.tar.gz

运行：

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

安装后重启 Jellyfin

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

注意

- 使用前必须先启动 HQPlayer 和 Jellyfin Server
- Jellyfin 与 HQPlayer 必须在同一台机器


==================================================
插件手动部署（非自动化）
==================================================

如插件未加载或自动部署失败，请参考19楼 手动部署方法

下载附件移步

[https://audiophilestyle.com/forums/topic/71901-jellyfin2hqplayer-%E2%80%93-control-hqplayer-from-jellyfin-file-based-bit-perfect-playback/#findComment-1338352]

music_forever

ytsam 发表于 2026-4-19 13:11
歌词有没有 完全依赖LrcLib Lyrics插件
国语基本不可能。下载后歌词应该在目录 ...

可能跟搜索的格式有关吧，反正歌词不是重点，聊胜于无

再次感谢~

ytsam

music_forever 发表于 2026-4-19 12:15
最新情况，可以下载、显示歌词了 （虽然不是所有的歌词都能搜到）

歌词有没有 完全依赖LrcLib Lyrics插件
国语基本不可能。下载后歌词应该在目录下，可以对照格式自己编辑