错误处理

播放器使用 PlayerError 统一描述错误，并通过事件抛出。核心关注点是 是否致命 与 错误来源。

PlayerError 结构

import { PlayerError, PLAYER_ERROR_CODES } from '@iunify/player'

// PlayerError {
//   code: PlayerErrorCode
//   fatal: boolean
//   source: 'engine' | 'media' | 'core'
//   cause?: unknown
// }

常见错误码（PLAYER_ERROR_CODES）：

• engine_network：引擎网络错误
• engine_media：引擎媒体错误
• engine_decode：引擎解码错误
• engine_format：引擎格式错误
• engine_unknown：引擎未知错误
• engine_attach_failed：引擎附加失败
• engine_not_found：没有可用引擎
• media_error：浏览器媒体错误
• core_error：核心错误

事件区别

• error：所有错误都会触发。
• engine-error：仅当引擎报告错误时触发。
• fatal-error：fatal === true 时触发，通常需要中断播放或切换备用源。
• engine-attach-failed：某个引擎在 setSource 过程中 attach 失败（随后会尝试下一个）。

推荐处理策略

player.on('fatal-error', (err: PlayerError) => {
  showToast(`播放失败：${err.message}`)
  // 例如：切换备用源或提示刷新
})

player.on('engine-error', (err: PlayerError) => {
  console.warn('Engine error', err.code, err.cause)
})

player.on('error', (err: PlayerError) => {
  // 记录日志或上报
})

与切源配合

• 监听 sourcechange-failed 判断所有引擎均失败，可提示“切换清晰度”或“刷新”。
• engine_not_found 通常是 URL 不支持或格式识别失败；建议改用其他格式。

UI 建议

• 对致命错误显示明显提示，并提供“重试 / 切源”按钮。
• 将错误信息写入日志面板，便于排查（示例见 Demo）。