play media

This represents media that can be played on the call. Either:

Used by action play

language wrappers and examples

TTS

The play media object properties for text are:

PropertyRequired/OptionalDefaultDescription
text to sayrequired-The text to say. This must be in ASCII or UTF-8 format.
tts voiceoptionalset in the service configurationThe TTS voice to use. Use a Selector from one of the voice tables on the Text-To-Speech (TTS) page.
text is privateoptionalfalsetrue or false. Whether the text is private and should not be logged.

See Text-To-Speech (TTS) for advanced TTS features.

file

The play media properties for files in the Aculab media file store or that are available on the web are:

PropertyRequired/OptionalDefaultDescription
file to playrequired-The wav file to play. This can be a file name or a web page request object. If a file name is given the file must be present in the Aculab media file store. If a web page request object is given it must identify a suitable media file that is available on the web. The web page request method defaults to GET.
decryption cipheroptionalnullA cipher object to be used to decrypt the file to play, if it is encrypted. Cannot be used if file to play is a web page request object.

The wav file encodings supported are:

  • G.711 A-law, 8 bits per sample
  • G.711 mu-law, 8 bits per sample
  • OKI ADPCM, 4 bit coding scheme
  • 8-bit unsigned linear coding, an unsigned value (0 to 255)
  • 16-bit signed linear coding, a signed value (-32768 to 32767)
  • 4-bit coding scheme standardised by the Interactive Multimedia Association (IMA)

The wav file must be mono at 8000 samples per second.

If a web page request object is supplied, the URL supplied should point to a page that will upload a wav file. The URL can be a relative or full path. The request method defaults to GET. Only GET is supported.

When the URL is accessed, Aculab Cloud will expect to receive audio data. No information will be sent to the URL, i.e., instance info will NOT be sent, and no actions can be returned from the URL. Aculab Cloud implements caching, so HTTP cache-control headers will be honoured. The maximum size of a file to be uploaded is five megabytes, which is about 10 minutes of 8 bit audio or 5 minutes of 16 bit audio. If your file has been cached and you need it to be refreshed immediately you can force a refresh by changing the url. An easy way to do this is to add a version number to your url.

For example, if your URL is http://Badger.set.com:80/my_wav_page?filename=my_audio.wav&version=1 it will be easy to change version to 2 and force a refresh.

Encrypted media files need to be validated before they can be played back on a call. This occurs automatically as part of the Play action when the file is decrypted for playback. If you receive an error in your REST log file 'Creating audio action: could not validate encrypted file to play: Format error' (see your REST Log Files Page) you should be sure to check the decryption details provided, as we are unable to validate the file format of an incorrectly decrypted file.

digits

The play media object properties for digits are:

PropertyRequired/OptionalDefaultDescription
digits to playrequired-A string of digits to play. Valid digits are 0123456789ABCD#*. Commas can be used, each one produces a delay of half a second.

Note that the DTMF digits you play may be eliminated by some parts of the telephone network. If you would like to play a general purpose beep to the far end, consider playing a wav file that contains a suitable tone.

  • Examples:


    • Using Text-To-Speech:

      	{
      		"text_to_say" : "Hello, good evening and welcome."
      	}
      
    • Playing a file:

      	{
      		"file_to_play" : "welcome.wav"
      	}
      
    • Playing digits:

      	{
      		"digits_to_play" : "987654321"
      	}
      
  • This functionality is provided by function calls of the Play class.
  • This functionality is provided by function calls of the Play class.
  • class Play

    This functionality is provided by members of the Play action class.

    Examples:

    • Using Text-To-Speech:

      Play playAction = new Play();
      playAction.addText("Hello, good evening and welcome.");
      
    • Playing a file:

      Play playAction = new Play();
      playAction.addFile("welcome.wav");
      
    • Playing digits:

      Play playAction = new Play();
      playAction.addDigits("987654321");
      
  • class Play

    Several Play class constructor parameters exist (text_to_say, file_to_play and digits_to_play) that can be used to specify different types of media to play.

    Examples:

    • Using Text-To-Speech:

      play_action = Play(text_to_say="Hello, good evening and welcome.")
      
    • Playing a file:

      play_action = Play(file_to_play="welcome.wav")
      
    • Playing digits:

      play_action = Play(digits_to_play="987654321")
      
  • This functionality is provided by function calls of the Play class.

    Examples:

    • Using Text-To-Speech:

      $play = \Aculab\TelephonyRestAPI\Play::sayText("Hello, good evening and welcome.");
      
    • Playing a file:

      $play = \Aculab\TelephonyRestAPI\Play::playFile("welcome.wav");
      
    • Playing digits:

      $play = \Aculab\TelephonyRestAPI\Play::playDigits("987654321");