視覚応答とオーディオ応答を統合する

視覚応答とオーディオ応答を統合する

Alexa Presentation Language(APL)では、画面付きデバイス向けの視覚応答を作成できます。APL for Audioでは、サウンドエフェクトなどのオーディオと音声を組み合わせて、リッチなオーディオ応答を作成できます。これらの視覚応答とオーディオ応答を統合すると、魅力的なユーザーエクスペリエンスを提供することができます。

視覚応答とオーディオ応答の統合の概要

視覚応答とオーディオ応答は、次の2つの方法で統合できます。

  • 同じ応答で2つのRenderDocumentディレクティブを返す - スキルの同じ応答で、次の2つの異なるディレクティブを返します。
  • 視覚応答にオーディオを埋め込む - 視覚応答用のAPLドキュメントとオーディオ応答用のAPL for Audioドキュメントの両方を含む、単一のAlexa.Presentation.APL.RenderDocumentをスキルから返します。その後、APLコマンドを使用して手動でオーディオを呼び出します。

詳細については、以下のセクションを参照してください。

同じ応答で2つのRenderDocumentディレクティブを返す

1つの応答で視覚応答用とオーディオ応答用の両方のRenderDocumentディレクティブを指定すると、Alexaは画面にコンテンツを表示し、指定された出力音声を読み上げてから、APL for Audio応答を再生します。通常の音声出力とオーディオ応答が重なることはありません。

オーディオ応答と視覚応答の両方を含むRenderDocumentディレクティブを返すには

  1. 視覚応答用のAPLドキュメントと、オーディオ応答用のAPL for Audioドキュメントを作成します。
  2. スキルコードで、Alexa.Presentation.APL.RenderDocumentAlexa.Presentation.APLA.RenderDocumentの両方をdirectives配列に追加します。

    directives配列内でのディレクティブの順序は問いません。

たとえば、以下のAPLドキュメントとデータソースでは、「ハローワールド」のようこそメッセージが設定されたAlexaHeadlineテンプレートが表示されます。

ようこそメッセージを表示するAPLドキュメント
ようこそメッセージを表示するAPLドキュメント

このコンテンツを表示し、同時に音声とバックグラウンドサウンドエフェクトを組み合わせたオーディオを再生するとします。以下のAPL for Audioドキュメントとデータソースでは、このオーディオが生成されます。

この両方のサンプルを同時に送信するには、APLインターフェースとAPLAインターフェースの2つのRenderDocumentをスキルの応答に含めます。

以下は、2つのRenderDocumentディレクティブをdirectives配列に追加する応答の例です。この応答では、outputSpeechプロパティも設定されます。Alexaは画面にコンテンツを表示し、outputSpeechを読み上げてから、APL for Audio応答を再生します。

視覚応答にオーディオを埋め込む

視覚応答用のAPLドキュメントにオーディオ応答を埋め込むことができます。スキルから単一のAlexa.Presentation.APL.RenderDocumentディレクティブを返し、APLのSpeakItemコマンドまたはSpeakListコマンド使用して、手動でオーディオを呼び出します。

このオプションを使用すると、オーディオと視覚コンテンツをより正確に同期させることができます。たとえば、Alexaでリスト内の項目ごとにオーディオを再生し、リストを自動的にスクロールしてそれぞれの項目をハイライト表示することができます。また、このオーディオを埋め込む方法は、ユーザーが画面上のボタンをタップしたときなど、ユーザーイベントへの応答としてオーディオを再生する場合にも便利です。

オーディオはコマンドに応答して再生されるため、Alexaが通常の出力音声の読み上げを終える前にオーディオの再生が開始される可能性があります。これを回避するために、さまざまなアプローチを使用できます。たとえば、応答に関連するすべての音声をAPL for Audioドキュメントに含めて、outputSpeechプロパティを含めないようにすることができます。

オーディオを埋め込むには、複数の手順が必要となります。まず、aplAudioToSpeechトランスフォーマーを使用して、APL for Audioドキュメントをオーディオファイルに変換します。その後、そのオーディオファイルへの参照をAPLドキュメントのコンポーネントにバインドします。

