In logic, an
Audio object represents an audio recording. Audio recordings may be loaded from audio files, saved to audio files, played, or recorded. Audio objects are typically used to record portions of an interview either interactively or in the background. With interactive recording, an audio recorder is displayed to the user who then controls when the recording is started and stopped. The user must complete the audio recording before moving to the next survey question. With background recording, the audio recorder is started and stopped using CSPro logic and the user can continue with the survey while the audio is recorded.
Audio recording is typically implemented by declaring a variable of type
Audio, calling either the
Audio.record or
Audio.recordInteractive function, and then calling the
Audio.save function to save the audio to a file. Audio recorded by CSPro is stored in m4a format (AAC encoded in an MPEG-4 container).
Audio recording and playback are currently only supported on Android.
| Function | Description |
|---|
| clear | Erases the audio recording currently stored in the Audio object. |
| concat | Appends an audio recording to the recording stored in the Audio object. |
| length | Returns the length, in seconds, of the recording in the Audio object. |
| load | Reads an audio file and places the contents in the Audio object. |
| play | Launches an audio player to play back the contents of the Audio object. (Android only.) |
| record | Starts recording audio in the background. (Android only.) |
| recordInteractive | Starts interactive audio recording. (Android only.) |
| save | Writes the audio recording to a file. |
| stop | Stops the current background recording. (Android only.) |
| |
| getLabel | Returns the symbol's label. |
| getName | Returns the symbol's name. |
| getJson | Returns the symbol's metadata and value represented in JSON. |
| getValueJson | Returns the symbol's value represented in JSON. |
| updateValueFromJson | Modifies the symbol based on a JSON representation of the value. |
In addition to these object functions, Audio objects can be used as arguments to the
filename function.
Audio objects can be assigned to other Audio objects, which will replace the recorded Audio with the recording from the assigned Audio object.
audio_name = another_audio_name;
It is also possible to assign Audio objects to a
Document:
document_name = audio_name;
You can also make the reverse assignment, assigning a Document to an Audio object. A runtime error will occur if the Document's data was not Audio data.
audio_name = document_name;
PROC AUDIO_QUESTION
onfocus
// Variable to store the recording
Audio recording;
// Save recording to a file that includes case id-items to differentiate it from
// audio saved in other cases
string nameOfAudioFile = maketext("%v%v%vAUDIO_QUESTION.m4a", PROVINCE, DISTRICT, EA);
// If no audio is recorded for this question then the only option is to record,
// otherwise allow user to re-record, play or clear recording before continuing
ValueSet vs;
if fileexist(nameOfAudioFile) and recording.load(nameOfAudioFile) then
vs.add("Re-record", 1);
vs.add("Play recording", 2);
vs.add("Clear recording", 3);
vs.add("Next question", 4);
else
vs.add("Record", 1);
endif;
setvalueset($, vs);
postproc
if $ = 1 then
// Record/re-record
recording.clear();
string message = "Record the respondent's answer to this question";
numeric seconds = recording.recordInteractive(message);
if seconds > 0 then
recording.save(nameOfAudioFile);
else
errmsg("No audio recorded. Please try again");
endif;
reenter;
elseif $ = 2 then
// Play back recording
recording.play();
reenter;
elseif $ = 3 then
// Clear the recording
filedelete(nameOfAudioFile);
reenter;
elseif $ = 4 then
// Continue to next question
endif;