耳机网-耳机大家坛

标题: Jellyfin2HQPlayer – 基于本地文件直读的 HQPlayer 控制方案（Bit-perfect） [打印本页]
作者: ytsam    时间: 2026-4-15 10:54
标题: Jellyfin2HQPlayer – 基于本地文件直读的 HQPlayer 控制方案（Bit-perfect）
本帖最后由 ytsam 于 2026-4-15 11:17 编辑

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

一直在找一个方案：


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

所以做了这个项目：Jellyfin2HQPlayer

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

一、这是个什么东西？

一句话：


核心不是播放器，而是：


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

二、一个很重要的点


包括：

- HQPlayer Desktop
- HQPlayer Embedded

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

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

三、为什么选 Jellyfin？

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

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

本质上：


另外：


但是问题在于：


所以才有这个项目。

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

四、核心思路

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


而是：


也就是说：

- 文件路径直接交给 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需映射到本机）

原因：


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

七、适合什么人？

这个项目定位比较明确：

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

一句话：


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

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

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

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

九、为什么要做这个？

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

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

所以目标很简单：


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

十、当前状态

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

插件：


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

十一、截图



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

结尾

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

欢迎测试
欢迎交流

作者: ytsam    时间: 2026-4-15 11:03
本帖最后由 ytsam 于 2026-4-15 11:20 编辑

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    时间: 2026-4-15 14:15
好思路，有需求的时候研究一下。
作者: 何伯077    时间: 2026-4-15 15:16
本帖最后由 何伯077 于 2026-4-15 15:18 编辑

谢谢分享，测试中。
作者: ytsam    时间: 2026-4-15 15:52
何伯077 发表于 2026-4-15 15:16
谢谢分享，测试中。

自己做着玩的，主要试用 codex，有问题可以反馈，有工夫就改
作者: 何伯077    时间: 2026-4-15 16:03
ytsam 发表于 2026-4-15 15:52
自己做着玩的，主要试用 codex，有问题可以反馈，有工夫就改

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

和 hqplayer本地播放 完全一样，jellyfin2hqplayer 只是告诉 hqplayer 绝对路径，hqplayer自己去取。
作者: ytsam    时间: 2026-4-15 20:14
补充说明一下：目前除了 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    时间: 2026-4-15 20:49
新增专辑。不会自动扫描添加。
作者: ytsam    时间: 2026-4-15 22:00
本帖最后由 ytsam 于 2026-4-15 22:16 编辑
何伯077 发表于 2026-4-15 20:49
新增专辑。不会自动扫描添加。

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

路径：
Dashboard → Libraries → 你的音乐库 → Edit
关键选项：

实测 ubuntu server 24.04LTS下的jellyfin 能自动扫描添加
作者: 902letter    时间: 2026-4-16 10:36
这个挺好的啊，2个问题请教下，一个是nas映射本地硬盘之后，那还是走的steam/http串流协议；另一个，控制端是web，那么就是手机也可以操作，对吧？
作者: ytsam    时间: 2026-4-16 11:25
本帖最后由 ytsam 于 2026-4-16 13:03 编辑
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    时间: 2026-4-16 17:11
本帖最后由 ytsam 于 2026-4-16 17:12 编辑

Update: Jellyfin2HQPlayer Plugin v1.1.0

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    时间: 2026-4-18 15:29
不采用推送的方式正是我想要的，一个管理，一个直读播放，安排测试
作者: music_forever    时间: 2026-4-18 18:00
本帖最后由 music_forever 于 2026-4-18 18:38 编辑

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

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

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

谢谢楼主~

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

虚拟机不知道，理论上，hqplayer和jellyfin server必须同机部署；
jellyfin2hqplayer 只要部署在能同时访问hqplayer和jellyfin的节点就可以！
作者: ytsam    时间: 2026-4-18 21:18
music_forever 发表于 2026-4-18 18:00
在虚拟机ubuntu里试了一下，挺好玩的。
-------
有一点需注意：

Jellyfin LrcLib Lyrics 插件
Jellyfin2HQPlayer 插件


2个插件安装后，就可以用歌词。
作者: music_forever    时间: 2026-4-18 22:16
ytsam 发表于 2026-4-18 21:18
Jellyfin LrcLib Lyrics 插件
Jellyfin2HQPlayer 插件

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


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

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

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




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

基本可以确定，是插件没有正确安装并加载。
歌词功能依赖两个部分：
两者缺一不可。
问题原因：
Jellyfin 插件部署脚本 deploy-jellyfin-plugin-windows-x64.ps1 默认使用的插件目录为：
C:\ProgramData\Jellyfin\Server\plugins
但这个路径只是“默认路径”，在很多情况下，实际插件目录并不在这里，从而导致插件虽然复制了，但 Jellyfin 并没有加载。
解决方法：
直接定位 Jellyfin 当前实际使用的插件目录，然后手动部署插件。
具体操作：
1、定位插件目录
在文件浏览器中搜索以下任意一个文件：
找到类似路径：
...\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    时间: 2026-4-19 10:56
ytsam 发表于 2026-4-19 08:27
基本可以确定，是插件没有正确安装并加载。
歌词功能依赖两个部分：

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

------


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


作者: ytsam    时间: 2026-4-19 11:07
本帖最后由 ytsam 于 2026-4-19 11:11 编辑
music_forever 发表于 2026-4-19 10:56
感谢耐心解答，应该就是您说的没正确识别插件路径的问题。不想在windows下折腾了，感觉既然都打开HQ软件 ...

1、歌词要确保能搜到；可以在jellyfin官方web 先试试搜不搜得到歌词。ip:8096
2、jellyfin2hqplayer setting页面 显示歌词选项 要打开

作者: music_forever    时间: 2026-4-19 11:35
1. jellyfin官方web 搜不到歌词  



2. jellyfin2hqplayer setting页面 显示歌词选项打开了





作者: music_forever    时间: 2026-4-19 12:15
本帖最后由 music_forever 于 2026-4-19 12:19 编辑

最新情况，可以下载、显示歌词了 （虽然不是所有的歌词都能搜到）



作者: ytsam    时间: 2026-4-19 13:11
本帖最后由 ytsam 于 2026-4-19 13:20 编辑
music_forever 发表于 2026-4-19 12:15
最新情况，可以下载、显示歌词了 （虽然不是所有的歌词都能搜到）

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

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

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

再次感谢~
作者: ytsam    时间: 2026-4-21 20:59
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]
作者: kentron2011    时间: 2026-4-22 09:49
jellyfin2hqplayer有没有可能实现双机应用，一机jellyfin,一机hq。
作者: ytsam    时间: 2026-4-22 17:54
本帖最后由 ytsam 于 2026-4-22 18:16 编辑
kentron2011 发表于 2026-4-22 09:49
jellyfin2hqplayer有没有可能实现双机应用，一机jellyfin,一机hq。

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

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

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

随后会和jussi沟通如何定位并落地异地模式
作者: music_forever    时间: 2026-4-22 20:28
ytsam 发表于 2026-4-22 17:54
可以 但是异地有以下主要问题1、无法实现hqplayer的专辑播放模式
2、DSD大文件体验不好

将来有没有可能，让这个jellyfin帮助HQ识别并播放sacd-iso文件，太需要这个功能了
作者: ytsam    时间: 2026-4-23 06:49
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    时间: 2026-4-23 20:23
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    时间: 2026-4-23 21:06
本帖最后由 ytsam 于 2026-4-23 21:09 编辑

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推送模式）





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

JRiver → HQPlayer
是HTTP Streaming 推送 HQPlayer

所以有所得 有所失
享受了 直读 sacd iso的便利，就得牺牲 不是最Hifi的推送模式 HTTP Streaming
作者: ytsam    时间: 2026-4-25 20:05
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    时间: 2026-4-27 17:21
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    时间: 2026-4-30 11:53
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】
欢迎大家试用、反馈与讨论！

如果有任何问题或需要进一步帮助，随时联系我！
作者: tjlp    时间: 2026-5-10 13:52
双击 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)






欢迎光临 耳机网-耳机大家坛 (http://bbs.erji.net/) Powered by Discuz! X3.2