Packageqnx.media
Classpublic class MediaPlayer
InheritanceMediaPlayer Inheritance flash.events.EventDispatcher

The MediaPlayer class provides the functionality that enables you to control the playback of audio or video files, streams, and track sets (for example, playlists, SQL queries, etc). The MediaPlayer class does not provide a user-interface component. Instead, use the qnx.ui.media.MediaControl class to provide a front end for the MediaPlayer object.

View the examples

See also

MediaControl
VideoDisplay
MediaPlayerErrorCodes


Public Properties
 PropertyDefined By
  bufferCapacity : int
[read-only] Gets the current buffer size that is used for playback of the current track (in milliseconds).
MediaPlayer
  bufferLevel : int
[read-only] Gets the current buffer level of the current playing track (in milliseconds).
MediaPlayer
  contextName : String
[read-only] Returns the name of the mm-renderer context.
MediaPlayer
  duration : uint
[read-only] Gets the duration of the file that is currently playing in milliseconds.
MediaPlayer
  isIdle : Boolean
[read-only] Checks whether the MediaPlayer is idle, meaning prepare() must still be called.
MediaPlayer
  isPaused : Boolean
[read-only] Checks whether the MediaPlayer is currently paused.
MediaPlayer
  isPlaying : Boolean
[read-only] Checks whether the MediaPlayer is playing.
MediaPlayer
  mediaType : int
[read-only] Returns the type of media that is currently playing.
MediaPlayer
  metadata : Object
[read-only] Returns the metadata that is associated with the current track.
MediaPlayer
  numTracks : uint
[read-only] Returns the number of tracks to play.
MediaPlayer
  position : uint
[read-only] Gets the current playback position of the current track (in milliseconds).
MediaPlayer
  repeat : String
Gets or sets the player repeat mode.
MediaPlayer
  speed : uint
Gets or sets the play speed, in units of 1/1000 of normal speed.
MediaPlayer
  trackIndex : uint
[read-only] Gets the track index of the media playing in the current playlist.
MediaPlayer
  url : String
Gets or sets the URL for playback (file-path, http/rtsp URL, etc).
MediaPlayer
  videoDisplay : VideoDisplay
Gets or sets the VideoDisplay object to use for displaying the video portion of the media.
MediaPlayer
Public Methods
 MethodDefined By
  
MediaPlayer(url:String = null, display:VideoDisplay = null)
Creates a MediaPlayer object, given a URL, with a VideoDisplay.
MediaPlayer
  
dispose():void
Releases resources associated with this MediaPlayer object.
MediaPlayer
  
Returns the current error code.
MediaPlayer
  
getPlayQueueMetadata(offset:int):Object
Gets the metadata of a track in the play queue, given the offset of the track.
MediaPlayer
  
hasError():Boolean
Returns whether the MediaPlayer has a error code.
MediaPlayer
  
pause():void
Pauses playback.
MediaPlayer
  
play():void
Starts or resumes playback.
MediaPlayer
  
prepare():void
Prepares the player for playback.
MediaPlayer
  
reset():void
Resets the MediaPlayer to its uninitialized state.
MediaPlayer
  
seek(position:uint, offset:int = -1):void
Seeks to a given time position and/or track offset.
MediaPlayer
  
stop():void
Stops playback after playback has been stopped or paused.
MediaPlayer
Events
 Event Summary Defined By
   Dispatched when buffer levels change.MediaPlayer
  Dispatched when an error has occurred during an asynchronous operation.MediaPlayer
   Dispatched to communicate some information and/or a warning about the media or its playback.MediaPlayer
   Dispatched when the media file is ready for playback.MediaPlayer
   Dispatched when the MediaPlayer instance has been reset.MediaPlayer
Property Detail
bufferCapacityproperty
bufferCapacity:int  [read-only]

Gets the current buffer size that is used for playback of the current track (in milliseconds).


Implementation
    public function get bufferCapacity():int
bufferLevelproperty 
bufferLevel:int  [read-only]

Gets the current buffer level of the current playing track (in milliseconds).


Implementation
    public function get bufferLevel():int
contextNameproperty 
contextName:String  [read-only]

Returns the name of the mm-renderer context.


Implementation
    public function get contextName():String
durationproperty 
duration:uint  [read-only]

Gets the duration of the file that is currently playing in milliseconds.

