@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

Overview

This package ships two standalone components:

Component	Selector	Purpose
MJMediaPlayerComponent	mj-media-player	Generic, framework-agnostic player. You give it one or more MediaTracks (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.

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

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

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

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

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

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

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

License

ISC