Base Component Properties (APL for Audio)

Note: Learn how to improve your skills with APL with Build visually rich experiences using APL at the Alexa Learning Lab.

A component is a primitive element that generates an audio clip when Alexa inflates your document. For example, a Speech component defines text to convert to speech. The Audio component identifies an audio file to play. Other components let you mix and arrange the speech and audio in different ways.

Properties

All components support the following properties.

Property	Type	Default	Description
`bind`	Array of binding	[]	Expressions to add to the data-binding context.
`description`	String	""	Optional description of this component.
`duration`	String	auto	Specifies options to adjust the duration of the component. Set to `auto` or `trimToParent`.
`id`	String	""	A unique ID you provide for the component, used to refer to the component from other components.
`type`	String	Required	The type of the component.
`when`	Boolean	true	When true, the document inflates this component. When false, the document ignores this component and all of its child components.

The Default column lists the default values of properties. You must set all required properties for the component to render.

bind

The bind property of a component extends the data-binding context for the component and its children. The bind property specifies an ordered set of data-bindings that extend the current context. Bindings are ordered; later bindings can use previous definitions.

The bind property evaluates after the when property for the component and before any other properties.

Each binding object in the binding array contains the following:

Property	Type	Default	Description
`name`	String	Required	The name to use for this binding. Must be a valid name.
`value`	Any	Required	The value to assign to this binding.
`type`	any, Boolean, string, or number	any	Property type.

The following example illustrates how a later binding might use the results from an earlier binding.

{
  "type": "Speech",
  "bind": [
    {"name":"FirstName","value":"Jasmine"},
    {"name":"LastName","value":"Smith"},
    {"name":"Title","value":"Dr."},
    {"name":"FormalName","value":"${Title} ${LastName}"}
  ],
  "content": "Should I call you ${FirstName} or ${FormalName}?"
}

In this example, FormalName depends upon the prior definitions of Title and LastName. The final text is "Should I call you Jasmine or Dr. Smith?" This example is contrived. In actual use, the values of FirstName, LastName, and Title are bound to elements provided in the raw data.

Capitalize your bound property names to avoid conflicts with intrinsic component properties. For example, use MyCounter or MY_COUNTER instead of myCounter.

description

A string that describes the component, for documenting your APL document. Including descriptions for your components in the context of your document makes your document easier to read and understand. The description has no effect on the rendering the component.

duration

Specifies options to adjust the component duration. This property applies when the component is used as a child component in the Mixer component.

Set this property to one of the following values:

auto – Use the intrinsic duration of component.
trimToParent – Trim the content to match with the duration of the parent component.

The intrinsic duration of a component is the duration of the audio clip generated by the component, after applying any audio filters. For example, the intrinsic duration of an Audio component with a 10-second long audio file is 10 seconds. If the Audio component also has a Repeat filter with repeatCount set to 1, the intrinsic duration is 20 seconds.

The duration of a parent Mixer component stretches to match the duration of its longest child component that has duration set to auto. For example, assume a Mixer component with a Speech component that lasts 5 seconds and an Audio component that lasts 10 seconds. When both of these components use auto for the duration, the duration of this component is 10 seconds.

The following example shows a Mixer in which all of the child components use the default auto setting for duration. This Mixer generates an audio clip that lasts for 10 seconds.

Copied to clipboard.

{
  "type": "Mixer",
  "items": [
    {
      "type": "Speech",
      "content": "Assume this speech lasts 5 seconds."
    },
    {
      "type": "Audio",
      "description": "Assume this audio file lasts for 10 seconds.",
      "source": "https://example.com/audio/ten-second-audio-file.mp3"
    }
  ]
}

auto

When duration is auto, a component uses the intrinsic duration of the component without any adjustment. In the previous example, the Mixer plays the speech with the background audio, and the audio plays for the full 10 seconds.

trimToParent

When duration is trimToParent, Alexa trims the audio generated by the component to match the duration of the component's parent component. For example, assume a Mixer with a Speech component that lasts 5 seconds and an Audio component that lasts 10 seconds. If you set duration on the Audio component to trimToParent, the duration of the parent is now the duration of the Speech component. Alexa therefore truncates the playback for the Audio component to 5 seconds.

The following example shows a Mixer with an Audio component set to trimToParent. This Mixer generates an audio clip that lasts for 5 seconds.

Copied to clipboard.

{
  "type": "Mixer",
  "items": [
    {
      "type": "Speech",
      "content": "Assume this speech lasts 5 seconds."
    },
    {
      "type": "Audio",
      "description": "Assume this audio file lasts for 10 seconds.",
      "source": "https://example.com/audio/ten-second-audio-file.mp3",
      "duration": "trimToParent"
    }
  ]
}

The trimToParent duration setting has no effect when the component's duration is already shorter than the parent duration.

When all child components on the Mixer have duration set to trimToParent, Alexa uses the intrinsic duration of the shortest child component to determine the duration of the parent.

Tip: Combine trimToParent with the Repeat filter to match background audio to the exact length of speech. For details, see Repeat.

id

A developer-assigned string value used to refer a particular component in the document. The valid characters in an id are [_a-zA-Z0-9]+. The id isn't required to be unique, but uniqueness is recommended.

type

Specifies the component or composition to inflate.

APL for audio supports the following primitive components:

A composition for APL for audio combines components into a new custom component that you can use and reuse. Specify the name of the composition in the type property. For details about compositions, see Compositions.

The type property is required.

when

When true, inflate the component. When false, ignore the component and all child components.

When not specified, when defaults to true.

Available components for APL for Audio

The following components are available:

You can apply filters to an audio component to modify an audio clip as it streams. For more details, see Filters.

Combine components

Combine multiple components together to create different audio effects.

The multiple-child components each have an items property that accepts an array of components to render.
- Mixer plays the child components at the same time.
- Sequencer plays the child components one after another in sequence.
For details, see Multiple-child Component Properties
Selector also has an items property that accepts an array of components. The Selector renders just one component out of the array. For details, see Selector.

Was this page helpful?

Provide feedback

Last updated: Nov 28, 2023