Inheritance diagram for Osp::Media::Player:

Since:: 1.0

The Player class provides methods to play audio and video, including:

Playing the audio or video content stored in the local storage (internal and external memory).
Playing the audio or video content stream from the content server over RTSP or HTTP.
Operating general controls for the audio or video content, such as play, pause, resume, and stop.
Moving the audio or video content on the basis of time.
Controlling the volume of the audio or video content.
Looping the audio or video content.
Getting the duration of an audio or the video content.
Playing back multiple audio streams.

The maximum count of the Player instance is 10.

For more information on the class features, see Playing Audio and Playing Video.

The following example demonstrates how to use the Player class to play an audio or video file.

 #include <FBase.h>
 #include <FMedia.h>
 #include <FGraphics.h>
 #include <FUi.h>
 #include <FApp.h>

 using namespace Osp::Media;
 using namespace Osp::App;
 using namespace Osp::Graphics; 

 class MyPlayerListener
    : public IPlayerEventListener
 {
    public:
    MyPlayerListener() {
    }
    void OnPlayerOpened(result r);
    void OnPlayerEndOfClip(void);
    void OnPlayerBuffering(int percent);
    void OnPlayerErrorOccurred(PlayerErrorReason r );
    void OnPlayerInterrupted();
    void OnPlayerReleased();
    void OnPlayerSeekCompleted(result r);
 };
 
 static  Player* __pPlayer = null;
 static MyPlayerListener* __pListener = null;
 String path0("SampleFile0.aac");
 String path1("SampleFile1.mp4");
 
 // The player's listener should be implemented to control asynchronously.
 void MyPlayerListener::OnPlayerOpened(result r)
 {
 // This listener is used when OpenXXX() is set to work asynchronously.
    // Insert your code to operate after the resource is opened.
    result rt = E_SUCCESS;
    rt = __pPlayer->Play();
 
    if (IsFailed(rt))
    {
        // Need to handle the exception.
    }
 }
 
 
 void MyPlayerListener::OnPlayerEndOfClip(void)
 {
    // Insert your code to operate after the player reaches end of clip.
    result r = E_SUCCESS;
    r = __pPlayer->Close();
    if (IsFailed(r))
    {
        // Handle the exception.
    }
 }
 
 
 void MyPlayerListener::OnPlayerBuffering(int percent)
 {
    // Insert your code to operate while the buffering for a remote resource is going on.
 }
 
 void MyPlayerListener::OnPlayerErrorOccurred(PlayerErrorReason r )
 {
    // Insert your code to operate after any error occurred.
 }
 
 void MyPlayerListener::OnPlayerInterrupted()
 {
    // Insert your code here.
 }
 
 void MyPlayerListener::OnPlayerReleased()
 {
    // Insert your code here.
 }
 
 void MyPlayerListener::OnPlayerSeekCompleted(result r)
 {
    // Insert your code here.
 }
 
 result TestAudioPlaying(void)
 {
    result r = E_SUCCESS;
    if(!__pPlayer){
 
        __pPlayer = new Player();
        __pListener = new MyPlayerListener;
 
        // Create audio player.
        r = __pPlayer->Construct(*__pListener, 0);
        if (IsFailed(r)) goto CATCH;
    }
 
    // Open file asynchronously.
    r = __pPlayer->OpenFile(path0, true);
    if (IsFailed(r)) goto CATCH;
 
    r = __pPlayer->SetLooping(true);
    if (IsFailed(r)) goto CATCH;
 
    r = __pPlayer->SetVolume(80);
    if (IsFailed(r)) goto CATCH;
 
 CATCH:
    delete __pPlayer;
    delete __pListener;
 
    return r;
 }
 
 result TestVideoPlaying(void)
 {
    result r = E_SUCCESS;
    Osp::Ui::Controls::OverlayRegion *pRegion = null;
    Osp::Ui::Controls::Form* pPlayerForm = null;
    Osp::Graphics::BufferInfo bufferInfo;
 
    pPlayerForm = Application::GetInstance()->GetAppFrame()->GetFrame()->GetCurrentForm();
    pRegion = pPlayerForm->GetOverlayRegionN(Rectangle(0,0,320,240),OVERLAY_REGION_TYPE_NORMAL);
 
    r = pRegion->GetBackgroundBufferInfo(bufferInfo);
    if (IsFailed(r)) { goto CATCH; }
 
    if(!__pPlayer)
    {
        Player* __pPlayer = new Player();
        __pListener = new MyPlayerListener;
 
        // Create video player.
        r = __pPlayer->Construct(*__pListener, &bufferInfo);
        if (IsFailed(r)) goto CATCH;
    }
 
    // Open file asynchronously.
    r = __pPlayer->OpenFile(path1, true);
    if (IsFailed(r)) goto CATCH;
 
    r = __pPlayer->SetVolume(80);
    if (IsFailed(r)) goto CATCH;
 
 CATCH:
    delete __pPlayer;
    delete __pListener;
 
    return r;
 }

