@portalshq/capability-video-delivery 0.1.4 → 0.1.8

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,16 +1,77 @@
1
1
  # @portalshq/capability-video-delivery
2
2
 
3
3
  `LiveDelivery` connects one configured HLS playback stream per instance. It
4
- does not create an origin, schedule programs, or define whether content is
5
- "live" or "VOD"; those are application business decisions. It verifies the
6
- configured manifest on start, retries connection failures, and continues to
7
- monitor its health while active.
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.
8
8
 
9
9
  `HlsPlaybackSession` is the common, token-free descriptor for an HLS-capable
10
10
  application player. Queue Broadcast returns this descriptor after its trusted
11
11
  backend has talked to the queue control plane; the player receives only the
12
12
  public/unlisted manifest URL.
13
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.
57
+
58
+ ```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
+ });
70
+
71
+ // Call when replacing the player/session.
72
+ captions.dispose();
73
+ ```
74
+
14
75
  ## Scheduled and dual-format programming
15
76
 
16
77
  Create separate delivery objects for independent stream windows. For example,
@@ -30,5 +91,20 @@ const afternoon = new LiveDelivery({
30
91
  });
31
92
 
32
93
  await morning.start();
33
- // Application-owned scheduler later calls morning.stop() and afternoon.start().
94
+ // Application routing later calls morning.stop() and afternoon.start().
34
95
  ```
96
+
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.
102
+
103
+ ## Browser playback
104
+
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.
@@ -0,0 +1,18 @@
1
+ import { type CaptionTrack } from "./captions.js";
2
+ import type { HlsPlaybackSession } from "./live-session.js";
3
+ export * from "./live-captions.js";
4
+ export * from "./hls-playback-controller.js";
5
+ export interface MountedCaptionTracks {
6
+ /** The exact native elements added to the player. */
7
+ readonly elements: readonly HTMLTrackElement[];
8
+ /** Removes only the tracks added by this mount operation. */
9
+ remove(): void;
10
+ }
11
+ /**
12
+ * Adds sidecar captions to a browser media element. This deliberately uses
13
+ * native HTML track rendering, so captions stay selectable and never become
14
+ * part of the encoded HLS stream.
15
+ */
16
+ export declare function mountCaptionTracks(player: HTMLMediaElement, tracks: readonly CaptionTrack[]): MountedCaptionTracks;
17
+ /** Mounts every caption track declared by a `LiveDelivery` playback session. */
18
+ export declare function mountPlaybackCaptions(player: HTMLMediaElement, playback: Pick<HlsPlaybackSession, "captionTracks">): MountedCaptionTracks;
@@ -0,0 +1,48 @@
1
+ import { createWebVtt, normalizeCaptionTracks } from "./captions.js";
2
+ export * from "./live-captions.js";
3
+ export * from "./hls-playback-controller.js";
4
+ /**
5
+ * Adds sidecar captions to a browser media element. This deliberately uses
6
+ * native HTML track rendering, so captions stay selectable and never become
7
+ * part of the encoded HLS stream.
8
+ */
9
+ export function mountCaptionTracks(player, tracks) {
10
+ const normalizedTracks = normalizeCaptionTracks(tracks);
11
+ const document = player.ownerDocument;
12
+ if (!document)
13
+ throw new TypeError("player must belong to a document");
14
+ const objectUrls = [];
15
+ let removed = false;
16
+ const elements = normalizedTracks.map((caption) => {
17
+ const element = document.createElement("track");
18
+ element.setAttribute("data-video-delivery-caption", caption.id);
19
+ element.kind = caption.kind ?? "captions";
20
+ if (caption.src !== undefined) {
21
+ element.src = caption.src;
22
+ }
23
+ else {
24
+ const objectUrl = URL.createObjectURL(new Blob([createWebVtt(caption.cues)], { type: "text/vtt" }));
25
+ objectUrls.push(objectUrl);
26
+ element.src = objectUrl;
27
+ }
28
+ element.srclang = caption.language;
29
+ element.label = caption.label;
30
+ element.default = caption.default ?? false;
31
+ player.append(element);
32
+ return element;
33
+ });
34
+ return {
35
+ elements,
36
+ remove: () => {
37
+ if (removed)
38
+ return;
39
+ removed = true;
40
+ elements.forEach((element) => element.remove());
41
+ objectUrls.forEach((objectUrl) => URL.revokeObjectURL(objectUrl));
42
+ },
43
+ };
44
+ }
45
+ /** Mounts every caption track declared by a `LiveDelivery` playback session. */
46
+ export function mountPlaybackCaptions(player, playback) {
47
+ return mountCaptionTracks(player, playback.captionTracks ?? []);
48
+ }
@@ -0,0 +1,139 @@
1
+ export interface BufferedProgrammingContent {
2
+ sequence: number;
3
+ totalBytes: number;
4
+ totalDurationSeconds: number;
5
+ idempotencyPrefix: string;
6
+ contentId?: string;
7
+ image?: {
8
+ sha256?: string;
9
+ };
10
+ video?: {
11
+ sha256?: string;
12
+ };
13
+ }
14
+ export interface ProgrammingDeliveryJob {
15
+ id: string;
16
+ status: string;
17
+ }
18
+ export interface ProgrammingPipelineMetrics {
19
+ sequence: number;
20
+ generationStartedAt?: number;
21
+ generationEndedAt?: number;
22
+ stagingStartedAt?: number;
23
+ stagingEndedAt?: number;
24
+ releasedAt?: number;
25
+ monitoringEndedAt?: number;
26
+ generationMs?: number;
27
+ stagingMs?: number;
28
+ pipelineMs?: number;
29
+ jobStateTransitions: Array<{
30
+ timestamp: number;
31
+ jobId: string;
32
+ from?: string;
33
+ to: string;
34
+ }>;
35
+ }
36
+ export interface ProgrammingPipelineStatus {
37
+ inFlightGeneration: number;
38
+ preparedBytes: number;
39
+ readySeconds: number;
40
+ stagedTurns: number;
41
+ releasedTurns: number;
42
+ nextReleaseSequence: number;
43
+ }
44
+ export interface BufferedProgrammingPipelineOptions<TPrepared extends BufferedProgrammingContent, TJob extends ProgrammingDeliveryJob> {
45
+ initialSequence: number;
46
+ generateTurn: (sequence: number, signal: AbortSignal) => Promise<TPrepared | undefined>;
47
+ stageTurn: (turn: TPrepared, signal: AbortSignal) => Promise<void>;
48
+ releaseTurn: (turn: TPrepared, signal: AbortSignal) => Promise<TJob[]>;
49
+ monitorJobs: (jobs: TJob[], signal: AbortSignal, onJobUpdate: (job: TJob) => void) => Promise<void>;
50
+ onError: (cause: unknown, phase: "generation" | "staging" | "release" | "monitoring", sequence: number) => void;
51
+ onActiveJobsChanged: (jobIds: string[]) => void;
52
+ onMetrics: (metrics: ProgrammingPipelineMetrics) => void;
53
+ maxReadySeconds?: number;
54
+ maxPreparedBytes?: number;
55
+ maxInFlightGeneration?: number;
56
+ safetyMarginMs?: number;
57
+ /**
58
+ * How many *distinct visuals* may sit staged-or-released (queued at the
59
+ * Streamer) ahead of playout. 2-3 keeps the next image(s) ready so queue
60
+ * time never eats into per-image playback duration. Split narration
61
+ * segments share one contentId and count as one visual. The Streamer plays
62
+ * FIFO, each slot for its own imageDuration; releases are immediate, never
63
+ * paced to playout. Video-safe: a future video turn counts as one visual
64
+ * exactly like an image turn.
65
+ */
66
+ maxBufferedSlots?: number;
67
+ }
68
+ export type ProgrammingReleaseResult = {
69
+ state: "released";
70
+ sequence: number;
71
+ jobIds: string[];
72
+ } | {
73
+ state: "pending";
74
+ } | {
75
+ state: "blocked";
76
+ episodeStart: number;
77
+ };
78
+ /**
79
+ * Generates ambient turns ahead of playout, stages them remotely, and only
80
+ * releases FIFO work when doing so cannot delay the next scheduled episode.
81
+ * The class owns all background promises so a coordinator can abort and join
82
+ * them during stop, restart, and mode changes.
83
+ */
84
+ export declare class BufferedProgrammingPipeline<TPrepared extends BufferedProgrammingContent, TJob extends ProgrammingDeliveryJob> {
85
+ private readonly options;
86
+ private readonly generatedTurns;
87
+ private readonly stagedTurns;
88
+ private readonly releasedTurns;
89
+ private readonly skippedSequences;
90
+ private readonly inFlightGeneration;
91
+ private readonly metrics;
92
+ private readonly monitorPromises;
93
+ private readonly maxReadySeconds;
94
+ private readonly maxPreparedBytes;
95
+ private readonly maxInFlightGeneration;
96
+ private readonly maxBufferedSlots;
97
+ private readonly safetyMarginMs;
98
+ private controller;
99
+ private refillPromise;
100
+ private nextGenerationSequence;
101
+ private nextStageSequence;
102
+ private nextReleaseSequence;
103
+ private preparedBytes;
104
+ private nextGenerationAt;
105
+ private revision;
106
+ private waiters;
107
+ constructor(options: BufferedProgrammingPipelineOptions<TPrepared, TJob>);
108
+ getStatus(): ProgrammingPipelineStatus;
109
+ start(signal: AbortSignal): void;
110
+ releaseNextSafe(nextEpisodeStart: number | null, signal: AbortSignal): Promise<ProgrammingReleaseResult>;
111
+ waitForProgress(afterRevision: number, signal: AbortSignal): Promise<void>;
112
+ currentRevision(): number;
113
+ abortAndAwaitAll(reason?: Error): Promise<void>;
114
+ private refill;
115
+ private launchGeneration;
116
+ private stageGeneratedTurns;
117
+ private startMonitoring;
118
+ private canReleaseTurn;
119
+ private hasGenerationCapacity;
120
+ private hasPreparedCapacity;
121
+ private readySeconds;
122
+ private releasedDurationSeconds;
123
+ private stagedDurationSeconds;
124
+ /**
125
+ * Distinct visuals currently reserving remote capacity (staged + released).
126
+ * Split siblings share one contentKey, so N slots of the same picture count
127
+ * as one — the buffer guarantees distinct images, not delivery slots.
128
+ * Staging gate only: releases are gated on released visuals alone so a
129
+ * full staged buffer can always drain.
130
+ */
131
+ private bufferedDistinctCount;
132
+ /** Distinct visuals already released and still outstanding (playing/monitored). */
133
+ private releasedDistinctCount;
134
+ private workerSignal;
135
+ private metricsFor;
136
+ private publishMetrics;
137
+ private publishActiveJobs;
138
+ private notify;
139
+ }