//========= Copyright Valve Corporation, All rights reserved. ============//

//

// Purpose:

//

// $NoKeywords: $

//

//=============================================================================//

// =============================================================================

// Interface to the LIPSinc TalkBack 1.1 library (TalkBack_*.lib).

//

// Copyright © 1998-2002 LIPSinc. All rights reserved.

#if !defined(TalkBack_h)

#define TalkBack_h

#include <stddef.h> // size_t.

// Enforce a C API.

#if defined(__cplusplus)

extern "C"

{

#endif

// -----------------------------------------------------------------------------

// Use the preprocessor to make the new API compatible with the old one.

#define TalkbackStartupLibrary TalkBackStartupLibrary

#define TalkbackShutdownLibrary TalkBackShutdownLibrary

#define TalkbackGetVersion TalkBackGetVersion

#define TalkbackGetVersionString TalkBackGetVersionString

#define TalkbackCheckSoundFile TalkBackCheckSoundFile

#define TalkbackCheckSpokenText TalkBackCheckSpokenText

#define TalkbackGetErrorString TalkBackGetErrorString

#define TalkbackGetAnalysis TalkBackGetAnalysis

#define TalkbackFreeAnalysis TalkBackFreeAnalysis

#define TalkbackGetFirstFrameNum TalkBackGetFirstFrameNum

#define TalkbackGetLastFrameNum TalkBackGetLastFrameNum

#define TalkbackGetFrameStartTime TalkBackGetFrameStartTime

#define TalkbackGetFrameEndTime TalkBackGetFrameEndTime

#define TalkbackGetNumPhonemes TalkBackGetNumPhonemes

#define TalkbackGetPhonemeEnum TalkBackGetPhonemeEnum

#define TalkbackGetPhonemeStartTime TalkBackGetPhonemeStartTime

#define TalkbackGetPhonemeEndTime TalkBackGetPhonemeEndTime

#define TalkbackInsertPhoneme TalkBackInsertPhoneme

#define TalkbackDeletePhoneme TalkBackDeletePhoneme

#define TalkbackChangePhonemeStart TalkBackChangePhonemeStart

#define TalkbackChangePhonemeEnd TalkBackChangePhonemeEnd

#define TalkbackChangePhonemeEnum TalkBackChangePhonemeEnum

#define TalkbackGetNumWords TalkBackGetNumWords

#define TalkbackGetWord TalkBackGetWord

#define TalkbackGetWordStartTime TalkBackGetWordStartTime

#define TalkbackGetWordEndTime TalkBackGetWordEndTime

#define TalkbackGetNumSpeechTargetTracks TalkBackGetNumSpeechTargetTracks

#define TalkbackGetNumSpeechTargetKeys TalkBackGetNumSpeechTargetKeys

#define TalkbackGetSpeechTargetKeyInfo TalkBackGetSpeechTargetKeyInfo

#define TalkbackGetSpeechTargetValueAtFrame TalkBackGetSpeechTargetValueAtFrame

#define TalkbackGetDominantSpeechTargetAtFrame TalkBackGetDominantSpeechTargetAtFrame

#define TalkbackGetSpeechTargetValueAtTime TalkBackGetSpeechTargetValueAtTime

#define TalkbackGetSpeechTargetDerivativesAtTime TalkBackGetSpeechTargetDerivativesAtTime

#define TalkbackGetNumGestureTracks TalkBackGetNumGestureTracks

#define TalkbackGetNumGestureKeys TalkBackGetNumGestureKeys

#define TalkbackGetGestureKeyInfo TalkBackGetGestureKeyInfo

#define TalkbackGetGestureValueAtFrame TalkBackGetGestureValueAtFrame

#define TalkbackGetGestureValueAtTime TalkBackGetGestureValueAtTime

#define TalkbackGetGestureDerivativesAtTime TalkBackGetGestureDerivativesAtTime

// -----------------------------------------------------------------------------

// For debug builds, set this to a non-zero value to get verbose debugging

// output from TalkBack.

extern int g_enableTalkBackDebuggingOutput;

// -----------------------------------------------------------------------------

// Miscellaneous constants.

// For calling TalkBackGetAnalysis() with all defaults.

#define TALKBACK_DEFAULT_SETTINGS NULL

// For setting the iSoundText parameter in TalkBackGetAnalysis() to "no text."

#define TALKBACK_NO_TEXT NULL

// Handy constants for TALKBACK_ANALYSIS_SETTINGS fields:

// For setting fSize.

#define TALKBACK_SETTINGS_SIZE sizeof(TALKBACK_ANALYSIS_SETTINGS)

// For setting fFrameRate to the

// default.

#define TALKBACK_DEFAULT_FRAME_RATE 30

// For setting fOptimizeForFlipbook

// to *not* optimize for flipbook.

#define TALKBACK_OPTIMIZE_FOR_FLIPBOOK_OFF 0

// For setting fOptimizeForFlipbook

// to optimize for flipbook.

#define TALKBACK_OPTIMIZE_FOR_FLIPBOOK_ON 1

// For setting fRandomSeed to use the

// current time to seed the random

// number generator and thereby get

// non-deterministic speech gestures.

#define TALKBACK_RANDOM_SEED -1

// For setting fConfigFile to "no

// config file."

#define TALKBACK_NO_CONFIG_FILE NULL

// -----------------------------------------------------------------------------

// Data types.

// TALKBACK_NOERR if successful, TalkBack error code if not.

typedef long TALKBACK_ERR;

// Opaque analysis results.

typedef void TALKBACK_ANALYSIS;

// Speech target.

typedef long TALKBACK_SPEECH_TARGET;

// Speech gesture.

typedef long TALKBACK_GESTURE;

// Phoneme.

typedef long TALKBACK_PHONEME;

// -----------------------------------------------------------------------------

// Data structures.

#pragma pack(push, 1)

// Optional analysis settings passed to TalkBackGetAnalysis().

typedef struct

{

// Set this field to sizeof(TALKBACK_ANALYSIS_SETTINGS) before using the

// structure.

long fSize;

// Frame rate for analysis. This only matters if you will be using *AtFrame

// functions.

//

// Default value: 30 (frames per second).

long fFrameRate;

// Set this to 1 to optimize for flipbook output, 0 to do analysis normally.

//

// Default value: 0 (normal analysis).

long fOptimizeForFlipbook;

// Set this to -1 to seed the random number generator with the current time.

// Any other number will be used directly for the random number seed, which

// is useful if you want repeatable speech gestures. This value does not

// influence lip-synching at all.

//

// Default value: -1 (use current time).

long fRandomSeed;

// Path to the configuration (.INI) file with phoneme-to-speech-target

// mapping. Set this to NULL to use the default mapping.

//

// Default value: NULL (use default mapping).

char const *fConfigFile;

} TALKBACK_ANALYSIS_SETTINGS;

typedef struct

{

// Set this field to sizeof(TALKBACK_SOUND_FILE_METRICS) before using the

// structure. This will allow the structure to evolve if necessary.

size_t m_size;

// Bits per sample.

long m_bitsPerSample;

// Sample rate in Hertz.

long m_sampleRate;

// Duration of the audio in seconds.

double m_duration;

// 1 if the sound file can be analyzed, 0 if not.

long m_canBeAnalyzed;

// 1 if the sound file is clipped, 0 if not.

long m_isClipped;

// The decibel range of the sound file.

double m_decibelRange;

// A quality value for the sound file: the nominal range is 0 to 100. Try

// to keep it above 45 for good results.

int m_quality;

// Added for version 2 of the metrics structure:

// ---------------------------------------------

// The number of channels in the sound file: 1 for mono, 2 for stereo, etc.

long m_channelCount;

} TALKBACK_SOUND_FILE_METRICS;

#pragma pack(pop)

// -----------------------------------------------------------------------------

// Constants.

// TalkBack error codes. Use TalkBackGetErrorString() to return text

// descriptions for these codes.

enum

{

// Windows convention: set this bit to indicate an application-defined error

// code.

BIT29 = (1 << 29),

// Success (not an error).

TALKBACK_NOERR = 0,

// The first error code: useful for iterating through the error codes.

TALKBACK_ERROR_FIRST = 4201 | BIT29,

// Generic error.

TALKBACK_ERROR = TALKBACK_ERROR_FIRST,

// TalkBackStartupLibrary() failed [internal error] or was never called.

TALKBACK_STARTUP_FAILED_ERR,

// TalkBackShutdownLibrary() failed, either because

// TalkBackStartupLibrary() was never called or because

// TalkBackShutdownLibrary() has already been called.

TALKBACK_SHUTDOWN_FAILED_ERR,

// The TalkBack data files could not be found [invalid path or missing

// files].

TALKBACK_CORE_DATA_NOT_FOUND_ERR,

// One or more of the parameters are NULL.

TALKBACK_NULL_PARAMETER_ERR,

// One or more of the parameters is invalid.

TALKBACK_INVALID_PARAMETER_ERR,

// The analysis object pointer is invalid.

TALKBACK_INVALID_ANALYSIS_ERR,

// Analysis failed [the sound file cannot be analyzed or an internal error

// occurred].

TALKBACK_ANALYSIS_FAILED_ERR,

// One or more of the indices (track, key, frame, word, phoneme) are

// invalid (out of range).

TALKBACK_INVALID_INDEX_ERR,

// The time parameter is invalid (out of range).

TALKBACK_INVALID_TIME_ERR,

// A serious internal error occurred in TalkBack; please alert LIPSinc by

// sending mail with a description of how the error was triggered to

// talkback-support@LIPSinc.com.

TALKBACK_INTERNAL_ERR,

// Could not open the specified sound file.

TALKBACK_COULD_NOT_LOAD_SOUND_ERR,

// TalkBackStartupLibrary() has not been called.

TALKBACK_STARTUP_NOT_CALLED,

// The configuration file specified in the TALKBACK_ANALYSIS_SETTINGS

// structure is invalid.

TALKBACK_CONFIG_PARSE_ERROR,

// The last error code: useful for iterating through the error codes.

TALKBACK_ERROR_LAST = TALKBACK_CONFIG_PARSE_ERROR

};

// Default lip-synching track identifiers.

//

// NOTE: these track identifiers apply *only* to the default phoneme-to-track

// mapping! Consult the TalkBack Reference Guide for more details.

//

// NOTE: these values are valid *only* if you use the default mapping and are

// provided as a convenience. If you use your own mapping, these values

// are invalid and should not be used.

enum

{

TALKBACK_SPEECH_TARGET_INVALID = -1,

TALKBACK_SPEECH_TARGET_FIRST = 0,

TALKBACK_SPEECH_TARGET_EAT = TALKBACK_SPEECH_TARGET_FIRST, // 0

TALKBACK_SPEECH_TARGET_EARTH, // 1

TALKBACK_SPEECH_TARGET_IF, // 2

TALKBACK_SPEECH_TARGET_OX, // 3

TALKBACK_SPEECH_TARGET_OAT, // 4

TALKBACK_SPEECH_TARGET_WET, // 5

TALKBACK_SPEECH_TARGET_SIZE, // 6

TALKBACK_SPEECH_TARGET_CHURCH, // 7

TALKBACK_SPEECH_TARGET_FAVE, // 8

TALKBACK_SPEECH_TARGET_THOUGH, // 9

TALKBACK_SPEECH_TARGET_TOLD, // 10

TALKBACK_SPEECH_TARGET_BUMP, // 11

TALKBACK_SPEECH_TARGET_NEW, // 12

TALKBACK_SPEECH_TARGET_ROAR, // 13

TALKBACK_SPEECH_TARGET_CAGE, // 14

TALKBACK_SPEECH_TARGET_LAST = TALKBACK_SPEECH_TARGET_CAGE, // 14

TALKBACK_NUM_SPEECH_TARGETS // 15 (0..14)

};

// Speech gesture track identifiers.

enum

{

TALKBACK_GESTURE_INVALID = -1,

TALKBACK_GESTURE_FIRST = 0,

TALKBACK_GESTURE_EYEBROW_RAISE_LEFT = TALKBACK_GESTURE_FIRST, // 0

TALKBACK_GESTURE_EYEBROW_RAISE_RIGHT, // 1

TALKBACK_GESTURE_BLINK_LEFT, // 2

TALKBACK_GESTURE_BLINK_RIGHT, // 3

TALKBACK_GESTURE_HEAD_BEND, // 4

TALKBACK_GESTURE_HEAD_SIDE_SIDE, // 5

TALKBACK_GESTURE_HEAD_TWIST, // 6

TALKBACK_GESTURE_EYE_SIDE_SIDE_LEFT, // 7

TALKBACK_GESTURE_EYE_SIDE_SIDE_RIGHT, // 8

TALKBACK_GESTURE_EYE_UP_DOWN_LEFT, // 9

TALKBACK_GESTURE_EYE_UP_DOWN_RIGHT, // 10

TALKBACK_GESTURE_LAST = TALKBACK_GESTURE_EYE_UP_DOWN_RIGHT, // 10

TALKBACK_NUM_GESTURES // 11 (0..10)

};

// Phoneme identifiers.

enum

{

TALKBACK_PHONEME_INVALID = -1,

TALKBACK_PHONEME_FIRST = 0,

TALKBACK_PHONEME_IY = TALKBACK_PHONEME_FIRST, // 0

TALKBACK_PHONEME_IH, // 1

TALKBACK_PHONEME_EH, // 2

TALKBACK_PHONEME_EY, // 3

TALKBACK_PHONEME_AE, // 4

TALKBACK_PHONEME_AA, // 5

TALKBACK_PHONEME_AW, // 6

TALKBACK_PHONEME_AY, // 7

TALKBACK_PHONEME_AH, // 8

TALKBACK_PHONEME_AO, // 9

TALKBACK_PHONEME_OY, // 10

TALKBACK_PHONEME_OW, // 11

TALKBACK_PHONEME_UH, // 12

TALKBACK_PHONEME_UW, // 13

TALKBACK_PHONEME_ER, // 14

TALKBACK_PHONEME_AX, // 15

TALKBACK_PHONEME_S, // 16

TALKBACK_PHONEME_SH, // 17

TALKBACK_PHONEME_Z, // 18

TALKBACK_PHONEME_ZH, // 19

TALKBACK_PHONEME_F, // 20

TALKBACK_PHONEME_TH, // 21

TALKBACK_PHONEME_V, // 22

TALKBACK_PHONEME_DH, // 23

TALKBACK_PHONEME_M, // 24

TALKBACK_PHONEME_N, // 25

TALKBACK_PHONEME_NG, // 26

TALKBACK_PHONEME_L, // 27

TALKBACK_PHONEME_R, // 28

TALKBACK_PHONEME_W, // 29

TALKBACK_PHONEME_Y, // 30

TALKBACK_PHONEME_HH, // 31

TALKBACK_PHONEME_B, // 32

TALKBACK_PHONEME_D, // 33

TALKBACK_PHONEME_JH, // 34

TALKBACK_PHONEME_G, // 35

TALKBACK_PHONEME_P, // 36

TALKBACK_PHONEME_T, // 37

TALKBACK_PHONEME_K, // 38

TALKBACK_PHONEME_CH, // 39

TALKBACK_PHONEME_SIL, // 40

TALKBACK_PHONEME_LAST = TALKBACK_PHONEME_SIL, // 40

TALKBACK_NUM_PHONEMES // 41 (0..40)

};

// -----------------------------------------------------------------------------

// Function declarations.

// ---------------------------

// Startup/shutdown functions.

// ---------------------------

// Must be the first function called when using TalkBack.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackStartupLibrary(

char const *iCoreDataDir); // IN: full path of folder containing TalkBack data files.

