HarmonyOS AVPlayer 音频播放器

鸿蒙文档中心：使用AVPlayer播放视频(ArkTS)文档中心https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/video-playback

这张图描述的是 HarmonyOS AVPlayer 音频播放器的状态流转过程，展示了 AVPlayer 在不同状态之间的切换条件和关键操作。

1. 核心状态说明

图中展示了 AVPlayer 的 7 个核心状态：

1. idle（空闲） ：初始状态或调用 reset() 后的状态。
2. initialized（初始化） ：设置播放源（如 fdSrc 或 url）后的状态。
3. prepared（准备完成） ：调用 prepare() 成功后的状态。
4. playing（播放中） ：调用 play() 后的状态。
5. paused（暂停） ：调用 pause() 后的状态。
6. completed（播放完成）：音频自然播放结束后的状态。
7. stopped（停止） ：调用 stop() 后的状态。

---

2. 状态流转详细过程

(1) idle → initialized

• 触发条件 ：调用 AVPlayer.create() 创建播放器后，设置播放源（如 fdSrc 或 url）。

关键操作：

const avPlayer = await media.createAVPlayer(); // 创建播放器（进入 idle）
avPlayer.fdSrc = { fd, offset, length };      // 设置播放源（进入 initialized）

(2) initialized → prepared

• 触发条件 ：调用 prepare() 方法。

关键操作：

• typescript复制下载avPlayer.prepare(); // 准备播放（进入 prepared）
• 备注：此时播放器已加载音频元数据（如时长），但还未开始播放。

(3) prepared → playing

• 触发条件 ：调用 play() 方法。

关键操作：

• typescript复制下载avPlayer.play(); // 开始播放（进入 playing）
• 备注 ：此时音频开始播放，timeUpdate 回调会持续更新进度。

(4) playing ↔ paused

• 双向切换：

playing → paused ：调用 pause()。

• • typescript复制下载avPlayer.pause(); // 暂停播放（进入 paused）

paused → playing ：再次调用 play()。

• • typescript复制下载avPlayer.play(); // 恢复播放（回到 playing）

(5) playing → completed

• 触发条件：音频自然播放结束（无需手动调用）。
• 关键行为：

• • 播放器自动进入 completed 状态。
  • 触发 stateChange 回调，通知应用播放结束。

(6) completed → playing

• 触发条件 ：调用 seek(0) + play()（如代码中的逻辑）。

关键操作

avPlayer.seek(0);    // 跳转到开头
avPlayer.play();     // 重新播放（回到 playing）

(7) 任何状态 → stopped

• 触发条件 ：调用 stop() 方法。

关键操作：

• typescript复制下载avPlayer.stop(); // 停止播放（进入 stopped）
• 备注 ：停止后需调用 reset() 或 release() 清理资源。

(8) stopped → idle

• 触发条件 ：调用 reset() 方法。

关键操作：

• typescript复制下载avPlayer.reset(); // 重置播放器（回到 idle）
• 备注 ：此时可以重新设置播放源（fdSrc），开启新一轮播放。

(9) 终止状态：released

• 触发条件 ：调用 release() 方法。

关键操作：

• typescript复制下载avPlayer.release(); // 释放播放器资源（不可逆）
• 备注：释放后播放器不可再用，需重新创建实例。

---

3. 关键注意事项

1. 错误处理：

• • 任何状态都可能因错误跳转到 error 状态，需监听 on('error') 回调。
  • 典型处理方式是调用 reset() 回到 idle 状态。

1. 进度控制：

• • seek() 只能在 playing、paused 或 completed 状态下调用。
  • 调用 seek() 后会触发 seekDone 回调。

1. 资源释放：

• • 页面退出时（aboutToDisappear）必须调用 release()，避免内存泄漏。

1. 状态检查：

• • 调用任何方法前应检查当前状态（如 avPlayer.state），避免非法操作。

---

总结

这张图清晰地描述了 AVPlayer 的生命周期 和状态驱动模型，开发者需要：

1. 按顺序操作 （如先 prepare() 再 play()）。
2. 处理边界情况（如播放完成后的恢复）。
3. 及时释放资源（避免内存泄漏）。

通过这张图，可以更好地理解代码中 avPlayer 的行为逻辑，确保播放功能稳定可靠。