voltmx.media Namespace
The voltmx.media namespace, together with the media object and the record object, implements the functionality of the Media API.
Your app uses the functions in the voltmx.media namespace to create media and record objects. It calls the createFromFile and createFromUri functions to instantiate media objects and associate media objects with files. The files can exist either locally on the device or remotely across the network or Internet.
To record audio to a file, your app uses the
voltmx media record
function to create a record object.
Functions
The voltmx.media namespace contains the following functions.
voltmx.media.createFromFile
Creates a media object from a media file on the device.
Syntax
voltmx.media.createFromFile(
fileobj,psp)
Input Parameters
| Parameter | Description |
|---|---|
| fileobj | An object of type voltmx.io.File that specifies the file that the created media object will play. |
| psp [Optional] | A JSON Object that contains the key-value pairs for the AVAudioSession Category and AVAudioSession Category Options parameters. Note: The psp parameter is only applicable for the iOS platform. The default value of the AVAudioSession Category is voltmx.media.AUDIO_SESSION_CATEGORY_PLAY_AND_RECORD. The AVAudioSession Category Options is an array of category options with the default value voltmx.media.AUDIO_SESSION_CATEGORY_OPTIONS_MIX_WITH_OTHERS and voltmx.media.AUDIO_SESSION_CATEGORY_OPTIONS_DEFAULT_TO_SPEAKER. |
Example 1
var fileObj = new voltmx.io.File("MyAudioFile.mp3");
var mediaObj = voltmx.media.createFromFile(fileObj);
Example 2
var fileObj = new voltmx.io.File("MyAudioFile.mp3");
var psp = {
"category": voltmx.media.AUDIO_SESSION_CATEGORY_PLAY_AND_RECORD,
"options": [voltmx.media.AUDIO_SESSION_CATEGORY_OPTIONS_DEFAULT_TO_SPEAKER,voltmx.media.AUDIO_SESSION_CATEGORY_OPTIONS_ALLOW_BLUETOOTH_A2DP,voltmx.media.AUDIO_SESSION_CATEGORY_OPTIONS_MIX_WITH_OTHERS]
}
var mediaObj = voltmx.media.createFromFile(fileObj,psp);
Return Values
Returns a media object that is associated with a specific file on the device, or null if the object was not created.
Remarks
This function has platform-specific behaviors when there are errors. In particular, when the fileObj parameter refers to a file that doesn't exist on iOS, iOS generates an error with the message string "Unable to play the media file". However, if this error occurs on Android, no error message is generated. Instead, this function does not create the media object.
Parameter Details
The psp parameter is an object that contains key-value pairs for the AVAudioSession Category and AVAudioSession Category Options parameters.
The structure of the psp parameter is as follows:
psp Structure:{
"category" : <category_name>
"options" : [categoryOptions]
}
Note: If the value of the options parameter is not an array, the default value
(voltmx.media.AUDIO_SESSION_CATEGORY_OPTIONS_MIX_WITH_OTHERS and voltmx.media.AUDIO_SESSION_CATEGORY_OPTIONS_DEFAULT_TO_SPEAKER) is assigned to the options parameter.
The AVAudioSession Category parameter supports the following values.
| Constant | Description |
|---|---|
| voltmx.media.AUDIO_SESSION_CATEGORY_AMBIENT | This category indicates that the sound playback for the app is non-primary. This means that the app will work even with the sound turned-off. When you use this category, audio from other apps gets mixed with the current audio.The audio is silenced when you lock the screen or use the Silent switch (the Ring/Silent switch on iPhones). |
| voltmx.media.AUDIO_SESSION_CATEGORY_SOLO_AMBIENT | This category indicates that the audio from the app is non-mix-able. This means that when you activate an audio session, it interrupts all the other audio sessions that are non-mix-able.If you want to allow audio mixing, you must use the voltmx.media.AUDIO_SESSION_CATEGORY_AMBIENT category.The audio is silenced when you lock the screen or use the Silent switch (the Ring/Silent switch on iPhones). |
| voltmx.media.AUDIO_SESSION_CATEGORY_PLAYBACK | Use this category for playing recorded music or other sounds that are central to the successful use of your app.This category indicates that the audio from the app is non-mix-able. This means that when you activate an audio session, it interrupts all the other audio sessions that are non-mix-able.If you want to allow audio mixing, you must use the voltmx.media.AUDIO_SESSION_CATEGORY_OPTIONS_MIX_WITH_OTHERS category. When you use this category, the audio of the app continues to play even when you lock the screen or use the Silent switch (the Ring/Silent switch on iPhones). |
| voltmx.media.AUDIO_SESSION_CATEGORY_PLAY_AND_RECORD | Use this category in scenarios where recording (input) and playback (output) of audio must be performed simultaneously. However, you can also use this category in apps that record and then play back the audio.This category indicates that the audio from the app is non-mix-able. This means that when you activate an audio session, it interrupts all the other audio sessions that are non-mix-able.If you want to allow audio mixing, you must use the voltmx.media.AUDIO_SESSION_CATEGORY_OPTIONS_MIX_WITH_OTHERS category. When you use this category, the audio of the app continues to play or get recorded even when you lock the screen or use the Silent switch (the Ring/Silent switch on iPhones). |
| voltmx.media.AUDIO_SESSION_CATEGORY_MULTIROUTE | Use this category to route distinct streams of audio data to different output devices at the same time. |
The AVAudioSession Category Options parameter supports the following values.
| Constant | Description |
|---|---|
| voltmx.media.AUDIO_SESSION_CATEGORY_OPTIONS_MIX_WITH_OTHERS | An option that indicates whether the audio from the current session mixes with the audio from active sessions in other audio apps. |
| voltmx.media.AUDIO_SESSION_CATEGORY_OPTIONS_DUCK_OTHERS | An option that reduces the volume of other audio sessions while audio from the current session plays. |
| voltmx.media.AUDIO_SESSION_CATEGORY_OPTIONS_ALLOW_BLUETOOTH | An option that determines whether Bluetooth hands-free devices can appear as available input routes. |
| voltmx.media.AUDIO_SESSION_CATEGORY_OPTIONS_DEFAULT_TO_SPEAKER | An option that determines whether audio from the current session must use the default built-in speaker instead of the receiver. |
| voltmx.media.AUDIO_SESSION_CATEGORY_OPTIONS_INTERRUPT_SPOKEN_AUDIO_AND_MIX_WITH_OTHERS | An option that determines whether spoken audio content from other sessions must be paused when the app plays its audio. |
| voltmx.media.AUDIO_SESSION_CATEGORY_OPTIONS_ALLOW_BLUETOOTH_A2DP | An option that determines whether you can stream audio from the current session to Bluetooth devices that support the Advanced Audio Distribution Profile (A2DP). |
| voltmx.media.AUDIO_SESSION_CATEGORY_OPTIONS_ALLOW_AIR_PLAY | An option that determines whether you can stream audio from the current session to AirPlay devices. |
| voltmx.media.AUDIO_SESSION_CATEGORY_OPTIONS_OVERRIDE_MUTED_MICROPHONE_INTERRUPTION | An option that indicates whether the system interrupts the audio session when the built-in microphone is muted. |
Platform Availability
Windows10, Android, iOS
voltmx.media.createFromUri
Creates a media object that plays a remote audio file across the network.
Syntax
voltmx.media.createFromUri(
uriString,psp)
Input Parameters
| Parameter | Description |
|---|---|
| uriString | A string containing the URI of the remote audio file. |
| psp [Optional] | A JSON Object that contains the key-value pairs for the AVAudioSessions Category and AVAudioSession Category Option parameters. Note: The psp parameter is only applicable for the iOS platform. The default value of the AVAudioSession Category is voltmx.media.AUDIO_SESSION_CATEGORY_PLAY_AND_RECORD. The AVAudioSession Category Options is an array of category options with the default value voltmx.media.AUDIO_SESSION_CATEGORY_OPTIONS_MIX_WITH_OTHERS and voltmx.media.AUDIO_SESSION_CATEGORY_OPTIONS_DEFAULT_TO_SPEAKER. |
Example 1
var mediaObj = voltmx.media.createFromUri(url);
Example 2
var psp = {
"category": voltmx.media.AUDIO_SESSION_CATEGORY_PLAY_AND_RECORD,
"options": [voltmx.media.AUDIO_SESSION_CATEGORY_OPTIONS_DEFAULT_TO_SPEAKER,voltmx.media.AUDIO_SESSION_CATEGORY_OPTIONS_ALLOW_BLUETOOTH_A2DP,voltmx.media.AUDIO_SESSION_CATEGORY_OPTIONS_MIX_WITH_OTHERS]
}
var mediaObj = voltmx.media.createFromUri(url,psp);
Return Values
Returns a media object that is associated with a remote audio file, or null if the object was not created.
Remarks
Parameter Details
The psp parameter is an object that contains key-value pairs for the AVAudioSessions Category and AVAudioSession Category Option parameters.
The structure of the psp parameter is as follows:
psp Structure:{
"category" : <category_name>
"options" : [categoryOptions]
}
Note: If the value of the options parameter is not an array, the default value
(voltmx.media.AUDIO_SESSION_CATEGORY_OPTIONS_MIX_WITH_OTHERS and
voltmx.media.AUDIO_SESSION_CATEGORY_OPTIONS_DEFAULT_TO_SPEAKER) is assigned to the options parameter.
The AVAudioSessions Category parameter supports the following values.
| Parameter | Description |
|---|---|
| voltmx.media.AUDIO_SESSION_CATEGORY_AMBIENT | This category indicates that the sound playback for the app is non-primary. This means that the app will work even with the sound turned-off. When you use this category, audio from other apps gets mixed with the current audio. The audio is silenced when you lock the screen or use the Silent switch (the Ring/Silent switch on iPhones). |
| voltmx.media.AUDIO_SESSION_CATEGORY_SOLO_AMBIENT | This category indicates that the audio from the app is non-mix-able. This means that when you activate an audio session, it interrupts all the other audio sessions that are non-mix-able.If you want to allow audio mixing, you must use the voltmx.media.AUDIO_SESSION_CATEGORY_AMBIENT category.The audio is silenced when you lock the screen or use the Silent switch (the Ring/Silent switch on iPhones). |
| voltmx.media.AUDIO_SESSION_CATEGORY_PLAYBACK | Use this category for playing recorded music or other sounds that are central to the successful use of your app.This category indicates that the audio from the app is non-mix-able. This means that when you activate an audio session, it interrupts all the other audio sessions that are non-mix-able.If you want to allow audio mixing, you must use the voltmx.media.AUDIO_SESSION_CATEGORY_OPTIONS_MIX_WITH_OTHERS category. When you use this category, the audio of the app continues to play even when you lock the screen or use the Silent switch (the Ring/Silent switch on iPhones). |
| voltmx.media.AUDIO_SESSION_CATEGORY_PLAY_AND_RECORD | Use this category in scenarios where recording (input) and playback (output) of audio must be performed simultaneously. However, you can also use this category in apps that record and then play back the audio.This category indicates that the audio from the app is non-mix-able. This means that when you activate an audio session, it interrupts all the other audio sessions that are non-mix-able.If you want to allow audio mixing, you must use the voltmx.media.AUDIO_SESSION_CATEGORY_OPTIONS_MIX_WITH_OTHERS category. When you use this category, the audio of the app continues to play or get recorded even when you lock the screen or use the Silent switch (the Ring/Silent switch on iPhones). |
| voltmx.media.AUDIO_SESSION_CATEGORY_MULTIROUTE | Use this category to route distinct streams of audio data to different output devices at the same time. |
The AVAudioSession Category Option parameter supports the following values.
| Parameter | Description |
|---|---|
| voltmx.media.AUDIO_SESSION_CATEGORY_OPTIONS_MIX_WITH_OTHERS | An option that indicates whether the audio from the current session mixes with the audio from active sessions in other audio apps. |
| voltmx.media.AUDIO_SESSION_CATEGORY_OPTIONS_DUCK_OTHERS | An option that reduces the volume of other audio sessions while audio from the current session plays. |
| voltmx.media.AUDIO_SESSION_CATEGORY_OPTIONS_ALLOW_BLUETOOTH | An option that determines whether Bluetooth hands-free devices can appear as available input routes. |
| voltmx.media.AUDIO_SESSION_CATEGORY_OPTIONS_DEFAULT_TO_SPEAKER | An option that determines whether audio from the current session must use the default built-in speaker instead of the receiver. |
| voltmx.media.AUDIO_SESSION_CATEGORY_OPTIONS_INTERRUPT_SPOKEN_AUDIO_AND_MIX_WITH_OTHERS | An option that determines whether spoken audio content from other sessions must be paused when the app plays its audio. |
| voltmx.media.AUDIO_SESSION_CATEGORY_OPTIONS_ALLOW_BLUETOOTH_A2DP | An option that determines whether you can stream audio from the current session to Bluetooth devices that support the Advanced Audio Distribution Profile (A2DP). |
| voltmx.media.AUDIO_SESSION_CATEGORY_OPTIONS_ALLOW_AIR_PLAY | An option that determines whether you can stream audio from the current session to AirPlay devices. |
| voltmx.media.AUDIO_SESSION_CATEGORY_OPTIONS_OVERRIDE_MUTED_MICROPHONE_INTERRUPTION | An option that indicates whether the system interrupts the audio session when the built-in microphone is muted. |
Platform Availability
Windows10, Android, iOS
voltmx.media.record
Creates a record object that your app can use to record audio.
Syntax
The syntax for native platforms is as follows.
voltmx.media.record(fileobj,config)
The syntax for Desktop Web is as follows.
voltmx.media.record(config)
Input Parameters
| Parameter | Description |
|---|---|
| fileobj | A voltmx.io.file object into which the recording will be saved. |
| config | An optional object that contains configuration information for the record object. For more information, see Remarks below. |
Example
function errorcallback(errorMessage) {
var errorMesg = "Reason for failure is : " + errorMessage;
alert(errorMesg);
}
function successcallback(fileobj) {
// Your code goes here.
}
var fileObj = new voltmx.io.file("recording");
var config = {
onSuccess: successCallback,
onFailure: failureCallback
};
var _recordObj = voltmx.media.record(fileObj, config);
Return Values
Returns an instantiated record object, or null if the object was not created.
Remark
Use the voltmx.media.record function to instantiate a record object that your app can use to record audio on the device.
Parameter Details
The config parameter contains an object with configuration information. Specifically, it contains key-value pairs that set callbacks which are invoked by the voltmx.media.record function. The config parameter supports the following keys.
| Key | Description |
|---|---|
| onFailure | The callback function that is invoked when the voltmx.media.record function is not able to create a record object. |
| onSuccess | The callback function that is invoked when the voltmx.media.record function successfully creates a record object. |
The callback for the onFailure key must have the following signature.
onFailureCallback(errorMessage);
where the errorMessage parameter is a string containing the reason for the failure.
The callback for the onSuccess key must have the following signature.
onSuccessCallback(fileobj);
where the fileobj parameter is an object of type voltmx.io.file that represents the file the audio is recorded into.
The callback for the onSuccess key must have the following signature in Desktop Web platform.
onSuccessCallback(audiobytes);
here, the audiobytes parameter contains the recorded audio as Blob URL.
Platform-Specific Notes
The following platform-specific features should be considered when using this function.
- iOS: Your app must enable recording before it calls this function. To enable recording, it invokes the voltmx.application.checkPermission(voltmx.os.RESOURCE_AUDIO_RECORD,null) function. In addition, the file extension of the audio file for the recording is set to
.aiff, irrespective of the extension specified in the user's input. - Android: You must add the
RECORD_AUDIOpermission into your app's manifest. On Android 6.0 or later, this will result in the operating system displaying a dialog box asking the user to confirm this permission at runtime. In addition, the file extension of the audio file for the recording is set to.m4ano matter what the user input specifies. - Windows: To enable your app to record audio, you must add the "Micriphone" capability in the app's properties.
- Desktop Web: If you are creating more than one
recordobject at the same time, theaudiobytesparameter returns only the last recording of allonSuccesscallbacks.
Platform Availability
Windows10, Android, iOS, and Desktop Web
