Skip to content

CastSenderPlugin

Reach for this plugin when you want your music player to cast to a Chromecast device. It opens the Cast session picker, forwards the current track to the receiver, and keeps the receiver in sync as the user plays, pauses, seeks, and changes tracks. When the receiver disconnects, the plugin restores local playback from the receiver’s last position.

The music-specific work this class does is small: it sets 'audio/mpeg' as the default content type and maps the music item shape (name, artist, album, cover) to MusicTrackMediaMetadata. Everything else (SDK probe, session negotiation, RemotePlayer event mirroring, forward and rewind helpers, resume-on-disconnect) lives in the core base class.

TypeScript
import { CastSenderPlugin } from '@nomercy-entertainment/nomercy-music-player/plugins';

Plugin id: 'cast-sender'

Options

OptionTypeDefaultDescription
chromecastAppIdstringundefinedChromecast receiver app id. When omitted, the Cast SDK uses the default media receiver.
enableAirPlaybooleanundefinedWhether AirPlay is allowed (Safari only).
customReceiverNamespacestringundefinedCustom receiver namespace for messages sent to the receiver.
resumeLocalOnDisconnectbooleantrueResume local playback after the receiver disconnects, restoring the receiver’s last time and play/pause state.
defaultContentTypestring'audio/mpeg'Override the default MIME type sent to the Cast SDK. Override per-item by setting mime or contentType on the playlist item.
livebooleanfalseTreat the source as a live unbounded stream rather than VOD.

Events

EventPayloadDescription
cast:connected{ deviceName: string }A Cast session is active on the named device.
cast:disconnectedvoidThe Cast session ended, either by calling disconnect() or by a remote disconnect.
cast:error{ error: Error }A Cast error occurred, for example a session refused or a network loss.
cast:remote-state{ time: number; state: 'playing' | 'paused' | 'buffering' }The receiver’s playback state was mirrored to the local player.
cast:media-changed{ contentId: string }The receiver loaded a different media item than the current local track.
unsupported{ reason: string }The Cast SDK is unavailable in this browser, for example Firefox or non-Chromium browsers.

Listen using the namespaced string form:

TypeScript
player.on('plugin:cast-sender:cast:connected', ({ deviceName }) => {
  showCastBadge(deviceName);
});

player.on('plugin:cast-sender:cast:disconnected', () => {
  hideCastBadge();
});

Methods

TypeScript
import { CastSenderPlugin } from '@nomercy-entertainment/nomercy-music-player/plugins';

const castPlugin = player.getPlugin(CastSenderPlugin)!;

isConnected(): boolean

Returns true while a Cast session is established.

TypeScript
if (castPlugin.isConnected()) {
  showCastBadge();
}

connect(): Promise<void>

Opens the Cast session picker. Once the user picks a device, the plugin wires up RemotePlayer listeners and forwards the current track. Emits cast:connected on success, cast:error on failure. Emits unsupported and throws BrowserPolicyError when the Cast SDK is absent, which happens in Firefox and non-Chromium browsers.

TypeScript
connectButton.addEventListener('click', async () => {
  try {
    await castPlugin.connect();
  }
  catch (castError) {
    console.error('Cast failed', castError);
  }
});

disconnect(): void

Ends the current Cast session and tears down RemotePlayer listeners. Safe to call when already disconnected. Emits cast:disconnected when the session is successfully torn down. When the Cast SDK is absent, emits unsupported and returns without emitting cast:disconnected.

TypeScript
stopCastButton.addEventListener('click', () => {
  castPlugin.disconnect();
});

Metadata mapping

The plugin builds MusicTrackMediaMetadata from the current playlist item. When MusicTrackMediaMetadata is not available from the Cast SDK, it falls back to GenericMediaMetadata.

MusicPlaylistItem fieldMusicTrackMediaMetadata field
nametitle
artistartist
albumalbumName
cover (resolved via resolveUrl)images[0].url

Registration

TypeScript
import nmMPlayer from '@nomercy-entertainment/nomercy-music-player';
import {
  CastSenderPlugin,
  AutoAdvancePlugin,
  MediaSessionPlugin,
} from '@nomercy-entertainment/nomercy-music-player/plugins';

const player = nmMPlayer('main')
  .addPlugin(CastSenderPlugin, { resumeLocalOnDisconnect: true })
  .addPlugin(AutoAdvancePlugin)
  .addPlugin(MediaSessionPlugin)
  .setup({
    baseUrl: 'https://raw.githubusercontent.com/NoMercy-Entertainment/nomercy-media/master/Music',
    playlist: [
      {
        id: 'kjc-01',
        name: 'Thaw You Out',
        url: '/D/Derek%20Clegg/%5B2010%5D%20KJC/01%20Thaw%20You%20Out.mp3',
        cover: '/D/Derek%20Clegg/%5B2010%5D%20KJC/01%20Thaw%20You%20Out.jpg',
        artist: 'Derek Clegg',
        album: 'KJC',
      },
    ],
  });

player.on('ready', () => {
  player.item(0, { autoplay: true });
});

See also