The following example demonstrates how to use the Player class to get a video frame through the video event listener.

 #include <FBase.h>
 #include <FMedia.h>
 #include <FGraphics.h>
 
 
 class MyVideoFrame :
        IPlayerEventListener,
        IPlayerVideoEventListener
 {
 public:
    MyVideoFrame(){};
    ~MyVideoFrame(){};
 
 public:
    void OnPlayerOpened(result r){};
    void OnPlayerEndOfClip(void){};
    void OnPlayerBuffering(int percent){};
    void OnPlayerErrorOccurred(PlayerErrorReason r ){};
    void OnPlayerInterrupted(){};
    void OnPlayerReleased(){};
    void OnPlayerSeekCompleted(result r){};
    void OnVideoFrameDecoded (Osp::Media::Player &src, Osp::Graphics::BitmapPixelFormat bitmapPixelFormat, const Osp::Graphics::Dimension &dim, const byte *pBuffer, int sizeOfBuffer, result r);
 
 public:
    result TestGetVideoFrame(void);
 
 private:
    Player* pPlayer;
 };
 
 void
 MyVideoFrame::OnVideoFrameDecoded (Osp::Media::Player &src, Osp::Graphics::BitmapPixelFormat bitmapPixelFormat, const Osp::Graphics::Dimension &dim, const byte *pBuffer, int sizeOfBuffer, result r)
 {
    ByteBuffer buf;
    Bitmap bitmap;
 
    if(r == E_SUCCESS)
    {
        buf.Construct(sizeOfBuffer);
        buf.SetArray(pBuffer, 0, sizeOfBuffer);
        buf.Flip();
        // Get the bitmap using the video frame.
        bitmap.Construct(buf, dim, bitmapPixelFormat);
    }
 }
 
 result MyVideoFrame::TestGetVideoFrame(void)
 {
    result r = E_SUCCESS;
 
    pPlayer = new Player;
    r = pPlayer->Construct(*this, *this);
    if(IsFailed(r))
    {
        goto CATCH;
    }
 
    r = pPlayer->OpenFile(String("SampleFile1.mp4"));
    if(IsFailed(r))
    {
        goto CATCH;
    }
 
    // Request get the first video frame.
     pPlayer->CaptureVideo();
    return r;
 
 CATCH:
    delete pPlayer;
    return r;
 }

List of all members.

Public Member Functions
result	CaptureVideo (void)
result	Close (void)
result	Construct (const IPlayerEventListener &listener, const IPlayerVideoEventListener &videoListener)
result	Construct (const IPlayerEventListener &listener, const Osp::Graphics::BufferInfo *pBufferInfo=null)
MediaStreamInfo *	GetCurrentMediaStreamInfoN (void)
long	GetDuration (void) const
long	GetPosition (void) const
PlayerState	GetState (void) const
int	GetVolume (void) const
bool	IsLooping (void)
bool	IsMuted (void) const
result	OpenBuffer (const Osp::Base::ByteBuffer &mediaBuffer, bool isAsync=false)
result	OpenFile (const Osp::Base::String &mediaLocalPath, bool isAsync=false)
result	OpenUrl (const Osp::Base::Utility::Uri &mediaUri, bool isAsync=false)
result	Pause (void)
result	Play (void)
	Player (void)
