@htmlbricks/hb-player-live 0.71.35 → 0.71.36

package/README.md

@@ -1,37 +1,136 @@
-## `hb-player-live` — player live
+# `hb-player-live`
 
 **Category:** media  
 **Tags:** media, video, streaming
 
-### What it does
+Live streaming player built on a native `<video>` element. It supports **HLS** (via [hls.js](https://github.com/video-dev/hls.js/) when Media Source Extensions are available, or the browser’s built-in HLS where supported), **WebRTC over WebSocket** ([`simple-webrtc-element`](https://www.npmjs.com/package/simple-webrtc-element)), and **WHEP** ([`MediaMTXWebRTCReader`](https://www.npmjs.com/package/simple-webrtc-element-whep) for MediaMTX-style endpoints).
 
-Live streaming `<video>` player for HLS (hls.js or native), WebSocket WebRTC (`simple-webrtc-element`), or WHEP (MediaMTX). Polls the manifest for HLS liveness, exposes the element via `getVideoElement`, and emits `liveStatus` and `htmlVideoInit`. When the stream is offline or missing, shows optional title/subtitle/text from `replacewithtext`, `forcecover`, or fallback labels.
+For **HLS**, the component periodically **fetches the manifest URL** to decide whether the source is reachable (“live” for overlay purposes). For **WebRTC** and **WHEP**, **online/offline** is driven by the underlying player callbacks, which also update `liveStatus`.
 
-### Custom element
+When the URI is missing, the stream is considered offline, or you force a cover state, the component can show a **full-area overlay** (default copy, `replacewithtext` JSON, and optional slots).
+
+---
+
+## Custom element
 
 `hb-player-live`
 
-### Attributes (snake_case; use string values in HTML)
+---
+
+## Attributes (snake_case; string values in HTML)
+
+Web component attributes are always strings. Use **`yes`** / **`no`** for boolean-like flags where noted. Pass **JSON as a single string** for object props (for example `replacewithtext='{"title":"…"}'`).
+
+| Attribute | Required | Description |
+| --- | --- | --- |
+| `mediauri` | Yes | Stream endpoint: HLS playlist (`.m3u8`), WebSocket signaling URL for `webrtc`, or WHEP URL for `whep`. Use an empty string if you intentionally have no URI (placeholder state). |
+| `media_type` | No | Playback mode: `hls`, `webrtc`, `whep`, or `auto` (see [Media type](#media-type)). Default in the implementation is `auto`. The `<video>` node is only rendered when both `mediauri` and `media_type` are non-empty. |
+| `forcecover` | No | Any non-empty value (commonly `yes`) forces the structured overlay when the conditions in the template are met (together with `replacewithtext` shape). |
+| `replacewithtext` | No | JSON string: `{ "title": string, "subtitle"?: string, "text"?: string }`. Used for default overlay copy; the component also parses a string value into an object when possible. |
+| `no_controls` | No | Hide native `<video>` controls when set to any truthy value except the strings `no` or `false` (for example `yes`). |
+| `id` | No | Passed through on custom events and when exposing the video element. |
+
+The authoring `Component` type also allows `style`; styling is normally done via CSS variables, `::part`, and host layout.
+
+---
+
+## Media type
+
+Set `media_type` explicitly for working playback:
+
+- **`hls`** — Loads `mediauri` with hls.js (or assigns `src` on Safari / browsers that report native HLS support). Autoplay is attempted with **muted** video.
+- **`webrtc`** — Uses `simple-webrtc-element` with `wsUri: mediauri` on the bound `<video>`.
+- **`whep`** — Uses `MediaMTXWebRTCReader` with `url: mediauri`; the first stream track is assigned to `video.srcObject`.
+
+The literal value **`auto`** appears in the public type union and is the Svelte default, but the internal `setVideo` path only wires **`hls`**, **`webrtc`**, and **`whep`**. Treat **`auto`** as reserved / not implemented for playback until a future version adds detection.
+
+---
+
+## Live status and polling
+
+- **`hls`**: `loadLive()` performs a `fetch(mediauri)` on the manifest. A response in the **1xx–299** range sets internal “live” to true and dispatches `liveStatus` with `live: true`. On failure, it dispatches `live: false` and **retries after 5 seconds** (also when `mediauri` is empty).
+- **`webrtc` / `whep`**: `liveStatus` is dispatched from **online/offline** handlers in the respective integrations (`live: true` / `live: false`).
+
+---
+
+## Overlay and fallback UI
+
+The dark **16:9** surface uses Bulma variables `--bulma-dark` and `--bulma-dark-invert` (see [Styling](#styling)).
+
+Rough behavior (see `component.wc.svelte` for exact conditions):
+
+1. **`forcecover`** is set, or **`mediauri` is set**, **`isLive` is false**, and **`replacewithtext`** includes at least one of `title`, `subtitle`, or `text` — shows the **`replacewithtext`** part with the **default slot layout** (one, two, or three lines depending on which JSON fields are present), unless you override the `replacewithtext` slot entirely.
+2. Otherwise, if there is a **`mediauri`** but the stream is **not live** and there is **no** `replacewithtext` copy — shows the literal **`offline`** label in the overlay.
+3. If there is **no `mediauri`** — shows **`nouri`** in the overlay.
+
+If you supply the **`replacewithtext`** slot, you replace the entire default overlay markup for that branch; the inner slots (`replacetitle`, `replacesubtitle`, `replacetext`) only apply inside the **default** structure.
+
+---
+
+## Events
+
+Listen with `addEventListener` on the host element (names are camelCase in the type definitions).
+
+| Event | `detail` (runtime) |
+| --- | --- |
+| `liveStatus` | `{ live: boolean; id: string }` |
+| `htmlVideoInit` | `{ htmlVideoElement: HTMLVideoElement; id: string }` — fired when the `<video>` is bound. The authoring `Events` type may use a `video` field name; the implementation uses **`htmlVideoElement`**. |
+
+---
+
+## Host API
+
+After upgrade, the custom element exposes:
+
+- **`getVideoElement()`** — Returns the internal `HTMLVideoElement` when it exists, otherwise `undefined`.
+
+---
+
+## Styling (CSS custom properties)
+
+Set on the host or an ancestor. The video frame and overlay use Bulma dark tokens.
+
+| Variable | Role |
+| --- | --- |
+| `--bulma-dark` | Background of the 16:9 video area and offline/cover overlay. |
+| `--bulma-dark-invert` | Foreground (text) on that surface. |
+
+See [Bulma CSS variables](https://bulma.io/documentation/features/css-variables/) for theme-wide tuning.
 
-- `id`, `style` (optional): strings.
-- `mediauri` (required): string — stream URL (HLS, WebRTC, WHEP as configured).
-- `media_type` (optional): `"hls"` | `"webrtc"` | `"auto"` | `"whep"` (empty string allowed in examples).
-- `forcecover` (optional): string — e.g. `"yes"` to force cover layout with placeholder text.
-- `replacewithtext` (optional): JSON string — `{ title; subtitle?; text? }` when offline.
-- `no_controls` (optional): boolean string — hide native/custom controls.
+---
 
-### Events
+## CSS parts (`::part(...)`)
 
-- `liveStatus`: `{ live: boolean; id: string }`.
-- `htmlVideoInit`: `{ video; id: string }`.
+| Part | Purpose |
+| --- | --- |
+| `container` | Root wrapper around the player and overlay; sizing and positioning of the whole component. |
+| `replacewithtext` | Full-bleed overlay when the stream is missing, not live, `forcecover` applies, or placeholder copy is shown. |
+| `video` | The native `<video>` element (streaming surface, native controls when enabled). |
 
-### Usage notes
+---
 
-- **CSS parts:** `container`, `replacewithtext`, `video`.
-- **Slots:** `replacewithtext` (wrapper when stream is covered/offline), `replacetitle`, `replacesubtitle`, `replacetext` — override fallback copy (still combined with `replacewithtext` / `forcecover` props when unset).
-- Pick `media_type` to match your pipeline (`whep` for WHEP examples in docs).
+## HTML slots
 
-### Minimal HTML example
+| Slot | When it matters | Purpose |
+| --- | --- | --- |
+| `replacewithtext` | Overlay branch with default structure | Replace the entire offline/cover layout. If you fill this slot, the default grid and nested slots are not used unless you reintroduce them in your markup. |
+| `replacetitle` | Default overlay only | Title line; falls back to `replacewithtext.title`. |
+| `replacesubtitle` | Default overlay (two- or three-line layout) | Subtitle line; falls back to `replacewithtext.subtitle` when the prop defines both title and subtitle. |
+| `replacetext` | Default three-line layout | Body copy; falls back to `replacewithtext.text`. |
+
+---
+
+## Usage notes
+
+- **Autoplay**: The implementation sets **`muted`** and calls **`play()`** where possible; browser policies may still block autoplay with sound or without user gesture.
+- **Changing `mediauri`**: When the URI changes, WHEP readers are closed, live state is reset, and the video is reinitialized.
+- **Accessibility**: The markup includes a captions `<track>` placeholder; provide real captions/tracks in your integration if you need accessibility compliance.
+
+---
+
+## Examples
+
+**HLS (public test stream)**
 
 ```html
 <hb-player-live
@@ -39,3 +138,56 @@ Live streaming `<video>` player for HLS (hls.js or native), WebSocket WebRTC (`s
   media_type="hls"
 ></hb-player-live>
 ```
+
+**WHEP endpoint** (replace with your server URL)
+
+```html
+<hb-player-live
+  mediauri="https://example.com/path/to/whep"
+  media_type="whep"
+></hb-player-live>
+```
+
+**Forced cover with JSON copy** (`replacewithtext` must be a valid JSON string attribute)
+
+```html
+<hb-player-live
+  mediauri="https://example.com/stream/whep"
+  media_type="whep"
+  forcecover="yes"
+  replacewithtext='{"title":"Stream paused","subtitle":"We will be back soon","text":"Thank you for waiting."}'
+></hb-player-live>
+```
+
+**Hide native controls**
+
+```html
+<hb-player-live
+  mediauri="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"
+  media_type="hls"
+  no_controls="yes"
+></hb-player-live>
+```
+
+**Listen for live state and grab the video element**
+
+```html
+<hb-player-live
+  id="cam1"
+  mediauri="https://example.com/live.m3u8"
+  media_type="hls"
+></hb-player-live>
+<script>
+  const el = document.querySelector("#cam1");
+  el.addEventListener("liveStatus", (e) => {
+    console.log(e.detail.live, e.detail.id);
+  });
+  el.addEventListener("htmlVideoInit", (e) => {
+    console.log(e.detail.htmlVideoElement, e.detail.id);
+  });
+  customElements.whenDefined("hb-player-live").then(() => {
+    const v = el.getVideoElement?.();
+    if (v) console.log("video", v);
+  });
+</script>
+```

package/manifest.json

@@ -146,19 +146,32 @@
     }
   },
   "styleSetup": {
-    "vars": [],
+    "vars": [
+      {
+        "name": "--bulma-dark",
+        "valueType": "color",
+        "defaultValue": "",
+        "description": "Background of the 16:9 video area and offline/cover overlay; pair with `--bulma-dark-invert` for readable contrast."
+      },
+      {
+        "name": "--bulma-dark-invert",
+        "valueType": "color",
+        "defaultValue": "",
+        "description": "Foreground (text) color on the dark video/placeholder surface."
+      }
+    ],
     "parts": [
       {
         "name": "container",
-        "description": ""
+        "description": "Root wrapper around the player and overlay; use for layout, sizing, or positioning the whole component."
       },
       {
         "name": "replacewithtext",
-        "description": ""
+        "description": "Full-bleed overlay shown when `forcecover` is set, the stream is not live, or there is no URI; contains default copy or slotted content."
       },
       {
         "name": "video",
-        "description": ""
+        "description": "The native `<video>` element (HLS / WebRTC / WHEP); style dimensions, object-fit, or controls appearance from the host page."
       }
     ]
   },
@@ -166,19 +179,19 @@
   "htmlSlots": [
     {
       "name": "replacewithtext",
-      "description": "Custom block when the stream is unavailable or covered (wraps title/subtitle/text slots)."
+      "description": "Replaces the entire offline/cover layout when shown. Use for custom markup; inner slots (`replacetitle`, `replacesubtitle`, `replacetext`) only apply inside the default structure when you do not override this slot."
     },
     {
       "name": "replacetitle",
-      "description": "Title inside the replace-with-text block."
+      "description": "Heading line in the default overlay; falls back to `replacewithtext.title` from the JSON prop when empty."
     },
     {
       "name": "replacesubtitle",
-      "description": "Subtitle inside the replace-with-text block."
+      "description": "Secondary line in the default overlay; falls back to `replacewithtext.subtitle` when empty (only when both title and subtitle are defined in props)."
     },
     {
       "name": "replacetext",
-      "description": "Body text inside the replace-with-text block."
+      "description": "Body copy in the default overlay; falls back to `replacewithtext.text` when empty (three-line layout only)."
     }
   ],
   "i18n": [],
@@ -264,5 +277,5 @@
   "size": {},
   "iifePath": "main.iife.js",
   "repoName": "@htmlbricks/hb-player-live",
-  "version": "0.71.35"
+  "version": "0.71.36"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htmlbricks/hb-player-live",
-  "version": "0.71.35",
+  "version": "0.71.36",
   "contributors": [],
   "description": "Live streaming `<video>` player for HLS (hls.js or native), WebSocket WebRTC (`simple-webrtc-element`), or WHEP (MediaMTX). Polls the manifest for HLS liveness, exposes the element via `getVideoElement`, and emits `liveStatus` and `htmlVideoInit`. When the stream is offline or missing, shows optional title/subtitle/text from `replacewithtext`, `forcecover`, or fallback labels.",
   "licenses": [