あなたのAlexaダッシュボード 設定

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

AudioPlayerインターフェースは、オーディオのストリーミングと再生のための進捗状況をモニタリングするためのディレクティブとリクエストを提供します。スキルはディレクティブを送信して、再生を開始したり停止したりできます。AlexaサービスはAudioPlayerリクエストをスキルに送信し、トラックの終了間際または再生の開始時や停止時といった、再生状況に関する情報を提供します。Alexaは、さらにリモコンなどのハードウェアのボタンに応答してPlaybackControllerリクエストも送信します。

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

例として、「My Podcast Player」というカスタムスキルに関する以下のシナリオを確認してください。このスキルは、PlayLatestEpisodeインテントを「最新のエピソードを再生して。」というサンプル発話にマッピングして定義しています。

ユーザー: 「Alexa、My Podcast Playerで最新のエピソードを再生して。」
Alexaはスキルの新しいセッションを開き、My Podcast Playerスキルに通常どおりPlayLatestEpisodeインテントを送信します。
My Podcast PlayerはPlayディレクティブを送信します。スキルのセッションが終了し、オーディオの再生が開始されます。
ユーザー: 「Alexa、次。」(呼び出し名がないことに注意)
Alexaはスキルの新しいセッションを開き、My Podcast PlayerスキルにAMAZON.NextIntentを送信します。
My Podcast Playerは、「次」に対して適切なアクションを実行し、スキルのセッションを終了します。
ユーザー: 「Alexa、一時停止して。」(再度呼び出し名なし)
Alexaはスキルの新しいセッションを開き、スキルにAMAZON.PauseIntentを送信します。
My Podcast PlayerはStopディレクティブを送信し、スキルのセッションを終了します。オーディオは停止されます。

この時点でオーディオは中断され、現在のセッションはなくなりますが、Alexaサービスは引き続きMy Podcast Playerを最近使用したスキルとしてトラッキングしています。端末がオンのままで、ユーザーが他のオーディオストリーミングのスキルやサービスを使用しない場合、タイミングを問わず以下の事項がその後発生する可能性があります。

ユーザー「Alexa、再開して。」(呼び出し名がないことに注意)
Alexaはスキルの新しいセッションを開き、My Podcast PlayerにAMAZON.ResumeIntentを送信します。
My Podcast Playerは適切なアクションを実行して、以前に再生していたトラックを判断し、新しいPlayディレクティブを送信して再生を再開します。

これは、ビルトインインテントの場合にのみ可能です。定義されたインテント(たとえばPlayLatestEpisodeインテント)は、通常の呼び出しフレーズを使用して起動する必要があります。

AudioPlayerディレクティブ

AudioPlayer では、以下のディレクティブが提供されています。

ディレクティブ 説明
AudioPlayer.Play Alexaにコマンドを送信して、指定されたaudioItemにより識別されるオーディオファイルをストリーミングします。
AudioPlayer.Stop 現在再生中のオーディオストリームを停止します。
AudioPlayer.ClearQueue オーディオストリームのキューをすべて削除します。

応答にディレクティブを含める場合、送信するディレクティブにtypeプロパティを設定します。応答のdirectives配列にディレクティブを含めます。

{
  "version": "1.0",
  "sessionAttributes": {},
  "response": {
    "outputSpeech": {},
    "card": {},
    "reprompt": {},
    "directives": [
      {
        "type": "AudioPlayer.Play",
        "playBehavior": "string",
        "audioItem": {
          "stream": {
            "token": "string",
            "url": "string",
            "offsetInMilliseconds": 0
          }
        }
      }
    ],
    "shouldEndSession": true
  }
}

完全な応答のフォーマットについては、カスタムスキル用JSONインターフェースリファレンス応答のフォーマットを参照してください。

AudioPlayerリクエスト

AudioPlayer は以下のリクエストを送信し、再生状況の変更についてスキルに通知します。