result	SeekTo (long msTime)
result	SetLooping (bool looping)
result	SetMute (bool mute)
result	SetRenderingBuffer (const Osp::Graphics::BufferInfo &bufferInfo)
result	SetVolume (int volume)
result	Stop (void)
virtual	~Player (void)

Constructor & Destructor Documentation

Osp::Media::Player::Player ( void )

This is the default constructor for this class.

Since:: 1.0

Remarks:: After creating an instance of this class, the Construct() method must be called explicitly to initialize this instance.

See also:: Construct()

virtual Osp::Media::Player::~Player ( void ) [virtual]

This is the destructor for this class.
This method deallocates the resources. This method should be called in the same thread as the Construct() method.

Since:: 1.0

See also:: Construct()

Member Function Documentation

result Osp::Media::Player::CaptureVideo ( void )

Captures the video frame.
This method delivers one video frame of a video content by using the IPlayVideoEventListener interface only once in the Player instance.
This method works only for the PLAYER_STATE_OPENED state of the Player instance, and the state of the Player instance is changed to PLAYER_STATE_PAUSED from PLAYER_STATE_OPENED after calling this method.

Since:: 2.0

Returns:: An error code

Exceptions:

E_SUCCESS	The method is successful.
E_INVALID_STATE	This method is invalid for the current state of this instance. This method throws E_INVALID_STATE if the Player instance is constructed without IPlayerVideoEventListener.
E_INVALID_OPERATION	This method is invalid for the current media content.
E_SYSTEM	A system error has occurred.

Remarks:: In the Real Time Streaming Protocol (RTSP), this method does not work properly.

See also:: IPlayerVideoEventListener

result Osp::Media::Player::Close ( void )

Closes the audio or video content.
This method works synchronously.

Since:: 1.0

Returns:: An error code

Exceptions:

E_SUCCESS	The method is successful.
E_INVALID_STATE	This method is invalid for the current state of this instance.
E_SYSTEM	A system error has occurred.

See also:: OpenFile(), OpenBuffer(), OpenUrl()

result Osp::Media::Player::Construct	(	const IPlayerEventListener &	listener,
		const Osp::Graphics::BufferInfo *	pBufferInfo = `null`
	)

Initializes this instance of Player.

Since:: 1.0

Returns:: An error code

Parameters:

[in]	listener	An event listener instance
[in]	pBufferInfo	The buffer information to display the video This information is essential to play a video but not required for an audio content.

Exceptions:

E_SUCCESS	The method is successful.
E_INVALID_STATE	This method is invalid for the current state of this instance.
E_SYSTEM	A system error has occurred.
E_RESOURCE_UNAVAILABLE	The player's resources are unavailable.

Remarks:: Multiple instances of Player can be constructed.

result Osp::Media::Player::Construct	(	const IPlayerEventListener &	listener,
		const IPlayerVideoEventListener &	videoListener
	)

Initializes this instance of Player with the video event listener in addition to the player event listener.

Since:: 2.0

Returns:: An error code

Parameters:

[in]	listener	An IPlayerEventListener instance
[in]	videoListener	An IPlayerVideoEventListener instance

Exceptions:

E_SUCCESS	The method is successful.
E_INVALID_STATE	This method is invalid for the current state of this instance.
E_SYSTEM	A system error has occurred.
E_RESOURCE_UNAVAILABLE	The player's resources are unavailable.

Remarks:: This method constructs the Player instance to render the video content into the buffer of the video event listener.

See also:: IPlayerVideoEventListener

MediaStreamInfo* Osp::Media::Player::GetCurrentMediaStreamInfoN ( void )

Gets the current media stream information.

Since:: 2.0

Returns:: A pointer to the MediaStreamInfo instance containing metadata for the current media stream

Exceptions:

E_SUCCESS	The method is successful.
E_INVALID_STATE	This method is invalid for the current state of this instance.
E_INVALID_CONTENT	The content is inappropriate to compose media stream information.
E_SYSTEM	A system error has occurred.

