Interface: RnMediaCast

Defined in: packages/cast/src/specs/cast.nitro.ts:313

First-party binding over the official Google Cast sender SDKs (play-services-cast-framework on Android, google-cast-sdk on iOS), audio-scoped.

Threading contract

Every CastContext/GCKCastContext touch happens on the platform main thread — both SDKs require it — via an internal main-thread trampoline; no method here may be assumed to run on the JS thread natively. Promises resolve from the main thread; Nitro schedules JS callbacks onto the JS thread itself (nitro.margelo.com/docs/types/callbacks).

Error contract

Rejections carry a [code] message prefix from the closed set in src/errors.ts (no-session, load-failed, …). The TS facade parses the prefix into a typed CastError; nothing in JS should match on prose.

Listener registration is id-based (Nitro callbacks are opaque native closures; identity comparison across the bridge is not dependable) — same contract as @afkcodes/timbre-audio-session.

Extends

• HybridObject<{ android: "kotlin"; ios: "swift"; }>

Properties

name

readonly name: string;

Defined in: node_modules/react-native-nitro-modules/lib/typescript/HybridObject.d.ts:52

The HybridObject's name.

Inherited from

HybridObject.name

Methods

addCastStateListener()

addCastStateListener(listener: (event: NativeCastStateEvent) => void): number;

Defined in: packages/cast/src/specs/cast.nitro.ts:525

Parameters

Parameter	Type
listener	(event: NativeCastStateEvent) => void

Returns

number

---

addDevicesListener()

addDevicesListener(listener: (event: NativeCastDevicesEvent) => void): number;

Defined in: packages/cast/src/specs/cast.nitro.ts:531

Parameters

Parameter	Type
listener	(event: NativeCastDevicesEvent) => void

Returns

number

---

addDeviceVolumeListener()

addDeviceVolumeListener(listener: (event: NativeDeviceVolumeEvent) => void): number;

Defined in: packages/cast/src/specs/cast.nitro.ts:557

Parameters

Parameter	Type
listener	(event: NativeDeviceVolumeEvent) => void

Returns

number

---

addMediaErrorListener()

addMediaErrorListener(listener: (event: NativeCastMediaErrorEvent) => void): number;

Defined in: packages/cast/src/specs/cast.nitro.ts:549

Receiver-side media failures. Fires on both platforms — see NativeCastMediaErrorEvent for how (and for the Android-only detail fields).

A single failure reaches JS on two channels (this one and a mediaStatus with idleReason: 'error'); the Cast.addListener('error', …) facade de-duplicates them into one CastError. Subscribe to that, not to this, unless you are driving the hybrid object directly.

Parameters

Parameter	Type
listener	(event: NativeCastMediaErrorEvent) => void

Returns

number

---

addMediaStatusListener()

addMediaStatusListener(listener: (event: NativeCastMediaStatusEvent) => void): number;

Defined in: packages/cast/src/specs/cast.nitro.ts:534

Parameters

Parameter	Type
listener	(event: NativeCastMediaStatusEvent) => void

Returns

number

---

addQueueChangedListener()

addQueueChangedListener(listener: () => void): number;

Defined in: packages/cast/src/specs/cast.nitro.ts:554

Parameters

Parameter	Type
listener	() => void

Returns

number

---

addSessionListener()

addSessionListener(listener: (event: NativeCastSessionEvent) => void): number;

Defined in: packages/cast/src/specs/cast.nitro.ts:528

Parameters

Parameter	Type
listener	(event: NativeCastSessionEvent) => void

Returns

number

---

dispose()

dispose(): void;

Defined in: node_modules/react-native-nitro-modules/lib/typescript/HybridObject.d.ts:94

Disposes any resources this HybridObject might hold natively, and releases this HybridObject's NativeState.

After calling (), this object can no longer be used.

Eagerly disposing a HybridObject could be beneficial for a queue-/handler-architecture where a bunch of Hybrid Objects are allocated, and later deallocated once a callback (e.g. a render function) completes.

Returns

void

Note

It is NOT required to call () manually, as the JavaScript Garbage Collector automatically disposes and releases any resources when needed. It is purely optional to eagerly-, and manually-, call () here - use with caution!

Inherited from

HybridObject.dispose

---

endSession()

endSession(stopReceiver: boolean): Promise<void>;

Defined in: packages/cast/src/specs/cast.nitro.ts:421

End the current session.

Parameters

Parameter	Type	Description
stopReceiver	boolean	true stops receiver playback (the transfer-back-to- local flow: snapshot the position from the last media status first); false disconnects the sender and leaves the receiver playing. Resolves when the session reaches ended.

Returns

Promise<void>

---

equals()

