!1216 更新js-apis-media.md和audio-playback.md

Merge pull request !1216 from 马靖涛/apis.md

zh-cn/application-dev/media/audio-playback.md

 # 音频播放开发指导
 
-- [场景介绍](#场景介绍)
-- [接口说明](#接口说明)
-
 ## 场景介绍
 
 音频播放的主要工作是将音频数据转码为可听见的音频模拟信号并通过输出设备进行播放，同时对播放任务进行管理。
 
 **图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()<sup>7+</sup> | 重置播放音频源。 | 
-| setVolume(vol:&nbsp;number) | 改变音频播放音量 | 
-| seek(timeMs:&nbsp;number) | 改变播放位置。 | 
-| src:string | 音频播放的媒体URI。 | 
-| state:AudioState | 播放的状态属性。 | 
-| currentTime:number | 音频的当前播放位置。 | 
-| duration:number | 音频播放的时长(当数据源不支持改变播放位置时返回-1, 比如实时流媒体场景)。 | 
-| loop:boolean | 音频的循环播放属性。 | 
-| on('play',&nbsp;function&nbsp;callback) | 订阅音频播放开始事件。 | 
-| on('pause',&nbsp;function&nbsp;callback) | 订阅音频播放暂停事件。 | 
-| on('stop',&nbsp;function&nbsp;callback) | 订阅音频播放停止事件。 | 
-| on('reset',&nbsp;function&nbsp;callback) | 订阅音频播放重置事件。 | 
-| on('finish',function&nbsp;callback) | 订阅音频播放结束事件。 | 
-| on('error',&nbsp;function&nbsp;callback) | 订阅音频播放错误事件。 | 
-| on('dataload',&nbsp;function&nbsp;callback) | 订阅音频播放加载数据事件。 | 
-| on('volumeChange',&nbsp;function&nbsp;callback) | 订阅音频播放音量变化事件。 | 
-| on('timeUpdate',&nbsp;function&nbsp;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