feat(ncm): 网易云客户端 v1 UI+播放链路 (agent-205) — os.meow.ncm: 登录页(真实unikey二维码+轮询状态机)/我的歌单(listview)/歌单详情/播放页(封面+seek+滚动歌词+竖横屏切换)/设置(音质默认Hi-res+缓存上限默认10G); 播放线程(缓存LRU+minimp3→ALSA UAPI直开hw:0,0); 媒体会话MSG_META上报+PLAYCTL接收(首真实媒体源)

ncm 1e331964 (text 764KB); 0 warning; 宿主离屏6页截图目检+真实QR可扫+qemu-mipsel干净启动+解码446xRT
真机待联调: ALSA时序/803扫码闭环/媒体会话联动/gbk大字库渲染

patch_v2/ncm_app/app/play/audio_out.c

@@ -0,0 +1,166 @@
+/* play/audio_out.c — 音频输出抽象：ALSA 直开 hw:0,0（44.1k/16bit/立体声）或 FILE/NULL sink。
+ *
+ * 设备（mipsel musl 无 libasound）：用 ALSA 内核 UAPI（sound/asound.h）直开 /dev/snd/pcmC0D0p，
+ * 非 mmap RW 模式下 ioctl 设 hw_params + write() 写交织帧。布局/时序真机待验证（本层只保证跨编译 +
+ *  宿主回退正确）。
+ * 宿主/qemu 验证：无 /dev/snd/pcmC0D0p → 回退 FILE sink（写 WAV，env NCM_AUDIO_OUT 指定路径，
+ *  缺省 /tmp/ncm_out.wav）或 NULL（env NCM_AUDIO_SINK=null，丢弃，仅测解码 RT 用）。
+ * 线程模型：仅由 player_manager 播放线程调用（单写者）；audio_out_close 可被 UI 线程调用打断阻塞写。
+ */
+#include "../ncm_app_internal.h"
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <fcntl.h>
+#include <unistd.h>
+#include <errno.h>
+
+#ifdef __linux__
+#include <sound/asound.h>
+#include <sys/ioctl.h>
+#define NCM_HAVE_ALSA 1
+#endif
+
+enum { SINK_ALSADEV = 0, SINK_FILE = 1, SINK_NULL = 2 };
+static int  g_sink = -1;
+static int  g_fd = -1;             /* alsa or file fd */
+static int  g_rate, g_ch, g_bits;
+static const char *g_path = NULL;
+
+#define NCM_DEFAULT_OUT "/tmp/ncm_out.wav"
+
+void audio_out_set_target(int ms) { (void)ms; }
+int  audio_out_buffered_ms(void) { return 0; }
+
+#ifdef NCM_HAVE_ALSA
+/* ALSA 非 mmap 直装：开设备 → hw_params（access=rw_interleaved, S16_LE, rate, 2ch, s16）→ write。
+ * 注意：musl 的 sound/asound.h 中 masks/intervals 是**重索引**数组：
+ *   masks[k]       ↔ hw_param (FIRST_MASK + k)；  intervals[k] ↔ hw_param (FIRST_INTERVAL + k)。
+ * 故访问时须减 FIRST_MASK/FIRST_INTERVAL，否则越界/错位。 */
+static void pmask(struct snd_mask *m, unsigned bit) { m->bits[bit / 32] |= 1u << (bit % 32); }
+static void pivset(struct snd_interval *iv, unsigned val)
+{
+    iv->min = iv->max = val;
+    iv->integer = 1;
+    iv->openmin = iv->openmax = 0;
+    iv->empty = 0;
+}
+static int alsa_open(int rate, int ch, int bits)
+{
+    if (bits != 16) return -1;
+    int fd = open("/dev/snd/pcmC0D0p", O_RDWR);
+    if (fd < 0) return -1;
+    struct snd_pcm_hw_params p;
+    memset(&p, 0, sizeof p);
+    p.flags = 0;
+    pmask(&p.masks[SNDRV_PCM_HW_PARAM_ACCESS - SNDRV_PCM_HW_PARAM_FIRST_MASK],
+          SNDRV_PCM_ACCESS_RW_INTERLEAVED);
+    pmask(&p.masks[SNDRV_PCM_HW_PARAM_FORMAT - SNDRV_PCM_HW_PARAM_FIRST_MASK],
+          SNDRV_PCM_FORMAT_S16_LE);
+    pmask(&p.masks[SNDRV_PCM_HW_PARAM_SUBFORMAT - SNDRV_PCM_HW_PARAM_FIRST_MASK],
+          SNDRV_PCM_SUBFORMAT_STD);
+    pivset(&p.intervals[SNDRV_PCM_HW_PARAM_CHANNELS - SNDRV_PCM_HW_PARAM_FIRST_INTERVAL],
+           (unsigned)ch);
+    pivset(&p.intervals[SNDRV_PCM_HW_PARAM_RATE - SNDRV_PCM_HW_PARAM_FIRST_INTERVAL],
+           (unsigned)rate);
+    p.rmask = ~0u;
+    p.info = 0;
+    p.msbits = 0;
+    p.rate_num = 0;
+    p.rate_den = 0;
+    if (ioctl(fd, SNDRV_PCM_IOCTL_HW_PARAMS, &p) != 0) { close(fd); return -1; }
+    ioctl(fd, SNDRV_PCM_IOCTL_PREPARE, 0);
+    return fd;
+}
+#endif
+
+/* 写 WAV 头（44 字节标准 PCM 布局：RIFF/WAVE/fmt(16)/data）。
+ * fmt(16) = format(2) ch(2) sample_rate(4) byte_rate(4) block_align(2) bits(2)。 */
+static void file_write_header(int fd, int rate, int ch, int bits, uint32_t data_len)
+{
+    unsigned char h[44];
+    memset(h, 0, sizeof h);
+    memcpy(h+0, "RIFF", 4);
+    uint32_t le = 36 + data_len; memcpy(h+4, &le, 4);
+    memcpy(h+8,  "WAVE", 4);
+    memcpy(h+12, "fmt ", 4);
+    le = 16; memcpy(h+16, &le, 4);
+    uint16_t s16 = 1; memcpy(h+20, &s16, 2);            /* PCM */
+    s16 = (uint16_t)ch; memcpy(h+22, &s16, 2);
+    le = (uint32_t)rate;                 memcpy(h+24, &le, 4);   /* sample rate */
+    le = (uint32_t)(rate * ch * bits / 8); memcpy(h+28, &le, 4); /* byte rate */
+    s16 = (uint16_t)(ch * bits / 8);   memcpy(h+32, &s16, 2);    /* block align */
+    s16 = (uint16_t)bits;              memcpy(h+34, &s16, 2);    /* bits/sample */
+    memcpy(h+36, "data", 4);
+    le = data_len; memcpy(h+40, &le, 4);
+    if (write(fd, h, 44) != 44) { /* 忽略 */ }
+}
+
+int audio_out_open(int sample_rate, int channels, int bits)
+{
+    g_rate = sample_rate; g_ch = channels; g_bits = bits;
+    const char *env = getenv("NCM_AUDIO_SINK");
+    g_path = getenv("NCM_AUDIO_OUT");
+    if (!g_path || !g_path[0]) g_path = NCM_DEFAULT_OUT;
+
+    /* 显式 null（测 RT） */
+    if (env && strcmp(env, "null") == 0) { g_sink = SINK_NULL; g_fd = -1; return 0; }
+
+    /* 尝试 ALSA（仅未显式指定 file；宿主无设备自动回退） */
+    if (!(env && strcmp(env, "file") == 0)) {
+#ifdef NCM_HAVE_ALSA
+        int fd = alsa_open(sample_rate, channels, bits);
+        if (fd >= 0) { g_sink = SINK_ALSADEV; g_fd = fd; return 0; }
+#endif
+    }
+    /* FILE sink */
+    int fd = open(g_path, O_WRONLY | O_CREAT | O_TRUNC, 0644);
+    if (fd < 0) { g_sink = SINK_NULL; g_fd = -1; return 0; }   /* 无路可写 → null */
+    file_write_header(fd, sample_rate, channels, bits, 0);
+    g_sink = SINK_FILE;
+    g_fd = fd;
+    return 0;
+}
+
+int audio_out_write(const short *samples, int frames)
+{
+    if (g_app_quit) return -1;
+    if (g_sink == SINK_NULL || g_sink < 0) return frames;
+    size_t n = (size_t)frames * (size_t)g_ch * (size_t)(g_bits / 8);
+    if (g_sink == SINK_ALSADEV) {
+        /* 阻塞尽力写满 - EINTR/EAGAIN 重试；错误返回 */
+        const unsigned char *p = (const unsigned char *)samples;
+        size_t off = 0;
+        while (off < n) {
+            ssize_t w = write(g_fd, p + off, n - off);
+            if (w > 0) { off += (size_t)w; continue; }
+            if (w < 0 && (errno == EINTR || errno == EAGAIN)) continue;
+            return -1;
+        }
+        return frames;
+    }
+    if (g_sink == SINK_FILE) {
+        if (write(g_fd, samples, n) != (ssize_t)n) return -1;
+        return frames;
+    }
+    return frames;
+}
+
+void audio_out_close(void)
+{
+    if (g_sink == SINK_FILE && g_fd >= 0) {
+        /* 回填：offset 4 = RIFF 总长-36；offset 40 = data 长度 */
+        off_t end = lseek(g_fd, 0, SEEK_END);
+        if (end > 44) {
+            uint32_t data_len = (uint32_t)(end - 44);
+            lseek(g_fd, 4, SEEK_SET);
+            uint32_t le = 36 + data_len;
+            if (write(g_fd, &le, 4) != 4) { }
+            lseek(g_fd, 40, SEEK_SET);
+            if (write(g_fd, &data_len, 4) != 4) { }
+        }
+    }
+    if (g_fd >= 0) close(g_fd);
+    g_fd = -1;
+    g_sink = -1;
+}

