1# 使用AVPlayer开发音频播放功能 2 3使用AVPlayer可以实现端到端播放原始媒体资源，本开发指导将以完整地播放一首音乐作为示例，向开发者讲解AVPlayer音频播放相关功能。 4 5以下指导仅介绍如何实现媒体资源播放，如果要实现后台播放或熄屏播放，需要使用[AVSession（媒体会话）](avsession-overview.md)和[申请长时任务](../task-management/continuous-task.md)，避免播放被系统强制中断。 6 7 8播放的全流程包含：创建AVPlayer，设置播放资源，设置播放参数（音量/倍速/焦点模式），播放控制（播放/暂停/跳转/停止），重置，销毁资源。 9 10 11在进行应用开发的过程中，开发者可以通过AVPlayer的state属性主动获取当前状态或使用on('stateChange')方法监听状态变化。如果应用在音频播放器处于错误状态时执行操作，系统可能会抛出异常或生成其他未定义的行为。 12 13 14**图1** 播放状态变化示意图 15 16 17状态的详细说明请参考[AVPlayerState](../reference/apis/js-apis-media.md#avplayerstate9)。当播放处于prepared / playing / paused / completed状态时，播放引擎处于工作状态，这需要占用系统较多的运行内存。当客户端暂时不使用播放器时，调用reset()或release()回收内存资源，做好资源利用。 18 19## 开发步骤及注意事项 20 21详细的API说明请参考[AVPlayer API参考](../reference/apis/js-apis-media.md#avplayer9)。 22 231. 创建实例createAVPlayer()，AVPlayer初始化idle状态。 24 252. 设置业务需要的监听事件，搭配全流程场景使用。支持的监听事件包括： 26 | 事件类型 | 说明 | 27 | -------- | -------- | 28 | stateChange | 必要事件，监听播放器的state属性改变。 | 29 | error | 必要事件，监听播放器的错误信息。 | 30 | durationUpdate | 用于进度条，监听进度条长度，刷新资源时长。 | 31 | timeUpdate | 用于进度条，监听进度条当前位置，刷新当前时间。 | 32 | seekDone | 响应API调用，监听seek()请求完成情况。<br/>当使用seek()跳转到指定播放位置后，如果seek操作成功，将上报该事件。 | 33 | speedDone | 响应API调用，监听setSpeed()请求完成情况。<br/>当使用setSpeed()设置播放倍速后，如果setSpeed操作成功，将上报该事件。 | 34 | volumeChange | 响应API调用，监听setVolume()请求完成情况。<br/>当使用setVolume()调节播放音量后，如果setVolume操作成功，将上报该事件。 | 35 | bufferingUpdate | 用于网络播放，监听网络播放缓冲信息，用于上报缓冲百分比以及缓存播放进度。 | 36 | audioInterrupt | 监听音频焦点切换信息，搭配属性audioInterruptMode使用。<br/>如果当前设备存在多个音频正在播放，音频焦点被切换（即播放其他媒体如通话等）时将上报该事件，应用可以及时处理。 | 37 383. 设置资源：设置属性url，AVPlayer进入initialized状态。 39 > **说明：** 40 > 41 > 下面代码示例中的url仅作示意使用，开发者需根据实际情况，确认资源有效性并设置： 42 > 43 > - 如果使用本地资源播放，必须确认资源文件可用，并使用应用沙箱路径访问对应资源，参考[获取应用文件路径](../application-models/application-context-stage.md#获取应用文件路径)。应用沙箱的介绍及如何向应用沙箱推送文件，请参考[文件管理](../file-management/app-sandbox-directory.md)。 44 > 45 > - 如果使用网络播放路径，需[申请相关权限](../security/accesstoken-guidelines.md)：ohos.permission.INTERNET。 46 > 47 > - 如果使用ResourceManager.getRawFd打开HAP资源文件描述符，使用方法可参考[ResourceManager API参考](../reference/apis/js-apis-resource-manager.md#getrawfd9)。 48 > 49 > - 需要使用[支持的播放格式与协议](avplayer-avrecorder-overview.md#支持的格式与协议)。 50 514. 准备播放：调用prepare()，AVPlayer进入prepared状态，此时可以获取duration，设置音量。 52 535. 音频播控：播放play()，暂停pause()，跳转seek()，停止stop() 等操作。 54 556. （可选）更换资源：调用reset()重置资源，AVPlayer重新进入idle状态，允许更换资源url。 56 577. 退出播放：调用release()销毁实例，AVPlayer进入released状态，退出播放。 58 59## 完整示例 60 61参考以下示例，完整地播放一首音乐。 62 63```ts 64import media from '@ohos.multimedia.media'; 65import fs from '@ohos.file.fs'; 66import common from '@ohos.app.ability.common'; 67import { BusinessError } from '@ohos.base'; 68 69export class AVPlayerDemo { 70 private count: number = 0; 71 private isSeek: boolean = true; // 用于区分模式是否支持seek操作 72 private fileSize: number = -1; 73 private fd: number = 0; 74 // 注册avplayer回调函数 75 setAVPlayerCallback(avPlayer: media.AVPlayer) { 76 // seek操作结果回调函数 77 avPlayer.on('seekDone', (seekDoneTime: number) => { 78 console.info(`AVPlayer seek succeeded, seek time is ${seekDoneTime}`); 79 }) 80 // error回调监听函数,当avPlayer在操作过程中出现错误时调用 reset接口触发重置流程 81 avPlayer.on('error', (err: BusinessError) => { 82 console.error(`Invoke avPlayer failed, code is ${err.code}, message is ${err.message}`); 83 avPlayer.reset(); // 调用reset重置资源，触发idle状态 84 }) 85 // 状态机变化回调函数 86 avPlayer.on('stateChange', async (state: string, reason: media.StateChangeReason) => { 87 switch (state) { 88 case 'idle': // 成功调用reset接口后触发该状态机上报 89 console.info('AVPlayer state idle called.'); 90 avPlayer.release(); // 调用release接口销毁实例对象 91 break; 92 case 'initialized': // avplayer 设置播放源后触发该状态上报 93 console.info('AVPlayer state initialized called.'); 94 avPlayer.prepare(); 95 break; 96 case 'prepared': // prepare调用成功后上报该状态机 97 console.info('AVPlayer state prepared called.'); 98 avPlayer.play(); // 调用播放接口开始播放 99 break; 100 case 'playing': // play成功调用后触发该状态机上报 101 console.info('AVPlayer state playing called.'); 102 if (this.count !== 0) { 103 if (this.isSeek) { 104 console.info('AVPlayer start to seek.'); 105 avPlayer.seek(avPlayer.duration); //seek到音频末尾 106 } else { 107 // 当播放模式不支持seek操作时继续播放到结尾 108 console.info('AVPlayer wait to play end.'); 109 } 110 } else { 111 avPlayer.pause(); // 调用暂停接口暂停播放 112 } 113 this.count++; 114 break; 115 case 'paused': // pause成功调用后触发该状态机上报 116 console.info('AVPlayer state paused called.'); 117 avPlayer.play(); // 再次播放接口开始播放 118 break; 119 case 'completed': // 播放结束后触发该状态机上报 120 console.info('AVPlayer state completed called.'); 121 avPlayer.stop(); //调用播放结束接口 122 break; 123 case 'stopped': // stop接口成功调用后触发该状态机上报 124 console.info('AVPlayer state stopped called.'); 125 avPlayer.reset(); // 调用reset接口初始化avplayer状态 126 break; 127 case 'released': 128 console.info('AVPlayer state released called.'); 129 break; 130 default: 131 console.info('AVPlayer state unknown called.'); 132 break; 133 } 134 }) 135 } 136 137 // 以下demo为使用fs文件系统打开沙箱地址获取媒体文件地址并通过url属性进行播放示例 138 async avPlayerUrlDemo() { 139 // 创建avPlayer实例对象 140 let avPlayer: media.AVPlayer = await media.createAVPlayer(); 141 // 创建状态机变化回调函数 142 this.setAVPlayerCallback(avPlayer); 143 let fdPath = 'fd://'; 144 // 通过UIAbilityContext获取沙箱地址filesDir，以Stage模型为例 145 let context = getContext(this) as common.UIAbilityContext; 146 let pathDir = context.filesDir; 147 let path = pathDir + '/01.mp3'; 148 // 打开相应的资源文件地址获取fd，并为url赋值触发initialized状态机上报 149 let file = await fs.open(path); 150 fdPath = fdPath + '' + file.fd; 151 this.isSeek = true; // 支持seek操作 152 avPlayer.url = fdPath; 153 } 154 155 // 以下demo为使用资源管理接口获取打包在HAP内的媒体资源文件并通过fdSrc属性进行播放示例 156 async avPlayerFdSrcDemo() { 157 // 创建avPlayer实例对象 158 let avPlayer: media.AVPlayer = await media.createAVPlayer(); 159 // 创建状态机变化回调函数 160 this.setAVPlayerCallback(avPlayer); 161 // 通过UIAbilityContext的resourceManager成员的getRawFd接口获取媒体资源播放地址 162 // 返回类型为{fd,offset,length},fd为HAP包fd地址，offset为媒体资源偏移量，length为播放长度 163 let context = getContext(this) as common.UIAbilityContext; 164 let fileDescriptor = await context.resourceManager.getRawFd('01.mp3'); 165 let avFileDescriptor: media.AVFileDescriptor = 166 { fd: fileDescriptor.fd, offset: fileDescriptor.offset, length: fileDescriptor.length }; 167 this.isSeek = true; // 支持seek操作 168 // 为fdSrc赋值触发initialized状态机上报 169 avPlayer.fdSrc = avFileDescriptor; 170 } 171 172 // 以下demo为使用fs文件系统打开沙箱地址获取媒体文件地址并通过dataSrc属性进行播放(seek模式)示例 173 async avPlayerDataSrcSeekDemo() { 174 // 创建avPlayer实例对象 175 let avPlayer: media.AVPlayer = await media.createAVPlayer(); 176 // 创建状态机变化回调函数 177 this.setAVPlayerCallback(avPlayer); 178 // dataSrc播放模式的的播放源地址，当播放为Seek模式时fileSize为播放文件的具体大小，下面会对fileSize赋值 179 let src: media.AVDataSrcDescriptor = { 180 fileSize: -1, 181 callback: (buf: ArrayBuffer, length: number, pos: number | undefined) => { 182 let num = 0; 183 if (buf == undefined || length == undefined || pos == undefined) { 184 return -1; 185 } 186 num = fs.readSync(this.fd, buf, { offset: pos, length: length }); 187 if (num > 0 && (this.fileSize >= pos)) { 188 return num; 189 } 190 return -1; 191 } 192 } 193 let context = getContext(this) as common.UIAbilityContext; 194 // 通过UIAbilityContext获取沙箱地址filesDir，以Stage模型为例 195 let pathDir = context.filesDir; 196 let path = pathDir + '/01.mp3'; 197 await fs.open(path).then((file: fs.File) => { 198 this.fd = file.fd; 199 }) 200 // 获取播放文件的大小 201 this.fileSize = fs.statSync(path).size; 202 src.fileSize = this.fileSize; 203 this.isSeek = true; // 支持seek操作 204 avPlayer.dataSrc = src; 205 } 206 207 // 以下demo为使用fs文件系统打开沙箱地址获取媒体文件地址并通过dataSrc属性进行播放(No seek模式)示例 208 async avPlayerDataSrcNoSeekDemo() { 209 // 创建avPlayer实例对象 210 let avPlayer: media.AVPlayer = await media.createAVPlayer(); 211 // 创建状态机变化回调函数 212 this.setAVPlayerCallback(avPlayer); 213 let context = getContext(this) as common.UIAbilityContext; 214 let src: media.AVDataSrcDescriptor = { 215 fileSize: -1, 216 callback: (buf: ArrayBuffer, length: number) => { 217 let num = 0; 218 if (buf == undefined || length == undefined) { 219 return -1; 220 } 221 num = fs.readSync(this.fd, buf); 222 if (num > 0) { 223 return num; 224 } 225 return -1; 226 } 227 } 228 // 通过UIAbilityContext获取沙箱地址filesDir，以Stage模型为例 229 let pathDir = context.filesDir; 230 let path = pathDir + '/01.mp3'; 231 await fs.open(path).then((file: fs.File) => { 232 this.fd = file.fd; 233 }) 234 this.isSeek = false; // 不支持seek操作 235 avPlayer.dataSrc = src; 236 } 237 238 // 以下demo为通过url设置网络地址来实现播放直播码流的demo 239 async avPlayerLiveDemo() { 240 // 创建avPlayer实例对象 241 let avPlayer: media.AVPlayer = await media.createAVPlayer(); 242 // 创建状态机变化回调函数 243 this.setAVPlayerCallback(avPlayer); 244 this.isSeek = false; // 不支持seek操作 245 avPlayer.url = 'http://xxx.xxx.xxx.xxx:xx/xx/index.m3u8'; 246 } 247} 248``` 249
