FreeSoft
English EN
PhoneGap archiveDocumentation

Documentation

Media — edge archive

Archived media documentation, with original examples and platform notes for the 3.0.0 release-era snapshot.

Recovered documentationedge snapshot at Cordova 3.0.0
Archive note. Historical reference. PhoneGap tools and the former Adobe services are no longer maintained as described in the original material. Recovered text and newly written explanations are identified below; consult current platform documentation for active development.

About this version

This page preserves the official documentation for edge snapshot at Cordova 3.0.0. Commands, supported platforms and API behavior below belong to that historical version. The edge URL changed over time; this is a named repository snapshot, not an assertion about its last live contents. For active projects, consult the current Apache Cordova documentation.

Reference sections

Original source: Media

Media

The Media object provides the ability to record and play back audio files on a device.

var media = new Media(src, mediaSuccess, [mediaError], [mediaStatus]);

NOTE: The current implementation does not adhere to a W3C specification for media capture, and is provided for convenience only. A future implementation will adhere to the latest W3C specification and may deprecate the current APIs.

Parameters

  • src: A URI containing the audio content. (DOMString)
  • mediaSuccess: (Optional) The callback that executes after a Media object has completed the current play, record, or stop action. (Function)
  • mediaError: (Optional) The callback that executes if an error occurs. (Function)
  • mediaStatus: (Optional) The callback that executes to indicate status changes. (Function)

Constants

The following constants are reported as the only parameter to the mediaStatus callback:

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

Methods

  • media.getCurrentPosition: Returns the current position within an audio file.
  • media.getDuration: Returns the duration of an audio file.
  • media.play: Start or resume playing an audio file.
  • media.pause: Pause playback of an audio file.
  • media.release: Releases the underlying operating system's audio resources.
  • media.seekTo: Moves the position within the audio file.
  • media.setVolume: Set the volume for audio playback.
  • media.startRecord: Start recording an audio file.
  • media.stopRecord: Stop recording an audio file.
  • media.stop: Stop playing an audio file.

Additional ReadOnly Parameters

  • position: The position within the audio playback, in seconds.
    • Not automatically updated during play; call getCurrentPosition to update.
  • duration: The duration of the media, in seconds.

Supported Platforms

  • Android
  • BlackBerry WebWorks (OS 5.0 and higher)
  • iOS
  • Windows Phone 7.5
  • Tizen
  • Windows 8

Permissions

Android

app/res/xml/config.xml

<plugin name="Media" value="org.apache.cordova.AudioHandler" />

app/AndroidManifest.xml

<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

BlackBerry WebWorks

www/plugins.xml

<plugin name="Capture" value="org.apache.cordova.media.MediaCapture" />

iOS

config.xml

<plugin name="Media" value="CDVSound" />

Windows Phone

Properties/WPAppManifest.xml

<Capabilities>
    <Capability Name="ID_CAP_MEDIALIB" />
    <Capability Name="ID_CAP_MICROPHONE" />
    <Capability Name="ID_HW_FRONTCAMERA" />
    <Capability Name="ID_CAP_ISV_CAMERA" />
    <Capability Name="ID_CAP_CAMERA" />
</Capabilities>

Reference: Application Manifest for Windows Phone

Tizen

No permissions are required.

Windows Phone Quirks

  • Only one media file can be played back at a time.
  • There are strict restrictions on how your application interacts with other media. See the Microsoft documentation for details.
Original source: MediaError

MediaError

A MediaError object is returned to the mediaError callback function when an error occurs.

Properties

  • code: One of the predefined error codes listed below.
  • message: An error message describing the details of the error.

Constants

  • MediaError.MEDIA_ERR_ABORTED
  • MediaError.MEDIA_ERR_NETWORK
  • MediaError.MEDIA_ERR_DECODE
  • MediaError.MEDIA_ERR_NONE_SUPPORTED

Description

The MediaError object is passed to a mediaError callback function when an error occurs.

Original source: mediaError

mediaError

A user-specified callback function that executes when there is an error in media functions.

function(error) {
    // Handle the error
}

Parameters

  • error: The error returned by the device. (MediaError)
Original source: CaptureCB

CaptureCB

Invoked upon a successful media capture operation.

function captureSuccess( MediaFile[] mediaFiles ) { ... };

Description

This function executes after a successful capture operation completes. At this point a media file has been captured, and either the user has exited the media capture application, or the capture limit has been reached.

Each MediaFile object describes a captured media file.

Quick Example

// capture callback
function captureSuccess(mediaFiles) {
    var i, path, len;
    for (i = 0, len = mediaFiles.length; i < len; i += 1) {
        path = mediaFiles[i].fullPath;
        // do something interesting with the file
    }
};
Original source: CaptureError

CaptureError

Encapsulates the error code resulting from a failed media capture operation.

Properties

  • code: One of the pre-defined error codes listed below.

Constants

  • CaptureError.CAPTURE_INTERNAL_ERR: The camera or microphone failed to capture image or sound.
  • CaptureError.CAPTURE_APPLICATION_BUSY: The camera or audio capture application is currently serving another capture request.
  • CaptureError.CAPTURE_INVALID_ARGUMENT: Invalid use of the API (e.g. the value of limit is less than one).
  • CaptureError.CAPTURE_NO_MEDIA_FILES: The user exits the camera or audio capture application before capturing anything.
  • CaptureError.CAPTURE_NOT_SUPPORTED: The requested capture operation is not supported.
Original source: CaptureErrorCB

CaptureErrorCB

Invoked if an error occurs during a media capture operation.

function captureError( CaptureError error ) { ... };

Description

This function executes if an error occurs when trying to launch a media capture operation. Failure scenarios include when the capture application is busy, a capture operation is already taking place, or the user cancels the operation before any media files are captured.

This function executes with a CaptureError object containing an appropriate error code.

Quick Example

// capture error callback
var captureError = function(error) {
    navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error');
};
Original source: ConfigurationData

ConfigurationData

Encapsulates a set of media capture parameters that a device supports.

Description

Describes media capture modes supported by the device. The configuration data includes the MIME type, and capture dimensions for video or image capture.

The MIME types should adhere to RFC2046. Examples:

  • video/3gpp
  • video/quicktime
  • image/jpeg
  • audio/amr
  • audio/wav

Properties

  • type: The ASCII-encoded lowercase string representing the media type. (DOMString)
  • height: The height of the image or video in pixels. The value is zero for sound clips. (Number)
  • width: The width of the image or video in pixels. The value is zero for sound clips. (Number)

Quick Example

// retrieve supported image modes
var imageModes = navigator.device.capture.supportedImageModes;

// Select mode that has the highest horizontal resolution
var width = 0;
var selectedmode;
for each (var mode in imageModes) {
    if (mode.width > width) {
        width = mode.width;
        selectedmode = mode;
    }
}

