Warning Older Docs! - You are viewing documentation for a previous released version of RhoMobile Suite.

Mediaplayer

Methods 7  
Examples 1
Remarks 4

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)

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)

start(STRING filename)

Play the audio file using the supplied filename. On WM/CE devices, the API supports only wav file format.

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)

startvideo(STRING filename)

Play the media file using the supplied filename. On WM/CE devices, it launches a media player process to play the supplied filename.

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)

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()

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()

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()

Examples

Play the first available ringtone
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

Availbility of Operating System

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.

Playback Controls

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.

Android Support

On Android devices, HTTPS is supported only on Android versions 4.0 (Ice Cream Sandwich) or newer.

Using File Transfer

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. On Windows Mobile/CE devices, HTTPS file transfer is not supported.