APL Video

---

Videoコンポーネントは、1つのビデオまたは一連のビデオを表示できるビデオプレーヤーを表示します。埋め込みのビデオプレーヤーにはコントロールがありません。代わりにVideoコンポーネントは、ビデオプレーヤーを操作するコントロールを作成するために必要なイベントとコマンドを提供します。ビデオプレーヤーを操作する方法の詳細については、PlayMediaコマンドとControlMediaコマンドを参照してください。

Videoコンポーネントを使用するスキルは、音声と画面上のボタンを使用してビデオコンテンツを一時停止する手段を提供する必要があります。

プロパティ

Videoコンポーネントには、基本コンポーネントのプロパティに加えて次のプロパティがあります。列の意味を参照する。

プロパティ	型	デフォルト	スタイル設定	動的	説明
audioTrack	次のいずれか：foreground、background、none	foreground	×	×	再生するオーディオトラックです。
autoplay	ブール値	false	×	×	trueの場合、ビデオの再生を自動的に開始します。
muted	ブール値	false	×	◯	trueの場合、ビデオの音声をミュートにします。
onEnd	コマンドの配列	[ ]	×	×	最後のビデオトラックの再生が終了したときに実行するコマンドです。
onPause	コマンドの配列	[ ]	×	×	ビデオが再生中から一時停止に切り替えられたときに実行するコマンドです。
onPlay	コマンドの配列	[ ]	×	×	ビデオが一時停止から再生中に切り替えられたときに実行するコマンドです。
onTimeUpdate	コマンドの配列	[ ]	×	×	再生位置が変更されたときに実行するコマンドです。
onTrackUpdate	コマンドの配列	[ ]	×	×	現在のビデオトラックが変更されたときに実行するコマンドです。
onTrackReady	コマンドの配列	[]	×	×	現在のトラックの状態がreadyに変更されたときに実行するコマンドです。
onTrackFail	コマンドの配列	[]	×	×	エラーの発生によってビデオプレーヤーがメディアを再生できないときに実行するコマンドです。
preserve	文字列の配列	[]	×	×	Reinflateコマンドでドキュメントを再インフレートするときに保存するプロパティです。
scale	次のいずれか：best-fill、best-fit	best-fit	×	×	表示領域に合わせてビデオのサイズを調整する方法を指定します。
screenLock	ブール値	true	×	◯	trueの場合、ビデオ再生中のドキュメントのライフサイクルを延長します。
source、source	URLまたはソースの配列	[ ]	×	◯	ビデオのソース（1つまたは複数）です。
trackChanges	文字列の配列	[]	×	×	視覚コンテキストの変更を追跡して報告するためのプロパティです。

Videoがイベントのソースまたはターゲットである場合は、以下の値がevent.sourceまたはevent.targetに報告されます。

heightとwidth

Videoコンポーネントのheightとwidthは、指定しない場合はデフォルトで100dpになります。

audioTrack

audioTrackプロパティは、メディアコンテンツをフォアグラウンドオーディオまたはバックグラウンドオーディオに割り当てるか、完全にミュート（none）にします。フォアグラウンドオーディオは、音声コマンドやサウンドエフェクトとインターリーブされます。バックグラウンドオーディオは、音声コマンドやサウンドエフェクトの後に再生されます。フォアグラウンドまたはバックグラウンドに使用できるオーディオソースは、一度に1つだけです。

値	説明
foreground	オーディオはフォアグラウンドトラックで再生されます。Alexaとの音声対話を行うと、このメディアは一時停止されます。
background	オーディオはバックグラウンドの音楽トラックで再生されます。既存のバックグラウンドオーディオは停止されます。Alexaとの音声対話を行うと、このメディアはダッキングされるか、短時間一時停止される可能性があります。
none	オーディオコンテンツは無視され、ビデオコンテンツのみが再生されます。

audioTrackがforegroundに設定されている場合、PlayMediaコマンドは、すべてのメディアトラックが終わになるまで「終了」しません。このため、次の例に示すように、単純なコマンドシーケンスでメディアコンテンツと音声をインターリーブして実行できます。

PlayMediaコマンドのaudioTrackがbackgroundまたはnoneに設定されている場合、オーディオは即座に「終了」し、メディアコンテンツの終わりまで待つことはありません。バックグラウンドメディアは画面のタッチに応答しません。たとえば、次のシーケンスでは、SendEventコマンドはメディアの再生終了を待たずにすぐに実行されます。

autoplay

