diff --git a/zh-cn/application-dev/media/audio-playback.md b/zh-cn/application-dev/media/audio-playback.md index 2afa827c57fc2cc9703c7c8c3ac8ffb6ad54b26d..7a6ddcb0b002c32a49eb034f70cf56efa9ddf84e 100644 --- a/zh-cn/application-dev/media/audio-playback.md +++ b/zh-cn/application-dev/media/audio-playback.md @@ -1,131 +1,151 @@ # 音频播放开发指导 -- [场景介绍](#场景介绍) -- [接口说明](#接口说明) - ## 场景介绍 音频播放的主要工作是将音频数据转码为可听见的音频模拟信号并通过输出设备进行播放，同时对播放任务进行管理。 -**图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.'); + + +![](https://gitee.com/openharmony/docs/raw/master/zh-cn/application-dev/media/figures/zh-cn_image_20220117.png) + +​ **图1** 音频播放状态机 + + + +## 音频播放demo示例 + +### 全流程场景 + +```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); + } +} + +let audioPlayer = media.createAudioPlayer(); //创建一个音频播放实例 +SetCallBack(audioPlayer); //设置事件回调 +/* 用户选择音频，设置uri */ +audioPlayer.src = 'file:///data/data/ohos.xxx.xxx/files/test.mp3'; //设置src属性，并触发'dataLoad'事件回调 +/* + * 用户主动下发命令： + * play、seek、setVolume、pause、getTrackDescription、stop + */ +audioPlayer.play(); //需等待'dataLoad'事件回调完成后，才可调用play进行播放，触发'play'事件回调 +audioPlayer.seek(30000); //触发'timeUpdate'事件回调，seek到30000ms处播放 +audioPlayer.setVolume(0.5); //触发'volumeChange'事件回调 +audioPlayer.pause(); //触发'pause'事件回调，暂停播放 +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}`); + } +}); +audioPlayer.stop(); //触发'stop'事件回调 +/* + * 用户切歌的方式： + * 1、调用reset方法后，重新设置src后play + */ +audioPlayer.reset(); //触发'reset'事件回调后，重新设置src属性，可完成切歌 +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'; +```