企业官网建设流程全解析

Home Assistant Sonos 队列管理：使用 sonos.remove_from_queue 精准移除队列条目

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io

本指南聚焦 Home Assistant 中 Sonos 集成的sonos.remove_from_queue动作（action），讲解如何通过 UI 或 YAML 按位置移除音箱播放队列中的曲目，并给出"播完即删""按关键词批量清理队列"等可直接落地的自动化示例。读完你既能独立完成队列移除配置，也能结合sonos.get_queue、sonos.play_queue构建完整的队列管理自动化。

动作的作用与典型场景

sonos.remove_from_queue用于按队列位置（queue position）从 Sonos 音箱的队列中移除一个条目。与按名称或 ID 匹配的方式不同，它直接以整数位置定位目标，语义简单、执行确定，非常适合程序化队列管理。

典型的应用场景包括：

• 清除队列中不想再听的曲目，例如在一首歌播放完毕后立即将其移除，让队列随收听进度自动清空；
• 配合 sonos.get_queue 读取队列内容后，按标题、专辑等条件批量剔除指定曲目；
• 在自动化流程中先移除某个位置，再通过 sonos.play_queue 从指定位置重新开始播放，实现"跳过/重排"效果。

该动作属于media_player域，作用于 Sonos 音箱对应的media_player.*实体，是 Sonos 集成在标准媒体播放器动作之外提供的专用队列动作之一（参见 Sonos 集成文档）。

在 UI 中配置：从自动化或脚本调用

在 Home Assistant 的设置 > 自动化与场景界面中，可以完全通过可视化方式添加该动作：

1. 进入设置>自动化与场景。
2. 打开一个已有的自动化或脚本；或选择创建自动化>创建新自动化。
3. 如果是新建自动化，在When（触发条件）区域添加一个触发器；脚本不需要触发器，由其他流程调用即可。
4. 在Then do（执行动作）区域选择添加动作。
5. 在目标（By target）下选择要操作的 Sonos 音箱（目标规则详见下文 动作的目标），也可以按区域、设备或标签选择。
6. 在该目标可用的动作列表中选择从队列中移除（Remove from queue）。
7. 设置要移除的队列位置（Queue position）。
8. 点击保存。

UI 中的选项

在 YAML 中使用：字段与完整参考

直接编写 YAML 时，动作名为sonos.remove_from_queue。最基本的调用形式如下：

action: sonos.remove_from_queue target: entity_id: media_player.living_room data: queue_position: 3

该示例会把media_player.living_room队列中的第 4 个条目（位置从 0 开始计数）移除。

YAML 字段说明

在 sonos.play_queue 中，queue_position的含义是"从该位置开始播放"，而此处是"移除该位置的条目"，两者共享同一套 0 基位置计数规则，编排流程时请注意区分。

动作的目标

该动作必须指定目标。目标可以是实体、设备、区域、楼层或标签，Home Assistant 会对目标背后所有匹配的media_player实体执行该动作：

• 实体（Entity）：某个具体的media_player实体，如media_player.living_room；
• 设备（Device）：属于某台设备的所有media_player实体；
• 区域（Area）：某个房间/区域内的所有media_player实体；
• 楼层（Floor）：某一楼层上的所有media_player实体；
• 标签（Label）：共享某个标签的所有media_player实体。

一次动作也可以混合多种目标类型，例如同时指定一个具体实体和一个区域，动作会分别作用于两者（完整规则参见 targets.md）。

实战示例：歌曲播完即从队列移除

原文档给出一个实用的自动化：每当队列前进到下一首时，把刚播完的那首从队列中移除，让队列随收听进度自然清空。

alias: "Remove last played song from queue" triggers: - trigger: state entity_id: media_player.kitchen - trigger: state entity_id: media_player.bathroom - trigger: state entity_id: media_player.move conditions: # Only act on the coordinator speaker - "{{ state_attr(trigger.entity_id, 'group_members')[0] == trigger.entity_id }}" # Only when moving from one queue position to another - >- {{ 'queue_position' in trigger.from_state.attributes and 'queue_position' in trigger.to_state.attributes }} # Only when moving forward in the queue - >- {{ trigger.from_state.attributes.queue_position < trigger.to_state.attributes.queue_position }} actions: - action: sonos.remove_from_queue target: entity_id: "{{ trigger.entity_id }}" data: queue_position: "{{ trigger.from_state.attributes.queue_position }}"

拆解该示例的三个关键条件：

