@memberjunction/ng-media-player 0.0.1 → 5.44.0

package/README.md

@@ -1,45 +1,258 @@
 # @memberjunction/ng-media-player
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+A world-class, zero-dependency Angular media (audio/video) player for MemberJunction applications, plus an MJStorage-bound wrapper that streams files stored in any MJ storage provider. The generic player has **no MemberJunction-core dependency** — it is pure Angular and safe to reuse in any app; all the MJ wiring lives in the separate wrapper.
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+## Installation
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+```bash
+npm install @memberjunction/ng-media-player
+```
 
-## Purpose
+## Overview
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@memberjunction/ng-media-player`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+This package ships **two** standalone components:
 
-## What is OIDC Trusted Publishing?
+| Component | Selector | Purpose |
+|-----------|----------|---------|
+| `MJMediaPlayerComponent` | `mj-media-player` | Generic, framework-agnostic player. You give it one or more `MediaTrack`s (plain URLs) and an optional transcript. |
+| `MJStorageMediaPlayerComponent` | `mj-storage-media-player` | MJStorage-bound wrapper. You give it an `MJ: Files` `FileID` (or several); it resolves each to a short-lived authenticated streaming URL and hands them to the generic player. |
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+The generic player renders a custom transport bar (play/pause, click-and-drag scrubber, playback-rate menu, ±skip, volume + mute, fullscreen), a **real audio waveform** that doubles as the scrubber, and an optional **time-synced transcript** whose cues are clickable and auto-highlight as playback advances. For a single audio track it shows the transport + waveform; for multiple video tracks it renders a responsive grid.
 
-## Setup Instructions
+```mermaid
+flowchart TD
+    subgraph Wrapper["MJStorageMediaPlayerComponent (mj-storage-media-player)"]
+        F["FileID / FileIDs[]"] --> M["CreateMediaAccessToken mutation<br/>(per-user permission check)"]
+        M --> U["/media/:fileId?token= streaming URL<br/>+ optional peaks.json peaks"]
+    end
+    subgraph Generic["MJMediaPlayerComponent (mj-media-player)"]
+        T["MediaTrack[]"] --> P["Transport bar + waveform scrubber"]
+        T --> W["Real waveform (supplied Peaks OR client-decoded)"]
+        C["MediaTranscriptCue[]"] --> X["Click-to-seek transcript (auto-highlight)"]
+    end
+    U -->|"MediaTrack[] (Url + Peaks)"| Generic
 
-To properly configure OIDC trusted publishing for this package:
+    style Wrapper fill:#2d6a9f,stroke:#1a4971,color:#fff
+    style Generic fill:#2d8659,stroke:#1a5c3a,color:#fff
+```
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+## Key features
 
-## DO NOT USE THIS PACKAGE
+- **Custom transport** — play/pause, click-and-drag scrubber, playback-rate menu, ±skip (configurable seconds), volume slider + mute, fullscreen for video.
+- **Real audio waveform** — for audio-only tracks the player renders a true waveform (not a synthetic one) that **IS** the scrubber. Peaks are either supplied via `MediaTrack.Peaks` (rendered as-is, no decode) or extracted client-side by decoding the track URL through an `AudioContext`. On any decode failure it falls back gracefully to a plain progress bar.
+- **Time-synced transcript** — supply `MediaTranscriptCue[]` and the player renders a transcript panel; clicking a cue seeks to its start, and the active cue auto-highlights as playback advances. Defaults to **below** the player (`TranscriptPosition='bottom'`) with a show/hide toggle in the transport bar.
+- **Loading / buffering state** — a `MediaPlaybackState` lifecycle (`idle`/`loading`/`buffering`/`ready`/`playing`/`paused`/`ended`/`error`) drives a stage busy-indicator overlay (the buffering spinner is debounced so instant seeks don't flash it) and a screen-reader-friendly status label.
+- **Multi-track video grid** — multiple video tracks render in a responsive grid; the first video leads the master timeline.
+- **Keyboard support** — space (play/pause), ←/→ (±5s), J/L (±10s), ↑/↓ (volume), M (mute), F (fullscreen); the scrubber itself is a `role="slider"` with arrow/Home/End support.
+- **Cancelable `Before*` events** — `BeforePlay`/`BeforePause`/`BeforeSeek`/`BeforeRateChange` each pass an event object; set `event.Cancel = true` to abort the pending action (mirrors the ng-conversations `beforeAgentTurn` pattern).
+- **Imperative API** — `Play()`, `Pause()`, `SeekToMs()`, `SetPlaybackRate()`, `SeekToCue()`, etc.
+- **Reduced-motion aware** — suppresses the waveform draw-in animation when the user prefers reduced motion.
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+## Usage
 
-## More Information
+### Generic player (plain URLs)
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+```typescript
+import { MJMediaPlayerComponent, MediaTrack, MediaTranscriptCue } from '@memberjunction/ng-media-player';
 
