多媒体

导入模块

import media from '@system.media'

接口定义

方法

创建一个 AudioPlayer 对象。

方法

创建一个 AudioRecorder 对象。

方法

设置系统媒体音量，参数 volume 是 $[0.0, 1.0]$ 之间的音量值。此属性用于系统媒体音量的控制，具体功能取决于平台实现，调整音量应优先使用AudioPlayer对象的volume属性。

AudioPlayer 对象

类型签名

interface AudioPlayer {
  src: string,
  name: string,
  icon: string,
  mode: string,
  status: string,
  duration: number,
  position: number,
  openSystemNotification: bool,
  songAttribute: object, 
  volume: number,

  play(): void,
  pause(): void,
  stop(): void,
  release(): void,  

  onplay?: () => void,
  onpause?: () => void,
  onstop?: () => void,
  onended?: () => void,
  onerror?: (err: {msg: string})=> void
  ontimeupdate?: () => void,
  oninterrupt?: (action: {interruptHint: number}) => void
  onnext?: () => void,
  onprevious?: () => void,
  onsongattribute?: () => void,
  onmodechanged?: () => void,
}

读取 • 设置

设置或读取需要播放音频的 url。支持本地资源路径与使用http、https协议的网络资源路径（例如：https://www.rt-thread.com/service/test/001.mp3）。下面是一个设置 src 然后开始播放的简单示例：

import media from '@system.media'
// 创建音频播放器
let player = media.createAudioPlayer()
// 设置需要播放的音频url
player.src = 'https://www.rt-thread.com/service/test/001.mp3'
// 开始播放音频
player.play()

读取 • 设置

播放器对象的名字，如果不设置，默认为创建播放器的应用名。需要注意的是，播放器对象的名字并不是全局不唯一，并不能使用名字来标识播放器对象。

读取 • 设置

播放器对象的图标 url。支持本地资源路径

读取 • 设置

播放模式。该属性对应的功能应由播放器应用实现，播放器对象默认不处理，只提供该属性。

• sequential：顺序播放
• random：随机播放
• singleloop：单曲循环
• listloop：列表循环

读取

读取当前播放器状态

• play：正在播放状态
• pause：暂停播放状态
• stop：停止播放状态
• ended：播放结束状态
• error：播放错误状态

读取

音频总时长，单位：秒

读取 • 设置

当前音频播放的时间位置，单位：秒

读取 • 设置

是否开启系统通知，默认不开启。开启后，此播放器对象才可以被音频播放器管理器查询到。

读取 • 设置

歌曲属性对象

类型签名

type songAttribute = {
  title: string; // 歌曲的名称
  artist: string; // 表演者的名称，可以是个人或者乐队
  album: string; // 歌曲所属的专辑名称
  year: string; // 歌曲的发行年份
  genre: string; // 歌曲的类型，例如流行、摇滚、古典等
  track: string; // 当前歌曲在专辑中的编号，例如："1/12" 表示第1首，共12首
  coverArt: string; // 歌曲封面图片的url
  lyrics: string; // 歌词文本的 url
  comments: string; // 额外信息，如版权备注等
}

songAttribute对象与AudioPlayer对象一样是一个Proxy对象，即不能使用JSON序列化与反序列化，也不能在响应式框架中引用。下面是一个简单的使用示例：

// 设置歌曲的名字
this.player.songAttribute.title = "未知"
// 设置歌曲演唱者
this.player.songAttribute.artist = "未知"
// 查看歌曲的名字
console.dir(this.player.songAttribute.title)

读取 • 设置

当前播放器的音量，范围：[0.0, 1.0]

方法

开始播放在 src 属性中指定的音频

• 如果在调用此方法之前未设置 src 属性，会导致播放失败，触发 onerror 事件；
• 此方法为同步接口，执行此接口后，需要等待 onplay 事件或者 onerror 事件来判定播放成功或失败，在事件未触发之前，执行的额其它操作会被忽略；

下面是一个调用play() 接口的简单示例：

import media from '@system.media'
// 创建音频播放器
let player = media.createAudioPlayer()
// 设置需要播放的音频url
player.src = 'https://www.rt-thread.com/service/test/001.mp3'
// 设置 onplay 事件
player.onplay = () => { console.dir("开始播放") }
// 设置 onerror 事件
player.onerror = () => { console.dir("播放错误") }
// 开始播放音频
player.play()

方法

暂停播放当前音频

• 此方法为同步接口，执行此接口后，需要等待 onpause 事件或者 onerror 事件来判定暂停成功或失败，在事件未触发之前，执行的额其它操作会被忽略；

方法

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