リクエストタイプ 説明
AudioPlayer.PlaybackStarted Playディレクティブで以前に送信されたオーディオストリームの再生をAlexaが開始したときにスキルに送信されます。これにより、再生が正常に開始したことをスキルが知ることができます。
AudioPlayer.PlaybackFinished Alexaが再生しているストリームが終了したときに送信されます。
AudioPlayer.PlaybackStopped 音声リクエストやAudioPlayerディレクティブに応じて、Alexaがオーディオストリームの再生を停止したときに送信されます。
AudioPlayer.PlaybackNearlyFinished 現在再生中のストリームが終了間際で、端末が新しいストリームを受信する準備ができている場合に送信されます。
AudioPlayer.PlaybackFailed ストリームを再生しようとしているときに、Alexaにエラーが発生した場合に送信されます。
{
  "version": "string",
  "context": {
    "System": {
      "application": {},
      "user": {},
      "device": {}
    }
  },
  "request": {
    "type": "AudioPlayer.PlaybackStarted",
    "requestId": "string",
    "timestamp": "string",
    "token": "string",
    "offsetInMilliseconds": 0,
    "locale": "string"
  }
}

完全なリクエストのフォーマットについては、カスタムスキル用JSONインターフェースリファレンスリクエストのフォーマットを参照してください。

また、AudioPlayerリクエストに対して、サービスは応答を返す必要がありません。

Playディレクティブ

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

Playディレクティブを送信するときは、通常、応答オブジェクトshouldEndSessionフラグをtrueに設定してセッションを終了します。このフラグをfalseに設定すると、Alexaは再生するために端末にストリームを送信し、すぐにストリームを一時停止して、ユーザーの応答を待ちます。

{
  "type": "AudioPlayer.Play",
  "playBehavior": "string",
  "audioItem": {
    "stream": {
      "url": "string",
      "token": "string",
      "expectedPreviousToken": "string",
      "offsetInMilliseconds": 0
    }
  }
}
パラメーター 説明 必須

type

AudioPlayer.Playに設定します。

string

必須

playBehavior

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

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

string

必須

audioItem

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

object

必須

audioItem.stream

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

object

必須

audioItem.stream.url

リモートのHTTPSロケーションでオーディオコンテンツの場所を特定します。

オーディオファイルは、インターネットにアクセス可能なHTTPSエンドポイント側でホストされる必要があります。 HTTPS は必須で、また自己署名証明書は使用できません。ファイルをホストするドメインは、有効で信頼できるSSL証明書を実装している必要があります。自己署名証明書は使用できません。これは、多くのコンテンツホスティングサービスで提供されています。たとえば、Amazon Simple Storage Service(Amazon S3)Amazon Web Servicesの提供)などのサービスでファイルをホストできます。

サポートされているオーディオファイルのフォーマットは、AAC/MP4、MP3、HLS、PLSやM3Uなどです。ビットレート: 16kbps~384kbps。

string

必須

audioItem.stream.token

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

string

必須

audioItem.stream.
expectedPreviousToken

想定される前のストリームを表す不透明なトークン。

このプロパティは、playBehaviorENQUEUEの場合にのみ必要であり、追加できる項目です。これは、プレイリストの進行とトラック変更のリクエストが同時に発生した場合に発生しうる競合状態を防ぐために使用されます。例:

  1. 複数のトラックからなるプレイリストのうち、トラック2をスキルがストリーミングしています。
  2. ユーザーが「Alexa、戻して。」と言うと、AMAZON.PreviousIntentが送信されます。
  3. ほぼ同時にトラック2が終わりに近づいたため、AlexaはPlaybackNearlyFinishedリクエストを送信します。
  4. スキルはAMAZON.PreviousIntentを最初に処理し、トラック1を含む新しいPlayディレクティブを送信します。このトラックの再生が開始されます。すでに送信されたPlaybackNearlyFinishedリクエストは、トラック2が再生されているという想定であったため、現状に適さなくなります。
  5. スキルは、今や古くなってしまったPlaybackNearlyFinishedリクエストを処理し、もともと再生していたトラック2の次のトラックであるトラック3を含むPlayディレクティブを送信します。このリクエストには、トラック2に設定されたexpectedPreviousTokenが含まれます。
  6. ディレクティブに含まれるexpectedPreviousTokenが、現在再生しているストリームのtokenと一致しないため、端末はこのディレクティブを無視します。
  7. トラック1が終わると、AlexaはPlaybackNearlyFinishedリクエストを送信します。スキルは、トラック2Playディレクティブで応答します。トラック1が終わり次第、このトラックの再生が開始します。

