ウェブアプリに音声操作と対話を追加する
Alexa Web API for Gamesを使うと、Alexa音声や音声コマンドをウェブベースのゲームに追加できます。このドキュメントでは、これらの要素をゲームに追加する一般的なシナリオをいくつか紹介します。
Alexaにユーザーと対話させる
ユーザーがウェブアプリを操作している間、Alexaがユーザーに話しかけるようにします。たとえば、ユーザーのタッチ操作にAlexaが答えたり、ゲームで起きていることをユーザーに教えたりといったシナリオが考えられます。また、ユーザーが音声で答えるように、Alexaからプロンプトを出すことも可能です。
たとえば、次のようにします。
ユーザーが画面上の「発射」のボタンにタッチします。
Alexa: ビームを発射しています…(サウンドエフェクト)…残念。外れたようです。次のターンが来たらまた挑戦してください。 (Alexa音声に合わせてウェブアプリの表示が変化します。)
ウェブアプリに新しいグラフィックスが表示され、ユーザーがタッチするのを待機します。
Alexaにユーザーと対話させるには
- ウェブアプリで、
alexa.skill.sendMessage()
を呼び出し、スキルにメッセージを送信します。 - スキルコードで、
sendMessage()
の呼び出しで生成されたAlexa.Presentation.HTML.Message
リクエストのハンドラーを作成します。このハンドラーは応答で次の項目を返します。- Alexaが話しかける
outputSpeech
- 未定義の
shouldEndSession
プロパティ(値を設定しない)
これにより、Alexaにテキストを読み上げさせて、マイクを有効にせずにセッションを維持するよう指示します。
- Alexaが話しかける
- ウェブアプリで、Alexaイベントに応答するリスナー関数を登録します。Alexaは、スピーチの開始と終了時にアプリに通知します。
ユーザーに何か言うよう促す
ウェブアプリでは、ゲーム中、ユーザーがボタンを押した場合などに、Alexaがユーザーに何か言うようプロンプトを出すことができます。たとえば、次のようにします。
ユーザーが画面上の「発射」のボタンにタッチします。
Alexa: ビームを発射しています…(サウンドエフェクト)…残念。外れたようです。もう一度挑戦しますか?
Alexaは、ユーザーの応答を聴き取るためにマイクを有効にします。
ユーザー: はい(スキルはAMAZON.YesIntent
など、対話モデルの標準インテントを取得します。)
…ゲームは続きます…
ユーザーの発話を促すプロンプトを決めるときは、ユーザーがどのように発話を開始するか考慮することが重要です。デバイスにボタンを押して話す(プッシュトゥトーク)ボタンがある場合、ボタンを押したり、長押したりして会話を始める方が自然な場合があります。もしくは、デバイスがウェイクワードに対応している場合は、ハンズフリーでウェイクワードを言うことでゲームをプレイする場合もあります。デバイスがどの方法をサポートするかは、alexa.capabilities.microphone
オブジェクトで確認できます。
Dialog
ディレクティブ(Dialog.Delegate
)を返さないでください。Alexa.Presentation.HTML
以外のインターフェースを返すと、ウェブアプリが終了します。ユーザーに何か言うようプロンプトを出すには
- ウェブアプリで、
alexa.skill.sendMessage()
を呼び出し、スキルにメッセージを送信します。 - スキルコードで、
Alexa.Presentation.HTML.Message
リクエストのハンドラーを作成します。このハンドラーは応答で次の項目を返します。- Alexaが話しかける
outputSpeech
- ユーザーが応答しない場合に使用する
reprompt
shouldEndSession
プロパティ(false
に設定する)
これにより、Alexaにテキストを読み上げてから、マイクを有効にしてユーザーの応答を待機するよう指示します。
- Alexaが話しかける
- ウェブアプリで、Alexaイベントに応答するリスナー関数を登録します。Alexaは、読み上げを開始/終了したときとマイクを有効/無効にしたときにアプリに通知します。
これらのステップにより、通常のAlexaスキルの対話がトリガーされます。Alexaは、outputSpeech
を読み上げてから、数秒間マイクを有効にし、ユーザーの応答を待機します。ユーザーの応答を聞き取れなかった場合、Alexaは再プロンプトを読み上げてから、マイクを再び有効にします。それでもユーザーが応答しない場合、Alexaはマイクを無効にします。ただし、ウェブアプリはまだ画面に表示されているため、セッションは開いたままになります。
ユーザーがプロンプトに応答し、その発話がモデルのインテントに解決されたら、スキルはIntentRequest
を取得します。スキルのインテントハンドラーはこのリクエストを処理します。たとえば、インテントハンドラーは次の項目を含む応答を返します。
- ウェブアプリにユーザーの発話から取得した関連情報を伝える
Alexa.Presentation.HTML.HandleMessage
- (オプション)
outputSpeech
- Alexaに何らかの応答をさせたい場合。 shouldEndSession
プロパティ - 未定義(別の応答を待機するためにマイクを有効にする必要がない場合)またはfalse
(別の応答を待機するためにマイクを有効にする場合)に設定。
最後に、ウェブアプリでalexa.skill.onMessage()を呼び出して、受け取ったメッセージに応答するコールバックを登録します。
JavaScript APIを使ってユーザーに何か言うようプロンプトを出す
ウェイクワードによる起動に対応しているデバイスでは、alexa.voice.requestMicrophoneOpen
APIを使ってプログラムからマイクを有効にするリクエストを出すことができます。
ユーザーに何か言うようプロンプトを出すには
-
ウェブアプリで、
alexa.capabilities.microphone.supportsWakeWord
がtrueになっていることを確認します。 -
デバイスがウェイクワード起動に対応している場合は、
alexa.voice.requestMicrophoneOpen
を呼び出します。 -
ユーザーが応答し終えたら、応答を対話モデルのインテントに解決し、スキルに送信します。
よくあるエラー応答は次の2つです。
-
microphone-already-open
: ユーザーがほかの方法(ウェイクワードなど)で既にマイクを有効にしています。 -
request-open-unsupported
: デバイスがこのAPIをサポートしていません。これ以降、アプリケーションの実行中はこのAPIを使用しないでください。このエラーが発生する原因としては、ウェイクワード起動に対応していないデバイスでAPIを呼び出した可能性が高いです。
ユーザー起動の音声入力を取得する
ウェブアプリが画面に表示されている間、ユーザーはウェイクワードを使っていつでもAlexaに話しかけることができます。スキルは、ウェブアプリがアクティブな間、ユーザー起動の音声入力にいつでも対応できる必要があります。
ユーザーが画面をタッチして複数のターゲットを選択します。ウェブアプリは標準のサウンドエフェクトとグラフィックスで応答します。
ユーザー: アレクサ、ターゲットに発射して! (スキルセッションが開いているため、ユーザーはウェイクワードと発話だけでスキルのインテントを呼び出すことができます。)
スキルは「ターゲットに発射」の発話に対応するIntentRequest
を受け取ります。
Alexa: ラジャー、ビームを発射しています!
サウンドエフェクトとグラフィックスを再生します。
ユーザー起動の音声入力を取得するには
- スキルの対話モデルに、ユーザーがゲームプレイ中に言う可能性のあるサンプル発話とインテントを追加します。
- これらのインテントのインテントハンドラーで、次の項目を返します。
- ウェブアプリにユーザーの発話リクエストから取得した関連情報を伝える
Alexa.Presentation.HTML.HandleMessage
- (オプション)
outputSpeech
- Alexaに何らかの応答をさせたい場合。 shouldEndSession
プロパティ - 未定義(別の応答を待機するためにマイクを有効にする必要がない場合)またはfalse
(別の応答を待機するためにマイクを有効にする場合)に設定。
- ウェブアプリにユーザーの発話リクエストから取得した関連情報を伝える
- ウェブアプリで
alexa.skill.onMessage()
を呼び出して、受け取ったメッセージに応答するコールバックを登録します。
トランスフォーマーを使ってHTMLでネイティブに音声をレンダリングする
Alexa.Presentation.HTML.Start
とAlexa.Presentation.HTML.HandleMessage
は、オプションのtransformers
配列を取ります。トランスフォーマーはSSMLまたはプレーンテキストをオーディオストリームに変換し、そのストリームのURLをウェブアプリに提供します。このオーディオストリームを取得し、分離してオーディオバッファとスピーチマークを抽出するには、fetchAndDemuxMP3関数を使用できます。