Home Assistantmedia_player.clear_playlist操作完全指南清空媒体播放器播放列表【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.iomedia_player.clear_playlist是 Home Assistant 中media_player域下的一个标准操作action用于将媒体播放器当前队列queue或播放列表中的所有条目一次性移除。本文以 关联文档 为骨架结合仓库中 Sonos 集成 与 HEOS 集成 的实际用法完整讲解该操作的 UI 配置、YAML 写法、目标target选择机制以及真实自动化场景读完后你将能独立在自动化与脚本中正确调用它并规避空队列报错等边界问题。操作概述它做什么、何时用该操作的作用非常聚焦删除一个媒体播放器播放列表或队列中的所有条目。官方文档的定位是Use this action to remove all items from a media players playlist or queue.从文档 front matter 可知它的基本身份信息Action 名称media_player.clear_playlist所属域domainmedia_player关联操作media_player.media_stop停止播放、media_player.play_media播放媒体典型使用场景包括夜间定时清空队列让第二天从干净的状态开始在批量加入新曲目之前清空旧队列见下文 Sonos 的搜索并重建队列示例切换播放源或结束某个收听会话时清理遗留的排队内容。需要特别强调文档中的一条重要说明Good to know 部分This action only works with media players that support clearing the playlist.即只有底层设备/集成实现了清空播放列表能力时该操作才会生效并非所有media_player实体都支持。因此调用前应确认目标设备能力或依赖下文介绍的continue_on_error机制做容错。在 UI 中配置自动化与脚本里的操作步骤文档给出了在用户界面中添加此操作的标准流程对应仓库模板 source/_includes/actions/ui_header.md进入Settings Automations scenes设置 自动化与场景。打开一个已有的自动化或脚本或选择Create automation Create new automation新建。如果是新建自动化在When何时部分添加一个触发器脚本script不需要触发器它们在被其他对象调用时运行。在Then do然后执行部分选择Add action添加操作。选择要控制的对象在By target按目标参见下文目标Targets下选择要控制的媒体播放器。在该目标显示的操作列表中选择Clear media player playlist清除媒体播放器播放列表。点击Save保存。需要留意的是此操作在 UI 中没有除目标target之外的任何额外选项原文This action has no additional options beyond the target.。这意味着它的全部行为都由作用于哪个实体决定配置极其简单。YAML 用法基础示例与完整参数在 YAML 中调用时操作名写作media_player.clear_playlist。文档给出的基础示例action: media_player.clear_playlist target: entity_id: media_player.living_room这段配置会清空media_player.living_room上的播放列表。与 UI 一致该操作在 YAML 中同样没有除目标之外的任何附加参数This action has no additional YAML options beyond the target.所以你不需要提供data块只有action与target两个键。更完整地在一个自动化中它通常长这样来自文档的深夜清空队列示例automation: - alias: Clear the queue at the end of the night triggers: - trigger: time at: 02:00:00 actions: - action: media_player.clear_playlist target: entity_id: media_player.living_roomTrigger触发器时间型触发器每天 02:00 触发。Action操作清空Living room speaker客厅音箱的播放列表次日从全新状态开始。目标Targets操作的作用对象该操作必须指定目标This action requires a target。目标是操作的客体你可以把操作指向单个实体、设备、区域、楼层或标签Home Assistant 会对目标背后所有匹配的media_player实体执行该操作。仓库模板 source/_includes/actions/targets.md 中定义了五种目标类型Entity实体某一个具体的media_player实体例如media_player.living_room。Device设备属于某台设备的所有media_player实体。Area区域某个房间或区域内的所有media_player实体。Floor楼层某一楼层上的所有media_player实体。Label标签共享某个标签的所有media_player实体。你还可以在同一操作中混用不同类型的多个目标例如同时指定一个具体实体和一个区域让操作同时作用于两者。借助这种机制一条media_player.clear_playlist就能批量清空多个音箱、多个房间的队列而无需为每个实体单独写一条。真实场景Sonos 集成中的搜索 → 清空 → 重建队列在仓库的 Sonos 集成文档 source/_integrations/sonos.markdown 中media_player.clear_playlist被用于一个非常实用的组合流程搜索本地音乐库中所有匹配的曲目、清空现有队列、逐条加入并播放。这个示例展示了该操作与media_player.search_media、media_player.play_media的典型协作方式actions: - action: media_player.search_media data: search_query: love media_content_type: track response_variable: results target: entity_id: media_player.kitchen - action: media_player.clear_playlist target: entity_id: media_player.kitchen - variables: search_length: {{ results[media_player.kitchen][result]|count }} - repeat: sequence: - action: media_player.play_media target: entity_id: media_player.kitchen data: enqueue: add media: media_content_id: - {{ results[media_player.kitchen][result][repeat.index - 1][media_content_id] }} media_content_type: - {{ results[media_player.kitchen][result][repeat.index - 1][media_content_type] }} until: - condition: template value_template: {{search_length repeat.index}} - action: sonos.play_queue target: entity_id: media_player.kitchen流程拆解media_player.search_media在 Sonos 本地音乐库中搜索所有匹配 love 的曲目结果存入response_variable: results搜索范围仅限本地音乐库流媒体服务如 Spotify、Tidal 不包含在内且media_content_type支持track、album、artist、composer、genre、playlist等取值。media_player.clear_playlist先清空厨房音箱当前队列保证新队列不混入旧内容。repeat循环逐条用enqueue: add把搜索结果追加进队列。最后调用sonos.play_queue开始播放整条队列。这个示例同时印证了文档中操作只对支持清空播放列表的播放器生效这一说明——Sonos 集成明确实现了该能力因此在此组合中它是安全可靠的。边界与容错HEOS 集成中的空队列报错并非所有实现都允许无条件清空。仓库的 HEOS 集成文档 source/_integrations/heos.markdown 中明确记录了一个容易踩坑的行为Actions may fail if they cannot be processed by the HEOS device. For example, attempting to callmedia_player.clear_playlistwhen the queue is empty will result in an error. To prevent this from halting a script or automation, setcontinue_on_error: truein the action call.也就是说HEOS 设备在队列为空时调用media_player.clear_playlist会直接报错。文档建议的规避方式是给该操作加上continue_on_error: true防止单个操作失败中断整个脚本或自动化actions: - action: media_player.clear_playlist target: entity_id: media_player.denon_avr continue_on_error: true关于continue_on_error的语义仓库的脚本文档 source/_docs/scripts.markdown 说明它适用于所有操作默认值为关闭设置后当该操作失败时脚本/自动化不会中止而是继续执行后续步骤。需要注意的是它不会掩盖配置错误本身例如目标实体不存在这类问题仍会被处理。这一容错模式对任何设备不支持清空或队列为空的播放器都具有普适参考价值。与关联操作的组合停止、播放与清空该文档 front matter 声明了两个关联操作理解它们的差异有助于设计正确的控制序列media_player.media_stop见 source/_actions/media_player.media_stop.markdown停止播放只中断当前播放并不删除队列内容。media_player.play_media见 source/_actions/media_player.play_media.markdown播放指定媒体可向队列添加内容配合enqueue参数。典型的完整控制序列可以是media_player.media_stop停止当前播放 →media_player.clear_playlist清空遗留队列 →media_player.play_media载入新的播放内容。三者的关注点分别是停止声音清空排队开始新内容组合使用即可覆盖媒体播放的完整状态机切换。常见问题与排障思路综合文档与集成源码遇到操作不生效时可依次排查设备能力确认目标播放器支持清空播放列表可查阅对应集成文档如 Sonos、HEOS 均支持不支持的实体该操作会被忽略或报错。目标是否正确确认target.entity_id存在且是media_player域实体需要批量操作时改用设备、区域、楼层或标签目标。空队列报错HEOS 等集成在队列为空时调用会报错为该操作加continue_on_error: true避免中断整个流程。与其他操作协作清空操作本身不改变播放状态若期望停止并清空需配合media_player.media_stop使用。总结media_player.clear_playlist是一个轻量但边界明确的media_player操作它只负责移除播放列表/队列中的所有条目没有除目标之外的任何参数因此正确选择目标和确认设备能力是使用的关键。通过 UI 操作添加流程、YAML 基础示例、Sonos 的搜索—清空—重建队列实战组合以及 HEOS 的空队列容错方案你可以在自动化与脚本中安全地管理任何支持该能力的媒体播放器的播放队列。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考