Amazon Developer

Console

as

Settings
Sign out
Notifications
Alexa
Amazonアプリストア
AWS
ドキュメント
Support
Contact Us
My Cases

Console

as

開発
設計と開発
公開
リファレンス
サポート

IPlayerServer

IPlayerServer

Keplerプレーヤーサーバーの操作を表します。このインターフェイスは、Keplerプレーヤーサーバーのハンドラーを管理し、Keplerプレーヤーのセッションステータスを更新するためのメソッドを提供します。

ランタイムエラーの場合、アプリはErrorオブジェクトでプロミスを拒否し、可能な場合はメディアプレーヤーから受信したエラーコードとメッセージをIPlayerSessionErrorを使用して送信する必要があります。

プロパティ

addTrack()

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

通知を希望するクライアントにKeplerプレーヤーの新しいトラックが追加されたこと通知します。AudioPlayerまたはVideoPlayerは、AudioTrackList、VideoTrackList、TextTrackListのいずれかに"addtrack"のEventListenerを登録してから、このAPIを呼び出す必要があります。

パラメーター

newTrack

ITrackInfo

新しいトラックの追加に関する読み取り専用の詳細情報です。

sessionId?

IPlayerSessionId

省略可能。新しいトラックが追加されたセッションのセッションIDです。指定しない場合、すべてのセッションのデータに関するリクエストとして扱います。

戻り値

Promise<void>

更新が完了したときに解決されるプロミスです。

詳細

サーバーセッションの新しいトラックに関する更新は、メディアの再生ステータス、現在選択されているメディア、その他の関連情報の変更を反映するために不可欠です。アプリでは、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プレーヤーの既存のトラックが削除されたことを通知します。AudioPlayerまたはVideoPlayerは、AudioTrackList、VideoTrackList、TextTrackListのいずれかに"removetrack"のEventListenerを登録してから、このAPIを呼び出す必要があります。

パラメーター

removedTrack

ITrackInfo

削除された既存のトラックの読み取り専用の詳細。

sessionId?

IPlayerSessionId

省略可能。既存のトラックが削除されたセッションのセッションIDです。指定しない場合、すべてのセッションのデータに関するリクエストとして扱います。

戻り値

Promise<void>

更新が完了したときに解決されるプロミスです。

詳細

サーバーセッションの削除されたトラックに関する更新は、メディアの再生ステータス、現在選択されているメディア、その他の関連情報の変更を反映するために不可欠です。アプリでは、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>

エラーが送信されたときに解決されるプロミスです。

例

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

any

送信するカスタムメッセージです。JSON値（undefinedを除く）をメッセージとして送信します。

sessionId?

IPlayerSessionId

省略可能。カスタムメッセージの処理が必要なセッションのセッションIDです。

戻り値

Promise<void>

メッセージが送信されたときに解決されるプロミスです。リクエストが失敗した場合やmessageがundefinedの場合は、エラーで拒否されます。

詳細

これは、UIの更新に使用できるカスタムメッセージをクライアントに提供する場合に特に役立ちます。

例

// 任意のオブジェクトを作成します。
const customMessage = {
  video: {
    title: "ビデオ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プレーヤーのカスタムロジックを実装するには、ハンドラーの割り当てが不可欠です。この呼び出しでは、コンポーネントごとに1つのハンドラーを使用できます。アクティブなハンドラーは、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>

更新が完了したときに解決されるプロミスです。

詳細

サーバーセッションの再生バッファ範囲に関する更新は、メディアの再生ステータス、現在選択されているメディア、その他の関連情報の変更を反映するために不可欠です。

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>

更新が完了したときに解決されるプロミスです。

詳細

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, Amazon.com, Inc. or its affiliates. All Rights Reserved. 無断複写·転載を禁じます。

利用規約

Amazon開発者ブログ

お問い合わせ