equals(other: HybridObject<{
  android: "kotlin";
  ios: "swift";
}>): boolean;

Defined in: node_modules/react-native-nitro-modules/lib/typescript/HybridObject.d.ts:79

Returns whether this HybridObject is the same object as other.

While two HybridObjects might not be equal when compared with ==, they might still hold the same underlying HybridObject, in which case equals(other) will return true.

Parameters

Parameter	Type
other	HybridObject<{ android: "kotlin"; ios: "swift"; }>

Returns

boolean

Example

const hybridA = SomeModule.getExistingHybridInstance()
const hybridB = SomeModule.getExistingHybridInstance()
console.log(hybridA.equals(hybridB)) // true

Inherited from

HybridObject.equals

---

fetchQueueSlice()

fetchQueueSlice(startIndex: number, count: number): Promise<CastQueueItemSnapshot[]>;

Defined in: packages/cast/src/specs/cast.nitro.ts:518

Page count rows of the sender-side queue mirror starting at startIndex. Resolves immediately with what the cache holds (resolved: false rows trigger one background fetch); re-read after the next queueChanged event. Deliberately never a chatty per-item RPC.

Parameters

Parameter	Type
startIndex	number
count	number

Returns

Promise<CastQueueItemSnapshot[]>

---

getApproximatePosition()

getApproximatePosition(): Promise<number>;

Defined in: packages/cast/src/specs/cast.nitro.ts:447

One approximate-position read, projected by the SDK from the last status update (RemoteMediaClient.getApproximateStreamPosition / GCKRemoteMediaClient.approximateStreamPosition). This is a read, not a stream — position is never polled or streamed across the bridge; clients project locally between mediaStatus discontinuities.

Returns

Promise<number>

---

getCastState()

getCastState(): CastConnectionState;

Defined in: packages/cast/src/specs/cast.nitro.ts:356

Last known connection state, from the native cache. Never blocks. 'unavailable' until initialize has resolved — before init, casting genuinely is not available.

Returns

CastConnectionState

---

getDevices()

getDevices(): Promise<CastDeviceInfo[]>;

Defined in: packages/cast/src/specs/cast.nitro.ts:378

Snapshot of currently discovered devices.

Returns

Promise<CastDeviceInfo[]>

---

getDeviceVolume()

getDeviceVolume(): Promise<NativeDeviceVolumeEvent>;

Defined in: packages/cast/src/specs/cast.nitro.ts:476

Returns

Promise<NativeDeviceVolumeEvent>

---

getQueueItemIds()

getQueueItemIds(): Promise<number[]>;

Defined in: packages/cast/src/specs/cast.nitro.ts:510

All receiver-assigned item ids, in queue order. Cheap (already cached).

Returns

Promise<number[]>

---

initialize()

initialize(receiverApplicationId?: string): Promise<CastConnectionState>;

Defined in: packages/cast/src/specs/cast.nitro.ts:349

Initialize the Cast framework. Idempotent; safe to call again after an unavailable answer (e.g. after the user installs Play services).

Android: CastContext.getSharedInstance(Context, Executor) — the Task-based variant; the framework is a dynamite module fetched from Play services, so a GMS-less device resolves 'unavailable' instead of crashing. The receiver application id comes from the manifest meta-data our OptionsProvider reads; passing receiverApplicationId here overrides it at runtime (CastContext.setReceiverApplicationId).

iOS: GCKCastContext.setSharedInstanceWith(options) with receiverApplicationId (default: the Default Media Receiver).

CEILING (receiver app id, iOS): the id is fixed at first initialize. GCKCastContext exposes only +setSharedInstanceWithOptions: and +isSharedInstanceInitialized (GoogleCast 4.8.6, GCKCastContext.h) — there is no setReceiverApplicationId, no writable options, and GCKDiscoveryManager has no way to swap its GCKDiscoveryCriteria. So a later initialize with a different id is honoured on Android (CastContext.setReceiverApplicationId, verified with javap against play-services-cast-framework 22.3.1) and cannot be honoured on iOS: the first id wins for the life of the process, and the native side logs a warning rather than failing silently. Pass the id on the first call, or set it in the manifest/plist through the Expo plugin.

NOTE (init timing): Google's guidance is to initialize in application(_:didFinishLaunchingWithOptions:) so the SDK can resume a session the app was killed during. Calling this from JS is later than that — automatic session resumption after process death may be missed until the first initialize of a launch. Documented ceiling, not a bug.

Parameters

Parameter	Type
receiverApplicationId?	string

Returns

Promise<CastConnectionState>

---

load()

load(source: CastMediaSource, options: CastLoadOptions): Promise<void>;

Defined in: packages/cast/src/specs/cast.nitro.ts:430

