<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
<!-- Copyright (C) 2024-2026 Gracker (Chris) | SmartPerfetto -->

---
scene: media
priority: 6
effort: medium
required_capabilities:
  - cpu_scheduling
optional_capabilities:
  - frame_rendering
  - gpu
  - gpu_work_period
  - power_rails
keywords:
  - 视频
  - 音频
  - 解码
  - 编码
  - media
  - codec
  - video
  - audio
  - decoder
  - encoder
  - mediacodec
  - codec2
  - omx
compound_patterns:
  - "(视频|音频|解码|编码).*(卡顿|耗电|延迟|掉帧)"
  - "(media|video|audio|codec|decoder).*(jank|power|latency|stutter)"

phase_hints:
  - id: codec_activity
    keywords: ['MediaCodec', 'Codec2', 'OMX', 'decoder', 'encoder', '解码', '编码', '视频卡顿']
    constraints: '优先调用 media_codec_activity 检查 codec/buffer 事件。该 skill 基于 slice 信号；缺 codec trace 时必须标注数据不足。'
    critical_tools: ['media_codec_activity']
    critical: true
  - id: media_rendering_power
    keywords: ['frame', 'gpu', 'power', '掉帧', '功耗', 'work period']
    constraints: '视频/媒体卡顿需要结合 frame/GL/GPU/power 证据：必要时调用 scrolling_analysis、gl_standalone_swap_jank、android_gpu_work_period_track、power_consumption_overview。'
    critical_tools: ['media_codec_activity', 'gl_standalone_swap_jank', 'android_gpu_work_period_track', 'power_consumption_overview']
    critical: false

plan_template:
  mandatory_aspects:
    - id: codec_activity
      match_keywords: ['media_codec_activity', 'MediaCodec', 'Codec2', 'OMX', '解码', '编码']
      suggestion: '媒体场景必须检查 codec/buffer 活动或明确说明 trace 缺少媒体信号'
    - id: render_or_power_context
      match_keywords: ['gl_standalone_swap_jank', 'android_gpu_work_period_track', 'power_consumption_overview', 'frame', 'gpu', '功耗']
      suggestion: '媒体卡顿/耗电问题需要补充渲染、GPU 或功耗上下文'
---

#### 媒体 / Codec 分析

当前公开 stdlib index 没有稳定的 Android codec 专用表，因此媒体基础分析先基于 `slice` / `thread` 信号识别 MediaCodec、Codec2、OMX、CCodec 和 buffer API。

**Phase 1 — Codec 活动与慢事件：**

```
invoke_skill("media_codec_activity", { package: "<包名>", start_ts: "<start>", end_ts: "<end>" })
```

重点看 `dequeueInputBuffer` / `queueInputBuffer` / `dequeueOutputBuffer` / `releaseOutputBuffer` 是否出现长耗时，以及 codec 线程是否集中在某个窗口。

**Phase 2 — 渲染/GPU/功耗上下文：**

| 问题 | 调用 |
|---|---|
| 视频掉帧但 codec 正常 | `invoke_skill("gl_standalone_swap_jank")` 或按场景切回 scrolling strategy |
| GPU active region 连续或异常 | `invoke_skill("android_gpu_work_period_track")` |
| 媒体播放耗电 | `invoke_skill("power_consumption_overview")` |

输出时必须标注媒体 trace 信号来源。如果 codec slices 不存在，只能说明当前 trace 不支持媒体归因，并给出采集建议。
