インターフェース(v1.0)AudioPlayerインターフェースでは、音声でオーディオ再生をコントロールするディレクティブや、再生の進行の管理や監視のためのイベントが提供されます。再生コントロールをボタン(物理またはGUI)にマッピングしたい場合は、PlaybackControllerインターフェースを参照してください。状態ダイアグラム機能APIAudioPlayerのコンテキストPlayディレクティブPlaybackStartedイベントPlaybackNearlyFinishedイベントProgressReportDelayElapsedイベントProgressReportIntervalElapsedイベントPlaybackStutterStartedイベントPlaybackStutterFinishedイベントPlaybackFinishedイベントPlaybackFailedイベントStopディレクティブPlaybackStoppedイベントPlaybackPausedイベントPlaybackResumedイベントClearQueueディレクティブPlaybackQueueClearedイベントStreamMetadataExtractedイベント状態ダイアグラム以下のダイアグラムは、AudioPlayerコンポーネントによって制御される状態の変化を表しています。箱はAudioPlayerの状態、コネクターは状態の遷移を示します。AudioPlayerには以下の状態があります。IDLE:AudioPlayerは、製品の電源を入れるか、再起動され、Playディレクティブに従って動作をする前にのみ、idle状態になります。PLAYING:クライアントがオーディオストリームの再生を開始すると、AudioPlayerはidle状態からplaying状態に遷移します。クライアントが、オーディオストリームの一時停止または停止などのアクションを実行するよう指示するディレクティブを受信した場合、クライアントでストリームのバッファリングに問題が生じた場合、または再生が失敗した場合は、AudioPlayerはそのアクションが実行されたときに適切な状態に遷移(およびAVSにイベントを送信)する必要があります。それ以外の場合、AudioPlayerは、現在のストリームが完了するまでplaying状態を維持する必要があります。AudioPlayerは、以下の場合にもplaying状態を維持する必要があります。AVSに対して再生の進行状況をレポートするAVSに対してストリームのメタデータを送信するSTOPPED:AudioPlayerがstopped状態に遷移する必要があるインスタンスは4つあります。playing状態にあるときに以下のイベントが発生すると、AudioPlayerはstopped状態に遷移する必要があります。ストリームに問題が検出され、再生に失敗したときクライアントが、AVSからStopディレクティブを受信したときclearBehaviorにCLEAR_ALLが指定されたClearQueueディレクティブを受信したときplayBehaviorにREPLACE_ALLが指定されたPlayディレクティブを受信したときpausedまたはbuffer_underrun状態にあるときにCLEAR_ALLにするClearQueueディレクティブを受信すると、AudioPlayerはstopped状態に遷移する必要があります。クライアントでPlayディレクティブを受信して、オーディオストリームの再生を開始し、AVSにPlaybackStartedイベントを送信するとき、AudioPlayerは必ずstopped状態からplaying状態に遷移する必要があります。PAUSED:ユーザーまたはAlexaの音声対話など、より優先度の高い音声入力/出力を処理するためにContentチャンネル上のオーディオが一時停止した場合、AudioPlayerはpaused状態に遷移する必要があります。優先度の高いアクティビティが完了したら、再生を再開する必要があります。音声入力/出力の優先順位付けの詳細については、対話モデルを参照してください。BUFFER_UNDERRUN:クライアントのデータフィードが読み上げよりも遅い場合、AudioPlayerはbuffer_underrun状態に遷移する必要があります。AudioPlayerは、再生を再開するのに十分なバッファリングが行われ、playing状態に戻るまでは、この状態を維持する必要があります。FINISHED:ストリームの再生が終了したら、AudioPlayerはfinished状態に遷移する必要があります。これは、再生キューに入っているすべてのストリームに適用されます。再生キューにまだ他のストリームが残っている場合でも、1つのストリームの再生が終了するたびに、クライアントからAVSにPlaybackFinishedイベントを送信し、続いてplaying状態からfinished状態に遷移する必要があります。以下の場合、AudioPlayerはfinished状態からplaying状態に遷移する必要があります。機能APIAudioPlayerインターフェースのバージョン1.0を使用するには、機能APIの呼び出し内で宣言する必要があります。詳細については、機能APIを参照してください。"1.0"}AudioPlayerのコンテキストAlexaは、コンテキストが必要な各イベントで、playerActivity(状態)と現在再生中のメディア項目のoffsetInMillisecondsがクライアントからレポートされることを想定しています。コンテキストのレポートの詳細については、コンテキストの概要を参照してください。これは、現在再生中のメディア項目のtokenと一致する必要があります。一致しない場合、tokenは最後に受信したPlayディレクティブで指定された項目と一致する必要があります。トラックの現在のオフセットをミリ秒で示します。AudioPlayerのコンポーネントの状態を示します。有効な値:IDLE、PLAYING、STOPPED、PAUSED、BUFFER_UNDERRUN、FINISHED。再生中または待機中のオーディオなし。ストリーミング再生中。ストリーミングを一時停止中。バッファアンダーランが発生。ストリーミングの再生を終了。ストリーミングを中断。PlayディレクティブPlayディレクティブは、オーディオ再生を開始する際にクライアントに送信されます。JSONディレクティブと、1つまでのオーディオストリームまたはバイナリのオーディオ添付ファイルで構成されるマルチパートのメッセージです。注:バイナリオーディオ添付ファイルの詳細については、こちらを参照してください。playBehaviorディレクティブのペイロードに含まれるパラメーターは、クライアントがストリームのキューイングと再生をどう処理するかを判断するのに使用できます。有効な値は、とるべきアクションのヒントを示します。REPLACE_ALL:Playディレクティブを返したストリームの再生をすぐに開始し、現在のストリームおよびキューに追加されたストリームを置き換えます。ストリームの再生中にplayBehaviorにREPLACE_ALLが指定されたPlayディレクティブを受信したら、AVSにPlaybackStoppedイベントを送信する必要があります。ENQUEUE:ストリームを現在のキューの最後に追加します。REPLACE_ENQUEUED:キューのストリームをすべて置き換えます。これにより、現在再生中のストリームが影響を受けることはありません。注:再生キューにストリームを追加するときには、現在再生中のストリームのトークンと追加しようとしているストリームのexpectedPreviousTokenが一致する必要があります。トークンとストリームが一致しない場合は無視されます。expectedPreviousTokenが返されない場合は、ストリームをキューに追加する必要があります。ディレクティブには、マルチパートのメッセージの一部として、対応するバイナリオーディオ添付ファイルが存在する場合があります。バイナリオーディオ添付ファイルが存在する場合、urlに指定される値にcidのプレフィックスが含まれます。バイナリオーディオ添付ファイルの前には、以下のマルチパートヘッダーが含まれます。特定のメッセージを表すのに使用する一意のIDです。特定のRecognizeイベントの応答として送信されるディレクティブの関連付けに使用する一意のIDです。重要:クライアントは、Playでサポートされるすべてのペイロードパラメーターを処理し、それに従って動作するよう設計する必要があります。JSONのキー/値ペアがない場合でも動作し続ける必要があります。再生のヒントを示します。有効な値:REPLACE_ALL、ENQUEUE、REPLACE_ENQUEUEDREPLACE_ALL:Playディレクティブを返したストリームの再生をすぐに開始し、現在のストリームおよびキューに追加されたストリームを置き換えます。ENQUEUE:ストリームを現在のキューの最後に追加します。REPLACE_ENQUEUED:キューのストリームをすべて置き換えます。これにより、現在再生中のストリームが影響を受けることはありません。audioItemsのキー/値ペアが含まれます。audioItemを識別します。streamのキー/値ペアが含まれます。オーディオコンテンツの場所を識別します。オーディオコンテンツがバイナリオーディオ添付ファイルの場合、値はコンテンツの一意の識別子で、"cid:"の形式で表されます。それ以外の場合、値はリモートのhttp/httpsの場所を示します。Playディレクティブが関連するバイナリオーディオ添付ファイルを持つ場合に、ペイロードに含まれます。このパラメーターは、関連するオーディオがストリームの場合には存在しません。クライアントがストリーム内のどこから再生を開始するべきかを示すタイムスタンプ。offsetInMillisecondsが0に設定されているとき、このパラメーターはストリームの0の位置、または最初から再生することを示します。それ以外の値は、指定されたオフセットから再生を開始することを示します。8601形式の日付と時刻です。進行状況レポートのキー/値ペアが含まれます。AVSにProgressReportDelayElapsedイベントを送るタイミングをミリ秒で指定します。指定されたインターバル後に1回だけ送信します。注:楽曲プロバイダーの一部には、このレポートが不要なものもあります。レポートが不要な場合、progressReportDelayInMillisecondsはペイロードに存在しません。AVSにProgressReportIntervalElapsedイベントを送るタイミングをミリ秒で指定します。指定されたインターバル後に定期的に送信します。注:楽曲プロバイダーの一部には、このレポートが不要なものもあります。レポートが不要な場合、progressReportIntervalInMillisecondsはペイロードに存在しません。現在のストリームを表す不透明なトークンです。想定される前のストリームを表す不透明なトークンです。文字列PlaybackStartedイベントPlaybackStartedイベントは、クライアントがPlayディレクティブを処理して関連するオーディオストリームの再生を開始した後、AVSに対して送信される必要があります。注:AVSが送信するURLごとに、最大1つのPlaybackStartedイベントが想定されます。プレイリストのURL(複数のURLで構成される)を受信した場合でも、送信するPlaybackStartedイベントは1つだけにしてください。特定のメッセージを表すのに使用する一意のIDです。Playディレクティブで提供される不透明なトークンです。トラックの現在のオフセットをミリ秒で示します。longPlaybackNearlyFinishedイベントPlaybackNearlyFinishedイベントは、クライアントが再生キューの次のストリームのバッファリングまたはダウンロードする準備が整ったときに送信される必要があります。クライアントでは、このイベントを現在再生中のストリームのPlaybackStartedイベントに続いてのみ送信しなければなりません。Alexaは、以下のいずれかの場合に、このイベントに応答します。204応答コードヒント:ベストプラクティスとして、PlaybackNearlyFinishedイベントをAlexaに送信する前に、前の曲をバッファリングされるまで待機することを検討します。これにより、expiryTimeを超えるリスクが低減し、ダウンロード中、複数のPlayディレクティブの同時処理中に再生の途切れが発生する頻度を減らすことができます。特定のメッセージを表すのに使用する一意のIDです。Playディレクティブで提供される不透明なトークンです。トラックの現在のオフセットをミリ秒で示します。longProgressReportDelayElapsedイベントProgressReportDelayElapsedイベントは、PlayディレクティブにprogressReportDelayInMillisecondsが存在する場合にAVSに送信される必要があります。イベントは、ストリームの最初から指定したインターバルが経過した後に1回のみ送信される必要があります(offsetInMillisecondsからではありません)。Playディレクティブに含まれるprogressReportDelayInMillisecondsの値が20000の場合、ProgressReportDelayElapsedイベントはトラックの最初から20,000ミリ秒経過した後に送信される必要があります。Playディレクティブに含まれるoffsetInMillisecondsの値が10000で、progressReportDelayInMillisecondsの値が20000の場合、イベントは再生の最初から10,000ミリ秒経過した後に送信される必要があります。これは、進行状況レポートが、Playディレクティブのオフセットではなく、ストリームの最初から起算されて送信されるためです。特定のメッセージを表すのに使用する一意のIDです。Playディレクティブで提供される不透明なトークンです。トラックの現在のオフセットをミリ秒で示します。longProgressReportIntervalElapsedイベントProgressReportIntervalElapsedイベントは、PlayディレクティブにprogressReportIntervalInMillisecondsが存在する場合にAVSに送信される必要があります。イベントは、ストリームの最初から指定したインターバルが経過した後に定期的に送信される必要があります(offsetInMillisecondsからではありません)。Playディレクティブに含まれるのprogressReportIntervalInMilliseconds値が20000の場合、ProgressReportIntervalElapsedイベントはトラックの最初から20,000ミリ秒経過した後、およびストリームの最後まで20,000ミリ秒ごとに送信される必要があります。Playディレクティブに含まれるoffsetInMillisecondsの値が10000で、progressReportIntervalInMillisecondsの値が20000の場合、イベントは再生の最初から10,000ミリ秒後、およびストリームの最後まで20,000ミリ秒ごとに送信される必要があります。これは、指定されたインターバルが、Playディレクティブのオフセットではなく、ストリームの最初から起算されるためです。特定のメッセージを表すのに使用する一意のIDです。Playディレクティブで提供される不透明なトークンです。トラックの現在のオフセットをミリ秒で示します。longPlaybackStutterStartedイベントPlaybackStutterStartedイベントは、クライアントのAudioPlayerコンポーネントのデータフィードが読み上げよりも遅い場合、PlaybackStartedイベントに続けてAVSに送信される必要があります。コンポーネントは、このイベントが送信されたらbuffer_underrun状態に遷移し、再生を再開するのに十分なバッファリングが行われるまでこの状態を維持する必要があります。特定のメッセージを表すのに使用する一意のIDです。Playディレクティブで提供される不透明なトークンです。トラックの現在のオフセットをミリ秒で示します。longPlaybackStutterFinishedイベントPlaybackStutterFinishedイベントは、ストリームの再生を再開するのに十分なバッファリングが行われたときにAVSに対して送信される必要があります。AVSは、オーディオ再生再開時に後続のPlaybackStartedイベントを待つことはありません。特定のメッセージを表すのに使用する一意のIDです。Playディレクティブで提供される不透明なトークンです。トラックの現在のオフセットをミリ秒で示します。スタッターの持続時間をミリ秒で示します。longPlaybackFinishedイベントPlaybackFinishedイベントは、クライアントがストリームの再生を終了するときにAVSに対して送信される必要があります。以下の場合には、このイベントは送信されません。再生が停止されたとき(ローカルで、またはStopディレクティブの結果として)ストリーム間の移動(次/前)注:AVSが送信するURLごとに、最大1つのPlaybackFinishedイベントが想定されます。プレイリストのURL(複数のURLで構成される)を受信した場合でも、送信するPlaybackFinishedイベントは1つだけにしてください。特定のメッセージを表すのに使用する一意のIDです。Playディレクティブで提供される不透明なトークンです。トラックの現在のオフセットをミリ秒で示します。longPlaybackFailedイベントPlaybackFailedイベントは、クライアントがストリームの再生試行中にエラーを検出するたびに、AVSに対して送信される必要があります。ストリームを再生中で、次のストリームのバッファリングに失敗した場合には、currentPlaybackTokenがペイロード内のtokenと異なる可能性があります。特定のメッセージを表すのに使用する一意のIDです。Playディレクティブから提供される不透明なトークンで、再生に失敗したストリームを表します。playbackStateオブジェクトのキー/値ペアが含まれます。Playディレクティブで提供される不透明なトークンです。トラックの現在のオフセットをミリ秒で示します。プレーヤーの状態を示します。エラーメッセージのキー/値ペアが含まれます。特定のタイプのエラーを識別します。各エラータイプの詳細は、以下の表に記載されています。端末で発生したエラーの説明です。ログの目的にのみ使用されます。HTTP関連のエラーの場合、エラーメッセージにHTTPエラー応答の本文が含まれる必要があります(存在する場合)。不明なエラーが発生しました。サーバーで、リクエストが不正なフォーマットであると認識されました。エラーがある、認証に失敗した、アクセス権がない、該当するものがない、などがあります。クライアントがサービスに到達できませんでした。有効なリクエストではあるものの、サーバーが適切に処理できませんでした。クライアントで内部エラーが発生しました。StopディレクティブStopディレクティブは、オーディオストリームの再生を停止する際にクライアントに送信されます。クライアントは、音声リクエスト、物理ボタンの押下、またはGUIアフォーダンスの機能の結果として、Stopディレクティブを受信する場合があります。特定のメッセージを表すのに使用する一意のIDです。文字列PlaybackStoppedイベントPlaybackStoppedイベントは、クライアントが以下のいずれかのディレクティブを受信してオーディオストリームの再生を停止したときに、AVSに対して送信される必要があります。CLEAR_ALL注:このイベントは、上記のディレクティブのいずれかを受信した結果としてストリームが終了されたときにのみ送信されます。通常は、ユーザーアクションの結果です。このイベントは、ストリームの再生が完了した場合には送信すべきではありません(PlaybackFinishedを参照してください)。特定のメッセージを表すのに使用する一意のIDです。Playディレクティブで提供される不透明なトークンです。トラックの現在のオフセットをミリ秒で示します。longPlaybackPausedイベントPlaybackPausedイベントは、クライアントがより優先度の高い入力/出力を処理するためにContentチャンネル上のオーディオを一時停止したときに送信される必要があります。優先度の高いアクティビティが完了したら、クライアントは再生を再開し、その時点でPlaybackResumedイベントを送信する必要があります。音声入力/出力の優先順位付けの詳細については、対話モデルを参照してください。レイテンシーを低減するためにRecognizeイベントの後に送信される必要があります。特定のメッセージを表すのに使用する一意のIDです。Playディレクティブで提供される不透明なトークンです。トラックの現在のオフセットをミリ秒で示します。longPlaybackResumedイベントPlaybackResumedイベントは、PlaybackPausedイベント(より優先度の高い入力/出力を処理するためにContentチャンネル上のオーディオが一時停止した)の後に再生が再開したときにAVSに対して送信される必要があります。音声入力/出力の優先順位付けの詳細については、対話モデルを参照してください。特定のメッセージを表すのに使用する一意のIDです。Playディレクティブで提供される不透明なトークンです。トラックの現在のオフセットをミリ秒で示します。longClearQueueディレクティブClearQueueディレクティブは、再生キューをクリアする際にAVSからクライアントに送信されます。ClearQueueディレクティブの動作には、CLEAR_ENQUEUED(キューをクリアして現在のストリームの再生を続ける)とCLEAR_ALL(再生キューをすべてクリアし、現在再生中のストリーム(ある場合)を中止する)という2つの動作があります。特定のメッセージを表すのに使用する一意のIDです。キューをクリアする動作を指定する文字列値。文字列PlaybackQueueClearedイベントPlaybackQueueClearedイベントは、クライアントがClearQueueディレクティブを処理した後にAVSに送信される必要があります。特定のメッセージを表すのに使用する一意のIDです。空のペイロードが送信される必要があります。StreamMetadataExtractedイベントクライアントが受信して再生を開始するオーディオストリームでメタデータを利用可能な場合、クライアントは未加工データとして受信したキー/値ペアを取得して、JSONオブジェクトに置き換える必要があります。このJSONオブジェクトでは、文字列と数字はJSON文字列として表され、ブール値はJSONブール値として表される必要があります。クライアントは、バイナリーデータを含むタグをすべて取り除く必要があります。クライアントは、画像、画像のプレビュー、添付ファイル、アプリケーションデータのタグをAVSに送信すべきではありません。特定のメッセージを表すのに使用する一意のIDです。Playディレクティブで提供される不透明なトークンです。受信したメタデータに関連付けられたキー/値ペアが含まれます。