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
setHandler
setHandler:
(handler:IPlayerServerHandler, componentId: string) => void
Assigns a handler to process requests for Kepler player actions associated with the given component ID.
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.
updateBufferedRanges
updateBufferedRanges:
(bufferedRanges: Array<ITimeRange>, sessionId?:IPlayerSessionId) => Promise<void>
Notifies interested clients about Kepler player buffered ranges.
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: Array<IPlayerSessionStatus>) => Promise<void>
Notifies interested clients about Kepler player session status updates.
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.
addTrack
addTrack:
(newTrack:ITrackInfo, sessionId?:IPlayerSessionId) => Promise<void>
Notifies interested clients about Kepler player new track. Audio,VideoPlayer must register to "addtrack" EventListener in AudioTrackList | VideoTrackList | TextTrackList, and then call this API.
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:ITrackInfo, sessionId?:IPlayerSessionId) => Promise<void>
Notifies interested clients about Kepler player existing track removed. Audio,VideoPlayer must register to "removetrack" EventListener in AudioTrackList | VideoTrackList | TextTrackList, and then call this API.
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);
sendMessage
sendMessage:
(message: any, sessionId?:IPlayerSessionId) => Promise<void>
Provides a way to send custom message to interactive component.
Any JSON type can be sent as a message (except undefined).
This is particularly useful in providing custom messages which can be used to by client to update UI.
sendError
sendError:
(error:IPlayerSessionError, sessionId?:IPlayerSessionId) => 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.
Last updated: Jul 22, 2026
