feat(ncm §21): 边下边播阶段1+2——stream_src流式源+decoder双路open_cb+下载线程预缓冲/stall联动+P2 HTTP空闲超时+cache fd写者+stream_sim全矩阵PCM金标准(0真实请求,未部署)

patch_v2/ncm_app/app/play/decoder.h

@@ -8,6 +8,7 @@
 #define NCM_DECODER_H
 
 #include <stdint.h>
+#include "stream_src.h"
 
 #ifdef __cplusplus
 extern "C" {
@@ -15,14 +16,22 @@ extern "C" {
 
 typedef struct ncm_decoder ncm_decoder_t;
 
-/* 打开并探测流参数：rate/ch/bits/total_frames 经指针回填实际值（mp3 恒 16bit；
- * total_frames 0=未知）。返回 0=成功。 */
+/* 在 stream_src 上打开并探测流参数（边下边播/缓存命中统一入口，§21）：
+ * magic 经 stream_src_peek 探测；mp3=mp3dec_ex_open_cb（MP3D_SEEK_TO_BYTE|MP3D_DO_NOT_SCAN，
+ * F3 红线：不带 DO_NOT_SCAN 会全流扫描阻塞到下载结束）；flac=drflac_open 回调模式。
+ * src 由调用方持有（dec_close 不关闭 src）。rate/ch/bits/total_frames 经指针回填
+ * （mp3 恒 16bit；total_frames 0=未知）。返回 0=成功。 */
+int         ncm_dec_open_src(ncm_decoder_t **out, stream_src_t *src,
+                             int *rate, int *ch, int *bits, int64_t *total_frames);
+/* 整文件路径便捷入口：内部建 final=size 的静态 stream_src（dec_close 一并释放）。
+ * 解码同样走 cb 路径（不 mmap 整文件，P1 修复），输出与 ncm_dec_open_src 一致。 */
 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 字节近似（同旧语义）。 */
+/* seek 到 ms。flac=精确 PCM 帧；mp3=按 file_bytes*ms/dur_ms 字节近似（同旧语义）。
+ * 流模式下 seek 目标超已下载区时读端自然阻塞等待（F4），不报错。 */
 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 用）。 */