/**
 * @file hal_local_player.h
 * @brief 本地音频文件播放器 HAL 接口
 */

#ifndef HAL_LOCAL_PLAYER_H
#define HAL_LOCAL_PLAYER_H

#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>

#ifdef __cplusplus
extern "C" {
#endif

/** 本地播放器句柄 */
typedef void *hal_local_player_handle_t;

/** 播放完成回调 */
typedef void (*hal_local_player_done_cb_t)(void *user_ctx);

/** @brief 创建本地播放器 */
hal_local_player_handle_t hal_local_player_create(void);

/**
 * @brief 播放本地音频文件
 * @param file_path 音频文件路径
 * @param done_cb   播放完成回调（可为 NULL）
 * @param user_ctx  回调用户上下文
 * @return 0 成功，负值失败
 */
int hal_local_player_play(hal_local_player_handle_t handle,
                          const char *file_path,
                          hal_local_player_done_cb_t done_cb,
                          void *user_ctx);

/** @brief 停止播放 */
int hal_local_player_stop(hal_local_player_handle_t handle);

/**
 * @brief 设置音量
 * @param volume 音量 0-100
 */
int hal_local_player_set_volume(hal_local_player_handle_t handle, uint8_t volume);

/** @brief 销毁本地播放器 */
void hal_local_player_destroy(hal_local_player_handle_t handle);

#ifdef __cplusplus
}
#endif

#endif /* HAL_LOCAL_PLAYER_H */
