Mediaplayer
The MediaPlayer extension is used to playback different types of audio files. It also allows the playback of Ringtones for the respective platform.
Enabling the API
In order to use this API you must include the following extension in your build.yml
extensions: ["mediaplayer"]
JavaScript Usage
Be sure to review the JavaScript API Usage guide for important information about using this API in JavaScript
Ruby Usage
Be sure to review the Ruby API Usage guide for important information about using this API in Ruby
Methods
getAllRingtones(CallBackHandler callback)
Getting all ringtones on the device – result is array of hashes , each HASH contains name, fullname pairs of info about ringtone.
Parameters
- callback : CallBackHandler Mandatory
Async Callback Returning Parameters: ARRAY
-
Object : HASH
- name : STRING
- fullname : STRING
Synchronous Return:
- Void : this method also supports async callbacks - check the Callback tab for callback return parameters.
Method Access:
-
Class Method: This method can only be accessed via the API class object.
- Javascript:
Rho.Mediaplayer.getAllRingtones(CallBackHandler callback) - Ruby:
Rho::Mediaplayer.getAllRingtones(CallBackHandler callback)
- Javascript:
playRingTone(STRING name)
Play a ringtone with the name supplied being used to designate which one. You cannot supply a location for the ringtone. They are built in. To get a full list of all ringtones available on the system use the method getAllRintones.
Parameters
- name : STRING
Name of the ringtone to be played.
Synchronous Return:
- Void
Method Access:
-
Class Method: This method can only be accessed via the API class object.
- Javascript:
Rho.Mediaplayer.playRingTone(STRING name) - Ruby:
Rho::Mediaplayer.playRingTone(STRING name)
- Javascript:
start(STRING filename)
Play a media file using the supplied filename.
Parameters
- filename : STRING
File name of the audio media to be played – absolute filepath. On iOS when you post URL to remote server (except https), then we open a standard browser (another application) for playing it. On iOS we support: mp3, mp4, wav formats. On other platforms the formats supported depend on what support is built into the platform. Typically on WM/CE this will be wav and on Android mp3.
Synchronous Return:
- Void
Method Access:
-
Class Method: This method can only be accessed via the API class object.
- Javascript:
Rho.Mediaplayer.start(STRING filename) - Ruby:
Rho::Mediaplayer.start(STRING filename)
- Javascript:
startvideo(STRING filename)
Playing a video file back.
Parameters
- filename : STRING
File name of the video media to be played – full filepath. On iOS when you post URL to remote server (except https), then we open a standard browser (another application) for playing it. On iOS we support: mov, mp4, 3gp formats. On other platforms the formats supported depend on what support is built into the platform. Typically on WM/CE this will be wmv and on Android mp4.
Synchronous Return:
- Void
Method Access:
-
Class Method: This method can only be accessed via the API class object.
- Javascript:
Rho.Mediaplayer.startvideo(STRING filename) - Ruby:
Rho::Mediaplayer.startvideo(STRING filename)
- Javascript:
stop()
Stop playing the media file. Not applicable on iOS, because on iOS the special UI is opened for playback audio / video – user can stop / close player by UI.
Synchronous Return:
- Void
Method Access:
-
Class Method: This method can only be accessed via the API class object.
- Javascript:
Rho.Mediaplayer.stop() - Ruby:
Rho::Mediaplayer.stop()
- Javascript:
stopRingTone()
Stop the currently playing ringtone.
Synchronous Return:
- Void
Method Access:
-
Class Method: This method can only be accessed via the API class object.
- Javascript:
Rho.Mediaplayer.stopRingTone() - Ruby:
Rho::Mediaplayer.stopRingTone()
- Javascript:
stopvideo()
Stop the playback of a currently playing video file. Not applicable on iOS, because on iOS the special UI is opened for playback audio / video – user can stop / close player by UI.
Synchronous Return:
- Void
Method Access:
-
Class Method: This method can only be accessed via the API class object.
- Javascript:
Rho.Mediaplayer.stopvideo() - Ruby:
Rho::Mediaplayer.stopvideo()
- Javascript:
Examples
function list_ringtones() { // Enumerate ringtones Rho.Mediaplayer.getAllRingtones(list_ringtones_callback); } function list_ringtones_callback(params) { // play the first ringtone var first_ringtone = params[0]["name"]; Rho.Mediaplayer.playRingTone(first_ringtone); }
def list_ringtones # Enumerate ringtones Rho::Mediaplayer.getAllRingtones(url_for(:action => :list_ringtones_callback)) end def list_ringtones_callback # Play the first ringtone first_ringtone = @params[0]["name"] Rho::Mediaplayer.playRingTone(first_ringtone) end
Remarks
Because the MediaPlayer extension uses the operating system’s built-in player for some media types, it may be possible for the user to access operating system features while media is playing.
Because the MediaPlayer extension uses the operating system’s built-in player for some media types, the playback controls available to the user are outside the control of RhoElements. Some players may have no playback controls in which the user will have to wait for the media to finish playing.
On Android devices, HTTPS is supported only on Android versions 4.0 (Ice Cream Sandwich) or newer.
When more flexible file transfer is required than is provided by MediaPlayer itself it is recommended to use the Network API to fetch the media file, and then to play the local file using MediaPlayer. For example, if playing a file from an FTP server, or an HTTP server requiring authentication. This can also be more efficient if the same file is to be played multiple times, especially on Windows Mobile/CE, where there is no streaming support and therefore the file is completely downloaded before being played.