Remarks:: This method returns a stream information of the media, which is currently being played. The specific error code can be accessed using the GetLastResult() method. This method should be called after Play() to get the correct data.

See also:: MediaStreamInfo

long Osp::Media::Player::GetDuration ( void ) const

Gets the total running time of the opened media source.

Since:: 1.0

Compatibility:: This method has compatibility issues with bada API versions prior to 1.2.
For more information, see here.

Returns:: The running time of the media source in milliseconds

Exceptions:

E_SUCCESS	The method is successful.
E_INVALID_STATE	This method is invalid for the current state of this instance.

Remarks:: The specific error code can be accessed using the GetLastResult() method. While playing live streaming, this operation returns 0.

See also:: GetPosition()

long Osp::Media::Player::GetPosition ( void ) const

Gets the time for the current playback position of the audio or video content.
Accuracy of the retrieved time is determined by the subsystem (for example, the time slice of the OS scheduler, time resolution of the audio or video codec, or implementation of the audio or video player). Note that it should not be assumed that this method can reach the exact position mentioned by GetDuration().

Since:: 1.0

Returns:: The current position of the player in milliseconds

Exceptions:

E_SUCCESS	The method is successful.
E_INVALID_STATE	This method is invalid for the current state of this instance.

Remarks:: The specific error code can be accessed using the GetLastResult() method.

See also:: SeekTo()

PlayerState Osp::Media::Player::GetState ( void ) const

Gets the state of an audio or video player.

Since:: 1.0

Returns:: The current state of the player

Exceptions:

E_SUCCESS	The method is successful.
E_INVALID_STATE	This method is invalid for the current state of this instance.

Remarks:: The specific error code can be accessed using the GetLastResult() method.

See also:: Close(), Play(), Stop(), Pause(), PlayerState

int Osp::Media::Player::GetVolume ( void ) const

Gets the current volume of an audio or video player.

Since:: 1.0

Returns:: The current volume level
The range of this return value is 0 to 100.

Exceptions:

E_SUCCESS	The method is successful.
E_INVALID_STATE	This method is invalid for the current state of this instance.

Remarks:: The specific error code can be accessed using the GetLastResult() method.

See also:: SetVolume(), IsMuted(), SetMute()

bool Osp::Media::Player::IsLooping ( void )

Checks whether the audio or video player is in a loop.

Since:: 1.0

Returns:: true if the audio or video player is in a loop,
else false

Exceptions:

E_SUCCESS	The method is successful.
E_INVALID_STATE	This method is invalid for the current state of this instance.

Remarks:: The specific error code can be accessed using the GetLastResult() method.

See also:: SetLooping()

bool Osp::Media::Player::IsMuted ( void ) const

Checks the mute status of an audio or video player.

Since:: 1.0

Returns:: true if the audio or video player is muted,
else false

Exceptions:

E_SUCCESS	The method is successful.
E_INVALID_STATE	This method is invalid for the current state of this instance.

Remarks:: The specific error code can be accessed using the GetLastResult() method.

See also:: GetVolume(), SetVolume(), SetMute()

result Osp::Media::Player::OpenBuffer	(	const Osp::Base::ByteBuffer &	mediaBuffer,
		bool	isAsync = `false`
	)

Opens an audio or video content to play on the memory.
This method works synchronously, but when the second parameter isAsync is set to true, this method works asynchronously. Note that a method that works asynchronously should implement a listener.

Since:: 1.0

Compatibility:: This method has compatibility issues with bada API versions prior to 2.0.
For more information, see here.

Returns:: An error code

Parameters:

[in]	mediaBuffer	A pointer to the media source in the external memory
[in]	isAsync	Set to `true` for asynchronous mode, else `false` for synchronous mode

Exceptions:

E_SUCCESS	The method is successful.
E_INVALID_STATE	This method is invalid for the current state of this instance.
E_SYSTEM	A system error has occurred.
E_OBJ_NOT_FOUND	The specified media buffer cannot be found.
E_UNSUPPORTED_FORMAT	The specified format is not supported.
E_UNSUPPORTED_CODEC	The specified codec is not supported.
E_INVALID_DATA	The specified buffer contains invalid data.
E_OUT_OF_MEMORY	The memory is insufficient.

