harmony 鸿蒙使用AVPlayer播放音频(ArkTS)

2025-06-12
浏览 (3)

使用AVPlayer播放音频(ArkTS)

使用AVPlayer可以实现端到端播放原始媒体资源，本开发指导将以完整地播放一首音乐作为示例，向开发者讲解AVPlayer音频播放相关功能。如需播放PCM音频数据，请使用AudioRenderer。

播放的全流程包含：创建AVPlayer，设置播放资源，设置播放参数（音量/倍速/焦点模式），播放控制（播放/暂停/跳转/停止），重置，销毁资源。

在应用开发的过程中，开发者可以通过AVPlayer的state属性主动获取当前状态，或使用on(‘stateChange’)方法监听状态变化。如果应用在音频播放器处于错误状态时执行操作，系统可能会抛出异常或产生其他未定义的行为。

图1 播放状态变化示意图 Playback status change

状态的详细说明请参考AVPlayerState。当播放处于prepared / playing / paused / completed状态时，播放引擎处于工作状态，这需要占用系统大量的运行内存。当客户端暂时不使用播放器时，调用reset()或release()回收内存资源，做好资源利用。

开发建议

当前指导仅介绍如何实现媒体资源播放，在应用开发过程中，涉及后台播放、播放冲突等情况时，请根据实际需要参考以下说明。

若要实现后台播放或熄屏播放，需要接入AVSession（媒体会话）和申请长时任务，避免播放被系统强制中断。
应用在播放过程中，若播放的媒体数据涉及音频，根据系统音频管理策略（参考处理音频焦点事件），可能会被其他应用打断，建议应用主动监听音频打断事件，根据内容提示做出相应处理，避免出现应用状态与预期效果不一致的问题。
面对设备同时连接多个音频输出设备的情况，应用可以通过on(‘audioOutputDeviceChangeWithInfo’)监听音频输出设备的变化，做出相应处理。
若要访问在线媒体资源，需要申请 ohos.permission.INTERNET 权限。

开发步骤及注意事项

详细的API说明请参考AVPlayer API参考。

创建实例createAVPlayer()，AVPlayer初始化idle状态。
设置业务需要的监听事件，搭配全流程场景使用。支持的监听事件包括：

设置资源：设置属性url，AVPlayer进入initialized状态。 > 说明： > > 下面代码示例中的url仅作示意使用，开发者需根据实际情况，确认资源有效性并设置： > > - 如果使用本地资源播放，必须确认资源文件可用，并使用应用沙箱路径访问对应资源，参考获取应用文件路径。应用沙箱的介绍及如何向应用沙箱推送文件，请参考文件管理。 > > - 如果使用网络播放路径，需声明权限：ohos.permission.INTERNET。 > > - 如果使用ResourceManager.getRawFd打开HAP资源文件描述符，使用方法可参考ResourceManager API参考。 > > - 需要使用支持的播放格式与协议。 > > 此外，如果需要设置音频渲染信息，则只允许在initialized状态下，第一次调用prepare()之前设置，以便音频渲染器信息在之后生效。若媒体源包含视频，则usage默认值为STREAM_USAGE_MOVIE，否则usage默认值为STREAM_USAGE_MUSIC。rendererFlags默认值为0。为了确保音频行为符合使用预期，建议根据具体业务场景和实际需求，主动配置audio.AudioRendererInfo，为音频选择恰当的流类型usage。
准备播放：调用prepare()，AVPlayer进入prepared状态，此时可以获取duration，设置音量。
音频播控：播放play()，暂停pause()，跳转seek()，停止stop() 等操作。
（可选）更换资源：调用reset()重置资源，AVPlayer重新进入idle状态，允许更换资源url。
退出播放：调用release()销毁实例，AVPlayer进入released状态，退出播放。

运行完整示例

参考以下示例，完整地播放一首音乐，实现起播后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 （音频资源）
编译新建工程并运行。