基本コンポーネントのプロパティ（APL for Audio）

基本コンポーネントのプロパティ（APL for Audio）

コンポーネントは、Alexaがドキュメントをインフレートするときにオーディオクリップを生成するプリミティブ要素です。たとえば、Speechコンポーネントで音声に変換するテキストを定義します。Audioコンポーネントで再生するオーディオファイルを識別します。その他のコンポーネントにより、さまざまな方法で音声とオーディオを組み合わせたり、配置したりできます。

プロパティ

すべてのコンポーネントは、次のプロパティをサポートしています。

プロパティ 型 デフォルト 説明
bind バインドの配列 [] データバインディングコンテキストに追加する式です。
description 文字列 "" このコンポーネントの任意の説明です。
duration 文字列 auto コンポーネントの長さを調整するためのオプションです。autoまたはtrimToParentに設定します。
id 文字列 "" コンポーネントに指定する固有のIDです。ほかのコンポーネントがこのコンポーネントを参照するときに使用します。
type 文字列 必須 コンポーネントの型です。
when ブール値 true trueの場合、ドキュメントはこのコンポーネントをインフレートします。falseの場合、ドキュメントはこのコンポーネントとすべての子コンポーネントを無視します。

デフォルト列は、プロパティのデフォルト値を示します。レンダリングするコンポーネントに必要なすべてのプロパティを設定する必要があります。

bind

コンポーネントのbindプロパティは、コンポーネントとその子コンポーネントのデータバインディングコンテキストを展開します。bindプロパティでは、現在のコンテキストを展開するデータバインディングを順序付きで指定します。バインディングには順序があり、以前のバインディングの定義を、それ以降のバインディングで使用できます。

bindプロパティの評価は、コンポーネントのwhenプロパティとその他のプロパティとの間に行われます。

バインディング配列の各バインディングオブジェクトには、次のプロパティが含まれます。

プロパティ 型 デフォルト 説明
name 文字列 必須 このバインディングで使用する名前です。有効な名前を設定する必要があります。
value 任意 必須 このバインディングに割り当てる値です。
type any、Boolean、文字列、または数値 any プロパティの型です。

以下は、以前のバインディングの結果を以降のバインディングがどう利用できるかの例です。

{
  "type": "Speech",
  "bind": [
    {"name":"FirstName","value":"ジャスミン"},
    {"name":"LastName","value":"スミス"},
    {"name":"Title","value":"博士"},
    {"name":"FormalName","value":"${LastName}${Title}"}
  ],
  "content": "${FirstName}さん、または${FormalName}のどちらでお呼びしますか？"
}

この例では、FormalNameの内容は、それより前に定義されたTitleとLastNameの値によって決まります。最終的にこのテキストは、「ジャスミンさん、またはスミス博士のどちらでお呼びしますか？」となります。 この例では仮の値を使っています。実際には、FirstName、LastName、Titleの値が生データ内の要素とバインドされます。

バインドされたプロパティ名を大文字にし、固有コンポーネントプロパティとのコンフリクトを回避します。たとえば、myCounterではなく、MyCounterやMY_COUNTERのような名前にします。

description

APLドキュメント用にコンポーネントを説明する文字列です。ドキュメントのコンテキストにコンポーネントの説明を含めることで、ドキュメントが読みやすく、理解しやすくなります。説明は、コンポーネントのレンダリング結果には影響しません。

duration

コンポーネントの長さを調整するためのオプションです。このプロパティは、コンポーネントがMixerコンポーネントで子コンポーネントとして使用されている場合に適用されます。

このプロパティーを次のいずれかの値に設定します。

  • auto – コンポーネント自然な継続時間が適用されます。
  • trimToParent – コンポーネントのdurationと一致するようにコンテンツをトリミングします。

コンポーネントの自然な継続時間は、オーディオフィルターを適用した後のコンポーネントによって生成されたオーディオクリップの時間です。例えば、長さが10秒のオーディオファイルを持つAudioコンポーネントの自然な継続時間は10秒です。AudioコンポーネントにもrepeatCountが1に設定されたRepeatフィルターがある場合は、自然な継続時間は20秒になります。

