media

Supported since API_LEVEL 3.0. For API compatibility, please refer to API_LEVEL.

The Media multimedia module includes a player and recorder with the capability to record and play audio.

create

Creates a multimedia control object

Pass the creation type to create a Player object or a Record object

create(id: number): Player | Record

id Value	Description
id.PLAYER	Player
id.RECORDER	Recorder

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

const player = create(id.PLAYER)

Common Methods and Properties

tip

Player and Record have common methods and properties

start

Starts playing/recording

start(): void

stop

Stops playing/recording

stop(): void

addEventListener

Event listening for player/recorder state monitoring. When the state changes, the callback function will be triggered

addEventListener(callback: function): void

Player Interface

setSource

Sets playback parameters and specifies the audio file path before starting playback

setSource(source: number, obj: object): void

The source value supports player.source.FILE

player.source.FILE plays a specified file, supporting MP3 format and OPUS format recorded using the audio API. The corresponding obj parameter type is as follows

Property	Description	Required	Type
file	File path, relative to the mini app assets directory by default. Can use data:// to point to the mini app data directory to play downloaded audio files	Yes	string

prepare

The player enters the preparation phase, checking if the path is correct, if the file format is playable, and if the bitrate is supported. If successful, the player state changes and starts caching multimedia data. Get the call result through the event listener function.

prepare(): void

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

const player = create(id.PLAYER)

player.addEventListener(player.event.PREPARE, function (result) {
  if (result) {
    console.log('=== prepare succeed ===')
    player.start()
  } else {
    console.log('=== prepare fail ===')
  }
})

getDuration

Gets the total duration of the currently playing media file in seconds. Returns 0 to indicate invalid. The player must be in PREPARED state to get the value

getDuration(): number

getVolume

Gets the current system volume value, range [0 - 100]

getVolume(): number

setVolume

Sets the system volume value, range [0 - 100]. The result indicates whether the setting was successful, true indicates success

setVolume(vol: number): boolean

getTitle

Gets the title of the currently playing media file. Returns undefined on failure

getTitle(): string | undefined

getArtist

Gets the artist information of the currently playing media file. Returns undefined on failure

getArtist(): string | undefined

getMediaInfo

Gets the title, artist, and duration information of the currently playing media file

getMediaInfo(): MediaInfo

Property	Description	Type
title	File name, available after setSource()	string|undefined
artist	Artist, available after setSource()	string|undefined
duration	File duration, player must be in PREPARED state to get the value	number

release

Interface deprecated, no need to call manually, system automatically manages

Releases player hardware resources after playback stops

release(): void

getStatus

Gets the player state

getStatus(): number

Refer to player.state for the meaning of return values

seek

API_LEVEL 4.2

Sets the playback position (percentage position of playback file duration), percentage valid value [0 - 100]. The return value indicates whether the setting was successful.

• If currently in PREPARED state, it will automatically start playing after seek()
• If currently in PAUSED or PLAY state, it will maintain the current state after seek()

seek(percentage: number): boolean

player.event

Event types supported by the player for listening

Event Value	Description
player.event.PREPARE	prepare() will trigger this event, callback function function(result), result is boolean type, indicating success
player.event.COMPLETE	After audio starts playing normally, when the audio file or audio data playback ends, you can listen to the COMPLETE event
player.event.PLAY	start() and seek() will trigger this event, callback function function(result), result is boolean type, indicating success
player.event.STOP	stop() stops playback
player.event.PAUSE	Playback paused, triggered by calling pause(), or triggered due to system resource conflicts
player.event.PROGRESS	Updates playback progress (every second) during playback

player.state

Player state enumeration

State Value	Description
player.state.IDLE	Initial state
player.state.INITIALIZED	State after setSource
player.state.PREPARING	Intermediate state, after prepare is called, before PREPARED state
player.state.PREPARED	State after successful prepare
player.state.STARTED	State after starting playback, deprecated, use PLAY instead
player.state.STARTING	Intermediate state, starting playback processing
player.state.PLAY	State after starting playback
player.state.PAUSED	State when playback is paused
player.state.STOPPED	State after stopping playback
player.state.RESUMING	Intermediate state, resuming playback processing, becomes PLAY state after resume

Player Event and State Transition Diagram

Record Interface

The recorder supports recording audio to files

setFormat

setFormat(codec: number, param: object): void

Refer to codec values for codec

codec Value	Description
codec.OPUS	Opus encoding type

param type

Property	Description	Required	Type
target_file	When recording to a file, specify the path to save the audio, supports the mini app's data directory, such as: data://record_file.opus	Yes	string

Code Examples

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

const player = create(id.PLAYER)

player.addEventListener(player.event.PREPARE, function (result) {
  if (result) {
    console.log('=== prepare succeed ===')
    player.start()
  } else {
    console.log('=== prepare fail ===')
  }
})

player.addEventListener(player.event.COMPLETE, function (result) {
  console.log('=== play end ===')
  player.stop()
})

player.setSource(player.source.FILE, { file: '08-15s-16000-1ch.opus' })

// User control
player.prepare()
player.pause()
player.stop()

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

const recorder = create(id.RECORDER)

recorder.setFormat(codec.OPUS, {
  target_file: 'data://record_file.opus'
})

// start
recorder.start()

// stop
recorder.stop()