qnx.media.MediaPlayer

MediaPlayer

Properties | Methods | Events | Examples


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.

Class information:
PlayBook Tablet OS Version:   1.0.6

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
  isBuffering : Boolean
[read-only] Checks whether the MediaPlayer is buffering content.
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 : IVideoDisplay
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:IVideoDisplay = 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
  
setParameters(parameters:Object):void
Sets mm-renderer context parameters.
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

bufferCapacity


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

bufferLevel


bufferLevel:int  [read-only]

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


Implementation

public function get bufferLevel():int

contextName


contextName:String  [read-only]

Returns the name of the mm-renderer context.


Implementation

public function get contextName():String

duration


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

isBuffering


isBuffering:Boolean  [read-only]

Checks whether the MediaPlayer is buffering content.


Implementation

public function get isBuffering():Boolean

isIdle


isIdle:Boolean  [read-only]

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


Implementation

public function get isIdle():Boolean

isPaused


isPaused:Boolean  [read-only]

Checks whether the MediaPlayer is currently paused.


Implementation

public function get isPaused():Boolean

isPlaying


isPlaying:Boolean  [read-only]

Checks whether the MediaPlayer is playing.


Implementation

public function get isPlaying():Boolean

mediaType


mediaType:int  [read-only]

Returns the type of media that is currently playing.


Implementation

public function get mediaType():int

See also

MediaPlayerMediaType

metadata


metadata:Object  [read-only]

Returns the metadata that is associated with the current track.


Implementation

public function get metadata():Object

See also

MediaPlayerMetadata

numTracks


numTracks:uint  [read-only]

Returns the number of tracks to play.


Implementation

public function get numTracks():uint

position


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

repeat


repeat:String

Gets or sets the player repeat mode.

Supported modes are:

  • MediaPlayerRepeat.ALL
  • MediaPlayerRepeat.NONE
  • MediaPlayerRepeat.TRACK


Implementation

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

See also

MediaPlayerRepeat

speed


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

trackIndex


trackIndex:uint  [read-only]

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


Implementation

public function get trackIndex():uint

url


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

videoDisplay


videoDisplay:IVideoDisplay

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():IVideoDisplay
public function set videoDisplay(value:IVideoDisplay):void

See also

VideoDisplay

Constructor Detail

MediaPlayer()


public function MediaPlayer(url:String = null, display:IVideoDisplay = 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:IVideoDisplay (default = null) — The VideoDisplay instance to use for video playback [optional].

See also

dispose()
VideoDisplay

Method Detail

dispose()


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


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

MediaPlayerErrorCodes

getPlayQueueMetadata()


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

MediaPlayerMetadata

hasError()


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

getErrorCode()

pause()


public function pause():void

Pauses playback.

play()


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


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

MediaPlayerEvent

reset()


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

prepare()

seek()


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.

setParameters()


public function setParameters(parameters:Object):void

Sets mm-renderer context parameters.

Parameters

parameters:Object

stop()


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 Object Type: qnx.events.MediaPlayerEvent
MediaPlayerEvent.type property = qnx.events.MediaPlayerEvent.BUFFER_CHANGE

Dispatched when buffer levels change.

error


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 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 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 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;
            _myVD.allowOverlay=false;
            addChild(_myVD);
            
            _myPlayer = new MediaPlayer();
            _myPlayer.addEventListener(MediaPlayerEvent.INFO_CHANGE, infoChange);        
            varfile:File = File.userDirectory.resolvePath("shared/videos/yourvideofile.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;
            }
        }
        
    }
    
    
}