Amazon Developer

Console

as

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

Console

as

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

IPlayerClient

IPlayerClient

一个接口，用于代表一个PlayerClient。

属性

clearTextView()

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

请求PlayerServer中的媒体会话，以清除渲染字幕内容的KeplerCaptionsView。

参数

sessionId?

IPlayerSessionId

可选用于清除字幕界面的目标会话ID。如果未指定，则由PlayerServer决定如何处理请求。

返回值

Promise<void>

这是一个Promise，会在成功处理请求时正常完成；在请求失败时，则会返回一个错误并拒绝执行。

示例

const sessionId: IPlayerSessionId = {id: 1};
try {
  await playerClientRef.current?.clearTextView(sessionId);
} catch (error) {
  console.error('调用clearTextView时出错：', error);
  // 执行错误处理。
}

clearVideoView()

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

请求PlayerServer中的媒体会话，以清除渲染视频内容的KeplerVideoSurfaceView。

参数

sessionId?

IPlayerSessionId

可选用于清除视频界面的目标会话ID。如果未指定，则由PlayerServer决定如何处理请求。

返回值

Promise<void>

这是一个Promise，会在成功处理请求时正常完成；在请求失败时，则会返回一个错误并拒绝执行。

示例

const sessionId: IPlayerSessionId = {id: 1};
try {
  await playerClientRef.current?.clearVideoView(sessionId);
} catch (error) {
  console.error('调用clearVideoView时出错：', error);
  // 执行错误处理。
}

destroy()

destroy: () => void

销毁Kepler播放器客户端实例并停止Kepler播放器服务。当交互式组件销毁时，客户端应该调用此API来清理媒体资源。

返回值

void

示例

playerClientRef.current?.destroy();

getCurrentPosition()

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

向PlayerServer发出请求以获取媒体播放的当前播放位置（以秒为单位）。

参数

sessionId?

IPlayerSessionId

可选请求的目标会话ID。若未提供，则目标会话由PlayerServer决定。

返回值

Promise<number>

这是一个Promise，会在成功处理请求时正常完成；在请求失败时，则会返回一个错误并拒绝执行；它返回一个数字，表示当前与sessionId对应的播放位置（以秒为单位）。

详情

媒体会话应更新其IPlayerSessionStatus以反映新播放状态。

示例

const sessionId: IPlayerSessionId = {id: 1};
try {
  let position = await playerClientRef.current?.getCurrentPosition(sessionId);
} catch (error) {
  console.error('调用getCurrentPosition时出错：', error);
  // 执行错误处理。
}

load()

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

向PlayerServer发送请求，以使用给定URL加载内容。

参数

mediaInfo

IPlayerSessionMediaInfo

这是一个对象，用于描述加载媒体内容所必需的URL和HTTP标头。

loadParams?

IPlayerSessionLoadParams

可选通过URL加载内容所需的参数。

sessionId?

IPlayerSessionId

可选加载内容的目标会话ID。如果未指定，PlayerServer会创建一个新的媒体会话。

返回值

Promise<void>

这是一个Promise，会在成功处理请求时正常完成；在请求失败时，则会返回一个错误并拒绝执行。

示例

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);
  // 执行错误处理。
}

pause()

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

向PlayerServer发送请求以暂停播放。

参数

sessionId?

IPlayerSessionId

可选请求的目标会话ID。若未提供，则目标会话由PlayerServer决定。

返回值

Promise<void>

这是一个Promise，会在成功处理请求时正常完成；在请求失败时，则会返回一个错误并拒绝执行。

详情

媒体会话应更新其IPlayerSessionStatus以反映新播放状态。

示例

const sessionId: IPlayerSessionId = {id: 1};
try {
  await playerClientRef.current?.pause(sessionId);
} catch (error) {
  console.error('调用暂停时出错：', error);
  // 执行错误处理。
}

play()

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

向PlayerServer发送请求以开始或恢复播放。

参数

sessionId?

IPlayerSessionId

可选请求的目标会话ID。若未提供，则目标会话由PlayerServer决定。

返回值

Promise<void>

这是一个Promise，会在成功处理请求时正常完成；在请求失败时，则会返回一个错误并拒绝执行。

详情

媒体会话应更新其IPlayerSessionStatus以反映新播放状态。Kepler播放器服务器可能会将播放速度重置为正常速度。

示例

const sessionId: IPlayerSessionId = {id: 1};
try {
  await playerClientRef.current?.play(sessionId);
} catch (error) {
  console.error('调用播放时出错：', error);
  // 执行错误处理。
}

registerBufferedRangesListener()

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

