Namespace: VoiceRecording

sap. 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
         }
     );

Members

closeDialog

Suspends an ongoing VoiceRecording operation and closes the dialog.

Methods

(static) audioCapture(successCallback, errorCallback, args)

An audio dialog appears where the user can start/stop/save the recording.
Parameters:
Name Type Description
successCallback sap.VoiceRecording.AudioCaptureSuccessCallback Callback method upon success. Invoked with the created Recording object.
errorCallback sap.VoiceRecording.AudioCaptureErrorCallback Callback method upon failure.
args sap.VoiceRecording.AudioCaptureArgs The arguments for audio capture.
Throws:
Will throw an error if SAPUI5 or jQuery is not defined or an ongoing voice recording operation is in progress.

(static) get(successCallback, errorCallback, id)

Get a Recording object from the storage by id. The Recording objects are persisted once they are created. All Recording object has an id. After application restart the application can retrieve the Recording for the given id by this function call.
This function can be used for application restart: the application can store the suspended recording id. When the application is restarted it can read the id and get the corresponding recording by this function call.
Parameters:
Name Type Description
successCallback sap.VoiceRecording.GetSuccessCallback Callback method upon success. Invoked with the Recording object corresponding to the key.
errorCallback sap.VoiceRecording.GetErrorCallback Callback method upon failure. It could be during the store.getItem() request.
id string the id of the Recording
Throws:
Will throw an error an ongoing VoiceRecording opration is in progress.

(static) getAll(successCallback, errorCallback)

Get the list of existing Recording objects. The Recording objects are persisted once they are created. After application restart the application can retrieve the existing Recordings by this function call.
Parameters:
Name Type Description
successCallback sap.VoiceRecording.GetAllSuccessCallback Callback method upon success. Invoked with an array of the Recording objects.
errorCallback sap.VoiceRecording.GetAllErrorCallback Callback method upon failure.
Throws:
Will throw an error if an ongoing VoiceRecording operation is in progress.

destroyAll(successCallback, errorCallback)

Destroys all recordings.
Parameters:
Name Type Description
successCallback sap.VoiceRecording.DestroyAllSuccessCallback Callback method upon success.
errorCallback sap.VoiceRecording.DestroyAllErrorCallback Callback method upon failure.

Type Definitions

AudioCaptureArgs

Declaration of the object which is passed in the audioCapture method.
Properties:
Name Type Description
maxLength long the maximum length of the recording. If it is exceeded the recording will be stopped and it can not be continued.

AudioCaptureErrorCallback(code, extraopt)

Callback invoked to inform the user about the audio capture process. The error codes and the associated extra parameters can be the following:
  • 'logon_error': logon is not initialized - extra parameter is the nested error comes from logon plugin.
  • 'encrypted_storage_error': error thrown by encrypted storage - extra parameter is the nested error comes from encrypted storage.
  • 'recording-cancel': the recording was cancelled by the user.
  • 'cancel_error': the recording was cancelled by the user, but there was an error during closing the audio recorder.
  • 'save_error': the recording was cancelled by the user, but there was an error during closing the audio recorder.
  • 'metadata_error': can not read/write metadata. 'extra' parameter is the nested error from file plugin.
  • 'file_error': can not read/write files. 'extra' parameter is the nested error from file plugin.
  • 'permission_denied': the user did not grant the necessary permissions. 'extra' parameter is the permission that was not granted.
  • 'interrupted' : the ongoing operation was interrupted. 'extra' parameter is the interrupted recording object.
  • 'unknown_error': unknown error happened. 'extra' parameter is the nested error.
Parameters:
Name Type Attributes Description
code string error code
extra Object <optional>
extra parameter for the given error code

AudioCaptureSuccessCallback(recording)

Callback invoked to inform the user about the audio capture process.
Parameters:
Name Type Description
recording sap.VoiceRecording.Recording the Recording object which is passed to the application. This object can be used for playback and upload.

DestroyAllErrorCallback(error, extraopt)

Callback invoked to inform the user about the destroyAll process.
  • 'destroy_error': can not destroy all recording. 'extra' parameter is an array of errors raised during destroying the recordings.
Parameters:
Name Type Attributes Description
error string the error code (see above)
extra Object <optional>
an object containing the nested error

DestroyAllSuccessCallback()

Callback invoked to inform the user about the destroyAll process.

GetAllErrorCallback(error, extraopt)

Callback invoked to inform the user about the get all recording process. The error codes and the associated extra parameters can be the following:
  • 'getall_error': can not retreive all recordings. 'extra' parameter is an array of errors raised during getting the recordings. The array contains 'encrypted_storage_error'.
Parameters:
Name Type Attributes Description
error string the error code (see above)
extra Object <optional>
an object containing the nested error

GetAllSuccessCallback(recordings)

Callback invoked to inform the user about the get all recording process.
Parameters:
Name Type Description
recordings Array.<Recording> the Recording objects stored in the encrypted storage.

GetErrorCallback(error, extraopt)

Callback invoked to inform the user about the get recording process. The error codes and the associated extra parameters can be the following:
  • 'file_error': error occured when trying to load resources from the file system. Extra parameter contains the nested error.
  • 'encrypted_storage_error': error thrown by encrypted storage. Extra parameter contains the nested error comes from encrypted storage.
  • 'not_found_error': the recording with the given id was not found
Parameters:
Name Type Attributes Description
error string the error code (see above)
extra Object <optional>
an object containing the nested error

GetSuccessCallback(recording)

Callback invoked to inform the user about the get recording process.
Parameters:
Name Type Description
recording sap.VoiceRecording.Recording the Recording object itself.