@portalshq/capability-video-delivery 0.1.8 → 0.1.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,110 +1,27 @@
1
1
  # @portalshq/capability-video-delivery
2
2
 
3
- `LiveDelivery` connects one configured HLS playback stream per instance. It
4
- does not create an origin or define whether content is "live" or "VOD"; those
5
- are application decisions. It verifies the configured manifest on start,
6
- retries connection failures, monitors health, and can run the package-owned
7
- release scheduler from an injected application programming policy.
3
+ **Reusable agent module:** [integration guide](../../docs/package-agents/video-delivery.md)
8
4
 
9
- `HlsPlaybackSession` is the common, token-free descriptor for an HLS-capable
10
- application player. Queue Broadcast returns this descriptor after its trusted
11
- backend has talked to the queue control plane; the player receives only the
12
- public/unlisted manifest URL.
13
-
14
- ## Sidecar captions
15
-
16
- Captions are a `video-delivery` feature: it validates supplied WebVTT URLs or
17
- timed cues, returns them with the playback descriptor, and mounts native HTML
18
- `<track>` elements in the viewer. They are never pixels burned into the stream.
19
- For supplied cues, the package creates and later revokes a browser-local WebVTT
20
- source. A cross-origin caption host must permit the player origin with the
21
- appropriate CORS headers.
22
-
23
- ```ts
24
- const playback = await client.getPlayback({
25
- captionTracks: [{
26
- id: "en",
27
- label: "English",
28
- language: "en",
29
- cues: [
30
- { startTimeSeconds: 0, endTimeSeconds: 2.5, text: "Welcome." },
31
- ],
32
- default: true,
33
- }],
34
- });
35
- ```
36
-
37
- ```ts
38
- import { mountPlaybackCaptions } from "@portalshq/capability-video-delivery/browser";
39
-
40
- const video = document.querySelector("video")!;
41
- video.src = playback.playbackManifestUrl;
42
- const mountedCaptions = mountPlaybackCaptions(video, playback);
43
-
44
- // Remove these package-managed tracks when this playback session is replaced.
45
- mountedCaptions.remove();
46
- ```
47
-
48
- Use `src` instead of `cues` when the consuming app already hosts a `.vtt` file.
49
- `createWebVtt(cues)` is also available when it needs VTT content for a custom
50
- storage flow.
51
-
52
- ## Realtime live captions
53
-
54
- For a live HLS timeline, use `createLiveCaptionController` rather than a fixed
55
- VTT cue list. It creates a native browser text track, forces it visible, and
56
- timestamps each supplied event at the player's current media time.
5
+ HLS playback health checks, browser playback helpers, sidecar captions, and optional application-policy programming. It does not provision an origin, sign manifests, or decide live/VOD product rules.
57
6
 
58
7
  ```ts
59
- import { createLiveCaptionController } from "@portalshq/capability-video-delivery/browser";
60
-
61
- const captions = createLiveCaptionController(video, {
62
- id: "en-live",
63
- label: "English",
64
- language: "en",
65
- });
66
-
67
- captionEvents.subscribe(({ text, durationSeconds }) => {
68
- captions.publish({ text, durationSeconds });
69
- });
8
+ import { LiveDelivery } from "@portalshq/capability-video-delivery";
70
9
 
71
- // Call when replacing the player/session.
72
- captions.dispose();
10
+ const delivery = new LiveDelivery({ sessionId, playbackManifestUrl });
11
+ const playback = await delivery.start(); // fetches and validates the manifest
12
+ // Hand only playback.playbackManifestUrl to the viewer.
13
+ await delivery.stop();
73
14
  ```
74
15
 
