# 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](MultiMedia_Player.md#ga7dac9dac65cbbea7e411adcf2c314ac5) : int32_t ```

Enumerator

Description
PLAYER_INFO_RENDER_START 

Pushed the first video frame for rendering

## PlayerSeekMode ``` enum [OHOS::Media::PlayerSeekMode](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](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](MultiMedia_Player.md#gade9bff3268e1c409273749a90700e056). 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](MultiMedia_Player.md#gacce284eac910970e405151fd3a1963c0). **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](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](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](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.