@portalshq/capability-video-delivery 0.1.9 → 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 +16 -99
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,110 +1,27 @@
|
|
|
1
1
|
# @portalshq/capability-video-delivery
|
|
2
2
|
|
|
3
|
-
|
|
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
|
-
|
|
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 {
|
|
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
|
-
|
|
72
|
-
|
|
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
|
-
##
|
|
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
|
-
|
|
98
|
-
|
|
99
|
-
|
|
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
|
-
##
|
|
22
|
+
## Usage notes
|
|
104
23
|
|
|
105
|
-
`
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
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.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@portalshq/capability-video-delivery",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.10",
|
|
4
4
|
"repository": {
|
|
5
5
|
"type": "git",
|
|
6
6
|
"url": "git+https://github.com/portalshq/portals-cloud.git",
|
|
@@ -57,4 +57,4 @@
|
|
|
57
57
|
"access": "public",
|
|
58
58
|
"registry": "https://registry.npmjs.org/"
|
|
59
59
|
}
|
|
60
|
-
}
|
|
60
|
+
}
|