Not supported by any platform. All configuration data arrays are empty.

Original source: MediaFile.getFormatData

MediaFile.getFormatData

Retrieves format information about the media capture file.

mediaFile.getFormatData(
    MediaFileDataSuccessCB successCallback,
    [MediaFileDataErrorCB errorCallback]
);

Description

This function asynchronously attempts to retrieve the format information for the media file. If successful, it invokes the MediaFileDataSuccessCB callback with a MediaFileData object. If the attempt fails, this function invokes the MediaFileDataErrorCB callback.

Supported Platforms

  • Android
  • BlackBerry WebWorks (OS 5.0 and higher)
  • iOS
  • Windows Phone 7 and 8
  • Windows 8

BlackBerry WebWorks Quirks

Does not provide an API for information about media files, so all MediaFileData objects return with default values.

Android Quirks

The API to access media file format information is limited, so not all MediaFileData properties are supported.

iOS Quirks

The API to access media file format information is limited, so not all MediaFileData properties are supported.

Original source: MediaFile

MediaFile

Encapsulates properties of a media capture file.

Properties

  • name: The name of the file, without path information. (DOMString)
  • fullPath: The full path of the file, including the name. (DOMString)
  • type: The file's mime type (DOMString)
  • lastModifiedDate: The date and time when the file was last modified. (Date)
  • size: The size of the file, in bytes. (Number)

Methods

  • MediaFile.getFormatData: Retrieves the format information of the media file.
Original source: MediaFileData

MediaFileData

Encapsulates format information about a media file.

Properties

  • codecs: The actual format of the audio and video content. (DOMString)
  • bitrate: The average bitrate of the content. The value is zero for images. (Number)
  • height: The height of the image or video in pixels. The value is zero for audio clips. (Number)
  • width: The width of the image or video in pixels. The value is zero for audio clips. (Number)
  • duration: The length of the video or sound clip in seconds. The value is zero for images. (Number)

BlackBerry WebWorks Quirks

No API provides format information for media files, so the MediaFileData object returned by MediaFile.getFormatData features the following default values:

  • codecs: Not supported, and returns null.
  • bitrate: Not supported, and returns zero.
  • height: Not supported, and returns zero.
  • width: Not supported, and returns zero.
  • duration: Not supported, and returns zero.

Android Quirks

Supports the following MediaFileData properties:

  • codecs: Not supported, and returns null.
  • bitrate: Not supported, and returns zero.
  • height: Supported: image and video files only.
  • width: Supported: image and video files only.
  • duration: Supported: audio and video files only.

iOS Quirks

Supports the following MediaFileData properties:

  • codecs: Not supported, and returns null.
  • bitrate: Supported on iOS4 devices for audio only. Returns zero for images and videos.
  • height: Supported: image and video files only.
  • width: Supported: image and video files only.
  • duration: Supported: audio and video files only.
Original source: Capture

Capture

Provides access to the device's audio, image, and video capture capabilities.

Important privacy note: Collection and use of images, video, or audio from the device's camera or microphone raises important privacy issues. Your app's privacy policy should discuss how the app uses such sensors and whether the data recorded is shared with any other parties. In addition, if the app's use of the camera or microphone is not apparent in the user interface, you should provide a just-in-time notice prior to your app accessing the camera or microphone (if the device operating system doesn't do so already). That notice should provide the same information noted above, as well as obtaining the user's permission (e.g., by presenting choices for "OK" and "No Thanks"). Note that some app marketplaces may require your app to provide just-in-time notice and obtain permission from the user prior to accessing the camera or microphone. For more information, please see the Privacy Guide.

Objects

  • Capture
  • CaptureAudioOptions
  • CaptureImageOptions
  • CaptureVideoOptions
  • CaptureCallback
  • CaptureErrorCB
  • ConfigurationData
  • MediaFile
  • MediaFileData

Methods

  • capture.captureAudio
  • capture.captureImage
  • capture.captureVideo
  • MediaFile.getFormatData

Scope

The capture object is assigned to the navigator.device object, and therefore has global scope.

// The global capture object
var capture = navigator.device.capture;

Properties

  • supportedAudioModes: The audio recording formats supported by the device. (ConfigurationData[])
  • supportedImageModes: The recording image sizes and formats supported by the device. (ConfigurationData[])
  • supportedVideoModes: The recording video resolutions and formats supported by the device. (ConfigurationData[])

Methods

  • capture.captureAudio: Launch the device's audio recording application to record audio clips.
  • capture.captureImage: Launch the device's camera application to take photos.
  • capture.captureVideo: Launch the device's video recorder application to record videos.

Supported Platforms

  • Android
  • BlackBerry WebWorks (OS 5.0 and higher)
  • iOS
  • Windows Phone 7 and 8
  • Windows 8

Permissions

Android

app/res/xml/plugins.xml

<plugin name="Capture" value="org.apache.cordova.Capture"/>

app/AndroidManifest.xml

<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

BlackBerry WebWorks

www/plugins.xml

<plugin name="Capture" value="org.apache.cordova.capture.MediaCapture" />

www/config.xml

<feature id="blackberry.system"  required="true" version="1.0.0.0" />
<feature id="blackberry.io.file" required="true" version="1.0.0.0" />

iOS

config.xml

<plugin name="Capture" value="CDVCapture" />

Windows Phone

Properties/WPAppManifest.xml

<Capabilities>
    <Capability Name="ID_CAP_MEDIALIB" />
    <Capability Name="ID_CAP_MICROPHONE" />
    <Capability Name="ID_HW_FRONTCAMERA" />
    <Capability Name="ID_CAP_ISV_CAMERA" />
    <Capability Name="ID_CAP_CAMERA" />
</Capabilities>
Original source: capture.captureAudio

capture.captureAudio

Start the audio recorder application and return information about the captured audio clip file(s).

navigator.device.capture.captureAudio(
    CaptureCB captureSuccess, CaptureErrorCB captureError,  [CaptureAudioOptions options]
);

Description

Starts an asynchronous operation to capture audio recordings using the device's default audio recording application. The operation allows the device user to capture multiple recordings in a single session.

The capture operation ends when either the user exits the audio recording application, or the maximum number of recordings specified by CaptureAudioOptions.limit is reached. If no limit parameter value is specified, it defaults to one (1), and the capture operation terminates after the user records a single audio clip.

When the capture operation finishes, the CaptureCallback executes with an array of MediaFile objects describing each captured audio clip file. If the user terminates the operation before an audio clip is captured, the CaptureErrorCallback executes with a CaptureError object, featuring the CaptureError.CAPTURE_NO_MEDIA_FILES error code.

Supported Platforms

  • Android
  • BlackBerry WebWorks (OS 5.0 and higher)
  • iOS
  • Windows Phone 7 and 8
  • Windows 8

