Player

Start from API_LEVEL 3.0 . Please refer to API_LEVEL.

The media player controller sets audio sources, prepares playback resources, controls playback, and reads media information..

Properties

source

Property	Type	Required	DefaultValue	Description	API_LEVEL
FILE	number	Y	-	Play a specified audio file	3.0

event

Property	Type	Required	DefaultValue	Description	API_LEVEL
PREPARE	number	Y	-	Asynchronous result of prepare()	3.0
COMPLETE	number	Y	-	Audio playback completed	3.0
PLAY	number	Y	-	Result after start() or resume()	3.0
STOP	number	Y	-	Playback stopped	3.0
PAUSE	number	Y	-	Playback paused	3.0
PROGRESS	number	Y	-	Playback progress updated	3.0

state

Property	Type	Required	DefaultValue	Description	API_LEVEL
IDLE	number	Y	-	Initial state	3.0
INITIALIZED	number	Y	-	State after setSource()	3.0
PREPARING	number	Y	-	Intermediate preparing state	3.0
PREPARED	number	Y	-	Resources prepared	3.0
STARTING	number	Y	-	Intermediate starting state	3.0
PLAY	number	Y	-	Playback in progress	3.0
PAUSING	number	Y	-	Intermediate pausing state	3.0
PAUSED	number	Y	-	Playback paused	3.0
RESUMING	number	Y	-	Intermediate resuming state	3.0

Methods

setSource

Set playback parameters and specify the audio file path before playback starts. player.source.FILE supports MP3 files and OPUS files recorded with the audio API. options.file is relative to the mini program assets directory by default; use data:// to access the data directory.

setSource(source: Player['source']['FILE'], options: { file: string }): void

prepare

Prepare the player by checking the path, file format, and supported bitrate. On success, the player changes state and starts buffering media data; use the event listener to get the result.

prepare(): void

start

Start playback

start(): void

pause

Pause playback

pause(): void

resume

Resume playback; has the same effect as calling start()

resume(): void

stop

Stop playback

stop(): void

seek

Start from API_LEVEL 4.2

Set the playback position as a percentage of the total duration. percentage must be in [0 - 100]; the return value indicates whether the position was set successfully.

• In PREPARED, playback starts automatically after seek()
• In PAUSED or PLAY, the current state is preserved after seek()

seek(percentage: number): boolean

seekTo

Start from API_LEVEL 4.3

Set the playback position in seconds; equivalent to seek()

seekTo(seconds: number): boolean

getDuration

Get the total duration of the current media file in seconds. A return value of 0 is invalid; the player must be in PREPARED to get the duration

getDuration(): number

getVolume

Get the current system volume in the range [0 - 100]

getVolume(): number

setVolume

Set the system volume in the range [0 - 100]. The return value indicates whether the setting succeeded; true means success

setVolume(volume: number): boolean

getTitle

Get the title of the current media file; returns undefined on failure

getTitle(): string | undefined

getArtist

Get the artist of the current media file; returns undefined on failure

getArtist(): string | undefined

getMediaInfo

Get the title, artist, and duration of the current media file. title and artist are available after setSource(); duration requires the player to be in PREPARED

getMediaInfo(): {
      title: string | undefined
      artist: string | undefined
      duration: number
    }

getStatus

Get the player state; see player.state for the meanings

getStatus(): number

addEventListener

Listen for playback state changes; callback is triggered when the state changes

addEventListener(event: number, callback: (result: boolean | number | undefined) => void): void

Example

import { create, id } from '@zos/media'

const player = create(id.PLAYER)
player.addEventListener(player.event.PREPARE, (result) => {
  if (result) player.start()
})
player.addEventListener(player.event.COMPLETE, () => {
  player.stop()
})
player.setSource(player.source.FILE, { file: 'data://music.opus' })
const info = player.getMediaInfo()
console.log(info.title, info.artist, info.duration)
player.prepare()
player.pause()
player.resume()
player.stop()