)
使用AVPlayer播放音频(ArkTS)使用AVPlayer可以实现端到端播放原始媒体资源本开发指导将以完整播放一首音乐作为示例向开发者讲解AVPlayer音频播放相关功能。如需播放PCM音频数据请使用AudioRenderer。播放的全流程包含创建AVPlayer设置播放资源设置播放参数音量/倍速/焦点模式播放控制播放/暂停/跳转/停止重置销毁资源。在应用开发的过程中开发者可以通过AVPlayer的state属性主动获取当前状态或使用on(‘stateChange’)方法监听状态变化。如果应用在音频播放器处于错误状态时执行操作系统可能会抛出异常或产生其他未定义的行为。状态的详细说明请参考AVPlayerState。当播放处于prepared / playing / paused / completed状态时播放引擎处于工作状态这需要占用系统大量的运行内存。当客户端暂时不使用播放器时调用reset()或release()回收内存资源做好资源利用。开发建议当前指导仅介绍如何实现媒体资源播放在应用开发过程中涉及后台播放、播放冲突等情况时请根据实际需要参考以下说明。若要实现后台播放或熄屏播放需要接入AVSession媒体会话和申请长时任务避免播放被系统强制中断。应用在播放过程中若播放的媒体数据涉及音频根据系统音频管理策略参考处理音频焦点事件可能会被其他应用打断建议应用主动监听音频打断事件根据内容提示做出相应处理避免出现应用状态与预期效果不一致的问题。面对设备同时连接多个音频输出设备的情况应用可以通过on(‘audioOutputDeviceChangeWithInfo’)监听音频输出设备的变化做出相应处理。若要访问在线媒体资源需要申请 ohos.permission.INTERNET 权限。若要切换听筒/扬声器应用可以参考音频输出设备路由切换。开发步骤及注意事项详细的API说明请参考AVPlayer。创建实例createAVPlayer()AVPlayer初始化idle状态。import{media}fromkit.MediaKit;// 创建avPlayer实例对象。letavPlayerawaitmedia.createAVPlayer();设置业务需要的监听事件搭配全流程场景使用。支持的监听事件包括事件类型说明stateChange必要事件监听播放器的state属性改变。需要播放器在idle状态下、未调用设置资源接口前完成设置监听若在调用设置资源接口后再设置监听可能导致无法收到资源设置过程中上报的stateChange事件。error必要事件监听播放器的错误信息。需要播放器在idle状态下、未调用设置资源接口前完成设置监听若在调用设置资源接口后再设置监听可能导致无法收到资源设置过程中上报的error事件。durationUpdate用于进度条监听进度条长度刷新资源时长。timeUpdate用于进度条监听进度条当前位置刷新当前时间。seekDone响应API调用监听seek()请求完成情况。当使用seek()跳转到指定播放位置后如果seek操作成功将上报该事件。speedDone响应API调用监听setSpeed()请求完成情况。当使用setSpeed()设置播放倍速后如果setSpeed操作成功将上报该事件。volumeChange响应API调用监听setVolume()请求完成情况。当使用setVolume()调节播放音量后如果setVolume操作成功将上报该事件。bufferingUpdate用于网络播放监听网络播放缓冲信息用于上报缓冲百分比以及缓存播放进度。audioInterrupt监听音频焦点切换信息搭配属性audioInterruptMode使用。如果当前设备存在多个音频正在播放音频焦点被切换即播放其他媒体如通话等时将上报该事件应用可以及时处理。// 此处仅为示例开发者根据需要设置合适的监听事件。import{BusinessError}fromkit.BasicServicesKit;import{audio}fromkit.AudioKit;avPlayer.on(stateChange,async(state:string,reason:media.StateChangeReason){// 开发者根据需要写入业务逻辑。});avPlayer.on(error,(error:BusinessError){// 开发者根据需要写入业务逻辑。});avPlayer.on(durationUpdate,(duration:number){// 开发者根据需要写入业务逻辑。});avPlayer.on(timeUpdate,(time:number){// 开发者根据需要写入业务逻辑。});avPlayer.on(seekDone,(seekDoneTime:number){// 开发者根据需要写入业务逻辑。});avPlayer.on(speedDone,(speed:number){// 开发者根据需要写入业务逻辑。});avPlayer.on(volumeChange,(vol:number){// 开发者根据需要写入业务逻辑。});avPlayer.on(bufferingUpdate,(infoType:media.BufferingInfoType,value:number){// 开发者根据需要写入业务逻辑。});avPlayer.on(audioInterrupt,(info:audio.InterruptEvent){// 开发者根据需要写入业务逻辑。});设置资源设置属性urlAVPlayer进入initialized状态。说明下面代码示例中的url仅作示意使用开发者需根据实际情况确认资源有效性并设置如果使用本地资源播放必须确认资源文件可用并使用应用沙箱路径访问对应资源参考获取应用文件路径。应用沙箱的介绍及如何向应用沙箱推送文件请参考文件管理。如果使用网络播放路径需声明权限ohos.permission.INTERNET。可以使用ResourceManager.getRawFd打开HAP资源文件描述符。需要使用支持的播放格式与协议。示例一播放网络媒体资源leturlhttps://abc.bcd.example.mp3;// 此处仅为示意请替换为真实资源文件URL。if(avPlayernull){return;}avPlayer.urlurl;示例二应用沙箱文件播放letfdPathfd://;// 此处仅为示意请替换为真实资源文件URL。letpath:string${this.context.filesDir}/${this.fileName};// 此处仅为示意请替换为真实资源文件URL。letfileawaitfs.open(path);fdPathfdPathfile.fd;this.avPlayerawaitmedia.createAVPlayer();this.avPlayer.urlurl;可选设置音频渲染只允许在initialized状态下第一次调用prepare()之前设置以便音频渲染器信息在之后生效。若媒体源包含视频则usage默认值为STREAM_USAGE_MOVIE否则usage默认值为STREAM_USAGE_MUSIC。rendererFlags默认值为0。为了确保音频行为符合使用预期建议根据具体业务场景和实际需求主动配置audio.AudioRendererInfo为音频选择恰当的流类型usage。import{audio}fromkit.AudioKit;avPlayer.audioRendererInfo{usage:audio.StreamUsage.STREAM_USAGE_MOVIE,rendererFlags:0}准备播放调用 prepare()方法进入准备播放阶段AVPlayer 将切换至 prepared 状态此时可获取视频时长duration并调整音量参数。import{BusinessError}fromkit.BasicServicesKit;avPlayer.prepare((err:BusinessError){if(err){console.error(Failed to prepare,error message is :err.message);}else{console.info(Succeeded in preparing);}});音频播控播放play()、暂停pause()、跳转seek()、停止stop() 等操作。说明在API version 23及之后版本中播放音频时会跳过静音帧。import{BusinessError}fromkit.BasicServicesKit;// 播放操作。avPlayer.play().then((){console.info(Succeeded in playing);},(err:BusinessError){console.error(Failed to play,error message is :err.message);});// 暂停操作。avPlayer.pause((err:BusinessError){if(err){console.error(Failed to pause,error message is :err.message);}else{console.info(Succeeded in pausing);}});// 跳转操作。letseekTime:number1000;avPlayer.seek(seekTime,media.SeekMode.SEEK_PREV_SYNC);// 停止操作。avPlayer.stop((err:BusinessError){if(err){console.error(Failed to stop,error message is :err.message);}else{console.info(Succeeded in stopping);}});可选更换资源调用reset()方法重置播放资源AVPlayer重新进入idle状态此时可重新设置资源url。import{BusinessError}fromkit.BasicServicesKit;awaitavPlayer.reset((err:BusinessError){avPlayer.urlurl;if(err){console.error(Failed to reset,error message is :err.message);}else{console.info(Succeeded in resetting);}});// 更换url。leturlhttps://xxx.xxx.xxx.mp3;if(avPlayernull){return;}avPlayer.urlurl;退出播放调用release()销毁实例AVPlayer进入released状态退出播放。import{BusinessError}fromkit.BasicServicesKit;avPlayer.release((err:BusinessError){if(err){console.error(Failed to release,error message is :err.message);}else{console.info(Succeeded in releasing);}});运行完整示例参考以下示例完整地播放一首音乐实现起播后3s暂停暂停3s重新播放的效果。新建工程下载示例工程并将示例工程的以下资源复制到对应目录。AVPlayerArkTSAudio entry/src/main/ets/ └── pages └── Index.ets (播放界面) entry/src/main/resources/ ├── base │ ├── element │ │ ├── color.json │ │ ├── float.json │ │ └── string.json │ └── media │ ├── ic_video_play.svg (播放键图片资源) │ └── ic_video_pause.svg (暂停键图片资源) └── rawfile └── test_01.mp3 音频资源编译新建工程并运行。 
长河君 · 2026/8/7 2:39:57 · 阅读 1.2k HarmonyOS 应用开发《掌上英语》第100篇：使用AVPlayer播放音频(ArkTS)
使用AVPlayer播放音频(ArkTS)使用AVPlayer可以实现端到端播放原始媒体资源本开发指导将以完整播放一首音乐作为示例向开发者讲解AVPlayer音频播放相关功能。如需播放PCM音频数据请使用AudioRenderer。播放的全流程包含创建AVPlayer设置播放资源设置播放参数音量/倍速/焦点模式播放控制播放/暂停/跳转/停止重置销毁资源。在应用开发的过程中开发者可以通过AVPlayer的state属性主动获取当前状态或使用on(‘stateChange’)方法监听状态变化。如果应用在音频播放器处于错误状态时执行操作系统可能会抛出异常或产生其他未定义的行为。状态的详细说明请参考AVPlayerState。当播放处于prepared / playing / paused / completed状态时播放引擎处于工作状态这需要占用系统大量的运行内存。当客户端暂时不使用播放器时调用reset()或release()回收内存资源做好资源利用。开发建议当前指导仅介绍如何实现媒体资源播放在应用开发过程中涉及后台播放、播放冲突等情况时请根据实际需要参考以下说明。若要实现后台播放或熄屏播放需要接入AVSession媒体会话和申请长时任务避免播放被系统强制中断。应用在播放过程中若播放的媒体数据涉及音频根据系统音频管理策略参考处理音频焦点事件可能会被其他应用打断建议应用主动监听音频打断事件根据内容提示做出相应处理避免出现应用状态与预期效果不一致的问题。面对设备同时连接多个音频输出设备的情况应用可以通过on(‘audioOutputDeviceChangeWithInfo’)监听音频输出设备的变化做出相应处理。若要访问在线媒体资源需要申请 ohos.permission.INTERNET 权限。若要切换听筒/扬声器应用可以参考音频输出设备路由切换。开发步骤及注意事项详细的API说明请参考AVPlayer。创建实例createAVPlayer()AVPlayer初始化idle状态。import{media}fromkit.MediaKit;// 创建avPlayer实例对象。letavPlayerawaitmedia.createAVPlayer();设置业务需要的监听事件搭配全流程场景使用。支持的监听事件包括事件类型说明stateChange必要事件监听播放器的state属性改变。需要播放器在idle状态下、未调用设置资源接口前完成设置监听若在调用设置资源接口后再设置监听可能导致无法收到资源设置过程中上报的stateChange事件。error必要事件监听播放器的错误信息。需要播放器在idle状态下、未调用设置资源接口前完成设置监听若在调用设置资源接口后再设置监听可能导致无法收到资源设置过程中上报的error事件。durationUpdate用于进度条监听进度条长度刷新资源时长。timeUpdate用于进度条监听进度条当前位置刷新当前时间。seekDone响应API调用监听seek()请求完成情况。当使用seek()跳转到指定播放位置后如果seek操作成功将上报该事件。speedDone响应API调用监听setSpeed()请求完成情况。当使用setSpeed()设置播放倍速后如果setSpeed操作成功将上报该事件。volumeChange响应API调用监听setVolume()请求完成情况。当使用setVolume()调节播放音量后如果setVolume操作成功将上报该事件。bufferingUpdate用于网络播放监听网络播放缓冲信息用于上报缓冲百分比以及缓存播放进度。audioInterrupt监听音频焦点切换信息搭配属性audioInterruptMode使用。如果当前设备存在多个音频正在播放音频焦点被切换即播放其他媒体如通话等时将上报该事件应用可以及时处理。// 此处仅为示例开发者根据需要设置合适的监听事件。import{BusinessError}fromkit.BasicServicesKit;import{audio}fromkit.AudioKit;avPlayer.on(stateChange,async(state:string,reason:media.StateChangeReason){// 开发者根据需要写入业务逻辑。});avPlayer.on(error,(error:BusinessError){// 开发者根据需要写入业务逻辑。});avPlayer.on(durationUpdate,(duration:number){// 开发者根据需要写入业务逻辑。});avPlayer.on(timeUpdate,(time:number){// 开发者根据需要写入业务逻辑。});avPlayer.on(seekDone,(seekDoneTime:number){// 开发者根据需要写入业务逻辑。});avPlayer.on(speedDone,(speed:number){// 开发者根据需要写入业务逻辑。});avPlayer.on(volumeChange,(vol:number){// 开发者根据需要写入业务逻辑。});avPlayer.on(bufferingUpdate,(infoType:media.BufferingInfoType,value:number){// 开发者根据需要写入业务逻辑。});avPlayer.on(audioInterrupt,(info:audio.InterruptEvent){// 开发者根据需要写入业务逻辑。});设置资源设置属性urlAVPlayer进入initialized状态。说明下面代码示例中的url仅作示意使用开发者需根据实际情况确认资源有效性并设置如果使用本地资源播放必须确认资源文件可用并使用应用沙箱路径访问对应资源参考获取应用文件路径。应用沙箱的介绍及如何向应用沙箱推送文件请参考文件管理。如果使用网络播放路径需声明权限ohos.permission.INTERNET。可以使用ResourceManager.getRawFd打开HAP资源文件描述符。需要使用支持的播放格式与协议。示例一播放网络媒体资源leturlhttps://abc.bcd.example.mp3;// 此处仅为示意请替换为真实资源文件URL。if(avPlayernull){return;}avPlayer.urlurl;示例二应用沙箱文件播放letfdPathfd://;// 此处仅为示意请替换为真实资源文件URL。letpath:string${this.context.filesDir}/${this.fileName};// 此处仅为示意请替换为真实资源文件URL。letfileawaitfs.open(path);fdPathfdPathfile.fd;this.avPlayerawaitmedia.createAVPlayer();this.avPlayer.urlurl;可选设置音频渲染只允许在initialized状态下第一次调用prepare()之前设置以便音频渲染器信息在之后生效。若媒体源包含视频则usage默认值为STREAM_USAGE_MOVIE否则usage默认值为STREAM_USAGE_MUSIC。rendererFlags默认值为0。为了确保音频行为符合使用预期建议根据具体业务场景和实际需求主动配置audio.AudioRendererInfo为音频选择恰当的流类型usage。import{audio}fromkit.AudioKit;avPlayer.audioRendererInfo{usage:audio.StreamUsage.STREAM_USAGE_MOVIE,rendererFlags:0}准备播放调用 prepare()方法进入准备播放阶段AVPlayer 将切换至 prepared 状态此时可获取视频时长duration并调整音量参数。import{BusinessError}fromkit.BasicServicesKit;avPlayer.prepare((err:BusinessError){if(err){console.error(Failed to prepare,error message is :err.message);}else{console.info(Succeeded in preparing);}});音频播控播放play()、暂停pause()、跳转seek()、停止stop() 等操作。说明在API version 23及之后版本中播放音频时会跳过静音帧。import{BusinessError}fromkit.BasicServicesKit;// 播放操作。avPlayer.play().then((){console.info(Succeeded in playing);},(err:BusinessError){console.error(Failed to play,error message is :err.message);});// 暂停操作。avPlayer.pause((err:BusinessError){if(err){console.error(Failed to pause,error message is :err.message);}else{console.info(Succeeded in pausing);}});// 跳转操作。letseekTime:number1000;avPlayer.seek(seekTime,media.SeekMode.SEEK_PREV_SYNC);// 停止操作。avPlayer.stop((err:BusinessError){if(err){console.error(Failed to stop,error message is :err.message);}else{console.info(Succeeded in stopping);}});可选更换资源调用reset()方法重置播放资源AVPlayer重新进入idle状态此时可重新设置资源url。import{BusinessError}fromkit.BasicServicesKit;awaitavPlayer.reset((err:BusinessError){avPlayer.urlurl;if(err){console.error(Failed to reset,error message is :err.message);}else{console.info(Succeeded in resetting);}});// 更换url。leturlhttps://xxx.xxx.xxx.mp3;if(avPlayernull){return;}avPlayer.urlurl;退出播放调用release()销毁实例AVPlayer进入released状态退出播放。import{BusinessError}fromkit.BasicServicesKit;avPlayer.release((err:BusinessError){if(err){console.error(Failed to release,error message is :err.message);}else{console.info(Succeeded in releasing);}});运行完整示例参考以下示例完整地播放一首音乐实现起播后3s暂停暂停3s重新播放的效果。新建工程下载示例工程并将示例工程的以下资源复制到对应目录。AVPlayerArkTSAudio entry/src/main/ets/ └── pages └── Index.ets (播放界面) entry/src/main/resources/ ├── base │ ├── element │ │ ├── color.json │ │ ├── float.json │ │ └── string.json │ └── media │ ├── ic_video_play.svg (播放键图片资源) │ └── ic_video_pause.svg (暂停键图片资源) └── rawfile └── test_01.mp3 音频资源编译新建工程并运行。