このチェックが設定されていない場合、ステップ5で送信されるディレクティブにより、トラック3がキューに追加されます。その結果、オーディオはトラック1の終了時にトラック1からトラック3へスキップします。

string

必須(playBehaviorENQUEUEの場合)

audioItem.stream. offsetInMilliseconds

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

long

必須

Stopディレクティブ

現在のオーディオ再生を停止します。

{
  "type": "AudioPlayer.Stop"
}
パラメーター 説明 必須
type 次に設定: AudioPlayer.Stop string 必須

ClearQueueディレクティブ

オーディオ再生のキューを削除します。このディレクティブを設定すると、現在再生中のストリームを停止することなくキューを削除したり、またはキューを削除して、かつ現在再生中のストリームを停止したりできます。

{
  "type": "AudioPlayer.ClearQueue",
  "clearBehavior" : "string"
}
パラメーター 説明 必須

type

AudioPlayer.ClearQueueに設定します。

string

必須

clearBehavior

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

  • CLEAR_ENQUEUED: 現在再生中のストリームを引き続き再生しながら、キューを削除します。
  • CLEAR_ALL: 現在再生中のストリームを停止して、再生キューをすべて削除します(該当する場合)。

string

必須

PlaybackStartedリクエスト

Playディレクティブで以前に送信されたオーディオストリームの再生をAlexaが開始したときにスキルに送信されます。これにより、再生が正常に開始したことをスキルが知ることができます。

このリクエストは、Alexaが音声リクエストのために再生を一時停止し、その後再開したときにも送信されます。

{
  "type": "AudioPlayer.PlaybackStarted",
  "requestId": "string",
  "timestamp": "string",
  "token": "string",
  "offsetInMilliseconds": 0,
  "locale": "string"
}

パラメーター

パラメーター 説明
type AudioPlayer.PlaybackStarted string
requestId 特定のリクエストの固有IDを表します。 string
timestamp ISO 8601形式で表された文字列で、Alexaがリクエストを送信した日時を提供します。スキルをウェブサービスとしてホスティングしている場面において、リクエストを検証するために使用されます。 string
token オーディオストリームを表す不透明なトークンです。Playディレクティブを送信するときに、このトークンを提供します。 string
offsetInMilliseconds PlaybackStartedリクエストが送信された時点のトラックのオフセットをミリ秒単位で特定します。 long
locale ユーザーのロケールを示すstringです。例: en-US string

リクエストの全フォーマットについては、カスタムスキル用JSONインターフェースリファレンスリクエストのフォーマットを参照してください。

有効な応答タイプ

スキルは、PlaybackStartedに対してStopまたはClearQueueディレクティブで応答できます。

応答に以下を含めることはできません。

  • outputSpeechcardrepromptなどの標準のプロパティ。
  • 他の任意のAudioPlayerディレクティブ。
  • Dialogディレクティブなど、他のインターフェースからの他の任意のディレクティブ。

PlaybackFinishedリクエスト

Alexaが再生しているストリームが終了したときに送信されます。

{
  "type": "AudioPlayer.PlaybackFinished",
  "requestId": "string",
  "timestamp": "string",
  "token": "string",
  "offsetInMilliseconds": 0,
  "locale": "string"
}

パラメーター

