IPlayerClient - Amazon Vega Docs

An interface that represents a PlayerClient.

Properties

load

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

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

Parameters

mediaInfo

IPlayerSessionMediaInfo

loadParams?

any

sessionId?

any

Returns

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

Examples

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

unload

unload: (sessionId?: IPlayerSessionId) => 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?

any

Returns

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

Examples

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: number, sessionId?: IPlayerSessionId) => 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. 2.2.0

Parameters

timeoutMsec

number

sessionId?

any

Returns

IUnloadSyncStatus One of the enum values in PlayerServer IUnloadSyncStatus.

Examples

const sessionId: IPlayerSessionId = { id: 1 };

if (isPresentOnOS('@amzn/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.');
}

setVideoView

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

Request the media session in PlayerServer to set the KeplerVideoSurfaceView with the loaded content. setVideoView should be called after the media content has been loaded by calling one of the load APIs.

Parameters

viewHandle

IViewHandle

sessionId?

any

Returns

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

Examples

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

clearVideoView

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

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

Parameters

sessionId?

any

Returns

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

Examples

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

setTextView

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

Request the media session in PlayerServer to set the KeplerCaptionsView with the loaded content. setTextView should be called after the media content has been loaded by calling one of the load APIs.

Parameters

viewHandle

IViewHandle

sessionId?

any

Returns

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

Examples

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

clearTextView

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

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

Parameters

sessionId?

any

Returns

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

Examples

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

play

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

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

Parameters

sessionId?

any

Returns

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

Examples

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

pause

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

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

Parameters

sessionId?

any

Returns

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

Examples

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

seek

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

Request the PlayerServer to seek to a given playback position (in seconds). The media sesssion should update its IPlayerSessionStatus to reflect the new playback position.

Parameters

position

number

isRelative?

boolean

sessionId?

any

Returns

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

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

setMute

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

Request the PlayerServer to mute or unmute playback. The media sesssion should update its IPlayerSessionStatus to reflect the new playback status.

Parameters

isMuted

boolean

sessionId?

any

Returns

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

Examples

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: number, sessionId?: IPlayerSessionId) => Promise<void>

Request the PlayerServer to set playback rate of media playback. The media sesssion should update its IPlayerSessionStatus to reflect the new playback status.

Parameters

playbackRate

number

sessionId?

any

Returns

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

Examples

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

setVolume

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

Request the PlayerServer to set volume of media playback. The media sesssion should update its IPlayerSessionStatus to reflect the new playback status.

Parameters

volume

number

sessionId?

any

Returns

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

Examples

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

setActiveTrack

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

Request the PlayerServer to set the active track of media playback. The media sesssion should update its IPlayerSessionStatus to reflect the new playback status.

Parameters

trackType

ITrackType

trackId

string

sessionId?

any

Returns

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

Examples

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: IComponentInstance, mediaControlHandler?: PlayerClientMediaControlHandler) => Promise<void>

Parameters

componentInstance

IComponentInstance

mediaControlHandler?

PlayerClientMediaControlHandler

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

Examples

// In the interactive component.
import {useComponentInstance, IComponentInstance} from '@amzn/react-native-kepler';
import { PlayerClientMediaControlHandler } from '@amzn/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.
}

getCurrentPosition

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

Request the PlayerServer to get the current playback position of media playback (in seconds). The media sesssion should update its IPlayerSessionStatus to reflect the new playback status.

Parameters

sessionId?

any

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.

Examples

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

registerBufferedRangesListener

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

Subscribes a listener to monitor changes in the buffered ranges.

Parameters

listener

IPlayerSessionBufferedRangesListener

sessionId?

any

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.

Examples

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

registerStatusListener

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

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

Parameters

listener

IPlayerSessionStatusListener

sessionId?

any

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.

Examples

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

registerPositionListener

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

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

Parameters

listener

IPlayerSessionPositionListener

interval

number

sessionId?

any

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.

Examples

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

registerTrackListener

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

Subscribes a listener to monitor changes in the track information.

Parameters

listener

IPlayerSessionTrackListener

sessionId?

any

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.

Examples

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

registerMessageListener

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

Subscribes a listener to receive message from service component.

Parameters

listener

IPlayerSessionMessageListener

sessionId?

any

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.

Examples

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

registerErrorListener

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

Subscribes a listener to receive error from service component.

Parameters

listener

IPlayerSessionErrorListener

sessionId?

any

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.

Examples

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

sendMessage

sendMessage: (message: any, sessionId?: IPlayerSessionId) => 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

sessionId?

any

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.

Examples

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

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.

Examples

playerClientRef.current?.destroy();

​Properties

​load

​Parameters

mediaInfo

loadParams?

sessionId?

​Returns

​Examples

​unload

​Parameters

sessionId?

​Returns

​Examples

​unloadSync

​Parameters

timeoutMsec

sessionId?

​Returns

​Examples

​setVideoView

​Parameters

viewHandle

sessionId?

​Returns

​Examples

​clearVideoView

​Parameters

sessionId?

​Returns

​Examples

​setTextView

​Parameters

viewHandle

sessionId?

​Returns

​Examples

​clearTextView

​Parameters

sessionId?

​Returns

​Examples

​play

​Parameters

sessionId?

​Returns

​Examples

​pause

​Parameters

sessionId?

​Returns

​Examples

​seek

​Parameters

position

isRelative?

sessionId?

​Returns

​Examples

​setMute

​Parameters

isMuted

sessionId?

​Returns

​Examples

​setPlaybackRate

​Parameters

playbackRate

sessionId?

​Returns

​Examples

​setVolume

​Parameters

volume

sessionId?

​Returns

​Examples

​setActiveTrack

​Parameters

trackType

trackId

Properties

load

Parameters

Returns

Examples

unload

Parameters

Returns

Examples

unloadSync

Parameters

Returns

Examples

setVideoView

Parameters

Returns

Examples

clearVideoView

Parameters

Returns

Examples

setTextView

Parameters

Returns

Examples

clearTextView

Parameters

Returns

Examples

play

Parameters

Returns

Examples

pause

Parameters

Returns

Examples

seek

Parameters

Returns

Examples

setMute

Parameters

Returns

Examples

setPlaybackRate

Parameters

Returns

Examples

setVolume

Parameters

Returns

Examples

setActiveTrack

Parameters

Returns

Examples

setMediaControlFocus

Parameters

Returns

Examples

getCurrentPosition

Parameters

Returns

Examples

registerBufferedRangesListener

Parameters

Returns

Examples

registerStatusListener

Parameters

Returns

Examples

registerPositionListener

Parameters

Returns

Examples

registerTrackListener

Parameters

Returns