// Should be the last function called when using TalkBack.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackShutdownLibrary(); // IN: nothing.

// ------------------

// Version functions.

// ------------------

// Gets the TalkBack version number.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackGetVersion(

long *oMajor, // OUT: major version number.

long *oMinor, // OUT: minor version number.

long *oRevision); // OUT: revision version number.

// Gets the TalkBack version number as a string.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackGetVersionString(

long iMaxChars, // IN: size of version string buffer.

char *oVersion); // OUT: version string buffer.

// ------------------

// Utility functions.

// ------------------

// Checks whether a sound file can be analyzed and returns some quality metrics.

//

// NOTE: this function is deprecated and has been supplanted by

// TalkBackGetSoundFileMetrics().

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackCheckSoundFile(

double *oDecibelRange); // OUT: used decibel range of sound.

// Returns metrics for the specified sound file.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackGetSoundFileMetrics(

char const *iSoundFileName, // IN: name of sound file to be checked.

TALKBACK_SOUND_FILE_METRICS *ioMetrics); // IN/OUT: address of a structure where the metrics will be stored.

// Checks whether text can be used for text-based analysis, returning the text

// as it will be analyzed.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackCheckSpokenText(

char const *iSpokenText, // IN: text to check.

long iMaxChars, // IN: size of analyzed text buffer.