patch_v2/ncm_app/app/play/ipc_media.c

@@ -0,0 +1,212 @@
+/* play/ipc_media.c — 媒体会话 IPC 最小客户端（SDK 尚无媒体封装，App 内用 meow_ipc.h 帧格式直连）。
+ *
+ * 连接：AF_UNIX SOCK_STREAM 到 MEOW_IPC_SOCK（缺省 /usr/data/meow_ipc.sock）。HELLO(app_id,
+ * MF_PLAYBACK) 注册为媒体源；之后**同一连接**周期发 MSG_META（~1s，进度随播放推进）并阻塞等
+ * launcher 下发 MSG_PLAYCTL（播放/暂停/上下曲/seek）。launcher 经该连接 fd 回发（meow_media.c
+ * send_playctl 用最近活跃会话的 fd）。无 socket/launcher 不跑 → 优雅跳过（打日志不崩）。
+ * 线程模型：独立线程（main 起了 meow_ui_run 阻塞；播放线程归 player_manager，本线程只做 IPC 收发）。
+ */
+#include "../ncm_app_internal.h"
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+#include <fcntl.h>
+#include <errno.h>
+#include <poll.h>
+#include <sys/socket.h>
+#include <sys/un.h>
+#include "meow_ipc.h"
+
+static pthread_t g_thr;
+static int       g_thr_on;
+static int       g_quit;
+
+static const char *sock_path(void)
+{
+    const char *e = getenv("MEOW_IPC_SOCK");
+    return (e && e[0]) ? e : MEOW_IPC_PATH;
+}
+
+static int connect_path(const char *path)
+{
+    int fd = socket(AF_UNIX, SOCK_STREAM, 0);
+    if (fd < 0) return -1;
+    struct sockaddr_un a;
+    memset(&a, 0, sizeof a);
+    a.sun_family = AF_UNIX;
+    strncpy(a.sun_path, path, sizeof a.sun_path - 1);
+    if (connect(fd, (struct sockaddr *)&a, sizeof a) < 0) { close(fd); return -1; }
+    return fd;
+}
+
+/* 发送一帧（头+负载）。 */
+static int send_frame(int fd, uint16_t type, uint32_t req_id, const void *payload, uint32_t len)
+{
+    uint8_t hdr[MEOW_IPC_HDR_LEN];
+    uint32_t magic = MEOW_IPC_MAGIC;
+    uint16_t ver = MEOW_IPC_VERSION;
+    memcpy(hdr + 0, &magic, 4);
+    memcpy(hdr + 4, &ver, 2);
+    memcpy(hdr + 6, &type, 2);
+    memcpy(hdr + 8, &req_id, 4);
+    memcpy(hdr + 12, &len, 4);
+    size_t off = 0;
+    while (off < sizeof hdr) {
+        ssize_t w = write(fd, hdr + off, sizeof hdr - off);
+        if (w <= 0) return -1;
+        off += (size_t)w;
+    }
+    if (len && payload) {
+        off = 0;
+        while (off < len) {
+            ssize_t w = write(fd, (const uint8_t *)payload + off, len - off);
+            if (w <= 0) return -1;
+            off += (size_t)w;
+        }
+    }
+    return 0;
+}
+
+static int read_frame(int fd, uint16_t *type, uint8_t *rbuf, uint32_t rcap)
+{
+    uint8_t hdr[MEOW_IPC_HDR_LEN];
+    size_t off = 0;
+    while (off < sizeof hdr) {
+        ssize_t r = read(fd, hdr + off, sizeof hdr - off);
+        if (r <= 0) return -1;
+        off += (size_t)r;
+    }
+    uint32_t magic, len; uint16_t ver;
+    memcpy(&magic, hdr, 4); memcpy(&ver, hdr + 4, 2); memcpy(type, hdr + 6, 2);
+    memcpy(&len, hdr + 12, 4);
+    if (magic != MEOW_IPC_MAGIC || ver != MEOW_IPC_VERSION) return -1;
+    if (len > rcap) len = rcap;
+    off = 0;
+    while (off < len) {
+        ssize_t r = read(fd, rbuf + off, len - off);
+        if (r <= 0) return -1;
+        off += (size_t)r;
+    }
+    return (int)len;
+}
+
+/* 组并发送一条 META。 */
+static void send_meta(int fd, uint32_t req_id)
+{
+    m_meta_t mm;
+    memset(&mm, 0, sizeof mm);
+    ncm_strlcpy(mm.app_id, "os.meow.ncm", sizeof mm.app_id);
+
+    int idx = player_manager_playing_song();
+    pthread_mutex_lock(&g_play.mu);
+    int pos = (int)g_play.pos_ms;
+    int dur = (int)g_play.dur_ms;
+    int state = g_play.state;
+    int err = g_play.err;
+    pthread_mutex_unlock(&g_play.mu);
+
+    static char title[128], artist[128], album[128];
+    title[0] = artist[0] = album[0] = 0;
+    if (idx >= 0 && idx < g_st.song_count) {
+        snprintf(title, sizeof title, "%s", g_st.songs[idx].name);
+        snprintf(artist, sizeof artist, "%s", g_st.songs[idx].art_name);
+        snprintf(album, sizeof album, "%s", g_st.songs[idx].album_name);
+    }
+    snprintf(mm.title, sizeof mm.title, "%s", title);
+    snprintf(mm.artist, sizeof mm.artist, "%s", artist);
+    snprintf(mm.album, sizeof mm.album, "%s", album);
+    mm.pos_ms = (uint32_t)(pos < 0 ? 0 : pos);
+    mm.dur_ms = (uint32_t)(dur < 0 ? 0 : dur);
+    uint32_t st = 0;
+    if (err != 0) st = 0;
+    else if (state == NCM_PC_PLAYING) st = 1;
+    else if (state == NCM_PC_PAUSED)  st = 2;
+    else if (state == NCM_PC_BUFFER)  st = 3;
+    else st = 0;
+    mm.state = st;
+    /* 封面：若已落盘（cover 缓存文件）则提供路径 */
+    mm.flags = 0;
+    const char *cp = cover_current_path();
+    if (cp && cp[0]) {
+        snprintf(mm.artwork, sizeof mm.artwork, "%s", cp);
+        mm.flags |= MF_ART | MF_COVER;
+    }
+    if (lyric_count() > 0) mm.flags |= MF_LYRIC;
+    send_frame(fd, MSG_META, req_id, &mm, sizeof mm);
+}
+
+static void apply_playctl(const m_playctl_t *c)
+{
+    switch (c->cmd) {
+        case NCM_CTL_PLAY:  player_manager_pause(0); break;
+        case NCM_CTL_PAUSE: player_manager_pause(1); break;
+        case NCM_CTL_PREV:  player_manager_next(-1); break;
+        case NCM_CTL_NEXT:  player_manager_next(1);  break;
+        case NCM_CTL_SEEK:  player_manager_seek(c->seek_ms); break;
+        default: break;
+    }
+}
+
+static void *ipc_thread(void *arg)
+{
+    (void)arg;
+    int fd = connect_path(sock_path());
+    if (fd < 0) { meow_log(MEOW_LOG_WARN, "ipc: no launcher socket"); return NULL; }
+
+    m_hello_t h;
+    memset(&h, 0, sizeof h);
+    ncm_strlcpy(h.app_id, "os.meow.ncm", sizeof h.app_id);
+    h.version = 1;
+    h.flags = MF_PLAYBACK;
+    if (send_frame(fd, MSG_HELLO, 1, &h, sizeof h) != 0) { close(fd); return NULL; }
+    uint8_t hb[256];
+    uint16_t htype;
+    if (read_frame(fd, &htype, hb, sizeof hb) < 0) { close(fd); return NULL; }
+
+    send_meta(fd, 2);   /* 首条注册媒体源（state=0 未播也登记，start 播后自动成源） */
+
+    uint64_t last_meta = 0;
+    while (!g_quit && !g_app_quit) {
+        struct pollfd p;
+        p.fd = fd; p.events = POLLIN;
+        int pr = poll(&p, 1, 200);
+        if (pr > 0 && (p.revents & POLLIN)) {
+            uint8_t rbuf[MEOW_IPC_MAX];
+            uint16_t type;
+            int n = read_frame(fd, &type, rbuf, sizeof rbuf);
+            if (n < 0) break;
+            if (type == MSG_PLAYCTL && n >= (int)sizeof(m_playctl_t)) {
+                m_playctl_t c;
+                memcpy(&c, rbuf, sizeof c);
+                apply_playctl(&c);
+            }
+        } else if (pr < 0 && errno != EINTR) {
+            break;
+        }
+        uint64_t now = meow_ui_time_ms();
+        if (now - last_meta >= 1000) {
+            send_meta(fd, (uint32_t)(now & 0x7FFFFFFF));
+            last_meta = now;
+        }
+    }
+    close(fd);
+    return NULL;
+}
+
+int ipc_media_start(void)
+{
+    if (g_thr_on) return 0;
+    g_quit = 0;
+    if (pthread_create(&g_thr, NULL, ipc_thread, NULL) != 0) return -1;
+    pthread_detach(g_thr);
+    g_thr_on = 1;
+    return 0;
+}
+
+void ipc_media_stop(void)
+{
+    g_quit = 1;
+    /* 线程在 200ms poll 内退出（detach，不 join）*/
+    g_thr_on = 0;
+}