----
+@Component({
+  standalone: true,
+  imports: [MJMediaPlayerComponent],
+  template: `
+    <mj-media-player
+      [Tracks]="tracks"
+      [Transcript]="transcript"
+      (Ended)="onEnded()">
+    </mj-media-player>
+  `,
+})
+export class MyComponent {
+  tracks: MediaTrack[] = [
+    { Id: 'a1', Kind: 'audio', Url: 'https://example.com/interview.wav' },
+  ];
+  transcript: MediaTranscriptCue[] = [
+    { Id: 'c1', StartMs: 0,    SpeakerLabel: 'Host',  Text: 'Welcome to the show.' },
+    { Id: 'c2', StartMs: 3200, SpeakerLabel: 'Guest', Text: 'Thanks for having me.' },
+  ];
+  onEnded() { /* ... */ }
+}
+```
 
-**Maintained for OIDC setup purposes only**
+### Storage-backed player (MJ: Files)
+
+```typescript
+import { MJStorageMediaPlayerComponent } from '@memberjunction/ng-media-player';
+
+@Component({
+  standalone: true,
+  imports: [MJStorageMediaPlayerComponent],
+  template: `
+    <mj-storage-media-player
+      [FileID]="recordingFileId"
+      [Transcript]="transcript">
+    </mj-storage-media-player>
+  `,
+})
+export class RecordingPlaybackComponent {
+  recordingFileId = '...';            // an MJ: Files row ID
+  transcript: MediaTranscriptCue[] = [ /* ... */ ];
+}
+```
+
+The wrapper resolves the file id to a streaming URL on init (and whenever `FileID`/`FileIDs` change), surfacing graceful loading / no-access / empty states while it does.
+
+## `MJMediaPlayerComponent` (`mj-media-player`)
+
+### Inputs
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `Tracks` | `MediaTrack[]` | `[]` | The track(s) to play. One audio track → transport bar + waveform; many videos → grid. |
+| `Transcript` | `MediaTranscriptCue[] \| null` | `null` | Transcript cues. When set (and `ShowTranscript`), a transcript panel renders. |
+| `Autoplay` | `boolean` | `false` | Begin playback automatically once media is ready. |
+| `StartAtMs` | `number \| null` | `null` | Start playback at this position (ms) once metadata loads. |
+| `ShowTranscript` | `boolean` | `true` | Master switch for the transcript panel (when a transcript is provided). |
+| `ShowTranscriptToggle` | `boolean` | `true` | Whether the transcript show/hide toggle renders in the transport bar. |
+| `ShowSpeedControl` | `boolean` | `true` | Whether the playback-rate menu is shown. |
+| `ShowSkipControls` | `boolean` | `true` | Whether the ±skip buttons are shown. |
+| `ShowVolume` | `boolean` | `true` | Whether the volume slider + mute are shown. |
+| `ShowWaveform` | `boolean` | `true` | Whether the real audio waveform (which doubles as the scrubber) is shown for audio-only tracks. |
+| `WaveformBarCount` | `number` | `DEFAULT_WAVEFORM_BARS` | Number of bars the waveform renders / downsamples to. |
+| `ShowFullscreen` | `boolean` | `true` | Whether the fullscreen button is shown for video. |
+| `SkipSeconds` | `number` | `30` | Seconds the ±skip buttons jump. |
+| `PlaybackRates` | `number[]` | `[0.5, 1, 1.25, 1.5, 2]` | Rates offered in the rate menu. |
+| `InitialRate` | `number` | `1` | Initial playback rate. |
+| `InitialVolume` | `number` | `1` | Initial volume (0..1). |
+| `TranscriptPosition` | `'bottom' \| 'side'` | `'bottom'` | Where the transcript panel sits relative to the media. |
+
+### Outputs
+
+`Before*` events are **cancelable** — set `event.Cancel = true` in a handler to abort.
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `BeforePlay` | `EventEmitter<MediaPlayerCancelableEvent>` | Before playback starts (cancelable). |
+| `AfterPlay` | `EventEmitter<void>` | After playback starts. |
+| `BeforePause` | `EventEmitter<MediaPlayerCancelableEvent>` | Before pause (cancelable). |
+| `AfterPause` | `EventEmitter<void>` | After pause. |
+| `BeforeSeek` | `EventEmitter<MediaSeekEvent>` | Before a seek (cancelable; carries `FromMs`/`ToMs`). |
+| `AfterSeek` | `EventEmitter<number>` | After a seek (the new position in ms). |
+| `BeforeRateChange` | `EventEmitter<MediaRateEvent>` | Before a rate change (cancelable; carries `FromRate`/`ToRate`). |
+| `AfterRateChange` | `EventEmitter<number>` | After a rate change (the new rate). |
+| `CueActivated` | `EventEmitter<MediaCueEvent>` | When the active transcript cue changes during playback. |
+| `CueClicked` | `EventEmitter<MediaCueEvent>` | When a transcript cue is clicked. |
+| `TimeUpdate` | `EventEmitter<number>` | On every time update (current position in ms). |
+| `DurationChange` | `EventEmitter<number>` | When the media duration is resolved/changes (ms). |
+| `Ended` | `EventEmitter<void>` | When playback reaches the end. |
+| `StateChanged` | `EventEmitter<MediaPlaybackState>` | On every playback-lifecycle transition. |
+| `TranscriptVisibilityChanged` | `EventEmitter<boolean>` | When the transcript is toggled (`true` = shown). |
+
+### Methods (imperative API)
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `Play()` | `void` | Begin playback (honors `BeforePlay`). |
+| `Pause()` | `void` | Pause playback (honors `BeforePause`). |
+| `TogglePlay()` | `void` | Toggle play/pause. |
+| `SeekToMs(ms)` | `void` | Seek to an absolute position (honors `BeforeSeek`). |
+| `SkipForward()` / `SkipBackward()` | `void` | Skip ±`SkipSeconds`. |
+| `SetPlaybackRate(rate)` | `void` | Set the playback rate (honors `BeforeRateChange`). |
+| `SeekToCue(index)` | `void` | Seek to a transcript cue's start (continues playing if playing, repositions if paused). |
+| `SetVolume(v)` | `void` | Set volume 0..1 (unmutes if > 0). |
+| `ToggleMute()` | `void` | Toggle mute. |
+| `EnterFullscreen()` / `ExitFullscreen()` / `ToggleFullscreen()` | `void` | Fullscreen control for video. |
+| `ToggleTranscript()` | `void` | Show/hide the transcript panel (emits `TranscriptVisibilityChanged`). |
+
+Read-only getters expose live state for template binding / inspection, including `CurrentTimeMs`, `DurationMs`, `IsPlaying`, `PlaybackRate`, `ActiveCueIndex`, `MediaState`, `IsLoading`, `IsBuffering`, and `StatusLabel`.
+
+## `MJStorageMediaPlayerComponent` (`mj-storage-media-player`)
+
+Extends `BaseAngularComponent`, so it accepts the standard `[Provider]` input for multi-provider apps.
+
+### Inputs
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `FileID` | `string \| null` | `null` | Convenience single `MJ: Files` id. Combined with `FileIDs`; duplicates are de-duped. |
+| `FileIDs` | `string[]` | `[]` | Multi-track file ids (e.g. separate meeting streams). |
+| `Transcript` | `MediaTranscriptCue[] \| null` | `null` | Transcript cues forwarded to the generic player. |
+| `ShowTranscript` / `ShowTranscriptToggle` / `ShowSpeedControl` / `ShowSkipControls` / `ShowVolume` / `ShowWaveform` / `ShowFullscreen` | `boolean` | `true` | Pass-through feature flags, forwarded to the generic player. |
+| `SkipSeconds` | `number` | `30` | Forwarded skip step. |
+| `PlaybackRates` | `number[]` | `[0.5, 1, 1.25, 1.5, 2]` | Forwarded rate menu. |
+| `Autoplay` | `boolean` | `false` | Forwarded autoplay flag. |
+| `StartAtMs` | `number \| null` | `null` | Forwarded start position. |
+| `TranscriptPosition` | `'side' \| 'bottom'` | `'bottom'` | Forwarded transcript position. |
+
+### Read-only getters
+
+| Getter | Type | Description |
+|--------|------|-------------|
+| `ResolvedTracks` | `MediaTrack[]` | The streaming tracks resolved from the file ids. |
+| `IsLoading` | `boolean` | True while minting access tokens / resolving tracks. |
+| `AccessError` | `string \| null` | A no-access / unavailable message, set only when **nothing** resolved. |
+| `HasFileIds` | `boolean` | Whether any file id is configured. |
+
+## Streaming & permission model (wrapper)
+
+The wrapper resolves each file id by calling the **`CreateMediaAccessToken`** GraphQL mutation (server-side, in `@memberjunction/server`). The server:
+
+1. Runs a **per-user permission check** for the file.
+2. Mints a short-lived (HS256) signed token and returns the authenticated streaming URL `GET /media/:fileId?token=…`.
+3. If a `peaks.json` sidecar sits beside the recording in storage, returns its precomputed waveform **peaks** alongside the URL.
+
+The `<audio>` / `<video>` element then streams that URL natively over **HTTP Range** (progressive playback + seek-before-download for large video) instead of base64'ing the whole file over GraphQL. The `/media` route re-verifies the token's signature/expiry and that it matches the requested file, then range-streams the bytes from the underlying MJ storage provider via `FileStorageBase.GetObjectStream` (see [@memberjunction/storage](../../../MJStorage/docs/STREAMING.md)).
+
+**Waveform peaks:** when the server supplies precomputed peaks (from the `peaks.json` sidecar), the wrapper sets them on `MediaTrack.Peaks` so the generic player renders the real waveform **instantly with no client-side fetch/decode**. When no sidecar exists, audio waveforms still decode client-side from the streaming URL; video shows the plain progress bar.
+
+## Public types
+
+```typescript
+type MediaKind = 'audio' | 'video';
+
+type MediaPlaybackState =
+  | 'idle' | 'loading' | 'buffering' | 'ready'
+  | 'playing' | 'paused' | 'ended' | 'error';
+
+interface MediaTrack {
+  Id: string;            // stable identifier (track-by + event correlation)
+  Kind: MediaKind;       // audio vs. video
+  Url: string;           // http(s) or blob: object URL
+  MimeType?: string;     // optional MIME hint (e.g. 'audio/wav', 'video/mp4')
+  Label?: string;        // optional label shown in multi-track layouts
+  PosterUrl?: string;    // optional poster image for video
+  Peaks?: number[];      // optional precomputed waveform peaks (normalized 0..1, one per bar).
+                         // Supplied → rendered directly, NO client-side decode.
+                         // Absent (audio + waveform on) → player decodes the URL client-side.
+}
+
+interface MediaTranscriptCue {
+  Id: string;            // stable cue identifier
+  StartMs: number;       // cue start (ms from media start)
+  EndMs?: number;        // optional cue end; when absent, the next cue's start is used
+  SpeakerLabel?: string; // optional speaker label (color-coded)
+  Text: string;          // the spoken text
+}
+
+interface MediaPlayerCancelableEvent { Cancel: boolean; }          // set true to abort
+interface MediaSeekEvent extends MediaPlayerCancelableEvent { FromMs: number; ToMs: number; }
+interface MediaRateEvent extends MediaPlayerCancelableEvent { FromRate: number; ToRate: number; }
+interface MediaCueEvent { Cue: MediaTranscriptCue; Index: number; }
+```
+
+Helper utilities (`computeActiveCueIndex`, `downsamplePeaks`, `nextPlaybackState`, transcript-layout resolvers) are also exported from the package public API for reuse and testing.
+
+## Dependencies
+
+- `@angular/common` / `@angular/core` (peer)
+- `@memberjunction/core`, `@memberjunction/graphql-dataprovider`, `@memberjunction/ng-base-types` — used **only** by the storage wrapper. The generic `MJMediaPlayerComponent` has no MemberJunction dependency.
+
+## Building & testing
+
+```bash
+npm run build   # ngc
+npm run test    # vitest
+```
+
+## License
+
+ISC

package/dist/lib/media-player/cue-utils.d.ts

@@ -0,0 +1,24 @@
+import { MediaTranscriptCue } from '../media-player.types';
+/**
+ * Pure computation of the active transcript cue for a given playback position.
+ *
+ * A cue is active when `currentMs` falls within `[StartMs, end)` where `end` is:
+ *  - the cue's own `EndMs` when present, OR
+ *  - the next cue's `StartMs` (the cue runs until the next one begins), OR
+ *  - `+Infinity` for the final cue with no `EndMs` (runs to the end of the media).
+ *
+ * Cues are assumed to be in chronological order by `StartMs`. When more than one
+ * cue qualifies (overlapping ranges), the LAST qualifying cue wins, which matches
+ * the "most recently started" intuition for transcripts.
+ *
+ * @param currentMs current playback position in milliseconds
+ * @param cues the ordered transcript cues
+ * @returns the index of the active cue, or -1 if none is active (e.g. before the first cue)
+ */
+export declare function computeActiveCueIndex(currentMs: number, cues: MediaTranscriptCue[] | null | undefined): number;
+/**
+ * Resolves the effective end time (exclusive) of the cue at `index`.
+ * Uses the cue's own `EndMs`, else the next cue's `StartMs`, else `+Infinity`.
+ */
+export declare function resolveCueEndMs(cues: MediaTranscriptCue[], index: number): number;
+//# sourceMappingURL=cue-utils.d.ts.map

package/dist/lib/media-player/cue-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cue-utils.d.ts","sourceRoot":"","sources":["../../../src/lib/media-player/cue-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE3D;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,kBAAkB,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAe9G;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,kBAAkB,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAUjF"}

package/dist/lib/media-player/cue-utils.js

@@ -0,0 +1,47 @@
+/**
+ * Pure computation of the active transcript cue for a given playback position.
+ *
+ * A cue is active when `currentMs` falls within `[StartMs, end)` where `end` is:
+ *  - the cue's own `EndMs` when present, OR
+ *  - the next cue's `StartMs` (the cue runs until the next one begins), OR
+ *  - `+Infinity` for the final cue with no `EndMs` (runs to the end of the media).
+ *
+ * Cues are assumed to be in chronological order by `StartMs`. When more than one
+ * cue qualifies (overlapping ranges), the LAST qualifying cue wins, which matches
+ * the "most recently started" intuition for transcripts.
+ *
+ * @param currentMs current playback position in milliseconds
+ * @param cues the ordered transcript cues
+ * @returns the index of the active cue, or -1 if none is active (e.g. before the first cue)
+ */
+export function computeActiveCueIndex(currentMs, cues) {
+    if (!cues || cues.length === 0) {
+        return -1;
+    }
+    let activeIndex = -1;
+    for (let i = 0; i < cues.length; i++) {
+        const cue = cues[i];
+        const start = cue.StartMs;
+        const end = resolveCueEndMs(cues, i);
+        if (currentMs >= start && currentMs < end) {
+            activeIndex = i; // last qualifying wins
+        }
+    }
+    return activeIndex;
+}
+/**
+ * Resolves the effective end time (exclusive) of the cue at `index`.
+ * Uses the cue's own `EndMs`, else the next cue's `StartMs`, else `+Infinity`.
+ */
+export function resolveCueEndMs(cues, index) {
+    const cue = cues[index];
+    if (cue.EndMs != null) {
+        return cue.EndMs;
+    }
+    const next = cues[index + 1];
+    if (next) {
+        return next.StartMs;
+    }
+    return Number.POSITIVE_INFINITY;
+}
+//# sourceMappingURL=cue-utils.js.map

package/dist/lib/media-player/cue-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cue-utils.js","sourceRoot":"","sources":["../../../src/lib/media-player/cue-utils.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,qBAAqB,CAAC,SAAiB,EAAE,IAA6C;IACpG,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,OAAO,CAAC,CAAC,CAAC;IACZ,CAAC;IAED,IAAI,WAAW,GAAG,CAAC,CAAC,CAAC;IACrB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC;QAC1B,MAAM,GAAG,GAAG,eAAe,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QACrC,IAAI,SAAS,IAAI,KAAK,IAAI,SAAS,GAAG,GAAG,EAAE,CAAC;YAC1C,WAAW,GAAG,CAAC,CAAC,CAAC,uBAAuB;QAC1C,CAAC;IACH,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,IAA0B,EAAE,KAAa;IACvE,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;IACxB,IAAI,GAAG,CAAC,KAAK,IAAI,IAAI,EAAE,CAAC;QACtB,OAAO,GAAG,CAAC,KAAK,CAAC;IACnB,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;IAC7B,IAAI,IAAI,EAAE,CAAC;QACT,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IACD,OAAO,MAAM,CAAC,iBAAiB,CAAC;AAClC,CAAC","sourcesContent":["import { MediaTranscriptCue } from '../media-player.types';\n\n/**\n * Pure computation of the active transcript cue for a given playback position.\n *\n * A cue is active when `currentMs` falls within `[StartMs, end)` where `end` is:\n *  - the cue's own `EndMs` when present, OR\n *  - the next cue's `StartMs` (the cue runs until the next one begins), OR\n *  - `+Infinity` for the final cue with no `EndMs` (runs to the end of the media).\n *\n * Cues are assumed to be in chronological order by `StartMs`. When more than one\n * cue qualifies (overlapping ranges), the LAST qualifying cue wins, which matches\n * the \"most recently started\" intuition for transcripts.\n *\n * @param currentMs current playback position in milliseconds\n * @param cues the ordered transcript cues\n * @returns the index of the active cue, or -1 if none is active (e.g. before the first cue)\n */\nexport function computeActiveCueIndex(currentMs: number, cues: MediaTranscriptCue[] | null | undefined): number {\n  if (!cues || cues.length === 0) {\n    return -1;\n  }\n\n  let activeIndex = -1;\n  for (let i = 0; i < cues.length; i++) {\n    const cue = cues[i];\n    const start = cue.StartMs;\n    const end = resolveCueEndMs(cues, i);\n    if (currentMs >= start && currentMs < end) {\n      activeIndex = i; // last qualifying wins\n    }\n  }\n  return activeIndex;\n}\n\n/**\n * Resolves the effective end time (exclusive) of the cue at `index`.\n * Uses the cue's own `EndMs`, else the next cue's `StartMs`, else `+Infinity`.\n */\nexport function resolveCueEndMs(cues: MediaTranscriptCue[], index: number): number {\n  const cue = cues[index];\n  if (cue.EndMs != null) {\n    return cue.EndMs;\n  }\n  const next = cues[index + 1];\n  if (next) {\n    return next.StartMs;\n  }\n  return Number.POSITIVE_INFINITY;\n}\n"]}