Provider
Asynchronous
No Custom Parameters
Initiates playback of the specified audio file and/or plays text-to-speech to the specified connection or conference.
The Play action allows one to specify up to 3 prompts, which can be either free-formed strings or the names of WAV files. If more than one prompt is specified, the format of the supplied WAV files must all be the same (sample rate, sample size, encoding, mono, file type) and also match the format of generated TTS WAV files, which is a sample rate of 8 kHz, a sample size of 8 bit, and an audio format of PCM. As an example, one can not specify VOX prompts in conjunction with text-to-spech prompts for a single Play action, since the file formats are different.
The Play command will fire Play_Complete once all prompts are finished, if a termination condition is satisfied, or if CommandTimeout is reached. If the action fails for any reason, all prompts are cancelled and Play_Failed is fired.
The termination condition parameters on the action are a means to create a matrix of reasons that the action should cease playing. In the Play_Complete event, one can use TerminationCondition to determine why the command stopped playing. To see a list of all possible termination conditions, reference the Play_Complete TerminationCondition action parameter.
The determination of whether a Prompt is a wav/vox file or a text-to-speech prompt involves a few steps.
Prompt, then the media engine will check the OS filesystem to determine if the file exists. If the file exists, it will attempt to play the audio file to the specified connection or conference. If the file does not exist at the specified location, then step 5 is executed. If the a file name is specified as the value of Prompt, with no path information, then the next step is executed.
Prompt, and check the OS filesystem to determine if the file exists. If the file exists, it will attempt to then play the audio file to the specified connection or conference. If the file does not exist, the next step is executed.
Prompt, and check the OS filesystem to determine if the file exists. If the file exists, it will attempt to then play the audio file to the specified connection or conference. If the file does not exist, then the next step is executed.
Prompt specified as a text-to-speech prompt. The string specified as Prompt will be passed to the text-to-speech engine to be converted to a WAV file. As soon as the WAV file is generated, it is then played to the specified connection or conference.
If one plays to a connection while it is in conference, the connection is temporarily taken out of the conference for the duration of the Play.
The following properties cover most audio file types that can be played by the media engine: sample rate of 6, 8, 11, sample size of 4, 8, 16, and 2 bit, and encoding types of ulaw, alaw, pcm, adpcm, and g726. Only mono vox and wav files are allowed.
If the command plays all prompts successfully to completion, the Play command will result in the Play_Complete event with a TerminationCondition of eod.
A Play to a connection or a conference results in a voice resource being utilized until the action results in the Play_Complete event.
If a connection is specified as the recepient of the Play, the voice resource attaches to the connection. If a conference is specified as the recepient of the Play, a new connection (which uses a conference resource) is created and added to the conference for the duration of the Play, and the voice resource is attached to that new connection. It is important to understand this behavior, as the ConnectionId result data will always be the connection to which the Play voice resource is attached. In other words, in the case of a Play to a connection, the value of the ConnectionId result data is the same as that specified as an action parameter. In the case of a Play to a conference, the value of the ConnectionId result data is the value of the new connection added to conference which is only a valid value for the duration of the Play. In either case, this result data ConnectionId is what one would later specify in StopMediaOperation.
A Play action which specifies a text-to-speech prompt will result in the usage of a text-to-speech resource on the embedded TTS engine. Unlike the voice resource, the text-to-speech resource is not used for the duration of the Play action. Instead, the TTS resource is only used for the amount of time it takes for the embedded TTS engine to generate a wav file for the specified prompt string. A wav file is generated in real-time at the onset of every text-to-speech Play operation.
| Parameter Name | .NET Type | Default | Description |
|---|---|---|---|
| AudioFileSampleSize | System.UInt32 | The sample size used in the audio file (in bits).
Valid values are 4, 8, or 16. 4 and 16 should be avoided as both have a higher impact on the media engine. If not specified, the media engine configuration file defines the sample size to use, which by default is 8. | |
| Prompt3 | System.String | A prompt field can be one of two types of values. It can be either an audio file name or a free-formed string which will be converted to text-to-speech. | |
| CommandTimeout | System.UInt32 | Indicates a command timeout value (in milliseconds).
If this condition is met, the Play command will result in the Play_Complete event with a
TerminationCondition of timeout. | |
| Volume | System.Int32 | The amount by which to modify the volume (in decibels) of audio playback. Valid values range from -10 to 10. | |
| Speed | System.Int32 | The amount by which to modify the speed of audio playback. Valid values range from -10 to 10. | |
| State | System.String | Arbitrary, user-defined state information which is passed back as the State event parameter in
Play_Complete or Play_Failed. | |
| AudioFileSampleRate | System.UInt32 | The sample rate of the audio file (in kHz).
Valid values are 6, 8, or 11. 11 should be avoided as it has a higher impact on the media engine. If not specified, the media engine configuration file defines the sample rate to use, which by default is 8. | |
| Timeout | System.Int32 | The Timeout property specifies to the Application Runtime Environment how long
to wait for a response from the provider for the current action.
The ReturnValue returned in this case is Timeout. The value must be a literal value in milliseconds. | |
| AudioFileEncoding | System.String | The encoding of the audio file: ulaw, alaw, pcm, or adpcm.
Pcm and adpcm should be avoided as each has a higher impact on the media engine. If not specified, the media engine configuration file defines the file encoding to use, which by default is ulaw. | |
| Prompt1 * | System.String | A prompt field can be one of two types of values. It can be either an audio file name or a free-formed string which will be converted to text-to-speech. | |
| Prompt2 | System.String | A prompt field can be one of two types of values. It can be either an audio file name or a free-formed string which will be converted to text-to-speech. | |
| ConnectionId | System.String | The connection to perform the Play on. If specified, ConferenceId must not be specified. | |
| ConferenceId | System.String | The conference to perform the Play on. If specified, ConnectionId must not be specified. | |
| TermCondMaxTime | System.UInt32 | The amount of time (in milliseconds) that can elapse before terminating the play operation.
If this condition is met, the Play command will result in the Play_Complete event with a
TerminationCondition of maxtime. | |
| TermCondMaxDigits | System.UInt32 | The number of digits that will cause the play operation to terminate.
If this condition is met, the Play command will result in the Play_Complete event with a
TerminationCondition of maxdigits. | |
| TermCondDigit | System.String | A specific digit that will cause the play operation to terminate.
If this condition is met, the Play command will result in the Play_Complete event with a
TerminationCondition of digit. If you wish to know what digit or digits were pushed, use GatherDigits after Play_Complete, which will process the digits collected into the digit buffer as the Play command was executing. | |
| TermCondDigitList | System.String | A list of digits that will cause the play operation to terminate, if any one of the digits in the list is inputted. The list has no delimiters.
If this condition is met, the Play command will result in the Play_Complete event with a
TerminationCondition of digitlist. | |
| TermCondSilence | System.UInt32 | The amount of silence (in milliseconds) to observe before terminating the Play operation.
If this condition is met, the Play command will result in the Play_Complete event with a
TerminationCondition of silence. | |
| TermCondNonSilence | System.UInt32 | The amount of non-silence (in milliseconds) to observe before terminating the Play operation.
If this condition is met, the Play command will result in the Play_Complete event with a
TerminationCondition of nonsilence. |
| Parameter Name | .NET Type | Description |
|---|---|---|
| ConnectionId | System.String | In the case of a Play to a connection,
the value of the ConnectionId result data is the same as that specified as an action parameter.
In the case of a Play to a conference,
the value of the ConnectionId result data is the value of the new connection added to conference.
In either case, this ConnectionId is what one would later specify in
StopMediaOperation if one were to abort the command programmatically. |
| OperationId | System.String | A unique identifier to this Play operation. This identifier can later be used by the
StopMediaOperation
action to stop just this particular operation on a connection, even if multiple media operations are concurrently executing on that connection.
In the case that the Play was specified to a conference, there is no reason to store OperationId,
since the ConnectionId returned as a result data will only ever have this Play action operating on it. |
| ResultCode | System.String | A numeric code indicating the result status of the operation. A '0' indicates success; a positive number indicates an error. Please reference the Media Control Error Codes table for descriptions on specific error codes. |
Branch Conditions
No description.
No description.
No description.