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. |