APL for Audio Reference

Alexa Presentation Language (APL) for Audio lets you create rich audio experiences for use within your custom skills. Use the APLA document type to define these experiences.

Use the following links to access the reference material relevant to APL for audio.

Documents

APL for audio uses the APLA Document format for sending an audio response to the device. The APLA document defines and arranges a set of audio clips. You build these audio clips from text-to-speech and audio files using APL components. All Alexa devices can play the audio response defined by these clips.

Data sources and data-binding

APL for audio uses data-binding to incorporate user-provided data, include audio resources, and conditionally inflate components based on data. To use data-binding in your document, you write data-binding expressions, which are JSON strings with an embedded ${...} substring.

See the following topics for details about data sources and data-binding for APL for audio:

Components

APL for audio uses APL components to define audio clips. 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.

All components have the same Base Component Properties.

Components that can render multiple child components also have the common multi-child component properties: Multiple Child Component Properties.

APL for audio supports the following primitive components:

You can use Filters to modify an audio component. For more details, see Filters.

Skill request and response reference

APL for audio supports directives in the Alexa.Presentation.APLA Interface:

Use the authoring tool for APL for audio

The developer console provides an authoring tool to build and preview APL documents. You can write your document and data sources in JSON, and then play the results, and then copy the JSON code into your skill.

To access the authoring tool

  1. Open the skill in the Alexa developer console.
  2. From the left hand navigation, click Multimodal Responses.
  3. At the top, click the Audio filter to display a list of all your APLA documents.
  4. To create a new audio response, select Create Audio Response.

After you update the JSON code for your APL for audio document, you can generate and preview the audio.

To preview an audio response

  1. In the authoring tool, click Preview button to generate the audio the first time.
  2. Click Play to hear the audio response.
  3. As you make changes to the JSON, click Refresh to re-generate the audio response with your changes.

After you generate the audio response, the authoring tool displays a time line that represents the audio. You can navigate this time line to play back portions of your response.

Audio time line displayed after you click Refresh
Audio time line displayed after you click Preview
UI element Description

Refresh button

Refresh button – Click to regenerate the audio response. You must regenerate the response to reflect your changes to the JSON.

Play button

Play button – Click to play back the response.

Repeat button

Repeat button – Click to repeatedly play the entire response or a portion of the response. Click again to turn off the repeat.

Audio response time line

Audio response time line – Displays a wave form representing the audio response. You can click within the time line to listen to different parts of the response.

  • To start playback from a different position or jump to a different position during playback, click in the time line.
  • To select a portion of the response to play, click and drag in the time line.
  • To move a previously-selected portion of the response to a different section of the time line, click and drag the selection.
  • To clear a previously-selected portion of the response, click inside the selected area.