trueの場合、ビデオは読み込まれた直後に自動的に再生を開始します。falseの場合、コマンドを使用して明示的にビデオの再生を開始する必要があります。ビデオ再生を制御するコマンドの詳細については、PlayMediaコマンドとControlMediaコマンドを参照してください。autoplayプロパティのデフォルトはfalseです。

muted

trueの場合、ビデオプレーヤーのオーディオをミュートにします。audioTrackがnoneに設定されている場合は無視されます。mutedプロパティのデフォルトはfalseです。

onEnd

onEndハンドラーは、ビデオシーケンスの最後のビデオのリピートが終わり、再生が終了したときに実行されます。onEndハンドラーは複数回実行される可能性があります。たとえば、あるビデオを最後まで再生して停止した後、シークコマンドを受け取って前の位置に早戻しし、そこで再生コマンドを受け取って、最後まで再生して停止するような状況があり得ます。

生成されるイベントの形式は次のようになります。

event.sourceのプロパティの詳細については、イベントソースを参照してください。

onEndイベントハンドラーは、コンポーネントのデータバインディングコンテキストで通常モードで実行されます。

onPause

onPauseハンドラーは、ビデオ再生が再生中から一時停止に意図的に切り替えられたときに実行されます。これは、ビデオプレーヤーが最後のビデオの終了位置に達した場合、コマンドで再生が停止された場合、ユーザーが意図的に次のトラックに進めたために同期ビデオ再生が中断された場合に発生する可能性があります。ビデオプレーヤーがビデオコンテンツのダウンロードのために再生を一時停止した場合や、エラーのために再生を続行できず、onTrackFailハンドラーが呼び出された場合は、onPauseハンドラーは実行されません。

生成されるイベントの形式は次のようになります。

event.sourceのプロパティの詳細については、イベントソースを参照してください。

onPauseイベントハンドラーは、コンポーネントのデータバインディングコンテキストで通常モードで実行されます。

onPlay

onPlayハンドラーは、ビデオ再生が一時停止から再生中に切り替えられるたびに呼び出されます。これは、autoplayがtrueに設定されたビデオ、PlayMediaコマンド、再生コマンドによって発生する可能性があります。

生成されるイベントの形式は次のようになります。

event.sourceのプロパティの詳細については、イベントソースを参照してください。

onPlayイベントハンドラーは、コンポーネントのデータバインディングコンテキストで通常モードで実行されます。

onTimeUpdate

onTimeUpdateハンドラーは、現在のビデオの再生位置が変更されたときに呼び出されます。ハンドラーは「ベストエフォート」ベースで呼び出され、呼び出しの頻度は保証されません。

生成されるイベントの形式は次のようになります。

event.sourceのプロパティの詳細については、イベントソースを参照してください。

onTimeUpdateイベントハンドラーは、コンポーネントのデータバインディングコンテキストで高速モードで実行されます。

onTrackUpdate

onTrackUpdateハンドラーは、別のビデオトラックがアクティブになったときに呼び出されます。これは、通常のビデオシーケンスとしてプレイヤーが次のビデオトラックに進むときに発生するほか、プレイヤーに対してコマンドが発行された結果として発生することもあります。

生成されるイベントの形式は次のようになります。

event.sourceのプロパティの詳細については、イベントソースを参照してください。

onTrackUpdateイベントハンドラーは、コンポーネントのデータバインディングコンテキストで高速モードで実行されます。

onTrackReady

onTrackReadyハンドラーは、trackStateがnotReadyからreadyに変更されたときにトラックに対して実行されます。これは、trackStateがnotReadyからreadyに変更されたときに、各トラックの再生が開始される前に発生します。

読み込みの成功時に生成されるイベントの形式は次のようになります。

event.sourceのプロパティの詳細については、イベントソースを参照してください。

onTrackReadyイベントハンドラーは、コンポーネントのデータバインディングコンテキストで高速モードで実行されます。

このハンドラーは次のシナリオで実行されます。

• 最初のソースが有効で、ビデオプレーヤーが再生開始に必要な関連メディア情報を取得したとき。これは、ドキュメントのインフレート後、再生開始の前に発生します。

  このシナリオでは、ハンドラーは次の形式のイベントを生成します。

    "event": {
      "source": {
        "type": "Video",
        "handler": "TrackReady",
          ...                     // コンポーネントのソースのプロパティ
      },
      "trackIndex": 0,
      "trackState": 'ready',
    }
  

  • ソースが無効な場合やメディアがサポートされていない場合は、代わりにonTrackFailが実行されます。

