IPlayerClient

An interface that represents a PlayerClient.

Properties

clearTextView()

clearTextView: (sessionId?) => Promise<void>

Request the media session in PlayerServer to clear the KeplerCaptionsView rendering the captions content.

Parameters

sessionId?

IPlayerSessionId

Optional. The session ID to target for clearing the captions surface. If not specified, the PlayerServer decides how to handle the request.

Returns

Promise<void>

A Promise that resolves when the request is successfully handled, or rejects with an error if the request fails.

Example

const sessionId: IPlayerSessionId = {id: 1};
try {
  await playerClientRef.current?.clearTextView(sessionId);
} catch (error) {
  console.error('Error while calling clearTextView: ', error);
  // Perform error handling.
}

clearVideoView()

clearVideoView: (sessionId?) => Promise<void>

Request the media session in PlayerServer to clear the KeplerVideoSurfaceView rendering the video content.

Parameters

sessionId?

IPlayerSessionId

Optional. The session ID to target for clearing the video surface. If not specified, the PlayerServer decides how to handle the request.

Returns

Promise<void>

A Promise that resolves when the request is successfully handled, or rejects with an error if the request fails.

Example

const sessionId: IPlayerSessionId = {id: 1};
try {
  await playerClientRef.current?.clearVideoView(sessionId);
} catch (error) {
  console.error('Error while calling clearVideoView: ', error);
  // Perform error handling.
}

destroy()

destroy: () => void

Destroys the kepler player client instance and stop the Kepler Player Service. Clients are expected to call this API for cleanup of media resources when interactive components gets destroyed.

Returns

void

Example

playerClientRef.current?.destroy();

getCurrentPosition()

getCurrentPosition: (sessionId?) => Promise<number>

Request the PlayerServer to get the current playback position of media playback (in seconds).

Parameters

sessionId?

IPlayerSessionId

Optional. The session ID to target with the request. If not provided, the session to target is decided by the PlayerServer.

Returns

Promise<number>

A Promise that resolves when the request is successfully handled, or rejects with an error if the request fails; and it returns number indicating current playback position corresponding to sessionId in seconds.

Details

The media sesssion should update its IPlayerSessionStatus to reflect the new playback status.

Example

const sessionId: IPlayerSessionId = {id: 1};
try {
  let position = await playerClientRef.current?.getCurrentPosition(sessionId);
} catch (error) {
  console.error('Error while calling getCurrentPosition: ', error);
  // Perform error handling.
}

load()

load: (mediaInfo, loadParams?, sessionId?) => Promise<void>

Request the PlayerServer to load the content using the given URL.

Parameters

mediaInfo

IPlayerSessionMediaInfo

The object to describe the necessary URLs and HTTP headers to load media content.

loadParams?

IPlayerSessionLoadParams

Optional. Params required to load content by URL.

sessionId?

IPlayerSessionId

Optional. The session ID to target for loading content. If not specified, the PlayerServer should create a new media session.

Returns

Promise<void>

A Promise that resolves when the request is successfully handled, or rejects with an error if the request fails.

Example

const mediaInfo: IPlayerSessionMediaInfo = {
  mediaUrl: {
    url: 'https://storage.googleapis.com/shaka-demo-assets/angel-one-widevine/dash.mpd',
    httpHeaders: [
      {
        name: 'header1',
        value: 'value1',
      },
      {
        name: 'header2',
        value: 'value2',
      },
    ],
  },
  laUrl: {
    url: 'https://cwip-shaka-proxy.appspot.com/no_auth',
    httpHeaders: [
      {
        name: 'drm_scheme',
        value: 'com.widevine.alpha',
      },
    ],
  },
  oobTextTrackInfo: [
    {
      url: 'https://mtoczko.github.io/hls-test-streams/test-vtt-ts-segments/text/1.vtt',
      kind: 'subtitles',
      label: 'English',
      language: 'en',
      mimeType: 'application/x-subtitle-vtt',
    },
    {
      url: 'https://brenopolanski.github.io/html5-video-webvtt-example/MIB2-subtitles-pt-BR.vtt',
      kind: 'subtitles',
      label: 'Spanish',
      language: 'es',
      mimeType: 'application/x-subtitle-vtt',
    },
  ],
};

const loadParams: IPlayerSessionLoadParams = {
  startPosition: 0,
  autoPlay: true,
};

