APL Video
Videoコンポーネントは、1つのビデオ、または一連のビデオを表示できるビデオプレーヤーを表示します。埋め込み動画のプレーヤーでは操作はできません。その代わり、Videoコンポーネントは、ビデオプレーヤーの操作に使用するコントロールの作成に必要なイベントとコマンドを、ビデオプレーヤーに提供します。ビデオプレーヤーを操作する方法の詳細は、APLメディアコマンドを参照してください。
Videoコンポーネントを使用するスキルでは、ビデオコンテンツを音声もしくは画面のタッチで一時停止する方法を提供してください。
プロパティ
Videoコンポーネントには、基本コンポーネントのプロパティのほかに次のプロパティがあります。列の意味を参照してください。
| プロパティ | 型 | デフォルト | スタイル設定 | 動的 | 説明 | |
|---|---|---|---|---|---|---|
|
|
|
|
✕ |
✕ |
再生するオーディオトラックです。 | |
|
|
ブール値 |
|
✕ |
✕ |
| |
|
|
ブール値 |
|
✕ |
◯ |
trueの場合、ビデオの音声をミュートにします。 | |
|
|
コマンド配列 |
[ ] |
✕ |
✕ |
最後のビデオトラックの再生が終わったときに実行するコマンドです。 | |
|
|
コマンド配列 |
[ ] |
✕ |
✕ |
ビデオが再生から一時停止に切り替えられたときに実行するコマンドです。 | |
|
|
コマンド配列 |
[ ] |
✕ |
✕ |
ビデオが一時停止から再生に切り替えられたときに実行するコマンドです。 | |
|
|
コマンドの配列 |
[ ] |
✕ |
✕ |
再生位置が変更されたときに実行するコマンドです。 | |
|
|
コマンド配列 |
[ ] |
✕ |
✕ |
現在のビデオトラックが変更されるときに実行するコマンドです。 | |
|
|
コマンド配列 |
[] |
✕ |
✕ |
現在のトラック状態が | |
|
|
コマンド配列 |
[] |
✕ |
✕ |
エラーが発生してビデオプレーヤーがメディアを再生できないときに実行するコマンドです。 | |
|
|
文字列の配列 |
|
✕ |
✕ |
| |
|
|
|
|
✕ |
✕ |
ビデオのサイズ変更方法です。 | |
|
|
URLまたはSource配列 |
[ ] |
✕ |
◯ |
ビデオソースです。 |
Videoがイベントのソースまたはターゲットである場合、以下の値がevent.sourceまたはevent.targetに報告されます。
{
// Video固有の値
"type": "Video",
"currentTime": Integer, // 現在のトラックでの現在の再生位置（ミリ秒）
"duration": Integer, // 現在のトラックの長さ（ミリ秒）。 トラックの長さが不明の場合は-1を返します。
"ended": Boolean, // Videoがended状態の場合はTrueを返します
"paused": Boolean, // Videoがpaused状態の場合はTrueを返します
"muted": Boolean, // Videoの音声がミュートの場合はTrueを返します
"trackCount": Integer, // ビデオトラックの合計数
"trackIndex": Integer, // 現在のトラックのインデックス（0ベース）
"trackState": notReady | ready | // 現在のトラックの状態
failed
"url": URL, // 現在のトラックのURL
// 一般的なコンポーネントの値
"bind": Map, // コンポーネントのデータバインディングコンテキストへのアクセス
"checked": Boolean, // チェック済み状態
"disabled": Boolean, // 無効化状態
"focused": Boolean, // フォーカス状態
"height": Number, // コンポーネントの高さ（dp単位、パディングを含む）
"id": ID, // コンポーネントのID
"opacity": Number, // コンポーネントの不透明度[0～1]
"pressed": Boolean, // 押された状態
"uid": UID, // ランタイムで生成されたコンポーネントの一意ID
"width": Number // コンポーネントの幅（dp単位、パディングを含む）
}
heightおよびwidth
指定されない場合、Videoコンポーネントのheightとwidthのデフォルトは100dpです。
audioTrack
audioTrackプロパティは、フォアグラウンドまたはバックグラウンドオーディオにメディアコンテンツを割り当てるか、完全にミュート（none）にします。フォアグラウンドオーディオは、音声コマンドやサウンドエフェクトと共にインターリーブします。バックグラウンドオーディオは、音声コマンドやサウンドエフェクトの後に再生します。フォアグラウンドまたはバックグラウンドに使用できるオーディオソースは、一度に1つのみです。
| 値 | 説明 |
|---|---|
|
|
フォアグラウンドトラックのオーディオが再生されます。Alexaと話すと、このメディアは一時停止します。 |
|
|
バックグラウンドの音楽トラックのオーディオが再生されます。既存のバックグラウンドオーディオを停止します。Alexaと話すと、このメディアは一時非表示になるか、短時間一時停止する場合があります。 |
|
|
オーディオコンテンツは無視され、ビデオコンテンツのみが再生されます。 |
audioTrackをforegroundに設定していると、すべてのメディアトラックが終わるまでPlayMediaコマンドは「完了」となりません。このため、シンプルなコマンドシーケンスで、この例のようにメディアコンテンツと音声をインターリーブして実行できます。
"onPress": [
{
"type": "PlayMedia",
"componentId": "myVideoPlayer",
"source": URL,
"audioTrack": "foreground"
},
{
"type": "SpeakItem",
"description": "これはメディアの再生終了後に実行されます",
"componentId": "myAnswerBox"
}
]
PlayMediaコマンドがaudioTrackをbackgroundまたはnoneに設定した場合、オーディオはただちに「終了」し、メディアコンテンツの終わりまで待つことはありません。バックグラウンドメディアは画面タッチに対応していません。たとえば以下のシーケンスでは、SendEventコマンドがただちに実行され、メディアの再生終了を待っていません。
"onPress": [
{
"type": "PlayMedia",
"componentId": "myVideoPlayer",
"source": URL,
"audioTrack": "background"
},
{
"type": "SendEvent",
"description": "これはすぐに実行されます",
"arguments": ["メディアが開始しましたが、まだ停止していません"]
}
]
autoplay
trueに設定すると、ビデオは読み込まれた直後に自動で再生を開始します。falseに設定すると、コマンドを使用して明示的にビデオを開始する必要があります。ビデオの再生を操作するコマンドの詳細は、APLメディアコマンドを参照してください。autoplayプロパティのデフォルトはfalseです。
autoplayをtrueに設定せず、かつshouldEndSessionをfalseに設定してください。これにより、ビデオの再生中、マイクがオンになります。ビデオの終了時に音声入力を受け取る方法の詳細は、ビデオ再生後の音声入力を管理するを参照してください。muted
trueの場合、ビデオプレーヤーの音声をミュートにします。audioTrackがnoneに設定されている場合は無視されます。mutedプロパティのデフォルトはfalseです。
onEnd
onEndハンドラーは、ビデオシーケンスの最後のビデオで繰り返しが終わり、再生が終了したときに実行されます。onEndハンドラーは複数回実行できます。たとえば、あるビデオを最後まで再生して停止し、シークコマンドを受け取って前のポイントまで早戻しして、再生コマンドを受け取ってから、最後まで再生して停止することができます。
生成されるイベントの形式は次のようになります。
"event": {
"source": {
"type": "Video",
"handler": "End",
... // コンポーネントのソースプロパティ
},
"trackIndex": Integer, // trackCount – 1と等しくなります。
"trackCount": Integer,
"trackState": String,
"currentTime": Integer, // durationと等しいか、それ以上になります
"duration": Integer,
"paused": true,
"ended": true
}
event.sourceの詳細についてはイベントソースを参照してください。
onPause
onPauseハンドラーは、ビデオ再生が再生から一時停止に意図的に切り替えられたときに実行されます。これは、ビデオプレーヤーが直前のビデオの最後まで達してコマンドが再生を停止するか、ユーザーが意図的に次のトラックに進めたために同期ビデオ再生が中断されたことにより発生する可能性があります。ビデオプレーヤーがビデオコンテンツのダウンロードのために再生を一時停止する場合や、エラーのために再生を続行できずにonTrackFailハンドラーが呼び出される場合は、onPauseハンドラーは実行されません。
生成されるイベントの形式は次のようになります。
"event": {
"source": {
"type": "Video",
"handler": "Pause",
... // コンポーネントのソースプロパティ
},
"trackIndex": Integer,
"trackCount": Integer,
"trackState": String,
"currentTime": Integer,
"duration": Integer,
"paused": true,
"ended": BOOLEAN
}
event.sourceの詳細についてはイベントソースを参照してください。
onPlay
onPlayハンドラーは、ビデオ再生が一時停止から再生に切り替えられるたびに呼び出されます。autoplayがtrueに設定されたビデオ、PlayMediaコマンド、再生コマンドなどによって発生します。
生成されるイベントの形式は、次のようになります。
"event": {
"source": {
"type": "Video",
"handler": "Play",
... // コンポーネントのソースプロパティ
},
"trackIndex": Integer,
"trackCount": Integer,
"trackState": String,
"currentTime": Integer,
"duration": Integer,
"paused": false,
"ended": BOOLEAN
}
event.sourceの詳細についてはイベントソースを参照してください。
onTimeUpdate
onTimeUpdateハンドラーは、現在のビデオの再生位置が変更されたときに呼び出されます。ハンドラーは「ベストエフォート」ベースで呼び出されます。呼び出しの頻度は保証されていません。
生成されるイベントの形式は次のようになります。
"event": {
"source": {
"type": "Video",
"handler": "TimeUpdate",
... // コンポーネントのソースプロパティ
},
"trackIndex": Integer,
"trackCount": Integer,
"currentTime": Integer,
"trackState": String,
"duration": Integer,
"paused": BOOLEAN,
"seekable": BOOLEAN,
"ended": BOOLEAN
}
event.sourceの詳細についてはイベントソースを参照してください。
onTimeUpdateハンドラーは、常に高速モードで実行されます。
onTrackUpdate
onTrackUpdateハンドラーは、別のビデオトラックがアクティブになったときに呼び出されます。通常のビデオシーケンスとしてプレイヤーが次のビデオトラックに進むとき、プレイヤーにコマンドが渡されたときなどに発生します。
生成されるイベントの形式は、次のようになります。
"event": {
"source": {
"type": "Video",
"handler": "TrackUpdate",
... // コンポーネントのソースプロパティ
},
"trackIndex": Integer,
"trackCount": Integer,
"trackState": String,
"currentTime": Integer,
"duration": Integer,
"paused": BOOLEAN,
"ended": BOOLEAN
}
event.sourceの詳細についてはイベントソースを参照してください。
onTrackReady
onTrackReadyハンドラーは、trackStateがnotReadyからreadyに変更されたときにトラックに対して実行されます。これは、trackStateがnotReadyからreadyに変更されたときに、各トラックの再生が開始される前に発生します。
読み込み成功時に生成されるイベントの形式は次のとおりです。
"event": {
"source": {
"type": "Video",
"handler": "TrackReady",
... // コンポーネントのソースプロパティ
},
"trackIndex": Integer,
"trackState": 'ready',
}
event.sourceの詳細についてはイベントソースを参照してください。
onTrackReadyイベントハンドラーは高速モードで実行されます。
ハンドラーは以下のシナリオで実行されます。
-
1つ目のソースが有効で、ビデオプレーヤーが再生開始に必要な関連メディア情報を取得した場合。これは、ドキュメントのインフレート後、再生開始の前に発生します。
このシナリオでは、ハンドラーは次の形式でイベントを生成します。
"event": { "source": { "type": "Video", "handler": "TrackReady", ... // コンポーネントのソースプロパティ }, "trackIndex": 0, "trackState": 'ready', }- ソースが無効かサポートされていないメディアの場合、代わりに
onTrackFailが実行されます。 - APLランタイムはメディアをキャッシュできるため、トラックをリピートするためにメディアコンテンツを再度読み込まなくてもよい場合があります。ビデオプレーヤーがキャッシュ済みのトラックをリピートする場合、
onTrackReadyは実行されません。プレーヤーがキャッシュ済みトラックに進む際、onTrackUpdateイベントのtrackStateプロパティはreadyです。
- ソースが無効かサポートされていないメディアの場合、代わりに
-
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": {
"type": "Video",
"handler": "TrackFail",
... // コンポーネントのソースプロパティ
},
"trackIndex": Integer,
"trackState": "failed",
"currentTime": Integer,
"errorCode": Number // プラットフォーム定義の数値エラー
}
event.sourceの詳細についてはイベントソースを参照してください。
onTrackFailイベントハンドラーは高速モードで実行されます。
ハンドラーは以下のシナリオで実行されます。
-
ビデオプレーヤーが再生する最初のトラックの読み込みに失敗した場合、または最初のトラックのメディアコンテンツの形式が誤っているか、サポートされない場合。再生は開始されず、ビデオプレーヤーが自動で次のトラックに進むことはありません。
このシナリオでは、
onTrackFailが以下のイベントを生成します。"event": { "source": { "type": "Video", "handler": "TrackFail", ... // コンポーネントのソースプロパティ }, "trackIndex": 0, "trackState": 'failed', "currentTime": 0, "errorCode": Number } -
ビデオプレーヤーが読み込みに失敗したトラックに進んだ場合、または形式が誤っているか、サポートされない場合。
このシナリオでは、
onTrackFailがonTrackUpdateの後に実行されます。たとえば、ビデオプレーヤーが無効な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
Container内でのビデオのサイズを調整します。
| 名前 | 説明 |
|---|---|
| best-fill | 画面の端を切らずにContainerいっぱいに表示されるよう、ビデオのサイズが調整されます。ビデオとContainerのアスペクト比が異なる場合、ビデオの上下または左右の端が表示されません。 |
| best-fit | Container内に収まるよう、ビデオのサイズが調整されます。ビデオとContainerのアスペクト比が異なる場合、黒帯状の画像がビデオの左右または上下の端に表示されます。 |
source
再生するビデオクリップまたはビデオクリップシーケンスを指定します。sourceプロパティはプレーンURL（文字列）かソースデータ配列になります。
配列に複数のビデオがある場合、プレーヤーは各ビデオを順に再生します。Videoコンポーネントの sourceプロパティと各ソースのurlプロパティは「配列化」のルールに従います。urlプロパティの場合、urlプロパティのあるオブジェクトのほかに、プレーンテキスト形式の文字列を単一URLとして指定することができます。
以下の例の各行は、sourceプロパティの有効な設定方法を示しています。
"source": URL
"source": [ URL ]
"source": { "url": URL }
"source": [ { "url": URL } ]
"source": [ URL1, { "url": URL2 } ]
メディアソースを指定する最も一般的な方法は、定義を完全に拡張することです。
"source": [
{
"description": "再生する最初のビデオクリップです",
"offset": 150, // 最初の150ミリ秒をスキップします
"url": URL1,
},
{
"description": "再生する2番目のビデオクリップです",
"url": URL2,
"repeatCount": -1 // 永久に繰り返します
},
{
"description": "このビデオは、コマンドからのみ操作できます",
"url": URL3
}
]
以下の最小限の定義は、前述の定義と同じです。
"source": [
{
"offset": 150, // 最初の150ミリ秒をスキップします
"url": URL1,
},
{
"url": URL2,
"repeatCount": -1 // 永久に繰り返します
},
URL3
]
sourceがデータ配列の場合、次のような構造になります。
| プロパティ | 型 | デフォルト | 説明 |
|---|---|---|---|
|
|
文字列 |
"" |
このソースの任意の説明です。 |
|
|
数値 |
none |
再生時間です。ゼロまたは負の場合、ストリーム全体を再生します。ミリ秒単位で設定します。 |
|
|
URL |
必須 |
メディアのソースです。 |
|
|
整数 |
0 |
ビデオをループさせる回数です。 |
|
|
エンティティの配列 |
[] |
このメディアをAlexaに報告する際に設定するエンティティデータです。 |
|
|
数値 |
0 |
補正値を指定し、ストリームの中でその場所から再生を開始します。 |
duration
ミリ秒単位の再生時間です。ビデオ全体を再生するように設定しないでください。実際のメディアクリップよりも短い時間に設定すると、ビデオプレーヤーは指定した時間だけ再生して停止します。durationを実際のメディアクリップよりも長い時間に設定しても、再生時間は追加されません。durationがゼロ以下の場合、ビデオプレーヤーはメディアクリップ全体を再生します。
url
メディアソースのURLです。https URLにする必要があります。Viewportのvideoプロパティを確認して、サポートされている形式を判断します。
repeatCount
このメディアの再生を繰り返す回数です。デフォルトは0です。つまり、一回通して再生したら停止となります。-1に設定した場合、ビデオは永久に繰り返されます。
offset
メディアの開始点からのoffsetであり、この場所から再生を開始します。ミリ秒で指定します。デフォルトは0です。つまり、メディアの開始点から再生が始まります。ビデオのrepeatCount値が正の場合、毎回同じ補正値でメディアが再生されます。
ビデオの状態
ビデオプレーヤーには、以下の表に記載された値を持つ公開状態があります。
| プロパティ | 型 | 説明 |
|---|---|---|
|
|
整数 |
ソース配列の現在のトラックです。0ベースのインデックスです。 |
|
|
整数 |
ソース配列のトラック合計数です。 |
|
|
|
現在のトラックの状態です。 |
|
|
整数 |
現在のトラックの現在の再生位置（ミリ秒単位）です。 |
|
|
整数 |
現在のトラックの長さ（ミリ秒単位）です。長さが不明の場合は |
|
|
ブール値 |
ビデオが一時停止状態の場合はTrueです。 |
|
|
ブール値 |
すべてのビデオトラックが再生を終了した場合はTrueです。 |
ビデオイベントハンドラーは、これらの状態をeventプロパティの別々のプロパティとして公開します。
以下の例は、ビデオが再生を開始したときにビデオの再生に関する情報を添えてスキルにリクエストを送信する方法を示しています。以下のonPlayハンドラーはSendEventコマンドを実行し、argumentsにeventプロパティを含みます。
{
"onPlay": {
"type": "SendEvent",
"arguments": [
"トラックインデックスは${event.trackIndex}です",
"トラック数は${event.trackCount}です",
"トラックのメディア状態は${event.trackState}です",
"現在の再生位置は${event.currentTime}ミリ秒です",
"トラックの長さは${event.duration}です",
"再生は${event.paused ? '一時停止中' : '実行中'}です",
"再生は終了${event.ended ? 'しました' : 'していません'}"
]
}
}
以下の例は、スキルが受け取るUserEventリクエストを示しています。リクエストのargumentsプロパティには、コマンドのargumentsプロパティで指定されたビデオ再生データが含まれています。
{
"request": {
"type": "Alexa.Presentation.APL.UserEvent",
"requestId": "amzn1.echo-api.request.1",
"timestamp": "2021-09-16T23:29:52Z",
"locale": "ja-JP",
"arguments": [
"トラックインデックスは0です",
"トラック数は3です",
"トラックのメディア状態はreadyです",
"現在の再生位置は0ミリ秒です",
"トラックの長さは32439です",
"再生は実行中です",
"再生は終了していません"
],
"components": {},
"source": {
"type": "Video",
"handler": "Play",
"id": "videoPlayerId"
},
"token": "videoHandlersExampleToken"
}
}
trackState
現在のトラックまたはメディアソースの状態を示す値を返します。
| 状態 | 説明 |
|---|---|
|
|
トラックの初期状態またはデフォルト状態です。この状態のときは、再生を開始できません。 |
|
|
トラックの準備が完了し、再生を開始できます。 |
|
|
トラックが失敗し、再生の開始または現在の再生位置からの続行ができません。 |
サンプルビデオ
{
"type": "Video",
"source": URL,
"autoplay": true
}
再生用インテント
音声ベースの再生操作に対応するには、 ビルトインインテントを実装する必要があります。
ビデオ再生後の音声入力を管理する
ビデオ終了後に音声入力を受け付けるには、onEndイベントハンドラーを使ってSendEventコマンドを呼び出します。スキルは、後続のUserEventリクエストを処理します。音声入力を受け入れるには、shouldEndSessionをfalseに設定してresponseを送信します。Alexaユーザーが入力を行えるように、応答には、適切なoutputSpeechオブジェクトとrepromptオブジェクトを含める必要があります。
ビデオをサポートしないデバイス
画面付きのデバイスの中にはビデオ再生をサポートしないものがあります。ビデオをサポートしていないデバイスでは、Videoコンポーネントは画面上に表示されていますが、コンテンツは表示されないため、ユーザーには画面に空白の領域が見えることになります。ビデオをサポートしていないデバイスには、別のエクスペリエンスを提供してください。
デバイスがビデオをサポートしていない場合、データバインディングコンテキストのdisallowVideoプロパティはtrueを返します。このプロパティをAPLドキュメントの条件付きロジックで使用します。
スキルコードでビデオをサポートしているかどうかを確認することもできます。スキルに送信されたリクエストのcontext.Viewport.videoプロパティを確認してください。
最終更新日: 2022 年 08 月 12 日