/* play/decoder.h — 格式分发解码（REPORT §19）：按文件 magic 选后端。
 *   "fLaC"        → dr_flac（无损 SQ / Hi-Res，vendor/dr_flac.h）
 *   其它（ID3 / 0xFF 帧同步 / 未知）→ minimp3（既有 mp3 路径，未知格式由 minimp3 兜底报错）
 * 输出约定：bits<=16 → 交织 S16；bits>16 → 交织 S32（dr_flac s32 左对齐满幅，送 audiod
 * AUDIO_FMT_S32，AUDIOD_DESIGN.md §4 格式归一由 SDK/audiod 完成，本层不做 SRC/裁剪）。
 */
#ifndef NCM_DECODER_H
#define NCM_DECODER_H

#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

typedef struct ncm_decoder ncm_decoder_t;

/* 打开并探测流参数：rate/ch/bits/total_frames 经指针回填实际值（mp3 恒 16bit；
 * total_frames 0=未知）。返回 0=成功。 */
int         ncm_dec_open(ncm_decoder_t **out, const char *path,
                         int *rate, int *ch, int *bits, int64_t *total_frames);
/* 读最多 cap_frames 帧到 buf（交织，样本位宽=open 返回的 bits；cap 以帧计，
 * buf 容量须 ≥ cap_frames*ch*(bits/8)）。返回实际帧数，0=EOF。 */
int64_t     ncm_dec_read(ncm_decoder_t *d, void *buf, int64_t cap_frames);
/* seek 到 ms。flac=精确 PCM 帧；mp3=按 file_bytes*ms/dur_ms 字节近似（同旧语义）。 */
int         ncm_dec_seek_ms(ncm_decoder_t *d, int64_t ms, int64_t file_bytes, int64_t dur_ms);
void        ncm_dec_close(ncm_decoder_t *d);
/* "mp3" / "flac"（日志/UI 用）。 */
const char *ncm_dec_format(const ncm_decoder_t *d);

#ifdef __cplusplus
}
#endif
#endif /* NCM_DECODER_H */