docs: 文档一致性整理 (agent-265) — 对齐 M2.91-96/0.7.86-0.7.91 + 261/262/264
- README: 版本头 M2.90→M2.96；M2.91-96 批次( audiod FPGA 开机武装根治 PCM 死锁 / 充电权威链 mp2731 / amsd 注册自愈 / NP 死循环修复+充电闪电 / 插孔消抖三路 / 长流护栏+几何 period=1024×4 / wd_vol_save 毁设置修复 / 音量反转四路统一 dac=255-pct*255/100 / 炸耳修复 dac_vol_mute=255 )；流媒体客户端三期续(254 滑窗/256 封面缓冲 UX/260 FLAC dr_flac/262 播放键 toggle)；已知问题 PCM 挂死条目移除(已根治)
- MEOW_APP_SDK §5.9: 后续批次全量(FPGA 武装/长流护栏+几何/音量反转+炸耳修复/261 电平监控 rms/peak+monitor CLI, ABI 兼容)；IME 节后注拼音 IME 已落地
- FRAMEWORK_DESIGN: 头部里程碑 M2.15-M2.96；附录 B PLAYCTL 补 cmd=6 toggle
- SPEC_REF: §4 audiod 条目补 M2.91-97 加固批；音频硬件事实补衰减量语义+端口 5=audiod 强制重烧约定；现行版本 0.7.91(261 待 M2.97)；252 面板 /api/audio+字体页；OPEN_QUESTIONS 待定批更新(PCM 挂死已清结)
- SYSTEM_SETTINGS: audio.volume 衰减量注记 + 音量存盘读改写单键纪律
- KEY_CONTROL §9: SDK 插孔消抖已落地(56c569f) + 音量反转/存盘修复 + 262 播放键 cmd=6 toggle
- APPS §3.7: audiod 加固批摘要 + 262 toggle
- DEVELOPMENT_PLAN: 头部截至 M2.96
- 口径: 入库文档应用名统一中性表述「流媒体客户端（dev.player.ncm）」
This commit is contained in:
MeowOS committed
1 parent
ad9778476a
commit
ab4dfb4f9c
8 files changed
+39
-32
No files matched your search
+11
-8
@@ -174,7 +174,7 @@ void meow_switch_set(meow_widget *s, int on);
|
||||
```
|
||||
|
||||
> 控件命中（触摸点是否落在控件内）由输入层语义事件驱动，应用在 `meow_ui_on_tap(x,y)` 回调里做分发——见下节。
|
||||
> **B1 先做最小控件集**（按钮/滑条/开关/列表四件套），其余（下拉、进度圈、通知卡片）随阶段 B 通知中心 / 网易云需要用再加。
|
||||
> **B1 先做最小控件集**（按钮/滑条/开关/列表四件套），其余（下拉、进度圈、通知卡片）随阶段 B 通知中心 / 流媒体客户端需要用再加。
|
||||
|
||||
### 5.1 输入法（IME）—— 内置触屏软键盘
|
||||
|
||||
@@ -183,7 +183,7 @@ void meow_switch_set(meow_widget *s, int on);
|
||||
**形态**：系统级单例软键盘，作为控件层的一个特例（`meow_ime`），应用调 `meow_ui_text_input()` 弹出，键盘覆盖在应用之上，由 SDK 绘制与分发（复用 `back_buf` + `meow_present` 无闪烁地基，不干扰业务渲染）。
|
||||
|
||||
**B1 范围**：**英文 QWERTY 键盘**（数字+字母+符号），覆盖字符输入、退格 Backspace、空格、回车/完成。
|
||||
**不在 B1**：中文拼音/词库选字——复杂度高、依赖词库，留到后期独立 IME（网易云/中文搜索需要时再上）。B1 的 IME 只保证"能输入 ASCII 文本"。
|
||||
**不在 B1**：中文拼音/词库选字——复杂度高、依赖词库，留到后期独立 IME（流媒体客户端/中文搜索需要时再上）。B1 的 IME 只保证"能输入 ASCII 文本"。（**后注**：中文拼音 IME 已落地——M2.88 agent-229 `meow_pinyin.c` 静态表 403 音节+329 词，组合条+候选栏+翻页+中英切换+九键数字盘，流媒体客户端搜索已接 `MEOW_IME_PINYIN`。）
|
||||
|
||||
```c
|
||||
/* 弹出软键盘，输入到应用提供的缓冲。返回 1=确认(fn=enter)，0=取消(fn=esc/背景点)。
|
||||
@@ -727,7 +727,7 @@ meow_widget *meow_layout_spacer(int w, int h);
|
||||
|
||||
### 5.9 音频客户端 API（`meow_audio_*`，M2.90 落地）
|
||||
|
||||
> **权威规范：`devdocs/plan/AUDIOD_DESIGN.md`**（用户定案五项决策）。**已实现**：A1（agent-244/246，audiod+CLI+SDK 客户端，M2.90 入固件）+ A2（ncm 迁 SINK_AUDIOD，e013621）。IPC 号段 `0x00C0-0x00CA` 见 `meow_ipc.h` / docs/MEOWOS_SPEC_REF §4。
|
||||
> **权威规范：`devdocs/plan/AUDIOD_DESIGN.md`**（用户定案五项决策）。**已实现**：A1（agent-244/246，audiod+CLI+SDK 客户端，M2.90 入固件）+ A2（流媒体客户端迁 SINK_AUDIOD，e013621）+ 后续批次（M2.91 FPGA 开机武装 / M2.93 长流护栏 / M2.94 几何收窄 / M2.95 音量反转 / M2.96 炸耳修复 / 261 电平监控待 M2.97 固件化）。IPC 号段 `0x00C0-0x00CA` 见 `meow_ipc.h` / docs/MEOWOS_SPEC_REF §4。
|
||||
|
||||
MeowOS 的声卡由**独占音频守护 `meow_audiod`** 持有（`hw:0,0`；M2.90 入固件，svcd 托管，HibyOS 模式不启动）。**App 不再直开 ALSA**，一律经 SDK 客户端 `meow_ui_audio.c`（编进 `meow_ui.a`）喂 PCM：
|
||||
|
||||
@@ -744,10 +744,13 @@ void meow_audio_on_preempt(void (*cb)(const char *by_app, void *ctx), void *ctx)
|
||||
- **fmt 枚举**：1=S16_LE 2=S24_LE 3=S32_LE 4=FLOAT_LE（v1 实装 S16/S24/S32）；服务端做**格式归一 + DAC 原生率跟随**（无 SRC，44.1-192k 全覆盖）。
|
||||
- **独占+抢占**：后开流赢，旧流收 `MSG_AUDIO_PREEMPTED`（App 收到自行暂停 UI）；**socket EOF=回收**（客户端崩溃/被 SIGKILL 不泄漏）。流绑定 socket 连接而非 App 前台状态（后台播放见 AUDIOD_DESIGN §3）。
|
||||
- **懒连接 + 断线重连**：open 时连 `/usr/data/meow_audio.sock`；write 遇 EPIPE → 标记流死，App 需重新 open。**不做隐式直开回退**：audiod 不在 → open 返回 -ENOENT；调试可 `MEOW_AUDIO_DIRECT=1` 允许 App 自带直开路径（仅开发用，非正式能力）。
|
||||
- **调试 CLI**（root 免鉴权，ssh 直呼）：`meow_audio status` / `meow_audio tone [freq] [ms] [rate]`（正弦测试音，排查无声不用开 App）/ `route <0|2|3>` / `vol [0-100]`。
|
||||
- **调试 CLI**（root 免鉴权，ssh 直呼）：`meow_audio status` / `meow_audio tone [freq] [ms] [rate]`（正弦测试音，排查无声不用开 App）/ `route <0|2|3>` / `vol [0-100]` / **`monitor [秒]`**（261，终端实时电平表：200ms 刷新 rms/peak dBFS + 文本电平条，缺省 10s，0=持续）。
|
||||
- **⚠️ ALSA UAPI 两坑（真机定位，App 自写直开路径时勿回退）**：① hw_params 须「全放行」初始化（params_any 语义：mask 全 1、interval [0,UINT_MAX]），memset 0 的 interval → HW_PARAMS 恒 EINVAL；② access/format/subformat mask 须**先清零再单点**，留全 1 会被 choose 成 MMAP_INTERLEAVED → write 恒 EINVAL。
|
||||
- **⚠️ 已知问题（2026-09-01 调查中）**：M2.90 内核在 `cs43198_dai_prepare` 后第二次 `hbc3000_start` 硬挂死（驱动对重复 start 不可重入）；底稿 `devdocs/plan/AUDIO_HANG_INVESTIGATION.md`。
|
||||
- **ncm 迁移范式（A2，e013621）**：`ncm_app/app/play/audio_out.c` 新增 `SINK_AUDIOD` 后端（与 ALSA/FILE/NULL 并列，**默认 audiod**），被抢占回调→暂停、resume 检测流死自动重开、播放路径全量 `meow_log`；UI/缓存/解码零改动。新 App 照此接。
|
||||
- **PCM 死锁已根治（M2.91，原「M2.90 一播 PCM 即内核硬挂死」）**：根因 = 未烧 hbc3000 FPGA 时驱动对第二次 `hbc3000_start` 不可重入死锁；audiod 路由线程启动时**无条件写 Output Port Switch**（4.4→3/3.5→2/无→4，同值先写 5 强制重烧）武装 FPGA。调查全程 `devdocs/plan/AUDIO_HANG_INVESTIGATION.md`。
|
||||
- **长流停摆已根治（M2.93 护栏 + M2.94 几何）**：驱动默认巨 buffer（上限 1048576 帧≈23s）致 hbc3000 桥周期中断稀缺 wedge（播 ~12s 停摆）→ audiod `alsa_hw_params` 收窄 **period=1024×4**（tiny_alsa 惯例，tonepcm2 矩阵 60s 零 stall 实证）；257 护栏：ring 有界等待/cond timedwait/popen 有界收割/O_NONBLOCK+poll 写/wedge 自救/心跳 watchdog/下行写不全丢弃。
|
||||
- **音量语义（M2.95 四路统一，勿回退）**：CS43198 音量寄存器 = **衰减量**（0=最响，255=静音）；launcher/audiod/watchdog/SDK 统一映射 `dac = 255 - pct*255/100`。**炸耳安全（M2.96）**：`dac_vol_mute` 必须写 **255（真静音）**——旧版写 0=最大响度，流回收/重配瞬间满幅输出（真机事故）。⚠️ 非线性（0.5dB/步，50%≈-64dB），感知曲线（dB taper）待做。
|
||||
- **电平监控（261，已提交待 M2.97 固件化）**：播放线程对 ring 取出 PCM 逐样本整数累加，~100ms 窗口（逐帧判边界）结算 RMS/peak dBFS（deci-dB，地板 -990=-inf）；`MSG_AUDIO_STATE` 追加 `rms=/peak=/lvlseq=` 键（**追加键，SDK `meow_audio_state` 结构体未动，ABI/协议兼容**）；流活跃时 1s 节拍写 TF `MeowOS/logs/audio_monitor_<bootts>.log`（流停即停，无流零开销）。
|
||||
- **流媒体客户端迁移范式（A2，e013621）**：`ncm_app/app/play/audio_out.c` 新增 `SINK_AUDIOD` 后端（与 ALSA/FILE/NULL 并列，**默认 audiod**），被抢占回调→暂停、resume 检测流死自动重开、播放路径全量 `meow_log`；UI/缓存/解码零改动。新 App 照此接。
|
||||
|
||||
---
|
||||
|
||||
@@ -1044,8 +1047,8 @@ patch_v2/meow_launcherd/meow_font.a # 复用（静态链接）
|
||||
|
||||
1. `meow_ui` 渲染后端需从 launcher 里**抽公共绘制实现**（`back_buf`/`meow_dirty_*`/`meow_present`/`meow_font_bind` 目前是 launcher 静态函数——需提取为可链接的 `meow_ui_gfx` 或改为共享 obj，注意 launcher 与 app 是**不同进程**，不能共享同一 back_buf；`meow_ui.a` 是**独立库**，内部自建 fb 上下文，不复用 launcher 的全局 `g_dirty`）。
|
||||
2. 输入线程优先级：vs 主循环 10ms 热键轮询的竞态，需在 B1 实现时定义清楚（应用进程内独立事件循环，不与 launcher 抢）。
|
||||
3. 网易云跑通后迭代控件集（播放页/列表/歌词），非一次性补齐。
|
||||
4. **`meow_ui_img_blur_bg`（降采样模糊背景，HibyOS 同款）API 待加**：已在 §11 确认可行性（缩 1/8 放大铺底 + α 遮罩，切歌算一次）；函数签名与实现留到 B1 之后（或并入网易云播放页时）。当前 SDK B1 的图片层先用 `meow_ui_img_scaled` + `fill_rect_alpha` 手动组合即可达到同等观感。
|
||||
3. 流媒体客户端跑通后迭代控件集（播放页/列表/歌词），非一次性补齐。
|
||||
4. **`meow_ui_img_blur_bg`（降采样模糊背景，HibyOS 同款）API 待加**：已在 §11 确认可行性（缩 1/8 放大铺底 + α 遮罩，切歌算一次）；函数签名与实现留到 B1 之后（或并入流媒体客户端播放页时）。当前 SDK B1 的图片层先用 `meow_ui_img_scaled` + `fill_rect_alpha` 手动组合即可达到同等观感。
|
||||
5. 视频**已定不做**：无解码器/无 GPU/内存 14MB 会 OOM；"视频"一律用预渲染帧序列模拟。若确需播放具体小视频，宿主机离线转帧序列 PNG → 打包到 TF 卡 → SDK 按帧播放（规避设备一切解码负担）。
|
||||
|
||||
### B1 落地状态（2026-08-29）
|
||||
|
||||
Reference in new issue
Block a user