订阅一个侦听器，以监视缓冲范围的变化。

参数

listener

IPlayerSessionBufferedRangesListener

要添加的侦听器。请参阅IPlayerSessionBufferedRangesListener。

sessionId?

IPlayerSessionId

可选请求的目标会话ID。若未提供，则目标会话由PlayerServer决定。

返回值

Promise<ISubscription>

这是一个Promise，当成功完成时，会返回一个ISubscription对象。当不再需要侦听器时，此对象可用于取消订阅侦听器。

示例

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

registerErrorListener()

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

订阅侦听器以接收来自服务组件的错误。

参数

listener

IPlayerSessionErrorListener

要添加的侦听器。参阅IPlayerSessionErrorListener

sessionId?

IPlayerSessionId

可选请求的目标会话ID。若未提供，则目标会话由PlayerServer决定。

返回值

Promise<ISubscription>

这是一个Promise，当成功完成时，会返回一个ISubscription对象。当不再需要侦听器时，此对象可用于取消订阅侦听器。

示例

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

registerMessageListener()

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

订阅侦听器以接收来自服务组件的消息。

参数

listener

IPlayerSessionMessageListener

要添加的侦听器。请参阅IPlayerSessionMessageListener

sessionId?

IPlayerSessionId

可选请求的目标会话ID。若未提供，则目标会话由PlayerServer决定。

返回值

Promise<ISubscription>

这是一个Promise，当成功完成时，会返回一个ISubscription对象。当不再需要侦听器时，此对象可用于取消订阅侦听器。

示例

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

registerPositionListener()

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

订阅侦听器以监视播放位置的更新。播放位置将以秒为单位。

参数

listener

IPlayerSessionPositionListener

要添加的侦听器。请参阅IPlayerSessionPositionListener

interval

number

接收播放位置更新的间隔（以秒为单位）。必须是非负值。

sessionId?

IPlayerSessionId

可选请求的目标会话ID。若未提供，则目标会话由PlayerServer决定。

返回值

Promise<ISubscription>

这是一个Promise，当成功完成时，会返回一个ISubscription对象。当不再需要侦听器时，此对象可用于取消订阅侦听器。

示例

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

registerStatusListener()

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

订阅侦听器以监视播放器会话状态的变化。

参数

listener

IPlayerSessionStatusListener

要添加的侦听器。请参阅IPlayerSessionStatusListener

sessionId?

IPlayerSessionId

可选请求的目标会话ID。若未提供，则目标会话由PlayerServer决定。

返回值

Promise<ISubscription>

这是一个Promise，当成功完成时，会返回一个ISubscription对象。当不再需要侦听器时，此对象可用于取消订阅侦听器。

示例

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

registerTrackListener()

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

订阅侦听器以监视轨道信息的变化。

参数

listener

IPlayerSessionTrackListener

要添加的侦听器。参阅IPlayerSessionTrackListener

sessionId?

IPlayerSessionId

可选请求的目标会话ID。若未提供，则目标会话由PlayerServer决定。

返回值

Promise<ISubscription>

这是一个Promise，当成功完成时，会返回一个ISubscription对象。当不再需要侦听器时，此对象可用于取消订阅侦听器。

示例

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

seek()

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

向PlayerServer发送请求以跳转至给定的播放位置（以秒为单位）。

参数

position

number

要跳转的播放位置（以秒为单位），要么相对于当前播放位置 (isRelative = true)；要么相对于媒体的播放起点，其中0表示媒体的播放起点 (isRelative = false)。

isRelative?

boolean

提供的位置是当前播放位置的相对位置 (isRelative = true)，还是媒体中的绝对位置 (isRelative = false)。默认值为false。

sessionId?

IPlayerSessionId

可选请求的目标会话ID。若未提供，则目标会话由PlayerServer决定。

返回值

Promise<void>

这是一个Promise，会在成功处理请求时正常完成；在请求失败时，则会返回一个错误并拒绝执行。

详情

媒体会话应更新其IPlayerSessionStatus，以反映新的播放位置。

示例

const sessionId: IPlayerSessionId = {id: 1};
try {
  await playerClientRef.current?.seek(30, true, sessionId);
} catch (error) {
  console.error('调用跳转时出错：', error);
  // 执行错误处理。
}

const sessionId: IPlayerSessionId = {id: 1};
try {
  await playerClientRef.current?.seek(-5, false, sessionId);
} catch (error) {
  console.error('调用跳转时出错：', error);
  // 执行错误处理。
}

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,
  },
};
const sessionId: IPlayerSessionId = {id: 1};

