AudioPlayerインターフェースのリファレンス

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インテントは、 「すみません、まだ曲をシャッフルできません。」と返す場合があります。

再生コントロール用のビルトインインテント

スキルが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インテントなど）は、通常の呼び出しフレーズを使用して呼び出す必要があります。

画面付きの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
カスタムの背景画像、タイトル、サブタイトル、アルバムアートが設定されたAudioPlayer
カスタムのアルバムアート、タイトル、サブタイトルが設定されたAudioPlayer
カスタムのアルバムアート、タイトル、サブタイトルが設定されたAudioPlayer（Echo Spotでは同じ背景画像を使用します）
カスタムの背景画像、タイトル、サブタイトル、アルバムアートが設定されたAudioPlayer（タッチコントロールあり）
カスタムの背景画像、タイトル、サブタイトル、アルバムアートが設定されたAudioPlayer（タッチコントロールあり）
カスタムのアルバムアートが設定されたAudioPlayer（タッチコントロールが表示されている間はタイトルとサブタイトルは表示されません）
カスタムのアルバムアートが設定されたAudioPlayer（タッチコントロールが表示されている間はタイトルとサブタイトルは表示されません）
スキル名だけが表示されたデフォルトのAudioPlayer
スキル名だけが表示されたデフォルトのAudioPlayer
スキル名だけが表示されたデフォルトのAudioPlayer
スキル名だけが表示されたデフォルトのAudioPlayer
スキル名だけが表示されたデフォルトのAudioPlayer（タッチコントロールあり）
スキル名だけが表示されたデフォルトのAudioPlayer（タッチコントロールあり）
デフォルトのAudioPlayer（タッチコントロールあり）
デフォルトのAudioPlayer（タッチコントロールが表示されているときは曲名は表示されません）

AudioPlayerとタッチコントロール

スキルがオーディオをストリーミング中にユーザーがデバイスの画面をタッチすると、オーディオタッチコントロールが数秒間表示されます。次へ、前へ、一時停止です。

次へ、前へ、再生コントローラーは、実際のリモコンのように動作し、スキルにそれぞれのリクエストを送信します。

これらのリクエストをスキルで適切に処理する必要があります。

一時停止コントロールは、スキルにリクエストを送信せずに自動で再生を停止します。ただし、他のデバイス（実際のリモコンなど）はこれらのリクエストを送信するため、スキルも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"
          }
        ]
      }
    }
  }
}

完全な応答の形式については、応答の形式を参照してください。

テストページの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にエラーが発生した場合に送信されます。 
{
  "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リクエストに対して、サービスは応答を返す必要がないことにも注意してください。

Playディレクティブ

Alexaにコマンドを送信して、指定されたaudioItemで識別されたオーディオファイルをストリーミングします。playBehaviorパラメーターを使用して、ストリームの再生を今すぐ開始するか、キューに追加するかを判断します。

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"
          }
        ]
      }
    }
  }
}

パラメーター

パラメーター 説明 型 必須

type

AudioPlayer.Playに設定します。

文字列

◯

playBehavior

再生動作を説明します。有効な値は以下のとおりです。

  • REPLACE_ALL： 現在のストリームおよびキューに追加されたストリームを置き換え、指定されたストリームの再生をすぐに開始します。
  • ENQUEUE： 指定されたストリームを現在のキューの最後に追加します。これにより、現在再生中のストリームが影響を受けることはありません。
  • REPLACE_ENQUEUED： キューのストリームをすべて置き換えます。これにより、現在再生中のストリームが影響を受けることはありません。

文字列

◯

audioItem

再生するオーディオストリームに関する情報を提供するオブジェクトが含まれています。

オブジェクト

◯

audioItem.stream

再生するオーディオストリームを表すオブジェクトが含まれています。

オブジェクト

◯

audioItem.stream.url

ポート443のリモートHTTPSロケーションのオーディオコンテンツの場所を特定します。詳細については、オーディオストリームの要件を参照してください。

文字列

◯

audioItem.stream.token

オーディオストリームを表すopaqueトークンです。このトークンは、1024文字以内でなければなりません。このトークンはストリームを識別します。

このトークンが使用された場合の例：

文字列

◯

audioItem.stream.
expectedPreviousToken

前のストリームと思われるストリームを表すopaqueなトークンです。これは前のストリームのaudioItem.stream.tokenの値と一致している必要があります。

このプロパティは、playBehaviorがENQUEUEである場合にのみ追加できる必須の項目です。これは、プレイリストの進行とトラック変更のリクエストが同時に発生した場合に、発生しうる競合状態を防ぐために使用されます。詳細については、ENQUEUEの場合のプレイリストの進行状況を参照してください。

文字列

◯（playBehaviorがENQUEUEの場合）

audioItem.stream. offsetInMilliseconds

ストリームで、Alexaが再生を開始するポイントのタイムスタンプです。最初からストリームを再生する場合は0に設定します。他の値に設定すると、ストリームの指定の位置から再生を開始します。

長整数

◯

audioItem.stream. captionData