パラメーター 説明
type AudioPlayer.PlaybackFinished string
requestId 特定のリクエストの固有IDを表します。 string
timestamp ISO 8601形式で表された文字列で、Alexaがリクエストを送信した日時を提供します。スキルをウェブサービスとしてホスティングしている場面において、リクエストを検証するために使用されます。 string
token オーディオストリームを表す不透明なトークンです。Playディレクティブを送信するときに、このトークンを提供します。 string
offsetInMilliseconds PlaybackFinishedリクエストが送信された時点のトラックのオフセットをミリ秒単位で特定します。 long
locale ユーザーのロケールを示すstringです。例: en-US string

有効な応答タイプ

スキルは、PlaybackFinishedに対してStopまたはClearQueueディレクティブで応答できます。

応答に以下を含めることはできません。

  • outputSpeechcardrepromptなどの標準のプロパティ。
  • 他の任意のAudioPlayerディレクティブ。
  • Dialogディレクティブなど、他のインターフェースからの他の任意のディレクティブ。

PlaybackStoppedリクエスト

以下のAudioPlayerディレクティブのいずれかに応じて、Alexaがオーディオストリームの再生を停止したときに送信されます。

  • Stop
  • PlayREPLACE_ALLplayBehavior
  • ClearQueueCLEAR_ALLclearBehavior

このリクエストは、ユーザーがAlexaへ音声リクエストを行った場合にも、再生が一時停止するため送信されます。この場合、音声対話が完了すると、再生が自動的に開始されます。

{
  "type": "AudioPlayer.PlaybackStopped",
  "requestId": "string",
  "timestamp": "string",
  "token": "string",
  "offsetInMilliseconds": 0,
  "locale": "string"
}

パラメーター

パラメーター 説明
type AudioPlayer.PlaybackStopped string
requestId 特定のリクエストの固有IDを表します。 string
timestamp ISO 8601形式で表された文字列で、Alexaがリクエストを送信した日時を提供します。スキルをウェブサービスとしてホスティングしている場面において、リクエストを検証するために使用されます。 string
token オーディオストリームを表す不透明なトークンです。Playディレクティブを送信するときに、このトークンを提供します。 string
offsetInMilliseconds PlaybackStoppedリクエストが送信された時点のトラックのオフセットをミリ秒単位で特定します。 long
locale ユーザーのロケールを示すstringです。例: en-US string

有効な応答タイプ

スキルは、PlaybackStoppedに応答を返すことはできません。

PlaybackNearlyFinishedリクエスト

端末が、次のストリームをキューに追加する準備ができている場合に送信されます。

オーディオストリームのプレイリストを進めるには、このリクエストに対して次のストリームのPlayディレクティブで応答し、ENQUEUEまたはREPLACE_ENQUEUEDplayBehaviorを設定します。これにより、現在の再生を停止することなく、キューに新しいストリームを追加できます。Alexaは、現在再生中の曲が終了すると、新しいオーディオアイテムのストリーミングを開始します。

{
  "type": "AudioPlayer.PlaybackNearlyFinished",
  "requestId": "string",
  "timestamp": "string",
  "token": "string",
  "offsetInMilliseconds": 0,
  "locale": "string"
}

パラメーター

パラメーター 説明
type AudioPlayer.PlaybackNearlyFinished string
requestId 特定のリクエストの固有IDを表します。 string
timestamp ISO 8601形式で表された文字列で、Alexaがリクエストを送信した日時を提供します。スキルをウェブサービスとしてホスティングしている場面において、リクエストを検証するために使用されます。 string
token 現在再生中のオーディオストリームを表す不透明なトークンです。Playディレクティブを送信するときに、このトークンを提供します。 string
offsetInMilliseconds PlaybackNearlyFinishedリクエストが送信された時点のトラックのオフセットをミリ秒単位で特定します。 long
locale ユーザーのロケールを示すstringです。例: en-US string

有効な応答タイプ

スキルは、PlaybackNearlyFinishedに対して、どのAudioPlayerディレクティブでも応答できます。

応答に以下を含めることはできません。

  • outputSpeechcardrepromptなどの標準のプロパティ。
  • Dialogディレクティブなど、他のインターフェースからの他の任意のディレクティブ。

