本帖最后由 neqq3 于 2025-12-15 02:19 编辑
2025.12.11更新 音质配置，尽量适配lyrics-card与播放链路优化 2025.12.12 - 更新自动化服务与 API 支持 2025.12.13 - 更新前端页面 https://bbs.hassbian.com/thread-30903-1-1.html 2025.12.14- 更新歌词卡片 2025.12.15 - 私人 FM 与默认播放器配置
前言 各位坛友大家好， 大家应该都在用社区大神的网易云音乐集成（ha_cloud_music）。我自己也是这个插件的重度用户，非常感谢原作者 shaonianzhentan 的开发。 最近升级到 Home Assistant 2025.12 版本后，发现原插件因为底层改动暂时无法添加实体了。因为我每天都要用它听歌，实在离不开，就自己动手 Fork 了一份代码进行修复。 关于这个版本 本人是 HA 开发方面的新人小白，第一次尝试对集成做这么大的改动。代码里可能有很多不成熟的地方。如果有什么做得不对的地方，还请各位大佬提醒，我会虚心接受批评。 在修复兼容性的过程中，顺手把自己平时使用中遇到的一些痛点（比如随机播放有时候会重复、搜索不太方便等）按自己的习惯改了一下。 想着可能也有朋友遇到同样的问题，就分享出来给需要临时过渡或者尝鲜的朋友试用。 如果原作者更新了，建议大家还是以原版为准。 特别致谢 本项目基于 shaonianzhentan 的原版代码(https://github.com/shaonianzhentan/ha_cloud_music)。 同时，切歌逻辑与计时逻辑的优化，参考借鉴了 IsCoding666 大佬的 Fork 版本（https://github.com/lsCoding666/ha_cloud_music）。 在此向两位前辈致以诚挚的谢意！ 项目地址 GitHub 链接： https://github.com/neqq3/ha_ncloud_music (支持通过 HACS > 集成 > 右上角自定义仓库 添加)
主要修改内容 主要是为了解决我自己的几个痛点： 1. 优化了“随机播放”逻辑 原版的随机播放是即时随机，有时候运气不好会听到重复的歌。我参考一般的音乐播放器的逻辑改了一下：
2. 调整了搜索体验 把搜索逻辑做得更原生了一点：
3. 优化切歌与计时逻辑 参考了 IsCoding666 的代码方案，优化了切歌时的逻辑判断和播放器的时间同步机制，让播放体验更顺滑一些。也方便以后做歌词滚动或者逐字变色之类的功能。 4. 修复 HA 2025.12+ 兼容性
关于后续 目前这个版本在我自己机器上跑得还算稳定。我是 前面的版本不知道能不能通用，我没试过，理论上也许可行？ 歌词功能 目前还在新建文件夹中... 后端解析得差不多了，我有空再慢慢研究。
安装与迁移方法 本项目还在测试当中，请务必备份！ 为了防止配置冲突，强烈建议按以下步骤操作： 重要提示 文档滞后：GitHub 仓库里的 README 文档没改，显示的还是原作者的文档，请大家以帖子里的介绍为准。 如果有 Bug 欢迎反馈，但我能力有限，不一定能修得很快，大家轻喷。 再次感谢原作者shaonianzhentan和IsCoding666 大佬提供的优秀基础！
2025.12.11更新 音质配置，尽量适配lyrics-card与播放链路优化
1. 首选音质配置 新增“首选音质”配置项，支持对播放流媒体的编码格式与码率进行精细化控制。 - 多级音质支持：支持从标准至母带级共 9 种规格的音质选项。
- 权益自动协商：播放器将根据当前登录账号的权益配置，自动请求该权益范围内的最高可用音质。
- 视觉分级提示：配置界面采用可视化符号（⚪/🔴/👑）标识不同码率等级的硬件解码需求与带宽负载情况
2. 播放可用性增强 从api项目调用unblock。
重构了底层音频流获取逻辑，引入了多级链路容错机制，显著降低了播放失败率。 - 链路自动寻址：当主播放链路响应超时、连接重置或仅返回试听片段时，系统将自动尝试备用路由策略。
- 异常自动降级：在遇到网络波动或源文件不可访问时，播放器可自动切换至高可用链路，确保播放不中断。
3. 歌词组件同步适配 尽量针对 lyrics-card 组件进行了协议层面的适配与优化。 - 尽量修复了在手动拖拽进度条或跳转播放时，歌词时间戳与音频流不同步的问题（该有不同步还是有，只是现在切歌之类的情况下能尽量保持不同步的一致，不会一会快一点，一会慢一点）。
- 优化了歌词传输协议，减少前端渲染抖动。
4. 状态响应性能提升 优化了 media_player 实体的状态机轮询逻辑。 - 切歌时的元数据（封面、标题、艺术家）加载延迟大幅降低，提升了 UI 交互的流畅度。
改进与修复- 国际化支持：规范了 zh-Hans 与 en 语言文件，优化了配置界面的文案指引。
- 代码重构：移除冗余的调试代码，优化了异步方法的调用开销。
升级说明- 建议升级后重启 Home Assistant 以加载新的配置选项。
- 新的音质选项位于集成“选项”页面中，默认为“极高 (320k)”。
2025.12.12 - 自动化服务与 API 支持v1.3.3 本版本新增了标准 Home Assistant 服务调用（Service Calls）支持，并开放了 HTTP 数据接口。 主要更新 1. 新增自动化服务 (Service Calls) 为了解决之前版本只能通过 UI 实体（输入框+按钮）进行控制的不便，本版本注册了以下标准服务，支持在 自动化 (Automation)、脚本 (Script) 和 语音助手 中直接调用： - ha_ncloud_music.search (搜索并播放)
- 输入关键词和类型（单曲/歌单/电台/专辑/歌手），自动播放搜索结果的第一项。
- 适用场景：语音控制“播放奥特曼的歌”。
- ha_ncloud_music.play_by_id (ID 播放)
- ha_ncloud_music.play_daily / play_favorites
2. 开放 HTTP API (开发者选项) 新增 Layer 2 HTTP 接口，用于绕过 WebSocket 获取大数据量信息（供前端卡片开发使用，普通用户可忽略）： - /cloud_music/api?action=lyric&id=xxx: 获取完整歌词数据（LRC/YRC）。
- /cloud_music/api?action=song_detail&id=xxx: 获取歌曲详情元数据。
使用示例 YAML 自动化配置： 无需再编写复杂的 text.set_value 和 button.press 序列，现在仅需一步：
<blockquote>action: ha_ncloud_music.search
同时，也支持可视化配置自动化：
升级说明 - 原有 UI 实体（Text/Button）依然保留，仅建议在 Dashboard 手动操作时使用。
- 建议将现有的自动化脚本迁移至新的 Service Call 方式。
- 升级后请重启 Home Assistant。
2025.12.13 - 更新前端页面 https://bbs.hassbian.com/thread-30903-1-1.html
## 主要功能
1. **歌词同步与微调**：支持全屏显示，**重点是加了歌词偏移调整**。因为网络传输或者 DLNA 推送经常会有延迟，导致歌词对不上，界面上可以直接微调（±0.1s, ±1s 等），手动对齐。
2. **直接控制 HA 播放器**：前端直接控制HA里的媒体播放器，切歌、暂停、进度调整、音量控制都很跟手。
3. **设备切换**：可以直接在界面上选择设备。
4. **侧边栏支持**：可以集成到 HA 的左侧菜单栏，点击即用。
2025.12.14- 更新歌词卡片 依赖 此卡片需配合 ha_ncloud_music 集成使用。 安装
HACS（推荐）
- 打开 HACS → 前端
- 点击右上角 ⋮ → 自定义存储库
- 添加 https://github.com/neqq3/ha_ncloud_music_card，类别选择「Dashboard」
- 安装「云音乐歌词卡片」
- 刷新浏览器
手动安装
- 下载 ncloud-lyrics-card.js 到 HA 配置目录的 www/ 文件夹
- 在仪表盘添加资源：
- 设置 → 仪表盘 → ⋮ → 资源
- 添加 /local/ncloud-lyrics-card.js，类型选择 JavaScript 模块
基础配置
type: custom:ncloud-lyrics-card
entity: media_player.cloud_music_xxx
完整配置
type: custom:ncloud-lyrics-card
entity: media_player.cloud_music_xxx
show_header: true # 可选，显示歌曲信息头部（默认 true）
show_cover: true # 可选，显示专辑封面（默认 true）
show_translation: true # 可选，显示翻译歌词（默认 true）
lyric_offset: 0 # 可选，歌词偏移秒数（默认 0）
# 正数=歌词延后，负数=歌词提前
# 例如：lyric_offset: -2 表示歌词提前 2 秒
2025.12.15 - 私人 FM 与默认播放器配置
v1.5.0 本版本新增原生私人 FM 功能，支持七种推荐模式与无感续播；引入全局默认播放器配置，优化多设备环境下的控制逻辑。 核心功能 1. 私人 FM (Personal FM) 集成网易云音乐算法推荐能力，重构底层队列管理，实现无限流播放体验。 - 七种模式支持：
- 基础模式：AI DJ（只有歌曲）、默认推荐、熟悉的歌、探索新歌。
- 场景模式：运动 (Exercise)、专注 (Focus)、夜晚情绪 (Night Emo)。
2. 默认播放器配置 针对多播放器环境，在集成选项（Options）中新增“快捷控制目标”配置。 - Dashboard 上的全局快捷按钮（每日推荐、私人 FM、我喜欢的音乐）将直接控制指定的默认设备，不再生成冗余的实体列表。
3. 自动化支持 - ha_ncloud_music.play_fm：支持自动化调用 FM 播放，可选具体模式（如 aidj, focus）。
- ha_ncloud_music.fm_trash：FM 不喜欢（垃圾桶）服务，执行“标记不喜欢 + 自动切下一首”操作。
底层改进与修复 - 状态同步：重构音量监听逻辑，解决双向同步不准确问题，增加静音功能；优化底层设备离线时的状态处理。
- 性能优化：用户信息改为异步加载，避免阻塞事件循环；引入线程锁机制确保并发操作下的数据一致性；优化 API 缓存过期策略。
升级说明 - 建议升级后进入集成选项设置默认播放器。
- FM 模式下无法开启“随机播放”为设计预期的行为。
| 
发表于 2025-12-9 17:32:44