Quick Example

// capture callback
var captureSuccess = function(mediaFiles) {
    var i, path, len;
    for (i = 0, len = mediaFiles.length; i < len; i += 1) {
        path = mediaFiles[i].fullPath;
        // do something interesting with the file
    }
};

// capture error callback
var captureError = function(error) {
    navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error');
};

// start audio capture
navigator.device.capture.captureAudio(captureSuccess, captureError, {limit:2});

Full Example

<!DOCTYPE html>
<html>
  <head>
    <title>Capture Audio</title>

    <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
    <script type="text/javascript" charset="utf-8" src="json2.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Called when capture operation is finished
    //
    function captureSuccess(mediaFiles) {
        var i, len;
        for (i = 0, len = mediaFiles.length; i < len; i += 1) {
            uploadFile(mediaFiles[i]);
        }
    }

    // Called if something bad happens.
    //
    function captureError(error) {
        var msg = 'An error occurred during capture: ' + error.code;
        navigator.notification.alert(msg, null, 'Uh oh!');
    }

    // A button will call this function
    //
    function captureAudio() {
        // Launch device audio recording application,
        // allowing user to capture up to 2 audio clips
        navigator.device.capture.captureAudio(captureSuccess, captureError, {limit: 2});
    }

    // Upload files to server
    function uploadFile(mediaFile) {
        var ft = new FileTransfer(),
            path = mediaFile.fullPath,
            name = mediaFile.name;

        ft.upload(path,
            "http://my.domain.com/upload.php",
            function(result) {
                console.log('Upload success: ' + result.responseCode);
                console.log(result.bytesSent + ' bytes sent');
            },
            function(error) {
                console.log('Error uploading file ' + path + ': ' + error.code);
            },
            { fileName: name });
    }

    </script>
    </head>
    <body>
        <button onclick="captureAudio();">Capture Audio</button> <br>
    </body>
</html>

BlackBerry WebWorks Quirks

  • Cordova for BlackBerry WebWorks attempts to launch the Voice Notes Recorder application, provided by RIM, to capture audio recordings. The app receives a CaptureError.CAPTURE_NOT_SUPPORTED error code if the application is not installed on the device.

iOS Quirks

  • iOS does not have a default audio recording application, so a simple user interface is provided.

Windows Phone 7 and 8 Quirks

  • Windows Phone 7 does not have a default audio recording application, so a simple user interface is provided.
Original source: CaptureAudioOptions

CaptureAudioOptions

Encapsulates audio capture configuration options.

Properties

  • limit: The maximum number of audio clips the device user can record in a single capture operation. The value must be greater than or equal to 1 (defaults to 1).
  • duration: The maximum duration of an audio sound clip, in seconds.

Quick Example

// limit capture operation to 3 media files, no longer than 10 seconds each
var options = { limit: 3, duration: 10 };

navigator.device.capture.captureAudio(captureSuccess, captureError, options);

Android Quirks

  • The duration parameter is not supported. Recording lengths cannot be limited programmatically.

BlackBerry WebWorks Quirks

  • The duration parameter is not supported. Recording lengths cannot be limited programmatically.

iOS Quirks

  • The limit parameter is not supported, so only one recording can be created for each invocation.
Original source: capture.captureImage

capture.captureImage

Start the camera application and return information about captured image file(s).

navigator.device.capture.captureImage(
    CaptureCB captureSuccess, CaptureErrorCB captureError, [CaptureImageOptions options]
);

Description

Starts an asynchronous operation to capture images using the device's camera application. The operation allows users to capture more than one image in a single session.

The capture operation ends either when the user closes the camera application, or the maximum number of recordings specified by CaptureAudioOptions.limit is reached. If no limit value is specified, it defaults to one (1), and the capture operation terminates after the user captures a single image.

When the capture operation finishes, it invokes the CaptureCB callback with an array of MediaFile objects describing each captured image file. If the user terminates the operation before capturing an image, the CaptureErrorCB callback executes with a CaptureError object featuring a CaptureError.CAPTURE_NO_MEDIA_FILES error code.

Supported Platforms

  • Android
  • BlackBerry WebWorks (OS 5.0 and higher)
  • iOS
  • Windows Phone 7 and 8
  • Windows 8

Windows Phone 7 Quirks

Invoking the native camera application while your device is connected via Zune does not work, and the error callback executes.

Quick Example

// capture callback
var captureSuccess = function(mediaFiles) {
    var i, path, len;
    for (i = 0, len = mediaFiles.length; i < len; i += 1) {
        path = mediaFiles[i].fullPath;
        // do something interesting with the file
    }
};

// capture error callback
var captureError = function(error) {
    navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error');
};

// start image capture
navigator.device.capture.captureImage(captureSuccess, captureError, {limit:2});

Full Example

<!DOCTYPE html>
<html>
  <head>
    <title>Capture Image</title>

    <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
    <script type="text/javascript" charset="utf-8" src="json2.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Called when capture operation is finished
    //
    function captureSuccess(mediaFiles) {
        var i, len;
        for (i = 0, len = mediaFiles.length; i < len; i += 1) {
            uploadFile(mediaFiles[i]);
        }
    }

    // Called if something bad happens.
    //
    function captureError(error) {
        var msg = 'An error occurred during capture: ' + error.code;
        navigator.notification.alert(msg, null, 'Uh oh!');
    }

    // A button will call this function
    //
    function captureImage() {
        // Launch device camera application,
        // allowing user to capture up to 2 images
        navigator.device.capture.captureImage(captureSuccess, captureError, {limit: 2});
    }

    // Upload files to server
    function uploadFile(mediaFile) {
        var ft = new FileTransfer(),
            path = mediaFile.fullPath,
            name = mediaFile.name;

        ft.upload(path,
            "http://my.domain.com/upload.php",
            function(result) {
                console.log('Upload success: ' + result.responseCode);
                console.log(result.bytesSent + ' bytes sent');
            },
            function(error) {
                console.log('Error uploading file ' + path + ': ' + error.code);
            },
            { fileName: name });
    }

    </script>
    </head>
    <body>
        <button onclick="captureImage();">Capture Image</button> <br>
    </body>
</html>
Original source: CaptureImageOptions

CaptureImageOptions

Encapsulates image capture configuration options.

Properties

  • limit: The maximum number of images the user can capture in a single capture operation. The value must be greater than or equal to 1 (defaults to 1).

Quick Example

// limit capture operation to 3 images
var options = { limit: 3 };

navigator.device.capture.captureImage(captureSuccess, captureError, options);

iOS Quirks

  • The limit parameter is not supported, and only one image is taken per invocation.
Original source: capture.captureVideo

capture.captureVideo

Start the video recorder application and return information about captured video clip file(s).

