Important: Inside Macintosh: Sound is deprecated as of Mac OS X v10.5. For new audio development in Mac OS X, use Core Audio. See the Audio page in the ADC Reference Library.
Speech Information Selectors
This section describes the speech information selectors that you can pass in theselector
parameter of theGetSpeechInfo
andSetSpeechInfo
functions.
CONST soCharacterMode = 'char'; {get or set character-processing mode} soCommandDelimiter = 'dlim'; {set embedded command delimiters} soCurrentA5 = 'myA5'; {set A5 on callbacks} soCurrentVoice = 'cvox'; {set speaking voice} soErrorCallBack = 'ercb'; {set error callback} soErrors = 'erro'; {get error information} soInputMode = 'inpt'; {get or set text-processing mode} soNumberMode = 'nmbr'; {get or set number-processing mode} soPhonemeCallBack = 'phcb'; {set phoneme callback} soPhonemeSymbols = 'phsy'; {get phoneme symbols and example } { words} soPitchBase = 'pbas'; {get or set baseline pitch} soPitchMod = 'pmod'; {get or set pitch modulation} soRate = 'rate'; {get or set speech rate} soRecentSync = 'sync'; {get most recent synchronization } { message information} soRefCon = 'refc'; {set reference constant value} soReset = 'rset'; {set channel back to default state} soSpeechDoneCallBack = 'sdcb'; {set speech-done callback} soStatus = 'stat'; {get status of channel} soSyncCallBack = 'sycb'; {set synchronization callback} soSynthExtension = 'xtnd'; {get or set synthesizer-specific } { information} soSynthType = 'vers'; {get synthesizer information} soTextDoneCallBack = 'tdcb'; {set text-done callback} soVolume = 'volm'; {get or set speech volume} soWordCallBack = 'wdcb'; {set word callback}Constant descriptions
soCharacterMode
- Get or set the speech channel's character-processing mode. Two constants are currently defined for the processing mode,
modeNormal
andmodeLiteral
. When the character-processing mode ismodeNormal
, input characters are spoken as you would expect to hear them. When the mode ismodeLiteral
, each character is spoken literally, so that the word "cat" would be spoken "C-A-T". ThespeechInfo
parameter points to a variable of typeOSType
, which is the character-processing mode.- This selector works with
GetSpeechInfo
andSetSpeechInfo
and does not move memory.soCommandDelimiter
- Set the embedded speech command delimiter characters to be used for the speech channel. By default the opening delimiter is "
[[
" and the closing delimiter is "]]
". Your application might need to change these delimiters temporarily if those character sequences occur naturally in a text buffer that is to be spoken. Your application can also disable embedded command processing by passing empty delimiters (2NIL
bytes). ThespeechInfo
parameter is a pointer to a delimiter information record, described on page 4-54.- This selector works with the
SetSpeechInfo
function and does not move memory.soCurrentA5
- Set the value that the Speech Manager assigns to the A5 register before invoking any application-defined callback procedures for the speech channel. The A5 register must be set correctly if the callback procedures are to be able to access application global variables. For more information on the A5 register, see Inside Macintosh: Memory. The
speechInfo
parameter should be set to the pointer contained in the A5 register at a time when the application is not executing interrupt code or toNIL
if your application wishes to clear a value previously set with thesoCurrentA5
selector.- This selector works with the
SetSpeechInfo
function and does not move memory. See Listing 4-6 on page 4-21 for an illustration of the use of this selector.soCurrentVoice
- Set the current voice on the current speech channel to the specified voice. The
speechInfo
parameter is a pointer to a voice specification record. Your application should create the record by calling theMakeVoiceSpec
function, described on page 4-64.SetSpeechInfo
will return anincompatibleVoice
error if the specified voice is incompatible with the speech synthesizer associated with the speech channel. If you have a speech channel open using a voice from a particular synthesizer and you try to switch to a voice that works with a different synthesizer, you receive anincompatibleVoice
error. You need to create a new channel to use with the new voice.- This selector works with only
SetSpeechInfo
and might move memory. Your application should not invoke it at interrupt time.soErrorCallBack
- Set the callback procedure to be called when an error is encountered during the processing of an embedded command. The callback procedure might also be called if other conditions (such as insufficient memory) arise during the speech conversion process. When a Speech Manager function returns an error directly, the error callback procedure is not called. The callback procedure is passed information about the most recent error; it can determine information about the oldest pending error by using the speech information selector
soErrors
. ThespeechInfo
parameter is a pointer to an application-defined error callback procedure, whose syntax is described on page 4-86. PassingNIL
inspeechInfo
disables the error callback procedure.- This selector works with the
SetSpeechInfo
function and does not move memory.soErrors
- Get saved error information for the speech channel and clear its error registers. This selector lets you poll for various run-time errors that occur during speaking, such as the detection of badly formed embedded commands. Errors returned directly by Speech Manager functions are not reported here. If your application defines an error callback procedure, the callback should use the
soErrors
selector to obtain error information. ThespeechInfo
parameter is a pointer to a speech error information record, described on page 4-49.- This selector works with the
GetSpeechInfo
function and does not move memory.soInputMode
- Get or set the speech channel's current text-processing mode. The returned value specifies whether the channel is currently in text input mode or phoneme input mode. The
speechInfo
parameter is a pointer to a variable of typeOSType
, which specifies a text-processing mode. The following constants specify the available text-processing modes:CONST modeText = 'TEXT'; modePhonemes = 'PHON';
- The
modeText
constant indicates that the speech channel is in text-processing mode. ThemodePhonemes
constant indicates that the speech channel is in phoneme-processing mode. When in phoneme-processing mode, a text buffer is interpreted to be a series of characters representing various phonemes and prosodic controls, as discussed in "Phonemic Representation of Speech" on page 4-32 and "Prosodic Control Symbols" on page 4-34. Some synthesizers might support additional input-processing modes and define constants for these modes.- This selector works with both the
GetSpeechInfo
andSetSpeechInfo
functions. It might move memory only when used in conjunction with theSetSpeechInfo
function.soNumberMode
- Get or set the speech channel's current number-processing mode. Two
OSType
constants are currently defined,modeNormal
andmodeLiteral
. When the number-processing mode ismodeNormal
, the synthesizer assembles digits into numbers (so that 12 is spoken as "twelve"). When the mode ismodeLiteral
, each digit is spoken literally (so that 12 is spoken as "one, two"). ThespeechInfo
parameter is a pointer to a variable of typeOSType
, which specifies the number-processing mode.- This selector works with both the
GetSpeechInfo
andSetSpeechInfo
functions and does not move memory.soPhonemeCallBack
- Set the callback procedure to be called every time the Speech Manager is about to generate a phoneme on the speech channel. The
speechInfo
parameter is a pointer to an application-defined phoneme callback procedure, whose syntax is described on page 4-87. PassingNIL
inspeechInfo
disables the phoneme callback procedure.- This selector works with the
SetSpeechInfo
function and does not move memory.soPhonemeSymbols
- Get a list of phoneme symbols and example words defined for the speech channel's synthesizer. Your application might use this information to show the user what symbols to use when entering phonemic text directly. The
speechInfo
parameter is a pointer to a variable of type Handle that, on exit from theGetSpeechInfo
function, is a handle to a phoneme descriptor record, described on page 4-53.- This selector works with the
GetSpeechInfo
function and might move memory. Your application should not invoke it at interrupt time.soPitchBase
- Get or set the speech channel's baseline speech pitch. This selector is intended for use by the Speech Manager; ordinarily, an application uses the
GetSpeechPitch
andSetSpeechPitch
functions, described on page 4-75 and page 4-76, respectively. ThespeechInfo
parameter is a pointer to a variable of typeFixed
.- This selector works with both the
GetSpeechInfo
andSetSpeechInfo
functions and does not move memory.soPitchMod
- Get or set a speech channel's pitch modulation. The
speechInfo
parameter is a pointer to a variable of typeFixed
. Pitch modulation is also expressed as a fixed-point value in the range of 0.000 to 127.000. These values correspond to MIDI note values, where 60.000 is equal to middle C on a piano scale. The most useful speech pitches fall in the range of 40.000 to 55.000. A pitch modulation value of 0.000 corresponds to a monotone in which all speech is generated at the frequency corresponding to the speech pitch. Given a speech pitch value of 46.000, a pitch modulation of 2.000 would mean that the widest possible range of pitches corresponding to the actual frequency of generated text would be 44.000 to 48.000.- This selector works with both the
GetSpeechInfo
andSetSpeechInfo
functions and does not move memory.soRate
- Get or set a speech channel's speech rate. The
speechInfo
parameter is a pointer to a variable of typeFixed
. The possible range of speech rates is from 0.000 to 65535.65535. The range of supported rates is not predefined by the Speech Manager; each speech synthesizer provides its own range of speech rates. Average human speech occurs at a rate of 180 to 220 words per minute.- This selector works with both the
GetSpeechInfo
andSetSpeechInfo
functions and does not move memory.soRecentSync
- Get the message code for the most recently encountered synchronization command. If no synchronization command has been encountered, 0 is returned. The
speechInfo
parameter is a pointer to a variable of typeOSType
.- This selector works with the
GetSpeechInfo
function and does not move memory.soRefCon
- Set a speech channel's reference constant value. The reference constant value is passed to application-defined callback procedures and might contain any value convenient for the application. The
speechInfo
parameter is a long integer containing the reference constant value. In contrast with other selectors, this selector does not require that thespeechInfo
parameter's value be a pointer value. Typically, however, an application does use this selector to pass a pointer or handle value to callback procedures.- This selector works with the
SetSpeechInfo
function and does not move memory. See Listing 4-6 on page 4-21 for an illustration of the use of this selector.soReset
- Set a speech channel back to its default state. For example, speech pitch and speech rate are set to default values. The
speechInfo
parameter should be set toNIL
.- This selector works with the
SetSpeechInfo
function and does not move memory.soSpeechDoneCallBack
- Set the callback procedure to be called when the Speech Manager has finished generating speech on the speech channel. The
speechInfo
parameter is a pointer to an application-defined speech-done callback procedure, whose syntax is described on page 4-84. PassingNIL
inspeechInfo
disables the speech-done callback procedure.- This selector works with the
SetSpeechInfo
function and does not move memory.soStatus
- Get a speech status information record for the speech channel. The
speechInfo
parameter is a pointer to a speech status information record, described on page 4-48.- This selector works with the
GetSpeechInfo
function and does not move memory.soSyncCallBack
- Set the callback procedure to be called when the Speech Manager encounters a synchronization command within an embedded speech command in text being processed on the speech channel. The
speechInfo
parameter is a pointer to an application-defined synchronization callback procedure, whose syntax is described on page 4-85. PassingNIL
inspeechInfo
disables the synchronization callback procedure.- This selector works with the
SetSpeechInfo
function and does not move memory.soSynthExtension
- Get or set synthesizer-specific information or settings. The
speechInfo
parameter is a pointer to a speech extension data record, described on page 4-53. Your application should set thesynthCreator
field of this record before callingGetSpeechInfo
orSetSpeechInfo
. Ordinarily, your application must pass additional information to the synthesizer in thesynthData
field.- This selector works with both the
GetSpeechInfo
andSetSpeechInfo
functions. Whether it moves memory depends on the synthesizer being used and the information passed to the synthesizer.soSynthType
- Get a speech version information record for the speech synthesizer being used on the specified speech channel. The
speechInfo
parameter is a pointer to a speech version information record, described on page 4-50.- This selector works with the
GetSpeechInfo
function and does not move memory.soTextDoneCallBack
- Set the callback procedure to be called when the Speech Manager has finished processing speech being generated on the speech channel. The
speechInfo
parameter is a pointer to an application-defined text-done callback procedure, whose syntax is described on page 4-84. PassingNIL
inspeechInfo
disables the text-done callback procedure.- This selector works with the
GetSpeechInfo
function and does not move memory.soVolume
- Get or set the speech volume for a speech channel. The
speechInfo
parameter is a pointer to a variable of typeFixed
. Volumes are expressed in fixed-point units ranging from 0.0 through 1.0. A value of 0.0 corresponds to silence, and a value of 1.0 corresponds to the maximum possible volume. Volume units lie on a scale that is linear with amplitude or voltage. A doubling of perceived loudness corresponds to a doubling of the volume.- This selector works with both the
GetSpeechInfo
andSetSpeechInfo
functions and does not move memory.soWordCallBack
- Set the callback procedure to be called every time the Speech Manager is about to generate a word on the speech channel. The
speechInfo
parameter is a pointer to an application-defined word callback procedure, whose syntax is described on page 4-87. PassingNIL
inspeechInfo
disables the word callback procedure.- This selector works with the
SetSpeechInfo
function and does not move memory. See Listing 4-7 on page 4-21 for an illustration of the use of this selector.