char *oAnalyzedText); // OUT: buffer for text as it will be analyzed.

// Convert a TalkBack error code to a description string.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackGetErrorString(

TALKBACK_ERR iErrorCode, // IN: TalkBack error code to convert.

long iMaxChars, // IN: size of the buffer.

char *oErrorString); // OUT: buffer for the description string.

// Gets the error code and text for the most recent TalkBack error.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackGetLastError(

long iMaxChars, // IN: size of the buffer.

char *oErrorString, // OUT: buffer for the description string.

TALKBACK_ERR *oErrorCode); // OUT: most recent TalkBack error code.

// -------------------

// Analysis functions.

// -------------------

// Gets an opaque TALKBACK_ANALYSIS object. This object is then queried with the

// TalkBackGet* functions below.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackGetAnalysis(

TALKBACK_ANALYSIS_SETTINGS *iSettings); // IN: pointer to a TALKBACK_ANALYSIS_SETTINGS structure (can be NULL for defaults).

// Frees an opaque TALKBACK_ANALYSIS object. This releases all memory used by

// the analysis.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackFreeAnalysis(

TALKBACK_ANALYSIS **ioAnalysis); // IN/OUT: analysis to free.

// #######################################################################

// NOTE: all functions from this point on require a valid analysis object.

