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 日