• ビデオプレーヤーが次のトラックに進もうとして、onTrackUpdateイベントのtrackStateプロパティがnotReadyだった場合に、onTrackUpdateの後でそのトラックの準備ができたとき。

  たとえば、2番目のトラックに進んだときにonTrackUpdateが実行され、その後でonTrackReadyが実行されます。2番目のトラックの再生時間が5000ミリ秒であるとすると、これらのハンドラーは次のイベントを生成します。

    "event": {
      "source": {
        "type": "Video",
        "handler": "TrackUpdate",
        ...                     // コンポーネントのソースのプロパティ
      },
      "trackIndex": 1,
      "trackCount": N,
      "trackState": 'notReady',
      "currentTime": 0,
      "duration": 5000,
      "paused": false,
      "ended": false
    }
  

    "event": {
      "source": {
        "type": "Video",
        "handler": "TrackReady",
        ...                     // コンポーネントのソースのプロパティ
      },
      "trackIndex": 1,
      "trackState": 'ready',
    }
  

onTrackFail

onTrackFailハンドラーは、再生の開始中やトラックの再生または切り替え中にエラーが発生した場合に、トラックに対して実行されます。エラーは、ソースURLにアクセスできない場合、メディアコンテンツがサポートされていない場合、メディアコンテンツの形式が誤っている場合に発生する可能性があります。

エラーが発生すると、プレーヤーは次のトラックに進まず、その時点の状態のままonTrackFailが実行されます。

生成されるイベントの形式は次のようになります。

event.sourceのプロパティの詳細については、イベントソースを参照してください。

onTrackFailイベントハンドラーは、コンポーネントのデータバインディングコンテキストで高速モードで実行されます。

このハンドラーは次のシナリオで実行されます。

• ビデオプレーヤーが再生する最初のトラックの読み込みに失敗した場合、または最初のトラックのメディアコンテンツの形式が誤っているかサポートされていない場合。再生は開始されず、ビデオプレーヤーが自動的に次のトラックに進むことはありません。

  このシナリオでは、onTrackFailで次のイベントが生成されます。

    "event": {
      "source": {
        "type": "Video",
        "handler": "TrackFail",
        ...                     // コンポーネントのソースのプロパティ
      },
      "trackIndex": 0,
      "trackState": 'failed',
      "currentTime": 0,
      "errorCode": Number
    }
  

• ビデオプレーヤーが次のトラックに進もうとして、そのトラックの読み込みに失敗したか、トラックの形式が誤っているか、トラックがサポートされていない場合。

  このシナリオでは、onTrackUpdateの後にonTrackFailが実行されます。

  たとえば、ビデオプレーヤーが無効なURLのトラックに進んだとします。この場合、onTrackUpdateハンドラーが実行され、続いてonTrackFailが実行されます。ハンドラーは次のイベントを生成します。

  "event": {
    "source": {
      "type": "Video",
      "handler": "TrackUpdate",
      ...                     // コンポーネントのソースのプロパティ
    },
    "trackIndex": 1,
    "trackCount": N,
    "trackState": 'notReady',
    "currentTime": 0,
    "duration": 0,
    "paused": 0,
    "ended": 0
  }
  

  "event": {
    "source": {
      "type": "Video",
      "handler": "TrackFail",
      ...                     // コンポーネントのソースのプロパティ
    },
    "trackIndex": 1,
    "trackState": 'failed',
    "currentTime": 0,
    "errorCode": Number
  }
  

• ビデオプレーヤーが新しいトラックに進み、onTrackUpdateに続いてonTrackReadyが呼び出され、トラックを再生し始めたものの、再生の開始後にエラーが発生して再生を続行できなくなったとき。再生はonTrackFailが実行された時点で停止し、ビデオプレーヤーが自動的に次のトラックに進むことはありません。

  たとえば、ビデオプレーヤーがシーケンスの2番目のトラックを再生しているとします。このトラックの再生時間は5000ミリ秒ですが、1500ミリ秒の時点でエラーが発生します。再生は停止し、onTrackFailハンドラーが実行されて、次のイベントが生成されます。

    "event": {
      "source": {
        "type": "Video",
        "handler": "TrackFail",
        ...                     // コンポーネントのソースのプロパティ
      },
      "trackIndex": 1,
      "trackState": 'failed',
      "currentTime": 1500,
      "errorCode": Number
    }
  

preserve

Reinflateコマンドでドキュメントを再インフレートするときに保存する、動的なコンポーネントプロパティとバインドされたプロパティの配列です。

Videoには以下のコンポーネント固有のプロパティ名があり、これらをpreserve配列に割り当てることができます。

• source - トラックの配列です。
• playingState - プレーヤーの状態（再生中または一時停止）です。

