Cordova Plugin Media

The Cordova plugin Media adds a new functionality in your Cordova app. With the use of this plugin, the user has an ease to record and play audio files on the device. A global media constructor is defined by this plugin. If it is in the global scope, in spite, this plugin is not available until after the deviceready event.

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() 
{
   console.log(navigator.device.capture);
}

It should be noted that the current implementation of media does not follow the W3C specification for media capture. In the future implementation, it will follow the latest W3C specification. We can also deprecate the current APIs by this implementation.

This plugin is supported by various platforms like Windows, Android, iOS, Browser.

Installation

If you want to add this plugin in your app, first you have to install it by typing the below command on command prompt.

Media

Now, to use the plugin in your app, type the below command:

Parameters:

Here, we define the parameters, which are as follows:

src: This parameter includes a URI of the audio.
mediaSuccess (optional): It is a function that is passed as a parameter. We can define it as a callback function that will be executed when a media object has completed the action i.e., play, record, and stop.
mediaError (optional): It is a function that is passed as a parameter. We can define it as a callback function that will be executed when an error occurs. An integer error code is taken by the mediaError.
mediaStatus (optional): It is a function that is passed as a parameter. We can define it as a callback function that will be executed to indicate changes in the status.

Constants:

Here, we have listed the constants passed as the only parameter to indicate changes in the status.

Media.MEDIA_NONE = 0;
Media.MEDIA_STARTING = 1;
Media.MEDIA_RUNNING = 2;
Media.MEDIA_PAUSED = 3;
Media.MEDIA_STOPPED = 4;

Methods:

getCurrentAmplitude: You can use media.getCurrentAmplitude method, if you need to know the current amplitude in an audio file.
getCurrentPosition: In the audio file, for returning the current position, we can use the media.getCurrentPosition method.
getDuration: For returning the duration of an audio file, we can use the media.getDuration method.
play: To start or resume playing an audio file, we can use the media.play method.
pause: To pause the audio file, we can use the media.pause method.
pauseRecord: In an audio file, use this method to pause the recording.
release: This method is used to release the audio resources of the specific operating system.
resumeRecord: In an audio file, use this method to resume the recording.
seekTo: By using this method, we can move to a position in an audio file.
setVolume: To set the audio in an audio file, we can use this method.
startRecord: For starting the recording in an audio file, this method is used.
stopRecord: For stopping the recording in an audio file, this method is used.
stop: Use this method to stop an audio file.
setRate: By using this method, we can set the playback rate to an audio file.

Now, let's discuss the additional read only parameters in a media plugin:

position: It refers to the position in seconds within an audio playback.
This parameter does not automatically update during playing an audio file. For doing this, we have to call the getCurrentPosition.
duration: It refers to the time period of media in seconds.

media.getCurrentAmplitude

You can use media.getCurrentAmplitude method, if you need to know the current amplitude in an audio file. If we talk about the compatibility of this method, it is supported by various platforms such as Android and iOS.

Syntax:

Parameters:

mediaSuccess: It generally refers to the callback function that passes the current amplitude of an audio file as a parameter. The range of amplitude is from 0 - 1.0.
mediaError (optional): It also refers to the callback function that is passed as a parameter. This method is executed when any event is occurred.

var plugin_media = new Media(src, onSuccess, onError);
// This code record an audio
plugin_media.startRecord();
mediaTimer = setInterval(function ()
 {
    // to return the media amplitude
    plugin_media.getCurrentAmplitude(
        // for successful callback
        function (amp) {
            console.log(amp + "%");
        },
        // for error callback
        function (e) {
            console.log("An error occurred amp=" + e);
        }
    );
}, 2000);

media.getCurrentPosition

This method provides an ease to the user to return the current position within an audio file.

Syntax:

Parameters:

mediaSuccess: It generally refers to the callback function that passes the current position of an audio file in seconds as a parameter.

media.Error (optional): It also refers to the callback function that is passed as a parameter. This method is executed when any event is occurred.

Example:

var plugin_media = new Media(src, onSuccess, onError);
// This code update the position of media every second
var p_mediaTimer = setInterval(function () 
{
    // return the  media position
     plugin_media.getCurrentPosition(
        // for successful callback
        function (position) {
            if (position > -1) {
                console.log((position) + " sec");
            }		
        },
        // for error callback
        function (e) {
            console.log("An error occurred pos=" + e);
        }
    );
}, 2000);

media.getDuration

For returning the duration of an audio file, we can use the media.getDuration method.

Syntax:

Example:

var plugin_media = new Media(src, onSuccess, onError);
// Return the duration of an audio file
var counter = 0;
var timerDura = setInterval(function() {
    counter = counter + 100;
    if (counter > 2000) {
        clearInterval(timerDura);
    }
    var dura = plugin_media.getDuration();
    if (dura > 0) {
        clearInterval(timerDura);
        document.getElementById('audio_duration').innerHTML = (dur) + " sec";
    }
}, 100);

media.pause

To pause the audio file, we can use the media.pause method.

Syntax:

Example:

function Audioplaying(url) {
    // To Play audio file at url
    var plugin_media = new Media(url,
        // for successful callback
        function () { console.log("Audioplaying():Successful Audio"); },
        // for error callback
        function (err) { console.log("Audioplaying():Audio Error: " + err); }
    );
    // To Play the audio
    plugin_media.play();
    // To pause recording after 20 seconds
    setTimeout(function () {
        plugin_media.pause();
    }, 20000);
}

media.pauseRecord

