MultiMedia_Player

MultiMedia_Player

Overview

Defines the Player class and provides functions related to media playback.

Since:

1.0

Version:

1.0

Summary

Files

File Name	Description
player.h	Declares the Player class, which is used to implement player-related operations.

Data Structures

Data Structure Name	Description
OHOS::Media::PlayerCallback	Provides listeners for events and exception notifications that occur during media playback.
OHOS::Media::Player	Provides functions for playing online movies, offline movies, and streams, for example, playing local movies and advanced audio coding (AAC) streams.

Enumerations

Enumeration Name	Description
OHOS::Media::PlayerSeekMode : int32_t { OHOS::Media::PLAYER_SEEK_PREVIOUS_SYNC = 0, OHOS::Media::PLAYER_SEEK_NEXT_SYNC, OHOS::Media::PLAYER_SEEK_CLOSEST_SYNC, OHOS::Media::PLAYER_SEEK_CLOSEST, OHOS::Media::PLAYER_SEEK_FRAME_INDEX }	Enumerates player seek modes. You can move the current playback position of the media to a given time position using the specified mode.
OHOS::Media::PlayerStates : uint32_t { OHOS::Media::PLAYER_STATE_ERROR = 0, OHOS::Media::PLAYER_IDLE = 1 << 0, OHOS::Media::PLAYER_INITIALIZED = 1 << 1, OHOS::Media::PLAYER_PREPARING = 1 << 2, OHOS::Media::PLAYER_PREPARED = 1 << 3, OHOS::Media::PLAYER_STARTED = 1 << 4, OHOS::Media::PLAYER_PAUSED = 1 << 5, OHOS::Media::PLAYER_STOPPED = 1 << 6, OHOS::Media::PLAYER_PLAYBACK_COMPLETE = 1 << 7 }	Enumerates player states.
OHOS::Media::PlayerCallback::PlayerInfoType : int32_t { OHOS::Media::PlayerCallback::PLAYER_INFO_RENDER_START = 0 }

Functions

Function Name	Description
OHOS::Media::PlayerCallback::OnPlaybackComplete ()=0	virtual void Called when the playback is complete.
OHOS::Media::PlayerCallback::OnError (int32_t errorType, int32_t errorCode)=0	virtual void Called when a playback error occurs.
OHOS::Media::PlayerCallback::OnInfo (int type, int extra)=0	virtual void Called when playback information is received.
OHOS::Media::PlayerCallback::OnVideoSizeChanged (int width, int height)=0	virtual void Called when the video image size changes.
OHOS::Media::PlayerCallback::OnRewindToComplete ()=0	virtual void Called when the rewind is complete.
OHOS::Media::Player::SetSource (const Source &source)	int32_t Sets the playback source for the player. The corresponding source can be the file descriptor (FD) of the local file, local file URI, network URI, or media stream.
OHOS::Media::Player::Prepare ()	int32_t Prepares the playback environment and buffers media data.
OHOS::Media::Player::Play ()	int32_t Starts or resumes playback.
OHOS::Media::Player::IsPlaying ()	bool Checks whether the player is playing.
OHOS::Media::Player::Pause ()	int32_t Pauses playback.
OHOS::Media::Player::Stop ()	int32_t Stops playback.
OHOS::Media::Player::Rewind (int64_t mSeconds, int32_t mode)	int32_t Changes the playback position.
OHOS::Media::Player::SetVolume (float leftVolume, float rightVolume)	int32_t Sets the volume of the player.
OHOS::Media::Player::SetVideoSurface (Surface *surface)	int32_t Sets a surface for video playback.
OHOS::Media::Player::EnableSingleLooping (bool loop)	int32_t Sets loop playback.
OHOS::Media::Player::IsSingleLooping ()	bool Checks whether the player is looping.
OHOS::Media::Player::GetCurrentTime (int64_t &time) const	int32_t Obtains the playback position, accurate to millisecond.
OHOS::Media::Player::GetDuration (int64_t &duration) const	int32_t Obtains the total duration of media files, in milliseconds.
OHOS::Media::Player::GetVideoWidth (int32_t &videoWidth)	int32_t Obtains the width of the video.
OHOS::Media::Player::GetVideoHeight (int32_t &videoHeight)	int32_t Obtains the height of the video.
OHOS::Media::Player::Reset ()	int32_t Restores the player to the initial state.
OHOS::Media::Player::Release ()	int32_t Releases player resources.
OHOS::Media::Player::SetPlayerCallback (const std::shared_ptr< PlayerCallback > &cb)	void Registers a listener to receive events and exception notifications from the player.