視覚応答にオーディオを埋め込んでドキュメントから呼び出すには

  1. 視覚応答用のAPLドキュメントと、オーディオ応答用のAPL for Audioドキュメントを作成します。
  2. APLドキュメントのデータソースで、aplAudioToSpeechトランスフォーマーを設定します。

    トランスフォーマーは、APL for Audioドキュメントをオーディオファイルに変換します。このオーディオファイルは、APLコマンドで呼び出すことができます。詳細については、aplAudioToSpeechトランスフォーマーを設定するを参照してください。

  3. トランスフォーマーの出力をAPLドキュメント内のコンポーネントのspeechプロパティにバインドします。詳細については、トランスフォーマーの出力をコンポーネントにバインドするを参照してください。
  4. SpeakItemまたはSpeakListのいずれかのAPLコマンドを実行し、speechプロパティが設定されたコンポーネントをターゲットにします。

    これらのコマンドは、ユーザーが画面をタップしたときや、ドキュメントが最初に表示されたときなど、さまざまな方法で開始できます。詳細についてはSpeakItemコマンドまたはSpeakListコマンドを実行してオーディオを呼び出すを参照してください。

  5. スキルコードでAlexa.Presentation.APL.RenderDocumentを返します。sourcesプロパティで、同じディレクティブにAPL for Audioドキュメントを含めます。

    詳細については、RenderDocumentディレクティブの一部としてオーディオ応答を含めるを参照してください。

以降のセクションでは、これらの各手順について詳しく説明します。

APLドキュメントとAPL for Audioドキュメントを作成する

APLドキュメントとAPL for Audioドキュメントを作成します。オーサリングツールでドキュメントを保存して、RenderDocumentディレクティブを送信する際にコードからそのドキュメントにリンクすることができます。または、スキルコードに各ドキュメントの完全なJSONを含めることもできます。

aplAudioToSpeechトランスフォーマーを設定する

aplAudioToSpeechトランスフォーマーは、APL for Audioドキュメントをオーディオファイルに変換します。このオーディオファイルはAPLドキュメント内で参照できます。トランスフォーマーは、APLドキュメントのデータソースのtransformers配列に含めます。

トランスフォーマーでは、データソースで指定されたデータを変換してから、同じデータソースのプロパティに出力を書き込みます。

aplAudioToSpeechトランスフォーマーには、以下を指定します。

  • template - 変換するAPL for Audioドキュメントの名前です。
  • outputName - 変換されたオーディオファイルのURLが格納されるプロパティの名前です。
  • inputPath -(オプション)APL for Audioドキュメントで使用するデータを含むデータソースのプロパティです。このプロパティは、配列内の各項目のオーディオを作成する場合に使用します。例については、リスト内の項目ごとにオーディオを再生するを参照してください。

クリップボードにコピーされました。

{
  "transformers": [
    {
      "template": "helloWorldEmbedAPLAudioExampleAudio",
      "transformer": "aplAudioToSpeech",
      "outputName": "welcomeSpeech"
    }
  ]
}

トランスフォーマーを使用するには、typeプロパティをobjectに設定して、データソースをオブジェクトデータソースとして定義する必要があります。トランスフォーマーを使用して変換するプロパティは、propertiesオブジェクト内で定義します。

以下は、前述の「ハローワールド」ドキュメントで使用できる有効なデータソースの例です。aplAudioToSpeechトランスフォーマーは、helloWorldEmbedAPLAudioExampleAudioというAPL for Audioドキュメントをオーディオファイルに変換し、このオーディオファイルのURLをhelloWorldData.properties.welcomeSpeech.urlプロパティに保存します。

クリップボードにコピーされました。