content と typeの2つのフィールドを持つオブジェクト。これらのフィールドを使用して、オーディオに関連したキャプションを対応デバイスの画面に表示します。captionData オブジェクトは、 content と typeの値が無いと表示されません。デバイスは機能APIを呼び出してAudioPlayerバージョン1.1以降をサポートできます。

object

✕

audioItem.stream .captionData.type

contentフィールド内の文字列の形式。サポートされている形式： WEBVTT

文字列

✕

audioItem.stream .captionData.content

時刻をエンコードしたキャプションテキスト。サポートされている形式： WEBVTT

文字列

✕

audioItem.metadata

オーディオに関するメタデータを設定するオブジェクトを含めて、画面付きのAlexa搭載デバイスに表示します。このメタデータはデバイスでのみ表示されることに注意してください。Alexaアプリには表示されません。

このオブジェクトを含めない場合、スキルはデフォルトのオーディオ画面を使用し、スキル名とグレーの背景のみを表示します。

このオブジェクトはオプションです。ただし、audioItem.metadataを含める場合は、4つすべてのmetadataプロパティ（タイトル、サブタイトル、アート、背景画像）を設定することをお勧めします。

新しいメタデータ項目を、それぞれ異なるaudioItem.stream.tokenと関連付けます。

画面付きのAlexa搭載デバイス用画像ガイドラインを参照してください。

メタデータは、Displayインターフェースを含めているかどうかに関係なく、画面付きのデバイスで使用されることに注意してください。

オブジェクト

✕

audioItem.metadata.title

表示するタイトルテキストです。通常、これはオーディオトラックのタイトルに使用されます。

文字列

✕

audioItem.metadata.subtitle

カテゴリーやアーティスト名など、表示するサブタイトルテキストです。

文字列

✕

audioItem.metadata.art

表示するアルバムアートを表す画像オブジェクトです。このオブジェクトは、Displayインターフェーステンプレートで使用される画像と同じ形式を使用します。

Echo ShowまたはFire TV Cubeでは、小さい正方形の画像になります。Echo Spotでは、円形にトリミングされて背景として表示されます。

意図したとおりに設定するには、画像についてのガイドラインと仕様書に従ってください。

画像オブジェクト

✕

audioItem.metadata.
backgroundImage

表示する背景画像を表す画像オブジェクトです。このオブジェクトは、Displayインターフェーステンプレートで使用される画像と同じ形式を使用します。

Echo ShowまたはFire TV Cubeでは、これは画面全体の背景画像になります。この画像はEcho Spotでは使用されません。

意図したとおりに設定するには、画像についてのガイドラインと仕様書に従ってください。

画像オブジェクト

✕

オーディオストリームの要件

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. 複数のトラックがある1つのプレイリストで、スキルがトラック2をストリーミングしています。
  2. ユーザーが「アレクサ、戻って。」と言うと、AMAZON.PreviousIntentが送信されます。
  3. ほぼ同時に、トラック2が終了間際であるためAlexaがPlaybackNearlyFinishedリクエストを送信します。
  4. スキルはまずAMAZON.PreviousIntentを処理して、トラック1の新しいPlayディレクティブを送信します。するとトラック1の再生が開始されます。すでに送信済みのPlaybackNearlyFinishedリクエストは、トラック2が再生されていることを前提としていたため、すでに古くなっています。
  5. スキルはこの古くなっているPlaybackNearlyFinishedリクエストを処理して、最初に再生していたトラック2の次のトラックであるトラック3のPlayディレクティブを送信します。このリクエストには、トラック2に設定されたexpectedPreviousTokenが含まれています。
  6. ディレクティブ内のこのexpectedPreviousTokenは、いま再生しているストリームのtokenと一致しないため、デバイスはこのディレクティブを無視します。
  7. トラック1が終了すると、AlexaはPlaybackNearlyFinishedリクエストを送信します。スキルはトラック2のPlayディレクティブで応答します。トラック1が終了すると、このトラックの再生が開始します。

このチェックが行われない場合、ステップ5で送信されたディレクティブはキューにトラック3を配置し、トラック1終了時にトラック1からトラック3にオーディオがスキップされることになります。

画面付きの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
画像 推奨最小サイズ Echo Show／Fire TV Cube Echo Spot

アート画像（audioItem.metadata.art）

480 x 480ピクセル

300 x 300に拡大され、アルバムアートとして表示されます。

480 x 480に拡大され、円形にトリミングされ、不透明度70%の黒い画面で背景画像として表示されます。

背景画像（audioItem.metadata.backgroundImage）

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値"
}
パラメーター 説明 型 必須

type

AudioPlayer.ClearQueueに設定します。

文字列

◯

clearBehavior

キューを削除する動作を説明します。有効な値は以下のとおりです。

  • CLEAR_ENQUEUED：キューを削除して、現在再生中のストリームの再生を継続します。
  • CLEAR_ALL：再生キュー全体を削除して、現在再生中のストリームを停止します（再生している場合）。

文字列

◯

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に音声リクエストをした場合にも再生が一時停止になるので、このリクエストが送信されます。この場合、音声対話が完了すると、再生が自動的に開始されます。

{
  "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）

リクエストの形式と標準のリクエストタイプ：

インターフェース：

Last updated: Apr 21, 2022