navigator.device.capture.captureVideo(
    CaptureCB captureSuccess, CaptureErrorCB captureError, [CaptureVideoOptions options]
);

Description

Starts an asynchronous operation to capture video recordings using the device's video recording application. The operation allows the user to capture more than one recordings in a single session.

The capture operation ends when either the user exits the video recording application, or the maximum number of recordings specified by CaptureVideoOptions.limit is reached. If no limit parameter value is specified, it defaults to one (1), and the capture operation terminates after the user records a single video clip.

When the capture operation finishes, it the CaptureCB callback executes with an array of MediaFile objects describing each captured video clip file. If the user terminates the operation before capturing a video clip, the CaptureErrorCB callback executes with a CaptureError object featuring a CaptureError.CAPTURE_NO_MEDIA_FILES error code.

Supported Platforms

  • Android
  • BlackBerry WebWorks (OS 5.0 and higher)
  • iOS
  • Windows Phone 7 and 8
  • Windows 8

Quick Example

// capture callback
var captureSuccess = function(mediaFiles) {
    var i, path, len;
    for (i = 0, len = mediaFiles.length; i < len; i += 1) {
        path = mediaFiles[i].fullPath;
        // do something interesting with the file
    }
};

// capture error callback
var captureError = function(error) {
    navigator.notification.alert('Error code: ' + error.code, null, 'Capture Error');
};

// start video capture
navigator.device.capture.captureVideo(captureSuccess, captureError, {limit:2});

Full Example

<!DOCTYPE html>
<html>
  <head>
    <title>Capture Video</title>

    <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
    <script type="text/javascript" charset="utf-8" src="json2.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Called when capture operation is finished
    //
    function captureSuccess(mediaFiles) {
        var i, len;
        for (i = 0, len = mediaFiles.length; i < len; i += 1) {
            uploadFile(mediaFiles[i]);
        }
    }

    // Called if something bad happens.
    //
    function captureError(error) {
        var msg = 'An error occurred during capture: ' + error.code;
        navigator.notification.alert(msg, null, 'Uh oh!');
    }

    // A button will call this function
    //
    function captureVideo() {
        // Launch device video recording application,
        // allowing user to capture up to 2 video clips
        navigator.device.capture.captureVideo(captureSuccess, captureError, {limit: 2});
    }

    // Upload files to server
    function uploadFile(mediaFile) {
        var ft = new FileTransfer(),
            path = mediaFile.fullPath,
            name = mediaFile.name;

        ft.upload(path,
            "http://my.domain.com/upload.php",
            function(result) {
                console.log('Upload success: ' + result.responseCode);
                console.log(result.bytesSent + ' bytes sent');
            },
            function(error) {
                console.log('Error uploading file ' + path + ': ' + error.code);
            },
            { fileName: name });
    }

    </script>
    </head>
    <body>
        <button onclick="captureVideo();">Capture Video</button> <br>
    </body>
</html>

BlackBerry WebWorks Quirks

  • Cordova for BlackBerry WebWorks attempts to launch the Video Recorder application, provided by RIM, to capture video recordings. The app receives a CaptureError.CAPTURE_NOT_SUPPORTED error code if the application is not installed on the device.
Original source: CaptureVideoOptions

CaptureVideoOptions

Encapsulates video capture configuration options.

Properties

  • limit: The maximum number of video clips the device's user can capture in a single capture operation. The value must be greater than or equal to 1 (defaults to 1).
  • duration: The maximum duration of a video clip, in seconds.

Quick Example

// limit capture operation to 3 video clips
var options = { limit: 3 };

navigator.device.capture.captureVideo(captureSuccess, captureError, options);

BlackBerry WebWorks Quirks

  • The duration parameter is not supported, so the length of recordings cannot be limited programmatically.

iOS Quirks

  • The limit parameter is not supported. Only one video is recorded per invocation.
Original source: media.getCurrentPosition

media.getCurrentPosition

Returns the current position within an audio file.

media.getCurrentPosition(mediaSuccess, [mediaError]);

Parameters

  • mediaSuccess: The callback that is passed the current position in seconds.
  • mediaError: (Optional) The callback to execute if an error occurs.

Description

An asynchronous function that returns the current position of the underlying audio file of a Media object. Also updates the Media object's position parameter.

Supported Platforms

  • Android
  • BlackBerry WebWorks (OS 5.0 and higher)
  • iOS
  • Windows Phone 7 and 8
  • Tizen
  • Windows 8

Quick Example

// Audio player
//
var my_media = new Media(src, onSuccess, onError);

// Update media position every second
var mediaTimer = setInterval(function () {
    // get media position
    my_media.getCurrentPosition(
        // success callback
        function (position) {
            if (position > -1) {
                console.log((position) + " sec");
            }
        },
        // error callback
        function (e) {
            console.log("Error getting pos=" + e);
        }
    );
}, 1000);

Full Example

    <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
                  "http://www.w3.org/TR/html4/strict.dtd">
    <html>
      <head>
        <title>Media Example</title>

        <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
        <script type="text/javascript" charset="utf-8">

        // Wait for device API libraries to load
        //
        document.addEventListener("deviceready", onDeviceReady, false);

        // device APIs are available
        //
        function onDeviceReady() {
            playAudio("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3");
        }

        // Audio player
        //
        var my_media = null;
        var mediaTimer = null;

        // Play audio
        //
        function playAudio(src) {
            // Create Media object from src
            my_media = new Media(src, onSuccess, onError);

            // Play audio
            my_media.play();

            // Update my_media position every second
            if (mediaTimer == null) {
                mediaTimer = setInterval(function() {
                    // get my_media position
                    my_media.getCurrentPosition(
                        // success callback
                        function(position) {
                            if (position > -1) {
                                setAudioPosition((position) + " sec");
                            }
                        },
                        // error callback
                        function(e) {
                            console.log("Error getting pos=" + e);
                            setAudioPosition("Error: " + e);
                        }
                    );
                }, 1000);
            }
        }

        // Pause audio
        //
        function pauseAudio() {
            if (my_media) {
                my_media.pause();
            }
        }

        // Stop audio
        //
        function stopAudio() {
            if (my_media) {
                my_media.stop();
            }
            clearInterval(mediaTimer);
            mediaTimer = null;
        }

        // onSuccess Callback
        //
        function onSuccess() {
            console.log("playAudio():Audio Success");
        }

        // onError Callback
        //
        function onError(error) {
            alert('code: '    + error.code    + '\n' +
                  'message: ' + error.message + '\n');
        }

        // Set audio position
        //
        function setAudioPosition(position) {
            document.getElementById('audio_position').innerHTML = position;
        }

        </script>
      </head>
      <body>
        <a href="#" class="btn large" onclick="playAudio('http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3');">Play Audio</a>
        <a href="#" class="btn large" onclick="pauseAudio();">Pause Playing Audio</a>
        <a href="#" class="btn large" onclick="stopAudio();">Stop Playing Audio</a>
        <p id="audio_position"></p>
      </body>
    </html>