{
  "helloWorldData": {
    "type": "object",
    "objectId": "helloWorldSample",
    "properties": {
      "headerTitle": "サンプル: 視覚応答からオーディオ応答を呼び出す",
      "primaryText": {
        "type": "PlainText",
        "text": "APLとオーディオ応答のサンプルです"
      },
      "secondaryText": {
        "type": "PlainText",
        "text": "このサンプルでは、APLドキュメントにAPL for Audio応答を埋め込みます。"
      },
      "welcomeText": {
        "contentType": "SSML",
        "textToSpeak": "<speak><amazon:emotion name='excited' intensity='medium'>APLへようこそ。</amazon:emotion>このサンプルでは、APL for Audio応答をAPLドキュメントに統合します。これには、まずAPLオーディオを音声に変換するトランスフォーマーを使用して、オーディオクリップを作成します。次に、トランスフォーマーの出力をAPLドキュメント内のコンポーネントのspeechプロパティにバインドします。最後に、SpeakItemコマンドを使用してオーディオを呼び出します。このサンプルでは、onMountハンドラーからコマンドを実行するため、ドキュメントが表示されたときにコマンドが実行されます。</speak>"
      }
    },
    "transformers": [
      {
        "template": "helloWorldEmbedAPLAudioExampleAudio",
        "transformer": "aplAudioToSpeech",
        "outputName": "welcomeSpeech"
      }
    ]
  }
}

以下は、aplAudioToSpeechトランスフォーマーが実行された後のデータソースの例です。propertiesオブジェクトに、結果が格納されたwelcomeSpeechプロパティが追加されています。

トランスフォーマーの出力をコンポーネントにバインドする

APLドキュメントでトランスフォーマーの出力を使用するには、APLのデータバインディング式を使用して、出力をコンポーネントのspeechプロパティにバインドします。バインド先となるプロパティは、outputName.urlです。

クリップボードにコピーされました。

{
  "type": "AlexaHeadline",
  "id": "helloWorldHeadline",
  "headerTitle": "${payload.helloWorldData.properties.headerTitle}",
  "primaryText": "${payload.helloWorldData.properties.primaryText.text}",
  "secondaryText": "${payload.helloWorldData.properties.secondaryText.text}",
  "speech": "${payload.helloWorldData.properties.welcomeSpeech.url}"
}

SpeakItemコマンドまたはSpeakListコマンドを実行してオーディオを呼び出す

オーディオを再生するには、SpeakItemまたはSpeakListのいずれかのコマンドを実行し、speechプロパティが設定されたコンポーネントをターゲットにします。

オーディオ再生のタイミング 実行内容

ドキュメントが表示されたとき

ドキュメントまたはコンポーネントのonMountハンドラーから、SpeakItemまたはSpeakListを呼び出します。

このシナリオでは、Alexaが応答のoutputSpeechを読み上げている途中でも、ドキュメントが表示されたときにオーディオの再生が開始されます。音声と重ならないようにするには、応答にoutputSpeechを含めないようにしてください。

ユーザーが画面上のコンポーネントを選択したとき

ユーザーがタップできるコンポーネントのハンドラーから、SpeakItemコマンドまたはSpeakListコマンドを次のように呼び出します。

  • AlexaButtonなどのレスポンシブ対応コンポーネントの場合は、primaryActionプロパティにSpeakItemコマンドまたはSpeakListコマンドを設定します。
  • APLコンポーネントを使用して作成されたカスタムレイアウトの場合は、SpeakItemコマンドまたはSpeakListコマンドを使用して、タッチ可能なコンポーネントonPressハンドラーを設定します。

例については、ユーザーの操作への応答としてオーディオを再生するを参照してください。

ユーザーに優れたエクスペリエンスを提供するには、ユーザーがボタンなどのタッチ可能な項目を音声で選択できるようにする必要があります。

ユーザーが音声でリクエストを行ったとき

対話モデルのインテントを作成してリクエストをキャプチャします。このインテントのハンドラーで、SpeakItemコマンドまたはSpeakListコマンドを含むExecuteCommandsディレクティブを返します。

詳細については、ユーザーの操作への応答としてオーディオを再生するを参照してください。

以下の例では、ドキュメントが表示されたときに、helloWorldHeadlineというIDを持つコンポーネントのspeechプロパティにバインドされた音声が再生されます。

