@memberjunction/ng-media-player

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.

Installation

npm install @memberjunction/ng-media-player
Copy

Overview

This package ships two standalone components:

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.

flowchart TD
    subgraph Wrapper["MJStorageMediaPlayerComponent (mj-storage-media-player)"]
        F["FileID / FileIDs[]"] --> M["CreateMediaAccessToken mutation
(per-user permission check)"]
        M --> U["/media/:fileId?token= streaming URL
+ 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

    style Wrapper fill:#2d6a9f,stroke:#1a4971,color:#fff
    style Generic fill:#2d8659,stroke:#1a5c3a,color:#fff
Copy

Key features

• 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.

Usage

Generic player (plain URLs)

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() { /* ... */ }
}
Copy

Storage-backed player (MJ: Files)

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[] = [ /* ... */ ];
}
Copy

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

Outputs

Before* events are cancelable — set event.Cancel = true in a handler to abort.

Methods (imperative API)

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

Read-only getters

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).

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

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; }
Copy

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

npm run build   # ngc
npm run test    # vitest
Copy

License

ISC