给 Jellyfin 装上空间声学校正系统

空间大师开发者简介：影院院线影音技术指导总监、原EMMA国际汽车音响联盟裁判、音响影音爱好者、nas玩家

空间声学校正系统空间大师（spacemaster）的音效优化引擎由原EMMA国际汽车音响联盟裁判调试。它是一款给Jellyfin 做空间声学校正的小工具，开源、免费而且完全不动您原有的 Jellyfin。作者鉴于nas音频输出方式有限，播放nas里的电影、音乐都总觉得音质一般，达不到自己想要的效果，于是开发了这款小工具自用，加强了声像结像度、层次感、定位感、环绕氛围感。用下来感觉也算是满意（基于非专业音响设备与非经过声学处理的听音空间环境比较），分享给所有喜爱影音的玩家，希望也能为大家在不用额外增加音频解码硬件成本的情况下带来解决空间声学烦恼的一个小方案。个人把玩小工具，如有瑕疵请跟帖指教提出宝贵意见，感恩。

一、空间大师是什么

简单说，空间大师是 Jellyfin 的音频校正附加层。您在网页版空间大师控制台里填一次房间尺寸，往后所有转码播放的声音，都会按您这间屋子的空间声学特性做过校正，当然，您也可以在控制台做适合自己聆听风格的调整。

1）根据空间计算建立PEQ 推荐值基底 在控制台填房间长宽高、喇叭距离等参数，空间大师会用声学算法算出并经过作者调试优化后的参量均衡（PEQ）推荐值作为音效基底。您也可以在此基底上手动微调，调到自己喜欢风格的声音。

2）延时校准（声道延迟补偿） 针对不同喇叭的功率、摆位和角度，手动调整声道延迟补偿，消除声波反相导致的「空洞感」，让声像定位更清晰、结像更准确。目前独立 2.0 / 2.1 音箱已可用，5.1 系统正在优化中。

3）空间大师和 Jellyfin 的关系 空间大师不是 Jellyfin 的修改版，也不替换它，只是在它外面套一层。您原有的 Jellyfin 镜像、媒体库、配置一律不动；卸掉它或者直接访问jellyfin原地址，Jellyfin音效立刻回到原版。

4）只做转码音频，其它功能都不受影响 空间大师只做转码音频工作，Jellyfin 的字幕 / 刮削 / 元数据 / 媒体库 / 用户记录等其它功能均不受影响。字幕烧录、外挂字幕、刮削识图、播放记录全都照常，不会改动或减少任何功能。

空间大师完全免费分享。

二、在 NAS 上安装（Docker 环境）

前提：您已经在 NAS 上用 Docker 跑着 Jellyfin（jellyfin/jellyfin 或 nyanmisaka/jellyfin 镜像）。空间大师是在它外面加一层音效，不修改 Jellyfin 本体。

很简单，安装一个音效调整页面和一个负责电影播放的代理页面即可（访问此代理页面走空间大师音效，访问jellyfin原页面走原始音效）。下面分三步，全部在您 NAS 的 Docker 图形界面（如群晖 Container Manager、飞牛 Docker、Portainer 等）里点选完成，不需要敲命令。

第 1 步｜拉取镜像

镜像地址（复制这一行）：

ghcr.io/gd-benzz/spacemaster-fnos:v3

在您 NAS 的 Docker 界面里添加镜像，把上面的地址粘贴进去拉取。

第 2 步｜部署（三个容器）

先在您 NAS 上建一个共享文件夹 smdata（路径自定义，例如 /docker/smdata），控制台和 Jellyfin 会共用它存音效参数和日志。名字可自定义，下文统一叫 smdata。

（1）创建控制台容器 spacemaster-console

镜像：spacemaster-fnos:v3

容器名：spacemaster-console（可自定义）

启动命令：保持默认 python3 /opt/sm/peq_toggle_nas.py，不用改

端口：容器 8777 → 主机 8777

存储：挂载 smdata → /opt/sm（读写）

部署后，浏览器打开 http://<您的NAS内网IP>:8777 应看到控制台页面。

（2）修改 Jellyfin 容器

先停止 Jellyfin 容器。

编辑 Jellyfin 容器，加两项：
- 存储：添加挂载 smdata → /opt/sm（读写）
- 环境变量：找到 JELLYFIN_FFMPEG 这一项
  - 有这一项 → 把值改成 /opt/sm/sm_wrapper.sh（只改值，不删该项，它是官方镜像自带变量）
  - 假如没有 → 新增变量，名称 JELLYFIN_FFMPEG，值 /opt/sm/sm_wrapper.sh

保存并启动。

注意启动顺序：先启动控制台（1），确认 smdata 目录里生成了 sm_wrapper.sh 等文件，再启动 Jellyfin（2）。顺序反了，Jellyfin 启动时找不到 sm_wrapper.sh 会报错。

（3）创建代理容器 spacemaster-proxy（必须安装） 以后看电影访问代理的端口地址，音效被空间大师优化；直接访问 Jellyfin 原端口地址，音效不被空间大师优化。

镜像：spacemaster-fnos:v3

容器名：spacemaster-proxy

端口：容器 8097（proxy 自身监听端口，可自定义）→ 主机 8097（proxy 访问端口，需确保没被占用，可自定义）

存储：挂载 smdata → /opt/sm（读写）

环境变量：新增两条
- SM_ROLE = proxy
- UPSTREAM = http://<您的NAS内网IP>:（平时访问 Jellyfin 的 IP 地址+端口，必须带 http:// 前缀；Jellyfin 默认端口是 8096）

启动命令：填 python3 /opt/sm/profile-proxy.py（先把栏里默认的控制台命令删掉，再填这一行）

注意：把您看电视 / 播放用的 Jellyfin 客户端里的「服务器地址」，从原来的 Jellyfin 端口改成上面代理的「主机端口」（例：http://<您的NAS内网IP>:8097）。

各 NAS 的 Docker 图形界面入口不同，但填写项一致：在镜像 / 容器创建页里，依次填基本设置 / 网络端口 / 存储位置 / 环境变量即可。

第 3 步｜验证是否生效

进入 spacemaster-proxy 网址（例：http://<您的NAS内网IP>:8097）播放一部电影，然后到您 NAS 的文件管理器，查看 smdata/wrapper.log（就是您建的共享文件夹子目录），里面出现 WRAP injected AF 一行，就代表音效已成功注入。

三、排查问题

8777 控制台打不开 控制台容器没起来，或端口冲突。看容器日志；或在端口设置里换一个主机端口再试。

wrapper.log 里没有 WRAP injected AF 说明 PEQ 没开 / 环境变量没生效。处理：

到空间大师控制台（8777）把 PEQ 开关打开；

确认 Jellyfin 容器里环境变量名拼写是 JELLYFIN_FFMPEG；

重启 Jellyfin；

确认 spacemaster-proxy（代理容器）的启动命令是 python3 /opt/sm/profile-proxy.py。

改完参数不生效 没点保存 / 没重播。在 8777 点「保存配置」，然后退出影片重新播放（每次修改参数后必须保存并重新播放影片）。

spacemaster-proxy代理端口访问不了 大概率是 UPSTREAM 少了 http:// 前缀或者没有按（3）加代理 spacemaster-proxy（必须安装）说明把“启动命令：改为python3 /opt/sm/profile-proxy.py”，补上再重启代理容器即可。

空间大师只动声音这一条线，装错了也不会把您的 Jellyfin 搞崩（引擎缺失时自动原样透传，只是没音效校正效果）。祝大家观影愉快，有问题欢迎回帖交流。