クリップボードにコピーされました。

{
  "onMount": [
    {
      "type": "SpeakItem",
      "componentId": "helloWorldHeadline"
    }
  ]
}

RenderDocumentディレクティブの一部としてオーディオ応答を含める

埋め込みのオーディオを使用するには、APLドキュメントとAPL for Audioドキュメントの両方を含むAlexa.Presentation.APL.RenderDocumentディレクティブを、次のように返します。

  • documentプロパティにAPLドキュメントを設定します。documentには、オーサリングツールで保存されたドキュメントへのリンクか、ドキュメントの完全なJSONのいずれかを設定できます。
  • sourcesプロパティに文字列とオブジェクトのマップを設定します。このマップ内で、文字列にはAPL for Audioドキュメントの名前、オブジェクトにはドキュメントを設定します。
    • 名前は、aplAudioToSpeechトランスフォーマーのtemplateプロパティに使用した文字列と一致している必要があります。
    • ドキュメントは、オーサリングツールで保存されたドキュメントへのリンクか、ドキュメントの完全なJSONのいずれかとして指定できます。

      以下は、helloWorldEmbedAPLAudioExampleAudioという1つのソースを持つsourcesのマップの例です。この例では、APL for Audioドキュメントはオーサリングツールで「helloWorldEmbedAPLAudioExampleAudio」という名前で保存されているものとします。

      {
        "sources": {
          "helloWorldEmbedAPLAudioExampleAudio": {
            "src": "doc://alexa/apla/documents/helloWorldEmbedAPLAudioExampleAudio",
            "type": "Link"
          }
        }
      }
      
  • datasourcesプロパティに、APLドキュメントとAPL for Audioドキュメントの両方で使用するデータソースを含む、文字列とオブジェクトのマップを設定します。

以下は、APLドキュメントとAPL for Audioドキュメントの両方を含む単一のRenderDocumentディレクティブを送信する応答の例です。APLドキュメントではonMountハンドラーを使用してオーディオの再生を開始するため、応答にoutputSpeechは含まれていません。outputSpeechを含めると、音声とオーディオが重なって再生されます。

リスト内の項目ごとにオーディオを再生する

APLのSpeakListコマンドは、リスト内の各項目(Sequenceなど)に関連付けられた音声を再生します。リストでは、自動的にスクロールして各項目を表示し、それぞれの項目の外観を変更してハイライト表示するカラオケ効果を利用できます。APL for AudioでSpeakListを使用すると、リスト内の項目ごとにオーディオクリップを再生できます。

全体的な手順は、視覚応答にオーディオを埋め込むで説明した手順と同じです。aplAudioToSpeechトランスフォーマーを設定し、トランスフォーマーの出力をリスト項目にバインドしてから、SpeakListコマンドを呼び出します。トランスフォーマーを設定する際は、単一のクリップを生成するのではなく、項目の配列を処理し、項目ごとにクリップを作成するように設定します。

リスト内の項目ごとにオーディオを再生するには

  1. SequenceGridSequenceなどの複数子コンポーネントを使用してリストを表示するAPLドキュメントを作成します。コンポーネントにはidプロパティを含めます。例については、リストを表示するAPLドキュメントとデータソースを作成するを参照してください。
  2. 表示するリスト項目の配列を含むデータソースを作成します。
    • オブジェクトデータソースを使用して、propertiesオブジェクト内にデータ配列を配置します。
    • ドキュメントで、データ配列をSequenceまたはGridSequencedataプロパティにバインドします。

    例については、リストを表示するAPLドキュメントとデータソースを作成するを参照してください。

  3. aplAudioToSpeechトランスフォーマーのinputPathプロパティを設定して、リスト項目を含むデータ配列へのパスを指定します。詳細については、aplAudioToSpeechトランスフォーマーを設定して項目の配列を処理するを参照してください。
  4. 1つのリスト項目に対して任意のオーディオを再生するAPL for Audioドキュメントを作成します。データバインディングを使用して、リスト項目の配列のデータにアクセスします。詳細については、APL for Audioドキュメントを作成するを参照してください。
  5. トランスフォーマーの出力をSequenceまたはGridSequenceの子コンポーネントにバインドします。詳細については、トランスフォーマーの出力をSequenceの子コンポーネントにバインドするを参照してください。
  6. SpeakListコマンドを実行し、SequenceまたはGridSequenceをターゲットにします。詳細については、SpeakListコマンドを実行してkaraokeスタイルを設定するを参照してください。
  7. スキルコードでAlexa.Presentation.APL.RenderDocumentを返します。sourcesプロパティで、同じディレクティブにAPL for Audioドキュメントを含めます。