PlaybackFailedリクエスト

ストリームを再生しようとしているときに、Alexaにエラーが発生した場合に送信されます。

{
  "type": "AudioPlayer.PlaybackFailed",
  "requestId": "string",
  "timestamp": "string",
  "token": "string",
  "locale": "string",
  "error": {
    "type": "string",
    "message": "string"
  },
  "currentPlaybackState": {
    "token": "string",
    "offsetInMilliseconds": 0,
    "playerActivity": "string"
  }
}

このリクエストには、それぞれrequestオブジェクトのプロパティとcurrentPlaybackStateオブジェクトのプロパティとして、2つのtokenプロパティが含まれます。request.tokenプロパティは、再生に失敗したストリームを表します。currentPlaybackState.tokenプロパティは、Alexaがストリームを再生中、キューの次のストリームをバッファリングしようとしたときに、エラーが発生すると異なるものになる場合があります。この場合、currentPlaybackState.tokenは正常に再生されていたストリームを表します。

パラメーター 説明
type AudioPlayer.PlaybackFailed string
requestId 特定のリクエストの固有IDを表します。 string
timestamp ISO 8601形式で表された文字列で、Alexaがリクエストを送信した日時を提供します。スキルをウェブサービスとしてホスティングしている場面において、リクエストを検証するために使用されます。 string
token Playディレクティブにより与えられる不透明なトークンで、再生に失敗したストリームを表します。 string
locale ユーザーのロケールを示すstringです。例: en-US string
error エラー情報を持つオブジェクトが含まれています。 object
error.type 特定のタイプのエラーを識別します。各エラータイプの詳細は、以下の表に記載されています。 string
error.message 端末で発生したエラーの説明です。 string
currentPlaybackState エラー発生時の再生アクティビティに関する詳細を提供するオブジェクトが含まれています。 object
currentPlaybackState.
token
エラー発生時に再生中のオーディオストリームを表す不透明なトークンです。これは、request.tokenプロパティの値と異なる場合があります。 string
currentPlaybackState.
offsetInMilliseconds
エラー発生時のトラックのオフセットをミリ秒単位で特定します。 long
currentPlaybackState.
playerActivity
エラー発生時のプレーヤーの状態を次のように特定します。PLAYINGPAUSEDFINISHEDBUFFER_UNDERRUN、またはIDLE string
エラータイプ 説明
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ディレクティブでも応答できます。

応答に以下を含めることはできません。

  • outputSpeechcardrepromptなどの標準のプロパティ。
  • Dialogディレクティブなど、他のインターフェースからの他の任意のディレクティブ。

System.ExceptionEncounteredリクエスト

AudioPlayerリクエストに対する応答によりエラーが発生した場合、System.ExceptionEncounteredリクエストがスキルに送信されます。応答に含まれるディレクティブはすべて無視されます。

{
  "type": "System.ExceptionEncountered",
  "requestId": "string",
  "timestamp": "string",
  "locale": "string",
  "error": {
    "type": "string",
    "message": "string"
  },
  "cause": {
    "requestId": "string"
  }
}

パラメーター

パラメーター 説明
type System.ExceptionEncountered string
requestId 特定のリクエストの固有IDを表します。 string
timestamp ISO 8601形式で表された文字列で、Alexaがリクエストを送信した日時を提供します。スキルをウェブサービスとしてホスティングしている場面において、リクエストを検証するために使用されます。 string
locale ユーザーのロケールを示すstringです。例: en-US string
error エラー情報を持つオブジェクトが含まれています。 object
error.type 特定のタイプのエラー(INVALID_RESPONSEDEVICE_COMMUNICATION_ERRORINTERNAL_ERROR)を識別します。 string
error.message 端末で発生したエラーの説明です。 string
cause.requestId エラーの原因となったリクエストのrequestIdです。 string

有効な応答タイプ

スキルは、System.ExceptionEncounteredに応答を返すことはできません。

サービスインターフェースのリファレンス(JSON)

インターフェース: