IPlayerServer
Represent Kepler player server operations. This interface provides methods for managing Kepler player server handlers and updating Kepler player session status.
For runtime errors, apps are expected to reject the promise with Error object, and if
possible send the error code and message received from media player using IPlayerSessionError
Properties
addTrack()
addTrack: (
newTrack,sessionId?) =>Promise<void>
Notifies interested clients about Kepler player new track. {Audio,Video}Player must register to "addtrack" EventListener in AudioTrackList | VideoTrackList | TextTrackList, and then call this API.
Parameters
newTrack
Read-only details of new track added.
sessionId?
Optional. The session ID of the session whose new track has been added. If not provided, treat as a request for data on all sessions.
Returns
Promise<void>
Promise that resolves when the update is complete.
Details
Updating the server session new track is crucial for reflecting changes in media playback
status, currently selected media, and other related information.
Apps can register to "addtrack" EventListener on HtmlMediaElement.{audioTracks,videoTracks,textTracks}
attributes and then call IPlayerServer.addTrack if the event is emitted.
Example:
let media = useRef<VideoPlayer | AudioPlayer | null>(...);
let sessionId = useRef<IPlayerSessionId | undefined>(...);
const onAudioTrackAdded = (event: Event): void => {
if (event instanceof TrackEvent) {
let track = (event as TrackEvent).track;
if (track !== undefined) {
playerServerRef.current?.addTrack({
id: track.id,
type: "AUDIO",
kind: track.kind,
label: track.label,
language: track.language,
enabled: (track as AudioTrack).enabled
}, sessionId.current);
// Do other operations if needed.
} else {
console.error("Undefined audio track.");
}
}
}
const onVideoTrackAdded = (event: Event): void => {
if (event instanceof TrackEvent) {
let track = (event as TrackEvent).track;
if (track !== undefined) {
playerServerRef.current?.addTrack({
id: track.id,
type: "VIDEO",
kind: track.kind,
label: track.label,
language: track.language,
enabled: (track as VideoTrack).selected
}, sessionId.current);
// Do other operations if needed.
} else {
console.error("Undefined video track.");
}
}
}
const onTextTrackAdded = (event: Event): void => {
if (event instanceof TrackEvent) {
let track = (event as TrackEvent).track;
if (track !== undefined) {
playerServerRef.current?.addTrack({
id: track.id,
type: "TEXT",
kind: track.kind,
label: track.label,
language: track.language,
mode: (track as TextTrack).mode
}, sessionId.current);
// Do other operations if needed.
} else {
console.error("Undefined text track.");
}
}
}
media.current?.audioTracks.addEventListener("addtrack", onAudioTrackAdded);
media.current?.videoTracks.addEventListener("addtrack", onVideoTrackAdded);
media.current?.textTracks.addEventListener("addtrack", onTextTrackAdded);
removeTrack()
removeTrack: (
removedTrack,sessionId?) =>Promise<void>
Notifies interested clients about Kepler player existing track removed. {Audio,Video}Player must register to "removetrack" EventListener in AudioTrackList | VideoTrackList | TextTrackList, and then call this API.
Parameters
removedTrack
Readonly details of existing track removed.
sessionId?
Optional. The session ID of the session whose existing track has been removed. If not provided, treat as a request for data on all sessions.
Returns
Promise<void>
Promise that resolves when the update is complete.
Details
Updating the server session removed track is crucial for reflecting changes in media playback
status, currently selected media, and other related information.
Apps can register to "removetrack" EventListener on HtmlMediaElement.{audioTracks,videoTracks,textTracks}
attributes and then call IPlayerServer.removeTrack if the event is emitted.
Example:
let media = useRef<VideoPlayer | AudioPlayer | null>(...);
let sessionId = useRef<IPlayerSessionId | undefined>(...);
const onAudioTrackRemoved = (event: Event): void => {
if (event instanceof TrackEvent) {
let track = (event as TrackEvent).track;
if (track !== undefined) {
playerServerRef.current?.removeTrack({
id: track.id,
type: "AUDIO",
kind: track.kind,
label: track.label,
language: track.language,
enabled: (track as AudioTrack).enabled
}, sessionId.current);
// Do other operations if needed.
} else {
console.error("Undefined audio track.");
}
}
}
const onVideoTrackRemoved = (event: Event): void => {
if (event instanceof TrackEvent) {
let track = (event as TrackEvent).track;
if (track !== undefined) {
playerServerRef.current?.removeTrack({
id: track.id,
type: "VIDEO",
kind: track.kind,
label: track.label,
language: track.language,
enabled: (track as VideoTrack).selected
}, sessionId.current);
// Do other operations if needed.
} else {
console.error("Undefined video track.");
}
}
}
const onTextTrackRemoved = (event: Event): void => {
if (event instanceof TrackEvent) {
let track = (event as TrackEvent).track;
if (track !== undefined) {
playerServerRef.current?.removeTrack({
id: track.id,
type: "TEXT",
kind: track.kind,
label: track.label,
language: track.language,
mode: (track as TextTrack).mode
}, sessionId.current);
// Do other operations if needed.
} else {
console.error("Undefined text track.");
}
}
}
media.current?.audioTracks.addEventListener("removetrack", onAudioTrackRemoved);
media.current?.videoTracks.addEventListener("removetrack", onVideoTrackRemoved);
media.current?.textTracks.addEventListener("removetrack", onTextTrackRemoved);
sendError()
sendError: (
error,sessionId?) =>Promise<void>
Provides the way to send the error from service component to interactive component.
Apps can register to "error" EventListener on HtmlMediaElement instance
and then call IPlayerServer.addTrack if the event is emitted.
Parameters
error
Error object to be sent.
sessionId?
Optional. The session ID of the session for which custom message needs to be handled.
Returns
Promise<void>
Promise that resolves when the error is sent.
Example
let media = useRef<VideoPlayer | AudioPlayer | null>(...);
let sessionId = useRef<IPlayerSessionId | undefined>(...);
const onError = (error: MediaError) => {
let errorObj: IPlayerSessionError = {
code: error.code,
message: error.message
}
try {
playerServerRef.current?.sendError(errorObj, sessionId);
} catch (error) {
console.error('Error while calling sendError: ', error);
}
};
media.current?.addEventListener("error", onError);
sendMessage()
sendMessage: (
message,sessionId?) =>Promise<void>
Provides a way to send custom message to interactive 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?
Optional. The session ID of the session for which custom message needs to be handled.
Returns
Promise<void>
Promise that resolves when the message is sent or rejects with an error
if the request fails, or message is undefined.
Details
This is particularly useful in providing custom messages which can be used to by client to update UI.
Example
// Create any object.
const customMessage = {
video: {
title: "Video 1",
myVideoId: 34
}
};
let sessionId = useRef<IPlayerSessionId | undefined>(...);
try {
playerServerRef.current?.sendMessage(customMessage, sessionId);
} catch (error) {
console.error('Error while calling sendMessage: ', error);
}
setHandler()
setHandler: (
handler,componentId) =>void
Assigns a handler to process requests for Kepler player actions associated with the given component ID.
Parameters
handler
An instance of the IPlayerServerHandler interface to invoke
when Kepler player requests arrive.
componentId
string
An id of the service component interface representing the component for which the handler is being set.
This MUST match the service ID declared in the application manifest.
Returns
void
Details
Assigning a handler is essential for processing Kepler player requests and implementing custom Kepler player logic. This call allows one handler per component. The active handler is the one set by the last invocation to setHandler.
Example
import {PackageInfo, PackageManager} from '@amazon-devices/package-manager-lib';
const parseClientPackageManifest = async (): Promise<string> => {
try {
const selfPackageInfo: PackageInfo =
await PackageManager.getSelfPackageInfo();
for (const component of selfPackageInfo.components) {
if (component.type === 'service') {
return component.id;
}
}
return '';
} catch (error) {
console.warn(
`Interactive: Unable to retrieve info from Package manager, ${error.message}`,
);
return '';
}
};
let serviceComponentId: string | undefined =
await this.parseClientPackageManifest();
playerServerRef.current?.setHandler(handler, serviceComponentId);
updateBufferedRanges()
updateBufferedRanges: (
bufferedRanges,sessionId?) =>Promise<void>
Notifies interested clients about Kepler player buffered ranges.
Parameters
bufferedRanges
Updated buffered ranges for player session.
sessionId?
session id for which the buffered ranges are being updated.
Returns
Promise<void>
Promise that resolves when the update is complete.
Details
Updating the server session playback buffered ranges is crucial for reflecting changes in media playback status, currently selected media, and other related information.
let sessionId1: IPlayerSessionId = { id: 1 };
let mediaPlayer1: HtmlMediaElement | VideoPlayer | AudioPlayer; // say associated with sessionId 1.
let sessionId2: IPlayerSessionId = { id: 2 };
let mediaPlayer2: HtmlMediaElement | VideoPlayer | AudioPlayer; // say associated with sessionId 2.
private getBufferedRanges(mediaPlayer: HtmlMediaElement | VideoPlayer | AudioPlayer): Array<ITimeRange> {
const result: Array<ITimeRange> = [];
const bufferedTimeRanges = mediaPlayer.buffered;
for (let i = 0; i < bufferedTimeRanges.length; ++i) {
result.push({
start: bufferedTimeRanges.start(i),
end: bufferedTimeRanges.end(i)
});
}
return result;
}
playerServerRef.current?.updateBufferedRanges(getBufferedRanges(mediaPlayer1), sessionId1);
playerServerRef.current?.updateBufferedRanges(getBufferedRanges(mediaPlayer2), sessionId2);
updateStatus()
updateStatus: (
status) =>Promise<void>
Notifies interested clients about Kepler player session status updates.
Parameters
status
Array of IPlayerSessionStatus containing updated session status.
Returns
Promise<void>
Promise that resolves when the update is complete.
Details
Updating the kepler player server session status is crucial for reflecting changes in media playback
status, currently selected media, and other related information.
For instance, apps will register media related EventListener on AudioPlayer or VideoPlayer
(https://html.spec.whatwg.org/#event-handlers-on-elements,-document-objects,-and-window-objects)
and then update the parameters of IPlayerSessionStatus accordingly and call
updateStatus.
When applicable, a Kepler player server is expected to issue session status updates upon acting on a
Kepler player request received through the installed IPlayerServerHandler instance.
Example
let mediaPlayer1: HtmlMediaElement | VideoPlayer | AudioPlayer; // say associated with sessionId 1.
let mediaPlayer2: HtmlMediaElement | VideoPlayer | AudioPlayer; // say associated with sessionId 2.
let sampleData_1: IPlayerSessionStatus = {
sessionID: {id: 1},
playbackSpeed: 1.0,
playbackStatus: IPlaybackStatus.PAUSED,
isMuted: true,
volume: 0.0,
seekable: false,
duration: mediaPlayer1.duration || 0,
};
let sampleData_2: IPlayerSessionStatus = {
sessionID: {id: 2},
playbackSpeed: 2.0,
playbackStatus: IPlaybackStatus.PLAYING,
isMuted: false,
volume: 0.75,
seekable: true,
duration: mediaPlayer2.duration || 0,
};
playerServerRef.current?.updateStatus([sampleData_1, sampleData_2]);
Last updated: Sep 30, 2025