リストを表示するAPLドキュメントとデータソースを作成する

以下は、サウンド名のリストを表示するSequenceの例です。リストに表示するデータは、listOfSoundsDataデータソースのlistOfSounds配列から取得されます。このドキュメントが表示されると、Sequence内のTextコンポーネントが、data内の項目ごとに1回表示されます。

クリップボードにコピーされました。

{
  "type": "Sequence",
  "height": "100%",
  "width": "100%",
  "id": "listOfSoundsSequence",
  "numbered": true,
  "padding": [
    "@marginHorizontal",
    "@spacingLarge"
  ],
  "items": [
    {
      "type": "Text",
      "text": "${ordinal}. ${data.name}",
      "spacing": "@spacingLarge"
    }
  ],
  "data": "${payload.listOfSoundsData.properties.listOfSounds}"
}

オブジェクト型のデータソースを使用し、データソースのpropertiesオブジェクト内に配列を配置して、トランスフォーマーが後で配列にアクセスできるようにします。以下はこのデータソースの例です。このデータソースには、最初の4つのリスト項目が含まれています。

クリップボードにコピーされました。

{
  "listOfSoundsData": {
    "type": "object",
    "objectId": "speakListAplForAudioExample",
    "properties": {
      "listOfSounds": [
        {
          "audioUrl": "soundbank://soundlibrary/animals/amzn_sfx_bird_chickadee_chirp_1x_01",
          "duration": 0.63,
          "name": "コガラのさえずり(1回)(1)"
        },
        {
          "audioUrl": "soundbank://soundlibrary/animals/amzn_sfx_bird_forest_01",
          "duration": 2.9,
          "name": "鳥が鳴く森(1)"
        },
        {
          "audioUrl": "soundbank://soundlibrary/animals/amzn_sfx_bird_robin_chirp_1x_01",
          "duration": 0.67,
          "name": "コマツグミのさえずり(1回)(1)"
        },
        {
          "audioUrl": "soundbank://soundlibrary/animals/amzn_sfx_raven_caw_1x_01",
          "duration": 0.63,
          "name": "ワタリガラスの鳴き声(1回)(1)"
        }
      ]
    }
  }
}
Sequenceコンポーネントで表示されるデータ配列の項目のリスト
Sequenceコンポーネントで表示されるデータ配列の項目のリスト

aplAudioToSpeechトランスフォーマーを設定して項目の配列を処理する

配列内の各項目のオーディオクリップを作成するには、aplAudioToSpeechトランスフォーマーのinputPathプロパティを使用します。inputPathプロパティでは、APL for Audioドキュメントで使用するデータを含むデータソースのオブジェクトへのパスを指定します。

inputPathには、Sequenceで表示している配列と同じものを設定します。templateにはAPL for Audioドキュメントの名前、outputNameにはトランスフォーマーの出力が格納されるプロパティを設定します。

以下の例では、Alexaは指定されたtemplatesoundItemToPlay)を使用して、listOfSounds配列内の各項目のオーディオクリップを生成します。

{
  "transformers": [
    {
      "transformer": "aplAudioToSpeech",
      "template": "soundItemToPlay",
      "outputName": "speech",
      "inputPath": "listOfSounds.*"
    }
  ]
}

APL for Audioドキュメントを作成する

作成するAPL for Audioドキュメントでは、リスト内の1つの項目のオーディオを再生する必要があります。トランスフォーマーで、APL for Audioドキュメントをテンプレートとして使用して、inputPath配列内の項目ごとに個別のオーディオクリップを生成します。