75
- ## Scheduled and dual-format programming
76
-
77
- Create separate delivery objects for independent stream windows. For example,
78
- an application can start a `morning` instance for a 9am–12pm manifest and an
79
- `afternoon` instance for a 1pm–5pm manifest. The application owns that clock,
80
- its routing, and any VOD-versus-live presentation rules; each `LiveDelivery`
81
- object only observes and returns its one configured HLS stream.
82
-
83
- ```ts
84
- const morning = new LiveDelivery({
85
- sessionId: "morning-stream",
86
- playbackManifestUrl: "https://media.example/morning/index.m3u8",
87
- });
88
- const afternoon = new LiveDelivery({
89
- sessionId: "afternoon-stream",
90
- playbackManifestUrl: "https://media.example/afternoon/index.m3u8",
91
- });
92
-
93
- await morning.start();
94
- // Application routing later calls morning.stop() and afternoon.start().
95
- ```
16
+ ## Exports
96
17
 
97
- For queue-backed programming, pass `programming` to `LiveDelivery`, or use
98
- `BufferedProgrammingPipeline` directly. The application provides candidates,
99
- generation/staging callbacks, release policy, limits, and configuration.
100
- Video Delivery owns single-flight scheduling, FIFO commit/release, safe
101
- canonical boundaries, shared-visual buffer accounting, monitoring, and stop.
18
+ - Root: `LiveDelivery`, `HlsPlaybackSession`, caption types/helpers, and programming pipeline types.
19
+ - `@portalshq/capability-video-delivery/browser`: `HlsPlaybackController`, `mountPlaybackCaptions`, and `createLiveCaptionController`.
20
+ - `@portalshq/capability-video-delivery/react`: `VideoDeliveryPlayer`.
102
21
 
103
- ## Browser playback
22
+ ## Usage notes
104
23
 
105
- `HlsPlaybackController` in the `/browser` export owns native HLS selection,
106
- optional hls.js attachment, media recovery, bounded reconnects, replacement,
107
- and cleanup. `VideoDeliveryPlayer` in the `/react` export combines that
108
- controller with captions and a held frame. Pass `externalPlayer` when an app
109
- needs its own video element component; return the element through `mediaRef`
110
- and the package retains the HLS/reconnect state machine.
24
+ - `LiveDelivery.start()` retries manifest access (three attempts by default), then performs periodic health checks. Inspect `getStatus()` for health and the last failure.
25
+ - Call browser-caption `remove()` or live-caption `dispose()` when replacing a player/session.
26
+ - Native HLS is used where available; `hls.js` is an optional peer dependency for other browsers. React is required only for the `/react` entry point.
27
+ - The manifest URL must be public/unlisted or otherwise playable by the browser. Do not expose origin/control-plane credentials.
@@ -94,7 +94,13 @@ export class HlsPlaybackController {
94
94
  };
95
95
  media.onplaying = guard(() => { this.attempts = 0; this.observe("playing"); });
96
96
  media.onwaiting = guard(() => this.observe("buffering"));
97
- media.onstalled = guard(() => this.reconnect(new Error("media stalled")));
97
+ /* `onstalled` is deliberately left unbound. Chrome fires it every few
98
+ seconds on a perfectly healthy MSE-backed HLS stream — readyState
99
+ intact, no error, currentTime still climbing. Treating it as a failure
100
+ tore the stream down and restarted it from zero on a loop; reporting it
101
+ as buffering just flickers the status bar over playing video. A real
102
+ outage surfaces as `waiting` (underrun) or a fatal hls.js NETWORK_ERROR,
103
+ and both are already handled. */
98
104
  media.onerror = guard(() => this.reconnect(media.error ?? new Error("media playback failed")));
99
105
  }
100
106
  cleanupSource() {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@portalshq/capability-video-delivery",
3
- "version": "0.1.8",
3
+ "version": "0.1.10",
4
4
  "repository": {
5
5
  "type": "git",
6
6
  "url": "git+https://github.com/portalshq/portals-cloud.git",
@@ -47,7 +47,9 @@
47
47
  },
48
48
  "devDependencies": {
49
49
  "@types/node": "^20.0.0",
50
+ "@types/react": "^18.0.0",
50
51
  "@vitest/coverage-v8": "^3.2.7",
52
+ "react": "^18.0.0",
51
53
  "typescript": "^5.5.0",
52
54
  "vitest": "^3.2.7"
53
55
  },