SpeakList Command

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

Speak the contents of a range of items inside a common container, such as a Sequence. Each item scrolls into view before Alexa reads the item. The speech property on each item defines the speech to play. If an item doesn't have the speech property set, the item scrolls into view without the accompanying speech.

Properties

The SpeakList command has the properties shown in the following table, in addition to the common command properties. Set the type property to SpeakList.

In the following table, the "Default" column shows "Required" for properties that must have a value for the command to run. Otherwise it displays the default value, which might be none.

Property	Type	Default	Description
`align`	`first`, `center`, `last`, `visible`	`visible`	The alignment of the item. Defaults to `visible`.
`componentId`	Selector	`:source`	The parent component that contains the list of items to read.
`count`	integer	REQUIRED	The number of children to read.
`minimumDwellTime`	number	0	The minimum number of milliseconds that an item will be highlighted for. Defaults to 0.
`start`	integer	REQUIRED	The index of the item to start reading.

The following example reads three components out of the middle of a list and ensures that each aligns in the center of the screen:

{
  "type": "SpeakList",
  "componentId": "movieList",
  "start": 3,
  "count": 3,
  "minimumDwellTime": 700,
  "align": "center"
}

The karaoke state of the component is set to true during the speech of each component and reset to false after that speech completes.

Note these characteristics of the SpeakList command:

The SpeakList command doesn't scroll the content during speech. For example, if the component is larger than the scrolling container of the component, those parts of the component that are not visible after scrolling remain hidden.
Components on round screens should use center alignment, or much of the content isn't visible.
SpeakList does not highlight individual words or lines of text during speech.
To scroll the item into view, the component hierarchy is searched upwards to find the first ancestor that can be scrolled.
The algorithm that scrolls the item into view assumes there is only a single scrolling component. SpeakList doesn't support nested scrolling components.
Components without a speech property still scroll into view.
Components without a speech property, but with a positive minimumDwellTime, have the karaoke state set for that time.
Components without a speech property and no minimumDwellTime won't have karaoke state set.

The SpeakList command is ignored in fast mode.

align

The alignment of the item on the screen after scrolling and before speech. Alignment is an enumerated value with the following options:

Alignment	Description
`first`	The top/left side of the item will be placed at the top/left side of the scrolling container.
`center`	The center of the item will be placed in the center of the container.
`last`	The bottom/right side of the item will be placed at the bottom/right side of the scrolling container.
`visible`	The item will be moved the minimal distance necessary to bring it fully into view.

componentId

A selector that identifies the parent component that contains the child items to read. You can target the following component types:

When not provided, defaults to :source. The :source selector targets the component that issued the SpeakList command.

count

The number of items to speak. The command does not run if the count is less than 1 (no scrolling, no speech). If the count is larger than the number of remaining items in the container, it is trimmed to the maximum number of items that can be spoken from the starting point.

minimumDwellTime

The minimum amount of time in milliseconds that an item will be highlighted (that is, have the karaoke state set to true). This defaults to 0.

The minimumDwellTime prevents items with short titles from being read too quickly. For example, a series of movie titles like "Venom", "Fences", and "Dear Zachary: A Letter to a Son About His Father" sounds better if you provide some dwell time for the first two items.

start

The 0-based index of the first child item in the parent container to scroll into view and speak. Negative values are measured from the end of the parent container. The following example reads the last three items in a list:

{
  "type": "SpeakList",
  "start": -3,
  "count": 3
}

For multi-child components, the SpeakList command can also speak the firstItem and lastItem properties. When the component has a firstItem defined, the index of the firstItem is 0 and the indices of the child components in items start at 1. When the component doesn't have a firstItem defined, the indices of the child components in items start at 0.

The following algorithm approximates how the reading is done.

let first = start < 0 ? start + children.length : start;
   let last = Math.min(first + count, children.length – 1);

first = Math.max(0, first);

for (let index = first ; index <= last ; index++) {
  let child = children[index];
  scrollIntoView(child);

  if (child.speech) {
    child.setState("karaoke", true);
    speakChildWithMinimumDwell(child, minimumDwellTime);
    child.setState("karaoke", false);
  }
  else if (minimumDwellTime > 0) {
    child.setState("karaoke", true);
    waitForTimeout(minimumDwellTime);
    child.setState("karaoke", false);
  }
}

Verify that the environment supports speech

Some environments might not allow dialog, including speech. Use the environment property disallowDialog to determine whether the device and configuration supports speech-related commands.

For example, widgets don't support the SpeakList command.

Reinflation strategy

When the Reinflate command runs, the SpeakList command can resume after Alexa reinflates the document. The command resumes when it runs on a sequencer that is specified in the preservedSequencers array on Reinflate. In this scenario, the Reinflate command doesn't interrupt audio playback. The command saves the current index being read, the minimumDwellTime, and the count of remaining items to read.

If the target component isn't in the reinflated hierarchy or is not an appropriate target of this command, then the audio stops and no more items are read.

If the target component is in the reinflated hierarchy, then the following occurs after reinflation:

The target component scrolls into view
The [karaoke](../alexa-presentation-language/apl-style-definition-and-evaluation.html state for the component updates to true

After this, Alexa reads the remaining number of items as specified by count.

When preserving the SpeakList command, the experience works best when the reinflated hierarchy contains a matching component with the same count and order of items with the same speech bindings. Otherwise, the SpeakList command might read components that the user doesn't expect.

Was this page helpful?

Provide feedback

Last updated: frontmatter-missing