Prosody speech processing: API: sm_play_tone_list

Prototype Definition

int sm_play_tone_list(struct sm_play_tone_list_parms *tonep)

Parameters

*tonep
a structure of the following type: 
typedef struct sm_play_tone_list_parms {
	tSMChannelId channel;					/* in */
	struct sm_play_tone_item {
		enum kSMToneOperation {
			kSMToneOperationStop,
			kSMToneOperationSum,
			kSMToneOperationModulate,
		} operation;					/* in */
		tSM_UT32 duration;				/* in */
		double frequency1;				/* in */
		double amplitude1;				/* in */
		double frequency2;				/* in */
		double amplitude2;				/* in */
	} *tones;						/* in */
	tSM_INT tone_count;					/* in */
} SM_PLAY_TONE_LIST_PARMS;

Description

This call allows an application to generate multiple simple tones on a given output channel channel.

The application can wait to be notified by an event that tone generation of a given duration has completed. When a write event has been associated with channel (see sm_channel_set_event()), then the driver will notify the application with that event whenever it needs to invoke sm_play_tone_list_status().

The sm_play_tone_list_abort() call may be used to stop an ongoing tone generation.

This call offers a superset of the functionality provided by sm_play_tone(), sm_play_cptone() and sm_play_digits().

Fields

channel
The channel on which the tones are to be generated.
tones
Pointer to an array containing the list of tones to play back.
operation
The operation to perform at this stage of the tone generation. One of these values:
kSMToneOperationStop
Stop the tone generation. sm_play_tone_list_status() will report kSMPlayToneListStatusComplete. All other parameters are ignored and should be zero.
kSMToneOperationSum
Combine the first and second signals by summing their output. This is the method used for generating DTMF tones.
kSMToneOperationModulate
Combine the first and second signals by treating the first as a carrier wave, over which the second signal is modulated. The amplitude2 parameter specifies the amplitude of the modulation. The output waveform is amplitude1 * sinewave(frequency1) * (1 + amplitude2 * sinewave(frequency2)) (after all parameters have been scaled appropriately).
duration
The duration of this tone, specified in milliseconds.
frequency1
The first component frequency of the tone to generate, specified in Hz. If operation is kSMToneOperationModulate then this tone specifies the carrier.
amplitude1
The amplitude of the first component frequency, specified in dBm0 (according to CCITT G.711) and must be in the range from -35 dBm0 to +3 dBm0.
frequency2
The second component frequency of the tone to generate, specified in Hz. If operation is kSMToneOperationModulate then this tone specifies the modulating signal.
amplitude2
If operation is kSMToneOperationSum then this is the amplitude of the second component frequency, specified in dBm0 (according to CCITT G.711) and must be in the range from -35 dBm0 to +3 dBm0. If operation is kSMToneOperationModulate then this is the amplitude relative to the carrier wave, with 0 dB corresponding to 100% modulation. For example, a 50% modulation would be specified as 20 * log10(0.5) = -6.0206 dB.
tone_count
The number of entries in the tones array.

Returns

0 if call completed successfully, otherwise a standard error such as:

This function is part of the Prosody speech processing API.