# 多媒体 media 2+

# 接口声明

{ "name": "system.media" }
1

# 导入模块

import media from '@system.media' 或 const network = require('@system.media')
1

# 接口定义

# media.createAudioPlayer()

创建音频播放的实例。

# 参数：

参数 类型 必填 说明
streamType String 否 streamType
contentType String 否 contentType
streamUsage String 否 streamUsage

# 返回值

AudioPlayer

# 示例：

const audioplayer = media.createAudioPlayer()
1

# media.createAudioTrack()

创建音频流式播放的实例

# 参数

参数名 类型 必填 说明
streamType String 否 streamType
contentType String 否 contentType
sampleRateInHz Number 否 采样率，单位赫兹，可选值为：8000、 16000；默认值为 16000
channelConfig Number 否 捕获音频的声道数目，1：单声道，2：立体声；默认值为 1
audioFormat Number 否 样本的分辨率，单位 bit，可选值为： 8、16；默认值为 16

# 返回值

AudioTrack

# 示例：

const audiotrack = media.createAudioTrack()
1

# media.createAudioRecord(OBJECT)

创建录音实例

# 参数

属性名 类型 必填 说明
sampleRateInHz Number 否 采样率，单位赫兹，可选值为：8000、 16000；默认值为 16000
channelConfig Number 否 音频的声道数目，1：单声道，2：立体声；默认值为 1
audioFormat Number 否 样本的分辨率，单位 bit，可选值为： 8、16；默认值为 16

# 返回值

AudioRecorder

# 示例：

const record = media.createAudioRecord()
1

# AudioPlayer

# AudioPlayer.play()

开始播放音频

# 参数

无

# 示例：

audioplayer.src = 'xxx'
// play 方法调用无需等待 src 加载完成
audioplayer.play()
1
2
3

# AudioPlayer.pause()

暂停播放音频

# 参数

无

# 示例：

audioplayer.pause()
1

# AudioPlayer.stop()

停止音频播放，可以通过 play 重新播放音频

# 参数

无

# 示例：

audioplayer.stop()
1

# AudioPlayer.release()

释放音频资源

# 参数

无

# 示例：

audioplayer.release()
1

# 属性

名称 参数类型 是否可读 是否可写 必填 描述
src String 是 是 是 播放的音频媒体 uri
currentTime Number 是 是 否 音频的当前进度，单位秒，对值设置可以调整播放进度
duration Number 是 否 否 音频文件的总时长，单位秒，未知返回 NaN
state String 是 否 否 播放状态，分别为'play','pause','stop','idle'
playcount Number 是 是 是 控制音频的循环播放，playcount == 1 或 playcount == 0：不开启循环; playcount >1：开启循环，且循环指定的次数; playcount == -1：开启循环，且循环无限次数

# 示例：

let currentTime = audioplayer.currentTime
// 跳转时间
audioplayer.currentTime = 100
1
2
3

# 事件

名称 描述 返回值
play 在音频 play 后的回调事件
pause 在音频 pause 后的回调事件
stop 在音频 stop 后的回调事件
ended 播放结束时的回调事件
error 播放发生错误时的回调事件
timeupdate 在 currentTime 属性更新时会触发的回调事件
durationchange 在 duration 属性更新时被触发的回调事件
previous 音乐面板点击上一首按钮时触发
next 音乐面板点击下一首按钮时触发
loadeddata 第一次获取到音频数据的回调事件
interrupt 音频打断事件，当前音频被其他有相同音频类型的音频抢夺时，被停止或者恢复的通知。或者当前音频被当外部设备操作打断的通知。 InterruptAction

# 示例：

audioplayer.oninterrupt = function (interruptAction) {
  console.log(interruptAction.interruptHint)
}
1
2
3

# AudioTrack

# AudioTrack.play()

开始播放音频

# 参数

无

# 示例：

audiotrack.play()
1

# AudioTrack.write(OBJECT)

写入音频数据

# 参数

参数 类型 必填 说明
buffer Uint8Array 是 写入的二进制音频数据
success Function 否 成功函数，通过该回调函数通知写入的情况
fail Function 否