1. 只处理协调器（coordinator）音箱：当 Sonos 音箱组成分组时，只有协调器管理队列。通过state_attr(trigger.entity_id, 'group_members')[0] == trigger.entity_id判断当前触发实体是否为组内第一个成员（即协调器），避免对组内从属音箱重复执行。
2. 仅当队列位置发生变化时：同时检查触发前后状态的属性中都存在queue_position，过滤掉与队列播放无关的状态变化。
3. 仅在队列向前推进时：from_state的位置小于to_state的位置，表示正在切到下一首，此时上一首已经结束，正是移除它的时机。

动作部分直接使用trigger.from_state.attributes.queue_position作为移除位置——也就是刚播完的那首歌曲所在的位置。

进阶：与 sonos.get_queue 联用，按条件批量清理

remove_from_queue按位置操作，而位置信息需要从 sonos.get_queue 获取。sonos.get_queue会将每个目标音箱的队列写入响应变量，队列中的每个条目包含以下字段：

• media_title：曲目标题；
• media_album_name：所属专辑；
• media_artist：艺术家；
• media_content_id：曲目的内容标识符。

响应结构按实体 ID 分组，例如：

media_player.living_room: - media_title: Lazy Sunday media_album_name: Morning Coffee media_artist: The Beanery media_content_id: x-sonos-http:track%3a1234.mp3

官方文档演示了两者联用的经典模式：获取队列 → 逆向遍历 → 移除所有标题或专辑包含 "holiday" 的曲目。注意这里刻意采用逆向遍历（从队列末尾向开头），因为移除条目会导致后续位置前移，逆向处理可以保证位置索引始终有效：

- action: sonos.get_queue target: entity_id: media_player.living_room response_variable: queue - variables: queue_len: "{{ queue['media_player.living_room'] | length }}" - repeat: sequence: - variables: title: "{{ queue['media_player.living_room'][queue_len - repeat.index]['media_title'].lower() }}" album: "{{ queue['media_player.living_room'][queue_len - repeat.index]['media_album_name'].lower() }}" position: "{{ queue_len - repeat.index }}" - if: - "{{ 'holiday' in title or 'holiday' in album }}" then: - action: sonos.remove_from_queue target: entity_id: media_player.living_room data: queue_position: "{{ position }}" until: - "{{ queue_len == repeat.index }}"

这个模板可以推广到任意过滤条件：把'holiday' in title or 'holiday' in album替换为"歌手匹配""时长超过阈值"或"内容 ID 属于某份黑名单"等判断，即可实现灵活的队列清洗。

分组场景与协调器说明

原文档特别提示：当目标是一个分组（group）时，请使用协调器（coordinator）音箱。在 Sonos 系统中，多房间同步播放时只有一个音箱充当协调器负责维护队列，队列操作（读取、移除、播放）都应当落在协调器实体上，否则可能无法生效或产生重复执行。上面的自动化示例正是用group_members属性来识别协调器。

与队列相关的其他动作与机制

围绕队列，Sonos 集成还提供了两个关联动作（参见原文档 frontmatter 的related_actions字段）：

• sonos.get_queue：返回音箱队列内容，配合响应变量在后续步骤中消费；
• sonos.play_queue：强制开始播放队列，可选的queue_position参数用于指定起始位置；这在从收音机等其他音源切回队列时尤其有用。

此外，media_player.play_media动作上的enqueue参数也直接参与队列构建（Sonos 集成文档）：replace（默认）替换整个队列并立即播放，add追加到队尾，next插入为下一首，play插入并立即播放。结合本文的移除动作，即可实现"增、删、播"完整的队列管理闭环。例如集成文档展示的流程：先media_player.search_media搜索所有匹配曲目，media_player.clear_playlist清空队列，再逐条enqueue: add入队，最后用sonos.play_queue开始播放（见 sonos.markdown）。

注意事项

• 移除动作依赖 Home Assistant 与 Sonos 设备之间的推送更新：Sonos 设备需要能回连 Home Assistant 主机的 TCP 1400 端口，若该端口被阻断，集成会回退到轮询模式，状态与队列变化更新会变慢（参见 Sonos 网络要求）。
• queue_position基于 0 计数，位置 0 是队列中的第一首，设置前建议先通过sonos.get_queue确认当前队列长度与目标位置，避免越界。
• 批量移除务必逆向遍历（从队尾到队首），否则位置索引会随移除操作发生偏移，导致误删或漏删。

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io