AudioPlayer

Description

The AudioPlayer control allows you to add a control to the UX to play audio files. Rich Data Capture.

The recent iOS 12.2 update changed the way media files are handled in the PhoneGap web view. In order for the UX Audio Player and Audio Player/Recorder controls to work with iOS 12.2, the iOS Media Playback Requires User Action property must be disabled in the PhoneGap configuration. This is the default value for new PhoneGap projects using Alpha Anywhere build 5771 and newer.

To change this setting in existing projects, check the Show Advanced Options property in the PhoneGap App Builder Genie and uncheck the Media Playback Requires User Action option.

Discussion 

To add a new AudioPlayer control to the UX component, select the [More...] entry in the controls toolbox (in the 'Data Controls' section) and then select the 'AudioPlayer' control.

A separate Audio Recorder/Player control is also available. The Audio Recorder/Player control is only available for PhoneGap applications.

This will insert a control into the UX that looks like this:

To customize the AudioPlayer control, click the smart field for the Control properties.

Since the AudioPlayer is a data bound control, it has a {dialog.object}.setValue() and a {dialog.object}.getValue() method.

To set the audio file that you want to play back you use the {dialog.object}.setValue() method

For example:

{dialog.object}.setValue('MYAUDIOCONTROL','stream:http://audio.wgbh.org:8004');

In this case the AudioPlayer value is being set to a 'stream' - (a continuous audio stream) rather than a file.

After the stream is ready to play, the AudioPlayer appearance will change to this:

While the stream is loading (i.e. before it is ready to play), the text 'Stream', shown in the above image, will say 'Loading...'.

All of the text messages shown in the control are customizable in the AudioPlayer Control properties.

In this next example, the AudioPlayer value is set to a file URL:

{dialog.object}.setValue('MYAUDIOCONTROL','http://s3.amazonaws.com/alphaVideos/theway.mp3');

In the case where the AudioPlayer value is set to an audio file (not a stream), its appearance will change as follows once the audio file is ready to play:

When the user taps the Play button, the audio starts to play back. The number on the right side indicates the duration of the audio file. Before playback starts, or when playback is paused, the fast forward and fast reverse buttons (on either side of the Play button) will skip to the beginning or end of the audio clip (if you tap on them). However, if you press and hold, they will rewind or fast forward in 2 second steps.

The top bar shows the progress as the audio file is being played. The number on the right hand side shows the duration of the audio file. The number on the left hand side shows how much of the audio file has been played. The buttons on each side of the Play button allows you to skip forward and back in the file.

The AudioPlayer control cannot play audio files that are hosted on the Alpha Anywhere server. It can play files that are hosted on Amazon S3, or, in the case of a PhoneGap application, files that are stored in the file system on the device.

JavaScript Methods 

JavaScript methods are available for the AudioRecorderAndPlayer control. Methods can be used for recording and playback. To call the methods, you must first get a reference to the JavaScript object for the AudioRecorderAndPlayer control using the {dialog.object}.getControl() method:

//Get a pointer to the AudioPlayer control with the ID 'AUDIO_CONTROL':
var audioObj = {dialog.object}.getControl('AUDIO_CONTROL');

if (audioObj) {
    // Play the video
    audioObj.play();
}

The AudioPlayer has methods for playback. See the A5.audio Namespace for more information on the methods and properties available for the AudioPlayer JavaScript object.

Inserting an Add-in Control 

Add-in Controls are inserted using the More... option in the Data Controls section of the UX Builder.

Select the control you would like to add and click OK.

In addition to the controls that ship with Alpha Anywhere, you can also create your own add-in controls. See How to Create Add-in Controls to learn more.

See Also