try {
  await playerClientRef.current?.sendMessage(customMessage, sessionId);
} catch (error) {
  console.error('调用sendMessage时出错', error);
  // 执行错误处理。
}

setActiveTrack()

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

向PlayerServer发送请求以设置媒体播放的活动轨道。

参数

trackType

ITrackType

要设置为活跃的轨道的类型。

trackId

string

要设置为活跃的轨道的轨道ID。

sessionId?

IPlayerSessionId

可选请求的目标会话ID。若未提供，则目标会话由PlayerServer决定。

返回值

Promise<void>

这是一个Promise，会在成功处理请求时正常完成；在请求失败时，则会返回一个错误并拒绝执行。

详情

媒体会话应更新其IPlayerSessionStatus以反映新播放状态。

示例

const sessionId: IPlayerSessionId = {id: 1};
try {
  await playerClientRef.current?.setActiveTrack('AUDIO', 'JS_0', sessionId);
} catch (error) {
  console.error('调用setActiveTrack时出错：', error);
  // 执行错误处理。
}

setMediaControlFocus()

setMediaControlFocus: (componentInstance, mediaControlHandler?) => Promise<void>

注册PlayerClientMediaControlHandler实例

自版本2.1.0起可用。

参数

componentInstance

IComponentInstance

需要为其设置处理程序的组件实例。

mediaControlHandler?

PlayerClientMediaControlHandler

一个对象，包含事件处理程序。

返回值

Promise<void>

这是一个Promise，会在成功处理请求时正常完成；在请求失败或目标版本低于2.1.0时，则会返回一个错误并拒绝执行。

示例

// 在交互式组件中。
import {
  useComponentInstance,
  IComponentInstance,
} from '@amazon-devices/react-native-kepler';
import {PlayerClientMediaControlHandler} from '@amazon-devices/kepler-player-client';

const componentInstance: IComponentInstance = useComponentInstance();
class MyMediaControlsHandler extends PlayerClientMediaControlHandler {
  private playerClientRef: IPlayerClient | undefined;
  // 实现MyMediaControlsHandler。
}

let mediaControlsHandler: MyMediaControlsHandler = new MyMediaControlsHandler(
  playerClientRef.current as IPlayerClient,
);
try {
  await playerClientRef.current?.setMediaControlFocus(
    componentInstance,
    mediaControlsHandler,
  );
} catch (error) {
  console.error('调用setMediaControlFocus时出错：', error);
  // 执行错误处理。
}

setMute()

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

向PlayerServer发送请求以将播放设为静音或取消静音。

参数

isMuted

boolean

如果为true，则应将媒体静音

sessionId?

IPlayerSessionId

可选请求的目标会话ID。若未提供，则目标会话由PlayerServer决定。

返回值

Promise<void>

这是一个Promise，会在成功处理请求时正常完成；在请求失败时，则会返回一个错误并拒绝执行。

详情

媒体会话应更新其IPlayerSessionStatus以反映新播放状态。

示例

const sessionId: IPlayerSessionId = {id: 1};
try {
  await playerClientRef.current?.setMute(true, sessionId);
} catch (error) {
  console.error('调用setMute时出错：', error);
  // 执行错误处理。
}

setPlaybackRate()

setPlaybackRate: (playbackRate, sessionId?) => Promise<void>

向PlayerServer发送请求以设置媒体播放的播放速率。

参数

playbackRate

number

要设置的播放速率，比如0.25、0.5、2.0等。如果不支持输入的播放速率，承诺将拒绝执行，注册的IPlayerSessionErrorListener实例将收到IPlayerSessionError。

sessionId?

IPlayerSessionId

可选请求的目标会话ID。若未提供，则目标会话由PlayerServer决定。

返回值

Promise<void>

这是一个Promise，会在成功处理请求时正常完成；在请求失败时，则会返回一个错误并拒绝执行。

详情

媒体会话应更新其IPlayerSessionStatus以反映新播放状态。

示例

const sessionId: IPlayerSessionId = {id: 1};
try {
  await playerClientRef.current?.setPlaybackRate(1.5, sessionId);
} catch (error) {
  console.error('调用setPlaybackRate时出错：', error);
  // 执行错误处理。
}

setTextView()

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

向PlayerServer中的媒体会话发送请求，以使用加载的内容设置KeplerCaptionsView。

参数

viewHandle

IViewHandle

KeplerCaptionsView的界面处理程序。

sessionId?

IPlayerSessionId

可选设置字幕界面的目标会话ID。如果未指定，则由PlayerServer决定如何处理请求。

返回值

Promise<void>