const sessionId: IPlayerSessionId = {id: 1};

try {
  await playerClientRef.current?.load(mediaInfo, loadParams, sessionId);
} catch (error) {
  console.error('Error while calling load: ', error);
  // Perform error handling.
}

pause()

pause: (sessionId?) => Promise<void>

Request the PlayerServer to pause playback.

Parameters

sessionId?

IPlayerSessionId

Optional. The session ID to target with the request. If not provided, the session to target is decided by the PlayerServer.

Returns

Promise<void>

A Promise that resolves when the request is successfully handled, or rejects with an error if the request fails.

Details

The media sesssion should update its IPlayerSessionStatus to reflect the new playback status.

Example

const sessionId: IPlayerSessionId = {id: 1};
try {
  await playerClientRef.current?.pause(sessionId);
} catch (error) {
  console.error('Error while calling pause: ', error);
  // Perform error handling.
}

play()

play: (sessionId?) => Promise<void>

Request the PlayerServer to start or resume playback.

Parameters

sessionId?

IPlayerSessionId

Optional. The session ID to target with the request. If not provided, the session to target is decided by the PlayerServer.

Returns

Promise<void>

A Promise that resolves when the request is successfully handled, or rejects with an error if the request fails.

Details

The media sesssion should update its IPlayerSessionStatus to reflect the new playback status. The Kepler player server may reset playback speed back to normal.

Example

const sessionId: IPlayerSessionId = {id: 1};
try {
  await playerClientRef.current?.play(sessionId);
} catch (error) {
  console.error('Error while calling play: ', error);
  // Perform error handling.
}

registerBufferedRangesListener()

registerBufferedRangesListener: (listener, sessionId?) => Promise<ISubscription>

Subscribes a listener to monitor changes in the buffered ranges.

Parameters

listener

IPlayerSessionBufferedRangesListener

The listener to add. See IPlayerSessionBufferedRangesListener.

sessionId?

IPlayerSessionId

Optional. The session ID to target with the request. If not provided, the session to target is decided by the PlayerServer.

Returns

Promise<ISubscription>

A Promise that resolves with an ISubscription object. This object can be used to unsubscribe the listener when it's no longer needed.

Example

const sessionId: IPlayerSessionId = {id: 1};
let subscription: ISubscription =
  await playerClientRef.current?.registerBufferedRangesListener(
    listener,
    sessionId,
  );

registerErrorListener()

registerErrorListener: (listener, sessionId?) => Promise<ISubscription>

Subscribes a listener to receive error from service component.

Parameters

listener

IPlayerSessionErrorListener

The listener to add. See IPlayerSessionErrorListener

sessionId?

IPlayerSessionId

Optional. The session ID to target with the request. If not provided, the session to target is decided by the PlayerServer.

Returns

Promise<ISubscription>

A Promise that resolves with an ISubscription object. This object can be used to unsubscribe the listener when it's no longer needed.

Example

const sessionId: IPlayerSessionId = {id: 1};
let subscription: ISubscription =
  await playerClientRef.current?.registerMessageListener(listener, sessionId);

registerMessageListener()

registerMessageListener: (listener, sessionId?) => Promise<ISubscription>

Subscribes a listener to receive message from service component.

Parameters

listener

IPlayerSessionMessageListener

The listener to add. See IPlayerSessionMessageListener

sessionId?

IPlayerSessionId

Optional. The session ID to target with the request. If not provided, the session to target is decided by the PlayerServer.

Returns

Promise<ISubscription>

A Promise that resolves with an ISubscription object. This object can be used to unsubscribe the listener when it's no longer needed.

Example

const sessionId: IPlayerSessionId = {id: 1};
let subscription: ISubscription =
  await playerClientRef.current?.registerMessageListener(listener, sessionId);

registerPositionListener()

registerPositionListener: (listener, interval, sessionId?) => Promise<ISubscription>

Subscribes a listener to monitor updates in the playback position. This position will be in seconds.

Parameters

listener

IPlayerSessionPositionListener

The listener to add. See IPlayerSessionPositionListener

interval

number

The interval (in seconds) at which to receive playback position updates. Must be non-negative value.

sessionId?

IPlayerSessionId

Optional. The session ID to target with the request. If not provided, the session to target is decided by the PlayerServer.

Returns

Promise<ISubscription>

