Skip to main content
版本：v3+

media

API_LEVEL 3.0 开始支持，API 兼容性请参考 API_LEVEL。

Media 多媒体模块包括播放器和录制器，有录制和播放音频的能力。

create​

创建多媒体控制对象

传入创建的类型，创建播放器 Player 对象或者录制器 Record 对象

create(id: number): Player | Record
id 取值说明
id.PLAYER播放器
id.RECORDER录制器
import { create, id } from '@zos/media'

const player = create(id.PLAYER)

通用方法和属性​

提示

Player 和 Record 具有公共的通用方法和属性

start​

开始播放/录制

start(): void

stop​

停止播放/录制

stop(): void

addEventListener​

事件监听，用于播放/录制器状态监听，当状态发生变化的时候，会触发 callback 回调函数

addEventListener(callback: function): void

Player 接口​

setSource​

在开始播放之前，设置播放参数，指定音频文件路径

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

source 的取值支持 player.source.FILE

player.source.FILE 播放指定文件，支持 MP3 格式，以及使用音频 API 录制的 OPUS 格式，对应的 obj 参数类型如下

属性说明是否必须类型
file文件路径，默认相对小程序 assets 目录。可通过 data://定向到小程序 data 目录播放小程序下载的音频文件是string

prepare​

播放器进入准备阶段，检查路径是否正确，文件格式是否可以播放，码率是否支持。成功则播放器状态变化，开始缓存多媒体数据。通过事件监听函数获取调用结果。

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​

获取当前播放的媒体文件总时长，单位秒，返回 0 代表无效，需要播放器处于 PREPARED 状态才可以获取到值

getDuration(): number

getVolume​

获取当前系统音量值，范围 [0 - 100]

getVolume(): number

setVolume​

设置系统音量值，范围 [0 - 100]，结果代表是否设置成功，true 表示设置成功

setVolume(vol: number): boolean

getTitle​

获取当前播放媒体文件标题，调用失败时返回 undefined

getTitle(): string | undefined

getArtist​

获取当前播放媒体文件艺术家信息，调用失败时返回 undefined

getArtist(): string | undefined

getMediaInfo​

获取当前播放媒体文件文件标题、艺术家、时长信息

getMediaInfo(): MediaInfo
属性说明类型
title文件名，setSource() 后可获取string|undefined
artist艺术家，setSource() 后可获取string|undefined
duration文件时长，需要播放器处于 PREPARED 状态才可以获取到值number

release​

接口已废弃，无需手动调用，系统自动管理

在播放停止后，释放播放器硬件资源

release(): void

getStatus​

获取播放器状态

getStatus(): number

返回值含义参考 player.state

seek​

API_LEVEL 4.2

设置播放位置（播放文件时长的百分比位置），percentage 有效值 [0 - 100]，返回值代表是否设置成功。

  • 如果当前是 PREPARED 状态，在 seek() 之后会自动开始播放
  • 如果当前是 PAUSED 或 PLAY 状态，在 seek() 之后保持当前状态
seek(percentage: number): boolean

player.event​

播放器支持监听的事件类型

事件值说明
player.event.PREPAREprepare() 会触发此事件，回调函数 function(result), result 为 boolean 类型，表示是否成功
player.event.COMPLETE音频正常开始播放后，待音频文件或音频数据播放结束时，可以监听到 COMPLETE 事件
player.event.PLAYstart() 和 seek() 会触发此事件，回调函数 function(result), result 为 boolean 类型，表示是否成功
player.event.STOPstop() 停止播放
player.event.PAUSE播放暂停，调用 pause() 触发，或因系统资源冲突触发
player.event.PROGRESS播放状态下（每秒）更新播放进度

player.state​

播放器状态枚举

状态值说明
player.state.IDLE初始状态
player.state.INITIALIZEDsetSource 后的状态
player.state.PREPARING中间状态，prepare 调用后，还未 PREPARED 时的状态
player.state.PREPAREDprepare 成功后的状态
player.state.STARTED开始播放后的状态，已废弃，使用 PLAY 替代
player.state.STARTING中间状态，开始播放处理
player.state.PLAY开始播放后的状态
player.state.PAUSED播放暂停时的状态
player.state.STOPPED停止播放后的状态
player.state.RESUMING中间状态，恢复播放处理中，恢复后变为 PLAY 状态

播放器事件和状态流转图​

Record 接口​

录音器支持录制音频到文件

setFormat​

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

codec 参考 codec 值

codec 取值说明
codec.OPUSOpus 编码类型

param 类型

属性说明是否必须类型
target_file录制到文件时，指定保存音频的路径，支持小程序的 data 目录，如：data://record_file.opus是string

代码示例​

// 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()