Add smart encoding debugging guidance

SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: embedded-app-pc-debug
-description: 用于 Windows 电脑端的 Eapil 嵌入式产品与平台调试，包括远程编译、NFS 模块部署、设备发现、ROM 升级、串口监测和故障诊断；普通代码开发或仅查看已有日志时不要自动触发。
+description: 用于 Windows 电脑端的 Eapil 嵌入式产品与平台调试，包括远程编译、NFS 模块部署、智能编码调试、设备发现、ROM 升级、串口监测和故障诊断；普通代码开发或仅查看已有日志时不要自动触发。
 ---
 
 # Windows电脑端调试
@@ -16,6 +16,7 @@ description: 用于 Windows 电脑端的 Eapil 嵌入式产品与平台调试，
 - 涉及 USB Wi-Fi、驱动加载、`wlan0`、关联、DHCP、PC 多网卡或网络恢复时，也读取 [references/validation-and-diagnostics.md](references/validation-and-diagnostics.md)；需要运行中恢复网络服务时再读取 [references/application-debugging.md](references/application-debugging.md)。
 - 涉及 Linux 打包任务与 Windows 设备任务之间交接时，读取 [references/cross-host-coordination.md](references/cross-host-coordination.md)。
 - 涉及简道云“研发组 -> 固件发布”记录填写、预填或核对时，读取 [references/firmware-release.md](references/firmware-release.md)。
+- 涉及晶视智能编码、AVBR 静态场景码率、`vencSmart.json` 调参或压降测试时，读取 [智能编码调试知识](references/smart-encoding-debugging.md)。
 
 只读取当前任务需要的参考文件。不要因为用户仅要求串口查看而加载远程打包流程。
 

references/smart-encoding-debugging.md