A Promise that resolves with an ISubscription object. This object can be used to unsubscribe the listener when it's no longer needed.

Example

const sessionId: IPlayerSessionId = {id: 1};
let subscription: ISubscription =
  await playerClientRef.current?.registerPositionListener(
    listener,
    1.0,
    sessionId,
  );

registerStatusListener()

registerStatusListener: (listener, sessionId?) => Promise<ISubscription>

Subscribes a listener to monitor changes in the player session status.

Parameters

listener

IPlayerSessionStatusListener

The listener to add. See IPlayerSessionStatusListener

sessionId?

IPlayerSessionId

Optional. The session ID to target with the request. If not provided, the session to target is decided by the PlayerServer.

Returns

Promise<ISubscription>

A Promise that resolves with an ISubscription object. This object can be used to unsubscribe the listener when it's no longer needed.

Example

const sessionId: IPlayerSessionId = {id: 1};
let subscription: ISubscription =
  await playerClientRef.current?.registerStatusListener(listener, sessionId);

registerTrackListener()

registerTrackListener: (listener, sessionId?) => Promise<ISubscription>

Subscribes a listener to monitor changes in the track information.

Parameters

listener

IPlayerSessionTrackListener

The listener to add. See IPlayerSessionTrackListener

sessionId?

IPlayerSessionId

Optional. The session ID to target with the request. If not provided, the session to target is decided by the PlayerServer.

Returns

Promise<ISubscription>

A Promise that resolves with an ISubscription object. This object can be used to unsubscribe the listener when it's no longer needed.

Example

const sessionId: IPlayerSessionId = {id: 1};
let subscription: ISubscription =
  await playerClientRef.current?.registerTrackListener(listener, sessionId);

seek()

seek: (position, isRelative?, sessionId?) => Promise<void>

Request the PlayerServer to seek to a given playback position (in seconds).

Parameters

position

number

The playback position (in seconds) to seek to, either relative to the current playback position (isRelative = true); or relative to the start of the media where 0 represents the start of the media (isRelative = false).

isRelative?

boolean

If the position provided is relative to the current playback position (isRelative = true) or an absolute position in the media (isRelative = false). Default value is false.

sessionId?

IPlayerSessionId

Optional. The session ID to target with the request. If not provided, the session to target is decided by the PlayerServer.

Returns

Promise<void>

A Promise that resolves when the request is successfully handled, or rejects with an error if the request fails.

Details

The media sesssion should update its IPlayerSessionStatus to reflect the new playback position.

Examples

const sessionId: IPlayerSessionId = {id: 1};
try {
  await playerClientRef.current?.seek(30, true, sessionId);
} catch (error) {
  console.error('Error while calling seek: ', error);
  // Perform error handling.
}

const sessionId: IPlayerSessionId = {id: 1};
try {
  await playerClientRef.current?.seek(-5, false, sessionId);
} catch (error) {
  console.error('Error while calling seek: ', error);
  // Perform error handling.
}

sendMessage()

sendMessage: (message, sessionId?) => Promise<void>

Provides a way for interactive component to send custom message to service component. Any JSON type can be sent as a message (except undefined).

Parameters

message

any

Custom message to be sent. send JSON value (except undefined) as message.

sessionId?

IPlayerSessionId

Optional. The session ID of the session for which custom message needs to be handled. If not provided, treat as a request for data on all sessions.

Returns

Promise<void>

A Promise that resolves when the request is successfully handled, or rejects with an error if the request fails or message is undefined.

Example

// Create any object.
const customMessage = {
  video: {
    title: 'Video 1',
    myVideoId: 34,
  },
};
const sessionId: IPlayerSessionId = {id: 1};

try {
  await playerClientRef.current?.sendMessage(customMessage, sessionId);
} catch (error) {
  console.error('Error while calling sendMessage: ', error);
  // Perform error handling.
}

setActiveTrack()

setActiveTrack: (trackType, trackId, sessionId?) => Promise<void>

Request the PlayerServer to set the active track of media playback.

Parameters

trackType

ITrackType

The type of the track to set as active.

trackId

string

The track ID of the track to set as active.

sessionId?

IPlayerSessionId

Optional. The session ID to target with the request. If not provided, the session to target is decided by the PlayerServer.

Returns

Promise<void>

A Promise that resolves when the request is successfully handled, or rejects with an error if the request fails.

Details

