Namespace: VoiceRecording

Voice Recording plugin is a Fiori plugin which can be used to create voice memo. With this plugin the user is able to record a voice memo in order to attach it to an item within Fiori application.

This plugin provides an API that allows to initiate the recording of a voice memo. When the user completes the recording of the memo, the recording is accessable so that it can be saved as an attachment or played back.
File upload is not in scope of the Voice Recoridng: it is the application's responsibility. In SMP SDK 3.0 SP10 the recording can be played back with a new js API method sap.VoiceRecording.Recording#play.

Recording

The recording can be initiated by sap.VoiceRecording.audioCapture. Example usage:

     sap.VoiceRecording.audioCapture(
         function(recording) {
             // success callback with the created recording as parameter
         },
         function(error_code, extra) {
             // error callback
         }
     );

MaxLength

Application can specify maximum length for a recording in millisec. Example usage:

     sap.VoiceRecording.audioCapture(
         function(recording) {
             // success callback with the created recording as parameter
         },
         function(error_code, extra) {
             // error callback
         },
         {
             maxLength: 12000 // 2 minutes
         }
     );

If the maximum length is exceeded the VoiceRecording stops the recording and does not allow to continue it.

Playback

The playback can be initiated on an existing Recording object with the following method: sap.VoiceRecording.Recording#play. Example usage:

    recording.play(
         function() {
             // success callback
         },
         function(error_code, extra) {
             // error callback
         }
     );

Lifecycle of Recordings

When a recording is created by sap.VoiceRecording.audioCapture it is also stored permanently. If the application is restarted the existing Recordings can be retrieved by sap.VoiceRecording.get and sap.VoiceRecording.getAll methods.

The Recording objects have an id (string). This id can be used by the application for retrieving a certain Recording. Example usage of retrieving a Recording by id (sap.VoiceRecording.get):

     sap.VoiceRecording.get(
         function(recording) {
             // success callback with the retrieved Recording as parameter
         ,
         function(error_code, extra) {
             // error callback (e.g. recoridng does not exist for the given id)
         },
         Id
     );

Example usage of retrieving all existing Recordings (sap.VoiceRecording.getAll):

     sap.VoiceRecording.getAll(
         function(retVal) {
             // success callback with an array of Recordings as parameter
         },
         function(error_code, extra) {
             // error callback
         }
     );

When the application does not need the recording any more the Recording must be destroyed by (sap.VoiceRecording.Recording#destroy). Example usage:

     recording.destroy(
         function() {
             // success callback
         },
         function(error_code, extra) {
             // error callback
         }
     );

The application can delete all existing recordings by calling (sap.VoiceRecording#destroyAll). Example usage:

     recording.destroyAll(
         function() {
             // success callback
         },
         function(error_code, extra) {
             // error callback
         }
     );

The application can explicitly suspend an ongoing VoiceRecording operation (playing or recording) and close the dialog by calling (sap.VoiceRecording#closeDialog). Example usage:

     sap.VoiceRecording.closeDialog(function() {
         alert("Success");    
     });

Suspend and Resume

The recording or playing operations can be suspended. This case the ongoing recording/playing is paused, the state is stored. When the application is resumed the user can continue the suspended recording/playing.

Thread safety

VoiceRecording is thread-safe in a way that it blocks all API call until an ongoing operation is finished. It means that while there is an ongoing operation (e.g. recording) API method calls throw Error.

3rd party plugin dependency

The VoiceRecording plugin uses the open source cordova plugin 'cordova-plugin-screen-orientation' to lock the screen when the dialog is shown. After the dialog is closed we unlock the screen orientation lock via this plugin. If the main application uses this plugin as well, it has to restore it's own status in the VoiceRecording success- or errorcallback.

Delete file from path

Only on Windows, the VoiceRecording plugin provides utility a function, which allows the usert to delete a decrypted recording. This function should be called by the application developer after recording.getAsFile. Example usage of deleteing a recording from path:

     sap.VoiceRecording.getAsFile(
         function(decryptedFilePath) {
             // success callback with the decrypted file path

             // upload or send the file

             // call delete
             sap.VoiceRecording.deleteFileFromPath(decryptedFilePath, function() {
                      // success callback, delete was successful
             }, function(error_code, extra) {
                      // error callback
             });
         },
         function(error_code, extra) {
             // error callback
         }
     );