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 callsha-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:
| Bit | Feature |
|---|---|
| 1 | pause |
| 2 | seek |
| 4 | volume set |
| 8 | volume mute |
| 16 | previous track |
| 32 | next track |
| 128 | turn on |
| 256 | turn off |
| 512 | play media |
| 1024 | volume step |
| 2048 | select source |
| 4096 | stop |
| 8192 | clear playlist |
| 16384 | play |
| 32768 | shuffle set |
| 65536 | select sound mode |
| 131072 | browse media |
| 262144 | repeat set |
| 524288 | grouping |
| 1048576 | announce |
| 2097152 | enqueue |
| 4194304 | search media |
If a requested feature bit is absent, say so plainly instead of calling the service and reporting a silent no-op.
Flow
- 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"}, filtereistarting withmedia_player., and match onei/en. For room phrasing, resolve the area and usesearch/relatedwithitem_type: "area". - several matches: present the candidates (max 5) and ask once. Never guess.
Then read its state (
/api/states/<entity_id>) forstate,supported_features,source_list,sound_mode_list,group_members, and current media attributes.
- exact
- 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_positionin seconds; readmedia_duration/media_positionfrom the state first)|volume_set(volume_level0.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 absolutevolume_set(4). Prefer stepping for relative requests, and only fall back tovolume_set(read the currentvolume_level, add a delta) when the player has 4 but not 1024.
- Relative volume ("turn it up / down a bit"): that is
- Browse: WS
{"type":"media_player/browse_media","entity_id":"media_player.<id>"}for the player's own library; drill down by passingmedia_content_typeANDmedia_content_idtogether (they are a pair — one without the other is rejected). For Home Assistant's media sources use WSmedia_source/browse_media, then WSmedia_source/resolve_mediato turn amedia-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_idis required, andmedia_content_type/media_content_idscope the search only when supplied together; WSmedia_source/search_mediawithsearch_query(media_filter_classesnarrows it) searches Home Assistant's sources. Pass amedia_content_idfor the source you mean: the media-source ROOT cannot search, so omitting it fails withsearch_media_failed: Search is not supported for media with content IDeven though the payload is valid. Only sources whosecan_searchis 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.
- Search before drilling when the user names a title, artist, or album: WS
- Play a resolved item:
media_player.play_mediawithmedia_content_id+media_content_typefrom 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" isnext, "add to the queue" isadd; without the bit the player only replaces what is playing — say that instead of silently replacing.addandnexthave no success signal. They deliberately do not changestateormedia_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
- Queue placement uses the same service: