IPlayerServer
表示Kepler播放器服务器操作。该接口提供用于管理Kepler播放器服务器处理程序以及更新Kepler播放器会话状态的方法。
对于运行时错误，此类应用应使用Error对象拒绝该Promise。如有可能，应使用IPlayerSessionError发送从媒体播放器收到的错误代码和消息
属性
setHandler
setHandler:
(handler:IPlayerServerHandler, componentId: string) => void
为处理与给定组件ID关联的Kepler播放器操作请求，分配处理程序。
分配处理程序对于处理Kepler播放器请求和实现自定义Kepler播放器逻辑至关重要。此调用允许每个组件有一个处理程序。活动处理程序指上次调用setHandler时所设置的处理程序。
updateBufferedRanges
updateBufferedRanges:
(bufferedRanges: Array<ITimeRange>, sessionId?:IPlayerSessionId) => Promise<void>
通知相关客户端有关Kepler播放器缓冲范围的信息。
更新服务器会话的播放缓冲范围对于反映媒体播放状态的变化、当前选定媒体及其他相关信息至关重要。
let sessionId1: IPlayerSessionId = { id: 1 };
let mediaPlayer1: HtmlMediaElement | VideoPlayer | AudioPlayer; // 与sessionId 1相关联的说明。
let sessionId2: IPlayerSessionId = { id: 2 };
let mediaPlayer2: HtmlMediaElement | VideoPlayer | AudioPlayer; // 与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>
通知相关客户端有关Kepler播放器会话状态更新的信息。
更新Kepler播放器服务器会话状态对于反映媒体播放状态的变化、当前选定媒体及其他相关信息至关重要。例如，应用将在AudioPlayer或VideoPlayer(https://html.spec.whatwg.org/#event-handlers-on-elements,-document-objects,-and-window-objects) 上注册媒体相关EventListener，然后更新对应的IPlayerSessionStatus参数并调用updateStatus。在适用情况下，Kepler播放器服务器在处理通过已安装IPlayerServerHandler实例接收到的Kepler播放器请求时，应发布会话状态更新。
addTrack
addTrack:
(newTrack:ITrackInfo, sessionId?:IPlayerSessionId) => Promise<void>
通知相关客户端有关Kepler播放器新轨道的信息。Audio,VideoPlayer必须先在AudioTrackList | VideoTrackList | TextTrackList中注册为 "addtrack" EventListener，然后才能调用此API。
更新服务器会话的新轨道对于反映媒体播放状态的变化、当前选定媒体及其他相关信息至关重要。应用可在HtmlMediaElement.audioTracks,videoTracks,textTracks属性上注册为 "addtrack" EventListener，然后调用IPlayerServer.addTrack（如果触发该事件）。
示例：
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);
// 必要时执行其他操作。
} else {
console.error("未定义的音轨。");
}
}
}
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);
// 必要时执行其他操作。
} else {
console.error("未定义的视频轨道。");
}
}
}
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);
// 必要时执行其他操作。
} else {
console.error("未定义的文本轨道。");
}
}
}
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>
通知相关客户端有关Kepler播放器的现有轨道被移除的信息。Audio,VideoPlayer必须先在AudioTrackList | VideoTrackList | TextTrackList中注册为 "removetrack" EventListener，然后才能调用此API。
更新服务器会话的已移除轨道对于反映媒体播放状态的变化、当前选定媒体及其他相关信息至关重要。应用可在HtmlMediaElement.audioTracks,videoTracks,textTracks属性上注册为 "removetrack" EventListener，然后调用IPlayerServer.removeTrack（如果触发该事件）。
示例：
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);
// 必要时执行其他操作。
} else {
console.error("未定义的音轨。");
}
}
}
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);
// 必要时执行其他操作。
} else {
console.error("未定义的视频轨道。");
}
}
}
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);
// 必要时执行其他操作。
} else {
console.error("未定义的文本轨道。");
}
}
}
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>
提供向交互组件发送自定义消息的方式。所有JSON类型都能作为消息发送（undefined除外）。
这在提供自定义消息方面尤为有用，客户端可利用这些消息更新用户界面。
sendError
sendError:
(error:IPlayerSessionError, sessionId?:IPlayerSessionId) => Promise<void>
提供将错误从服务组件发送到交互组件的途径。
应用可在HtmlMediaElement实例上注册为 "error" EventListener，然后调用IPlayerServer.addTrack（如果触发该事件）。
Last updated: 2026年7月22日