sourceオプションは、古いビデオプレーヤーから現在のソースリストを保存し、新しいビデオプレーヤーで復元します。これには、現在選択されているトラックとそのトラック内の位置が含まれます。

playingStateオプションは、ビデオが現在再生中かどうかを保存します。playingStateが保存されていない場合、ビデオプレーヤーでビデオ再生を自動的に開始する必要があるかどうかの判断には、Videoコンポーネントのautoplayプロパティが使用されます。

scale

コンテナー内でのビデオのサイズを調整します。

名前	説明
best-fill	レターボックス処理を行わずに、コンテナーに合わせてビデオのサイズを調整します。ビデオとコンテナーのアスペクト比が異なる場合、ビデオの上下または左右の端が表示されなくなります。
best-fit	コンテナー内に収まるようにビデオのサイズを調整します。ビデオとコンテナーのアスペクト比が異なる場合、ビデオの左右または上下に黒帯を入れるレターボックス処理が適用されます。

screenLock

screenLockプロパティは、ビデオを再生しているときのドキュメントのインタラクション時間を制御します。screenLockプロパティがtrue（デフォルト）の場合、ビデオを再生するとタイマーが無効になります。screenLockがfalseの場合、ドキュメントのライフサイクルは変更されません。

source

再生するビデオクリップまたは一連のビデオクリップを指定します。sourceプロパティには、プレーンなURL（文字列）かソースデータの配列を設定できます。

複数のビデオを配列で指定すると、プレーヤーは各ビデオを順番に再生します。Videoコンポーネントのsourceプロパティと各ソースのurlプロパティは、「配列化」のルールに従います。urlプロパティには、プレーンな文字列を単一のURLとして指定するほかに、urlプロパティのあるオブジェクトを指定することもできます。

次の例の各行は、sourceプロパティを設定する有効な方法を示しています。

メディアソースを指定する最も一般的な方法は、定義をすべて展開することです。

以下は、上の定義と同等の最小限の定義です。

sourceがデータ配列の場合、次のような構造になります。

プロパティ	型	デフォルト	説明
description	文字列	""	（任意）このソースの説明です。
duration	数値	none	再生時間です。0または負の場合、ストリーム全体を再生します。ミリ秒単位で表します。
url	URL	必須	メディアのソースです。
textTrack（textTracks）	textTrackオブジェクトの配列	[]	このビデオソースのテキストトラックを表すオブジェクトです。再生中にクローズドキャプションを提供するために使用されます。
repeatCount	整数	0	ビデオのリピート回数です。
entity（entities）	エンティティの配列	[]	このメディアをAlexaに報告するときに設定するエンティティデータです。
offset	数値	0	ストリーム内の再生開始位置のオフセットです。

duration

ミリ秒単位の再生時間です。設定しない場合、ビデオ全体が再生されます。実際のメディアクリップよりも短い時間に設定すると、ビデオプレーヤーは指定した時間だけ再生して停止します。durationを実際のメディアクリップよりも長い時間に設定しても、再生時間は追加されません。durationが0以下の場合、ビデオプレーヤーはメディアクリップ全体を再生します。

url（urls）

メディアソースのURLです。httpsのURLを使用する必要があります。サポートされているビデオ形式を特定するには、Viewportのvideoプロパティを確認します。

textTrack

textTrackプロパティは、ビデオソースに追加できる1つまたは複数のテキストトラックに関するデータを保持します。ビデオの再生中にクローズドキャプションとして表示するテキストを提供するには、このプロパティを使用します。

textTrackオブジェクトには、次の表に示すプロパティがあります。

プロパティ	型	デフォルト	説明
description	文字列	""	（任意）このテキストトラックの説明です。
url	URL	必須	このテキストトラックのソースです。SubRip字幕ファイル（SRT）のURLを指定します。
type	文字列	必須	このテキストトラックの用途を示します。captionに設定する必要があります。その他の値は無視されます。

ビデオソースには、typeをcaptionに設定したtextTrackを1つ含めることができます。同じビデオソースに追加のtextTrackオブジェクトを指定しても、ビデオプレーヤーによる再生中には無視されます。

最初のtextTrackの読み込みに失敗した場合、ビデオプレーヤーはキャプションなしでビデオの再生を続行します。それ以降のトラックは使用されません。

次の例は、textTrackプロパティを設定する有効な方法を示しています。

以下の例は、Videoコンポーネントのsource配列を示しています。配列内の各sourceには、それぞれ独自のtextTrackがあります。

以下は、複数のソースを含むビデオソース配列の例です。各ソースには、それぞれ独自のテキストトラックがあります。

Videoコンポーネントは、SubRip字幕ファイル（SRT）形式のテキストトラックをサポートしています。

