media Methods

The media Object consists of the following methods.

Pauses the playback of a media file.

Syntax

pause();

Example


var theFile = new kony.io.File("MyAudioFile.mp3");
var mediaObj = kony.media.createFromFile(theFile);
mediaObj.pause();

Input Parameters

None

Return Values

None

Remarks

This method only has an effect if a media file is currently being played.

Platform Availability

  • Android
  • iOS

Plays a media file.

Syntax

play(repeatCount);

Input Parameters

Parameter Description
repeatCount An integer specifying the number of time the media is played. The default is 1.
 

Example


var theFile = new kony.io.File("MyAudioFile.mp3");
var mediaObj =  kony.media.createFromFile(theFile);
mediaObj.play(5);

Return Values

None

Remarks

If your app calls this method and does not provide a value for the repeatCount parameter, this method plays the audio file once. if the value for the repeatCount parameter is negative, the file plays indefinitely. Setting the repeatCount parameter to zero stops the playback. However, the recommended way to stop playback is for your app to call the stop or pause methods.

When you call the stop method on Android and then call play, there may be a noticeable lag before the file starts playing again. The delay is caused by Android preparing the media again and is therefore specific to that platform only.

Platform Availability

  • Android
  • iOS

Releases the memory and resources held by the media object.

Syntax

releaseMedia();

Example

var theFile = new kony.io.File("MyAudioFile.mp3");
var mediaObj = kony.media.createFromFile(theFile);
mediaObj.releaseMedia();
// If your app tries to use the mediaObj object again, it will get an error!

Input Parameters

None

Return Values

None

Remarks

Your app can call this function to save memory, especially on devices where memory is in short supply. After your app invokes this function, the media object is no longer in memory and attempts to continue to use it by calling its member functions result in errors. Your app must

Sets the current playback position to a specific spot in the media file.

Syntax

seek(position);

Input Parameters

Parameter Description
position An integer number of seconds within the timeline of the media object where playback begins.
 

Example


var theFile = new kony.io.File("MyAudioFile.mp3");
var mediaObj = kony.media.createFromFile(theFile);
mediaObj.seek(5); // Moves playback to 5 seconds from the start of the file.

Return Values

None

Remarks

This method moves the current playback position to a point that is a specified number of seconds from the beginning of the media. The number of seconds is specified as an integer in the position parameter.

Platform Availability

  • Android
  • iOS

Associates callback functions with the media object.

Syntax

setCallbacks(
    config);

Input Parameters

config

A JavaScript object that contains key-value pairs specifying functions to call when media object events occur. The keys are as follows.

Key Description
onMediaCompleted A function that is called when the media is finished playing. For more information, see the Remarks section below.
onMediaFailed A function that is called if the media cannot be played. For more information, see the Remarks section below.
onProgressCallBack A function that is called when the media is playing. For more information, see the Remarks section below.

Example

function OnMediaProgress(Position) {
    // Your code goes here.
}

function OnMediaCompleted() {
    alert("Completed playing given song");
}

function OnMediaFailed(errorMessage) {
    alert("Unable to play the given media");
}

function SetCallbacks() {
    var mediaObj = kony.media.createFromFile(fileobj);
    mediaObj.setCallbacks({
        onProgressCallBack: OnMediaProgress,
        onMediaCompleted: OnMediaCompleted,
        onMediaFailed: OnMediaFailed
    });
}

Return Values

None

Remarks

The config parameter of the setCallbacks function contains keys that specify callback functions. The callback functions are as follows.

onMediaCompleted

The onMediaCompleted key in the config parameter of the setCallbacks function enables your app to set a callback function that is invoked when the media is finished being played. The callback function must have the following signature.

onMediaCompleted();

onMediaFailed

The onMediaFailed key in the config parameter of the setCallbacks function enables your app to set a callback function that is invoked when the media cannot be played. The callback function must have the following signature.

onMediaFailed();

onProgressCallBack

The onProgressCallBack key in the config parameter of the setCallbacks function enables your app to set a callback function that is invoked when the media plays. The callback function must have the following signature.

onProgressCallBack(Position);

where Position contains the position of the current playback at the time the callback function is triggered.

Platform Availability

  • Android
  • iOS

Stops the playback of a media file.

Syntax

stop();

Example


var theFile = new kony.io.File("MyAudioFile.mp3");
var mediaObj = kony.media.createFromFile(theFile);
mediaObj.stop();

Input Parameters

None

Return Values

None

Remarks

This method only has an effect if a media file is currently being played.

When you call this method on Android and then call play, there may be a noticeable lag before the file starts playing again. The delay is caused by Android preparing the media again and is therefore specific to that platform only.

Platform Availability

  • Android
  • iOS