Details

Enumeration Type Documentation

PlayerInfoType

enum [OHOS::Media::PlayerCallback::PlayerInfoType]($api-api-SmartVision-Devices-MultiMedia_Player.md#ga7dac9dac65cbbea7e411adcf2c314ac5) : int32_t

Enumerator	Description
PLAYER_INFO_RENDER_START	Pushed the first video frame for rendering

PlayerSeekMode

enum [OHOS::Media::PlayerSeekMode]($api-api-SmartVision-Devices-MultiMedia_Player.md#gad1574e5769b3174c2103a2a8b49e20d4) : int32_t

Description:

Enumerates player seek modes. You can move the current playback position of the media to a given time position using the specified mode.

Enumerator	Description
PLAYER_SEEK_PREVIOUS_SYNC	Moves the media position to the latest synchronization frame located before the given time position.
PLAYER_SEEK_NEXT_SYNC	Moves the media position to the latest synchronization frame located after the given time position.
PLAYER_SEEK_CLOSEST_SYNC	Moves the media position to the latest synchronization frame located before or after the given time position.
PLAYER_SEEK_CLOSEST	Moves the media position to the latest frame located before or after the given time position.
PLAYER_SEEK_FRAME_INDEX	Moves the media position to a given frame index.

PlayerStates

enum [OHOS::Media::PlayerStates]($api-api-SmartVision-Devices-MultiMedia_Player.md#ga8b1147e57c4a67f63f193836302da2b7) : uint32_t

Description:

Enumerates player states.

Enumerator	Description
PLAYER_STATE_ERROR	Error
PLAYER_IDLE	Idle
PLAYER_INITIALIZED	Initialized
PLAYER_PREPARING	Preparing
PLAYER_PREPARED	Prepared
PLAYER_STARTED	Playback started
PLAYER_PAUSED	Playback paused
PLAYER_STOPPED	Playback stopped
PLAYER_PLAYBACK_COMPLETE	Playback completed

Function Documentation

EnableSingleLooping()

int32_t OHOS::Media::Player::EnableSingleLooping (bool loop)

Description:

Sets loop playback.

Parameters:

Name	Description
loop	Specifies whether to enable loop playback. The value true means to enable loop playback, and false means to disable loop playback.

Returns:

Returns 0 if the setting is successful; returns -1 otherwise.

GetCurrentTime()

int32_t OHOS::Media::Player::GetCurrentTime (int64_t & time) const

Description:

Obtains the playback position, accurate to millisecond.

Parameters:

Name	Description
time	Indicates the playback position.

Returns:

Returns 0 if the playback position is obtained; returns -1 otherwise.

GetDuration()

int32_t OHOS::Media::Player::GetDuration (int64_t & duration) const

Description:

Obtains the total duration of media files, in milliseconds.

Parameters:

Name	Description
duration	Indicates the total duration of media files.

Returns:

Returns 0 if the total duration is obtained; returns -1 otherwise.

GetVideoHeight()

int32_t OHOS::Media::Player::GetVideoHeight (int32_t & videoHeight)

Description:

Obtains the height of the video.

Parameters:

Name	Description
videoHeight	Indicates the video height.

Returns:

Returns 0 if the video height is obtained; returns -1 otherwise.

GetVideoWidth()

int32_t OHOS::Media::Player::GetVideoWidth (int32_t & videoWidth)

Description:

Obtains the width of the video.

Parameters:

Name	Description
videoWidth	Indicates the video width.

Returns:

Returns 0 if the video width is obtained; returns -1 otherwise.

IsPlaying()

bool OHOS::Media::Player::IsPlaying ()

Description:

Checks whether the player is playing.

Returns:

Returns true if the player is playing; returns false otherwise.

IsSingleLooping()

bool OHOS::Media::Player::IsSingleLooping ()

Description:

Checks whether the player is looping.

Returns:

Returns true if the player is looping; returns false otherwise.

OnError()

virtual void OHOS::Media::PlayerCallback::OnError (int32_t errorType, int32_t errorCode )

Description:

Called when a playback error occurs.

Parameters:

Name	Description
errorType	Indicates the error type. For details, see PlayerErrorType.
errorCode	Indicates the error code.

OnInfo()

virtual void OHOS::Media::PlayerCallback::OnInfo (int type, int extra )

Description:

Called when playback information is received.

Parameters:

Name	Description
type	Indicates the information type. For details, see PlayerInfoType.
extra	Indicates the information code.

OnPlaybackComplete()

virtual void OHOS::Media::PlayerCallback::OnPlaybackComplete ()

Description:

Called when the playback is complete.

OnRewindToComplete()

virtual void OHOS::Media::PlayerCallback::OnRewindToComplete ()

Description:

Called when the rewind is complete.

OnVideoSizeChanged()

virtual void OHOS::Media::PlayerCallback::OnVideoSizeChanged (int width, int height )

Description:

Called when the video image size changes.

Parameters:

Name	Description
width	Indicates the video width.
height	Indicates the video height.

Pause()

int32_t OHOS::Media::Player::Pause ()

Description:

Pauses playback.

Returns:

Returns 0 if the playback is paused; returns -1 otherwise.

Play()

int32_t OHOS::Media::Player::Play ()

Description:

Starts or resumes playback.

This function must be called after Prepare. If the player state is Prepared, this function is called to start playback. If the player state is Playback paused, this function is called to resume playback. If the media is playing in an abnormal speed, this function is called to restore the playback speed to normal.

Returns:

Returns 0 if the playback starts or resumes; returns -1 otherwise.

Prepare()

int32_t OHOS::Media::Player::Prepare ()

Description:

Prepares the playback environment and buffers media data.

This function must be called after SetSource.

Returns:

Returns 0 if the playback environment is prepared and media data is buffered; returns -1 otherwise.

Release()

int32_t OHOS::Media::Player::Release ()

Description:

Releases player resources.

Returns:

Returns 0 if player resources are released; returns -1 otherwise.

Reset()

int32_t OHOS::Media::Player::Reset ()

Description:

Restores the player to the initial state.

Returns:

Returns 0 if the player is restored; returns -1 otherwise.

Rewind()

int32_t OHOS::Media::Player::Rewind (int64_t mSeconds, int32_t mode )

Description:

Changes the playback position.

This function can be used during playback or pause.

Parameters:

Name	Description
mSeconds	Indicates the target playback position, accurate to second.
mode	Indicates the player seek mode. For details, see PlayerSeekMode.

Returns:

Returns 0 if the playback position is changed; returns -1 otherwise.

SetPlayerCallback()

void OHOS::Media::Player::SetPlayerCallback (const std::shared_ptr< [PlayerCallback]($api-api-SmartVision-Devices-OHOS-Media-PlayerCallback.md) > & cb)

Description:

Registers a listener to receive events and exception notifications from the player.

Parameters:

Name	Description
cb	Indicates the listener to register. For details, see PlayerCallback.

SetSource()

int32_t OHOS::Media::Player::SetSource (const [Source]($api-api-SmartVision-Devices-OHOS-Media-Source.md) & source)

Description:

Sets the playback source for the player. The corresponding source can be the file descriptor (FD) of the local file, local file URI, network URI, or media stream.

Parameters:

Name	Description
source	Indicates the playback source. Currently, only local file URIs and media streams are supported. For details, see Source.

Returns:

Returns 0 if the setting is successful; returns -1 otherwise.

SetVideoSurface()

int32_t OHOS::Media::Player::SetVideoSurface ([Surface]($api-api-SmartVision-Devices-OHOS-Surface.md) * surface)

Description:

Sets a surface for video playback.

Parameters:

Name	Description
surface	Indicates the surface to set. For details, see Surface.

Returns:

Returns 0 if the setting is successful; returns -1 otherwise.

SetVolume()

int32_t OHOS::Media::Player::SetVolume (float leftVolume, float rightVolume )

Description:

Sets the volume of the player.

This function can be used during playback or pause. The value 0 indicates no sound, and 100 indicates the original volume. If no audio device is started or no audio stream exists, the value -1 is returned.

Parameters:

Name	Description
leftVolume	Indicates the target volume of the left audio channel to set, ranging from 0 to 300.
rightVolume	Indicates the target volume of the right audio channel to set, ranging from 0 to 300.

Returns:

Returns 0 if the setting is successful; returns -1 otherwise.

Stop()

int32_t OHOS::Media::Player::Stop ()

Description:

Stops playback.

Returns:

Returns 0 if the playback is stopped; returns -1 otherwise.