// #######################################################################

// ------------------------

// Speech target functions.

// ------------------------

// Gets the number of speech target tracks.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackGetNumSpeechTargetTracks(

TALKBACK_ANALYSIS *iAnalysis, // IN: opaque analysis object returned by TalkBackGetAnalysis().

long *oResult); // OUT: number of speech target tracks.

// Gets the number of keys in the specified speech target track.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackGetNumSpeechTargetKeys(

TALKBACK_ANALYSIS *iAnalysis, // IN: opaque analysis object returned by TalkBackGetAnalysis().

long iTrackNum, // IN: speech target track.

long *oResult); // OUT: number of keys in the speech target track.

// Gets key information (time, value, derivative in, and derivative out) for the

// specified key in the specified speech target track.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackGetSpeechTargetKeyInfo(

double *oDerivativeOut); // OUT: outgoing derivative of key.

// Gets the value of the function curve for the specified speech target track at

// the specified time.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackGetSpeechTargetValueAtTime(

double *oResult); // OUT: value of the function curve.

// Gets the derivatives of the function curve for the specified speech target

// track at the specified time.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackGetSpeechTargetDerivativesAtTime(

double *oDerivativeOut); // OUT: value of the outgoing derivative of the function curve.

// -------------------------

// Speech gesture functions.