In the following example, the duration property is used in an event listener function to set the duration of the current media:

            private function infoChange(event:MediaPlayerEvent):void {            
        
            if (event.what.duration) {
                _myMediaControl.setProperty(MediaControlProperty.DURATION, _myPlayer.duration);
            }
         


Implementation
    public function get duration():uint
isIdleproperty 
isIdle:Boolean  [read-only]

Checks whether the MediaPlayer is idle, meaning prepare() must still be called.


Implementation
    public function get isIdle():Boolean
isPausedproperty 
isPaused:Boolean  [read-only]

Checks whether the MediaPlayer is currently paused.


Implementation
    public function get isPaused():Boolean
isPlayingproperty 
isPlaying:Boolean  [read-only]

Checks whether the MediaPlayer is playing.


Implementation
    public function get isPlaying():Boolean
mediaTypeproperty 
mediaType:int  [read-only]

Returns the type of media that is currently playing.


Implementation
    public function get mediaType():int

See also

metadataproperty 
metadata:Object  [read-only]

Returns the metadata that is associated with the current track.


Implementation
    public function get metadata():Object

See also

numTracksproperty 
numTracks:uint  [read-only]

Returns the number of tracks to play.


Implementation
    public function get numTracks():uint
positionproperty 
position:uint  [read-only]

Gets the current playback position of the current track (in milliseconds).

In the following example, the position property is used in an event listener function to set the position of the seek bar:

            private function infoChange(event:MediaPlayerEvent):void {
            
            if (event.what.position) {
                _myMediaControl.setProperty(MediaControlProperty.POSITION, _myPlayer.position);
            }
         


Implementation
    public function get position():uint

See also

repeatproperty 
repeat:String

Gets or sets the player repeat mode.

Supported modes are:


Implementation
    public function get repeat():String
    public function set repeat(value:String):void

See also

speedproperty 
speed:uint

Gets or sets the play speed, in units of 1/1000 of normal speed.

For example, speed == 0 is paused, speed == 1000 indicates normal playback speed.


Implementation
    public function get speed():uint
    public function set speed(value:uint):void
trackIndexproperty 
trackIndex:uint  [read-only]

Gets the track index of the media playing in the current playlist.


Implementation
    public function get trackIndex():uint
urlproperty 
url:String

Gets or sets the URL for playback (file-path, http/rtsp URL, etc).

In the following listing, an absolute URL is passed into the url method. The URL is a path to a video file that is included on the file system. Since the file is a movie, a VideoDisplay instance is attached to the MediaPlayer object using the videoDisplay method.

         _myPlayer = new MediaPlayer();
         _myPlayer.addEventListener(MediaPlayerEvent.INFO_CHANGE, infoChange);            
         _myPlayer.url = "/accounts/1000/shared/videos/Vancouver City.mp4"            
         _myPlayer.videoDisplay = _myVD;
         


Implementation
    public function get url():String
    public function set url(value:String):void
videoDisplayproperty 
videoDisplay:VideoDisplay

Gets or sets the VideoDisplay object to use for displaying the video portion of the media.

This call is optional. If you do not call this method when playing back a video, only the audio track will be played.


Implementation
    public function get videoDisplay():VideoDisplay
    public function set videoDisplay(value:VideoDisplay):void

See also

Constructor Detail
MediaPlayer()Constructor
public function MediaPlayer(url:String = null, display:VideoDisplay = null)

Creates a MediaPlayer object, given a URL, with a VideoDisplay. The url and display parameters are set to null by default.

When you are done with the MediaPlayer instance, call the dispose method to free the memory resources.

Parameters
url:String (default = null) — The URL to use for playback [optional].
 
display:VideoDisplay (default = null) — The VideoDisplay instance to use for video playback [optional].

See also

Method Detail
dispose()method
public function dispose():void

Releases resources associated with this MediaPlayer object.

It is considered good practice to call this method when you're done using the MediaPlayer.

getErrorCode()method 
public function getErrorCode():int

Returns the current error code. If no error code is present an Error is thrown.

Returns
int — Return int indicating the error code or throws an error if no error exists,

Throws
Error — Thrown if no error exits, calling only if hasError() returns true will prevent the exception from being thrown.

See also

getPlayQueueMetadata()method 
public function getPlayQueueMetadata(offset:int):Object

Gets the metadata of a track in the play queue, given the offset of the track.

Parameters

offset:int — The offset of the track in the queue.

Returns
Object — A MediaPlayerMetadata object.

See also

hasError()method 
public function hasError():Boolean

Returns whether the MediaPlayer has a error code.

Returns
Boolean — Returns a Boolean indicating whether or not the player has an error code.

See also

pause()method 
public function pause():void

Pauses playback.

play()method 
public function play():void

Starts or resumes playback.

If playback had previously been paused, playback will continue from where it was paused. If playback had been stopped, or never previously started, playback will start at the beginning.

In the following listing, the play() and stop() methods are called in an event listener function that listens for MediaControlEvents. The play() and stop() methods are called when the user taps the play and stop button.

        private function mediaControlStateChange(mediaControlEvent:MediaControlEvent):void
        {
            var state:String = _myMediaControl.getState();
                
            switch( state )
            {
                case MediaControlState.PLAY:
                    if (!_myPlayer.isPlaying) 
                    {
                        _myPlayer.play();
                    } 
                    else 
                    {
                        _myPlayer.speed = 1000;
                    }
                    break;
                case MediaControlState.PAUSE:
                    _myPlayer.speed = 0;
                    break;
                case MediaControlState.STOP:
                    _myPlayer.stop();
                    break;
                case MediaControlState.SEEK_START:                    
                    break;
                case MediaControlState.SEEK_END:                    
                    break;
                default:
                    break;
            }
        }
         


Throws
Error — Thrown if MediaPlayer is in a valid state to start plaback.
prepare()method 
public function prepare():void

Prepares the player for playback.

After setting the URL and/or the VideoDisplay, you can call prepare() to start the video subsystem initialization. Once the operation has completed, the MediaPlayerEvent.PREPARE_COMPLETE event is displatched.


Throws
Error — Thrown if MediaPlayer is in a valid state to prepare playback.

See also

reset()method 
public function reset():void

Resets the MediaPlayer to its uninitialized state.

If the player is idle, calling this will have no effect. After calling this method, you must initialize the MediaPlayer again by setting the URL and by calling prepare once the MediaPlayerEvent.RESET_COMPLETE event has been received.

See also

seek()method 
public function seek(position:uint, offset:int = -1):void

Seeks to a given time position and/or track offset.

In the following listing, the seek method is called in an event listener function using the MediaControlProperty.POSITION property. When the user drags the seek bar thumb along the track, the media player seeks to the position within the current track:

        private function mediaControlPropChange(event:MediaControlEvent):void {
            
            switch (event.property) {
                
                case MediaControlProperty.POSITION:
                {
                    _myPlayer.seek(uint( _myMediaControl.getProperty(MediaControlProperty.POSITION)));
                }
                    break;
                case MediaControlProperty.DURATION:
                    break;
                case MediaControlProperty.FULLSCREEN:
                    break;
                case MediaControlProperty.VOLUME:
                    break;
                default:
                    break;
            }
        }
         

Parameters

position:uint — The offset (in milliseconds) from the start of the track for which to seek to.
 
offset:int (default = -1) — The track to seek. If not specified, the current track is used.

stop()method 
public function stop():void

Stops playback after playback has been stopped or paused.

In the following listing, the play() and stop() methods are called in an event listener function that listens for MediaControlEvents. The play() and stop() methods are called when the user taps the play and stop button.

        private function mediaControlStateChange(mediaControlEvent:MediaControlEvent):void
        {
            var state:String = _myMediaControl.getState();
                
            switch( state )
            {
                case MediaControlState.PLAY:
                    if (!_myPlayer.isPlaying) 
                    {
                        _myPlayer.play();
                    } 
                    else 
                    {
                        _myPlayer.speed = 1000;
                    }
                    break;
                case MediaControlState.PAUSE:
                    _myPlayer.speed = 0;
                    break;
                case MediaControlState.STOP:
                    _myPlayer.stop();
                    break;
                case MediaControlState.SEEK_START:                    
                    break;
                case MediaControlState.SEEK_END:                    
                    break;
                default:
                    break;
            }
        }
         

Event Detail
bufferChange Event
Event Object Type: qnx.events.MediaPlayerEvent
MediaPlayerEvent.type property = qnx.events.MediaPlayerEvent.BUFFER_CHANGE

Dispatched when buffer levels change.
error Event  
Event Object Type: flash.events.ErrorEvent
ErrorEvent.type property = flash.error.ErrorEvent.ERROR

Dispatched when an error has occurred during an asynchronous operation.

infoChange Event  
Event Object Type: qnx.events.MediaPlayerEvent
MediaPlayerEvent.type property = qnx.events.MediaPlayerEvent.INFO_CHANGE

Dispatched to communicate some information and/or a warning about the media or its playback.
prepareComplete Event  
Event Object Type: qnx.events.MediaPlayerEvent
MediaPlayerEvent.type property = qnx.events.MediaPlayerEvent.PREPARE_COMPLETE

Dispatched when the media file is ready for playback. This event is dispatched after a call to prepare() or play().
resetComplete Event  
Event Object Type: qnx.events.MediaPlayerEvent
MediaPlayerEvent.type property = qnx.events.MediaPlayerEvent.RESET_COMPLETE

Dispatched when the MediaPlayer instance has been reset. This event indicates that the player is ready to prepare or play a new URL. The RESET_COMPLETE event is dispatched after a call to reset().
Examples

The following sample application is included to describe the interaction between the MediaControl class and the MediaPlayer class. The application launches a movie. The MediaControl class provides the basic UI, while the MediaPlayer class provides the rendering. In the example below, a URL to a local movie file is passed into the MediaPlayer instance. The MediaPlayer and MediaControl communicate state and property changes using events.

This sample assumes that the media file permissions are set properly, and that the media file is executable.

In order to run this sample application, you must set the access_shared permission capability for your application. See the BlackBerry Tablet OS Developer's Guide for more information.

package
{
    import flash.display.Sprite;
    import flash.filesystem.File;
    
    import qnx.events.MediaPlayerEvent;
    import qnx.media.MediaPlayer;
    import qnx.media.VideoDisplay;
    import qnx.ui.events.MediaControlEvent;
    import qnx.ui.media.
    
    [SWF(width='1024', height='600', backgroundColor='#FFFFFF', frameRate='30')]
    public class MediaPlayerSample extends Sprite
    {
        private var _myPlayer:MediaPlayer;
        private var _myVD:VideoDisplay;
        private var _myMediaControl:MediaControl;
        
        public function MediaPlayerSample()
        {
            initializeUI();
            initializePlayer();            
        }
        
        private function initializePlayer():void
        {
            
            _myVD = new VideoDisplay;
            _myVD.setPosition(1024/2 - 800/2, 600/2 - 480/2);
            _myVD.setSize(800, 480);
            _myVD.backgroundColor = 0x000000;
            addChild(_myVD);
            
            _myPlayer = new MediaPlayer();
            _myPlayer.addEventListener(MediaPlayerEvent.INFO_CHANGE, infoChange);            
            var file:File = File.userDirectory.resolvePath("shared/videos/PlayBook HiDef Demo.mp4");
            _myPlayer.url = file.nativePath;            
            _myPlayer.videoDisplay = _myVD;
                        
        }
        
        private function initializeUI():void
        {
            
            _myMediaControl = new MediaControl();
            _myMediaControl.width = 900;
            _myMediaControl.x = Math.round((stage.stageWidth - _myMediaControl.width) / 2);
            _myMediaControl.y = stage.stageHeight - _myMediaControl.height;
            
            _myMediaControl.setOption( MediaControlOption.VOLUME, true );
            _myMediaControl.setOption( MediaControlOption.PLAY_PAUSE, true );
            _myMediaControl.setOption( MediaControlOption.NEXT, true );
            _myMediaControl.setOption( MediaControlOption.PREVIOUS, true );
            _myMediaControl.setOption( MediaControlOption.STOP, true );
            _myMediaControl.setOption( MediaControlOption.SEEKBAR, true );
            _myMediaControl.setOption( MediaControlOption.DURATION, true );
            _myMediaControl.setOption( MediaControlOption.POSITION, true );
            _myMediaControl.setOption( MediaControlOption.BACKGROUND, true);
            _myMediaControl.setProperty( MediaControlProperty.VOLUME, 80 );
            
            _myMediaControl.addEventListener( MediaControlEvent.STATE_CHANGE, mediaControlStateChange );
            _myMediaControl.addEventListener( MediaControlEvent.PROPERTY_CHANGE, mediaControlPropChange );
            
            addChild(_myMediaControl);            
        
        }
        
        private function infoChange(event:MediaPlayerEvent):void {
            
            if (event.what.position) {
                _myMediaControl.setProperty(MediaControlProperty.POSITION, _myPlayer.position);
            }
            if (event.what.duration) {
                _myMediaControl.setProperty(MediaControlProperty.DURATION, _myPlayer.duration);
            }
            if (event.what.state) {
                _myMediaControl.setState(_myPlayer.isPlaying ? MediaControlState.PLAY : MediaControlState.PAUSE);
            }        
            
        }
        
        private function mediaControlStateChange(mediaControlEvent:MediaControlEvent):void
        {
            var state:String = _myMediaControl.getState();
                
            switch( state )
            {
                case MediaControlState.PLAY:
                    if (!_myPlayer.isPlaying) 
                    {
                        _myPlayer.play();
                    } 
                    else 
                    {
                        _myPlayer.speed = 1000;
                    }
                    break;
                case MediaControlState.PAUSE:
                    _myPlayer.pause();
                    break;
                case MediaControlState.STOP:
                    _myPlayer.stop();
                    break;
                case MediaControlState.SEEK_START:
                    _myPlayer.pause();
                    break;
                case MediaControlState.SEEK_END:
                    _myPlayer.play();
                    break;
                default:
                    break;
            }
        }
                
        private function mediaControlPropChange(event:MediaControlEvent):void {
            
            switch (event.property) {
                
                case MediaControlProperty.POSITION:
                {
                    _myPlayer.seek(uint( _myMediaControl.getProperty(MediaControlProperty.POSITION)));
                }
                    break;
                case MediaControlProperty.DURATION:
                    break;
                case MediaControlProperty.FULLSCREEN:
                    break;
                case MediaControlProperty.VOLUME:
                    break;
                default:
                    break;
            }
        }
        
    }
    
    
}