AudioPlayer の概要
- 概要
- 単純な例
- AudioPlayerディレクティブ
- サポートされているオーディオフォーマット
- ローカルの再生キュー
- Playディレクティブの徹底解剖
- 進行状況レポート
- シーケンス図
- 次のステップ
- リソース
概要
Alexa Voice Service（AVS）は、オーディオ再生、音量制御、テキスト読み上げ（TTS）といった、クライアント（製品）側の基本機能に対応するインターフェースの集まりです。一般的に、これらのインターフェースには、Alexaのビルトイン機能およびAlexa Skills Kit（ASK）を使用して開発したサードパーティスキルとの間に1対多の関係があります。たとえば、Alexaスキルを介したAmazon Music、フラッシュブリーフィング、Audible、TuneIn、オーディオストリーミングは、すべてAudioPlayerインターフェースを使ってオーディオコンテンツのストリーミングを管理、制御、レポートしています。
AVSはクライアントに（ストリームの再生などの）アクションを実行するよう指示するディレクティブを送信し、これらのアクションが実行される特定の順序でイベントが返されることを想定します。AudioPlayerを利用したすべてのストリーミングサービスが設計どおりに動作すること、およびメディア認定にパスするよう製品を準備することを確認するために、AudioPlayerインターフェースを正しく実装することが重要です。このページでは、開発、統合、テスト、およびトラブルシューティングに役立つ概念情報、定義、シーケンス図について説明します。
単純な例
まず、クライアントとAVSの間で想定される対話を示す単純な例から説明します。台所で、夕食のパスタを料理しているとします。料理に手いっぱいで、お湯も沸いています。そんなときは、自分でスマートフォンを操作して楽曲を再生するかわりに、「アレクサ、音楽を流して。」と声で操作しますね。このとき、内部で何が行われているかを説明します。
バイナリオーディオ添付ファイル（キャプチャされた音声）を含むRecognizeイベントが、AVSに送信されます。キャプチャされたオーディオは、Alexaにより一連のディレクティブ（およびオーディオ添付ファイル）に変換され、アクションを実行するようクライアントに送信されます。
このシナリオでは、クライアントは2つのディレクティブを受信します。最初に、SpeakディレクティブでクライアントにAlexaが読み上げる音声を再生するよう指示します。たとえば、「音楽をシャッフル再生します。」などと読み上げます。次に、Playディレクティブでクライアントに楽曲の再生を開始するよう指示します。
AVSでは、クライアントがPlayディレクティブを処理する前に、Speakディレクティブを処理し、一連のイベントをAVSに送信することを想定しています。この場合、クライアントがAlexaの読み上げ音声の再生を開始したときにSpeechStartedイベントが送信され、Alexaの読み上げ音声の再生が完了したときにSpeechFinishedが送信されます。この時点で、クライアントはPlayディレクティブに含まれるストリームの再生を開始します。
再生を開始すると、クライアントは以下の一連のライフサイクルイベントをAVSに送信します。
PlaybackStartedは、再生が開始されるときに送信されます。AVSに送信されるoffsetInMillisecondsは、Playディレクティブで指定されたオフセットと一致する必要があります。PlaybackNearlyFinishedは、クライアントが再生キューの次のストリームのバッファリングまたはダウンロードする準備が整ったときに送信されます。たいていの実装では、このイベントをPlaybackStartedの直後に送信してバッファリングを開始し、再生するストリーム間のタイムラグを低減しています。ProgressReportDelayElapsedは、PlayディレクティブにprogressReportDelayInMillisecondsが存在する場合にAVSに送信されます。ProgressReportIntervalElapsedは、PlayディレクティブにprogressReportIntervalInMillisecondsが存在する場合にAVSに送信されます。PlaybackFinishedは、クライアントがストリームの再生を完了したときに送信されます。PlaybackStoppedは、Stopディレクティブを受信して、再生を停止するときに送信されます。
これらのイベントでは、Alexaに対する再生開始の通知、次のストリームの要求、AVSや音楽サービスプロバイダーへの進行状況レポートの送信を行います。
以下のシナリオでは、これらのイベントと送信すべきタイミングが網羅されています。現時点で最も重要なのは、スムースジャズが流れている間にボロネーズソースを仕上げることです。
AudioPlayerディレクティブ
AudioPlayerインターフェースでは、オーディオ再生の制御に使用される3つのディレクティブが提供されています。
Play: クライアントに対して、クラウドからオーディオ再生を開始するように指示します。URIまたはオーディオ添付ファイルが提供されるのに加え、Playディレクティブには、クライアントにどのライフサイクルイベントをAlexaに対して送信する必要があるのかを伝えるplayBehavior、offsetInMilliseconds、streamFormat、expiryTime、progressReportなどの情報が含まれます。Stop: は、オーディオストリームの再生を停止するようクライアントに指示します。クライアントは、音声リクエスト、物理コントロール（PlaybackControllerを参照）の結果としてこのディレクティブを受信する場合があります。ClearQueue: クライアントに、現在の再生キューをクリアするよう指示します。ClearQueueディレクティブの動作には、CLEAR_ENQUEUED（キューをクリアして現在のストリームの再生を続ける）とCLEAR_ALL（再生キューをすべてクリアし、現在再生中のストリーム（ある場合）を中止する）という2つの動作があります。
クライアントは、APIで提供されるすべてのプロパティを処理し、想定外のフィールドやプロパティが検出されてもブレークしないよう設計する必要があります。たとえば、Jackson（JSONパーサー）を使用している場合、FAIL_ON_UNKNOWN_PROPERTIESをfalseに設定する必要があります。
サポートされているオーディオフォーマット
Play ディレクティブは、オーディオをさまざまなフォーマット、コンテナ、ビットレートで提供します。次のフォーマットでは、最低でも 16kbps ～ 384kbpsに対応する必要があります。AAC/MP4、MP3、HLS、PLS、 および M3U。
ローカルの再生キュー
クライアントの再生キューの作成と管理は、AudioPlayerインターフェースを関連付けられたメディアサービスが設計どおりに動作することを確認するために重要なものです。クライアントの再生キューは以下の要件を満たす必要があります。
- 複数の
Playディレクティブを処理する能力を持つ。 - クライアントのキューの調整と維持のために、各
PlayディレクティブのペイロードのplayBehaviorを使用する。 - アクティブなストリームの
tokenとキューに追加するストリームのexpectedPreviousTokenを一致させる。注: トークンとストリームが一致しない場合は無視されます。ただし、expectedPreviousTokenが返されない場合は、ストリームをキューに追加する必要があります。 ClearQueueディレクティブを受信したら、必ずキューをクリアする。
Playディレクティブの徹底解剖
単純な例に戻りましょう。Alexaに楽曲を再生するように言った後、クライアントにオーディオストリーム（またはバイナリオーディオ添付ファイル）の再生を開始するよう指示するPlayディレクティブを受信しました。ディレクティブのペイロードには、ストリームのURL、ストリームURLの有効期限、想定される再生動作、進行状況レポートの要件といった重要な情報が含まれています。このセクションでは、Playディレクティブを徹底解剖します。
ペイロードは、以下のようになります。
{
"directive": {
"header": {
"namespace": "AudioPlayer",
"name": "Play",
"messageId": "42941f13-90ed-4d9e-8159-xxxxxxxx",
"dialogRequestId": "req:a345fgh598383xxx""
},
"payload": {
"playBehavior": "REPLACE_ALL",
"audioItem": {
"audioItemId": "test1.as-ct.v1.XYZ-ABCDE-FGHIJ#ACRI#url#ACRI#0f6bcd24-f621-555a-822c-1111111:1",
"stream": {
"url": "https://opml.radiotime.com/Tune.ashx?serial=SAMPLE&formats=aac,mp3&partnerId=SAMPLE",
"streamFormat" "AUDIO_MPEG"
"offsetInMilliseconds": 0,
"expiryTime": "2016-09-13T18:22:49+0000",
"progressReport": {
"progressReportDelayInMilliseconds": 15000,
"progressReportIntervalInMilliseconds": 900000
},
"token": "test1.as-ct.v1.XYZ-ABCDE-FGHIJ#ACRI#url#ACRI#0f6bcd24-f621-555a-822c-1111111:1"
}
}
}
}
}
- 最初は、この
Playディレクティブがローカルの再生キューにどう影響するかに関する情報を提供するplayBehaviorです。以下の3つの動作がサポートされています。REPLACE_ALL: クライアントに、ペイロードに含まれるストリームの再生をすぐに開始し、ローカルの再生キューにあるストリームをすべて置き換えるよう指示します。ENQUEUE: クライアントに、Playディレクティブに含まれるストリームを現在の再生キューの最後に追加するよう指示します。REPLACE_ENQUEUED: クライアントに、ローカルの再生キューにあるすべてのストリームを置き換えるよう指示します。これにより、現在再生中のストリームが影響を受けることはありません。
上のサンプルでは、
playBehaviorはREPLACE_ALLに設定されています。そのため、クライアントはローカルの再生キューをすべてクリアし、ペイロードに含まれるオーディオストリームの再生をすぐに開始する必要があります。 - 次は、
audioItemIdとstreamを含む、audioItemオブジェクトです。audioItemId: オーディオストリームを表す不透明なトークンです。stream: オーディオストリームに関する、以下の具体的な情報を提供するオブジェクトです。url: オーディオコンテンツの場所を指定します。オーディオコンテンツがバイナリオーディオ添付ファイルの場合、値はcid:プレフィックスに続く、コンテンツの一意の識別子です。streamFormat: オーディオストリームの形式を指定します。offsetInMilliseconds: クライアントがオーディオストリームの再生を開始するオフセットを指定します。expiryTime: ストリームがいつ無効になるかを示すタイムスタンプです（ISO 8601の日付と時刻形式で示されます）。progressReport: コンテンツプロバイダーが要求する進行状況レポートに関する情報を含むオブジェクトです。progressReportprogressReportIntervalInMillisecondsとprogressReportDelayInMillisecondsがサポートされます。この例では、この両方のみが必要です。progressReportDelayInMilliseconds: いつ最初の進行状況レポートを送信する必要があるかを示すオフセットです。このイベントは、Playディレクティブに指定されたインターバルで1回のみ送信されます。progressReportIntervalInMilliseconds: いつ定期的な進行状況レポートを送信する必要があるかを示すオフセットです。トラックの最初から、このオフセットが経過するたびに発生するイベントです。
token: 現在のオーディオストリームを表す不透明なトークンです。
ペイロードでは、クライアントがオーディオストリームを正常に処理し、ローカルの再生キューに追加するのに必要なすべての情報が提供されます。
offsetInMilliseconds、progressReportDelayInMilliseconds、progressReportIntervalInMillisecondsを常に把握しておくようにしてください。これらのパラメーターはクライアントに進行状況レポートの情報を提供し、AVSに返す必要のある値を含む場合があります。
進行状況レポート
progressReportDelayInMillisecondsおよび/またはprogressReportIntervalInMillisecondsがPlayディレクティブのペイロードに存在する場合、クライアントが、コンテンツプロバイダーに対してこの特定のストリームに関する進行状況レポートをどのように提供する必要があるかを示しています。
これらのパラメーターが存在する場合、クライアントは、以下の対応するライフサイクルイベントを送信する必要があります。
ProgressReportDelayElapsed:ProgressReportDelayElapsedイベントは、PlayディレクティブにprogressReportDelayInMillisecondsが存在する場合にAVSに送信される必要があります。イベントは、ストリームの最初から指定したインターバルが経過した後に1回のみ送信される必要があります（offsetInMillisecondsからではありません）。たとえば、Playディレクティブに含まれるprogressReportDelayInMillisecondsの値が20000の場合、ProgressReportDelayElapsedイベントはトラックの最初から20,000ミリ秒経過した後に送信される必要があります。ただし、Playディレクティブに含まれるoffsetInMillisecondsの値が10000で、progressReportDelayInMillisecondsの値が20000の場合、イベントは再生の最初から10,000ミリ秒経過した後に送信される必要があります。これは、進行状況レポートが、Playディレクティブのオフセットではなく、ストリームの最初から起算されて送信されるためです。ProgressReportIntervalElapsed:ProgressReportIntervalElapsedイベントは、PlayディレクティブにprogressReportIntervalInMillisecondsが存在する場合にAVSに送信される必要があります。イベントは、ストリームの最初から指定したインターバルが経過した後に定期的に送信される必要があります（offsetInMillisecondsからではありません）。たとえば、Playディレクティブに含まれるprogressReportIntervalInMillisecondsの値が20000の場合、ProgressReportIntervalElapsedイベントはトラックの最初から20,000ミリ秒経過した後、およびストリームの最後まで20,000ミリ秒ごとに送信される必要があります。ただし、Playディレクティブに含まれるoffsetInMillisecondsの値が10000で、progressReportIntervalInMillisecondsの値が20000の場合、イベントは再生の最初から10,000ミリ秒後、およびストリームの最後まで20,000ミリ秒ごとに送信される必要があります。これは、指定されたインターバルが、Playディレクティブのオフセットではなく、ストリームの最初から起算されるためです。
シーケンス図
以下の図は、Alexaから送信されたディレクティブに応答して、クライアントから送信すると想定されるライフサイクルイベント（および製品で行われたその後のアクション）を示しています。これらの図をJavaサンプルアプリで生成されるログと組み合わせることで、開発や認定で問題が発生した場合のトラブルシューティングに活用できます。
シナリオ1: 「Alexa, play rock music from iHeartRadio.」
このシナリオでは、ユーザーはiHeartRadioでロックの楽曲を再生するようリクエストしています。以下の図は、AVSに送信されるイベントと、AVSからの受信が想定されるディレクティブの適切なシーケンスを示しています。
注: この例では、最初のストリームが最後まで再生され、クライアントがPlaybackFinishedイベントを送信しています。
シナリオ2: オーディオストリームの停止と再開
このシナリオでは、ユーザーは楽曲を再生し、再生開始から約45秒後に「アレクサ、ストップ。.」と言います。その約10秒後に、「アレクサ、リズーム。」と言います。このシナリオは、端末がストリームの開始から正しい進行状況レポートを送信していることを確認するために使用します。また、クライアントがどうオーディオ出力の優先順位を付けるかを制御するために使用される概念である、チャネルも使用しています。この場合、優先順位付けされるオーディオ出力は、オーディオ再生とAlexaの音声応答です。
注: この例では、ユーザーはオーディオ再生を停止するようリクエストし、Stopディレクティブがクライアントに送信され、PlaybackStoppedがAVSに送信されます。この点が、ストリームが完了するまで再生してからAVSにPlaybackFinishedが送信された前の例とは異なります。さらに、ローカルで楽曲が一時停止され、再開されると、クライアントはそれぞれPlaybackPausedとPlaybackResumedを送信すると想定されます。
シナリオ3-A: 物理コントロールを使用した再生キューの次のストリームへの移動
このシナリオでは、ユーザーは楽曲を再生し、再生開始から約15秒後に端末の「次」ボタンを押して次のストリームにスキップします。
注: この例は、ローカルでの制御であり、Amazon Alexaアプリ上で実行されるアクションではありません。
シナリオ3-B: 音声を使用した再生キューの次のストリームへの移動
このシナリオでは、ユーザーは楽曲を再生し、再生開始から約15秒後に「アレクサ、次。」と言います。
シナリオ4: アラーム鳴動による楽曲再生の中断
このシナリオでは、ユーザーはAVS端末に楽曲を再生するよう言います。再生中に、予めセットされていたアラームが鳴り、ユーザーはアラームを停止します。クライアントがどうオーディオ出力の優先順位を付けるかを制御するために使用される概念である、チャネルも使用しています。この場合、優先順位付けされるオーディオ出力は、オーディオ再生と鳴っているアラームです。
以下の図は、AVSに送信されるイベントと、AVSからの受信が想定されるディレクティブの適切なシーケンスを示しています。
シナリオ5: 「アレクサ、近くで上映中の映画を教えて？」
このシナリオでは、ユーザーは近くで上映されている映画を尋ねます。以下の図は、AVSに送信されるイベントと、AVSからの受信が想定されるディレクティブの適切なシーケンスを示しています。
次のステップ
- AudioPlayerインターフェースを確認する