// -------------------------

// Gets the number of speech gesture tracks.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackGetNumGestureTracks(

TALKBACK_ANALYSIS *iAnalysis, // IN: opaque analysis object returned by TalkBackGetAnalysis().

long *oResult); // OUT: number of speech gesture tracks

// Gets the number of keys in the specified speech gesture track.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackGetNumGestureKeys(

TALKBACK_ANALYSIS *iAnalysis, // IN: opaque analysis object returned by TalkBackGetAnalysis().

long iTrackNum, // IN: speech gesture track.

long *oResult); // OUT: number of keys in the speech gesture track.

// Gets key information (time, value, derivative in, and derivative out) for the

// specified key in the specified speech gesture track.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackGetGestureKeyInfo(

double *oDerivativeOut); // OUT: outgoing derivative of key.

// Gets the value of the function curve for the specified speech gesture track

// at the specified time.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackGetGestureValueAtTime(

double *oResult); // OUT: value of the function curve.

// Gets the derivatives of the function curve for the specified speech gesture

// track at the specified time.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackGetGestureDerivativesAtTime(

double *oDerivativeOut); // OUT: value of the outgoing derivative of the function curve.

// ----------------

// Frame functions.

// ----------------

// NOTE: these functions use the frame rate specified in the

// TALKBACK_ANALYSIS_SETTINGS structure passed to TalkBackGetAnalysis() and