親であるMixerコンポーネントの継続時間は、durationがautoに設定されている子コンポーネントの継続時間のうち最も長いものに合わせて延長されます。たとえば、5秒続くSpeechコンポーネントと、10秒続くAudioコンポーネントを持つMixerコンポーネントがあるとします。これらのコンポーネントの両方がdurationにautoを使用する場合、このコンポーネントの継続時間は10秒です。

以下は、すべての子コンポーネントのdurationがデフォルトのautoに設定されているMixerの例です。このMixerでは、10秒間続くオーディオクリップが生成されます。

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

{
  "type": "Mixer",
  "items": [
    {
      "type": "Speech",
      "content": "この読み上げが5秒続くとします"
    },
    {
      "type": "Audio",
      "description": "このオーディオファイルが10秒続くとします。",
      "source": "https://example.com/audio/ten-second-audio-file.mp3"
    }
  ]
}

auto

durationがautoの場合、コンポーネントでは調整が行われることなく、コンポーネントの自然な継続時間が適用されます。先ほどの例では、Mixerによりバックグラウンドオーディオで音声が再生され、オーディオが10秒間フルで再生されます。

trimToParent

durationがtrimToParentの場合、Alexaはそのコンポーネントの親コンポーネントの継続時間に合わせて、コンポーネントで生成されるオーディオをトリミングします。たとえば、5秒続くSpeechコンポーネントと、10秒続くAudioコンポーネントを持つMixerがあるとします。AudioコンポーネントのdurationをtrimToParentに設定すると、親コンポーネントの継続時間はSpeechコンポーネントの継続時間と同じになります。そのため、AlexaはAudioコンポーネントの再生を5秒に切り詰めます。

以下は、AudioコンポーネントがtrimToParentに設定されているMixerの例です。このMixerでは、5秒間続くオーディオクリップが生成されます。

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

{
  "type": "Mixer",
  "items": [
    {
      "type": "Speech",
      "content": "この読み上げが5秒続くとします"
    },
    {
      "type": "Audio",
      "description": "このオーディオファイルが10秒続くとします。",
      "source": "https://example.com/audio/ten-second-audio-file.mp3",
      "duration": "trimToParent"
    }
  ]
}

trimToParentの時間設定は、コンポーネントの継続時間が既に親コンポーネントの継続時間よりも短い場合は無効となります。

Mixerのすべての子コンポーネントのdurationがtrimToParentに設定されている場合、Alexaは子コンポーネントの自然な継続時間のうち最も短いものを使用して、親コンポーネントの継続時間を決定します。

id

ドキュメントで特定のコンポーネントを参照できるように、開発者が割り当てる文字列値です。idに指定できる有効な文字は[_a-zA-Z0-9]+です。id は一意である必要はありませんが、一意の値を割り当てることをお勧めします。

type

インフレートするコンポーネントまたは合成を指定します。

APL for Audioは、以下のプリミティブコンポーネントをサポートします。

APL for Audioの合成は、コンポーネントを組み合わせて新しいカスタムコンポーネントを作成します。合成したカスタムコンポーネントは再利用できます。typeプロパティには合成の名前を指定します。合成の詳細については、合成を参照してください。

typeプロパティは必須です。

when

trueの場合、コンポーネントをインフレートします。falseの場合、コンポーネントとすべての子コンポーネントが無視されます。

指定しない場合、whenはデフォルトのtrueになります。

APL for Audioで利用可能なコンポーネント

次のコンポーネントを利用できます。

Audioコンポーネントにフィルターを適用して、ストリーミング中にオーディオクリップを変更できます。詳細については、フィルターを参照してください。

コンポーネントの組み合わせ

複数のコンポーネントを組み合わせて使用することで、さまざまなオーディオエフェクトを作成できます。

  • 複数子コンポーネントはそれぞれ、itemsプロパティを持ち、レンダリングするコンポーネントの配列を受け取ります。
    • Mixerは、子コンポーネントを同時に再生します。
    • Sequencerは、子コンポーネントを順番に再生します。

    詳細については複数子コンポーネントのプロパティを参照してください。

  • Selectorも、コンポーネントの配列を受け取るitemsプロパティを持ちます。Selectorは、配列のコンポーネントを1つだけレンダリングします。詳細については、Selectorを参照してください。