@@ -0,0 +1,122 @@
+# 晶视智能编码调试知识
+
+## 适用范围与来源
+
+- 厂商依据：《晶视智能编码介绍 V1.7》，修订日期 2024-04-12，适用于 CV181X、SDK V4.1.0。本文页码均指该 PDF 的页码。原始资料由用户提供，位于 `D:/dingding-work/晶视智能编码介绍V1.7.pdf`；本参考可独立阅读，无须依赖该本机路径。
+- 工程案例：[会话“排查首次调用初始化回调”中的智能编码讨论](codex://threads/01a1573c-f743-7f70-8005-2e67079bb077?hostId=remote-ssh-discovered%3Aeapil-server)，工程为 PT41EC-S/HangYan。这里只采纳其中智能编码内容。
+- 厂商能力、旧版平台要求、工程实现和案例调参值各有适用范围。用于其他芯片、SDK 或固件版本前，核实相应接口与实际运行参数；本文未证明任何当前设备已达标。
+
+## 机制与生效条件
+
+这里的 SVC 指 **Smart Video Coding（智能编码）**。其调试分为两个环节：先根据 ISP 直方图统计把静态画面分为简单、中等、复杂场景，再为各类场景配置码率比例。先确认分类正确，再调对应码率。（第 4、8、9 页）
+
+- 该版本 SVC 支持 H.264/H.265，开关用于 AVBR；不能把静态三档调节方法直接套用到 VBR。支持 SBM、FBM。
+- 调用 `CVI_VENC_EnableSvc` 使能，再通过 `CVI_VENC_GetSvcParam` / `CVI_VENC_SetSvcParam` 读取、修改 SVC 参数，并检查返回结果。核对匹配的驱动、库、头文件及应用解析，不能仅凭 JSON 中字段存在判断功能已生效。（第 4—7 页）
+- 开关方案准备普通编码和智能编码两套 RC 参数。该 SDK 多数 RC 参数不能动态切换，文档要求销毁并重建 VENC 后应用新参数；单独保存配置文件不能证明运行通道已经更新。（第 8 页）
+- 该版本支持静态场景压降，不支持动态场景码率压降；H.265 支持动态场景保护，H.264 不支持同样的保护能力。不能因为 H.264 配置中有 `fg_protect_en` 就判定其有效。SVC 会占用部分 TPU 算力，需观察与其他 AI 功能并行的实际效果。（第 4 页）
+
+## 参数怎么选
+
+| 参数 | 调试用途与注意点 |
+|---|---|
+| `u32MaxBitrate` | 公式中的最大码率。读取活动通道的实际值，不用实测平均码率代替，也不默认沿用示例中的 1500。 |
+| `s32ChangePos` | 码率公式中的整体比例，proc 中可显示为 `ChgPs`。先保持实际值不变，用对应场景的比例调节；更改它也会影响动态场景/VBR 的公式上界。 |
+| `middle_min_percent` | 静态中等场景比例，范围 `[1,100]`。识别为中等场景时增大它，会提高计算上界，实测通常随之提高，但不保证线性增长。 |
+| `complex_min_percent` | 静态复杂场景比例，范围 `[1,100]`。只针对实际识别出的复杂场景；调节方向与中等场景相同。 |
+| `MinStillPercent` / `s32MinStillPercent` | 简单静态场景的比例。厂商公式与工程 JSON 的命名可能不同，需核实字段映射。 |
+| `complex_scene_detect_en` | 场景复杂度识别开关。 |
+| `complex_scene_low_th` / `complex_scene_hight_th` | 分类边界，范围 `[0,512]`。文档推荐 `150/318`；实际阈值依 ISP/PQ 和测试场景调整，低阈值应小于高阈值。保留接口中的 `hight` 拼写。它们不直接指定码率。 |
+| QP 限制 | 关注 `u32MinQp`、`u32MaxQp`、`u32MinIQp`、`u32MaxIQp`、`u32MaxStillQP` 及实际 `cur_qp`。预期码率与输出码流不一致时核对这些约束，不先批量修改所有 QP 参数。 |
+| `fg_protect_en` / `fg_dealt_qp` | 前景保护及帧级 QP 与运动区域 QP 的差值；后者范围 `[0,8]`，文档建议 `4`。值越大，运动区域保护越明显，静态区域质量可能下降。用途是画质分配，不是静态中等/复杂码率的首选调节项。 |
+| `u32RowQpDelta` | 行级码控，范围 `[0,10]`。文档建议 VBR/AVBR 取 `1`，同时说明非零可能影响前景保护，需结合画质观察。 |
+| `smart_ai_en` | AI 区域保护还需要有效 AI ROI map 配合；不能只开布尔值。文档建议 `0`，说明该版本此功能暂未开启。 |
+
+上述参数解释来自第 7—9 页及会话案例。文档给出的 `middle_min_percent` / `complex_min_percent` 电信参考值为 `50/80`、移动参考值约为 `15/20`；这些是项目调试起点，不能直接作为所有设备的默认值。运动灵敏度等其他 RC 项先保留项目现值，只有证据指向动静判断异常时再核对其 SDK 定义。
+
+## 码率公式与反算
+
+设 `M = u32MaxBitrate`，`C = s32ChangePos`，`P = 当前静态场景比例`，百分比字段使用 `75`、`60` 这样的数值。
+
+```text
+AVBR 静态：平均码率 < M × C/100 × P/100
+  简单：P = MinStillPercent
+  中等：P = middle_min_percent
+  复杂：P = complex_min_percent
+
+AVBR 动态：平均码率 < M × C/100
+VBR：     平均码率 < M × C/100（该公式不区分动静场景）
+
+令公式右侧等于期望码率 T，反算参考比例：
+P_ref = T × 10000 / (M × C)
+```
+
+第 8 页明确使用“小于”。因此这些是平均码率的计算上界，**不是码率下限、精确输出值或达标保证**；参数名中的 `min` 也不能改变该结论。反算只给出调试起点，需留出实验余量再实测。若 `M` 或 `C` 无效，先纠正输入；若 `P_ref > 100`，仅调这两个场景比例无法达到期望，应重新核对最大码率、`s32ChangePos` 与用例要求。`P` 表示码率比例，不等于开启/关闭对比得到的压降率。
+
+### 会话案例：3MP、最大码率 1250 kbps
+
+用户在会话中报告中等/复杂场景约 `148/198 kbps`，要求调向 `500/800 kbps`，并最终明确公式中的最大码率为 **1250 kbps**。这组测量缺少一一对应的活动编码模式、参数快照和统计口径，不能用于验证下表公式。下表只按最终确认的最大码率反算：3MP 配置为 `2304×1296`；H.264 的 `s32ChangePos=75`，H.265 为 `95`。
+
+| 编码 | 原中等/复杂比例 | 反算比例（中等/复杂） | 首轮试调比例（中等/复杂） | 试调值对应公式上界（kbps） |
+|---|---|---|---|---|
+| H.264 | `12/19` | `53.33%/85.33%` | `60/90` | `562.5/843.75` |
+| H.265 | `10/18` | `42.11%/67.37%` | `45/70` | `534.375/831.25` |
+
+该表是会话条件下的算例和待验证起点，不能直接推广到其他最大码率、分辨率、编码格式或固件。先确认活动通道使用包含 `2304×1296` 的配置对象；会话另一个对象只有 `640×360`，不能混用，也不能仅凭数组顺序推定主/子码流映射。原配置高阈值为 `260`，与文档推荐 `318` 不同；若分类已正确，不为提高码率而机械替换阈值。
+
+## 工程开关与运行证据
+
+会话中的 HangYan `source/callback/1.64.x/CallBackResp.cpp`、`source/env/EnvCap.cpp` 使用能力字段 `support_static_scence_ABR`、接口字段 `static_scence_ABR_on`，映射到 `vencParam.smartCode`。该会话所见实现中，手动码率设置会关闭智能编码；开启智能编码会执行视频参数 `Reset()` / `Load()` 并重新赋值 RC 模式、帧率、GOP、码率等。测试前核对目标版本实现，并在每次切换后回读最终参数，避免配置被重置却仍用旧值计算。文档中的“可通过下发高码率提升画质”不代表该工程接口已具有相同语义。
+
+`vencSmart.json` 只是配置入口。依次追踪它的实际加载路径、码流/分辨率选择、`svcH264` 或 `svcH265` 分支、SDK 参数下发以及活动通道回读；不要把编辑了本地文件当作设备已经使用新配置。
+
+在已连接且身份确认的目标上，按 SDK 实际支持情况读取：
+
+```sh
+cat /proc/cvitek/venc
+cat /proc/cvitek/rc
+```
+
+第 8 页图 7 展示 VENC 的 SVC 信息，第 9—11 页图示同时展示 VENC 和 RC。不要假定下表所有字段都在同一个 proc 节点；节点与名称以设备输出为准。
+
+| 观测项 | 用来回答的问题 |
+|---|---|
+| 通道 ID、分辨率、H.264/H.265、`RcMode`、`Br(kbps)`、`ChgPs` | 当前读到的是否为目标通道，计算输入是否与运行值一致？ |
+| `svcEnable`、场景识别开关、两项阈值及中等/复杂比例 | SVC 和新的配置是否已下发？ |
+| `cur_scene_cplx` / `senecCplx` | 当前场景复杂度及换景后的变化是否合理？文档存在不同拼写，按实际输出识别。 |
+| `minPercent` | 当前分类实际选用了哪档比例？不能仅凭肉眼认为画面属于中等或复杂。 |
+| `realBitrate` | 码控模块当前时刻的实际码率；它不是整段录像的平均码率。 |
+| `cur_qp`、QP 上下限、实际帧率 | 是否受到 QP 约束或以掉帧影响测量结果？ |
+
+换景后 `cur_scene_cplx` 一直不变时，文档指出 PQ 中关闭 DCI 是一个关键排查方向，应核对 PQ/DCI 并与负责方确认匹配参数；不要只通过扩大两个阈值掩盖统计值不更新的问题。（第 8 页）
+
+## 调参顺序与常见问题
+
+1. 明确本次判据：目标平台、分辨率、编码、主/子码流，目标是相对压降还是绝对码率，以及数值属于上限、下限或允许区间。用户已指定的案例目标优先；不从厂商旧版示例推定当前验收标准。
+2. 核对实际模式、SVC 使能、最大码率、`s32ChangePos`、配置分支及切换后回读。该版本采用 AVBR 智能编码时，确认对应 RC 参数已通过 VENC 重建生效。
+3. 固定场景观察复杂度统计与 `minPercent`。分类不对才调高低阈值；分类正确时保持阈值不变。
+4. 中等/复杂静态码率偏低，分别提高对应 `middle_min_percent` / `complex_min_percent`；按公式反算起点，每轮只调整能解释当前现象的参数并记录前后值。偏高时相反，始终同时观察画质。
+5. 比例已改但运行值未变，查加载路径、通道选择、解析映射、接口返回值、VENC 重建及后续覆盖。第 6 页图 5 的参考 demo 仅在 `complex_min_percent > middle_min_percent > 0` 时更新两项比例，阈值更新也要求 `high > low > 0`；核对当前工程是否沿用这些应用层条件，不将其当作 SDK 通用限制。运行比例已变但码流不符合预期，再查场景是否稳定、QP 约束和测量口径。
+6. 完成静态测试后检查静转动、动转静的码率恢复与画质，并检查帧率、卡顿、马赛克、拖影、灰屏和相关 AI 功能。这一步能发现只追求压降造成的质量退化。
+
+## 测试方法与判定边界
+
+**相对压降测试**：在同一画面、光照、机位、分辨率、编码、目标帧率和 GOP 条件下，分别采集关闭与开启智能编码的稳定码流。按实现记录两套 RC 参数；文档普通组通常为 VBR、智能组为 AVBR，不能要求两组 RC 模式完全相同而破坏功能。若开关重置了其他参数，先核实并明确差异。对简单、中等、复杂场景分别测量，按需求覆盖 H.264/H.265 和主/子码流。
+
+```text
+平均视频码率（kbps）= 统计窗口内的视频负载字节数 × 8 / 时长（秒）/ 1000
+压降率（%）= (关闭组平均码率 - 开启组平均码率) / 关闭组平均码率 × 100
+```
+
+关闭组平均码率必须大于零。视频流按同一口径统计，排除音频、容器和网络协议开销；如果用例评估音视频总流量，按该口径单列结果，不与纯视频结果混比。文档第 10—11 页实验表分别列了无音频、12k 音频和 64k 音频数据，说明音频会改变总压降比例。
+
+会话建议每组稳定采集约 5 分钟、至少 3 轮，可作为复现实验起点；这不是厂商强制时长，也不能替代全天云存测试。排除开关/重建后的过渡段，以各轮稳定窗口统计结果，并保留采集时长、负载字节数、码率、帧率、画质观察和参数快照。
+
+**绝对码率测试**：直接比较指定场景下开启智能编码后的平均码率与用例范围。文档第 11 页说明旧版杭研方案不要求开关对比，因此不强制为所有项目增加相对压降门槛。
+
+| 判据来源 | 文档或会话中的数值 | 使用边界 |
+|---|---|---|
+| 文档旧版电信要求（第 4 页） | 简单/中等/复杂压降约 `80%/50%/20%`；全天云存整体约 `50%—70%`；帧率至少 15 fps，GOP 2—4 秒 | 该版本资料描述的要求；全天数值不能由短时静态采集直接证明。 |
+| 文档旧版杭研要求（第 4 页） | 3MP 中等/复杂约 `100/170 kbps`；4MP `130/230`；5MP `160/280`；帧率至少 15 fps，GOP 不长于 5 秒 | 旧版目标；动态保持原画质/码率，切换顺畅，简单静态场景当时无要求。 |
+| 本会话实际调参目标 | 3MP 中等/复杂 `500/800 kbps`，最大码率 `1250 kbps` | 与文档旧版目标不同；只作为该案例目标，最终仍按实际用例的上下界和容差判定。 |
+
+文档第 9 页说明不同设备 ISP 参数会造成偏差；第 10—11 页图 10、13、15 是厂商模拟自测数据，不能当作当前设备实测证据。报告应写清采用哪版用例、实际运行配置、场景分类、测量口径、各轮结果及画质结论；未进行设备测量时只给调参建议，不写“已达标”。