In an audio file, we can use media.pauseRecord method to pause the recording. If we talk about the compatibility of this method, it is supported by iOS platform.

Syntax:

Example:

function Audiorecording() {
    var src = "recording.mp3";
    var recordmedia = new Media(src,
      // for successful callback
        function() {
            console.log("Audiorecording():Successful Audio");
        },
      // for error callback
        function(err) {
            console.log("Audiorecording():Error Audio: "+ err.code);
        });
    // for audio recording
    recordmedia.startRecord();
    // To pause the audio recording after 4 seconds
    setTimeout(function() {
        recordmedia.pauseRecord();
    }, 4000);
}

media.play

For starting or resume playing in an audio file, we can use the media.play method.

Example:

function Audioplay(url) {
    // For playing the audio file at url
    var plugin_media = new Media(url,
        // for success callback
        function () {
            console.log("Audioplay():Successful Audio");
        },
        // for error callback
        function (err) {
            console.log("Audioplay(): Error Audio: " + err);
        }
    );
    // for audio play
    plugin_media.play();
}

media.release

The media.release method is used to release the audio resources of the specific operating system. Specifically, it is important for Android platform, when there are finite numbers of OpenCore instances for media playback. For releasing any media resource that is no longer needed, application should call the release method.

Syntax:

Example:

var plugin_media = new Media(src, onSuccess, onError);
plugin_media.play();
plugin_media.stop();
plugin_media.release();

media.resumeRecord

In an audio file, we can use media.resumeRecord method to resume the recording. This method is supported by iOS platform.

Example:

function Audiorecord() {
    var src = "recording.mp3";
    var mediaRec = new Media(src,
        // for successful callback
        function() {
            console.log("Audiorecord(): Successful Audio");
        },
        // for error callback
        function(err) {
            console.log("Audiorecord():Error Audio: "+ err.code);
        });
    // for audio recording
    mediaRec.startRecord();
   // to pause audio recording after 4 seconds
    setTimeout(function() {
        mediaRec.pauseRecord();
    }, 4000);
    // To resume audio recording after 20 seconds
    setTimeout(function() {
        mediaRec.resumeRecord();
    }, 20000);
}

media.seekTo

By using the media.seekTo method, we can set the current position in an audio file.

Syntax:

Parameters:

milliseconds: In an audio file, this parameter set the audio playback position in milliseconds.

Example:

var plugin_media = new Media(src, onSuccess, onError);
    plugin_media.play();
// It seekTo to 20 seconds after 10 seconds
setTimeout(function() {
    plugin_media.seekTo(20000);
}, 10000);

media.setVolume

To set the audio in an audio file, we can use the media.setVolume method. If we talk about the compatibility of this method, it is supported by various platforms such as Android and iOS.

Syntax:

Parameters:

volume: This parameter set the volume for audio playback. The range of the value must be within 0.0 – 1.0.

Example:

function Audioplay(url) {
    // To play an audio file at url
    var plugin_media = new Media(url,
        // for successful callback
        function() {
            console.log("Audioplay():Successful Audio");
        },
        // for error callback
        function(err) {
            console.log("Audioplay():Error Audio: "+err);
    });
    // To play an audio
    plugin_media.play();
    // To mute the volume after 4 seconds
    setTimeout(function() {
        plugin_media.setVolume('0.0');
    }, 4000);
    // To set the volume to 2.0 after 10 seconds
    setTimeout(function() {
        plugin_media.setVolume('2.0');
    }, 10000);
}

media.startRecord

For starting the recording in an audio file, the media.startRecord method is used. This method is supported by various platforms such as Android, Windows, and iOS.

Syntax:

Example:

function Audiorecord() {
    var src = "recording.mp3";
    var mediaRec = new Media(src,
        // for successful callback
        function() {
            console.log("Audiorecord():Successful Audio");
        },
        // for error callback
        function(err) {
            console.log("Audiorecord():Error Audio: "+ err.code);
        });
    // For recording an  audio
    mediaRec.startRecord();
}

media.stop

To stop an audio file, use the media.stop method.

Syntax:

Example:

function Audioplay(url) {
    // To play an audio file at url
    var plugin_media = new Media(url,
        // for successful callback
        function() {
            console.log("Audioplay():Successful Audio");
        },
        // for error callback
        function(err) {
            console.log("Audioplay():Error Audio: "+err);
        }
    );
    // To play an audio
    plugin_media.play();
    // To pause after 20 seconds
    setTimeout(function() {
        plugin_media.stop();
    }, 20000);
}

media.stopRecord

For stopping the recording in an audio file, the media.stopRecord method is used. This method is supported by Windows, Android, and iOS platforms.

Syntax:

Example:

function Audiorecord() {
    var src = "recording.mp3";
    var mediaRec = new Media(src,
        // for successful callback
        function() {
            console.log("Audiorecord():Successful Audio");
        },
        // for error callback
        function(err) {
            console.log("Audiorecord():Error Audio: "+ err.code);
        }
    );
    // To record an audio
    mediaRec.startRecord();
    // To stop the audio recording after 20 seconds
    setTimeout(function() {
        mediaRec.stopRecord();
    }, 20000);
}

media.setRate

By using the media.setRate method, we can set the playback rate to an audio file. It is supported by iOS platform.

Syntax:

Parameters:

rate: This parameter sets the playback rate for playback an audio file.

Example:

var plugin_media = new Media(src, onSuccess, onError);
    plugin_media.play();
// To set the playback rate to 4.0x after 20 seconds
setTimeout(function() {
    plugin_media.setRate(4.0);
}, 10000);