qc_speak :: QUARC MATLAB Functions

navigation bar

qc_speak

Speaks formatted text.

Syntax

[code_units, num_fields, ...] = qc_speak(voice, max_code_units, format_string, ...)
[code_units, num_fields, ...] = qc_speak(max_code_units, format_string, ...)

Description

This function speaks formatted text. It is the like the C printf function except that it reads the formatted text using voice synthesis. The function does not return until the speech is finished. If no voice is specified then a default voice is used.

Parameters

voice

Either a string or a structure. If it is a string then it must be the name of a voice, such as 'Microsoft Anna'. Use the qc_get_voices function to get a list of available voices.

If it is a structure, then it may contain any or all of the following fields:

Field Name	Description
name	The name of the voice, such as 'Microsoft Anna'.
language	The language for the voice as a culture code, such as 'en-US', or as a hexadecimal language identifier, such as '409'.
gender	The gender for the voice. Valid values are 'male' or 'female'.
age	The age for the voice. Valid values are 'child', 'teen', 'adult' or 'senior'.
volume	The volume for the voice. Valid values range from 0 to 100, indicating a percentage. A value of zero indicates no sound at all, while 100 means full volume.
rate	The rate for the voice. Valid values range from -10 to 10. A value of -10 indicates the slowest speed, zero is the natural speed, while 10 means the fastest speed.
pitch	The pitch for the voice. Valid values range from -10 to 10. A value of -10 indicates the lowest pitch, zero is the natural pitch, while 10 means the highest pitch voice.

If no name field is specified, then the language, gender and age fields are used to find the closest match for the voice. Since the selection of voices available is often quite limited, the match may not be that close. Language takes priority over gender, while gender takes priority over age in the search.

If a name field is specified then it overrides the language, gender and age fields.

The volume, rate and pitch fields may be used to control the volume, rate and pitch of the voice respectively.

max_code_units

The maximum number of code units to speak. The text will be truncated if this limit would be exceeded.

format_string

A format string akin to the C library function printf. Note however that more options are available, such as the ability to print arrays using a single format specifier. Refer to Format Strings for Printing for details on format strings.

...

Additional arguments corresponding to each format specifier in the format string.

Outputs

code_units

The number of code units actually spoken, which may be less than max_code_units.

num_fields

The number of fields actually spoken completely, which may be less than the number of fields in the format string if the output was truncated due to the max_code_units being exceeded.

...

Additional output arguments corresponding to %n format specifiers in the format string.

Examples

Speech Using Default Voice

            qc_speak(80, 'Value of pi is %lg', pi);

Speech Using Named Voice

            qc_speak('Microsoft Anna', 80, 'Hello world!');

Speech Using Closest Voice

            voice.language = 'en-US';
            voice.gender   = 'female';
            voice.age      = 'adult';
            voice.volume   = 50;
            voice.rate     = -2;
            voice.pitch    = 3;
            
            qc_speak(voice, 80, 'A quieter, slower, higher pitched voice');