APL for Audioドキュメントでは、データバインディングを使用して、配列項目のデータにアクセスできます。このデータにアクセスするには、${payload.data}式を使用します。

以下は、サウンド名を読み上げた後でサウンドエフェクトのオーディオを再生するSequencerコンポーネントを含むドキュメントの例です。${payload.data.name}${payload.data.audioUrl}の値は、inputPathプロパティで参照されている配列(この例では前述のlistOfSoundsプロパティ)から取得されます。

クリップボードにコピーされました。

{
  "type": "APLA",
  "version": "0.91",
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "item": {
      "type": "Sequencer",
      "items": [
        {
          "type": "Speech",
          "contentType": "SSML",
          "content": "${payload.data.name}"
        },
        {
          "type": "Silence",
          "duration": 500
        },
        {
          "type": "Audio",
          "source": "${payload.data.audioUrl}"
        }
      ]
    }
  }
}

aplAudioToSpeechトランスフォーマーが実行されると、listOfSounds配列内の項目ごとに次の処理が行われます。

  1. ${payload.data.name}${payload.data.audioUrl}の式が、listOfSounds内の項目の値に置き換えられます。
  2. APL for Audioドキュメントに基づいてオーディオクリップが作成されます。この例のクリップでは、サウンド名が読み上げられた後にサウンドのサンプルが再生されます。
  3. outputNameプロパティの配列内の項目に新しいオブジェクトが追加されます。このオブジェクトには、生成されたサウンドクリップのURLが格納されたurlプロパティが含まれています。以下は、リスト内の最初の項目に対するトランスフォーマーの出力例です。

     {
       "duration": 0.63,
       "audioUrl": "soundbank://soundlibrary/animals/amzn_sfx_bird_chickadee_chirp_1x_01",
       "speech": {
         "url": "https://tinyaudio.amazon.com/ext/v1/apl/audio/AYADeIg.../resource.mp3"
       },
       "name": "コガラのさえずり(1回)(1)"
     }
    

トランスフォーマーの出力をSequenceの子コンポーネントにバインドする

APLドキュメントで、SequenceまたはGridSequenceの子コンポーネントのspeechプロパティを、トランスフォーマーの出力にバインドします。Sequence自体ではなく、必ず子コンポーネントのspeechコンポーネントをバインドするようにしてください。

以下は、前出のSequenceコンポーネントの例です。dataプロパティは、データソースのlistOfSounds配列にバインドされています。Textコンポーネントのspeechプロパティは、aplAudioToSpeechコンポーネントの出力にバインドされています。

クリップボードにコピーされました。

{
  "type": "Sequence",
  "height": "100%",
  "width": "100%",
  "id": "listOfSoundsSequence",
  "numbered": true,
  "padding": [
    "@marginHorizontal",
    "@spacingLarge"
  ],
  "items": [
    {
      "type": "Text",
      "text": "${ordinal}. ${data.name}",
      "spacing": "@spacingLarge",
      "speech": "${data.speech.url}"
    }
  ],
  "data": "${payload.listOfSoundsData.properties.listOfSounds}"
}

SpeakListコマンドを実行してkaraokeスタイルを設定する

オーディオを再生するには、SpeakListコマンドを実行し、SequenceコンポーネントまたはGridSequenceコンポーネントをターゲットにします。SpeakItemコマンドまたはSpeakListコマンドを実行してオーディオを呼び出すで説明したように、SpeakListコマンドはさまざまな方法で呼び出すことができます。ターゲットには必ずリストのコンポーネント(SequenceまたはGridSequence)を指定してください。

以下の例では、Sequence内の各項目のオーディオを再生するボタンを定義しています。

クリップボードにコピーされました。

{
  "type": "AlexaButton",
  "buttonText": "サウンドサンプルをすべて聴く",
  "alignSelf": "center",
  "spacing": "@spacingMedium",
  "primaryAction": [
    {
      "type": "SpeakList",
      "componentId": "listOfSoundsSequence",
      "start": 0,
      "count": "${payload.listOfSoundsData.properties.listOfSounds.length}",
      "align": "center"
    }
  ]
}