Load a single item (MediaLoadRequestData on both platforms — the only non-deprecated load path, and the one that carries credentials). Requires a connected session; rejects [no-session] otherwise.

Parameters

Parameter	Type
source	CastMediaSource
options	CastLoadOptions

Returns

Promise<void>

---

pause()

pause(): Promise<void>;

Defined in: packages/cast/src/specs/cast.nitro.ts:433

Returns

Promise<void>

---

play()

play(): Promise<void>;

Defined in: packages/cast/src/specs/cast.nitro.ts:432

Returns

Promise<void>

---

queueInsert()

queueInsert(items: CastQueueItemInput[], beforeItemId?: number): Promise<void>;

Defined in: packages/cast/src/specs/cast.nitro.ts:494

Insert before beforeItemId, or append when omitted.

Parameters

Parameter	Type
items	CastQueueItemInput[]
beforeItemId?	number

Returns

Promise<void>

---

queueJumpTo()

queueJumpTo(itemId: number, position?: number): Promise<void>;

Defined in: packages/cast/src/specs/cast.nitro.ts:505

Jump to a queue item, optionally seeking within it.

Parameters

Parameter	Type
itemId	number
position?	number

Returns

Promise<void>

---

queueLoad()

queueLoad(items: CastQueueItemInput[], options: CastQueueLoadOptions): Promise<void>;

Defined in: packages/cast/src/specs/cast.nitro.ts:488

Replace the receiver queue (MediaLoadRequestData + MediaQueueData on both platforms). Receiver-side advancement (autoplay + preloadTime per item) is what keeps playback going while the phone sleeps.

The receiver queue dies with the session by design; the JS queue stays authoritative and rebuilds it on the next session.

Parameters

Parameter	Type
items	CastQueueItemInput[]
options	CastQueueLoadOptions

Returns

Promise<void>

---

queueRemove()

queueRemove(itemIds: number[]): Promise<void>;

Defined in: packages/cast/src/specs/cast.nitro.ts:496

Parameters

Parameter	Type
itemIds	number[]

Returns

Promise<void>

---

queueReorder()

queueReorder(itemIds: number[], beforeItemId?: number): Promise<void>;

Defined in: packages/cast/src/specs/cast.nitro.ts:502

Reorder itemIds (in the given order) to sit before beforeItemId, or at the end when omitted.

Parameters

Parameter	Type
itemIds	number[]
beforeItemId?	number

Returns

Promise<void>

---

queueSetRepeatMode()

queueSetRepeatMode(mode: CastRepeatMode): Promise<void>;

Defined in: packages/cast/src/specs/cast.nitro.ts:507

Parameters

Parameter	Type
mode	CastRepeatMode

Returns

Promise<void>

---

removeCastStateListener()

removeCastStateListener(listenerId: number): void;

Defined in: packages/cast/src/specs/cast.nitro.ts:526

Parameters

Parameter	Type
listenerId	number

Returns

void

---

removeDevicesListener()

removeDevicesListener(listenerId: number): void;

Defined in: packages/cast/src/specs/cast.nitro.ts:532

Parameters

Parameter	Type
listenerId	number

Returns

void

---

removeDeviceVolumeListener()

removeDeviceVolumeListener(listenerId: number): void;

Defined in: packages/cast/src/specs/cast.nitro.ts:560

Parameters

Parameter	Type
listenerId	number

Returns

void

---

removeMediaErrorListener()

removeMediaErrorListener(listenerId: number): void;

Defined in: packages/cast/src/specs/cast.nitro.ts:552

Parameters

Parameter	Type
listenerId	number

Returns

void

---

removeMediaStatusListener()

removeMediaStatusListener(listenerId: number): void;

Defined in: packages/cast/src/specs/cast.nitro.ts:537

Parameters

Parameter	Type
listenerId	number

Returns

void

---

removeQueueChangedListener()

removeQueueChangedListener(listenerId: number): void;

Defined in: packages/cast/src/specs/cast.nitro.ts:555

Parameters

Parameter	Type
listenerId	number

Returns

void

---

removeSessionListener()

removeSessionListener(listenerId: number): void;

Defined in: packages/cast/src/specs/cast.nitro.ts:529

Parameters

Parameter	Type
listenerId	number

Returns

void

---

requestSession()

requestSession(deviceId: string): Promise<void>;

Defined in: packages/cast/src/specs/cast.nitro.ts:386

Connect to a device by CastDeviceInfo.id. Resolves when the session reaches started; rejects [session-start-failed] when the platform reports failure. Discovery must be running (the id has to come from somewhere) — see stopDiscovery for the ordering rule.

Parameters

Parameter	Type
deviceId	string

Returns

Promise<void>

---

seek()