ユーザーは、ビデオの再生中にキャプションを表示するかどうかを制御できます。Echo Showデバイスでは、設定＞ユーザー補助＞字幕で字幕にチェックを入れますこれらの設定の詳細については、スクリーン付きEchoデバイスで字幕をオンにするを参照してください。

repeatCount

このメディアをリピート再生する回数です。デフォルトは0で、1回最後まで再生したら停止します。-1に設定すると、ビデオは無限にリピート再生されます。

offset

再生の開始位置を示す、メディアの先頭からのオフセットです。ミリ秒単位で表します。デフォルトは0で、メディアの先頭から再生を開始します。ビデオに正のrepeatCount値が設定されている場合、メディアは毎回同じオフセットから再生されます。

trackChanges

VideoコンポーネントのtrackChangesには、次の表に示す名前付きのプロパティが追加されています。

名前	型	説明
currentTrack	数値	選択されているトラックです。
playingState	次のいずれか：idle、playing、paused、stopped	ビデオプレーヤーの状態です。

コンポーネントのtrackChangesプロパティの詳細については、trackChangesを参照してください。

変更がどのようにスキルに報告されるかの詳細については、スキルリクエストのAPL視覚コンテキストを参照してください。

ビデオの状態

ビデオプレーヤーでは、次の表に示す値を持つ状態が公開されます。

プロパティ	型	説明
trackIndex	整数	ソース配列内の現在のトラックです。0から始まるインデックスで示されます。
trackCount	整数	ソース配列に含まれているトラックの合計数です。
trackState	notReady | ready | failed	現在のトラックの状態です。
currentTime	整数	現在のトラックの現在の再生位置です。ミリ秒単位で表されます。
duration	整数	現在のトラックの再生時間です。ミリ秒単位で表されます。トラックの長さが不明な場合は-1を返します。
paused	ブール値	ビデオが一時停止状態の場合はtrueです。
ended	ブール値	すべてのビデオトラックの再生が終了した場合はtrueです。

ビデオイベントハンドラーは、これらの状態をeventプロパティの個別のプロパティとして公開します。

次の例は、ビデオの再生が開始されたときに、ビデオ再生に関する情報を含むリクエストをスキルに送信する方法を示しています。以下のonPlayハンドラーは、SendEventコマンドを実行します。argumentsにはeventのプロパティが含まれています。

次の例は、スキルが受け取るUserEventリクエストを示しています。リクエストのargumentsプロパティには、コマンドのargumentsプロパティで指定されたビデオ再生データが含まれています。

trackState

現在のトラックまたはメディアソースの状態を表す値を返します。

状態	説明
notReady	トラックの初期状態またはデフォルト状態です。この状態では再生を開始できません。
ready	トラックの準備が完了し、再生を開始できます。
failed	トラックが失敗し、再生の開始または現在の再生位置からの続行ができません。

サンプルビデオ

以下は、このVideoコンポーネントを含むドキュメント全体の例を示しています。この例では、AlexaTransportControlsとAlexaSliderの各レスポンシブ対応コンポーネントを使用してビデオのUIコントロールを提供します。

---

再生用インテント

音声ベースの再生コントロールをサポートするには、 ビルトインインテントを実装する必要があります。

ビデオ再生後の音声入力を管理する

ビデオの終了後に音声入力を受け付けるには、onEndイベントハンドラーを使用してSendEventコマンドを呼び出します。次に、後続のUserEventリクエストをスキルで処理します。音声入力を受け付けるには、shouldEndSessionをfalseに設定した応答を送信します。応答には適切なoutputSpeechオブジェクトとrepromptオブジェクトを含めて、Alexaユーザーに入力をたずねる必要があります。

ビデオをサポートしないデバイス

画面付きのデバイスの中には、ビデオ再生をサポートしないものがあります。ビデオをサポートしないデバイスでもVideoコンポーネントは画面上に表示されますが、コンテンツは表示されないため、ユーザーには画面に空白の領域が見えることになります。ビデオをサポートしないデバイスでは、別のエクスペリエンスを提供してください。

デバイスがビデオをサポートしていない場合、データバインディングコンテキストのdisallowVideoプロパティからtrueが返されます。このプロパティをAPLドキュメントの条件付きロジックで使用します。

または、スキルコードでビデオサポートを確認することもできます。その場合は、スキルに送信されたリクエストのcontext.Viewport.videoプロパティを確認します。

関連トピック

• Alexaデザインガイド： Alexa Presentation Language（英語のみ）

---

---

最終更新日: 2025 年 11 月 26 日