e2m2e.api.frames

二进制帧编解码（ADR 0035 §3）。

帧格式是 tod ↔ e2m2e 的跨仓库持久契约，逐字段定义（多字节整数一律小端）：

偏移 长度 类型 含义 0 4 u32 magic = 0x324D3245（ASCII "E2M2" 小端；字节 45 32 4D 32） 4 1 u8 dtype：0 = float32，1 = float64 5 1 u8 ndim：维度数，≥ 1 6 4·ndim u32[] shape：各维元素数（不是字节数） 6+4·ndim — — 原始数组字节：C 连续、小端，长度 = prod(shape) × 元素宽度

没有 version 字段：magic 兼职版本锚点，不兼容改动时换 magic（须走新 ADR）。 本模块是帧契约的唯一实现点，不得引入 ADR 之外的字段。位于 api/ 包根而 非 sidecar 子包：执行核心的画布帧抽取（execution.py）与 sidecar 协议共 用同一编解码（#601）。

Attributes

MAGIC

Exceptions

FrameError

帧编解码失败（坏 magic、坏 dtype、长度与声明不符等）。

Functions

encode_frame(→ bytes)	把数组编码为一帧。
decode_frame(→ tuple[numpy.ndarray, str, int])	从 buf 开头解码一帧。

Module Contents

e2m2e.api.frames.MAGIC = 843919941

exception e2m2e.api.frames.FrameError

Bases: ValueError

帧编解码失败（坏 magic、坏 dtype、长度与声明不符等）。

e2m2e.api.frames.encode_frame(array: numpy.ndarray, dtype: str) → bytes

把数组编码为一帧。

Args:

array: 任意布局的数组（内部规范化为 C 连续、小端）。 dtype: "f32" 或 "f64"，与数组当前 dtype 独立（按声明转换）。

e2m2e.api.frames.decode_frame(buf: bytes | memoryview) → tuple[numpy.ndarray, str, int]

从 buf 开头解码一帧。

Returns:

(数组, dtype 名, 消费字节数)。消费字节数让调用方在帧流后恢复 JSON 行流（JSON 行的 binary_frames 声明了帧数，帧后无分隔符）。