AudioPlayerインターフェースのリファレンス
AudioPlayer
インターフェースは、オーディオをストリーミングしたり再生状況を監視したりするディレクティブとリクエストを提供します。スキルは、ディレクティブを送信して再生を開始したり停止したりできます。AlexaサービスはAudioPlayer
リクエストをスキルに送信し、トラックの終了間際や再生の開始時と停止時など、再生状況に関する情報を提供します。また、Alexaは、リモコンなどのハードウェアボタンや、画面付きのAlexa搭載デバイスの次へ/前へタッチコントロールに応答して、PlaybackControllerリクエストも送信します。
AudioPlayerディレクティブを使用できるようにスキルを設定する
これらのディレクティブをオーディオ再生のために使用する場合、以下を実行する必要があります。
- スキル設定時に、スキルがこのインターフェースを実装していることを示すこと。
- 開発者コンソールで、カスタム > インターフェースに移動します。
- Audio Playerオプションを有効にしてからインターフェースを保存をクリックします。必ずモデルをビルドをクリックして対話モデルを再ビルドしてください。
- オーディオの一時停止や再開に必要なビルトインインテントを実装すること。AudioPlayerインターフェースをスキルに追加すると、自動的にこれらの必要なインテントがモデルに追加されます。
AMAZON.PauseIntent
AMAZON.ResumeIntent
必須のビルトインインテントに加えて、スキルは以下に示す追加のビルトインインテントを適切に処理する必要があります。
AMAZON.CancelIntent
AMAZON.LoopOffIntent
AMAZON.LoopOnIntent
AMAZON.NextIntent
AMAZON.PreviousIntent
AMAZON.RepeatIntent
AMAZON.ShuffleOffIntent
AMAZON.ShuffleOnIntent
AMAZON.StartOverIntent
ユーザーは、スキルの呼び出し名を使用せずに、これらのビルトインインテントを呼び出すことができます(こちらを参照)。スキルが現在オーディオを再生中の場合、または最後に実行した処理がオーディオの再生である場合、これらのインテントは自動的にスキルに送信されます。こうしたインテントを想定し、エラーを返さないコードにする必要があります。
これらのインテントのいずれかがスキルに適用されないものである場合には、コードで正常に処理できるようにしてください。たとえば、コマンドがスキルに対して適切ではないことを示す応答を読み上げ機能で返す方法があります。具体的なメッセージは、スキルによって、また、ある時点でインテントが処理可能なものかどうかによって異なります。次のような例があげられます。
- ポッドキャストのスキルでは、
AMAZON.ShuffleOnIntent
インテントは、 「楽曲をシャッフルできません。」というメッセージを返す場合があります。 - プレイリストやシャッフルに未対応なバージョン1.0の音楽スキルでは、
AMAZON.ShuffleOnIntent
インテントは、 「すみません、まだ曲をシャッフルできません。」と返す場合があります。
AudioPlayer
ディレクティブを使用する場合、上記のビルトインインテントを独自のサンプル発話で拡張することはできません。再生コントロール用のビルトインインテント
スキルがPlay
ディレクティブを送信して再生を開始すると、Alexaサービスはデバイスにオーディオストリームを送信して再生させます。セッションが正常に終了すると(たとえば、true
に設定されたshouldEndSession
フラグが応答に含まれる場合)、ユーザーが以下のいずれかを実行するまで、Alexaはスキルが再生を開始したことを記憶しています。
- 別のスキルでオーディオ再生を呼び出す
- ビルトインの音楽サービスやフラッシュニュースなど、オーディオをストリーミングする別のサービスを呼び出す
- デバイスを再起動する
この間、ユーザーはスキルの呼び出し名を使用せずに、以下の再生コントロールのビルトインインテントを呼び出すことができます。
AMAZON.CancelIntent
AMAZON.LoopOffIntent
AMAZON.LoopOnIntent
AMAZON.NextIntent
AMAZON.PauseIntent
AMAZON.PreviousIntent
AMAZON.RepeatIntent
AMAZON.ResumeIntent
AMAZON.ShuffleOffIntent
AMAZON.ShuffleOnIntent
AMAZON.StartOverIntent
例として、「マイポッドキャストプレイヤー」というカスタムスキルに関する以下のシナリオを確認してください。このスキルは、PlayLatestEpisode
インテントを「最新のエピソードを再生して」というサンプル発話にマッピングして定義しています。
ユーザー: アレクサ、マイポッドキャストプレイヤーで最新のエピソードを再生して。
Alexaはスキルの新しいセッションを開き、マイポッドキャストプレイヤースキルに通常どおりPlayLatestEpisode
インテントを送信します。
マイポッドキャストプレイヤーはPlay
ディレクティブを送信します。スキルのセッションが終了し、オーディオの再生が開始されます。
ユーザー: アレクサ、次。(呼び出し名がないことに注意)
Alexaはスキルの新しいセッションを開き、マイポッドキャストプレイヤースキルにAMAZON.NextIntent
を送信します。
マイポッドキャストプレイヤーは、「次」に対して適切なアクションを実行し、スキルのセッションを終了します。
ユーザー: アレクサ、一時停止して。(今度も呼び出し名なし)
Alexaはスキルの新しいセッションを開き、スキルにAMAZON.PauseIntent
を送信します。
マイポッドキャストプレイヤーはStop
ディレクティブを送信し、スキルのセッションを終了します。オーディオは停止します。
この時点でオーディオは中断され、現在実行されているセッションはありませんが、Alexaサービスは引き続きマイポッドキャストプレイヤーを、最近オーディオをストリーミングしたスキルとしてトラッキングしています。デバイスがオンのままで、ユーザーが他のオーディオストリーミングのスキルやサービスを使用しない場合、それ以降はどの時点でも以下が発生する可能性があります。
ユーザー: アレクサ、再開して。(呼び出し名がないことに注意)
Alexaはスキルの新しいセッションを開き、マイポッドキャストプレイヤーにAMAZON.ResumeIntent
を送信します。
マイポッドキャストプレイヤーは適切なアクションを実行して、以前に再生していたトラックを判断し、新しいPlay
ディレクティブを送信して再生を再開します。
これは、ビルトインインテントの場合にのみ可能です。定義されたインテント(たとえばPlayLatestEpisode
インテントなど)は、通常の呼び出しフレーズを使用して呼び出す必要があります。
AMAZON.StopIntent
の代わりにAMAZON.PauseIntent
がスキルに送信されます。画面付きのAlexa搭載デバイス用AudioPlayer
以下のセクションでは、オーディオスキルの表示の仕方と、画面付きのAlexa搭載デバイスで使用されたときの動作について説明します。
これには Display
インターフェースを含める必要がないことに注意してください。画面付きのデバイスは、自動的に音声再生を処理します。
AudioPlayerのカスタムおよびデフォルトの画面
画面付きのAlexa搭載デバイスでは、AudioPlayerは画面表示されます。Play
ディレクティブを送信する際に、アルバムアート、背景画像、トラックタイトル、サブタイトルを任意に設定できます。このとき、デバイスには以下のようなメタデータが表示されます。メタデータが設定されていない場合、無地の背景とスキル名だけのデフォルトのPlayerが表示されます。
設定できるメタデータの詳細については、Play
ディレクティブのaudioItem.metadata
プロパティを参照してください。
ユーザーがデバイスの画面をタッチすると、AudioPlayerの画面にはタッチコントロール(次へ、前へ、一時停止)が表示されます。Echo ShowとEcho Spotの場合は以下のように表示されます。Fire TV Cubeもサポートされています。
Echo Show | Echo Spot |
---|---|
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
AudioPlayerとタッチコントロール
スキルがオーディオをストリーミング中にユーザーがデバイスの画面をタッチすると、オーディオタッチコントロールが数秒間表示されます。次へ、前へ、一時停止です。
次へ、前へ、再生コントローラーは、実際のリモコンのように動作し、スキルにそれぞれのリクエストを送信します。
PlaybackController.NextCommandIssued
PlaybackController.PreviousCommandIssued
PlaybackController.PlayCommandIssued
これらのリクエストをスキルで適切に処理する必要があります。
一時停止コントロールは、スキルにリクエストを送信せずに自動で再生を停止します。ただし、他のデバイス(実際のリモコンなど)はこれらのリクエストを送信するため、スキルもPlaybackController.PauseCommandIssued
を処理します。
AudioPlayerディレクティブ
AudioPlayer
では、以下のディレクティブが提供されています。
ディレクティブ | 説明 |
---|---|
AudioPlayer.Play |
Alexaにコマンドを送信して、指定されたaudioItem で識別されたオーディオファイルをストリーミングします。 |
AudioPlayer.Stop |
現在再生中のオーディオストリームを停止します。 |
AudioPlayer.ClearQueue |
オーディオストリームのキューをすべて削除します。 |
応答にディレクティブを含める場合、送信するディレクティブにtype
プロパティを設定します。応答のdirectives
配列にディレクティブを含めます。
{
"type": "AudioPlayer.Play",
"playBehavior": "ENQUEUEなどの有効なplayBehavior値",
"audioItem": {
"stream": {
"url": "https://cdn.example.com/url-of-the-stream-to-play",
"token": "このストリームを表すopaqueトークンです",
"expectedPreviousToken": "前のストリームを表すopaqueトークンです",
"offsetInMilliseconds": 0,
"captionData": {
"content": "WEBVTT\n\n00:00.000 --> 00:02.107\n<00:00.006>この<00:00.0192>オーディオの <00:01.232>キャプションです\n",
"type": "WEBVTT"
}
},
"metadata": {
"title": "表示するトラックのタイトル",
"subtitle": "表示するトラックのサブタイトル",
"art": {
"sources": [
{
"url": "https://cdn.example.com/url-of-the-album-art-image.png"
}
]
},
"backgroundImage": {
"sources": [
{
"url": "https://cdn.example.com/url-of-the-background-image.png"
}
]
}
}
}
}
完全な応答の形式については、応答の形式を参照してください。
LaunchRequest
またはIntentRequest
に応答する場合、応答に、AudioPlayer
ディレクティブ、およびoutputSpeech
、card
、reprompt
などの標準の応答プロパティの両方を含めることができます。たとえば、Play
ディレクティブと同じ応答にoutputSpeech
を含めると、Alexaはあらかじめ用意されたテキストを読み上げてからオーディオのストリーミングを開始します。AudioPlayer
リクエストに応答する場合のルールは異なるので、注意してください。テストページのAlexaシミュレーターにはオーディオ再生機能はありませんが、スキルI/Oセクションにはスキルから送信されるAudioPlayer
ディレクティブが表示されることに注意してください。再生されないため、Alexaシミュレーターを使用して、再生中のイベントによってトリガーされるPlaybackNearlyFinished
などのAudioPlayer
リクエストをテストすることはできません。
AudioPlayerリクエスト
AudioPlayer
は以下のリクエストを送信し、再生状況の変更についてスキルに通知します。
リクエストタイプ | 説明 |
---|---|
AudioPlayer.PlaybackStarted |
Play ディレクティブで以前に送信されたオーディオストリームの再生をAlexaが開始すると、スキルに送信されます。これにより、スキルは再生が正常に開始したことを確認できます。 |
AudioPlayer.PlaybackFinished |
Alexaが再生しているストリームが終了すると、送信されます。 |
AudioPlayer.PlaybackStopped |
音声リクエストやAudioPlayer ディレクティブに対応して、Alexaがオーディオストリームの再生を停止したときに送信されます。 |
AudioPlayer.PlaybackNearlyFinished |
現在再生中のストリームが終了間際で、デバイスが新しいストリームを受信する準備ができている場合に送信されます。 |
AudioPlayer.PlaybackFailed |
ストリームを再生しようとしているときに、Alexaにエラーが発生した場合に送信されます。 |
session
オブジェクトを含みません。applicationId
やuserId
などの詳細を取得するには、context
オブジェクトを使用してください。{
"version": "1.0",
"context": {
"System": {
"application": {},
"user": {},
"device": {}
}
},
"request": {
"type": "AudioPlayer.PlaybackStarted",
"requestId": "amzn1.echo-api.request.aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"timestamp": "2018-04-11T15:15:25Z",
"token": "1234AAAABBBBCCCCCDDDDEEEEEFFFF",
"offsetInMilliseconds": 0,
"locale": "ja-JP"
}
}
完全なリクエストの形式については、リクエストの形式を参照してください。
AudioPlayer
リクエストに応答する場合、AudioPlayer
ディレクティブでしか応答できません。応答には、outputSpeech
などの標準のプロパティはいずれも含めることができません。また、Play
を許可しないなど、使用できるディレクティブを制限するリクエストもあります。サポートされていないプロパティを含む応答を送信すると、エラーが発生します。各リクエストの制限については、この後に示す各リクエストタイプの詳細を参照してください。また、AudioPlayer
リクエストに対して、サービスは応答を返す必要がないことにも注意してください。
Playディレクティブ
Alexaにコマンドを送信して、指定されたaudioItem
で識別されたオーディオファイルをストリーミングします。playBehavior
パラメーターを使用して、ストリームの再生を今すぐ開始するか、キューに追加するかを判断します。
Play
ディレクティブは1つだけです。Play
ディレクティブを送信するときは、通常、応答オブジェクトのshouldEndSession
フラグをtrue
に設定してセッションを終了します。このフラグをfalse
に設定すると、Alexaはストリームを再生するためにデバイスに送信し、その後すぐにストリームを一時停止して、ユーザーの応答を待ちます。
{
"type": "AudioPlayer.Play",
"playBehavior": "ENQUEUEなどの有効なplayBehavior値",
"audioItem": {
"stream": {
"url": "https://cdn.example.com/url-of-the-stream-to-play",
"token": "このストリームを表すopaqueトークンです",
"expectedPreviousToken": "前のストリームを表すopaqueトークンです",
"offsetInMilliseconds": 0,
"captionData":{
"content": "WEBVTT\n\n00:00.000 --> 00:02.107\n<00:00.006>この<00:00.0192>オーディオの <00:01.232>キャプションです\n",
"type": "WEBVTT"
}
},
"metadata": {
"title": "表示するトラックのタイトル",
"subtitle": "表示するトラックのサブタイトル",
"art": {
"sources": [
{
"url": "https://cdn.example.com/url-of-the-album-art-image.png"
}
]
},
"backgroundImage": {
"sources": [
{
"url": "https://cdn.example.com/url-of-the-background-image.png"
}
]
}
}
}
}
パラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
|
|
◯ |
|
再生動作を説明します。有効な値は以下のとおりです。
|
|
◯ |
|
再生するオーディオストリームに関する情報を提供するオブジェクトが含まれています。 |
|
◯ |
|
再生するオーディオストリームを表すオブジェクトが含まれています。 |
|
◯ |
|
ポート443のリモート |
|
◯ |
|
オーディオストリームを表すopaqueトークンです。このトークンは、1024文字以内でなければなりません。このトークンはストリームを識別します。 このトークンが使用された場合の例:
|
|
◯ |
|
前のストリームと思われるストリームを表すopaqueなトークンです。これは前のストリームの このプロパティは、 |
|
◯( |
|
ストリームで、Alexaが再生を開始するポイントのタイムスタンプです。最初からストリームを再生する場合は0に設定します。他の値に設定すると、ストリームの指定の位置から再生を開始します。 |
|
◯ |
|
|
|
✕ |
|
contentフィールド内の文字列の形式。サポートされている形式: WEBVTT |
|
✕ |
|
時刻をエンコードしたキャプションテキスト。サポートされている形式: WEBVTT |
|
✕ |
|
オーディオに関するメタデータを設定するオブジェクトを含めて、画面付きのAlexa搭載デバイスに表示します。このメタデータはデバイスでのみ表示されることに注意してください。Alexaアプリには表示されません。 このオブジェクトを含めない場合、スキルはデフォルトのオーディオ画面を使用し、スキル名とグレーの背景のみを表示します。 このオブジェクトはオプションです。ただし、 新しいメタデータ項目を、それぞれ異なる 画面付きのAlexa搭載デバイス用画像ガイドラインを参照してください。 メタデータは、 |
|
✕ |
|
表示するタイトルテキストです。通常、これはオーディオトラックのタイトルに使用されます。 |
|
✕ |
|
カテゴリーやアーティスト名など、表示するサブタイトルテキストです。 |
|
✕ |
|
表示するアルバムアートを表す画像オブジェクトです。このオブジェクトは、Displayインターフェーステンプレートで使用される画像と同じ形式を使用します。 Echo ShowまたはFire TV Cubeでは、小さい正方形の画像になります。Echo Spotでは、円形にトリミングされて背景として表示されます。 意図したとおりに設定するには、画像についてのガイドラインと仕様書に従ってください。 |
✕ |
|
|
表示する背景画像を表す画像オブジェクトです。このオブジェクトは、Displayインターフェーステンプレートで使用される画像と同じ形式を使用します。 Echo ShowまたはFire TV Cubeでは、これは画面全体の背景画像になります。この画像はEcho Spotでは使用されません。 意図したとおりに設定するには、画像についてのガイドラインと仕様書に従ってください。 注:
AudioPlayer スキルの背景画像は、レンダリング前に自動カラーオーバーレイを取得します。カラーは、スキルで使用されるアルバムカバーの色から取得されます。現在、色合いを取り除くことはできません。 |
✕ |
オーディオストリームの要件
audioItem.stream.url
プロパティで指定するURLは、これらの要件を満たす必要があります。
- オーディオファイルは、インターネットにアクセス可能なポート443の
HTTPS
エンドポイント側でホスティングされる必要があります。 - ウェブブラウザは有効で信頼できるSSL証明書を実装している必要があります。自己署名証明書は許可されていません。これは、多くのコンテンツホスティングサービスで提供されています。たとえば、Amazon Simple Storage Service(Amazon S3)(Amazon Web Servicesが提供)などのサービスでファイルをホストできます。
- ストリームが追加のストリームを参照するプレイリストコンテナである場合、プレイリスト内の各ストリームは、443のインターネットアクセス可能な
HTTPS
エンドポイントで、有効で信頼できるSSL証明書を使用してホストされている必要があります。
サポートされているオーディオファイルのフォーマットは、AAC/MP4、MP3、PLS、M3U/M3U8、HLSなどです。ビットレート: 16kbps~384kbps
ENQUEUEの場合のプレイリストの進行状況
audioItem.stream.expectedPreviousToken
プロパティは、プレイリストの進行とトラックの変更のリクエストが同時に発生する状況に対処するためにplayBehavior
をENQUEUE
にした場合は、必須になります。audioItem.stream.expectedPreviousToken
の値は、前のストリームで提供されたaudioItem.stream.token
プロパティと一致している必要があります。
例:
- 複数のトラックがある1つのプレイリストで、スキルがトラック2をストリーミングしています。
- ユーザーが「アレクサ、戻って。」と言うと、
AMAZON.PreviousIntent
が送信されます。 - ほぼ同時に、トラック2が終了間際であるためAlexaが
PlaybackNearlyFinished
リクエストを送信します。 - スキルはまず
AMAZON.PreviousIntent
を処理して、トラック1の新しいPlay
ディレクティブを送信します。するとトラック1の再生が開始されます。すでに送信済みのPlaybackNearlyFinished
リクエストは、トラック2が再生されていることを前提としていたため、すでに古くなっています。 - スキルはこの古くなっている
PlaybackNearlyFinished
リクエストを処理して、最初に再生していたトラック2の次のトラックであるトラック3のPlay
ディレクティブを送信します。このリクエストには、トラック2に設定されたexpectedPreviousToken
が含まれています。 - ディレクティブ内のこの
expectedPreviousToken
は、いま再生しているストリームのtoken
と一致しないため、デバイスはこのディレクティブを無視します。 - トラック1が終了すると、Alexaは
PlaybackNearlyFinished
リクエストを送信します。スキルはトラック2のPlay
ディレクティブで応答します。トラック1が終了すると、このトラックの再生が開始します。
このチェックが行われない場合、ステップ5で送信されたディレクティブはキューにトラック3を配置し、トラック1終了時にトラック1からトラック3にオーディオがスキップされることになります。
playBehavior
が他の値(REPLACE_ALL
またはREPLACE_ENQUEUED
)になっている場合にaudioItem.stream.expectedPreviousToken
を含めると、エラーが発生します。画面付きのAlexa搭載デバイス用画像ガイドライン
audioItem.metadata.art
プロパティとaudioItem.metadata.backgroundImage
プロパティに画像を設定する場合、以下のガイドラインに注意してください。
- 新しいメタデータを含むトラックを送信する場合は、トラックの
audioItem.stream.token
プロパティも必ず変更してください。 audioItem.metadata.art
については、正方形の画像を使用することをお勧めします。画像が正方形でない場合、デバイスに不要な黒い空白が表示されます。Echo Spotでは画像が円形にトリミングされることに注意してください。- この画像は、
Display
インターフェースディレクティブで使用される画像と同じ要件に従っている必要があります。唯一の違いは、推奨されている最小サイズが以下になっていることです。 - 以下の推奨最小サイズに設定すれば、画像が拡大されることはありません。それよりも小さい画像を設定すると、デバイスはその画像を拡大するので、画像がぼやけてしまう可能性があります。
Image
オブジェクトを使用すれば、source
配列に複数の画像URLを設定できます。Displayインターフェースを使用すると、デバイスでは最高解像度で画像が表示されます。Image
オブジェクトの特定の画像のsource
に関する以下のプロパティは、オーディオの背景画像とアルバムアートを表示するときには使用されないため、オブジェクトに含める必要はありません。contentDescription
size
widthPixels
heightPixels
Play
ディレクティブ内のaudioItem.stream.token
によって識別されます。特定のaudioItem.stream.token
に関連するメタデータは、最大5日間Alexaサービスにキャッシュされる可能性があるため、メタデータの変更(別の画像や、タイトルテキストの変更など)はすぐにデバイスに反映されない場合があることに注意してください。たとえば、同じオーディオストリームについて別の画像やタイトルテキストを試しながらテストしているときに、このような現象が発生する場合があります。そのときは、別のaudioItem.stream.token
の新しいPlay
ディレクティブを送信してキャッシュを削除できます。画面付きのAlexa搭載デバイスで使用される画像の推奨最小サイズは以下の表のとおりです。
画像 | 推奨最小サイズ | Echo Show/Fire TV Cube | Echo Spot |
---|---|---|---|
アート画像( |
480 x 480ピクセル |
300 x 300に拡大され、アルバムアートとして表示されます。 |
480 x 480に拡大され、円形にトリミングされ、不透明度70%の黒い画面で背景画像として表示されます。 |
背景画像( |
1024 x 640ピクセル |
1024 x 640に拡大され、背景画像として表示されます。画像はEcho ShowまたはFire TV Cubeにそのまま表示されるため、必要があればソース画像にフェード効果を適用してください。たとえば、画像に不透明度70%の黒いレイヤーをかぶせて画像をフェードしたように見せ、テキストを目立たせることができます。 |
使用しません。 |
Stopディレクティブ
現在のオーディオ再生を停止します。
{
"type": "AudioPlayer.Stop"
}
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
type |
AudioPlayer.Stop に設定します |
文字列 |
◯ |
ClearQueueディレクティブ
オーディオ再生のキューを削除します。このディレクティブを設定して、現在再生中のストリームを停止せずにキューを削除したり、キューを削除して現在再生中のストリームを停止したりできます。
{
"type": "AudioPlayer.ClearQueue",
"clearBehavior" : "CLEAR_ALLなどの有効なclearBehavior値"
}
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
|
|
◯ |
|
キューを削除する動作を説明します。有効な値は以下のとおりです。
|
|
◯ |
PlaybackStartedリクエスト
Play
ディレクティブで以前に送信されたオーディオストリームの再生をAlexaが開始すると、スキルに送信されます。これにより、スキルは再生が正常に開始したことを確認できます。
このリクエストは、Alexaが音声リクエストのために再生を一時停止し、その後再開したときにも送信されます。
{
"type": "AudioPlayer.PlaybackStarted",
"requestId": "unique.id.for.the.request",
"timestamp": "次の形式のリクエストのタイムスタンプ: 2018-04-11T15:15:25Z",
"token": "現在再生中のストリームを表すトークンです",
"offsetInMilliseconds": 0,
"locale": "en-USなどのロケールコード"
}
パラメーター
パラメーター | 説明 | 型 |
---|---|---|
type |
AudioPlayer.PlaybackStarted |
文字列 |
requestId |
特定のリクエストの固有IDを表します。 | 文字列 |
timestamp |
ISO 8601形式で表された文字列で、Alexaがリクエストを送信した日時を提供します。スキルをウェブサービスとしてホスティングしているときに、リクエストを検証するために使用されます。 | 文字列 |
token |
オーディオストリームを表すopaqueトークンです。Play ディレクティブを送信するときに、このトークンを提供します。 |
文字列 |
offsetInMilliseconds |
PlaybackStarted リクエストが送信された時点のトラックのオフセットをミリ秒単位で指定します。 |
長整数 |
locale |
ユーザーのロケールを示す文字列 です。例:en-US 。サポートされているロケールコードを参照してください。 |
string |
完全なリクエストの形式については、リクエストの形式を参照してください。
有効な応答タイプ
スキルは、PlaybackStarted
に対してStop
またはClearQueue
ディレクティブで応答できます。
応答に以下を含めることはできません。
outputSpeech
、card
、reprompt
などの標準のプロパティ。- 他の任意の
AudioPlayer
ディレクティブ。 - Dialogディレクティブなど、他のインターフェースからの他のディレクティブ。
PlaybackFinishedリクエスト
Alexaが再生しているストリームが終了すると、送信されます。
{
"type": "AudioPlayer.PlaybackFinished",
"requestId": "unique.id.for.the.request",
"timestamp": "次の形式のリクエストのタイムスタンプ: 2018-04-11T15:15:25Z",
"token": "現在再生中のストリームを表すトークンです",
"offsetInMilliseconds": 0,
"locale": "en-USなどのロケールコード"
}
パラメーター
パラメーター | 説明 | 型 |
---|---|---|
type |
AudioPlayer.PlaybackFinished |
文字列 |
requestId |
特定のリクエストの固有IDを表します。 | 文字列 |
timestamp |
ISO 8601形式で表された文字列で、Alexaがリクエストを送信した日時を提供します。スキルをウェブサービスとしてホスティングしているときに、リクエストを検証するために使用されます。 | 文字列 |
token |
オーディオストリームを表すopaqueトークンです。Play ディレクティブを送信するときに、このトークンを提供します。 |
文字列 |
offsetInMilliseconds |
PlaybackFinished リクエストが送信された時点のトラックのオフセットをミリ秒単位で指定します。 |
長整数 |
locale |
ユーザーのロケールを示す文字列 です。例:en-US 。サポートされているロケールコードを参照してください。 |
文字列 |
有効な応答タイプ
スキルは、PlaybackFinished
に対してStop
またはClearQueue
ディレクティブで応答できます。
応答に以下を含めることはできません。
outputSpeech
、card
、reprompt
などの標準のプロパティ。- 他の任意の
AudioPlayer
ディレクティブ。 - Dialogディレクティブなど、他のインターフェースからの他のディレクティブ。
PlaybackStoppedリクエスト
以下のAudioPlayer
ディレクティブのいずれかに応答して、Alexaがオーディオストリームの再生を停止したときに送信されます。
Stop
Play
とREPLACE_ALL
のplayBehavior
ClearQueue
とCLEAR_ALL
のclearBehavior
ユーザーがAlexaに音声リクエストをした場合にも再生が一時停止になるので、このリクエストが送信されます。この場合、音声対話が完了すると、再生が自動的に開始されます。
PlaybackStopped
の代わりにPlaybackFinished
を送信します。{
"type": "AudioPlayer.PlaybackStopped",
"requestId": "unique.id.for.the.request",
"timestamp": "次の形式のリクエストのタイムスタンプ: 2018-04-11T15:15:25Z",
"token": "現在再生中のストリームを表すトークンです",
"offsetInMilliseconds": 0,
"locale": "en-USなどのロケールコード"
}
パラメーター
パラメーター | 説明 | 型 |
---|---|---|
type |
AudioPlayer.PlaybackStopped |
文字列 |
requestId |
特定のリクエストの固有IDを表します。 | 文字列 |
timestamp |
ISO 8601形式で表された文字列で、Alexaがリクエストを送信した日時を提供します。スキルをウェブサービスとしてホスティングしているときに、リクエストを検証するために使用されます。 | 文字列 |
token |
オーディオストリームを表すopaqueトークンです。Play ディレクティブを送信するときに、このトークンを提供します。 |
文字列 |
offsetInMilliseconds |
PlaybackStopped リクエストが送信された時点のトラックのオフセットをミリ秒単位で指定します。 |
長整数 |
locale |
ユーザーのロケールを示す文字列 です。例:en-US 。サポートされているロケールコードを参照してください。 |
文字列 |
有効な応答タイプ
スキルは、PlaybackStopped
に応答を返すことはできません。
PlaybackNearlyFinishedリクエスト
デバイスが、次のストリームをキューに追加する準備ができている場合に送信されます。
オーディオストリームのプレイリストを次に進めるには、このリクエストに対して次のストリームのPlay
ディレクティブで応答し、ENQUEUE
またはREPLACE_ENQUEUED
にplayBehavior
を設定します。これにより、現在の再生を停止することなく、キューに新しいストリームを追加できます。Alexaは、現在再生中の曲が終了すると、新しいオーディオアイテムのストリーミングを開始します。
{
"type": "AudioPlayer.PlaybackNearlyFinished",
"requestId": "unique.id.for.the.request",
"timestamp": "次の形式のリクエストのタイムスタンプ: 2018-04-11T15:15:25Z",
"token": "現在再生中のストリームを表すトークンです",
"offsetInMilliseconds": 0,
"locale": "en-USなどのロケールコード"
}
パラメーター
パラメーター | 説明 | 型 |
---|---|---|
type |
AudioPlayer.PlaybackNearlyFinished |
文字列 |
requestId |
特定のリクエストの固有IDを表します。 | 文字列 |
timestamp |
ISO 8601形式で表された文字列で、Alexaがリクエストを送信した日時を提供します。スキルをウェブサービスとしてホスティングしているときに、リクエストを検証するために使用されます。 | 文字列 |
token |
現在再生中のオーディオストリームを表すopaqueトークンです。Play ディレクティブを送信するときに、このトークンを提供します。 |
文字列 |
offsetInMilliseconds |
PlaybackNearlyFinished リクエストが送信された時点のトラックのオフセットをミリ秒単位で指定します。 |
長整数 |
locale |
ユーザーのロケールを示す文字列 です。例:en-US 。サポートされているロケールコードを参照してください。 |
文字列 |
有効な応答タイプ
スキルは、PlaybackNearlyFinished
に対して、どのAudioPlayerディレクティブでも応答できます。
応答に以下を含めることはできません。
outputSpeech
、card
、reprompt
などの標準のプロパティ。- Dialogディレクティブなど、他のインターフェースからの他のディレクティブ。
PlaybackFailedリクエスト
ストリームを再生しようとしているときに、Alexaにエラーが発生した場合に送信されます。
構文
{
"type": "AudioPlayer.PlaybackFailed",
"requestId": "unique.id.for.the.request",
"timestamp": "次の形式のリクエストのタイムスタンプ: 2018-04-11T15:15:25Z",
"token": "現在再生中のストリームを表すトークンです",
"offsetInMilliseconds": 0,
"locale": "en-USなどのロケールコード",
"error": {
"type": "error code",
"message": "発生したエラーの説明"
},
"currentPlaybackState": {
"token": "エラーが発生したときに再生していたストリームを表すトークンです",
"offsetInMilliseconds": 0,
"playerActivity": "PLAYINGのように、エラーが発生したときのPlayerのステータスです"
}
}
このリクエストタイプには、request
オブジェクトのプロパティと、currentPlaybackState
オブジェクトのプロパティという、2つのtoken
プロパティが含まれています。request.token
プロパティは、再生に失敗したストリームを表します。currentPlaybackState.token
プロパティの値は、Alexaがストリームを再生していてキューの次のストリームをバッファリングしようとしたときにエラーが発生すると、異なる場合があります。この場合、currentPlaybackState.token
は正常に再生されていたストリームを表します。
パラメーター
パラメーター | 説明 | 型 |
---|---|---|
type |
AudioPlayer.PlaybackFailed |
文字列 |
requestId |
特定のリクエストの固有IDを表します。 | 文字列 |
timestamp |
ISO 8601形式で表された文字列で、Alexaがリクエストを送信した日時を提供します。スキルをウェブサービスとしてホスティングしているときに、リクエストを検証するために使用されます。 | 文字列 |
token |
Play ディレクティブから提供されるopaqueトークンで、再生に失敗したストリームを表します。 |
文字列 |
locale |
ユーザーのロケールを示す文字列 です。例:en-US 。サポートされているロケールコードを参照してください。 |
文字列 |
error |
エラー情報を持つオブジェクトが含まれています。 | オブジェクト |
error.type |
特定のタイプのエラーを識別します。各エラータイプの詳細は、以下の表に記載されています。 | 文字列 |
error.message |
デバイスで発生したエラーの説明です。 | 文字列 |
currentPlaybackState |
エラー発生時の再生アクティビティに関する詳細を提供するオブジェクトが含まれています。 | オブジェクト |
currentPlaybackState. token |
エラー発生時に再生中のオーディオストリームを表すopaqueトークンです。これは、request.token プロパティの値と異なる場合があることに注意してください。 |
文字列 |
currentPlaybackState. offsetInMilliseconds |
エラー発生時のトラックのオフセットをミリ秒単位で指定します。 | 長整数 |
currentPlaybackState. playerActivity |
エラー発生時のプレーヤーのステータスを以下のように識別します。 PLAYING 、PAUSED 、FINISHED 、BUFFER_UNDERRUN 、またはIDLE 。 |
文字列 |
エラータイプ | 説明 |
---|---|
MEDIA_ERROR_UNKNOWN |
不明なエラーが発生しました。 |
MEDIA_ERROR_INVALID_REQUEST |
リクエストが不正な形式であるとAlexaが認識しました。たとえば、不正なリクエストである、認証に失敗した、アクセス権がない、該当するものがない、などがあります。 |
MEDIA_ERROR_SERVICE_UNAVAILABLE |
AlexaがストリームのURLにアクセスできませんでした。 |
MEDIA_ERROR_INTERNAL_SERVER_ERROR |
Alexaはリクエストを受け取りましたが、適切に処理できませんでした。 |
MEDIA_ERROR_INTERNAL_DEVICE_ERROR |
デバイスで内部エラーが発生しました。 |
有効な応答タイプ
スキルは、PlaybackFailed
に対して、どのAudioPlayerディレクティブでも応答できます。
応答に以下を含めることはできません。
outputSpeech
、card
、reprompt
などの標準のプロパティ。- Dialogディレクティブなど、他のインターフェースからの他のディレクティブ。
System.ExceptionEncounteredリクエスト
AudioPlayer
リクエストに対する応答が原因でエラーが発生した場合、System.ExceptionEncountered
リクエストがスキルに送信されます。応答に含まれるディレクティブはすべて無視されます。
{
"type": "System.ExceptionEncountered",
"requestId": "unique.id.for.the.request",
"timestamp": "次の形式のリクエストのタイムスタンプ: 2018-04-11T15:15:25Z",
"locale": "en-USなどのロケールコード",
"error": {
"type": "INVALID_RESPONSEなどのエラーコード",
"message": "発生したエラーの説明"
},
"cause": {
"requestId": "エラーの原因となったリクエストの一意のID"
}
}
パラメーター
パラメーター | 説明 | 型 |
---|---|---|
type |
System.ExceptionEncountered |
文字列 |
requestId |
特定のリクエストの固有IDを表します。 | 文字列 |
timestamp |
ISO 8601形式で表された文字列で、Alexaがリクエストを送信した日時を提供します。スキルをウェブサービスとしてホスティングしているときに、リクエストを検証するために使用されます。 | 文字列 |
locale |
ユーザーのロケールを示す文字列 です。例:en-US 。サポートされているロケールコードを参照してください。 |
文字列 |
error |
エラー情報を持つオブジェクトが含まれています。 | オブジェクト |
error.type |
特定のタイプのエラー(INVALID_RESPONSE 、DEVICE_COMMUNICATION_ERROR 、INTERNAL_ERROR )を識別します。 |
文字列 |
error.message |
デバイスで発生したエラーの説明です。 | 文字列 |
cause.requestId |
エラーの原因となったリクエストのrequestId です。 |
文字列 |
有効な応答タイプ
スキルは、System.ExceptionEncountered
に応答を返すことはできません。
サービスインターフェースのリファレンス(JSON)
リクエストの形式と標準のリクエストタイプ:
インターフェース:
- Alexa.Presentation.APLインターフェース
- Alexa.Presentation.APLTインターフェース
- Alexa.Presentation.HTMLインターフェース
- AudioPlayerインターフェース(このドキュメント)
- Connectionsインターフェース
- Dialogインターフェース
- PlaybackControllerインターフェース
- VideoAppインターフェース
関連トピック
最終更新日: 2022 年 04 月 21 日