# SoftBank Robotics documentation What's new in NAOqi 2.8?

# ALAnimatedSpeech

NAOqi Audio - Overview | API

## What it does

The ALAnimatedSpeech module allows you to make the robot talk in an expressive way.

Options

- You can create more lively speech by annotating the text yourself with some instructions or by adding animations for some words with ALSpeakingMovement.
- You can also disable ALSpeakingMovement by the API of this module or by calling the ^mode instruction so that the robot only executes your instructions and does not move outside of them.

For further details, see: ALSpeakingMovement.

## How it works

A - The ALAnimatedSpeech module receives a text that can be annotated with instructions.

B - It splits the text into little chunks.

C - It analyzes the text and annotates the things he recognizes to choose contextual moves.

D - Any part of the text which is not annotated with animations is filled with animations launched by ALSpeakingMovement.

E - The module prepares the robot to execute each instruction so that it can be executed as soon as it is needed. This enables speech and instructions to be well synchronized.

F - The ALAnimatedSpeech module makes the robot say the text and keeps an eye on the speech to launch instructions at the right time.

### Annotated text

The annotated text is a string combining text to be said and Instructions managing behaviors.

For example, you could send:

    "Hello! ^start(animations/Stand/Gestures/Hey_1) Nice to meet you!"

In this case:

- The robot says “Hello!”.
- Then, simultaneously, the robot:
  - starts the execution of the `animations/Stand/Gestures/Hey_1` animation and,
  - says “Nice to meet you!”.
- Once the text is said, the robot stops abruptly the execution of the `animations/Stand/Gestures/Hey_1` animation.

If you want it to keep running, you can add a ^wait instruction at the end:

    "Hello! ^start(animations/Stand/Gestures/Hey_1) Nice to meet you ^wait(animations/Stand/Gestures/Hey_1)"

### Instructions

The following instructions allow you to do some actions during the course of a speech.

Warning

All those instructions are local to the sentence currently said.

So:

- ^mode will not change the global speaking movement mode.
- All the animations started by: ^start, ^startTag, ... will be stopped at the end of the speech.

#### Speaking Movement Modes

Use ... | To ...
--- | ---
^mode( speaking_movement_mode ) | Change the speaking movement mode for the current text. speaking_movement_mode can be “disabled”, “random” or “contextual”

Example

    "Hello. Look I can stop moving ^mode(disabled) and after I can resume moving ^mode(contextual), you see ?"

For further details, see: Speaking Movement Modes.

#### Animations

Use ... | To ...
--- | ---
^run( animation_full_name ) | Suspend the speech, run an animation and resume the speech.
^start( animation_full_name ) | Start an animation.
^stop( animation_full_name ) | Stop an animation.
^wait( animation_full_name ) | Suspend the speech, wait for the end of the animation and resume the speech.

Examples

    "^start(animations/Stand/Gestures/Enthusiastic_4) Look what I can do while speaking!"

    "^start(animations/Stand/Gestures/Enthusiastic_4) Look what I can do while speaking! ^stop(animations/Stand/Gestures/Enthusiastic_4) Now I am animated by the ALSpeakingMovement module"

    "^start(animations/Stand/Gestures/Hey_1)Hi, guys! ^wait(animations/Stand/Gestures/Hey_1)"

Note

It is highly recommended to use one of the animations available by default on the robot. Fur further details, see: Default Animation library.

If you nevertheless need to create a new one, make sure you comply all the recommendations given in ALAnimationPlayer documentation. For further details, see: Animation Paths and Animation requirements.

#### Tagged animations

Use ... | To ...
--- | ---
^runTag( tag_name ) ^runTag( path, tag_name ) | Suspend the speech. Run an animation which has the mentioned tag. If a path is specified, only the animations that begins with the mentioned path can be choosen. Resume the speech. Chooses randomly the animation which will be started among all the animations which have the mentioned tag.
^startTag( tag_name ) ^runTag( path, tag_name ) | Start an animation which has the mentioned tag. If a path is specified, only the animations that begins with the mentioned path can be choosen. Chooses randomly the animation which will be started among all the animations which have the mentioned tag.
^stopTag( tag_name ) ^stopTag( path, tag_name ) | Stop an animation which has the mentioned tag. If a path is specified, only the animations that begins with the mentioned path can be stopped.
^waitTag( tag_name ) ^waitTag( path, tag_name ) | Suspend the speech. Wait for the end of the animation which has the mentioned tag. If a path is specified, only the animations that begins with the mentioned path can be waited. Resume the speech.

Examples

    "^startTag(me) My name is Nao."

    "^startTag(hello) Hello. ^waitTag(hello)"

    "^startTag(hello) Hello Paul, nice to meet you. ^stopTag(hello) My name is Nao."

    "^startTag(animations/Stand, hello) Hello. ^waitTag(animations/Stand, hello)"

For further details, see : Tags.

#### Sounds

Use ... | To ...
--- | ---
^runSound( soundSet/soundFile ) ^runSound( soundSet/soundFile, soundVolume ) | Suspend the speech, play a sound and resume the speech. soundVolume is an integer between 0 and 100. (by default it’s 100)
^startSound( soundSet/soundFile ) ^startSound( soundSet/soundFile, soundVolume ) | Play a sound in background. The volume is an integer between 0 and 100. (by default it’s 100)
^stopSound( soundSet/soundFile ) | Stop a sound.
^waitSound( soundSet/soundFile ) | Suspend the speech, wait for the end of the sound and resume the speech.

Examples

    "^startSound(my_sound_set/my_sound) That's cool."

    "^startSound(my_sound_set/my_sound, 50) That's cool. ^waitSound(my_sound_set/my_sound)"

    "That's cool. ^runSound(my_sound_set/my_sound) "

For further details, see: Soundset.

#### NAOqi API

Use ... | To ...
--- | ---
^pCall( ALModule.method(args) ) | Call asynchronously any NAOqi method.
^call( ALModule.method(args) ) | Call synchronously any NAOqi method.
$ my_event = my_value | Raise an ALMemory event.

Examples

    "^pCall(ALMotion.wakeUp()) Ok, I wake up."

    "While, I am speaking, $my_event=my_value I can raise an event."

Note

`$my_event=my_value` is equivalent to `^pCall(ALMemory.raiseEvent("my_event", "my_value"))`.

## Features inherited from other modules

### Add your own animations

You can install your own behaviors through the Application Manager panel and uses them in your text.

Warning

As you can call your own behaviors in an annotated text, you could call a behavior which is not an animation. But we advise you to only annotate text with animations. Also we strongly recommend you to set the resources of your behaviors before you start using them in an annotated text.

For further details, see: Creating an animation.

### Animation started from the speech sentence

ALAnimatedSpeech uses the ALAnimationPlayer module to play your animations during speech.

For further details, see: ALAnimationPlayer.

### Animation autonomously started

ALAnimatedSpeech uses the ALSpeakingMovement module to autonomously start animations during the speech when a sentence has no animations specified.

For further details, see: ALSpeakingMovement.

### Voice customization

As ALAnimatedSpeech uses the ALTextToSpeech module to say the text, you can customize the voice of the robot.

For further details, see: ALTextToSpeech.

### Sound managing

ALAnimatedSpeech uses the ALAudioPlayer module to play the sounds.

For further details, see: ALAudioPlayer.

## Getting started

To discover the basic functions of the animated speech using Choregraphe, see the tutorial: Testing the Body language.

Glossary Site map Index Support Contact Legal Notices