The media sesssion should update its IPlayerSessionStatus to reflect the new playback status.

Example

const sessionId: IPlayerSessionId = {id: 1};
try {
  await playerClientRef.current?.setActiveTrack('AUDIO', 'JS_0', sessionId);
} catch (error) {
  console.error('Error while calling setActiveTrack: ', error);
  // Perform error handling.
}

setMediaControlFocus()

setMediaControlFocus: (componentInstance, mediaControlHandler?) => Promise<void>

Register PlayerClientMediaControlHandler instance

Available since version 2.1.0.

Parameters

componentInstance

IComponentInstance

The component instance for which the handler needs to be set.

mediaControlHandler?

PlayerClientMediaControlHandler

Object containing the event handlers.

Returns

Promise<void>

A Promise that resolves when the request is successfully handled, or rejects with an error if the request fails, or targeted version is less than 2.1.0

Example

// In the interactive component.
import {
  useComponentInstance,
  IComponentInstance,
} from '@amazon-devices/react-native-kepler';
import {PlayerClientMediaControlHandler} from '@amazon-devices/kepler-player-client';

const componentInstance: IComponentInstance = useComponentInstance();
class MyMediaControlsHandler extends PlayerClientMediaControlHandler {
  private playerClientRef: IPlayerClient | undefined;
  // Implement MyMediaControlsHandler.
}

let mediaControlsHandler: MyMediaControlsHandler = new MyMediaControlsHandler(
  playerClientRef.current as IPlayerClient,
);
try {
  await playerClientRef.current?.setMediaControlFocus(
    componentInstance,
    mediaControlsHandler,
  );
} catch (error) {
  console.error('Error while calling setMediaControlFocus: ', error);
  // Perform error handling.
}

setMute()

setMute: (isMuted, sessionId?) => Promise<void>

Request the PlayerServer to mute or unmute playback.

Parameters

isMuted

boolean

If true, the media should be muted

sessionId?

IPlayerSessionId

Optional. The session ID to target with the request. If not provided, the session to target is decided by the PlayerServer.

Returns

Promise<void>

A Promise that resolves when the request is successfully handled, or rejects with an error if the request fails.

Details

The media sesssion should update its IPlayerSessionStatus to reflect the new playback status.

Example

const sessionId: IPlayerSessionId = {id: 1};
try {
  await playerClientRef.current?.setMute(true, sessionId);
} catch (error) {
  console.error('Error while calling setMute: ', error);
  // Perform error handling.
}

setPlaybackRate()

setPlaybackRate: (playbackRate, sessionId?) => Promise<void>

Request the PlayerServer to set playback rate of media playback.

Parameters

playbackRate

number

The playback rate to set, like 0.25, 0.5, 2.0 etc If the input playback rate is not supported, promise will be rejected and registered IPlayerSessionErrorListener instance will receive IPlayerSessionError.

sessionId?

IPlayerSessionId

Optional. The session ID to target with the request. If not provided, the session to target is decided by the PlayerServer.

Returns

Promise<void>

A Promise that resolves when the request is successfully handled, or rejects with an error if the request fails.

Details

The media sesssion should update its IPlayerSessionStatus to reflect the new playback status.

Example

const sessionId: IPlayerSessionId = {id: 1};
try {
  await playerClientRef.current?.setPlaybackRate(1.5, sessionId);
} catch (error) {
  console.error('Error while calling setPlaybackRate: ', error);
  // Perform error handling.
}

setTextView()

setTextView: (viewHandle, sessionId?) => Promise<void>

Request the media session in PlayerServer to set the KeplerCaptionsView with the loaded content.

Parameters

viewHandle

IViewHandle

Surface handle of KeplerCaptionsView.

sessionId?

IPlayerSessionId

Optional. The session ID to target for setting the captions surface. If not specified, the PlayerServer decides how to handle the request.

Returns

Promise<void>

A Promise that resolves when the request is successfully handled, or rejects with an error if the request fails.

Details

setTextView should be called after the media content has been loaded by calling one of the load APIs.

Example

const captionsHandleRef = useRef<IViewHandle | null>(null);
const sessionId: IPlayerSessionId = {id: 1};