• 此方法为同步接口，执行此接口后，需要等待 onstop 事件或者 onerror 事件来判定停止成功或失败，在事件未触发之前，执行的额其它操作会被忽略；

方法

释放音频资源

• 执行此接口会停止播放当前音频，需要等待 onstop 事件或者 onerror 事件来判定停止成功或失败，在事件未触发之前，执行的额其它操作会被忽略；

设置

在音频 play 成功后的回调事件

设置

在音频 pause 成功后的回调事件

设置

在音频 stop 成功后的回调事件

设置

在音频播放结束后的回调事件

设置

play pause stop 事件发生错误的回调事件，发生错误时， 对应的 onplay 等事件不会被触发

设置

在 position 属性更新时会触发的回调事件

设置

发生音频打断事件时的回调函数，当前音频被其他有相同音频类型的音频抢夺时，被停止或者恢复的通知。或者当前音频被当外部设备操作打断的通知。

action 参数的 interruptHint 指示打断事件的类型：

• 1：音频恢复 （如：来电恢复）
• 2：音频暂停 （如：来电打断）
• 3：音频暂停 （如：彻底停止）

以下示例演示注册 oninterrupt 回调函数的方法，该函数会在事件发生时调用：

player.oninterrupt = (action) => {
  console.log(action.interruptHint)
}

设置

需要播放下一曲时的回调事件

设置

需要播放上一曲时的回调事件

设置

歌曲属性对象发生变化时的回调事件

设置

播放模式发生变化时的回调事件

AudioRecorder 对象

类型签名

interface AudioRecorder {
    start({
      uri: string, 
      sample?: 8000 | 16000 | 44100 | 48000,
      layout?: 8 | 16 | 32,
      channel?: 1 | 2,
      bitrate?: 16 | 32 | 64,
    }): Promise<void>,
    read({callback: (ArrayBuffer) => void}): void,
    stop(): void,
    release(): void,
    onstart?: () => void,
    onstop?: () => void,
    onrelease?: () => void,
    onavailable?: (ArrayBuffer) => void,
    onerror?: ({error: string})=> void
}

start

方法

开始录制音频，options 参数的各字段功能为：

• uri：需要存储的录音文件 URI，只支持 internal 协议，会自动创建目录；
• sample：音频采样率，单位为 $\rm Hz$，默认为 $8000$；
• layout：音频数据位深度，默认为 $16$；
• channel：音频声道数，默认为 $1$；
• bitrate：音频码率，单位为 $\rm kbps$，默认为 $16$，码率越高，音质越好但文件也越大。

以下启动录音的示例代码：

let recorder = media.createAudioRecord()
recorder.start({
  uri: "internal://tmp/media_test.mp3",
  sample: 16000,
  layout: 16,
  channel: 1,
  bitrate: 16
})

相关信息

关于 internal URI 协议的更多说明请参考资源访问文档。

在录制完成后，请调用 stop() 方法来结束录制。

read

方法

读取录制的音频数据（每次读取到的数据为从上次读取结束的位置开始到目前为止所有可用的数据）

方法

停止录制音频。调用此接口后，可以由其他模块读取 start() 方法录制的音频文件（由 uri 参数指定）。

方法

释放录制音频资源

设置

在录制 start 后的回调事件

设置

在录制 stop 后的回调事件

设置

在录制 release 后的回调事件

设置

在录制开始后有新数据产生的回调事件

设置

start、stop 或 release 事件发生错误的回调事件，发生错误时，对应的 onstart 等不会被触发

示例

录音

以下代码演示了录制 3 秒钟音频的最简单示例：

import media from "@system.media"

async function record() {
  // 创建录音对象
  let record = media.createAudioRecord()
  console.log('start record')
  // 只填写了 uri 参数，其他参数使用默认值
  await record.start({
    uri: 'internal://tmp/test.mp3'
  })
  setTimeout(() => {
    console.log('stop record')
    record.stop() // 延时 3 秒后停止录音
  }, 3000)
}

record()

调用 record() 函数时会创建一个录音对象，然后开始录音，并在 3 秒钟之后停止录音。录音会被记录到 internal://tmp/test.mp3 文件中，并以 MP3 格式编码。

该示例只为 AudioPlayer.start() 方法传入了 uri 参数，sample、layout 、 channel 和 bitrate 均使用默认配置。

提示

使用模拟器时，可以到应用的数据目录找到录音文件并播放。internal://tmp/test.mp3 对应的文件路径是 .glyphix-work/image/{device}/data/temp/{app-id}/test.mp3 其中 {device} 和 {app-id} 是模拟时的设备名称和应用名称。