(Page 5 of 7 in this chapter)

2.4 Speaking Text

When text-to-speech services are set up, applications can use functions in the NaturalText API to perform text-to-speech conversion. NaturalText provides functions for: Starting and stopping speech (including pausing and resuming speech). Modifying and navigating through active speech.

2.4.1 Starting and Stopping Speech

Applications can perform text-to-speech conversion by calling the function ttsSpeak. Calls to ttsSpeak specify the CT Access handle of an open context of text-to-speech and a pointer to a memory resident buffer. Because NaturalText reads and speaks one text buffer at a time, applications must wait for TTSEVN_SPEAK_DONE events before submitting new buffers.
In the following example NaturalText takes text from a fixed buffer to pronounce the phrase, "The eagle has landed":

char* text = "The eagle has landed"; /* Text to speak */
CTAHD ctahd; /* CTA handle */ /*...*/ ttsSpeak( ctahd, text ); /*...*/
Applications can pause or stop active speech with the functions ttsPause or ttsStop. ttsPause interrupts speech and retains the current buffer. When applications resume speech with ttsResume, speech continues from the point where it was interrupted.
ttsStop interrupts speech and releases the current text buffer. When applications start speech again (with ttsSpeak), speaking starts at the beginning of a specified buffer.
The following functions start and stop NaturalText speech:

If you want to...

Then use this function...

Speak text from a buffer

ttsSpeak

Stop speech (release text buffer)

ttsStop

Pause active speech

ttsPause

Resume paused speech

ttsResume

If you want to...	Then use this function...
Speak text from a buffer	`ttsSpeak`
Stop speech (release text buffer)	`ttsStop`
Pause active speech	`ttsPause`
Resume paused speech	`ttsResume`

2.4.2 Modifying Active Speech

Calls to ttsSetPitch, ttsSetGain, and ttsSetSpeed modify speech pitch, volume, and speed. These functions establish new settings for particular speech characteristics, rather than adjusting existing settings. For example, specifying 50 words per minute within a ttsSetSpeed call, sets the rate of speech at 50 words per minute, rather than increasing the speed by 50 words per minute. Applications can track current speech settings internally, or obtain these settings by calling ttsGetStatus.
Calls to ttsJump move speech forward or backward a specific number of bytes in a text buffer (rounded to the closest word). A jump cannot exceed the bounds of a buffer. If a jump reaches the end of a buffer, the last word is spoken.
Note: The functions described above cannot take effect while speech is paused or stopping.
The following code sample illustrates how to modify speech characteristics and navigate within spoken text:

#define GAIN_DELTA ((short)12) #define PITCH_DELTA ((short)15) #define SPEED_DELTA ((short)50) #define JUMP_DELTA ((short)60) TTS_STATUS tts_status; TTSRETCODE rc; /* ... Code not shown has retrieved a digit event. The * value of the digit pressed is in event.value */ rc = ttsGetStatus( ctahd, &tts_status, sizeof(TTS_STATUS) ); if( rc == SUCCESS ) { switch( (char)event.value ) { case '1': /* Speak louder */ ttsSetGain( ctahd, tts_status.gain += GAIN_DELTA ); break; case '2': /* Speak softer */ ttsSetGain( ctahd, tts_status.gain -= GAIN_DELTA ); break; case '4': /* Speak faster */ ttsSetSpeed( ctahd, tts_status.speed += SPEED_DELTA ); break; case '5': /* Speak slower */ ttsSetSpeed( ctahd, tts_status.speed -= SPEED_DELTA ); break; case '7': /* Speak with a higher pitch */ ttsSetPitch( ctahd, tts_status.pitch += PITCH_DELTA ); break; case '8': /* Speak with a lower pitch */ ttsSetPitch( ctahd, tts_status.pitch -= PITCH_DELTA ); break; case '3': /* Jump forward */ ttsJump( ctahd, JUMP_DELTA ); break; case '6': /* Jump backward */ ttsJump( ctahd, -JUMP_DELTA ); break; case '0': /* Stop */ ttsStop( ctahd ); break; case '*': /* Pause */ ttsPause( ctahd ); break; case '#': /* Resume */ ttsResume( ctahd ); break; } }
The table below shows NaturalText functions for controlling active speech: To... Use this function... Change speech volume ttsSetGain Change speech pitch ttsSetPitch Change speech speed ttsSetSpeed Jump forward or backward in spoken text ttsJump

To...	Use this function...
Change speech volume	`ttsSetGain`
Change speech pitch	`ttsSetPitch`
Change speech speed	`ttsSetSpeed`
Jump forward or backward in spoken text	`ttsJump`

(Page 5 of 7 in this chapter)

tech_support@nmss.com