// Register below onCaptionViewCreated function in <KeplerCaptionsView> component.
const onCaptionViewCreated = (surfaceHandle: string): void => {
  captionsHandleRef.current = {handle: surfaceHandle};
  try {
    await playerClientRef.current?.setTextView(
      captionsHandleRef.current,
      sessionId,
    );
  } catch (error) {
    console.error('Error while calling clearVideoView: ', error);
    // Perform error handling.
  }
};

setVideoView()

setVideoView: (viewHandle, sessionId?) => Promise<void>

Request the media session in PlayerServer to set the KeplerVideoSurfaceView with the loaded content.

Parameters

viewHandle

IViewHandle

The identifier for the KeplerVideoSurfaceView.

sessionId?

IPlayerSessionId

Optional. The session ID to target for setting the video surface. If not specified, the PlayerServer decides how to handle the request.

Returns

Promise<void>

A Promise that resolves when the request is successfully handled, or rejects with an error if the request fails.

Details

setVideoView should be called after the media content has been loaded by calling one of the load APIs.

Example

const surfaceHandleRef = useRef<IViewHandle | null>(null);
const sessionId: IPlayerSessionId = {id: 1};

// Register below onSurfaceViewCreated function in <KeplerVideoSurfaceView> component.
const onSurfaceViewCreated = (surfaceHandle: string): void => {
  surfaceHandleRef.current = {handle: surfaceHandle};
  try {
    await playerClientRef.current?.setVideoView(
      surfaceHandleRef.current,
      sessionId,
    );
  } catch (error) {
    console.error('Error while calling setVideoView: ', error);
    // Perform error handling.
  }
};

setVolume()

setVolume: (volume, sessionId?) => Promise<void>

Request the PlayerServer to set volume of media playback.

Parameters

volume

number

The volume to set, in the range of 0.0 to 1.0.

sessionId?

IPlayerSessionId

Optional. The session ID to target with the request. If not provided, the session to target is decided by the PlayerServer.

Returns

Promise<void>

A Promise that resolves when the request is successfully handled, or rejects with an error if the request fails.

Details

The media sesssion should update its IPlayerSessionStatus to reflect the new playback status.

Example

const sessionId: IPlayerSessionId = {id: 1};
try {
  await playerClientRef.current?.setVolume(0.75, sessionId);
} catch (error) {
  console.error('Error while calling setVolume: ', error);
  // Perform error handling.
}

unload()

unload: (sessionId?) => Promise<void>

Request the media session in PlayerServer to unload media content. To unload media content synchronously, for instance, in case when app state changes to background, call unloadSync.

Parameters

sessionId?

IPlayerSessionId

Optional. The session ID to target for unloading content. If not specified, the PlayerServer decides how to handle the request.

Returns

Promise<void>

A Promise that resolves when the request is successfully handled, or rejects with an error if the request fails.

Example

const sessionId: IPlayerSessionId = {id: 1};

try {
  await playerClientRef.current?.unload(sessionId);
} catch (error) {
  console.error('Error while calling unload: ', error);
  // Perform error handling.
}

unloadSync()

unloadSync: (timeoutMsec, sessionId?) => IUnloadSyncStatus

Request the media session in PlayerServer to unload media content synchronously. Use this API to release media resources when app state changes to background.

Parameters

timeoutMsec

number

Maximum allowed time (in milliseconds) for unloadSync API to execute.

Note

Minimum value is 1000, and maximum value is 5000.

sessionId?

IPlayerSessionId

Optional. The session ID to target for unloading content. If not specified, the PlayerServer decides how to handle the request.

Returns

IUnloadSyncStatus

One of the enum values in @amazon-devices/kepler-player-server#IUnloadSyncStatus|PlayerServer IUnloadSyncStatus.

Since

2.2.0

Example

const sessionId: IPlayerSessionId = {id: 1};

if (isPresentOnOS('@amazon-devices/kepler-player-client', '2.2.0')) {
  try {
    let unloadResult: IUnloadSyncStatus | undefined =
      playerClientRef.current?.unloadSync(1000, sessionId);
    if (
      unloadResult === IUnloadSyncStatus.INVALID ||
      unloadResult === IUnloadSyncStatus.TIMEDOUT
    ) {
      console.error('unloadSync failed due to ', unloadResult);
    } else {
      console.log('unloadSync completed successfully.');
    }
  } catch (error) {
    console.error('Error while calling unloadSync: ', error);
    // Perform error handling.
  }
} else {
  console.error('unloadSync not supported in this OS.');
}

Last updated: Oct 02, 2025