这是一个Promise，会在成功处理请求时正常完成；在请求失败时，则会返回一个错误并拒绝执行。

详情

只有在调用某个加载API并成功加载媒体内容后，再调用setTextView。

示例

const captionsHandleRef = useRef<IViewHandle | null>(null);
const sessionId: IPlayerSessionId = {id: 1};

// 在<KeplerCaptionsView>组件中注册下面的onCaptionViewCreated函数。
const onCaptionViewCreated = (surfaceHandle: string): void => {
  captionsHandleRef.current = {handle: surfaceHandle};
  try {
    await playerClientRef.current?.setTextView(
      captionsHandleRef.current,
      sessionId,
    );
  } catch (error) {
    console.error('调用clearVideoView时出错：', error);
    // 执行错误处理。
  }
};

setVideoView()

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

向PlayerServer中的媒体会话发送请求，以使用加载的内容设置KeplerVideoSurfaceView。

参数

viewHandle

IViewHandle

KeplerVideoSurfaceView的标识符。

sessionId?

IPlayerSessionId

可选设置视频界面的目标会话ID。如果未指定，则由PlayerServer决定如何处理请求。

返回值

Promise<void>

这是一个Promise，会在成功处理请求时正常完成；在请求失败时，则会返回一个错误并拒绝执行。

详情

只有在调用某个加载API并成功加载媒体内容后，再调用setVideoView。

示例

const surfaceHandleRef = useRef<IViewHandle | null>(null);
const sessionId: IPlayerSessionId = {id: 1};

// 在<KeplerVideoSurfaceView>组件中注册下面的onSurfaceViewCreated函数。
const onSurfaceViewCreated = (surfaceHandle: string): void => {
  surfaceHandleRef.current = {handle: surfaceHandle};
  try {
    await playerClientRef.current?.setVideoView(
      surfaceHandleRef.current,
      sessionId,
    );
  } catch (error) {
    console.error('调用setVideoView时出错：', error);
    // 执行错误处理。
  }
};

setVolume()

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

向PlayerServer发送请求以设置媒体播放的音量。

参数

volume

number

要设置的音量，在0.0到1.0范围之间。

sessionId?

IPlayerSessionId

可选请求的目标会话ID。若未提供，则目标会话由PlayerServer决定。

返回值

Promise<void>

这是一个Promise，会在成功处理请求时正常完成；在请求失败时，则会返回一个错误并拒绝执行。

详情

媒体会话应更新其IPlayerSessionStatus以反映新播放状态。

示例

const sessionId: IPlayerSessionId = {id: 1};
try {
  await playerClientRef.current?.setVolume(0.75, sessionId);
} catch (error) {
  console.error('调用setVolume时出错：', error);
  // 执行错误处理。
}

unload()

unload: (sessionId?) => Promise<void>

向PlayerServer中的媒体会话发送请求，以卸载媒体内容。例如，要同步卸载媒体内容，如果应用转入后台状态，请调用unloadSync。

参数

sessionId?

IPlayerSessionId

可选卸载内容的目标会话ID。如果未指定，则由PlayerServer决定如何处理请求。

返回值

Promise<void>

这是一个Promise，会在成功处理请求时正常完成；在请求失败时，则会返回一个错误并拒绝执行。

示例

const sessionId: IPlayerSessionId = {id: 1};

try {
  await playerClientRef.current?.unload(sessionId);
} catch (error) {
  console.error('调用卸载时出错：', error);
  // 执行错误处理。
}

unloadSync()

unloadSync: (timeoutMsec, sessionId?) => IUnloadSyncStatus

向PlayerServer中的媒体会话发送请求，以同步卸载媒体内容。当应用转入后台状态时，使用此API释放媒体资源。

参数

timeoutMsec

number

unloadSync API允许的最长执行时间（以毫秒为单位）。

注意

最小值为1000，最大值为5000。

sessionId?

IPlayerSessionId

可选卸载内容的目标会话ID。如果未指定，则由PlayerServer决定如何处理请求。

返回值

IUnloadSyncStatus

@amazon-devices/kepler-player-server#IUnloadSyncStatus|PlayerServer IUnloadSyncStatus.中的一个枚举值。

自以下版本起可用：

2.2.0

示例

const sessionId: IPlayerSessionId = {id: 1};

if (isPresentOnOS('@amazon-devices/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成功完成。');
    }
  } catch (error) {
    console.error('调用unloadSync时出错：', error);
    // 执行错误处理。
  }
} else {
  console.error('该操作系统不支持unloadSync。');
}

Last updated: 2025年10月2日

关注我们:
amazon_developer_logo

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

协议

开发人员博客

联系我们