PlayerClient

The implementation of IKeplerPlayer.

Implements

• IPlayerClient

Constructors

new PlayerClient()

new PlayerClient(serviceComponentId): PlayerClient

Parameters

serviceComponentId

string

Returns

PlayerClient

Methods

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

Implementation of

IPlayerClient.clearTextView

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

Implementation of

IPlayerClient.clearVideoView

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();

Implementation of

IPlayerClient.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.
}

Implementation of

IPlayerClient.getCurrentPosition

load()

load(_urlInfo, _loadParams?, _sessionId?): Promise<void>

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

Parameters

_urlInfo

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

Implementation of

IPlayerClient.load

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

Implementation of

IPlayerClient.pause

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

Implementation of

IPlayerClient.play

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,
  );

Implementation of

IPlayerClient.registerBufferedRangesListener

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

Implementation of

IPlayerClient.registerErrorListener

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

Implementation of

IPlayerClient.registerMessageListener

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,
  );

Implementation of

IPlayerClient.registerPositionListener

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

Implementation of

IPlayerClient.registerStatusListener

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

Implementation of

IPlayerClient.registerTrackListener

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

Implementation of

IPlayerClient.seek

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

Implementation of

IPlayerClient.sendMessage

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

Implementation of

IPlayerClient.setActiveTrack

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

Implementation of

IPlayerClient.setMediaControlFocus

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

Implementation of

IPlayerClient.setMute

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

Implementation of

IPlayerClient.setPlaybackRate

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

Implementation of

IPlayerClient.setTextView

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

Implementation of

IPlayerClient.setVideoView

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

Implementation of

IPlayerClient.setVolume

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

Implementation of

IPlayerClient.unload

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.');
}

Implementation of

IPlayerClient.unloadSync

Last updated: Sep 30, 2025