/**
 * @file hal_audio_player.h
 * @brief 流式 PCM 音频播放器 HAL 接口
 */

#ifndef HAL_AUDIO_PLAYER_H
#define HAL_AUDIO_PLAYER_H

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

#ifdef __cplusplus
extern "C" {
#endif

/** 播放器句柄 */
typedef void *hal_player_handle_t;

/** 播放器事件类型 */
typedef enum {
    HAL_PLAYER_EVENT_STARTED = 0,   /* 开始播放 */
    HAL_PLAYER_EVENT_STOPPED,       /* 停止播放 */
    HAL_PLAYER_EVENT_ERROR,         /* 播放错误 */
    HAL_PLAYER_EVENT_UNDERRUN,      /* 缓冲区欠载 */
} hal_player_event_t;

/** 播放器事件回调 */
typedef void (*hal_player_event_cb_t)(hal_player_event_t event, void *user_ctx);

/** 播放器配置 */
typedef struct {
    uint32_t              sample_rate;      /* 采样率（Hz），如 16000 */
    uint8_t               channels;         /* 声道数（1=单声道，2=立体声）*/
    uint8_t               bits_per_sample;  /* 采样位宽，如 16 */
    hal_player_event_cb_t on_event;         /* 事件回调 */
    void                 *user_ctx;         /* 回调用户上下文 */
} hal_player_config_t;

/**
 * @brief 创建流式播放器
 * @param config 播放器配置
 * @return 句柄，失败返回 NULL
 */
hal_player_handle_t hal_player_create(const hal_player_config_t *config);

/**
 * @brief 准备一次播放会话
 *
 * 平台层可在此写入启动期所需的静音数据。
 * core 层在写入首份真实音频数据前调用。
 */
int hal_player_prepare(hal_player_handle_t handle);

/**
 * @brief 启动播放（写入数据后实际开始出声）
 * @return 0 成功，负值失败
 */
int hal_player_start(hal_player_handle_t handle);

/**
 * @brief 写入 PCM 数据
 * @return 实际写入字节数，负值失败
 */
int hal_player_write(hal_player_handle_t handle, const void *data, size_t len);

/**
 * @brief 停止播放
 * @return 0 成功，负值失败
 */
int hal_player_stop(hal_player_handle_t handle);

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

/**
 * @brief 获取当前音量
 * @return 音量 0-100，负值失败
 */
int hal_player_get_volume(hal_player_handle_t handle);

/** @brief 查询播放器是否已启动 */
bool hal_player_is_started(hal_player_handle_t handle);

/** @brief 获取已缓存待播放数据字节数 */
int hal_player_buffered_size(hal_player_handle_t handle);

/** @brief 销毁播放器 */
void hal_player_destroy(hal_player_handle_t handle);

#ifdef __cplusplus
}
#endif

#endif /* HAL_AUDIO_PLAYER_H */
