跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
搜索与研究

media

Use when controlling or browsing Home Assistant media players — play, pause, volume, source/sound mode, speaker grouping, browsing media libraries, and TTS announcements — through HA NOVA Relay.

markusleben · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add markusleben/ha-nova --skill media

技能说明


name: media description: Use when controlling or browsing Home Assistant media players — play, pause, volume, source/sound mode, speaker grouping, browsing media libraries, and TTS announcements — through HA NOVA Relay. license: MIT compatibility: Requires the ha-nova CLI (run 'ha-nova setup' first) and the HA NOVA Relay in Home Assistant (App, or standalone container on Container/Core).

HA NOVA Media

Scope

Media player control and discovery:

  • transport control (play, pause, stop, next, previous, seek), volume, mute, source and sound mode
  • browsing media libraries and media sources, then playing a resolved item
  • speaker grouping (join / unjoin)
  • TTS announcements to a player

Not in scope: creating automations that use media players (ha-nova:write), camera streams (ha-nova:camera), generic service calls to other domains (ha-nova:service-call).

Bootstrap (once per session)

Read and follow ../ha-nova/session-bootstrap.md. Verify relay CLI: ha-nova relay health If this fails: ha-nova setup

Relay Contract

  • ha-nova relay ws --data-file <payload-file> for WS commands (browse, search)
  • ha-nova relay core --method POST --path /api/services/<domain>/<service> --body-file <payload-file> for service calls
  • ha-nova relay core --method GET --path /api/states/<entity_id> to read a player's state and attributes
  • --out <result-file> for large browse responses; --jq-file <filter-file> for non-trivial filters

Feature Gate (read before acting)

A media player's attributes.supported_features bitmask decides what it can do — never assume. Read the entity state first and check the bit before offering an action:

BitFeature
1pause
2seek
4volume set
8volume mute
16previous track
32next track
128turn on
256turn off
512play media
1024volume step
2048select source
4096stop
8192clear playlist
16384play
32768shuffle set
65536select sound mode
131072browse media
262144repeat set
524288grouping
1048576announce
2097152enqueue
4194304search media

If a requested feature bit is absent, say so plainly instead of calling the service and reporting a silent no-op.

Flow

  1. Resolve the player yourself — this skill owns its resolution (one skill per intent; never dispatch to another skill mid-task):
    • exact media_player.<id> from the user: use it directly.
    • name or room: WS {"type":"config/entity_registry/list_for_display"}, filter ei starting with media_player., and match on ei/en. For room phrasing, resolve the area and use search/related with item_type: "area".
    • several matches: present the candidates (max 5) and ask once. Never guess. Then read its state (/api/states/<entity_id>) for state, supported_features, source_list, sound_mode_list, group_members, and current media attributes.
  2. Transport / volume / source: check the bit for the exact action first (play 16384, pause 1, stop 4096, next 32, previous 16, seek 2, volume set 4, volume step 1024, mute 8, source 2048, sound mode 65536, turn on 128 / off 256), preview the service + target, then call it: media_player.media_play|media_pause|media_stop|media_next_track|media_previous_track|media_seek (seek_position in seconds; read media_duration/media_position from the state first) |volume_set (volume_level 0.0-1.0) |volume_mute|select_source|select_sound_mode|turn_on|turn_off.
    • Relative volume ("turn it up / down a bit"): that is media_player.volume_up / volume_down, gated by VOLUME_STEP (1024) — a player can support stepping without absolute volume_set (4). Prefer stepping for relative requests, and only fall back to volume_set (read the current volume_level, add a delta) when the player has 4 but not 1024.
  3. Browse: WS {"type":"media_player/browse_media","entity_id":"media_player.<id>"} for the player's own library; drill down by passing media_content_type AND media_content_id together (they are a pair — one without the other is rejected). For Home Assistant's media sources use WS media_source/browse_media, then WS media_source/resolve_media to turn a media-source://... id into a playable URL.
    • Search before drilling when the user names a title, artist, or album: WS {"type":"media_player/search_media","entity_id":"media_player.<id>","search_query":"<text>"} (bit 4194304) searches the player's own library — entity_id is required, and media_content_type/media_content_id scope the search only when supplied together; WS media_source/search_media with search_query (media_filter_classes narrows it) searches Home Assistant's sources. Pass a media_content_id for the source you mean: the media-source ROOT cannot search, so omitting it fails with search_media_failed: Search is not supported for media with content ID even though the payload is valid. Only sources whose can_search is true participate. Both return browse-shaped results you can hand straight to step 4. Neither is universal: when the bit is missing or a source cannot search, say so once and fall back to browsing rather than guessing a content id.
  4. Play a resolved item: media_player.play_media with media_content_id + media_content_type from the browse/resolve step. Never invent a content id.
    • Queue placement uses the same service: enqueue: add | next | play | replace (bit 2097152). "Play this next" is next, "add to the queue" is add; without the bit the player only replaces what is playing — say that instead of silently replacing.
      • add and next have no success signal. They deliberately do not change state or media_title — that is what queueing means — and Home Assistant exposes no standard queue attribute to read back. Step 7's re-read therefore proves nothing here: report the call as accepted, name what would have changed i
阅读完整来源 ↗