# success 返回值：

参数值 类型 说明
state Number 写入状态，1 - 成功 2 - 失败 3 - 参数异常

# 示例：

http.get('/getAudio').then((res) => {
  audiotrack.write({
    buffer: new Uint8Array(res),
    success: function () {
      // wirte success
    },
  })
})
1
2
3
4
5
6
7
8

# AudioTrack.pause()

暂停播放音频

# 参数

无

# 示例：

audiotrack.pause()
1

# AudioTrack.stop()

停止音频播放，可以通过 play 重新播放音频

# 参数

无

# 示例：

audiotrack.stop()
1

# AudioTrack.release()

释放音频资源

# 参数

无

# 示例：

audiotrack.release()
1

# 属性

名称 参数类型 是否可读 是否可写 必填 描述
state String 是 否 否 播放状态，分别为'play','pause','stop'

# 示例：

let state = audiotrack.state
console.log(state)
1
2

# 事件

名称 描述 返回值
play 在音频 play 后的回调事件
stop 在音频 stop 后的回调事件
pause 在音频 pause 后的回调事件
ended 播放结束时的回调事件
error 播放发生错误时的回调事件
timeupdate 在 currentTime 属性更新时会触发的回调事件
interrupt 音频打断事件，当前音频被其他有相同音频类型的音频抢夺时，被停止或者恢复的通知。或者当前音频被当外部设备操作打断的通知。 InterruptAction

# 示例：

audiotrack.oninterrupt = function (interruptAction) {
  console.log(interruptAction.interruptHint)
}
1
2
3

# AudioRecorder

# AudioRecorder.start(OBJECT)

开始录音，并在录音结束后生成音频文件。

# 参数：

参数名 类型 必填 说明
uri String 是 需要输出到文件的 uri
success Function 是 成功的回调
fail Function 是 失败的回调
complete Function 是 执行结束后的回调
# success 返回值：

无

# 示例：

record.start({
  uri: 'internal://cache/path/to/file',
  success: function (data) {
    console.log(`handling success: ${data.uri}`)
  },
  fail: function (data, code) {},
})
1
2
3
4
5
6
7

# AudioRecorder.read(OBJECT)

开始录音，录音的过程中实时返回音频内容。

# 参数：

参数 类型 必填 说明
callback Function 否 回调函数
# callback 返回值：
参数名 类型 说明
buffer Uint8Array 录音内容

# 示例：

record.read({
  callback(buffer) {
    console.log('buffer.length: ' + buffer.length)
  },
})
1
2
3
4
5

# AudioRecorder.stop(OBJECT)

停止录音。

# 参数：

无

# 示例：

record.stop()
1

# AudioRecorder.release(OBJECT)

释放录音资源。

# 参数：

无

# 示例：

record.release()
1

# 事件

名称 描述
error 录音发生错误时的回调事件
start 录音开始时的回调事件
stop 录音停止时的回调事件

# 示例：

record.onerror = function () {
  console.log(`audio error`)
}
1
2
3

# streamUsage

指定使用音频类型 ，默认值为music。用于对音频冲突的仲裁，多个相同的streamUsage音频同时播放时，系统只会保留一个，其他的会被打断。

名称 说明
music 媒体

# contentType

用于音频后处理，默认值为music。系统会根据不同的 contentType 对声音进行优化处理。

名称 说明
speech 语音播报
music 音乐播放
movie 视频播放/电视节目
sonification 按键音/游戏中的短音提示/拟音

# streamType

用于音量策略，默认值为music。系统可以通过不同的 streamType 来管理音频的音量，例如：播放音乐设置为 music，消息提示音设置为 ring 。

名称 说明
music 媒体

# InterruptAction

属性 类型 说明
interruptHint Number 1 - 音频恢复 （如：来电恢复）
2 - 音频暂停 （如：来电打断）
3 - 音频停止（如：彻底停止）
actionType Number 事件返回类型。
0 - 被音频抢夺，焦点触发事件
1 - 音频被外部设备打断事件。