SpeakItem Command

Speak the content provided in the speech property for the component. Scrolls or pages the component into view if it isn't already visible.

Properties

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

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, last, center, visible

visible

The alignment of the item after scrolling. Defaults to "visible".

componentId

Selector

:source

The component to read.

highlightMode

line, block

block

How karaoke is applied: on a line-by-line basis, or to the entire block. Defaults to "block".

minimumDwellTime

Integer

0

The minimum number of milliseconds that an item will be highlighted.

The following example shows the SpeakItem command that reads the contents of a single text component and aligns the text in the center of the screen:

{
  "type": "SpeakItem",
  "componentId": "myJokeSetup",
  "highlightMode": "line",
  "align": "center"
}

The SpeakItem 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 component to read. When not provided, defaults to :source. The :source selector targets the component that issued the SpeakItem command.

highlightMode

Controls how contents of a Text component are styled during speech. If set to "block", the entire Text component has the karaoke state set to true during speech. If highlightMode is set to "line", the individual lines of the Text component are treated separately. Each line will scroll to match the align property and be styled separately.

In line-by-line karaoke mode, the only styling change accepted is the color property; other properties are ignored.

When a component other than a Text component is the recipient of SpeakItem, the highlightMode is ignored.

minimumDwellTime

The minimum amount of time in milliseconds to highlight an item.

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 SpeakItem command.

Set the speech property on the component

Set the speech property of the component to the output of a transformer that converts to speech, such as the ssmlToSpeech, textToSpeech, or aplAudioToSpeech transformer.

When the component doesn't have a speech property, the SpeakItem command scrolls the component into view, but doesn't render any speech.

SpeakItem and karaoke

The SpeakItem command sets the karaoke state of the component to true during the speech and then sets it back to false after the speech completes. Use the karaoke component state in a style to change the visual look of the component during speech.

The highlightMode property applies to Text components. When Alexa reads a Text component in "highlightMode": "line" mode, individual lines of text are set to the karaoke state during speech and reset to false after speech completes.

Note the following restrictions:

  • The SpeakItem command doesn't scroll the content during speech in block mode. For example, if the component is larger than the scrolling container of the component, those parts of the component that aren't visible after scrolling remain hidden.
  • Components on round screens should use center alignment, or much of the content won't be visible.
  • SpeakItem doesn't highlight individual words or lines of text during speech when highlightMode is block.
  • The algorithm used to scroll the item into view assumes there is only a single scrolling component. Nested scrolling components aren't supported.
  • Components without a speech property scroll into view, but don't render any speech.
  • The SpeakItem stops during configuration changes, such switching the orientation on a tablet.

When a SpeakItem command stops early, it clears any visual changes and stops speech immediately.

Reinflation strategy

When the Reinflate command runs, the SpeakItem 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 target component.

If the target component isn't in the reinflated hierarchy, then audio stops and the command is ignored.

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

  • The component scrolls into view
  • The karaoke state for the component updates to true
  • Any line-by-line highlighting resumes
Was this page helpful?

Last updated: frontmatter-missing