"""Evolution sidecar 的 JOC/OAMD 纯 Python 解析、校验和可读输出。""" from collections import Counter import csv import hashlib import json from pathlib import Path from adm_atmos import q_to_adm_xyz from bed_layout import (BED_CHANNEL_NAMES, EXTRA_PAIR_BY_CONFIG, bed_layout, declared_bed_channels, extra_pair) from evo_unpack import unpack_evolution from emdf import (ACMOD_LOCATIONS, EmdfError, audio_frame_groups, expand_chanmap, find_joc_emdf, iter_syncframes, parse_container) from joc_decode import parse_joc, parse_joc_header from oamd_bits import (JocFieldState, frame_update_values, program_bed_channels, program_bed_summary) from variant_error import UnsupportedVariantError, bytes_descriptor def _joc_pair_score(container): """这个容器作为本帧 JOC 元数据的可信度(规格 §8.2 / Table 56)。 §8.2:OAMD 与 JOC 载荷放在同一个 EMDF 容器里;Table 56:两者的 groupid 必须相同。同一个同步帧里可能出现多个含 ID11/ID14 的顶层容器,其中不构成一对的那个 (ID14 声明的对象数超出其字节所能容纳的范围、ID11 未声明 groupid)既不是一对 合法载荷,也不可能是本帧的 JOC 参数。 2 = 两个载荷 groupid 相同且 ID14 完整解析;1 = ID14 完整解析;0 = 其余。 """ payload = container.payloads.get(14) if payload is None or 11 not in container.payloads: return 0 parses = True try: parse_joc(payload) except (IndexError, ValueError): parses = False group_ids = getattr(container, "group_ids", None) or {} first = group_ids.get(11) second = group_ids.get(14) associated = first is not None and second is not None and first == second if associated and parses: return 2 return 1 if parses else 0 def _transport_record(group): """从一个音频帧的同步帧组提取规格 §11.2 需要的 L2 声明。""" core_locations = () core_lfe = False chanmap = None for sync in group: if sync.codec == "ac3" or sync.strmtyp == 0: core_locations = ACMOD_LOCATIONS.get(sync.acmod, ()) core_lfe = bool(sync.lfeon) elif sync.chanmap is not None: chanmap = sync.chanmap return { "core_locations": tuple(core_locations), "core_lfe": core_lfe, "chanmap": chanmap, "syncframes": [ { "offset": sync.offset, "size": sync.size, "codec": sync.codec, "strmtyp": sync.strmtyp, "substreamid": sync.substreamid, "acmod": sync.acmod, "lfeon": sync.lfeon, } for sync in group ], } def _bed_covers_core(bed_channels, core_positions): """声明的 bed 布局是否覆盖核心子流携带的全频段声道。 OAMD 的 bed 掩码描述的是**内容**的 bed 布局,可以比 E-AC-3 核心实际编码的声道多 (例如 9.1.6 bed 只编 5.1 核心)。因此只有"核心声道在 bed 布局里找不到位置"才是 真正的不一致;多出来的 bed 声道是布局的一部分,不算冲突。 """ names = {BED_CHANNEL_NAMES.get(label, label) for instance in bed_channels for label in instance} return all(position in names for position in core_positions) def check_cross_layer(parsed, *, frame, transport=None, bed_channels=None, bed_layout_info=None, diagnostics=None): """规格 §11.2 的跨层一致性校验。 校验 1/2(额外那对的身份)不一致时只记 diagnostics:通道身份不进 DSP (§10.1),床映射按 chanmap 给出的通道码做,音频与 k 一致时逐样本相同。 校验 3(核心通道数)与 joc_ext_config_idx 会改变 DSP 输入,仍按变体报错。 """ config_idx = parsed["dmx_config_idx"] n_channels = parsed["n_channels"] expected_pair = EXTRA_PAIR_BY_CONFIG.get(config_idx) if parsed["ext_config_idx"] != 0: raise UnsupportedVariantError( "joc", "ext_config_idx_unsupported", "joc_ext_config_idx 取到当前未映射的值", frame=frame, details={ "downmix_config": config_idx, "extension_config_idx": parsed["ext_config_idx"], "payload": bytes_descriptor(parsed.get("payload", b"")), }) if diagnostics is not None and parsed.get("objects_clamped"): diagnostics.append({ "stage": "joc", "variant": "num_objects_clamped", "frame": frame, "message": "对象数超过 15,已截断", "details": {"declared": parsed["num_objects_bits"] + 1, "used": parsed["n_objects"]}, }) if transport is not None: chanmap = transport["chanmap"] core_locations = transport["core_locations"] details = { "config_idx": config_idx, "n_channels": n_channels, "syncframes": transport["syncframes"], } if n_channels == 7: if not core_locations or chanmap is None: raise UnsupportedVariantError( "eac3", "core_extension_pair", "7 通道配置需要独立子流与依赖子流 chanmap 同时在场", frame=frame, details=details) pair = extra_pair(core_locations, chanmap) details["chanmap"] = chanmap details["chanmap_locations"] = expand_chanmap(chanmap) details["extra_pair"] = list(pair) if pair != expected_pair: if diagnostics is not None: diagnostics.append({ "stage": "eac3", "variant": "chanmap_cfg_mismatch", "frame": frame, "message": "依赖子流 chanmap 声明的额外对与 joc_dmx_config_idx 不一致," "按 chanmap 的通道码映射,音频不受影响", "details": {**details, "expected_pair": list(expected_pair or ())}, }) elif chanmap is not None and extra_pair(core_locations, chanmap): raise UnsupportedVariantError( "eac3", "core_channel_count_mismatch", "5 通道配置的依赖子流声明了额外通道", frame=frame, details={**details, "chanmap_locations": expand_chanmap(chanmap)}) # 校验 3:核心通道数(子流声明汇总,去掉 LFE) declared = set(core_locations) if chanmap is not None: declared |= set(expand_chanmap(chanmap)) declared -= {"LFE", "LFE2"} details["declared_full_band_channels"] = len(declared) if len(declared) != n_channels: raise UnsupportedVariantError( "eac3", "core_channel_count_mismatch", "子流声明的全频段通道数与 joc_dmx_config_idx 不一致", frame=frame, details=details) if bed_channels is not None: core_positions = [] if transport is not None: core_positions = list(transport["core_locations"]) if transport["chanmap"] is not None: core_positions += expand_chanmap(transport["chanmap"]) if not _bed_covers_core(bed_channels, core_positions): if diagnostics is not None: diagnostics.append({ "stage": "oamd", "variant": "bed_mask_cfg_mismatch", "frame": frame, "message": "OAMD bed 布局没有覆盖核心子流的全频段声道,只影响 bed 槽位记录," "音频不受影响", "details": { "config_idx": config_idx, "bed_channels": [list(instance) for instance in bed_channels], "bed_layout": (bed_layout_info or {}).get("name"), "core_positions": core_positions, }, }) class DirectPayloadIndex: """One-pass in-memory view of contiguous EMDF containers in an E-AC-3 file. The optional cache directory keeps the existing ``frames.csv + emdf/`` contract, but normal processing reuses the containers already parsed during the scan instead of reading and parsing thousands of small files again. 音频帧 = 同一 (编码, strmtyp, substreamid) 组合出现一次为止的同步帧组; JOC 通常只在依赖子流里,核心子流(AC-3 或 E-AC-3 独立子流)没有 EMDF。 """ def __init__(self, rows, subpayloads, sample_offsets, directory=None, transports=None, diagnostics=None, config_idx=None, n_channels=None, bed_assignments=None, bed_only=False): self.rows = rows self._subpayloads = subpayloads self._sample_offsets = sample_offsets self.directory = Path(directory) if directory is not None else None self.transports = transports if transports is not None else [] self.diagnostics = diagnostics if diagnostics is not None else [] self.config_idx = config_idx self.n_channels = n_channels # OAMD bed 声明(内容声床布局):bed 对象没有位置字段,位置由布局决定。 self.bed_assignments = bed_assignments if bed_assignments is not None else [] self.bed_layout = bed_layout(self.bed_assignments) self.bed_only = bool(bed_only) @property def bed_channels(self): """bed 声道标签(JOC 对象槽顺序);非 bed-only 内容返回空。 bed 声道是固定通道,只有整个 program 都由 bed 组成时 15 路 JOC 对象才逐槽 对应 bed 声道。含动态对象的内容仍按 OAMD 坐标渲染。 """ if not self.bed_only: return () layout = self.bed_layout or {} return tuple(layout.get("channels") or ()) def transport(self, row): return self.transports[int(row["frame"])] if self.transports else None def subpayloads(self, row): return self._subpayloads[int(row["frame"])] def subpayload_sample_offset(self, row, payload_id): offsets = self._sample_offsets[int(row["frame"])] return 0 if offsets is None else int(offsets.get(payload_id, 0)) @classmethod def from_eac3(cls, eac3_path, max_frames=None, cache_dir=None): cache_dir = Path(cache_dir) if cache_dir is not None else None emdf_dir = None if cache_dir is not None: emdf_dir = cache_dir / "emdf" emdf_dir.mkdir(parents=True, exist_ok=True) data = Path(eac3_path).read_bytes() rows = [] payloads = [] offsets = [] transports = [] diagnostics = [] config_idx = None n_channels = None missing_joc_frames = 0 bed_assignments = [] bed_only = False bed_layout_info = None groups = audio_frame_groups(iter_syncframes(data)) for frame_number, group in enumerate(groups): if max_frames is not None and frame_number >= max_frames: break transport = _transport_record(group) transports.append(transport) container = None for sync in group: chunk = data[sync.offset:sync.offset + sync.size] try: container = find_joc_emdf(chunk, usable=_joc_pair_score, diagnostics=diagnostics, frame_number=frame_number) except UnsupportedVariantError as exc: if exc.variant != "no_contiguous_joc_container": exc.add_context(frame=frame_number, details={"syncframe_bytes": len(chunk)}) raise continue except EmdfError as exc: raise UnsupportedVariantError( "emdf_transport", "container_syntax", "EMDF 容器语法无法解析", frame=frame_number, details={"syncframe_bytes": len(chunk), "parser_error": str(exc)}) from exc break if container is None: missing_joc_frames += 1 rows.append({ "frame": frame_number, "emdf_hash": "", "emdf_size": 0, "emdf_start_bit": "", "payload_ids": "", "error": "no_joc", }) payloads.append(None) offsets.append(None) continue if 14 in container.payloads: parsed = parse_joc_header(container.payloads[14]) parsed["payload"] = container.payloads[14] frame_bed = (program_bed_summary(container.payloads[11]) if 11 in container.payloads else None) if frame_bed and not bed_assignments and frame_bed["channels"]: bed_assignments = [list(instance) for instance in frame_bed["channels"]] bed_only = bool(frame_bed["bed_only"]) bed_layout_info = bed_layout(bed_assignments) check_cross_layer(parsed, frame=frame_number, transport=transport, bed_channels=(frame_bed["channels"] if frame_bed else None), bed_layout_info=bed_layout_info, diagnostics=diagnostics) if config_idx is None: config_idx = parsed["dmx_config_idx"] n_channels = parsed["n_channels"] digest = hashlib.sha256(container.raw).hexdigest() if emdf_dir is not None: target = emdf_dir / f"{digest}.bin" if not target.is_file(): target.write_bytes(container.raw) rows.append({ "frame": frame_number, "emdf_hash": digest, "emdf_size": len(container.raw), "emdf_start_bit": container.start_bit, "payload_ids": ";".join(str(x) for x in container.payloads), "error": "", }) payloads.append(container.payloads) offsets.append(container.sample_offsets) if (frame_number + 1) % 1000 == 0: print(f"[metadata] {frame_number + 1} frames", flush=True) if not rows: raise EmdfError("E-AC-3 输入中没有可处理的同步帧") if config_idx is None: raise UnsupportedVariantError( "emdf_transport", "no_contiguous_joc_container", "输入中没有找到可连续解析且同时包含 ID11/ID14 的 EMDF 容器", details={"audio_frames": len(rows), "syncframe_bytes": len(data)}) if missing_joc_frames: diagnostics.append({ "stage": "eac3", "variant": "joc_frame_missing", "frame": None, "message": "部分音频帧没有 JOC 元数据,这些帧的对象通道静音", "details": {"frames": missing_joc_frames, "total": len(rows)}, }) if cache_dir is not None: with (cache_dir / "frames.csv").open("w", encoding="utf-8", newline="") as fp: fields = ("frame", "emdf_hash", "emdf_size", "emdf_start_bit", "payload_ids", "error") writer = csv.DictWriter(fp, fieldnames=fields) writer.writeheader() writer.writerows(rows) return cls(rows, payloads, offsets, cache_dir, transports, diagnostics, config_idx, n_channels, bed_assignments, bed_only) def __len__(self): return len(self.rows) class PayloadIndex: """旧 evolution sidecar 或直接 EMDF sidecar 的严格顺序视图。""" def __init__(self, directory): self.directory = Path(directory) csv_path = self.directory / "frames.csv" self.payload_dir = self.directory / "payloads" self.emdf_dir = self.directory / "emdf" if not csv_path.is_file() or not (self.payload_dir.is_dir() or self.emdf_dir.is_dir()): raise FileNotFoundError( f"元数据目录需要 frames.csv 和 payloads/ 或 emdf/: {self.directory}") with csv_path.open(encoding="utf-8", newline="") as fp: self.rows = list(csv.DictReader(fp)) if not self.rows: raise ValueError("frames.csv 为空") self._sub_cache = {} self._sample_offset_cache = {} def payload(self, row): payload_hash = row.get("payload_hash", "") if not payload_hash: raise ValueError(f"frame {row.get('frame', '?')} 缺少 evolution payload") path = self.payload_dir / f"{payload_hash}.bin" if not path.is_file(): raise FileNotFoundError(path) return path.read_bytes() def subpayloads(self, row): """返回 ``{payload_id: bytes}``,屏蔽两种 sidecar 容器的差异。""" emdf_hash = row.get("emdf_hash", "") if emdf_hash: key = ("emdf", emdf_hash) if key not in self._sub_cache: path = self.emdf_dir / f"{emdf_hash}.bin" if not path.is_file(): raise FileNotFoundError(path) container = parse_container(path.read_bytes()) self._sub_cache[key] = container.payloads self._sample_offset_cache[key] = container.sample_offsets return self._sub_cache[key] payload_hash = row.get("payload_hash", "") key = ("evolution", payload_hash) if key not in self._sub_cache: self._sub_cache[key], _ = unpack_evolution(self.payload(row), loose=True) self._sample_offset_cache[key] = {} return self._sub_cache[key] def subpayload_sample_offset(self, row, payload_id): """返回 EMDF payload 的外层 sample offset;旧 sidecar 没有该字段时为 0。""" self.subpayloads(row) emdf_hash = row.get("emdf_hash", "") key = (("emdf", emdf_hash) if emdf_hash else ("evolution", row.get("payload_hash", ""))) return int(self._sample_offset_cache.get(key, {}).get(payload_id, 0)) def __len__(self): return len(self.rows) def _frame_record(frame, parsed, state): present = [i for i, obj in enumerate(parsed["objs"]) if obj["present"]] sparse = [i for i in present if parsed["objs"][i]["sparse"]] bands = Counter(parsed["objs"][i]["n_bands"] for i in present) positions = [] for obj in range(1, 16): q1, q2, q3 = (state.q[(obj, key)] for key in ("q1", "q2", "q3")) x, y, z = q_to_adm_xyz(q1, q2, q3) positions.append([round(float(x), 7), round(float(y), 7), round(float(z), 7)]) return { "frame": frame, "sequence": parsed["seq_count_bits"], "downmix_config": parsed["dmx_config_idx"], "extension_config": parsed["ext_config_idx"], "objects_declared": parsed["n_objects"], "objects_present": present, "sparse_objects": sparse, "parameter_bands": {str(k): v for k, v in sorted(bands.items())}, "clipgain": parsed["clipgain"], "oamd_xyz": positions, } def inspect(index, limit=None, print_frames=False): """逐帧完整解析 ID11/ID14,并返回可 JSON 序列化的汇总。""" rows = index.rows if limit is None else index.rows[:limit] oamd = JocFieldState() frame_records = [] configs = Counter() active = Counter() band_totals = Counter() sparse_counts = Counter() clipgains = [] for seq, row in enumerate(rows): frame_number = int(row.get("frame", seq)) try: subs = index.subpayloads(row) except UnsupportedVariantError as exc: exc.add_context(frame=frame_number) raise except Exception as exc: raise UnsupportedVariantError( "metadata_container", "sidecar_or_emdf_parse", "元数据容器无法解析", frame=frame_number, details={"exception_type": type(exc).__name__, "parser_error": str(exc)}) from exc if subs is None: # 该音频帧没有任何 JOC EMDF(例如编码器未写首帧元数据):对象静音。 frame_records.append({"frame": frame_number, "no_joc": True}) continue if 11 not in subs or 14 not in subs: raise UnsupportedVariantError( "emdf_payloads", "missing_required_payload", "EMDF 缺少 ID11/OAMD 或 ID14/JOC", frame=frame_number, details={ "payload_ids": list(subs), "payload_lengths": {str(k): len(v) for k, v in subs.items()}, }) try: oamd.apply(frame_update_values(subs[11])) except UnsupportedVariantError as exc: exc.add_context(frame=frame_number, details={"payload_id": 11}) raise except Exception as exc: raise UnsupportedVariantError( "oamd", "payload_syntax", "OAMD 字段解析失败", frame=frame_number, details={ "payload_id": 11, "payload": bytes_descriptor(subs[11]), "exception_type": type(exc).__name__, "parser_error": str(exc), }) from exc try: parsed = parse_joc(subs[14]) except UnsupportedVariantError as exc: exc.add_context(frame=frame_number, details={"payload_id": 14}) raise except Exception as exc: payload = subs[14] header = {} if len(payload) >= 4: value = int.from_bytes(payload[:4], "big") header = { "downmix_config": (value >> 29) & 7, "objects_minus_one": (value >> 23) & 63, "extension_config": (value >> 20) & 7, } raise UnsupportedVariantError( "joc", "payload_syntax", "JOC ID14 解析失败", frame=frame_number, details={ "payload_id": 14, "header_probe": header, "payload": bytes_descriptor(payload), "exception_type": type(exc).__name__, "parser_error": str(exc), "repair_hint": "检查 JOC header、对象数、参数带、Huffman 或扩展字段", }) from exc if parsed["n_channels"] not in (5, 7): raise UnsupportedVariantError( "joc", "unsupported_configuration", "JOC 核心通道数超出当前渲染器范围", frame=frame_number, details={ "downmix_config": parsed["dmx_config_idx"], "core_channels": parsed["n_channels"], "objects": parsed["n_objects"], "extension_config": parsed["ext_config_idx"], "payload": bytes_descriptor(subs[14]), }) check_cross_layer( parsed, frame=frame_number, transport=(index.transport(row) if hasattr(index, "transport") else None), bed_channels=program_bed_channels(subs[11])) rec = _frame_record(frame_number, parsed, oamd) configs[(parsed["dmx_config_idx"], parsed["ext_config_idx"], parsed["n_channels"], parsed["n_objects"])] += 1 active[len(rec["objects_present"])] += 1 band_totals.update({int(k): v for k, v in rec["parameter_bands"].items()}) sparse_counts[len(rec["sparse_objects"])] += 1 clipgains.append(float(parsed["clipgain"])) if print_frames: print(json.dumps(rec, ensure_ascii=False, separators=(",", ":"))) frame_records.append(rec) summary = { "frames": len(rows), "frame_samples": 1536, "sample_rate": 48000, "duration_sec": len(rows) * 1536 / 48000, "bed_layout": (getattr(index, "bed_layout", None) or {}).get("name"), "bed_channels": [ BED_CHANNEL_NAMES.get(label, label) for label in getattr(index, "bed_channels", ())], "configurations": [ {"downmix_config": k[0], "extension_config": k[1], "core_channels": k[2], "objects": k[3], "frames": count} for k, count in sorted(configs.items()) ], "active_object_count_histogram": {str(k): v for k, v in sorted(active.items())}, "parameter_band_totals": {str(k): v for k, v in sorted(band_totals.items())}, "sparse_object_count_histogram": {str(k): v for k, v in sorted(sparse_counts.items())}, "clipgain_min": min(clipgains), "clipgain_max": max(clipgains), "first_frame": frame_records[0], "last_frame": frame_records[-1], } emdf_rows = [row for row in rows if row.get("emdf_start_bit", "") != ""] if emdf_rows: starts = [int(row["emdf_start_bit"]) for row in emdf_rows] id_sets = Counter(row.get("payload_ids", "") for row in emdf_rows) summary["emdf_transport"] = { "continuous_containers": len(emdf_rows), "start_bit_min": min(starts), "start_bit_max": max(starts), "bit_alignment_histogram": { str(k): v for k, v in sorted(Counter(x & 7 for x in starts).items()) }, "payload_id_order_histogram": dict(sorted(id_sets.items())), } return summary def write_summary(index, output, limit=None, print_frames=False): summary = inspect(index, limit=limit, print_frames=print_frames) output = Path(output) output.write_text(json.dumps(summary, ensure_ascii=False, indent=2), encoding="utf-8") return summary