Home Assistant 中使用 heos.get_queue 动作读取 Denon HEOS 播放队列【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io本文围绕 Home Assistant 中 Denon HEOS 集成提供的heos.get_queue动作展开讲解如何通过 UI 或 YAML 读取 HEOS 媒体播放器的当前播放队列、解析其响应数据结构并与heos.move_queue_item、heos.remove_from_queue动作配合实现队列管理。读完本文你将掌握读取队列、定位queue_id、按索引跳播队列项以及自动化脚本中消费响应变量的完整实战方案。动作概述heos.get_queue是 Denon HEOS 集成 提供的专用动作之一用于读取 HEOS 媒体播放器扬声器、功放、接收机等当前排队播放的音乐列表。它返回队列中每一项的曲目、专辑、艺术家、封面图以及 HEOS 内部的曲目与专辑标识用途有两个查看当前排队播放的内容获取队列项的queue_id即队列中的位置序号供 Move queue item 与 Remove from queue 动作使用。该动作属于媒体播放器领域目标域为media_player在自动化、脚本以及 Home Assistant 的“开发者工具 操作”界面中均可调用。在自动化或脚本中使用通过 UI 操作进入设置自动化与场景Automations scenes。打开现有的自动化或脚本若新建选择创建自动化创建新自动化。若是新建自动化在When区域添加一个触发器脚本不需要触发器脚本由其他调用方触发运行。在Then do区域选择添加操作Add action。在目标Targets下选择要读取的 HEOS 媒体播放器。在针对该目标显示的操作列表中选择Get queue。选择保存。UI 中的选项该动作在 UI 中没有额外的配置选项选择目标后即可直接执行。在 YAML 中使用在 YAML 中该动作名称为heos.get_queue。若要使用返回值可将其存入响应变量response variable供后续步骤使用action: | action: heos.get_queue target: entity_id: media_player.office response_variable: queue上述示例将media_player.office的播放队列存入queue变量后续步骤即可通过queue[media_player.office].queue访问具体列表数据。动作目标Targets该动作必须有目标。目标是动作的作用对象可以指向单个实体、设备、区域、楼层或标签Home Assistant 会对该目标背后所有匹配的media_player实体执行动作实体单个media_player实体例如media_player.living_room设备属于某台设备的所有media_player实体区域某个房间/区域内所有media_player实体楼层某个楼层上所有media_player实体标签共享某个标签的所有media_player实体。同一动作中可以混用多种目标类型例如同时指定一个实体和一个区域动作会对两者同时生效。响应数据响应按每个被定向播放器的实体 ID 作为键组织。对每台播放器queue列表包含当前排队的各项每个队列项包含以下字段字段说明queue_id该项在队列中的位置从 1 开始song曲目标题album曲目所属专辑artist曲目艺术家image_url封面图链接media_id曲目的 HEOS 标识符album_id专辑的 HEOS 标识符一个典型的响应示例如下media_player.office: queue: - queue_id: 1 song: Alone Again album: After Hours artist: The Weeknd image_url: - http://resources.example.com/images/640x640.jpg media_id: 134788274 album_id: 134788273 - queue_id: 2 song: Too Late album: After Hours artist: The Weeknd image_url: - http://resources.example.com/images/640x640.jpg media_id: 134788275 album_id: 134788273与队列管理动作配合heos.get_queue的价值往往体现在与以下两个动作的配合中移动队列项heos.move_queue_item使用 Move queue item 可以重排队列。需要提供要移动的queue_ids队列项的位置序号和destination_position目标位置从 1 开始。例如将第二项移动到队首action: | action: heos.move_queue_item target: entity_id: media_player.family_room data: queue_ids: - 2 destination_position: 1移除队列项heos.remove_from_queue使用 Remove from queue 可以按queue_ids移除一个或多个队列项。例如移除第一项和第三项action: | action: heos.remove_from_queue target: entity_id: media_player.family_room data: queue_ids: - 1 - 3注意queue_id从 1 开始且会随队列中项目的移动、添加或删除而发生变化。因此在使用移动或移除动作前应先用heos.get_queue获取当前最新的位置编号避免引用失效的queue_id。按索引跳播队列项除了读写队列HEOS 集成还支持通过标准的media_player.play_media动作直接跳播到队列中的某一项将media_content_type设为queuemedia_content_id设为队列索引从 1 开始。队列内容同样可以先用heos.get_queue枚举action: media_player.play_media data: entity_id: media_player.office media_content_type: queue media_content_id: 1实用提示建议先执行heos.get_queue获取queue_id再将其传给 Move queue item 或 Remove from queue。在自动化或脚本中使用时若后续动作依赖队列数据请通过response_variable存储结果并注意响应按实体 ID 键控的结构。部分 HEOS 动作在设备无法处理时可能报错例如队列为空时调用media_player.clear_playlist会返回错误。为避免中断整个脚本或自动化可在动作调用上设置continue_on_error: true具体参见脚本文档的“出错时继续”说明。动手验证无需编写 YAML 即可快速测试打开设置工具操作Actions搜索heos.get_queue填写目标播放器并选择执行操作Perform action即可在真实实体上观察返回的队列数据。关于 Denon HEOS 集成的完整能力配置方式、支持设备、播放收藏/播放列表/Quick Select/URL、设备分组、已知限制等可进一步阅读 Denon HEOS 集成文档。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考