Remarks:: DRM content cannot be played by this method.

See also:: Close()

result Osp::Media::Player::OpenFile	(	const Osp::Base::String &	mediaLocalPath,
		bool	isAsync = `false`
	)

Opens an audio or video file to be played.
This method works synchronously, but when the second parameter, isAsync is set to true, this method works asynchronously. Note that a method that works asynchronously should implement a listener.

Since:: 1.0

Compatibility:: This method has compatibility issues with bada API versions prior to 2.0.
For more information, see here.

Returns:: An error code

Parameters:

[in]	mediaLocalPath	The local file path of the media source
[in]	isAsync	Set to `true` for the asynchronous mode, else `false` for the synchronous mode

Exceptions:

E_SUCCESS	The method is successful.
E_INVALID_STATE	This method is invalid for the current state of this instance.
E_SYSTEM	A system error has occurred.
E_FILE_NOT_FOUND	The specified file cannot be found or accessed.
E_UNSUPPORTED_FORMAT	The specified format is not supported.
E_UNSUPPORTED_CODEC	The specified codec is not supported.
E_INVALID_DATA	The specified file contains invalid data.
E_OUT_OF_MEMORY	The memory is insufficient.

See also:: Close()

result Osp::Media::Player::OpenUrl	(	const Osp::Base::Utility::Uri &	mediaUri,
		bool	isAsync = `false`
	)

Opens an audio or video streaming content to play through the specified URL.
This method works synchronously, but when the second parameter isAsync is set to true, this method works asynchronously. Note that a method that works asynchronously should implement a listener.

Since:: 1.0

Returns:: An error code

Parameters:

[in]	mediaUri	The URL of the media source
[in]	isAsync	Set to `true` for the asynchronous mode, else `false` for the synchronous mode

Exceptions:

E_SUCCESS	The method is successful.
E_INVALID_STATE	This method is invalid for the current state of this instance.
E_CONNECTION_FAILED	The network connection has failed.
E_UNSUPPORTED_PROTOCOL	The protocol is not supported.
E_UNSUPPORTED_FORMAT	The specified format is not supported.
E_UNSUPPORTED_CODEC	The specified codec is not supported.
E_SYSTEM	A system error has occurred.

Remarks:: This method is not thread-safe when isAsync is false.

See also:: Close()

result Osp::Media::Player::Pause ( void )

Pauses the playback of the audio or video content.
To resume the playback, the Play() method should be called. This method works synchronously.

Since:: 1.0

Returns:: An error code

Exceptions:

E_SUCCESS	The method is successful.
E_INVALID_STATE	This method is invalid for the current state of this instance.
E_SYSTEM	A system error has occurred.

See also:: Play(), Stop()

result Osp::Media::Player::Play ( void )

Starts the playback or resumes the playback of the audio or video content after Pause() is called.
The playback starts from the current position. In case of the PLAYER_STATE_ENDOFCLIP player state, the audio or video content is played again.

Since:: 1.0

Returns:: An error code

Exceptions:

E_SUCCESS	The method is successful.
E_INVALID_STATE	This method is invalid for the current state of this instance.
E_DEVICE_BUSY	The device cannot be approached because of other operations.
E_SYSTEM	A system error has occurred. If playback has been paused, it resumes from the last position. E_SYSTEM is thrown when unsupported format or codec media data are received during streaming. E_SYSTEM is thrown when the unsupport resolution is set for rendering since: 2.0.

Remarks:: When this method is called after the Player instance is created with the Construct() method that accepts the IPlayVideoEventListener interface as a parameter, it delivers every video frame of a video content continuously until the state is changed to PLAYER_STATE_ENDOFCLIP, or the Stop() or Pause() method is called since: 2.0.

See also:: Stop(), Pause(), IPlayerVideoEventListener

result Osp::Media::Player::SeekTo ( long msTime )

Changes the current playback position of the audio or video content to the specified time.
This method works asynchronously.
Note that a method that works asynchronously should implement a listener.
This method only works for the PLAYER_STATE_PLAYING and PLAYER_STATE_PAUSED states of the player.
This method changes the playback position as well as the time value.
In video, it may not change position accurately.