Original source: media.getDuration

media.getDuration

Returns the duration of an audio file.

media.getDuration();

Description

The media.getDuration method executes synchronously, returning the duration of the audio file in seconds, if known. If the duration is unknown, it returns a value of -1.

Supported Platforms

  • Android
  • BlackBerry WebWorks (OS 5.0 and higher)
  • iOS
  • Windows Phone 7 and 8
  • Tizen
  • Windows 8

Quick Example

// Audio player
//
var my_media = new Media(src, onSuccess, onError);

// Get duration
var counter = 0;
var timerDur = setInterval(function() {
    counter = counter + 100;
    if (counter > 2000) {
        clearInterval(timerDur);
    }
    var dur = my_media.getDuration();
    if (dur > 0) {
        clearInterval(timerDur);
        document.getElementById('audio_duration').innerHTML = (dur) + " sec";
    }
}, 100);

Full Example

    <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
                          "http://www.w3.org/TR/html4/strict.dtd">
    <html>
      <head>
        <title>Media Example</title>

        <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
        <script type="text/javascript" charset="utf-8">

        // Wait for device API libraries to load
        //
        document.addEventListener("deviceready", onDeviceReady, false);

        // device APIs are available
        //
        function onDeviceReady() {
            playAudio("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3");
        }

        // Audio player
        //
        var my_media = null;
        var mediaTimer = null;

        // Play audio
        //
        function playAudio(src) {
            // Create Media object from src
            my_media = new Media(src, onSuccess, onError);

            // Play audio
            my_media.play();

            // Update my_media position every second
            if (mediaTimer == null) {
                mediaTimer = setInterval(function() {
                    // get my_media position
                    my_media.getCurrentPosition(
                        // success callback
                        function(position) {
                            if (position > -1) {
                                setAudioPosition((position) + " sec");
                            }
                        },
                        // error callback
                        function(e) {
                            console.log("Error getting pos=" + e);
                            setAudioPosition("Error: " + e);
                        }
                    );
                }, 1000);
            }
        }

        // Pause audio
        //
        function pauseAudio() {
            if (my_media) {
                my_media.pause();
            }
        }

        // Stop audio
        //
        function stopAudio() {
            if (my_media) {
                my_media.stop();
            }
            clearInterval(mediaTimer);
            mediaTimer = null;
        }

        // onSuccess Callback
        //
        function onSuccess() {
            console.log("playAudio():Audio Success");
        }

        // onError Callback
        //
        function onError(error) {
            alert('code: '    + error.code    + '\n' +
                  'message: ' + error.message + '\n');
        }

        // Set audio position
        //
        function setAudioPosition(position) {
            document.getElementById('audio_position').innerHTML = position;
        }

        </script>
      </head>
      <body>
        <a href="#" class="btn large" onclick="playAudio('http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3');">Play Audio</a>
        <a href="#" class="btn large" onclick="pauseAudio();">Pause Playing Audio</a>
        <a href="#" class="btn large" onclick="stopAudio();">Stop Playing Audio</a>
        <p id="audio_position"></p>
      </body>
    </html>
Original source: media.pause

media.pause

Pauses playing an audio file.

media.pause();

Description

The media.pause method executes synchronously, and pauses playing an audio file.

Supported Platforms

  • Android
  • BlackBerry WebWorks (OS 5.0 and higher)
  • iOS
  • Windows Phone 7 and 8
  • Tizen
  • Windows 8

Quick Example

// Play audio
//
function playAudio(url) {
    // Play the audio file at url
    var my_media = new Media(url,
        // success callback
        function () { console.log("playAudio():Audio Success"); },
        // error callback
        function (err) { console.log("playAudio():Audio Error: " + err); }
    );

    // Play audio
    my_media.play();

    // Pause after 10 seconds
    setTimeout(function () {
        media.pause();
    }, 10000);
}

Full Example

    <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
                          "http://www.w3.org/TR/html4/strict.dtd">
    <html>
      <head>
        <title>Media Example</title>

        <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
        <script type="text/javascript" charset="utf-8">

        // Wait for device API libraries to load
        //
        document.addEventListener("deviceready", onDeviceReady, false);

        // device APIs are available
        //
        function onDeviceReady() {
            playAudio("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3");
        }

        // Audio player
        //
        var my_media = null;
        var mediaTimer = null;

        // Play audio
        //
        function playAudio(src) {
            // Create Media object from src
            my_media = new Media(src, onSuccess, onError);

            // Play audio
            my_media.play();

            // Update my_media position every second
            if (mediaTimer == null) {
                mediaTimer = setInterval(function() {
                    // get my_media position
                    my_media.getCurrentPosition(
                        // success callback
                        function(position) {
                            if (position > -1) {
                                setAudioPosition((position) + " sec");
                            }
                        },
                        // error callback
                        function(e) {
                            console.log("Error getting pos=" + e);
                            setAudioPosition("Error: " + e);
                        }
                    );
                }, 1000);
            }
        }

        // Pause audio
        //
        function pauseAudio() {
            if (my_media) {
                my_media.pause();
            }
        }

        // Stop audio
        //
        function stopAudio() {
            if (my_media) {
                my_media.stop();
            }
            clearInterval(mediaTimer);
            mediaTimer = null;
        }

        // onSuccess Callback
        //
        function onSuccess() {
            console.log("playAudio():Audio Success");
        }

        // onError Callback
        //
        function onError(error) {
            alert('code: '    + error.code    + '\n' +
                  'message: ' + error.message + '\n');
        }

        // Set audio position
        //
        function setAudioPosition(position) {
            document.getElementById('audio_position').innerHTML = position;
        }

        </script>
      </head>
      <body>
        <a href="#" class="btn large" onclick="playAudio('http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3');">Play Audio</a>
        <a href="#" class="btn large" onclick="pauseAudio();">Pause Playing Audio</a>
        <a href="#" class="btn large" onclick="stopAudio();">Stop Playing Audio</a>
        <p id="audio_position"></p>
      </body>
    </html>
Original source: media.play

media.play

Starts or resumes playing an audio file.

media.play();

Description

The media.play method executes synchronously, and starts or resumes playing an audio file.

Supported Platforms

  • Android
  • BlackBerry WebWorks (OS 5.0 and higher)
  • iOS
  • Windows Phone 7 and 8
  • Tizen
  • Windows 8

Quick Example

// Play audio
//
function playAudio(url) {
    // Play the audio file at url
    var my_media = new Media(url,
        // success callback
        function () {
            console.log("playAudio():Audio Success");
        },
        // error callback
        function (err) {
            console.log("playAudio():Audio Error: " + err);
        }
    );
    // Play audio
    my_media.play();
}

Full Example

    <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
                          "http://www.w3.org/TR/html4/strict.dtd">
    <html>
      <head>
        <title>Media Example</title>

        <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
        <script type="text/javascript" charset="utf-8">

        // Wait for device API libraries to load
        //
        document.addEventListener("deviceready", onDeviceReady, false);

        // device APIs are available
        //
        function onDeviceReady() {
            playAudio("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3");
        }

        // Audio player
        //
        var my_media = null;
        var mediaTimer = null;

        // Play audio
        //
        function playAudio(src) {
            if (my_media == null) {
                // Create Media object from src
                my_media = new Media(src, onSuccess, onError);
            } // else play current audio
            // Play audio
            my_media.play();

            // Update my_media position every second
            if (mediaTimer == null) {
                mediaTimer = setInterval(function() {
                    // get my_media position
                    my_media.getCurrentPosition(
                        // success callback
                        function(position) {
                            if (position > -1) {
                                setAudioPosition((position) + " sec");
                            }
                        },
                        // error callback
                        function(e) {
                            console.log("Error getting pos=" + e);
                            setAudioPosition("Error: " + e);
                        }
                    );
                }, 1000);
            }
        }

        // Pause audio
        //
        function pauseAudio() {
            if (my_media) {
                my_media.pause();
            }
        }

        // Stop audio
        //
        function stopAudio() {
            if (my_media) {
                my_media.stop();
            }
            clearInterval(mediaTimer);
            mediaTimer = null;
        }

        // onSuccess Callback
        //
        function onSuccess() {
            console.log("playAudio():Audio Success");
        }

        // onError Callback
        //
        function onError(error) {
            alert('code: '    + error.code    + '\n' +
                  'message: ' + error.message + '\n');
        }

        // Set audio position
        //
        function setAudioPosition(position) {
            document.getElementById('audio_position').innerHTML = position;
        }

        </script>
      </head>
      <body>
        <a href="#" class="btn large" onclick="playAudio('http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3');">Play Audio</a>
        <a href="#" class="btn large" onclick="pauseAudio();">Pause Playing Audio</a>
        <a href="#" class="btn large" onclick="stopAudio();">Stop Playing Audio</a>
        <p id="audio_position"></p>
      </body>
    </html>

BlackBerry WebWorks Quirks

  • BlackBerry devices support a limited number of simultaneous audio channels. CDMA devices only support a single audio channel. Other devices support up to two simultaneous channels. An attempt to play more audio files than the supported amount results in previous playback being stopped.

iOS Quirks

  • numberOfLoops: Pass this option to the play method to specify the number of times you want the media file to play, e.g.:

      var myMedia = new Media("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3")
  myMedia.play({ numberOfLoops: 2 })

  • playAudioWhenScreenIsLocked: Pass in this option to the play method to specify whether you want to allow playback when the screen is locked. If set to true (the default value), the state of the hardware mute button is ignored, e.g.:

      var myMedia = new Media("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3")
  myMedia.play({ playAudioWhenScreenIsLocked : false })

  • order of file search: When only a file name or simple path is provided, iOS searches in the www directory for the file, then in the application's documents/tmp directory:

      var myMedia = new Media("audio/beer.mp3")
  myMedia.play()  // first looks for file in www/audio/beer.mp3 then in <application>/documents/tmp/audio/beer.mp3
Original source: media.release

media.release

Releases the underlying operating system's audio resources.

media.release();

Description

The media.release method executes synchronously, releasing the underlying operating system's audio resources. This is particularly important for Android, since there are a finite amount of OpenCore instances for media playback. Applications should call the release function for any Media resource that is no longer needed.

Supported Platforms

  • Android
  • BlackBerry WebWorks (OS 5.0 and higher)
  • iOS
  • Windows Phone 7 and 8
  • Tizen
  • Windows 8

Quick Example

// Audio player
//
var my_media = new Media(src, onSuccess, onError);

my_media.play();
my_media.stop();
my_media.release();

Full Example

    <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
                          "http://www.w3.org/TR/html4/strict.dtd">
    <html>
      <head>
        <title>Media Example</title>

        <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
        <script type="text/javascript" charset="utf-8">

        // Wait for device API libraries to load
        //
        document.addEventListener("deviceready", onDeviceReady, false);

        // device APIs are available
        //
        function onDeviceReady() {
            playAudio("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3");
        }

        // Audio player
        //
        var my_media = null;
        var mediaTimer = null;

        // Play audio
        //
        function playAudio(src) {
            // Create Media object from src
            my_media = new Media(src, onSuccess, onError);

            // Play audio
            my_media.play();

            // Update my_media position every second
            if (mediaTimer == null) {
                mediaTimer = setInterval(function() {
                    // get my_media position
                    my_media.getCurrentPosition(
                        // success callback
                        function(position) {
                            if (position > -1) {
                                setAudioPosition((position) + " sec");
                            }
                        },
                        // error callback
                        function(e) {
                            console.log("Error getting pos=" + e);
                            setAudioPosition("Error: " + e);
                        }
                    );
                }, 1000);
            }
        }

        // Pause audio
        //
        function pauseAudio() {
            if (my_media) {
                my_media.pause();
            }
        }

        // Stop audio
        //
        function stopAudio() {
            if (my_media) {
                my_media.stop();
            }
            clearInterval(mediaTimer);
            mediaTimer = null;
        }

        // onSuccess Callback
        //
        function onSuccess() {
            console.log("playAudio():Audio Success");
        }

        // onError Callback
        //
        function onError(error) {
            alert('code: '    + error.code    + '\n' +
                  'message: ' + error.message + '\n');
        }

        // Set audio position
        //
        function setAudioPosition(position) {
            document.getElementById('audio_position').innerHTML = position;
        }

        </script>
      </head>
      <body>
        <a href="#" class="btn large" onclick="playAudio('http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3');">Play Audio</a>
        <a href="#" class="btn large" onclick="pauseAudio();">Pause Playing Audio</a>
        <a href="#" class="btn large" onclick="stopAudio();">Stop Playing Audio</a>
        <p id="audio_position"></p>
      </body>
    </html>
Original source: media.seekTo

media.seekTo

Sets the current position within an audio file.

media.seekTo(milliseconds);

Parameters

  • milliseconds: The position to set the playback position within the audio, in milliseconds.

Description

The media.seekTo executes asynchronously, updating the current playback position within an audio file referenced by a Media object. Also updates the Media object's position parameter.

Supported Platforms

  • Android
  • BlackBerry WebWorks (OS 6.0 and higher)
  • iOS
  • Windows Phone 7 and 8
  • Tizen
  • Windows 8

Quick Example

// Audio player
//
var my_media = new Media(src, onSuccess, onError);
    my_media.play();
// SeekTo to 10 seconds after 5 seconds
setTimeout(function() {
    my_media.seekTo(10000);
}, 5000);

Full Example

    <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 
                          "http://www.w3.org/TR/html4/strict.dtd">
    <html>
      <head>
        <title>Media Example</title>

        <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
        <script type="text/javascript" charset="utf-8">

        // Wait for device API libraries to load
        //
        document.addEventListener("deviceready", onDeviceReady, false);

        // device APIs are available
        //
        function onDeviceReady() {
            playAudio("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3");
        }

        // Audio player
        //
        var my_media = null;
        var mediaTimer = null;

        // Play audio
        //
        function playAudio(src) {
            // Create Media object from src
            my_media = new Media(src, onSuccess, onError);

            // Play audio
            my_media.play();

            // Update media position every second
            mediaTimer = setInterval(function() {
                // get media position
                my_media.getCurrentPosition(
                    // success callback
                    function(position) {
                        if (position > -1) {
                            setAudioPosition(position + " sec");
                        }
                    },
                    // error callback
                    function(e) {
                        console.log("Error getting pos=" + e);
                    }
                );
            }, 1000);

            // SeekTo to 10 seconds after 5 seconds
            setTimeout(function() {
                my_media.seekTo(10000);
            }, 5000);
        }

        // Stop audio
        //
        function stopAudio() {
            if (my_media) {
                my_media.stop();
            }
            clearInterval(mediaTimer);
            mediaTimer = null;
        }

        // onSuccess Callback
        //
        function onSuccess() {
            console.log("playAudio():Audio Success");
        }

        // onError Callback
        //
        function onError(error) {
            alert('code: '    + error.code    + '\n' +
                  'message: ' + error.message + '\n');
        }

        // Set audio position
        //
        function setAudioPosition(position) {
            document.getElementById('audio_position').innerHTML = position;
        }

        </script>
      </head>
      <body>
        <a href="#" class="btn large" onclick="playAudio('http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3');">Play Audio</a>
        <a href="#" class="btn large" onclick="stopAudio();">Stop Playing Audio</a>
        <p id="audio_position"></p>
      </body>
    </html>

BlackBerry WebWorks Quirks

  • Not supported on BlackBerry OS 5 devices.
Original source: media.setVolume

media.setVolume

Set the volume for an audio file.

media.setVolume(volume);

Paramters

  • volume: The volume to set for playback. The value must be within the range of 0.0 to 1.0.

Description

Function media.setVolume is an asynchronous function that sets the volume during audio playback.

Supported Platforms

  • Android
  • iOS

Quick Example

// Play audio
//
function playAudio(url) {
    // Play the audio file at url
    var my_media = new Media(url,
        // success callback
        function() {
            console.log("playAudio():Audio Success");
        },
        // error callback
        function(err) {
            console.log("playAudio():Audio Error: "+err);
    });

    // Play audio
    my_media.play();

    // Mute volume after 2 seconds
    setTimeout(function() {
        my_media.setVolume('0.0');
    }, 2000);

    // Set volume to 1.0 after 5 seconds
    setTimeout(function() {
        my_media.setVolume('1.0');
    }, 5000);
}

Full Example

    <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
                          "http://www.w3.org/TR/html4/strict.dtd">
    <html>
      <head>
        <title>Media Example</title>

        <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
        <script type="text/javascript" charset="utf-8">

        // Wait for Cordova to load
        //
        document.addEventListener("deviceready", onDeviceReady, false);

        // Cordova is ready
        //
        function onDeviceReady() {
            playAudio("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3");
        }

        // Audio player
        //
        var my_media = null;
        var mediaTimer = null;

        // Play audio
        //
        function playAudio(src) {
            // Create Media object from src
            my_media = new Media(src, onSuccess, onError);

            // Play audio
            my_media.play();

            // Update my_media position every second
            if (mediaTimer == null) {
                mediaTimer = setInterval(function() {
                    // get my_media position
                    my_media.getCurrentPosition(
                        // success callback
                        function(position) {
                            if (position > -1) {
                                setAudioPosition((position) + " sec");
                            }
                        },
                        // error callback
                        function(e) {
                            console.log("Error getting pos=" + e);
                            setAudioPosition("Error: " + e);
                        }
                    );
                }, 1000);
            }
        }

        // Set audio volume
        //
        function setVolume(volume) {
            if (my_media) {
                my_media.setVolume(volume);
            }
        }

        // Stop audio
        //
        function stopAudio() {
            if (my_media) {
                my_media.stop();
            }
            clearInterval(mediaTimer);
            mediaTimer = null;
        }

        // onSuccess Callback
        //
        function onSuccess() {
            console.log("playAudio():Audio Success");
        }

        // onError Callback
        //
        function onError(error) {
            alert('code: '    + error.code    + '\n' + 
                  'message: ' + error.message + '\n');
        }

        // Set audio position
        //
        function setAudioPosition(position) {
            document.getElementById('audio_position').innerHTML = position;
        }

        </script>
      </head>
      <body>
        <a href="#" class="btn large" onclick="playAudio('http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3');">Play Audio</a>
        <a href="#" class="btn large" onclick="setVolume('0.0');">Mute Audio</a>
        <a href="#" class="btn large" onclick="setVolume('1.0');">Unmute Audio</a>
        <a href="#" class="btn large" onclick="stopAudio();">Stop Playing Audio</a>
        <p id="audio_position"></p>
      </body>
    </html>
Original source: media.startRecord

media.startRecord

Starts recording an audio file.

media.startRecord();

Description

The media.startRecord method executes synchronously, starts a recording for an audio file.

Supported Platforms

  • Android
  • BlackBerry WebWorks (OS 5.0 and higher)
  • iOS
  • Windows Phone 7 and 8
  • Windows 8

Quick Example

// Record audio
//
function recordAudio() {
    var src = "myrecording.mp3";
    var mediaRec = new Media(src,
        // success callback
        function() {
            console.log("recordAudio():Audio Success");
        },

        // error callback
        function(err) {
            console.log("recordAudio():Audio Error: "+ err.code);
        });

    // Record audio
    mediaRec.startRecord();
}

Full Example