ユーザーは、リスト内の個々の項目を選択できることを期待しています。ユーザーが1つの項目を選択したときにそのリスト項目のオーディオを再生するには、TextコンポーネントをTouchWrapperでラップし、onPressプロパティにSpeakItemコマンドを設定します。speechプロパティは、Sequenceの子コンポーネントのものである必要があります。プロパティは、Textコンポーネントではなく、TouchWrapperで設定します。この例では、SpeakItemコマンドにcomponentIdプロパティは必要ありません。これは、コマンドが独自のコンポーネント、つまりTouchWrapper自体をターゲットにしているためです。

クリップボードにコピーされました。

{
  "type": "TouchWrapper",
  "spacing": "@spacingLarge",
  "speech": "${data.speech.url}",
  "items": [
    {
      "type": "Text",
      "text": "${ordinal}. ${data.name}"
    }
  ],
  "onPress": [
    {
      "type": "SpeakItem"
    }
  ]
}

SpeakListコマンドでは、オーディオの再生中に各項目をハイライト表示することもできます。これを有効にするには、karaoke状態に基づいてSequenceの子コンポーネントの外観を変更するスタイルを追加します。Alexaでspeechが再生されている間、そのコンポーネントはkaraoke状態に設定されます。スタイルは、コンポーネントのstyleプロパティに割り当てます。

たとえば、以下のスタイルでは、Alexaでコンポーネントのspeechが再生されているときに、コンポーネントの色が青に変更されます。

クリップボードにコピーされました。

{
  "styles": {
    "textStyleListItem": {
      "values": [
        {
          "when": "${state.karaoke}",
          "color": "blue"
        }
      ]
    }
  }
}

以下は、リスト項目のTextコンポーネントが含まれたTouchWrapperの例です。この例では、テキストスタイルが設定されています。karaoke状態は、speechプロパティが含まれている項目(この例ではTouchWrapper)に適用されます。この状態をTextコンポーネントに適用するには、inheritParentStatetrueに設定します。

クリップボードにコピーされました。

{
  "type": "TouchWrapper",
  "spacing": "@spacingLarge",
  "speech": "${data.speech.url}",
  "items": [
    {
      "type": "Text",
      "text": "${ordinal}. ${data.name}",
      "style": "textStyleListItem",
      "inheritParentState": true
    }
  ],
  "onPress": [
    {
      "type": "SpeakItem"
    }
  ]
}

以下は、項目のリストを表示する完全なAPLドキュメントとデータソースの例です。ユーザーは、ボタンを選択してリストのすべての項目を再生するか、個々の項目を選択して1つずつ再生することができます。

SpeakListコマンドを開始するAlexaButtonを使用したSequenceコンポーネント
SpeakListコマンドを開始するAlexaButtonを使用したSequenceコンポーネント

RenderDocumentディレクティブを返す

埋め込みのオーディオを使用するには、RenderDocumentディレクティブの一部としてオーディオ応答を含めるで説明したように、APLドキュメントとAPL for Audioドキュメントの両方を含むAlexa.Presentation.APL.RenderDocumentディレクティブを返します。

ユーザーの操作への応答としてオーディオを再生する

ユーザーが画面をタップしたときや、音声でリクエストを行ったときなど、ユーザーの操作への応答としてSpeakItemコマンドまたはSpeakListコマンドを実行できます。

全体的な手順は、視覚応答にオーディオを埋め込むで説明した手順と同じです。

  1. aplAudioToSpeechトランスフォーマーを設定し、トランスフォーマーの出力をコンポーネントのspeechプロパティにバインドします。
  2. ボタンのタップなどのタップイベントの場合は、ユーザーがタップできるコンポーネントのハンドラーから、SpeakItemコマンドまたはSpeakListコマンドを実行します。
  3. 音声リクエストの場合は、対話モデルのインテントを作成してリクエストをキャプチャします。このインテントのハンドラーで、SpeakItemコマンドまたはSpeakListコマンドと、speechプロパティが設定されたコンポーネントのIDを含む、ExecuteCommandsディレクティブを返します。

