diff --git a/zh-cn/application-dev/media/audio-playback.md b/zh-cn/application-dev/media/audio-playback.md index 2afa827c57fc2cc9703c7c8c3ac8ffb6ad54b26d..9a385d90763dff0760f236ef64078a6dacf2238f 100644 --- a/zh-cn/application-dev/media/audio-playback.md +++ b/zh-cn/application-dev/media/audio-playback.md @@ -1,131 +1,179 @@ # 音频播放开发指导 -- [场景介绍](#场景介绍) -- [接口说明](#接口说明) - ## 场景介绍 音频播放的主要工作是将音频数据转码为可听见的音频模拟信号并通过输出设备进行播放，同时对播放任务进行管理。 **图1** 音频播放状态机 -![zh-cn_image_0000001182608857](figures/zh-cn_image_0000001182608857.png) - - -## 接口说明 - -**表1** media - -| 接口名 | 描述 | -| -------- | -------- | -| media.createAudioPlayer() | 创建AudioPlayer实例。 | -| AudioPlayer | 提供音频播放相关功能，具体见表 音频播放相关的interface AudioPlayer。 | - -**表2** 音频播放相关的interface **AudioPlayer** - -| 接口名 | 描述 | -| -------- | -------- | -| release() | 释放音频资源。 | -| play() | 开始播放音频源。 | -| pause() | 暂停播放。 | -| stop() | 停止播放。 | -| reset()7+ | 重置播放音频源。 | -| setVolume(vol: number) | 改变音频播放音量 | -| seek(timeMs: number) | 改变播放位置。 | -| src:string | 音频播放的媒体URI。 | -| state:AudioState | 播放的状态属性。 | -| currentTime:number | 音频的当前播放位置。 | -| duration:number | 音频播放的时长(当数据源不支持改变播放位置时返回-1, 比如实时流媒体场景)。 | -| loop:boolean | 音频的循环播放属性。 | -| on('play', function callback) | 订阅音频播放开始事件。 | -| on('pause', function callback) | 订阅音频播放暂停事件。 | -| on('stop', function callback) | 订阅音频播放停止事件。 | -| on('reset', function callback) | 订阅音频播放重置事件。 | -| on('finish',function callback) | 订阅音频播放结束事件。 | -| on('error', function callback) | 订阅音频播放错误事件。 | -| on('dataload', function callback) | 订阅音频播放加载数据事件。 | -| on('volumeChange', function callback) | 订阅音频播放音量变化事件。 | -| on('timeUpdate', function callback) | 订阅音频播放进度改变事件。 | - - -1. 创建音频播放器。 - ``` - import media from '@ohos.multimedia.media'; - var player = media.createAudioPlayer(); - ``` - -2. 设置消息订阅事件。 - ``` - player.on('play', (err, action) => { - if (err) { - console.error('Error returned in the play() callback.'); - return; - } - console.info('Current player duration: '+ player.duration); - console.info('Current player time: ' + player.currentTime); - console.info('Current player status: '+player.state); - console.info('Pause MP3'); - player.pause(); - }); - player.on('pause', (err, action) => { - if (err) { - console.error('Error returned in the pause() callback.'); + +![zh-ch_image_20220117](figures/zh-ch_image_20220117.jpg) + +## 音频播放开发步骤 + +详细API含义可参考：[js-apis-media.md](../reference/apis/js-apis-media.md) + +### 全流程场景 + +包含流程：创建实例，设置uri，播放音频，跳转播放位置，设置音量，暂停播放，获取轨道信息，停止播放，重置，释放资源等流程。 + +AudioPlayer支持的src媒体源输入类型可参考：[src属性说明](../reference/apis/js-apis-media.md#audioplayer_属性) + +```js +function SetCallBack(audioPlayer) { + audioPlayer.on('dataLoad', () => { //设置'dataLoad'事件回调，src属性设置成功后，触发此回调 + console.info('audio set source success'); + //播放界面可切换至已准备好，可点击播放按钮进行播放状态 + }); + audioPlayer.on('play', () => { //设置'play'事件回调 + console.info('audio play success'); + //将播放按钮切换至可暂停状态 + }); + audioPlayer.on('pause', () => { //设置'pause'事件回调 + console.info('audio pause success'); + //将播放按钮切换至可播放状态 + }); + audioPlayer.on('stop', () => { //设置'stop'事件回调 + console.info('audio stop success'); + //播放停止，播放进度条归零，播放按钮切换至可播放状态 + }); + audioPlayer.on('reset', () => { //设置'reset'事件回调 + console.info('audio reset success'); + //需重新设置src属性后，可继续播放其他音频 + }); + audioPlayer.on('timeUpdate', (seekDoneTime) => {//设置'timeUpdate'事件回调 + if (typeof(seekDoneTime) == 'undefined') { + console.info('audio seek fail'); return; - } - console.info('Current player status: ' + player.state); - console.info('Current player time: ' + player.currentTime); - player.seek(30000); // Seek for 30 seconds. - }); - player.on('stop', (err, action) => { - if (err) { - console.error('Error returned in the stop() callback.'); - return; - } - console.info('stop callback invoked. State:' + player.state); - player.reset(); - }); - player.on('dataLoad', (err, action) => { - if (err) { - console.error('Error returned in the dataLoad() callback.'); - return; - } - console.info('dataLoad callback invoked. Current time: ' + player.currentTime); - console.info('Duration of the source:' + player.duration); - player.play(); - }); - player.on('reset', (err, action) => { - if (err) { - console.error('Error returned in the reset() callback.'); - return; - } - console.info('reset callback invoked.'); - player.release(); - }); - player.on('finish', (err, action) => { - if (err) { - console.error('Error returned in the finish() callback.'); - return; } - console.info('finish callback invoked.'); - }); - player.on('timeUpdate', (seekTime, action) => { - console.info('Seek time: ' + seekTime); - console.info('Current player time: ' + player.currentTime); - var newTime = player.currentTime; - if(newTime == 30000) { - console.info('Seek succeeded. New time: ' + newTime); - } else { - console.error('Seek failed: ', + newTime); + console.info('audio seek success, and seek time is ' + seekDoneTime); + //播放进度条更新到seek对应的位置 + }); + audioPlayer.on('volumeChange', () => { //设置'volumeChange'事件回调 + console.info('audio volumeChange success'); + //更新音量显示 + }); + audioPlayer.on('finish', () => { //设置'finish'事件回调，播放完成触发 + console.info('audio play finish'); + }); + audioPlayer.on('error', (error) => { //设置'error'事件回调 + console.info(`audio error called, errName is ${error.name}`); + console.info(`audio error called, errCode is ${error.code}`); + console.info(`audio error called, errMessage is ${error.message}`); + }); +} + +function printfDescription(obj) { + for (let item in obj) { + let property = obj[item]; + console.info('audio key is ' + item); + console.info('audio value is ' + property); + } +} + +//1、创建实例 +let audioPlayer = media.createAudioPlayer(); +SetCallBack(audioPlayer); //设置事件回调 +//2、用户选择音频，设置uri +audioPlayer.src = 'file:///data/data/ohos.xxx.xxx/files/test.mp3'; //设置src属性，并触发'dataLoad'事件回调 +//3、播放音频 +audioPlayer.play(); //需等待'dataLoad'事件回调完成后，才可调用play进行播放，触发'play'事件回调 +//4、跳转播放位置 +audioPlayer.seek(30000); //触发'timeUpdate'事件回调，seek到30000ms处播放 +//5、设置音量 +audioPlayer.setVolume(0.5); //触发'volumeChange'事件回调 +//6、暂停播放 +audioPlayer.pause(); //触发'pause'事件回调，暂停播放 +//7、获取轨道信息 +audioPlayer.getTrackDescription((error, arrlist) => { //通过回调方式获取音频轨道信息 + if (typeof (arrlist) != 'undefined') { + for (let i = 0; i < arrlist.length; i++) { + printfDescription(arrlist[i]); } - player.stop(); - }); - player.on('error', (err) => { - console.error('Player error: ${err.message}'); - }); - ``` - -3. 启动播放。 - ``` - var audioSourceMp3 = 'file://test.mp3'; - player.src = audioSourceMp3; - player.loop = true; - ``` + } else { + console.log(`audio getTrackDescription fail, error:${error.message}`); + } +}); +//8、停止播放 +audioPlayer.stop(); //触发'stop'事件回调 +//9、重置播放资源 +audioPlayer.reset(); //触发'reset'事件回调后，重新设置src属性，可完成切歌 +//10、释放资源 +audioPlayer.release(); //audioPlayer资源被销毁 +audioPlayer = undefined; +``` + +### 正常播放场景 + +```js +function SetCallBack(audioPlayer) { + audioPlayer.on('dataLoad', () => { //设置'dataLoad'事件回调，src属性设置成功后，触发此回调 + console.info('audio set source success'); + audioPlayer.play(); //调用play方法开始播放，触发'play'事件回调 + }); + audioPlayer.on('play', () => { //设置'play'事件回调 + console.info('audio play success'); + }); + audioPlayer.on('finish', () => { //设置'finish'事件回调，播放完成触发 + console.info('audio play finish'); + audioPlayer.release(); //audioPlayer资源被销毁 + audioPlayer = undefined; + }); +} + +let audioPlayer = media.createAudioPlayer(); //创建一个音频播放实例 +SetCallBack(audioPlayer); //设置事件回调 +/* 用户选择音频，设置uri */ +audioPlayer.src = 'file:///data/data/ohos.xxx.xxx/files/test.mp3'; //设置src属性，并触发'dataLoad'事件回调 +``` + +### 切歌场景 + +```js +function SetCallBack(audioPlayer) { + audioPlayer.on('dataLoad', () => { //设置'dataLoad'事件回调，src属性设置成功后，触发此回调 + console.info('audio set source success'); + audioPlayer.play(); //调用play方法开始播放，触发'play'事件回调 + }); + audioPlayer.on('play', () => { //设置'play'事件回调 + console.info('audio play success'); + }); + audioPlayer.on('finish', () => { //设置'finish'事件回调，播放完成触发 + console.info('audio play finish'); + audioPlayer.release(); //audioPlayer资源被销毁 + audioPlayer = undefined; + }); +} + +let audioPlayer = media.createAudioPlayer(); //创建一个音频播放实例 +SetCallBack(audioPlayer); //设置事件回调 +/* 用户选择音频，设置uri */ +audioPlayer.src = 'file:///data/data/ohos.xxx.xxx/files/test.mp3'; //设置src属性，并触发'dataLoad'事件回调 +/* 播放一段时间后，下发切歌指令 */ +audioPlayer.reset(); +audioPlayer.src = 'file:///data/data/ohos.xxx.xxx/files/next.mp3'; +``` + +### 单曲循环场景 + +```js +function SetCallBack(audioPlayer) { + audioPlayer.on('dataLoad', () => { //设置'dataLoad'事件回调，src属性设置成功后，触发此回调 + console.info('audio set source success'); + audioPlayer.play(); //调用play方法开始播放，触发'play'事件回调 + }); + audioPlayer.on('play', () => { //设置'play'事件回调 + console.info('audio play success'); + }); + audioPlayer.on('finish', () => { //设置'finish'事件回调，播放完成触发 + console.info('audio play finish'); + audioPlayer.release(); //audioPlayer资源被销毁 + audioPlayer = undefined; + }); +} + +let audioPlayer = media.createAudioPlayer(); //创建一个音频播放实例 +SetCallBack(audioPlayer); //设置事件回调 +/* 用户选择音频，设置uri */ +audioPlayer.src = 'file:///data/data/ohos.xxx.xxx/files/test.mp3'; //设置src属性，并触发'dataLoad'事件回调 +audioPlayer.loop = true; //设置循环播放属性 +``` \ No newline at end of file diff --git a/zh-cn/application-dev/media/figures/zh-ch_image_20220117.jpg b/zh-cn/application-dev/media/figures/zh-ch_image_20220117.jpg new file mode 100644 index 0000000000000000000000000000000000000000..bc56b9d8395873193bbad2b3faf7340c6728af60 Binary files /dev/null and b/zh-cn/application-dev/media/figures/zh-ch_image_20220117.jpg differ diff --git a/zh-cn/application-dev/reference/apis/js-apis-media.md b/zh-cn/application-dev/reference/apis/js-apis-media.md index 22bbb3998329082e085bf9c70aaef9c63583b6aa..718a612763e60244faa01bf695e5f70e832f87b4 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-media.md +++ b/zh-cn/application-dev/reference/apis/js-apis-media.md @@ -1,34 +1,95 @@ -# 音频播放和录制 +# 媒体服务 + +媒体子系统为开发者提供一套简单且易于理解的接口，使得开发者能够方便接入系统并使用系统的媒体资源。 + +媒体子系统包含了音视频相关媒体业务，提供以下常用功能： + +- 音频播放（[AudioPlayer](#audioplayer)） +- 音频录制（[AudioRecorder](#audiorecorder)） + +后续将提供以下功能：视频播放、视频录制、DataSource音视频播放、音视频编解码、容器封装解封装、媒体能力查询等功能。 ## 导入模块 -``` +```js import media from '@ohos.multimedia.media'; ``` +## media.createAudioPlayer -## 权限 +createAudioPlayer(): [AudioPlayer](#audioplayer) -无 +同步方式创建音频播放实例。 +**返回值：** -## media.createAudioPlayer +| 类型 | 说明 | +| --------------------------- | ------------------------------------------------------------ | +| [AudioPlayer](#audioplayer) | 返回AudioPlayer类实例，失败时返回null。可用于音频播放、暂停、停止等操作。 | -createAudioPlayer(): AudioPlayer +**示例：** -创建音频播放的实例。 +```js +var audioPlayer = media.createAudioPlayer(); +``` -**返回值：** +## media.createAudioPlayerAsync8+ + +createAudioPlayerAsync(callback: AsyncCallback\<[AudioPlayer](#audioplayer)>): void -| 类型 | 说明 | -| -------- | -------- | -| [AudioPlayer](#audioplayer) | 返回AudioPlayer类实例，失败时返回null。 | +异步方式创建音频播放实例。通过注册回调函数获取返回值。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------ | ---- | ------------------------------ | +| callback | AsyncCallback<[AudioPlayer](#audioplayer)> | 是 | 异步创建音频播放实例回调方法。 | **示例：** +```js +media.createAudioPlayerAsync((error, audio) => { + if (typeof(audio) != 'undefined') { + audioPlayer = audio; + console.info('audio createAudioPlayerAsync success'); + } else { + console.info(`audio createAudioPlayerAsync fail, error:${error.message}`); + } +}); ``` -var audioplayer = media.createAudioPlayer(); + +## media.createAudioPlayerAsync8+ + +createAudioPlayerAsync: Promise<[AudioPlayer](#audioplayer)> + +异步方式创建音频播放实例。通过Promise获取返回值。 + +**返回值：** + +| 类型 | 说明 | +| ------------------------------------ | ----------------------------------- | +| Promise<[AudioPlayer](#audioplayer)> | 异步创建音频播放实例Promise返回值。 | + +**示例：** + +```js +function failureCallback(error) { + console.info(`audio failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`audio catchCallback, error:${error.message}`); +} + +await media.createAudioPlayerAsync.then((audio) => { + if (typeof(audio) != 'undefined') { + audioPlayer = audio; + console.info('audio createAudioPlayerAsync success'); + } else { + console.info('audio createAudioPlayerAsync fail'); + } +}, failureCallback).catch(catchCallback); ``` + ## media.createAudioRecorder createAudioRecorder(): AudioRecorder @@ -41,42 +102,109 @@ createAudioRecorder(): AudioRecorder | [AudioRecorder](#audiorecorder) | 返回AudioRecorder类实例，失败时返回null。 | **示例：** + ``` var audiorecorder = media.createAudioRecorder(); ``` +## MediaErrorCode8+ + +媒体服务错误类型枚举 + +| 名称 | 值 | 说明 | +| -------------------------- | ---- | -------------------------------------- | +| MSERR_OK | 0 | 表示操作成功。 | +| MSERR_NO_MEMORY | 1 | 表示申请内存失败，系统可能无可用内存。 | +| MSERR_OPERATION_NOT_PERMIT | 2 | 表示无权限执行此操作。 | +| MSERR_INVALID_VAL | 3 | 表示传入入参无效。 | +| MSERR_IO | 4 | 表示发生IO错误。 | +| MSERR_TIMEOUT | 5 | 表示操作超时。 | +| MSERR_UNKNOWN | 6 | 表示未知错误。 | +| MSERR_SERVICE_DIED | 7 | 表示服务端失效。 | +| MSERR_INVALID_STATE | 8 | 表示在当前状态下，不允许执行此操作。 | +| MSERR_UNSUPPORTED | 9 | 表示在当前版本下，不支持此操作。 | + +## MediaType8+ + +媒体类型枚举 + +| 名称 | 值 | 说明 | +| ------------------- | ---- | ------------------ | +| MEDIA_TYPE_AUD | 0 | 表示音频。 | +| MEDIA_TYPE_VID | 1 | 表示视频。 | +| MEDIA_TYPE_SUBTITLE | 2 | 表示字幕：开发中。 | + +## CodecMimeType8+ + +Codec MIME类型枚举 + +| 名称 | 值 | 说明 | +| ------------ | ----------------- | ------------------------ | +| AUDIO_MPEG | "audio/mpeg" | 表示音频/mpeg类型。 | +| AUDIO_AAC | "audio/mp4a-latm" | 表示音频/mp4a-latm类型。 | +| AUDIO_VORBIS | "audio/vorbis" | 表示音频/vorbis类型。 | +| AUDIO_FLAC | "audio/flac" | 表示音频/flac类型。 | + +## MediaDescriptionKey8+ + +媒体信息描述枚举 + +| 名称 | 值 | 说明 | +| ------------------------ | --------------- | ------------------------------------------------------------ | +| MD_KEY_TRACK_INDEX | "track_index" | 表示轨道序号，其对应键值类型为number。 | +| MD_KEY_TRACK_TYPE | "track_type" | 表示轨道类型，其对应键值类型为number，参考[MediaType](#mediatype8)。 | +| MD_KEY_CODEC_MIME | "codec_mime" | 表示codec_mime类型，其对应键值类型为string。 | +| MD_KEY_DURATION | "duration" | 表示媒体时长，其对应键值类型为number，单位为ms。 | +| MD_KEY_BITRATE | "bitrate" | 表示比特率，其对应键值类型为number，单位为bps。 | +| MD_KEY_WIDTH | "width" | 表示视频宽度，其对应键值类型为number，单位为像素。 | +| MD_KEY_HEIGHT | "height" | 表示视频高度，其对应键值类型为number，单位为像素。 | +| MD_KEY_FRAME_RATE | "frame_rate" | 表示视频帧率，其对应键值类型为number，单位为100fps。 | +| MD_KEY_AUD_CHANNEL_COUNT | "channel_count" | 表示声道数，其对应键值类型为number。 | +| MD_KEY_AUD_SAMPLE_RATE | "sample_rate" | 表示采样率，其对应键值类型为number，单位为HZ。 | + +## BufferingInfoType8+ + +缓存事件类型枚举 + +| 名称 | 值 | 说明 | +| ----------------- | ---- | -------------------------- | +| BUFFERING_START | 1 | 表示开始缓存。 | +| BUFFERING_END | 2 | 表示结束缓存。 | +| BUFFERING_PERCENT | 3 | 表示缓存百分比。 | +| CACHED_DURATION | 4 | 表示缓存时长，单位为毫秒。 | + ## AudioPlayer -音频播放管理类，用于管理和播放音频媒体。在调用AudioPlayer的方法前，需要先通过[createAudioPlayer()](#createaudioplayer-)构建一个AudioPlayer实例。 +音频播放管理类，用于管理和播放音频媒体。在调用AudioPlayer的方法前，需要先通过[createAudioPlayer()](#media.createaudioplayer)或[createAudioPlayerAsync()](#media.createaudioplayerasync8)构建一个[AudioPlayer](#audioplayer)实例。 +音频播放demo可参考：[音频播放开发指导](../../media/audio-playback.md) -### 属性 +### 属性 -| 名称 | 参数类型 | 可读 | 可写 | 说明 | -| -------- | -------- | -------- | -------- | -------- | -| src | string | 是 | 是 | 音频媒体URI，支持当前主流的音频格式(mp4、aac、mp3、ogg)，支持本地绝对路径（file://) | -| loop | boolean | 是 | 是 | 音频循环播放属性，设置为'true'表示循环播放。 | -| currentTime | number | 是 | 否 | 音频的当前播放阶段。 | -| duration | number | 是 | 否 | 音频时长。 | -| state | [AudioState](#audiostate) | 是 | 否 | 音频播放的状态。 | +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ----------- | ------------------------- | ---- | ---- | ------------------------------------------------------------ | +| src | string | 是 | 是 | 音频媒体URI，支持当前主流的音频格式(mp4、aac、mp3、ogg)。
**支持路径示例**：
1、本地绝对路径：file:///data/data/ohos.xxx.xxx/files/test.mp4
![zh-cn_image_0000001164217678](figures/zh-cn_image_0000001164217678.png)
2、http网络播放路径：开发中
3、hls网络播放路径：开发中
4、fd类型播放：开发中
**注意事项**：
媒体素材需至少赋予读权限后，才可正常播放 | +| loop | boolean | 是 | 是 | 音频循环播放属性，设置为'true'表示循环播放。 | +| currentTime | number | 是 | 否 | 音频的当前播放位置。 | +| duration | number | 是 | 否 | 音频时长。 | +| state | [AudioState](#audiostate) | 是 | 否 | 音频播放的状态。 | -### play +### play play(): void -开始播放音频资源。 +开始播放音频资源，需在[dataLoad](#on('play' | 'pause' | 'stop' | 'reset' | 'dataload' | 'finish' | 'volumechange'))事件成功触发后，才能调用play方法。 **示例：** -``` -audioplayer.src = 'file:///data/media/sounds.mp4'; -audioplayer.on('play', () => { - console.log('Playback starts.'); +```js +audioPlayer.on('play', () => { //设置'play'事件回调 + console.log('audio play success'); }); -audioplayer.play(); +audioPlayer.play(); ``` -### pause +### pause pause(): void @@ -84,15 +212,14 @@ pause(): void **示例：** -``` -audioplayer.src = 'file:///data/media/sounds.mp4'; -audioplayer.on('pause', () => { - console.log('Playback paused.'); +```js +audioPlayer.on('pause', () => { //设置'pause'事件回调 + console.log('audio pause success'); }); -audioplayer.pause(); +audioPlayer.pause(); ``` -### stop +### stop stop(): void @@ -100,15 +227,29 @@ stop(): void **示例：** +```js +audioPlayer.on('stop', () => { //设置'stop'事件回调 + console.log('audio stop success'); +}); +audioPlayer.stop(); ``` -audioplayer.src = 'file:///data/media/sounds.mp4'; -audioplayer.on('stop',() => { - console.log('Playback stopped.'); + +### reset7+ + +reset(): void + +切换播放音频资源。 + +**示例：** + +```js +audioPlayer.on('reset', () => { //设置'reset'事件回调 + console.log('audio reset success'); }); -audioplayer.stop(); +audioPlayer.reset(); ``` -### seek +### seek seek(timeMs: number): void @@ -116,26 +257,24 @@ seek(timeMs: number): void **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| timeMs | number | 是 | 指定的跳转时间节点。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------------------------ | +| timeMs | number | 是 | 指定的跳转时间节点，单位毫秒。 | **示例：** -``` -audioplayer.src = 'file:///data/media/sounds.mp4'; -audioplayer.on('timeupdate', (action) => { - var newTime = audioplayer.currenTime; - if(newTime >= 30000) { - console.info('Seek succeeded. New time: ' + newTime); - } else { - console.info('Seek failed.'); - } +```js +audioPlayer.on('timeUpdate', (seekDoneTime) => { //设置'timeUpdate'事件回调 + if (typeof (seekDoneTime) == 'undefined') { + console.info('audio seek fail'); + return; + } + console.log('audio seek success. seekDoneTime: ' + seekDoneTime); }); -audioplayer.seek(30000); +audioPlayer.seek(30000); //seek到30000ms的位置 ``` -### setVolume +### setVolume setVolume(vol: number): void @@ -143,128 +282,279 @@ setVolume(vol: number): void **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| vol | number | 是 | 指定的相对音量大小，取值范围为[0.00-1.00]，1表示最大音量，即100%。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------------------------------------------------------ | +| vol | number | 是 | 指定的相对音量大小，取值范围为[0.00-1.00]，1表示最大音量，即100%。 | **示例：** -``` -audioplayer.src = 'file:///data/media/sounds.mp4'; -audioplayer.on('volumeChange', () => { - console.log('Playback volume changed.'); +```js +audioPlayer.on('volumeChange', () => { //设置'volumeChange'事件回调 + console.log('audio volumeChange success'); }); -audioplayer.setVolume(1); +audioPlayer.setVolume(1); //设置音量到100% ``` -### reset7+ +### release -reset(): void +release(): void -切换播放音频资源。 +释放音频资源。 **示例：** -``` -audioplay.reset(); +```js +audioPlayer.release(); +audioPlayer = undefined; ``` -### release7+ +### getTrackDescription8+ -release(): void +getTrackDescription(callback: AsyncCallback>): void -释放音频资源。 +通过回调方式获取音频轨道信息。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------------------ | ---- | -------------------------- | +| callback | AsyncCallback> | 是 | 获取音频轨道信息回调方法。 | **示例：** +```js +function printfDescription(obj) { + for (let item in obj) { + let property = obj[item]; + console.info('audio key is ' + item); + console.info('audio value is ' + property); + } +} + +audioPlayer.getTrackDescription((error, arrlist) => { + if (typeof (arrlist) != 'undefined') { + for (let i = 0; i < arrlist.length; i++) { + printfDescription(arrlist[i]); + } + } else { + console.log(`audio getTrackDescription fail, error:${error.message}`); + } +}); ``` -audioplay.release(); + +### getTrackDescription8+ + +getTrackDescription(): Promise> + +通过Promise方式获取音频轨道信息。 + +**返回值：** + +| 类型 | 说明 | +| ------------------------------------------------------ | ------------------------------- | +| Promise> | 获取音频轨道信息Promise返回值。 | + +**示例：** + +```js +function printfDescription(obj) { + for (let item in obj) { + let property = obj[item]; + console.info('audio key is ' + item); + console.info('audio value is ' + property); + } +} +function failureCallback(error) { + console.info(`audio failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`audio catchCallback, error:${error.message}`); +} + +await audioPlayer.getTrackDescription.then((arrlist) => { + if (typeof (arrlist) != 'undefined') { + arrayDescription = arrlist; + } else { + console.log('audio getTrackDescription fail'); + } +}, failureCallback).catch(catchCallback); +for (let i = 0; i < arrayDescription.length; i++) { + printfDescription(arrayDescription[i]); +} ``` -### on('play' | 'pause' | 'stop' | 'reset' | 'dataLoad' | 'finish' | 'volumeChange') +### on('bufferingUpdate')8+ -on(type: 'play' | 'pause' | 'stop' | 'reset' | 'dataLoad' | 'finish' | 'volumeChange', callback: () => void) +on(type: 'bufferingUpdate', callback: (infoType: [BufferingInfoType](#bufferinginfotype8), value: number) => void): void -开始监听音频播放事件。 +开始订阅音频缓存更新事件。 **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| type | string | 是 | 播放事件回调类型，支持的事件包括：'play' \| 'pause' \| 'stop' \| 'reset' \| 'dataLoad' \| 'finish' \| 'volumeChange'。
- 'play' ：完成play方法调用，音频开始播放，触发该事件。
- 'pause'：完成pause方法调用，音频暂停播放，触发该事件。
- 'stop'：完成stop方法调用，音频停止播放，触发该事件。
- 'reset'：完成reset方法调用，播放器重置，触发该事件。
- 'dataLoad'：完成音频数据加载后触发该事件。
- 'finish'：完成音频播放后触发该事件。
- 'volumeChange'：播放音量改变后触发该事件。播放事件回调方法。 | -| callback | function | 是 | 播放事件回调方法。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | string | 是 | 音频缓存事件回调类型，支持的事件：'bufferingUpdate'。 | +| callback | (infoType: [BufferingInfoType](#bufferinginfotype8), value: number) => void | 是 | 音频缓存事件回调方法。
[BufferingInfoType](#bufferinginfotype8)为BUFFERING_PERCENT或CACHED_DURATION时，value值有效，否则固定为0。 | **示例：** +```js +audioPlayer.on('bufferingUpdate', (infoType, value) => { + console.log('audio bufferingInfo type: ' + infoType); + console.log('audio bufferingInfo value: ' + value); +}); ``` -audioplayer.src = 'file://xxx/sounds.mp4'; -audioplayer.on('play', () => { - console.log('Playback starts.'); + + ### on('play' | 'pause' | 'stop' | 'reset' | 'dataLoad' | 'finish' | 'volumeChange') + +on(type: 'play' | 'pause' | 'stop' | 'reset' | 'dataLoad' | 'finish' | 'volumeChange', callback: () => void): void + +开始订阅音频播放事件。 + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------- | ---- | ------------------------------------------------------------ | +| type | string | 是 | 播放事件回调类型，支持的事件包括：'play' \| 'pause' \| 'stop' \| 'reset' \| 'dataLoad' \| 'finish' \| 'volumeChange'。
- 'play'：完成[play()](#audioplayer_play)调用，音频开始播放，触发该事件。
- 'pause'：完成[pause()](#audioplayer_pause)调用，音频暂停播放，触发该事件。
- 'stop'：完成[stop()](#audioplayer_stop)调用，音频停止播放，触发该事件。
- 'reset'：完成[reset()](#audioplayer_reset)调用，播放器重置，触发该事件。
- 'dataLoad'：完成音频数据加载后触发该事件，即src属性设置完成后触发该事件。
- 'finish'：完成音频播放后触发该事件。
- 'volumeChange'：完成[setVolume()](#audioplayer_setvolume)调用，播放音量改变后触发该事件。 | +| callback | () => void | 是 | 播放事件回调方法。 | + +**示例：** + +```js +let audioPlayer = media.createAudioPlayer(); //创建一个音频播放实例 +audioPlayer.on('dataLoad', () => { //设置'dataLoad'事件回调，src属性设置成功后，触发此回调 + console.info('audio set source success'); + audioPlayer.play(); //开始播放，并触发'play'事件回调 +}); +audioPlayer.on('play', () => { //设置'play'事件回调 + console.info('audio play success'); + audioPlayer.seek(30000); //调用seek方法，并触发'timeUpdate'事件回调 +}); +audioPlayer.on('pause', () => { //设置'pause'事件回调 + console.info('audio pause success'); + audioPlayer.stop(); //停止播放，并触发'stop'事件回调 }); -audioplayer.play(); +audioPlayer.on('reset', () => { //设置'reset'事件回调 + console.info('audio reset success'); + audioPlayer.release(); //释放播放实例资源 + audioPlayer = undefined; +}); +audioPlayer.on('timeUpdate', (seekDoneTime) => { //设置'timeUpdate'事件回调 + if (typeof(seekDoneTime) == "undefined") { + console.info('audio seek fail'); + return; + } + console.info('audio seek success, and seek time is ' + seekDoneTime); + audioPlayer.setVolume(0.5); //设置音量为50%，并触发'volumeChange'事件回调 +}); +audioPlayer.on('volumeChange', () => { //设置'volumeChange'事件回调 + console.info('audio volumeChange success'); + audioPlayer.pause(); //暂停播放，并触发'pause'事件回调 +}); +audioPlayer.on('finish', () => { //设置'finish'事件回调 + console.info('audio play finish'); + audioPlayer.stop(); //停止播放，并触发'stop'事件回调 +}); +audioPlayer.on('error', (error) => { //设置'error'事件回调 + console.info(`audio error called, errName is ${error.name}`); + console.info(`audio error called, errCode is ${error.code}`); + console.info(`audio error called, errMessage is ${error.message}`); +}); +audioPlayer.src = 'file:///data/data/ohos.xxx.xxx/files/test.mp4'; //设置src属性，并触发'dataLoad'事件回调 ``` ### on('timeUpdate') on(type: 'timeUpdate', callback: Callback\): void -开始监听音频播放时间戳更新事件。 +开始订阅音频播放[seek()](#audioplayer_seek)时间更新事件。 **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| type | string | 是 | 播放事件回调类型，支持的事件为：'timeUpdate'。
'timeUpdate'：音频播放时间戳更新，触发该事件。seek方法调用时也会触发该事件。 | -| callback | Callback<number> | 是 | 播放事件回调方法。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------- | ---- | ------------------------------------------------------------ | +| type | string | 是 | 播放事件回调类型，支持的事件包括：'timeUpdate'。
- 'timeUpdate'：[seek()](#audioplayer_seek)调用完成，触发该事件。 | +| callback | Callback\ | 是 | 播放事件回调方法。回调方法入参为成功seek的时间。 | **示例：** -``` -audioplayer.src = 'file://xxx/sounds.mp4'; -audioplayer.on('timeupdate', (newTime ) => { - if(newTime >= 30000) { - console.info('Seek succeeded. New time: ' + newTime); - } else { - console.info('Seek failed.'); - } +```js +audioPlayer.on('timeUpdate', (seekDoneTime) => { //设置'timeUpdate'事件回调 + if (typeof (seekDoneTime) == 'undefined') { + console.info('audio seek fail'); + return; + } + console.log('audio seek success. seekDoneTime: ' + seekDoneTime); }); -audioplayer.seek(30000); +audioPlayer.seek(30000); //seek到30000ms的位置 ``` ### on('error') on(type: 'error', callback: ErrorCallback): void -开始监听音频播放错误事件。 +开始订阅音频播放错误事件。 **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| type | string | 是 | 播放错误事件回调类型'error'。
'error'：音频播放中发生错误，触发该事件。 | -| callback | ErrorCallback | 是 | 播放错误事件回调方法。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------- | ---- | ------------------------------------------------------------ | +| type | string | 是 | 播放错误事件回调类型，支持的事件包括：'error'。
- 'error'：音频播放中发生错误，触发该事件。 | +| callback | ErrorCallback | 是 | 播放错误事件回调方法。 | **示例：** -``` -audioplayer.src = 'file:///data/sounds.mp4'; -audioplayer.on('error', (err) => { - console.info('error callback info: ' + err); +```js +audioPlayer.on('error', (error) => { //设置'error'事件回调 + console.info(`audio error called, errName is ${error.name}`); //打印错误类型名称 + console.info(`audio error called, errCode is ${error.code}`); //打印错误码 + console.info(`audio error called, errMessage is ${error.message}`);//打印错误类型详细描述 }); -audioplayer.setVolume(30000); +audioPlayer.setVolume(3); //设置volume为无效值，触发'error'事件 ``` - ## AudioState -音频播放的状态机。 +音频播放的状态机。可通过state属性获取当前状态。 + +| 名称 | 类型 | 描述 | +| ------------------ | ------ | -------------- | +| idle | string | 音频播放空闲。 | +| playing | string | 音频正在播放。 | +| paused | string | 音频暂停播放。 | +| stopped | string | 音频播放停止。 | +| error8+ | string | 错误状态。 | + +## MediaDescription8+ + +### [key : string] : any + +通过key-value方式获取媒体信息 -| 名称 | 描述 | -| -------- | -------- | -| idle | 音频播放空闲。 | -| playing | 音频正在播放。 | -| paused | 音频暂停播放。 | -| stopped | 音频播放停止。 | +| 名称 | 类型 | 说明 | +| ----- | ------ | ------------------------------------------------------------ | +| key | string | 通过key值获取对应的value。key值具体可见[MediaDescriptionKey](#mediadescriptionkey8)。 | +| value | any | 对应key值得value。其类型可为任意类型，具体key对应value的类型可参考[MediaDescriptionKey](#mediadescriptionkey8)的描述信息。 | + +**示例：** + +```js +function printfItemDescription(obj, key) { + let property = obj[key]; + console.info('audio key is ' + key); + console.info('audio value is ' + property); +} + +audioPlayer.getTrackDescription((error, arrlist) => { + if (typeof (arrlist) != 'undefined') { + for (let i = 0; i < arrlist.length; i++) { + printfItemDescription(arrlist[i], MD_KEY_TRACK_TYPE); //打印出每条轨道MD_KEY_TRACK_TYPE的值 + } + } else { + console.log(`audio getTrackDescription fail, error:${error.message}`); + } +}); +``` ## AudioRecorder