合成（APL for Audio）

合成（APL for Audio）

APL for Audioの合成は、コンポーネントを組み合わせて新しいカスタムコンポーネントを作成します。合成したカスタムコンポーネントは、ドキュメントのメインテンプレート内で再利用できます。合成内で条件付きロジックを使用して、最終オーディオクリップでどのコンポーネントをレンダリングするかを選択できます。合成を使うことでAPLコードをシンプルにし、一貫性を維持することができます。

APLの合成について

合成は、APLドキュメントのcompositionsプロパティで定義します。このプロパティの引数は文字列とオブジェクトのマッピングです。

以下は、JoeyVoiceという合成を1つ含むcompositionsプロパティの例です。合成には、speechContentというパラメーターがあります。この合成には、SSMLを使って音声を生成するspeechContentパラメーターに渡されたコンテンツを使用するSpeechコンポーネントが1つ含まれます。

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

{
  "compositions": {
    "JoeyVoice": {
      "parameters": [
        {
          "name": "speechContent",
          "type": "string"
        }
      ],
      "items": [
        {
          "type": "Speech",
          "contentType": "SSML",
          "content": "<speak><voice name='Joey'><lang xml:lang='en-US'>${speechContent}</lang></voice></speak>"
        }
      ]
    }
  }
}

ドキュメントで合成を使用するには、コンポーネントのtypeとして合成の名前を指定し、すべてのパラメーターを渡します。プリミティブコンポーネントを追加する方法と同様です。以下は、JoeyVoice合成を2回使用する基本のSequencerコンポーネントの例です。使用するたびに、speechContentの値を変えています。

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

{
  "type": "Sequencer",
  "items": [
    {
      "type": "JoeyVoice",
      "speechContent": "このテキストをJoey Voice合成に渡します。"
    },
    {
      "type": "JoeyVoice",
      "speechContent": "合成を1つ作成すると、ドキュメント内で複数回再利用できます。このため、ドキュメントを簡素化できます。"
    }
  ]
}

合成のプロパティ

以下の表は、合成のプロパティを示しています。

プロパティ 型 必須 説明
description 文字列 ✕ この合成の説明です。
item、items コンポーネントの配列 ◯ インフレートする項目です。itemsに配列が含まれる場合、whenがtrueに評価された最初の項目がインフレートされます。
parameters パラメーターの配列 ✕ この合成に渡すパラメーターの配列です。

item、items

オーディオクリップにインフレートするコンポーネントの配列を含みます。itemsに配列が含まれる場合、whenがtrueに評価された最初の項目がインフレートされます。合成はコンポーネントの一種のため、itemsプロパティは、ドキュメントのcompositionsプロパティで定義したほかの合成を参照できます。

配列を使ったデータバインディングの詳細については、配列を使ったデータバインディングを参照してください。

parameters

合成のパラメーターの配列を含みます。各パラメーターは、以下の表のプロパティを持つオブジェクトです。

プロパティ 型 必須 説明
default 任意 ✕ パラメーターを指定しない場合に使用するデフォルト値です。デフォルトは空白です。
description 文字列 ✕ このパラメーターの用途について説明する文字列です。
name 文字列 ◯ パラメーターの名前です。ドキュメントで合成を使うときに、この名前を使ってパラメーターを指定します。パラメーターの名前には、大文字または小文字の英字で始まり、スペースを含まない一意の名前を設定します。
type 型 ✕ パラメーターの期待値の型を定義する文字列です。any、array、boolean、component、integer、map、number、object、stringのいずれかに設定します。デフォルトは、"any"です。

型の強制やデフォルト値を必要としないパラメーターを定義する場合、パラメーターオブジェクトではなくパラメーター名だけを指定できます。たとえば、{"name": "title", ...}の代わりに、"title"だけを指定します。これにより、合成の定義をよりコンパクトにできます。

合成のインフレート

合成は、ほかの合成やコンポーネントのコレクションに拡張可能な関数のように機能します。合成のインフレートアルゴリズムは以下の手順を実行します。

  1. 各parameterを評価し、データバインディングコンテキストに追加します。
  2. 1つの子アルゴリズムを使ってitemsプロパティを評価します。
  3. 合成で定義したパラメーターに一致しないその他のパラメーターをすべて、評価のために合成項目に渡します。

以下は、インフレートアルゴリズムの例です。

まず、Greetingsという合成を、JoeySpeech、IvySpeechの2つのパラメーターで定義します。items配列には、2つのSpeechコンポーネントが含まれており、それぞれにwhen句があります。この合成によって生成された最終的なオーディオクリップは、これらのSpeechコンポーネントのいずれか1つだけを使用します。

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

{
  "compositions": {
    "Greetings": {
      "parameters": [
        {
          "name": "JoeySpeech",
          "type": "string"
        },
        {
          "name": "IvySpeech",
          "type": "string"
        }
      ],
      "items": [
        {
          "type": "Speech",
          "when": "${environment.alexaLocale == 'ja-JP'}",
          "content": "<speak><voice name='Joey'><lang xml:lang='ja-JP'>${JoeySpeech}</lang></voice></speak>"
        },
        {
          "type": "Speech",
          "when": "${environment.alexaLocale != 'ja-JP'}",
          "content": "<speak><voice name='Ivy'><lang xml:lang='ja-JP'>${IvySpeech}</lang></voice></speak>"
        }
      ]
    }
  }
}

合成をインフレートしてオーディオクリップを生成するには、合成をAPLドキュメントのmainTemplateに追加し、パラメーターに値を渡します。この例では、IvySpeech、JoeySpeech、contentTypeという3つのパラメーターを合成に渡しています。

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

{
  "type": "あいさつ",
  "IvySpeech": "こんにちは",
  "JoeySpeech": "やあ",
  "contentType": "SSML"
}

Alexaは、

  • IvySpeechとJoeySpeechをデータバインディングコンテキストに追加するというロジックを使って、この合成をインフレートします。これにより、合成は${IvySpeech}のように、データバインディング表現を使ってこれらの値を参照できます。
  • 1つの子アルゴリズムを使ってitemsプロパティを評価します。ユーザーのロケールがja-JPだとすると、最初のSpeechコンポーネントのwhenプロパティがtrueとなるため、合成はitems配列の最初のコンポーネントを選択します。
  • 定義されたパラメーターに一致しないその他のパラメーターをすべて渡します。この例では、contentTypeは合成内で定義されていません。Alexaは、このパラメーターを選択されたitemに渡します。この例では、Speechコンポーネントが選択されており、SpeechコンポーネントにはcontentTypeプロパティがあります。このため、Speechコンポーネントは指定された"SSML"値を使用します。

このアルゴリズムの最終結果は、次のようなSpeechコンポーネントとなります。

{
    "type": "Speech",
    "contentType": "SSML",
    "content": "<speak><voice name='Joey'><lang xml:lang='ja-JP'>Hi</lang></voice></speak>"
}
このページは役に立ちましたか？

最終更新日: 2020 年 11 月 20 日