seek(position: number, resumeState: CastSeekResumeState): Promise<void>;

Defined in: packages/cast/src/specs/cast.nitro.ts:438

Seek to position seconds.

Parameters

Parameter	Type
position	number
resumeState	CastSeekResumeState

Returns

Promise<void>

---

setDeviceMuted()

setDeviceMuted(muted: boolean): Promise<void>;

Defined in: packages/cast/src/specs/cast.nitro.ts:475

Parameters

Parameter	Type
muted	boolean

Returns

Promise<void>

---

setDeviceVolume()

setDeviceVolume(volume: number): Promise<void>;

Defined in: packages/cast/src/specs/cast.nitro.ts:474

Physical device volume (0..1) — the primary layer. Android: CastSession.setVolume; iOS: GCKCastSession.setDeviceVolume.

CEILING (iOS): the hardware volume buttons cannot drive it. The SDK still ships the switch (GCKCastOptions.physicalVolumeButtonsWillControlDeviceVolume, GCKCastOptions.h, default NO), but Google's own iOS sender guide states the behaviour is "currently not supported for iOS 15+" because of OS changes (https://developers.google.com/cast/docs/ios_sender/integrate) — so this package deliberately leaves the flag off rather than shipping a switch that does nothing. On Android the cast framework routes the volume keys to the receiver for a connected session. This method is the programmatic path, and on iOS it is the only path.

Parameters

Parameter	Type
volume	number

Returns

Promise<void>

---

setStreamMuted()

setStreamMuted(muted: boolean): Promise<void>;

Defined in: packages/cast/src/specs/cast.nitro.ts:456

Parameters

Parameter	Type
muted	boolean

Returns

Promise<void>

---

setStreamVolume()

setStreamVolume(volume: number): Promise<void>;

Defined in: packages/cast/src/specs/cast.nitro.ts:455

Receiver stream volume (0..1) — the secondary, app-level layer. Device volume is the primary layer users expect hardware buttons to move.

Parameters

Parameter	Type
volume	number

Returns

Promise<void>

---

showCastPicker()

showCastPicker(): Promise<void>;

Defined in: packages/cast/src/specs/cast.nitro.ts:411

Open the platform's device picker (headless-API path for a cast button).

iOS: GCKCastContext.presentCastDialog(). Android: the androidx MediaRouteChooserDialog over the merged cast selector, from the current Activity. On Android 13+ the system output switcher is additionally reachable from any CastButtonFactory-wired cast icon (our CastOptions enable setShowSystemOutputSwitcherOnCastIconClick) and from the media notification — there is no documented public intent for launching the switcher directly, so this method deliberately sticks to documented API.

Resolves when the picker is shown (not when a device is picked — watch the session events). Rejects [invalid-state] with no foreground Activity (Android).

CEILING (iOS): "shown" is unverifiable. -[GCKCastContext presentCastDialog] returns void (GoogleCast 4.8.6, GCKCastContext+UI.h) — with no key window the SDK simply does nothing and reports nothing, so iOS always resolves. Android can and does reject. Do not treat a resolved promise as "the user saw a picker" on either platform.

Returns

Promise<void>

---

startDiscovery()

startDiscovery(): Promise<void>;

Defined in: packages/cast/src/specs/cast.nitro.ts:364

Start device discovery. Discovery is battery-expensive (active mDNS scanning) — scope it to "device picker open", never to app lifetime. Android: MediaRouter.addCallback with CALLBACK_FLAG_REQUEST_DISCOVERY | CALLBACK_FLAG_PERFORM_ACTIVE_SCAN; iOS: GCKDiscoveryManager.startDiscovery.

Returns

Promise<void>

---

stop()

stop(): Promise<void>;

Defined in: packages/cast/src/specs/cast.nitro.ts:435

Stops receiver playback and unloads the media (receiver goes idle).

Returns

Promise<void>

---

stopDiscovery()

stopDiscovery(): Promise<void>;

Defined in: packages/cast/src/specs/cast.nitro.ts:375

Stop device discovery.

Ordering rule (hard-won, encoded natively too): connect after the picker closes but before stopping discovery. If a session start is in flight when this is called, the native side defers the actual teardown until the session start settles, so MediaRouter cannot drop the route mid-handshake even if the JS caller gets the order wrong.

Returns

Promise<void>

---

toString()

toString(): string;

Defined in: node_modules/react-native-nitro-modules/lib/typescript/HybridObject.d.ts:64

Returns a string representation of the given HybridObject.

Unless overridden by the HybridObject, this will return the name of the object.

Returns

string

Example

const hybridA = SomeModule.getExistingHybridInstance()
console.log(hybridA.toString()) // [HybridObject HybridA]

Inherited from

HybridObject.toString