Home Assistant Jellyfin 随机播放动作详解用 jellyfin.play_media_shuffle 一键乱序播放整个剧集目录【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io本文以 Home Assistant 官方文档中的jellyfin.play_media_shuffle动作为核心讲解如何让 Jellyfin 客户端在开始播放时对指定媒体目录如整个剧集、电视剧或某一季进行乱序shuffle播放并立即替换当前播放队列。读完本文你将掌握该动作的 UI 操作步骤、完整 YAML 调用写法、media参数的准确格式以及如何通过media_player.browse_media/media_player.search_media获取所需的media_content_id并了解它与通用播放动作media_player.play_media的差异与配合方式。动作概述什么是随机播放目录jellyfin.play_media_shuffle是 Jellyfin 集成为媒体播放器实体提供的专属动作。它用于从你的 Jellyfin 媒体库中随机播放一个目录例如一整部剧集series、一部电视剧TV show或某一季season。其核心行为包括两点Jellyfin 服务端 API 支持在播放开始时就对目录进行乱序处理因此随机是播放启动时即生效的而不是先按顺序播放再手动切换执行该动作会立即替换当前客户端正在播放的播放队列被替换的内容不再继续播放。如果不需要随机、只想按顺序播放特定媒体官方文档明确建议改用通用的 Play mediamedia_player.play_media 动作。也就是说jellyfin.play_media_shuffle可以看作Play media 目录乱序的 Jellyfin 专用变体。适用前提该动作依赖 Jellyfin 客户端对乱序播放的支持。Home Assistant 官方文档标明Jellyfin 集成已在Jellyfin 服务端 10.6.4 及更高版本上完成测试见 Jellyfin 集成说明且媒体浏览目前限于music音乐、movie电影、TV show剧集三类媒体库其他类型库不会出现在媒体浏览器中。在 UI 界面中使用随机播放动作如果你习惯用可视化方式构建自动化与脚本可以完全绕过 YAML。官方文档给出了如下操作路径UI 与 YAML 两种方式行为等价进入SettingsAutomations scenes{% my automations %}快捷链接在 UI 中可直接跳转打开一个已有的自动化或脚本如果是新建设置选择Create automationCreate new automation新建自动化时在When触发条件部分添加一个触发器脚本不需要触发器它由其他内容调用时运行在Then do执行动作部分选择Add action添加动作在By target目标下选择要播放的 Jellyfin 播放器详见下文动作的目标一节从该目标可用的动作列表中选择Play media shuffled随机播放媒体填写你想要使用的选项点击Save保存。UI 中的选项UI 模式下该动作只有一项可配置内容选项说明Media要播放的媒体。浏览并选择你想要乱序播放的目录例如一部剧集或某一季。在 YAML 中使用随机播放动作官方文档将jellyfin.play_media_shuffle归类为动作action在 YAML 中它以action键调用基本示例为action: jellyfin.play_media_shuffle target: entity_id: media_player.chrome data: media: media_content_id: 34361f3855c9c0ac39b0f7503fe86be0这个示例的含义是在目标 Jellyfin 客户端media_player.chrome上对 ID 为34361f3855c9c0ac39b0f7503fe86be0的目录进行随机播放——官方文档用它来演示随机播放某一整季的电视剧。YAML 选项参考参数说明是否必填类型media要播放的媒体是一个映射map其中包含你要随机播放目录的media_content_id是map可以看到YAML 中唯一的参数media是一个嵌套结构其内部实际承载的是 Jellyfin 的媒体标识符media_content_id。这一点与通用动作media_player.play_media直接平铺media_content_idmedia_content_type两个顶层字段的写法不同——随机播放动作把媒体信息收敛在media映射内同时不需要指定media_content_type。如何获取 media_content_idmedia_content_id是 Jellyfin 库中特定条目的标识符形如 32 位十六进制字符串例如示例中的34361f3855c9c0ac39b0f7503fe86be0。官方文档给出的获取途径是使用以下两个动作浏览或搜索你的媒体库Browse mediamedia_player.browse_media类似在媒体播放器 UI 中浏览媒体树逐层进入目录最终定位到目标剧集或季并从返回数据中取得其media_content_idSearch mediamedia_player.search_media按关键词搜索媒体库从搜索结果中取得对应条目的media_content_id。这两个动作都会把结果写入响应变量response variable供同一自动化或脚本的后续步骤使用。以media_player.browse_media为例其响应是一个媒体树对象包含title、media_class、media_content_type、media_content_id、children_media_class与children等字段children中每个子项又带有相似的属性子项的media_content_id通常是被 URL 编码过的# 示例浏览返回的媒体树片段 media_player.living_room: title: Beatles media_class: album media_content_type: album media_content_id: A:ALBUMARTIST/Beatles children_media_class: directory children: - title: A Hard Days Night media_class: album media_content_type: album media_content_id: A:ALBUMARTIST/Beatles/A%20Hard%20Days%20Night说明上述示例来自通用文档其A:ALBUMARTIST/...形式的 ID 是 Sonos 设备的格式。Jellyfin 的media_content_id是它自己的库条目 ID具体取值请以你实际浏览/搜索 Jellyfin 库返回的数据为准。自动化实战先查找 ID再随机播放结合响应变量机制可以在一个自动化中先浏览 Jellyfin 媒体树定位目标再用其media_content_id触发随机播放automation: - alias: Shuffle a season on the living room Jellyfin triggers: - trigger: state entity_id: input_boolean.movie_night to: on actions: - action: media_player.browse_media target: entity_id: media_player.living_room data: media_content_type: tvshow response_variable: browse_result - action: jellyfin.play_media_shuffle target: entity_id: media_player.living_room data: media: media_content_id: {{ browse_result[media_player.living_room].children[0].media_content_id }}动作的目标Targetsjellyfin.play_media_shuffle与所有 media_player 域动作一样必须指定目标target。目标是一个动作的对象可以将动作指向单个实体、设备、区域、楼层或标签Home Assistant 会针对目标背后所有匹配的媒体播放器实体执行该动作。可用的目标类型包括源自 actions/targets.mdEntity实体一个具体的 media_player 实体如media_player.living_roomDevice设备属于某个设备的所有 media_player 实体Area区域某个房间/区域内的所有 media_player 实体Floor楼层某一楼层上的所有 media_player 实体Label标签共享某个标签的所有 media_player 实体。你还可以在同一个动作里混合选择不同类型的目标例如同时指定一个具体实体和一个区域让动作同时作用于两者。Jellyfin 集成为每个连接到服务器的媒体会话建立一个 media_player 实体因此目标通常就是对应到具体客户端如电视、浏览器客户端的实体。与 media_player.play_media 的对比与配合jellyfin.play_media_shuffle与通用动作 media_player.play_media 之间既有区别又有配合关系维度jellyfin.play_media_shufflemedia_player.play_media乱序能力由 Jellyfin API 在播放开始时对目录乱序不具备目录乱序语义媒体参数单个media映射内含media_content_id顶层media_content_idmedia_content_type必填队列行为立即替换当前播放队列由enqueue选项控制add/next/play/replace适用场景整部剧集/某一季的随机连续播放指定单曲、播放列表、视频流等精确播放Jellyfin 集成文档source/_integrations/jellyfin.markdown还补充了media_player.play_media在 Jellyfin 上的行为细节可帮助你理解两者的关系Jellyfin 支持enqueue的next与add选项而play与replace选项会替换当前播放队列效果等同于不设置enqueue——这与jellyfin.play_media_shuffle立即替换当前队列的行为一致对 Jellyfin 而言media_content_type的取值generally inconsequential通常无关紧要任意字符串都可以通过校验因此随机播放动作不要求该字段并不会造成歧义无论使用哪个动作查找media_content_id的途径都是 Browse media 与 Search media 两个动作。注意media_player.media_playPlay media恢复播放是另一个不同的动作——它仅恢复客户端当前已加载的内容不指定新媒体因此与随机播放动作用途完全不同见 media_player.media_play。快速验证与排障动手试验打开SettingsToolsActions开发者工具中的 Actions搜索jellyfin.play_media_shuffle填写字段后点击Perform action即可在真实实体上观察效果无需编写任何 YAML见 actions/try_it.md。常见问题排查思路找不到该动作请确认目标实体确实是 Jellyfin 集成创建的 media_player 实体且该动作只会在对应目标的动作列表中显示媒体浏览里看不到某些库Jellyfin 集成目前仅支持 music、movie、TV show 三类媒体库其他类型不会出现在媒体浏览器中ID 取错media_content_id应来自对 Jellyfin 库执行 browse/search 返回的条目 ID不同 Jellyfin 服务器/库的 ID 各不相同示例中的 ID 仅用于演示不能直接复用客户端无响应随机播放依赖客户端对 Jellyfin 播放会话的能力支持请确认客户端版本与服务端10.6.4兼容。小结jellyfin.play_media_shuffle是 Home Assistant Jellyfin 集成面向整目录乱序播放场景提供的专用动作一个media参数即可让 Jellyfin 服务端在播放启动时完成乱序并替换当前队列。配合media_player.browse_media/media_player.search_media的响应变量机制可以完全自动化地定位并随机播放某一季或整部剧集而在需要精确控制播放内容与队列行为时则回到通用的media_player.play_media动作。两者的边界与配合构成了 Jellyfin 在 Home Assistant 中播放控制的核心用法。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考