// default to 30 fps (TALKBACK_DEFAULT_FRAME_RATE) if the structure pointer was

// NULL.

// Gets the first frame number.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackGetFirstFrameNum(

TALKBACK_ANALYSIS *iAnalysis, // IN: opaque analysis object returned by TalkBackGetAnalysis().

long *oResult); // OUT: number of the first frame.

// Gets the last frame number.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackGetLastFrameNum(

TALKBACK_ANALYSIS *iAnalysis, // IN: opaque analysis object returned by TalkBackGetAnalysis().

long *oResult); // OUT: number of the last frame.

// Gets the start time of the specified frame.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackGetFrameStartTime(

TALKBACK_ANALYSIS *iAnalysis, // IN: opaque analysis object returned by TalkBackGetAnalysis().

long iFrameNum, // IN: frame.

double *oResult); // OUT: start time of the frame in seconds.

// Gets the end time of the specified frame.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackGetFrameEndTime(

TALKBACK_ANALYSIS *iAnalysis, // IN: opaque analysis object returned by TalkBackGetAnalysis().

long iFrameNum, // IN: frame.

double *oResult); // OUT: end time of the frame in seconds.

// Gets the value of the function curve for a speech target integrated over the

// specified frame.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackGetSpeechTargetValueAtFrame(

double *oResult); // OUT: value of the function curve integrated over the frame.

// Gets the dominant speech target at the specified frame.

//

// NOTE: this function is meant to be used in flipbook mode only.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackGetDominantSpeechTargetAtFrame(

TALKBACK_ANALYSIS *iAnalysis, // IN: opaque analysis object returned by TalkBackGetAnalysis().

long iFrameNum, // IN: frame number.

TALKBACK_SPEECH_TARGET *oSpeechTarget); // OUT: dominant speech target.

// Gets the value of the function curve for a speech gesture integrated over the

// specified frame.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackGetGestureValueAtFrame(

double *oResult); // OUT: value of the function curve integrated over the frame.

// ------------------

// Phoneme functions.

// ------------------

// Gets the number of phonemes.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackGetNumPhonemes(

TALKBACK_ANALYSIS *iAnalysis, // IN: opaque analysis object returned by TalkBackGetAnalysis().

long *oResult); // OUT: number of phonemes.

// Gets the enumeration of the specified phoneme.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackGetPhonemeEnum(

TALKBACK_ANALYSIS *iAnalysis, // IN: opaque analysis object returned by TalkBackGetAnalysis().

long iPhonemeNum, // IN: phoneme.

TALKBACK_PHONEME *oResult); // OUT: enumeration of the specified phoneme.

// Gets the start time of the specified phoneme.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackGetPhonemeStartTime(

TALKBACK_ANALYSIS *iAnalysis, // IN: opaque analysis object returned by TalkBackGetAnalysis().

long iPhonemeNum, // IN: phoneme.

double *oResult); // OUT: start time of the phoneme in seconds.