patch_v2/ncm_app/app/play/minimp3_impl.c

@@ -0,0 +1,4 @@
+/* play/minimp3_impl.c — minimp3(x) 唯一实现 TU（header-only：define 实现一次）。
+ * 编译时 -I<vendor>/minimp3。宿主与 mipsel 共用。 */
+#define MINIMP3_IMPLEMENTATION
+#include "minimp3_ex.h"

patch_v2/ncm_app/app/play/player_manager.c

@@ -0,0 +1,321 @@
+/* play/player_manager.c — 播放线程：URL 获取(Hi-res 逐档降级)→缓存(命中直接播/否则流式落盘)→
+ * minimp3 解码→audio_out 直写。UI 不卡（网络+解码全在此线程）。
+ *
+ * 模型：一个持久的播放线程。外层循环取「目标曲目」，run_song() 负责一首歌的
+ *   「下载(缓冲) → 解码 → 输出 → 结束/被指令打断」。暂停=冻结（停读停写停推 pos，状态置 PAUSED）；
+ *   seek=重开解码器+输出并 seek 到目标 ms（字节 offset 近似）；下一/上一首=打断当前 run_song 返回外层。
+ * 所有跨线程共享状态在 g_play (mu)。g_st.ctx 的 device_id/cookie/cache 在播放期间稳定（登出会先停播）。
+ * 返回码/错误经 g_play.err/errmsg 供 UI 提示。
+ */
+#include "../ncm_app_internal.h"
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+#include <sys/stat.h>
+#include "minimp3_ex.h"
+
+static pthread_t g_thr;
+static int       g_thr_on;
+static int       g_want_run = 1;     /* 线程运行标志（quit=0） */
+#define PCM_CHUNK 8192               /* 每块交织样本数（双声道 → 4096 帧） */
+
+/* ---- 线程内部一次性歌的状态 ---- */
+static char      g_path[512];        /* 本地 mp3 路径（缓存） */
+static int64_t   g_file_bytes;
+static int       g_level;            /* 音质档（来自设置） */
+static int       g_cache_gb;
+
+int player_manager_state(void) { int s; pthread_mutex_lock(&g_play.mu); s = g_play.state; pthread_mutex_unlock(&g_play.mu); return s; }
+int player_manager_playing_song(void) { int s; pthread_mutex_lock(&g_play.mu); s = g_play.cur_song; pthread_mutex_unlock(&g_play.mu); return s; }
+int64_t player_manager_pos_ms(void) { int64_t p; pthread_mutex_lock(&g_play.mu); p = g_play.pos_ms; pthread_mutex_unlock(&g_play.mu); return p; }
+int64_t player_manager_dur_ms(void) { int64_t d; pthread_mutex_lock(&g_play.mu); d = g_play.dur_ms; pthread_mutex_unlock(&g_play.mu); return d; }
+int player_manager_error(void) { int e; pthread_mutex_lock(&g_play.mu); e = g_play.err; pthread_mutex_unlock(&g_play.mu); return e; }
+
+void player_manager_set_quality(int level, int cache_gb)
+{
+    g_level = level;
+    g_cache_gb = cache_gb;
+    pthread_mutex_lock(&g_play.mu);
+    g_play.err = 0;
+    ncm_cache_set_limit_gb(&g_st.ctx.cache, cache_gb);
+    pthread_mutex_unlock(&g_play.mu);
+}
+
+void player_manager_play(int song_idx)
+{
+    pthread_mutex_lock(&g_play.mu);
+    g_play.cur_song = song_idx;
+    g_play.cmd = 0;
+    g_play.state = NCM_PC_BUFFER;
+    g_play.pos_ms = 0;
+    g_play.seq++;
+    pthread_mutex_unlock(&g_play.mu);
+}
+
+void player_manager_pause(int on)
+{
+    pthread_mutex_lock(&g_play.mu);
+    if (on) { if (g_play.state == NCM_PC_PLAYING) g_play.state = NCM_PC_PAUSED; }
+    else    { if (g_play.state == NCM_PC_PAUSED)  g_play.state = NCM_PC_PLAYING; }
+    pthread_mutex_unlock(&g_play.mu);
+}
+
+void player_manager_seek(int64_t ms)
+{
+    pthread_mutex_lock(&g_play.mu);
+    g_play.cmd = NCM_CTL_SEEK;
+    g_play.cmd_seek_ms = ms;
+    pthread_mutex_unlock(&g_play.mu);
+}
+
+void player_manager_next(int dir)
+{
+    pthread_mutex_lock(&g_play.mu);
+    int c = g_play.cur_song + dir;
+    if (c < 0) c = 0;
+    if (c >= g_st.song_count) c = g_st.song_count - 1;
+    if (c != g_play.cur_song) {
+        g_play.cur_song = c;
+        g_play.cmd = 0;
+        g_play.state = NCM_PC_BUFFER;
+        g_play.pos_ms = 0;
+        g_play.seq++;
+    }
+    pthread_mutex_unlock(&g_play.mu);
+}
+
+void player_manager_stop(void)
+{
+    pthread_mutex_lock(&g_play.mu);
+    g_play.cur_song = -1;
+    g_play.state = NCM_PC_STOPPED;
+    g_play.pos_ms = 0;
+    g_play.seq++;
+    pthread_mutex_unlock(&g_play.mu);
+}
+
+/* ---- 每首歌的播放体（在外层循环内调用）---- */
+static int download_cb(void *ctx, const unsigned char *data, size_t len)
+{
+    return ncm_cache_write((ncm_cache_writer_t *)ctx, data, len);
+}
+
+/* 得到本地 mp3 路径 + 文件大小。命中缓存直接返回；否则 URL 降级 + 流式落缓存。
+ * 返回 NCM_OK 或负错误码。 */
+static int song_local_file(int idx, char *path, size_t psz, int64_t *bytes)
+{
+    const ncm_song_t *s = &g_st.songs[idx];
+    const char *id = s->id;
+
+    /* 缓存命中 → 离线直接播 */
+    if (ncm_cache_lookup(&g_st.ctx.cache, id, ".mp3", path, psz) == NCM_OK) {
+        struct stat st;
+        if (stat(path, &st) == 0) { *bytes = (int64_t)st.st_size; return NCM_OK; }
+    }
+
+    /* 播放地址：从 g_level 降级，只收 mp3 */
+    ncm_play_url_t u;
+    int rc = ncm_api_song_url_auto(g_st.ctx.device_id, g_st.ctx.cookie, id, g_level, &u);
+    if (rc != NCM_OK) return rc;
+    if (!u.url[0]) return NCM_ERR_NOTFOUND;
+
+    /* 流式下载到缓存 temp → commit（稳妥者：先落盘再播） */
+    ncm_cache_writer_t *w = NULL;
+    rc = ncm_cache_open(&g_st.ctx.cache, id, ".mp3", &w);
+    if (rc != NCM_OK) return rc;
+
+    ncm_http_req_t req;
+    memset(&req, 0, sizeof req);
+    req.url = u.url;
+    req.method = "GET";
+    req.extra_hdrs = "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
+                     "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36";
+    req.verify_ca = NCM_HTTP_VERIFY_DEFAULT;
+    req.timeout_ms = 30000;
+
+    ncm_http_resp_t resp;
+    size_t maxb = (u.size > 0 && u.size < (64LL << 20)) ? (size_t)u.size : (64u << 20);
+    rc = ncm_http_download(&req, download_cb, w, maxb, &resp);
+    if (rc != NCM_OK || resp.status != 200) {
+        ncm_cache_abort(w);
+        return (rc != NCM_OK) ? rc : NCM_ERR_HTTP;
+    }
+    rc = ncm_cache_commit(w);
+    if (rc != 0) return rc;
+    if (ncm_cache_lookup(&g_st.ctx.cache, id, ".mp3", path, psz) != NCM_OK)
+        return NCM_ERR_NOENT;
+    struct stat st;
+    if (stat(path, &st) == 0) *bytes = (int64_t)st.st_size;
+    return NCM_OK;
+}
+
+static void set_err(int err, const char *msg)
+{
+    pthread_mutex_lock(&g_play.mu);
+    g_play.err = err;
+    if (msg) { ncm_strlcpy(g_play.errmsg, msg, sizeof g_play.errmsg); }
+    g_play.state = NCM_PC_STOPPED;
+    pthread_mutex_unlock(&g_play.mu);
+}
+
+/* 一首歌：下载→解码→输出，直到结束或被打断。返回后由外层处理下一首。 */
+static void run_song(int idx)
+{
+    int64_t file_bytes = 0;
+    char path[512];
+    int rc = song_local_file(idx, path, sizeof path, &file_bytes);
+    if (rc != NCM_OK) {
+        const char *m = (rc == NCM_ERR_NOTFOUND) ? "no stream (VIP/copyright)"
+                       : (rc == NCM_ERR_AUTH) ? "session expired" : "load failed";
+        set_err(rc, m);
+        return;
+    }
+    ncm_strlcpy(g_path, path, sizeof g_path);
+    g_file_bytes = file_bytes;
+
+    const ncm_song_t *s = &g_st.songs[idx];
+    int64_t dur = s->duration_ms > 0 ? s->duration_ms : 0;
+
+    mp3dec_ex_t dec;
+    memset(&dec, 0, sizeof dec);
+    if (mp3dec_ex_open(&dec, path, MP3D_SEEK_TO_BYTE) != 0) { set_err(NCM_ERR_IO, "decode open failed"); return; }
+
+    /* 音频输出：解码器输出 S16_LE（minimp3 默认）；用 44100/2ch 直开 */
+    if (audio_out_open(44100, 2, 16) != 0) { mp3dec_ex_close(&dec); set_err(NCM_ERR_IO, "audio open failed"); return; }
+
+    /* 状态→播放 */
+    pthread_mutex_lock(&g_play.mu);
+    g_play.state = NCM_PC_PLAYING;
+    g_play.pos_ms = 0;
+    g_play.dur_ms = dur;
+    g_play.err = 0;
+    pthread_mutex_unlock(&g_play.mu);
+
+    mp3d_sample_t pcm[PCM_CHUNK];
+    int64_t frames_done = 0;          /* 已输出帧（每通道） */
+    int need_seek_ms = -1;
+
+    for (;;) {
+        if (g_app_quit) break;
+
+        /* 取命令 */
+        pthread_mutex_lock(&g_play.mu);
+        int cmd = g_play.cmd; g_play.cmd = 0;
+        int64_t seek_ms = g_play.cmd_seek_ms;
+        int cur = g_play.cur_song;
+        int st  = g_play.state;
+        pthread_mutex_unlock(&g_play.mu);
+
+        if (cur != idx) break;               /* 切歌 → 回外层 */
+        if (st == NCM_PC_STOPPED) break;
+
+        if (cmd == NCM_CTL_SEEK && seek_ms >= 0) { need_seek_ms = (int)seek_ms; }
+
+        if (st == NCM_PC_PAUSED) { usleep(40 * 1000); continue; }   /* 冻结 */
+
+        if (need_seek_ms >= 0) {
+            /* 重开并 seek：关闭后重开（字节 offset 近似） */
+            audio_out_close();
+            mp3dec_ex_close(&dec);
+            memset(&dec, 0, sizeof dec);
+            if (mp3dec_ex_open(&dec, path, MP3D_SEEK_TO_BYTE) != 0) { set_err(NCM_ERR_IO, "seek reopen failed"); break; }
+            if (audio_out_open(44100, 2, 16) != 0) { set_err(NCM_ERR_IO, "audio reopen failed"); break; }
+            int64_t target = (g_file_bytes > 0 && dur > 0)
+                             ? (int64_t)g_file_bytes * need_seek_ms / dur : 0;
+            mp3dec_ex_seek(&dec, (uint64_t)(target > 0 ? target : 0));
+            frames_done = (int64_t)need_seek_ms * 44100 / 1000;
+            need_seek_ms = -1;
+            continue;
+        }
+
+        size_t got = mp3dec_ex_read(&dec, pcm, PCM_CHUNK);
+        if (got == 0) break;                         /* 播完 */
+        int frames = (int)(got / 2);
+        if (audio_out_write(pcm, frames) != frames)   break;
+        frames_done += frames;
+        /* 更新进度（~200ms 节流）*/
+        int64_t pos = frames_done * 1000 / 44100;
+        pthread_mutex_lock(&g_play.mu);
+        g_play.pos_ms = pos;
+        if (dur > 0 && pos >= dur) g_play.pos_ms = dur;
+        pthread_mutex_unlock(&g_play.mu);
+    }
+
+    audio_out_close();
+    mp3dec_ex_close(&dec);
+    /* 若应继续播下一首且非因命令打断，由外层处理（外层见 cur==idx 且需自然结束） */
+}
+
+/* 外层播放线程循环 */
+static void *player_thread(void *arg)
+{
+    (void)arg;
+    while (g_want_run && !g_app_quit) {
+        pthread_mutex_lock(&g_play.mu);
+        int cur = g_play.cur_song;
+        int st  = g_play.state;
+        pthread_mutex_unlock(&g_play.mu);
+
+        if (cur < 0 || cur >= g_st.song_count || st == NCM_PC_STOPPED) {
+            usleep(60 * 1000);
+            continue;
+        }
+        /* 以本地快照播放（idx 被外层线程独占，无需再锁） */
+        run_song(cur);
+
+        pthread_mutex_lock(&g_play.mu);
+        int cur2 = g_play.cur_song;
+        int st2  = g_play.state;
+        pthread_mutex_unlock(&g_play.mu);
+        /* 自然播完且无新命令 → 顺延下一首；否则回到循环等待 */
+        if (cur2 >= 0 && cur2 < g_st.song_count && st2 != NCM_PC_STOPPED && cur2 == cur) {
+            int nx = cur + 1;
+            if (nx < g_st.song_count) { player_manager_next(1); }
+            else { player_manager_stop(); }
+        } else {
+            usleep(50 * 1000);
+        }
+    }
+    return NULL;
+}
+
+/* 为当前曲目拉歌词并解析（UI 线程调）：buf 有界，解析后存 lyric 模块。 */
+int player_manager_load_lyric(void)
+{
+    lyric_clear();
+    int idx = player_manager_playing_song();
+    if (idx < 0 || idx >= g_st.song_count) return NCM_ERR_ARG;
+    const ncm_song_t *s = &g_st.songs[idx];
+    char *lrc = (char *)malloc(64 * 1024);
+    char *tl = (char *)malloc(32 * 1024);
+    if (!lrc || !tl) { free(lrc); free(tl); return NCM_ERR_OOM; }
+    int rc = ncm_api_lyric(g_st.ctx.device_id, g_st.ctx.cookie, s->id, lrc, 64 * 1024, tl, 32 * 1024);
+    if (rc == NCM_OK) lyric_parse(lrc, tl);
+    free(lrc);
+    free(tl);
+    return rc;
+}
+
+int player_manager_start(void)
+{
+    if (g_thr_on) return 0;
+    g_want_run = 1;
+    g_level = g_st.level;
+    g_cache_gb = g_st.cache_limit_gb;
+    pthread_mutex_init(&g_play.mu, NULL);
+    if (pthread_create(&g_thr, NULL, player_thread, NULL) != 0) return -1;
+    g_thr_on = 1;
+    return 0;
+}
+
+void player_manager_stop_thread(void)
+{
+    g_want_run = 0;
+    g_app_quit = 1;
+    audio_out_close();   /* 打断阻塞写 */
+    if (g_thr_on) {
+        pthread_join(g_thr, NULL);
+        g_thr_on = 0;
+    }
+}