ユーザーに最良のエクスペリエンスを提供するには、スキルでタップイベントと音声リクエストの両方に応答できるようにしてください。これにより、ユーザーがスキルの操作方法を選択することが可能になります。

タップイベントにオーディオで応答する

以下は、サウンドのリストを表示するAPLドキュメントです。これはリスト内の項目ごとにオーディオを再生するの例と似ています。この例では、カスタムコンポーネントではなくレスポンシブ対応コンポーネントのAlexaTextListItemを使用して、コンテンツの全体的な外観を改良しています。ユーザーがリスト項目をタップしたときに実行するコマンドは、AlexaTextListItemprimaryActionプロパティで指定しています。

リスト項目にAlexaTextListItemを使用する改良されたSequence(Alexaで読み上げ中の項目がハイライト表示される)
リスト項目にAlexaTextListItemを使用する改良されたSequence(Alexaで読み上げ中の項目がハイライト表示される)

音声リクエストにオーディオで応答する

ユーザーは、画面でコンテンツを視聴している場合でも、音声でAlexaと対話できることを期待しています。たとえば、項目のリストを表示しているときに、「2番目を選んで」などの発話で特定の項目がリクエストされる場合があります。

APLコンテンツに関連する音声リクエストをキャプチャするインテントを作成します。ドキュメントに埋め込まれたオーディオを使用してインテントに応答するには、Alexa.Presentation.APL.ExecuteCommandsディレクティブを使用して、SpeakItemまたはSpeakListを呼び出します。スキルがExecuteCommandsディレクティブを返すと、Alexaはまず応答のoutputSpeechを読み上げてから、指定されたコマンドを呼び出します。

サウンドのリストを表示する先ほどの例であれば、次のように複数のインテントを追加して、視覚コンテンツを音声で完全に操作できるようにします。

  • ビルトインインテントのAMAZON.SelectIntentを使用して、ユーザーがリストの特定の項目をリクエストできるようにします。ユーザーは、「4番目の項目を選んで」などのフレーズを使用できます。 AMAZON.SelectIntentは、選択した項目に関する情報を含むIntentRequestをスキルに送信します。
  • カスタムインテントを作成して、ユーザーがリスト全体の読み上げをリクエストできるようにします。たとえば、このインテントに「サンプルサウンドを全部聴かせて」「このリストを読んで」などの発話を追加することができます。
  • スロットを含むカスタムインテントを作成し、ユーザーが項目を名前でリクエストできるようにします。これにより、ユーザーは「鳥が鳴く森1のサウンドを再生して」などの発話を使用できます。 このインテントのスロットを使用して、再生するサウンドの名前を収集します。

これらのインテントごとに、スキルでExecuteCommandsディレクティブと、SpeakListまたはSpeakItemのいずれかのコマンドを使用して応答します。

例: 1つのリスト項目のオーディオを使用してAMAZON.SelectIntentに応答する

ビルトインのAMAZON.SelectIntentインテントには、ListPositionというスロットが含まれています。このスロットは、リスト項目の位置を示す序数をキャプチャして、それを数値に変換します。ユーザーが「3番目を選んで」と言った場合、ListPositionスロットの値は3になります。

また、以下の両方を満たす場合、ListPositionスロットではリスト項目のコンポーネントIDも取得できます。

  • ユーザーがリクエストした項目が画面に表示されている。
  • 項目のコンポーネントにIDが定義されている。

このインテントとスロットを使用して、ユーザーがリクエストした特定の項目をキャプチャし、ExecuteCommandsで応答して、その項目に関連付けられているspeechを再生できます。

次のハンドラーは、以下の両方の条件が満たされた場合に実行されます。

ハンドラーは、ユーザーがリクエストした項目をListPostionスロットから取得し、ExecuteCommandsで応答して、選択された項目に関連付けられているオーディオを再生します。