HRESULT Phoneme(VOICECHARSET eCharacterSet, DWORD dwFlags,
SDATA dText, PSDATA pdPhoneme);
Converts text to a phonemic representation, which is an intermediate stage between Unicode text and digital-audio data.
· Returns NOERROR if successful, or one of these error values:
<E_INVALIDARG>
<E_OUTOFMEMORY>
<TTSERR_INVALIDCHAR>
<TTSERR_NOTSUPPORTED>
eCharacterSet
[in] Character set to use to convert the text. This parameter can be one of these values:
Value | Meaning |
CHARSET_ENGINEPHONETIC | An engine-specific phonetic character set |
CHARSET_IPAPHONETIC | The International Phonetic Alphabet (IPA) character set |
CHARSET_TEXT cannot be used as the character set for converted text.
dwFlags
[in] TTSDATAFLAG_TAGGED if the text contains text-to-speech control tags that alter inflection, speed, and so on, or NULL if the text does not contain tags. Note that an engine-specific phonetic character set may use a different tagging protocol than that used by the IPA character set. This is left for future expansion.
dText
[in] SDATA structure that contains the address of the null-terminated text string to be converted. If the engine supports the IPA character set, tags can be used to intersperse words written in IPA phonemes with words in the language's character set. The application should not change this memory until the function returns.
pdPhoneme
[out] Address of an SDATA structure that receives a pointer to the phonemic representation of the text using the specified character set. The text string is null-terminated. The character set is wide or multibyte, depending upon the interface used (ITTSCentralW or ITTSCentralA). Engine-specific character sets must follow the wide/multibyte convention.
The calling application allocates the SDATA structure and passes its address to Phoneme. Phoneme allocates memory (using the OLE task allocator) for the returned data and sets the pData member of SDATA to point to the memory. If the allocation fails, the pData member is set to NULL and the dwSize member is set to zero. The calling application must free the memory pointed to by pData, as well as the SDATA structure itself.
This function can be used to adjust the phonetic representation of text before it is spoken by the engine, such as correcting mispronounced words.
Phoneme is synchronous; that is, the member function does not return until the conversion is complete. Depending on the amount of text passed, this process can take some time to complete, so an application should call Phoneme with a background thread.
If the CHARSET_IPAPHONETIC value is used in the ANSI version of Phoneme, the function returns an error.
It is up to the calling application to free the memory allocated by the function, using the CoTaskMemAlloc and CoTaskMemFree functions.