Amazon Developer

Console

as

Settings
Sign out
Notifications
Alexa
亚马逊应用商店
AWS
文档
Support
Contact Us
My Cases

Console

as

新手入门
设计和开发
应用发布
参考
支持

IPlayerServer

IPlayerServer

表示Kepler播放器服务器操作。该接口提供用于管理Kepler播放器服务器处理程序以及更新Kepler播放器会话状态的方法。

对于运行时错误，此类应用应使用Error对象拒绝该Promise。如有可能，应使用IPlayerSessionError发送从媒体播放器收到的错误代码和消息

属性

addTrack()

addTrack: (newTrack, sessionId?) => Promise<void>

通知相关客户端有关Kepler播放器新轨道的信息。{Audio,Video}Player必须先在AudioTrackList | VideoTrackList | TextTrackList中注册为"addtrack" EventListener，然后才能调用此API。

参数

newTrack

ITrackInfo

新轨道的只读详情已添加。

sessionId?

IPlayerSessionId

可选已添加新轨道会话ID。若未提供，则视为请求获取所有会话的数据。

返回值

Promise<void>

在更新完成时进行解析的Promise。

详情

更新服务器会话的新轨道对于反映媒体播放状态的变化、当前选定媒体及其他相关信息至关重要。应用可在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, sessionId?) => Promise<void>

通知相关客户端有关Kepler播放器已移除的现有轨道的信息。{Audio,Video}Player必须先在AudioTrackList | VideoTrackList | TextTrackList中注册为"removetrack" EventListener，然后才能调用此API。

参数

removedTrack

ITrackInfo

已删除的现有轨道的详细信息，只读。

sessionId?

IPlayerSessionId

可选已删除现有轨道的会话ID。若未提供，则视为请求获取所有会话的数据。

返回值

Promise<void>

在更新完成时进行解析的Promise。

详情

更新服务器会话的已移除轨道对于反映媒体播放状态的变化、当前选定媒体及其他相关信息至关重要。应用可在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);

sendError()

sendError: (error, sessionId?) => Promise<void>

提供将错误从服务组件发送到交互组件的途径。

应用可在HtmlMediaElement实例上注册为"error" EventListener，然后调用IPlayerServer.addTrack（如果触发该事件）。

参数

error

IPlayerSessionError

要发送的错误对象。

sessionId?

IPlayerSessionId

可选需要处理自定义消息的会话的会话ID。

返回值

Promise<void>

在错误发生时进行解析的Promise。

示例

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('调用sendError时发生错误: ', error);
  }
};

media.current?.addEventListener("error", onError);

sendMessage()

sendMessage: (message, sessionId?) => Promise<void>

提供向交互组件发送自定义消息的方式。所有JSON类型都能作为消息发送（undefined除外）。

参数

message

任何

要发送的自定义消息。将JSON值（undefined除外）作为消息发送。

sessionId?

IPlayerSessionId

可选需要处理自定义消息的会话的会话ID。

返回值

Promise<void>

这是一个Promise，会在消息发送时正常完成；在请求失败或未定义message时，则会返回一个错误并拒绝执行。

详情

这在提供自定义消息方面尤为有用，客户端可利用这些消息更新用户界面。

示例

// 创建任意对象。
const customMessage = {
  video: {
    title: "Video 1",
    myVideoId: 34
  }
};
let sessionId = useRef<IPlayerSessionId | undefined>(...);

try {
  playerServerRef.current?.sendMessage(customMessage, sessionId);
} catch (error) {
  console.error('调用sendMessage时发生错误: ', error);
}

setHandler()

setHandler: (handler, componentId) => void

为处理与给定组件ID关联的Kepler播放器操作请求，分配处理程序。

参数

handler

IPlayerServerHandler

当Kepler播放器请求到达时，要调用的IPlayerServerHandler接口实例。

componentId

string

service component接口ID，表示正在为其设置处理程序的组件。这必须与应用程序清单中声明的服务ID相匹配。

返回值

void

详情

分配处理程序对于处理Kepler播放器请求和实现自定义Kepler播放器逻辑至关重要。此调用允许每个组件有一个处理程序。活动处理程序指上次调用setHandler时所设置的处理程序。

示例

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(
      `交互: 无法从程序包管理器中检索信息，${error.message}`,
    );
    return '';
  }
};

let serviceComponentId: string | undefined =
  await this.parseClientPackageManifest();
playerServerRef.current?.setHandler(handler, serviceComponentId);

updateBufferedRanges()

updateBufferedRanges: (bufferedRanges, sessionId?) => Promise<void>

通知相关客户端有关Kepler播放器缓冲范围的信息。

参数

bufferedRanges

ITimeRange[]

更新了玩家会话的缓冲范围。

sessionId?

IPlayerSessionId

正在更新的缓冲范围的会话ID。

返回值

Promise<void>

在更新完成时进行解析的Promise。

详情

更新服务器会话的播放缓冲范围对于反映媒体播放状态的变化、当前选定媒体及其他相关信息至关重要。

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) => Promise<void>

通知相关客户端有关Kepler播放器会话状态更新的信息。

参数

status

IPlayerSessionStatus[]

包含更新后会话状态的IPlayerSessionStatus数组。

返回值

Promise<void>

在更新完成时进行解析的Promise。

详情

更新Kepler播放器服务器会话状态对于反映媒体播放状态的变化、当前选定媒体及其他相关信息至关重要。例如，应用将在AudioPlayer或VideoPlayer(https://html.spec.whatwg.org/#event-handlers-on-elements,-document-objects,-and-window-objects) 上注册媒体相关EventListener，然后更新对应的IPlayerSessionStatus参数并调用updateStatus。在适用情况下，Kepler播放器服务器在处理通过已安装IPlayerServerHandler实例接收到的Kepler播放器请求时，应发布会话状态更新。

示例

let mediaPlayer1: HtmlMediaElement | VideoPlayer | AudioPlayer; // 与sessionId 1相关联的说明。
let mediaPlayer2: HtmlMediaElement | VideoPlayer | AudioPlayer; // 与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: 2025年10月2日

关注我们:
amazon_developer_logo

© 2010-2025 年，亚马逊公司或其附属公司. 保留所有权利。

协议

开发人员博客

联系我们