IPlayerClient - Amazon Vega Docs

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

​Properties

​clearTextView()

​Parameters

sessionId?

​Returns

​Example

​clearVideoView()

​Parameters

sessionId?

​Returns

​Example

​destroy()

​Returns

​Example

​getCurrentPosition()

​Parameters

sessionId?

​Returns

​Details

​Example

​load()

​Parameters

mediaInfo

loadParams?

sessionId?

​Returns

​Example

​pause()

​Parameters

sessionId?

​Returns

​Details

​Example

​play()

​Parameters

sessionId?

​Returns

​Details

​Example

​registerBufferedRangesListener()

​Parameters

listener

sessionId?

​Returns

​Example

​registerErrorListener()

​Parameters

listener

sessionId?

​Returns

​Example

​registerMessageListener()

​Parameters

listener

sessionId?

​Returns

​Example

​registerPositionListener()

​Parameters

listener

interval

sessionId?

​Returns

​Example

​registerStatusListener()

​Parameters

listener

sessionId?

​Returns

​Example

​registerTrackListener()

​Parameters

listener

sessionId?

​Returns

​Example

​seek()

​Parameters

position

isRelative?

Properties

clearTextView()

Parameters

Returns

Example

clearVideoView()

Parameters

Returns

Example

destroy()

Returns

Example

getCurrentPosition()

Parameters

Returns

Details

Example

load()

Parameters

Returns

Example

pause()

Parameters

Returns

Details

Example

play()

Parameters

Returns

Details

Example

registerBufferedRangesListener()

Parameters

Returns

Example

registerErrorListener()

Parameters

Returns

Example

registerMessageListener()

Parameters

Returns

Example

registerPositionListener()

Parameters

Returns

Example

registerStatusListener()

Parameters

Returns

Example

registerTrackListener()

Parameters

Returns

Example

seek()

Parameters

Returns

Details

Examples

sendMessage()

Parameters

Returns

Example

setActiveTrack()

Parameters

Returns

Details

Example

setMediaControlFocus()

Parameters

Returns

Example

setMute()

Parameters

Returns

Details

Example

setPlaybackRate()

Parameters