// Gets the end time of the specified phoneme.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackGetPhonemeEndTime(

TALKBACK_ANALYSIS *iAnalysis, // IN: opaque analysis object returned by TalkBackGetAnalysis().

long iPhonemeNum, // IN: phoneme.

double *oResult); // OUT: end time of the phoneme in seconds.

// ---------------

// Word functions.

// ---------------

// NOTE: these functions only yield data for text-based analysis.

// Gets the number of words.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackGetNumWords(

TALKBACK_ANALYSIS *iAnalysis, // IN: opaque analysis object returned by TalkBackGetAnalysis().

long *oResult); // OUT: number of words.

// Gets the text of the specified word.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackGetWord(

char *oWord); // OUT: word buffer.

// Gets the start time of the specified word.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackGetWordStartTime(

TALKBACK_ANALYSIS *iAnalysis, // IN: opaque analysis object returned by TalkBackGetAnalysis().

long iWordNum, // IN: word.

double *oResult); // OUT: start time of the word in seconds.

// Gets the end time of the specified word.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackGetWordEndTime(

TALKBACK_ANALYSIS *iAnalysis, // IN: opaque analysis object returned by TalkBackGetAnalysis().

long iWordNum, // IN: word.

double *oResult); // OUT: end time of the word in seconds.

// --------------------------

// Phoneme editing functions.

// --------------------------

// Use these functions to modify the phoneme list after you get an opaque

// analysis object from TalkBackGetAnalysis(). After modifying the phoneme list

// in the opaque analysis object, subsequent TalkBackGet* calls on that opaque

// analysis object for speech target (lip-synching) data will return values

// based on the modified phoneme list. However, speech gesture data is not

// affected by phoneme editing.

//

// NOTE: phoneme editing is only provided in order to support Ventriloquist-like

// applications where tweaking of the phoneme segmenation (and subsequent

// recalculation of the animation data) is required. Most customers probably

// won't need this functionality.

// Inserts a phoneme at the specified position in the specified manner.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackInsertPhoneme(

int iInsertBefore); // IN: manner of insertion:

// 0 means put phoneme after insert position;

// 1 means put phoneme before insert position.

// Deletes the specified phoneme.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackDeletePhoneme(

TALKBACK_ANALYSIS *iAnalysis, // IN: opaque analysis object returned by TalkBackGetAnalysis().

long iPhonemeToDelete); // IN: phoneme to delete.

// Changes the start time of the specified phoneme.

//

// NOTE: the start time specified may not be the actual start time for a number

// of reasons, most notably if the specified start time will make the phoneme

// too short. This function returns the actual start time so the caller can

// check the result without having to query the phoneme.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackChangePhonemeStart(

TALKBACK_ANALYSIS *iAnalysis, // IN: opaque analysis object returned by TalkBackGetAnalysis().

long iPhonemeToChange, // IN: phoneme to change.

double *ioNewTime); // IN/OUT: new start time value in seconds (in); actual start time (out).

// Changes the end time of the specified phoneme.

//

// NOTE: the end time specified may not be the actual end time for a number of

// reasons, most notably if the specified end time will make the phoneme too

// short. This function returns the actual end time so the caller can check the

// result without having to query the phoneme.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackChangePhonemeEnd(

TALKBACK_ANALYSIS *iAnalysis, // IN: opaque analysis object returned by TalkBackGetAnalysis().

long iPhonemeToChange, // IN: phoneme to change.

double *ioNewTime); // IN/OUT: new end time value in seconds (in); actual end time (out).

// Changes the enumeration of the specified phoneme.

TALKBACK_ERR // RETURNS: TALKBACK_NOERR if successful, TalkBack error code if not.

TalkBackChangePhonemeEnum(

TALKBACK_ANALYSIS *iAnalysis, // IN: opaque analysis object returned by TalkBackGetAnalysis().

long iPhonemeToChange, // IN: phoneme to change.

TALKBACK_PHONEME iNewPhoneme); // IN: new phoneme enumeration.

#if defined(__cplusplus)

}

#endif

#endif