<!DOCTYPE html>
<html>
  <head>
    <title>Device Properties Example</title>

    <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for device API libraries to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // Record audio
    //
    function recordAudio() {
        var src = "myrecording.amr";
        var mediaRec = new Media(src, onSuccess, onError);

        // Record audio
        mediaRec.startRecord();

        // Stop recording after 10 sec
        var recTime = 0;
        var recInterval = setInterval(function() {
            recTime = recTime + 1;
            setAudioPosition(recTime + " sec");
            if (recTime >= 10) {
                clearInterval(recInterval);
                mediaRec.stopRecord();
            }
        }, 1000);
    }

    // device APIs are available
    //
    function onDeviceReady() {
        recordAudio();
    }

    // onSuccess Callback
    //
    function onSuccess() {
        console.log("recordAudio():Audio Success");
    }

    // onError Callback
    //
    function onError(error) {
        alert('code: '    + error.code    + '\n' +
              'message: ' + error.message + '\n');
    }

    // Set audio position
    //
    function setAudioPosition(position) {
        document.getElementById('audio_position').innerHTML = position;
    }

    </script>
  </head>
  <body>
    <p id="media">Recording audio...</p>
    <p id="audio_position"></p>
  </body>
</html>

Android Quirks

  • Android devices record audio in Adaptive Multi-Rate format. The specified file should end with a .amr extension.

BlackBerry WebWorks Quirks

  • BlackBerry devices record audio in Adaptive Multi-Rate format. The specified file must end with a .amr extension.

iOS Quirks

  • iOS only records to files of type .wav and returns an error if the file name extension is not correct.

  • If a full path is not provided, the recording is placed in the application's documents/tmp directory. This can be accessed via the File API using LocalFileSystem.TEMPORARY. Any subdirectory specified at record time must already exist.

  • Files can be recorded and played back using the documents URI:

      var myMedia = new Media("documents://beer.mp3")

Tizen Quirks

  • Not supported on Tizen devices.
Original source: media.stop

media.stop

Stops playing an audio file.

media.stop();

Description

The media.stop method executes synchronously to stop playing an audio file.

Supported Platforms

  • Android
  • BlackBerry WebWorks (OS 5.0 and higher)
  • iOS
  • Windows Phone 7 and 8
  • Tizen
  • Windows 8

Quick Example

// Play audio
//
function playAudio(url) {
    // Play the audio file at url
    var my_media = new Media(url,
        // success callback
        function() {
            console.log("playAudio():Audio Success");
        },
        // error callback
        function(err) {
            console.log("playAudio():Audio Error: "+err);
        }
    );

    // Play audio
    my_media.play();

    // Pause after 10 seconds
    setTimeout(function() {
        my_media.stop();
    }, 10000);
}

Full Example

    <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
                          "http://www.w3.org/TR/html4/strict.dtd">
    <html>
      <head>
        <title>Media Example</title>

        <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
        <script type="text/javascript" charset="utf-8">

        // Wait for device API libraries to load
        //
        document.addEventListener("deviceready", onDeviceReady, false);

        // device APIs are available
        //
        function onDeviceReady() {
            playAudio("http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3");
        }

        // Audio player
        //
        var my_media = null;
        var mediaTimer = null;

        // Play audio
        //
        function playAudio(src) {
            // Create Media object from src
            my_media = new Media(src, onSuccess, onError);

            // Play audio
            my_media.play();

            // Update my_media position every second
            if (mediaTimer == null) {
                mediaTimer = setInterval(function() {
                    // get my_media position
                    my_media.getCurrentPosition(
                        // success callback
                        function(position) {
                            if (position > -1) {
                                setAudioPosition((position) + " sec");
                            }
                        },
                        // error callback
                        function(e) {
                            console.log("Error getting pos=" + e);
                            setAudioPosition("Error: " + e);
                        }
                    );
                }, 1000);
            }
        }

        // Pause audio
        //
        function pauseAudio() {
            if (my_media) {
                my_media.pause();
            }
        }

        // Stop audio
        //
        function stopAudio() {
            if (my_media) {
                my_media.stop();
            }
            clearInterval(mediaTimer);
            mediaTimer = null;
        }

        // onSuccess Callback
        //
        function onSuccess() {
            console.log("playAudio():Audio Success");
        }

        // onError Callback
        //
        function onError(error) {
            alert('code: '    + error.code    + '\n' +
                  'message: ' + error.message + '\n');
        }

        // Set audio position
        //
        function setAudioPosition(position) {
            document.getElementById('audio_position').innerHTML = position;
        }

        </script>
      </head>
      <body>
        <a href="#" class="btn large" onclick="playAudio('http://audio.ibeat.org/content/p1rj1s/p1rj1s_-_rockGuitar.mp3');">Play Audio</a>
        <a href="#" class="btn large" onclick="pauseAudio();">Pause Playing Audio</a>
        <a href="#" class="btn large" onclick="stopAudio();">Stop Playing Audio</a>
        <p id="audio_position"></p>
      </body>
    </html>
Original source: media.stopRecord

media.stopRecord

Stops recording an audio file.

media.stopRecord();

Description

The media.stopRecord method executes synchronously, stopping the recording of an audio file.

Supported Platforms

  • Android
  • BlackBerry WebWorks (OS 5.0 and higher)
  • iOS
  • Windows Phone 7 and 8
  • Windows 8

Quick Example

// Record audio
//
function recordAudio() {
    var src = "myrecording.mp3";
    var mediaRec = new Media(src,
        // success callback
        function() {
            console.log("recordAudio():Audio Success");
        },

        // error callback
        function(err) {
            console.log("recordAudio():Audio Error: "+ err.code);
        }
    );

    // Record audio
    mediaRec.startRecord();

    // Stop recording after 10 seconds
    setTimeout(function() {
        mediaRec.stopRecord();
    }, 10000);
}

Full Example

<!DOCTYPE html>
<html>
  <head>
    <title>Device Properties Example</title>

    <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for device API libraries to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // Record audio
    //
    function recordAudio() {
        var src = "myrecording.mp3";
        var mediaRec = new Media(src, onSuccess, onError);

        // Record audio
        mediaRec.startRecord();

        // Stop recording after 10 sec
        var recTime = 0;
        var recInterval = setInterval(function() {
            recTime = recTime + 1;
            setAudioPosition(recTime + " sec");
            if (recTime >= 10) {
                clearInterval(recInterval);
                mediaRec.stopRecord();
            }
        }, 1000);
    }

    // device APIs are available
    //
    function onDeviceReady() {
        recordAudio();
    }

    // onSuccess Callback
    //
    function onSuccess() {
        console.log("recordAudio():Audio Success");
    }

    // onError Callback
    //
    function onError(error) {
        alert('code: '    + error.code    + '\n' +
              'message: ' + error.message + '\n');
    }

    // Set audio position
    //
    function setAudioPosition(position) {
        document.getElementById('audio_position').innerHTML = position;
    }

    </script>
  </head>
  <body>
    <p id="media">Recording audio...</p>
    <p id="audio_position"></p>
  </body>
</html>

Tizen Quirks

  • Not supported on Tizen devices.

Sources & archive notes

Recovered repository material is attributed to its original authors and distributed with its source license. Changes: FreeSoft layout, archive context, navigation, link and image locations. Apache License 2.0 · Notices and provenance. Editorial material is labeled separately.