Since:: 1.0

Compatibility:: This method has compatibility issues with different bada API versions prior to 1.2.
For more information, see issues in version 1.2 and 2.0.

Returns:: An error code

Parameters:

[in] msTime The time in milliseconds to move to the current playback position
0 indicates the starting position.

Exceptions:

E_SUCCESS	The method is successful.
E_INVALID_STATE	This method is invalid for the current state of this instance. While playing live streaming, this operation returns E_INVALID_STATE. This method returns E_INVALID_STATE, if this method is called again before IPlayerEventListener::OnPlayerSeekCompleted() is called.
E_OUT_OF_RANGE	The specified time is out of range.
E_INVALID_DATA	The media data is inappropriate for seeking.
E_SYSTEM	A system error has occurred.

Remarks:: For video, this method delivers one video frame on the specified position through the video event. Before calling this method, the Player instance should be created with the Construct() method has a parameter of the IPlayVideoEventListener interface since: 2.0.

See also:: GetPosition(), IPlayerVideoEventListener

result Osp::Media::Player::SetLooping ( bool looping )

Sets an audio or video player to be in a loop.
Set the looping to true to continuously play the audio or video content.

Since:: 1.0

Returns:: An error code

Parameters:

[in] looping Set to true to play the audio or video content in a loop,
else false

Exceptions:

E_SUCCESS	The method is successful.
E_INVALID_STATE	This method is invalid for the current state of this instance.

Remarks:: In streaming, this method throws E_INVALID_STATE for the cost of network.

See also:: IsLooping()

result Osp::Media::Player::SetMute ( bool mute )

Sets the mute status of an audio or video player.

Since:: 1.0

Returns:: An error code

Parameters:

[in] mute Set to true to mute the audio or video player,
else false

Exceptions:

E_SUCCESS	The method is successful.
E_INVALID_STATE	This method is invalid for the current state of this instance.

See also:: GetVolume(), SetVolume(), IsMuted()

result Osp::Media::Player::SetRenderingBuffer ( const Osp::Graphics::BufferInfo & bufferInfo )

Sets the rendering buffer for the video playback.

Since:: 2.0

Returns:: An error code

Parameters:

[in] bufferInfo The buffer information to display the video

Exceptions:

E_SUCCESS	The method is successful.
E_INVALID_STATE	This method is invalid for the current state of this instance.
E_INVALID_ARG	The specified input parameter is invalid.
E_SYSTEM	A system error has occurred. E_SYSTEM is thrown when the unsupport resolution is set for rendering since: 2.0.

Remarks:: This method works for the PLAYER_STATE_OPENED, PLAYER_STATE_ENDOFCLIP, PLAYER_STATE_STOPPED, PLAYER_STATE_PAUSED, and PLAYER_STATE_PLAYING states of the player. This method throws E_INVALID_STATE after the player instance is constructed with IPlayerVideoEventListener.

result Osp::Media::Player::SetVolume ( int volume )

Sets the specified value for the volume of an audio or video player.

Since:: 1.0

Returns:: An error code

Parameters:

[in] volume The new value of volume
The range of this parameter is 0 to 100 and it is proportional to the current media sound volume level in setting.

Exceptions:

E_SUCCESS	The method is successful.
E_OUT_OF_RANGE	The specified volume is out of range.
E_INVALID_STATE	This method is invalid for the current state of this instance.

See also:: GetVolume(), IsMuted(), SetMute()

result Osp::Media::Player::Stop ( void )

Stops the playback of the audio or video content. This method works synchronously.

Since:: 1.0

Returns:: An error code

Exceptions:

E_SUCCESS	The method is successful.
E_INVALID_STATE	This method is invalid for the current state of this instance.
E_SYSTEM	A system error has occurred.

Remarks:: In the Real Time Streaming Protocol (RTSP), this method stops the media stream and requests the termination of the network session.

See also:: Play(), Pause()

The documentation for this class was generated from the following file:

FMediaPlayer.h

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation