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

ytsam

music_forever 发表于 2026-4-19 10:56
感谢耐心解答，应该就是您说的没正确识别插件路径的问题。不想在windows下折腾了，感觉既然都打开HQ软件 ...

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

music_forever

1. jellyfin官方web 搜不到歌词  



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

music_forever

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

ytsam

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

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

music_forever

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

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

再次感谢~

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]

kentron2011

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

ytsam

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

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

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

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

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

music_forever

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

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

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-23 06:49
目前jellyfin2hqplayer不支持,除非将来jellyfin有原生支持sacd iso 的插件。
HQPlayer 本身不识别 SACD  ...

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

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

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

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

ytsam

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

JRiver → HQPlayer
是HTTP Streaming 推送 HQPlayer

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

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

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