飞牛音乐 Home Assistant 集成：用 HA 音箱直接播放飞牛曲库
最近把自己一直在用的飞牛音乐接进了 Home Assistant，整理了一下之后发布了第一个正式版本。
当前版本：v1.0.0
需要注意的是：本项目并非把飞牛音乐网页嵌入 Home Assistant，也不是在 HA 里面放一个飞牛音乐的网页链接。
这个集成会直接读取飞牛音乐里的曲库，并通过已经接入 Home Assistant 的音箱 / media_player 实体实际播放音乐。
简单来说就是：
飞牛音乐负责提供曲库、歌曲、专辑、歌手、歌单和歌词，Home Assistant 里已经接入的音箱负责真正播放。
例如你的 DLNA 音箱、智能音箱或者其他已经能够被 HA 控制的 media_player，都可以作为飞牛音乐的播放设备使用。
这样平时就不需要再打开飞牛音乐网页选歌，可以直接在 HA 里完成浏览曲库、选歌和播放。
两种主要使用方式
第一种是把它放在平时使用的 Home Assistant 仪表盘里，作为一个比较紧凑的音乐播放器。
平时只占一小块位置，可以显示封面、歌曲信息、进度和播放控制，也可以切换成歌词模式。
点击封面可以展开当前歌曲页面，点击右上角可以直接打开整个音乐库。
第二种是直接给飞牛音乐单独做一个 Home Assistant 页面。
把 HA 视图设置成“面板”，然后让飞牛音乐卡片占满整个页面，就可以把它当成 HA 里面的一个独立音乐 App 使用。
可以浏览：
并且支持横屏、竖屏和全屏播放界面。
歌词
播放页面支持同步歌词。
有时间轴的歌词可以跟随播放滚动，也可以手动查看。
点击歌词旁边的时间按钮可以直接跳转到对应播放位置。
如果歌词时间稍微有偏差，也提供了提前、延后以及手动设置歌词偏移的功能。
普通纯文本歌词也可以显示，不过因为本身没有时间轴，所以不能自动跟随播放。
独立播放队列
除了界面之外，这个集成也创建了自己的飞牛音乐播放器实体。
每一个选择的 HA 音箱都会对应一个飞牛播放器，并且拥有自己独立的播放队列。
目前队列支持：
- 整张专辑 / 歌单播放
- 追加到队列
- 下一首播放
- 调整歌曲顺序
- 删除歌曲
- 随机播放
- 循环播放
不同音箱的队列互不影响。
例如客厅音箱和卧室音箱可以同时播放完全不同的飞牛音乐内容。
队列在 Home Assistant 重启之后也会保留。
多账号支持
另外也支持同时接入多个飞牛音乐账号。
可以重复添加 FeiNiu Music 集成，每个账号分别拥有自己的曲库入口和播放器实体。
比较适合 NAS 上本身就有多个飞牛音乐用户的情况。
目前使用的是普通飞牛音乐账号登录，暂时不支持 FN ID 和 NAS OAuth。
整个过程中不会修改 NAS 上原来的音乐文件、歌单或者曲库内容。
Home Assistant 原生媒体源
集成同时实现了 Home Assistant 原生的 media_source。
所以即使完全不用我做的音乐卡片，也可以直接在 Home Assistant 自带的媒体浏览器里面看到 FeiNiu Music。
可以直接浏览歌曲、专辑、歌手和歌单，也支持搜索。
同时可以在 Home Assistant 自动化里的“播放媒体”动作中选择飞牛音乐。
如果需要使用这个集成自己的播放队列和自动续播，目标需要选择集成创建出来的飞牛播放器实体。
如果直接让原始音箱实体播放媒体，则只会播放当前选择的这一首歌。
卡片
卡片不需要单独安装。
安装 FeiNiu Music 集成之后，前端卡片也会一起安装并自动注册。
然后在 Home Assistant 仪表盘里直接：
添加卡片 → FeiNiu Music
就可以通过可视化编辑器配置。
目前可以设置紧凑播放器、歌词播放器、自动模式、固定背景、封面氛围背景、柔和蒙版、透明玻璃效果、深色 / 浅色主题等。
安装方法
目前主要推荐 HACS。
接下来选择希望用来播放音乐的 Home Assistant 音箱。
配置完成后，就会为这些音箱生成对应的飞牛音乐播放器实体。
这里有一个比较重要的地方
卡片和完整音乐页面选择的播放器，必须是 FeiNiu Music 集成为音箱生成的播放器实体，而不是原来的音箱实体。
例如原来 HA 里面有：
media_player.ke_ting_yin_xiang
添加飞牛音乐之后，还会生成一个对应的飞牛播放器。
平时在飞牛音乐卡片、播放队列和完整音乐页面里使用的是后者。
最终真正发声的仍然是原来的 HA 音箱。
这样集成才能在中间负责管理飞牛音乐曲库、播放队列和自动切歌。
兼容性与已知说明
目前需要 Home Assistant 2026.9.4 或更新版本。
播放器本身的一些能力仍然取决于底层音箱以及对应的 Home Assistant 集成，例如暂停、播放进度跳转、音量控制、音频格式支持以及播放状态反馈。
这个项目本身不会对音频进行转码。
目前我实际测试比较多的是 EDIFIER MA3 / DLNA。
其他已经接入 Home Assistant 的 media_player 理论上也可以使用，不过不同设备对播放状态、Seek、媒体格式等支持会有差异。
如果遇到歌曲加载后不播放、歌曲播完不能自动切下一首等情况，集成设置里面也提供了针对单个播放器的“起播与续播设置”。
反馈
这个项目目前刚刚发布第一个正式版本，肯定还有很多设备和使用场景没有测试到。
如果大家有飞牛 NAS，同时家里又有已经接入 Home Assistant 的音箱，可以帮忙测试一下。
特别欢迎反馈不同品牌、不同接入方式的播放器兼容情况。目前已经在GitHub开源。
遇到问题可以直接提 Issue，最好附上：
- Home Assistant 版本
- 飞牛音乐版本
- 音箱型号
- 音箱在 HA 中使用的集成
- 具体操作步骤
目前先发第一个版本，后面会继续完善。
| 
发表于 
