// guide
使用指南
从打开文件到读懂 QP 热力图与运动矢量，把整个分析流程走一遍。全部处理都在你的浏览器内完成，文件不会上传到任何服务器。
一、打开文件
点击首页的「打开文件」按钮，或把文件直接拖拽到页面上。支持 MP4 / MOV / M4V / 3GP / MKV 等容器，视频编码支持 H.264 (AVC) 与 H.265 (HEVC)。
建议使用较新版本的 Chrome 或 Edge：帧预览依赖浏览器内置的硬件解码器，其他浏览器仍可正常分析码流，只是没有画面预览。
二、认识左侧的 Box 结构树
打开文件后，左侧是 ISOBMFF 容器结构树。它是 MP4 文件的骨架，理解了它，后面看什么都顺：
| Box | 作用 |
|---|---|
| ftyp | 文件类型与兼容品牌，决定播放器是否认这个文件 |
| moov / mvhd | 媒体元信息与全局参数（时长、时间基、播放速率） |
| trak / tkhd | 一条轨道（视频或音频）及其轨道头信息 |
| stbl / stsd | 采样表与编解码配置（SPS/PPS 等参数集） |
| stts / stss / stco | 时间戳、关键帧索引、采样在文件中的偏移 |
| mdat | 真正的码流数据 |
点击任意节点即可查看详情：字段树 + 二进制 Hex Dump。容器类 Box 支持展开。
三、看文件信息与帧列表
侧栏的「文件信息」汇总了容器层面的关键信息：轨道数量、编解码器、分辨率、帧率、时长、码率等，适合快速判断一个文件是否正常。
「帧列表」按采样顺序列出每一帧，包含帧号、帧类型、大小与该帧在文件中的偏移。三种帧类型是理解码流的基础：
| 类型 | 含义 |
|---|---|
| I | 帧内编码，不依赖其他帧，可独立解码（关键帧） |
| P | 前向预测，参考过去的帧 |
| B | 双向预测，同时参考过去与未来的帧 |
四、进入帧详情：三种模式
- 预览：调用浏览器内置的硬件解码器显示该帧画面。分析块信息时它会作为底图，方便把 QP / MV 与真实画面内容对应起来。
- 二进制：整帧的 Hex Dump，可按字节查看该帧的原始数据。
- 块分析：本工具的核心，把这一帧的编码决策可视化出来（下节详述）。
五、读懂 QP 热力图
QP（Quantization Parameter，量化参数）决定编码器对每个块「压得多狠」：QP 越大，量化越粗、丢弃的细节越多、占用码率越低；QP 越小，保留的细节越多、码率越高。
块分析视图里每个块的颜色按「相对该帧基准 QP 的偏差」着色：
| 颜色 | 含义 |
|---|---|
| 绿 | QP 明显低于基准——编码器认为这里重要，给足了码率 |
| 黄 / 橙 | 接近基准 QP——常规处理 |
| 红 | QP 明显高于基准——压缩很狠，细节损失大 |
打开顶部的 QP值 开关，会在每个块上直接标出 QP 数值；Grid 开关显示编码块边界，能直观看出编码器在不同区域选的块尺寸差异。
典型用法：画面某区域出现明显块效应或糊，切到对应帧看那一块的 QP 是不是偏高——是，就说明是码率分配问题，而不是画面本身的问题。
六、读懂运动矢量（MV）
打开 MV 开关后，每个参与帧间预测的块都会画出一根箭头：
- 起点 = 当前块的中心；
- 终点（圆点） = 编码器为该块找到的最佳匹配块，即参考块的中心；
- 长度 = 运动幅度。越长的线代表这块画面动得越快；起点终点重合（只有一个点）表示零矢量，即静止区域；
- 方向 = 这块内容「从哪里来」。因此箭头的方向与画面实际运动方向相反。
| 颜色 | 含义 |
|---|---|
| 蓝 | L0 矢量，参考过去的帧（P 帧、B 帧都有） |
| 橙 | L1 矢量，参考未来的帧（仅 B 帧会出现） |
箭头只在块在屏幕上足够大时才绘制。缩小视图时几百根箭头会糊成一片反而看不清方向，放大即可显现。
单击任意块可以选中它（红色框），右侧「块信息」面板会给出该块的精确数值：QP、相对基准的偏差、运动矢量分量以及预测类型，同时附一个该块及其邻域的放大取景框。
七、用 Hex 搜索定位数据
在 Box 详情或帧的二进制度视图中，搜索框支持两种模式：文本模式按 ASCII 字符串查找（例如找 avcC、mdat），Hex 模式按字节序列查找。
- Hex 模式输入会自动大写并按两位分组，输入 ffff 会实时变成 FF FF；
- 非十六进制字符在输入阶段就会被过滤，粘贴 0xdeadbeef 也能直接识别；
- 用 ↑ / ↓ 在命中项之间跳转（Enter / Shift+Enter 同样可用），命中处会高亮；
- 文本模式下可切换是否区分大小写。
典型用法：定位 NAL 单元起始码、检查参数集（SPS/PPS/VPS）是否被重复写入、核对 mdat 中的实际数据长度。
// guide
Guide
From opening a file to reading QP heatmaps and motion vectors — the whole workflow. Everything runs inside your browser; your file is never uploaded.
1. Open a file
Click Open File on the landing page, or drag a file onto the page. Containers MP4 / MOV / M4V / 3GP / MKV are supported, with H.264 (AVC) and H.265 (HEVC) video codecs.
A recent Chrome or Edge is recommended: frame preview uses the browser's built-in hardware decoder. Other browsers can still analyze the bitstream, just without the picture preview.
2. Read the box tree
The left panel shows the ISOBMFF structure — the skeleton of the file:
| Box | Purpose |
|---|---|
| ftyp | File type and compatible brands |
| moov / mvhd | Media metadata and global parameters (duration, timescale, rate) |
| trak / tkhd | One track (video or audio) and its track header |
| stbl / stsd | Sample tables and codec configuration (SPS/PPS) |
| stts / stss / stco | Timing, keyframe index, and sample byte offsets |
| mdat | The actual coded bitstream |
Click any node to inspect its fields and a hex dump of its bytes. Container boxes can be expanded.
3. File info and frame list
File Info summarizes container-level facts: track count, codec, resolution, frame rate, duration and bitrate — useful for a quick sanity check.
Frame List enumerates every sample with its index, frame type, size and byte offset. The three frame types are the basis of everything else:
| Type | Meaning |
|---|---|
| I | Intra-coded, independently decodable (keyframe) |
| P | Forward prediction from past frames |
| B | Bi-directional prediction, referencing past and future frames |
4. Frame detail: three modes
- Preview — decode and display the frame via the browser's built-in hardware decoder; it doubles as the backdrop for block analysis.
- Binary — a hex dump of the whole frame.
- Block analysis — the core of the tool: visualize this frame's coding decisions.
5. Reading the QP heatmap
QP (Quantization Parameter) is how aggressively a block is compressed: higher QP means coarser quantization, fewer retained details, lower bitrate; lower QP means more detail and more bits.
Each block is colored by its deviation from the frame's base QP:
| Color | Meaning |
|---|---|
| Green | Well below base QP — the encoder spent bits here |
| Yellow / orange | Around the base QP — business as usual |
| Red | Well above base QP — heavy compression, details dropped |
Toggle QP values to print the number on each block, and Grid to outline coding block boundaries — useful to see how block sizes vary across the frame.
6. Reading motion vectors (MV)
With MV enabled, every inter-predicted block gets an arrow:
- Start — the center of the current block;
- End (dot) — the center of the best-matching reference block;
- Length — motion magnitude; a dot with no line means a zero vector (still area);
- Direction — where this content came from, i.e. the opposite of apparent motion.
| Color | Meaning |
|---|---|
| Blue | L0 vector — references a past frame (P and B frames) |
| Orange | L1 vector — references a future frame (B frames only) |
Arrows are drawn only once a block is large enough on screen at the current zoom. Zoom in to reveal them.
Click any block to select it (red outline); the block info panel on the right reports exact values — QP, delta from base, motion vector components and prediction type — plus a magnified view of the block and its neighborhood.
7. Locating bytes with hex search
Both in box details and in a frame's binary view, the search box offers two modes: text (ASCII, e.g. find avcC or mdat) and hex (byte sequence).
- Hex input is auto-uppercased and grouped in pairs: typing ffff becomes FF FF;
- Non-hex characters are filtered as you type, and pasting 0xdeadbeef works;
- Jump between matches with ↑ / ↓ (or Enter / Shift+Enter); matches are highlighted;
- Text mode can be made case-sensitive.