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