@invintusmedia/tomp4 1.3.0 → 1.4.0

package/src/codecs/h264-sps-pps.js

@@ -0,0 +1,483 @@
+/**
+ * H.264 SPS and PPS Parsers
+ *
+ * Full parsing of Sequence Parameter Set and Picture Parameter Set
+ * NAL units, extracting all fields needed for decoding.
+ *
+ * Reference: ITU-T H.264, Section 7.3.2.1 (SPS) and 7.3.2.2 (PPS)
+ *
+ * @module codecs/h264-sps-pps
+ */
+
+import { BitstreamReader, removeEmulationPrevention } from './h264-cabac.js';
+
+// ══════════════════════════════════════════════════════════
+// SPS Parser
+// ══════════════════════════════════════════════════════════
+
+/**
+ * Parse a full Sequence Parameter Set.
+ * @param {Uint8Array} nalUnit - SPS NAL unit data (including NAL header byte)
+ * @returns {object} Parsed SPS fields
+ */
+export function parseSPSFull(nalUnit) {
+  const rbsp = removeEmulationPrevention(nalUnit);
+  const bs = new BitstreamReader(rbsp, 8); // skip NAL header
+
+  const sps = {};
+  sps.profile_idc = bs.readBits(8);
+  sps.constraint_set0_flag = bs.readBit();
+  sps.constraint_set1_flag = bs.readBit();
+  sps.constraint_set2_flag = bs.readBit();
+  sps.constraint_set3_flag = bs.readBit();
+  sps.constraint_set4_flag = bs.readBit();
+  sps.constraint_set5_flag = bs.readBit();
+  bs.readBits(2); // reserved_zero_2bits
+  sps.level_idc = bs.readBits(8);
+  sps.seq_parameter_set_id = bs.readUE();
+
+  // High profile extensions
+  sps.chroma_format_idc = 1; // default
+  sps.separate_colour_plane_flag = 0;
+  sps.bit_depth_luma_minus8 = 0;
+  sps.bit_depth_chroma_minus8 = 0;
+  sps.qpprime_y_zero_transform_bypass_flag = 0;
+  sps.seq_scaling_matrix_present_flag = 0;
+  sps.scalingLists4x4 = null;
+  sps.scalingLists8x8 = null;
+
+  const isHigh = [100, 110, 122, 244, 44, 83, 86, 118, 128, 138, 139, 134].includes(sps.profile_idc);
+  if (isHigh) {
+    sps.chroma_format_idc = bs.readUE();
+    if (sps.chroma_format_idc === 3) {
+      sps.separate_colour_plane_flag = bs.readBit();
+    }
+    sps.bit_depth_luma_minus8 = bs.readUE();
+    sps.bit_depth_chroma_minus8 = bs.readUE();
+    sps.qpprime_y_zero_transform_bypass_flag = bs.readBit();
+    sps.seq_scaling_matrix_present_flag = bs.readBit();
+
+    if (sps.seq_scaling_matrix_present_flag) {
+      const numLists = sps.chroma_format_idc !== 3 ? 8 : 12;
+      sps.scalingLists4x4 = [];
+      sps.scalingLists8x8 = [];
+      for (let i = 0; i < numLists; i++) {
+        const present = bs.readBit();
+        if (present) {
+          if (i < 6) {
+            sps.scalingLists4x4.push(parseScalingList(bs, 16));
+          } else {
+            sps.scalingLists8x8.push(parseScalingList(bs, 64));
+          }
+        } else {
+          if (i < 6) sps.scalingLists4x4.push(null);
+          else sps.scalingLists8x8.push(null);
+        }
+      }
+    }
+  }
+
+  sps.log2_max_frame_num_minus4 = bs.readUE();
+  sps.MaxFrameNum = 1 << (sps.log2_max_frame_num_minus4 + 4);
+
+  sps.pic_order_cnt_type = bs.readUE();
+  if (sps.pic_order_cnt_type === 0) {
+    sps.log2_max_pic_order_cnt_lsb_minus4 = bs.readUE();
+    sps.MaxPicOrderCntLsb = 1 << (sps.log2_max_pic_order_cnt_lsb_minus4 + 4);
+  } else if (sps.pic_order_cnt_type === 1) {
+    sps.delta_pic_order_always_zero_flag = bs.readBit();
+    sps.offset_for_non_ref_pic = bs.readSE();
+    sps.offset_for_top_to_bottom_field = bs.readSE();
+    sps.num_ref_frames_in_pic_order_cnt_cycle = bs.readUE();
+    sps.offset_for_ref_frame = [];
+    for (let i = 0; i < sps.num_ref_frames_in_pic_order_cnt_cycle; i++) {
+      sps.offset_for_ref_frame.push(bs.readSE());
+    }
+  }
+
+  sps.max_num_ref_frames = bs.readUE();
+  sps.gaps_in_frame_num_value_allowed_flag = bs.readBit();
+
+  sps.pic_width_in_mbs_minus1 = bs.readUE();
+  sps.pic_height_in_map_units_minus1 = bs.readUE();
+
+  sps.frame_mbs_only_flag = bs.readBit();
+  if (!sps.frame_mbs_only_flag) {
+    sps.mb_adaptive_frame_field_flag = bs.readBit();
+  } else {
+    sps.mb_adaptive_frame_field_flag = 0;
+  }
+
+  sps.direct_8x8_inference_flag = bs.readBit();
+
+  sps.frame_cropping_flag = bs.readBit();
+  sps.frame_crop_left_offset = 0;
+  sps.frame_crop_right_offset = 0;
+  sps.frame_crop_top_offset = 0;
+  sps.frame_crop_bottom_offset = 0;
+  if (sps.frame_cropping_flag) {
+    sps.frame_crop_left_offset = bs.readUE();
+    sps.frame_crop_right_offset = bs.readUE();
+    sps.frame_crop_top_offset = bs.readUE();
+    sps.frame_crop_bottom_offset = bs.readUE();
+  }
+
+  sps.vui_parameters_present_flag = bs.readBit();
+  // We skip VUI parsing — not needed for decoding
+
+  // Derived values
+  sps.PicWidthInMbs = sps.pic_width_in_mbs_minus1 + 1;
+  sps.PicHeightInMapUnits = sps.pic_height_in_map_units_minus1 + 1;
+  sps.FrameHeightInMbs = (2 - sps.frame_mbs_only_flag) * sps.PicHeightInMapUnits;
+  sps.PicHeightInMbs = sps.FrameHeightInMbs; // frame mode only for now
+  sps.PicSizeInMbs = sps.PicWidthInMbs * sps.PicHeightInMbs;
+
+  const cropUnitX = sps.chroma_format_idc === 0 ? 1 : 2;
+  const cropUnitY = (sps.chroma_format_idc === 0 ? 1 : 2) * (2 - sps.frame_mbs_only_flag);
+  sps.width = sps.PicWidthInMbs * 16 - (sps.frame_crop_left_offset + sps.frame_crop_right_offset) * cropUnitX;
+  sps.height = sps.PicHeightInMbs * 16 - (sps.frame_crop_top_offset + sps.frame_crop_bottom_offset) * cropUnitY;
+
+  // ChromaArrayType
+  sps.ChromaArrayType = sps.separate_colour_plane_flag ? 0 : sps.chroma_format_idc;
+  sps.SubWidthC = sps.chroma_format_idc === 1 || sps.chroma_format_idc === 2 ? 2 : 1;
+  sps.SubHeightC = sps.chroma_format_idc === 1 ? 2 : 1;
+  sps.MbWidthC = 16 / sps.SubWidthC;
+  sps.MbHeightC = 16 / sps.SubHeightC;
+
+  sps.BitDepthY = 8 + sps.bit_depth_luma_minus8;
+  sps.BitDepthC = 8 + sps.bit_depth_chroma_minus8;
+  sps.QpBdOffsetY = 6 * sps.bit_depth_luma_minus8;
+  sps.QpBdOffsetC = 6 * sps.bit_depth_chroma_minus8;
+
+  return sps;
+}
+
+function parseScalingList(bs, size) {
+  const list = new Int32Array(size);
+  let lastScale = 8;
+  let nextScale = 8;
+  for (let i = 0; i < size; i++) {
+    if (nextScale !== 0) {
+      const deltaScale = bs.readSE();
+      nextScale = (lastScale + deltaScale + 256) % 256;
+    }
+    list[i] = nextScale === 0 ? lastScale : nextScale;
+    lastScale = list[i];
+  }
+  return list;
+}
+
+// ══════════════════════════════════════════════════════════
+// PPS Parser
+// ══════════════════════════════════════════════════════════
+
+/**
+ * Parse a full Picture Parameter Set.
+ * @param {Uint8Array} nalUnit - PPS NAL unit data (including NAL header byte)
+ * @param {object} sps - The associated SPS (needed for some fields)
+ * @returns {object} Parsed PPS fields
+ */
+export function parsePPSFull(nalUnit, sps) {
+  const rbsp = removeEmulationPrevention(nalUnit);
+  const bs = new BitstreamReader(rbsp, 8); // skip NAL header
+
+  const pps = {};
+  pps.pic_parameter_set_id = bs.readUE();
+  pps.seq_parameter_set_id = bs.readUE();
+  pps.entropy_coding_mode_flag = bs.readBit(); // 0=CAVLC, 1=CABAC
+  pps.bottom_field_pic_order_in_frame_present_flag = bs.readBit();
+
+  pps.num_slice_groups_minus1 = bs.readUE();
+  if (pps.num_slice_groups_minus1 > 0) {
+    // Slice group map — rarely used, skip for now
+    pps.slice_group_map_type = bs.readUE();
+    // TODO: parse slice group map if needed
+    throw new Error('Slice groups not supported');
+  }
+
+  pps.num_ref_idx_l0_default_active_minus1 = bs.readUE();
+  pps.num_ref_idx_l1_default_active_minus1 = bs.readUE();
+  pps.weighted_pred_flag = bs.readBit();
+  pps.weighted_bipred_idc = bs.readBits(2);
+  pps.pic_init_qp_minus26 = bs.readSE();
+  pps.pic_init_qs_minus26 = bs.readSE();
+  pps.chroma_qp_index_offset = bs.readSE();
+  pps.deblocking_filter_control_present_flag = bs.readBit();
+  pps.constrained_intra_pred_flag = bs.readBit();
+  pps.redundant_pic_cnt_present_flag = bs.readBit();
+
+  // High profile extensions
+  pps.transform_8x8_mode_flag = 0;
+  pps.pic_scaling_matrix_present_flag = 0;
+  pps.second_chroma_qp_index_offset = pps.chroma_qp_index_offset;
+
+  if (bs.bitsLeft > 8) {
+    // More RBSP data → High profile extensions
+    pps.transform_8x8_mode_flag = bs.readBit();
+    pps.pic_scaling_matrix_present_flag = bs.readBit();
+    if (pps.pic_scaling_matrix_present_flag) {
+      const numLists = 6 + (sps?.chroma_format_idc !== 3 ? 2 : 6) * pps.transform_8x8_mode_flag;
+      for (let i = 0; i < numLists; i++) {
+        const present = bs.readBit();
+        if (present) {
+          parseScalingList(bs, i < 6 ? 16 : 64);
+        }
+      }
+    }
+    pps.second_chroma_qp_index_offset = bs.readSE();
+  }
+
+  // Derived
+  pps.SliceQPY = 26 + pps.pic_init_qp_minus26;
+
+  return pps;
+}
+
+// ══════════════════════════════════════════════════════════
+// Slice Header Parser
+// ══════════════════════════════════════════════════════════
+
+/**
+ * Parse a slice header from a slice NAL unit.
+ * @param {Uint8Array} nalUnit - Slice NAL unit (type 1 or 5)
+ * @param {object} sps - Active SPS
+ * @param {object} pps - Active PPS
+ * @returns {object} Parsed slice header + bit position where data begins
+ */
+export function parseSliceHeader(nalUnit, sps, pps) {
+  const rbsp = removeEmulationPrevention(nalUnit);
+  const bs = new BitstreamReader(rbsp, 0);
+
+  // NAL header
+  const forbidden_zero_bit = bs.readBit();
+  const nal_ref_idc = bs.readBits(2);
+  const nal_unit_type = bs.readBits(5);
+
+  const sh = {};
+  sh.nal_ref_idc = nal_ref_idc;
+  sh.nal_unit_type = nal_unit_type;
+  sh.isIDR = nal_unit_type === 5;
+
+  sh.first_mb_in_slice = bs.readUE();
+  sh.slice_type = bs.readUE();
+  // Normalize slice type (0-4 and 5-9 map to the same types)
+  sh.slice_type_mod5 = sh.slice_type % 5;
+  sh.isI = sh.slice_type_mod5 === 2;
+  sh.isP = sh.slice_type_mod5 === 0;
+  sh.isB = sh.slice_type_mod5 === 1;
+
+  sh.pic_parameter_set_id = bs.readUE();
+
+  if (sps.separate_colour_plane_flag) {
+    sh.colour_plane_id = bs.readBits(2);
+  }
+
+  sh.frame_num = bs.readBits(sps.log2_max_frame_num_minus4 + 4);
+
+  sh.field_pic_flag = 0;
+  sh.bottom_field_flag = 0;
+  if (!sps.frame_mbs_only_flag) {
+    sh.field_pic_flag = bs.readBit();
+    if (sh.field_pic_flag) {
+      sh.bottom_field_flag = bs.readBit();
+    }
+  }
+
+  if (sh.isIDR) {
+    sh.idr_pic_id = bs.readUE();
+  }
+
+  sh.pic_order_cnt_lsb = 0;
+  sh.delta_pic_order_cnt_bottom = 0;
+  sh.delta_pic_order_cnt = [0, 0];
+
+  if (sps.pic_order_cnt_type === 0) {
+    sh.pic_order_cnt_lsb = bs.readBits(sps.log2_max_pic_order_cnt_lsb_minus4 + 4);
+    if (pps.bottom_field_pic_order_in_frame_present_flag && !sh.field_pic_flag) {
+      sh.delta_pic_order_cnt_bottom = bs.readSE();
+    }
+  } else if (sps.pic_order_cnt_type === 1 && !sps.delta_pic_order_always_zero_flag) {
+    sh.delta_pic_order_cnt[0] = bs.readSE();
+    if (pps.bottom_field_pic_order_in_frame_present_flag && !sh.field_pic_flag) {
+      sh.delta_pic_order_cnt[1] = bs.readSE();
+    }
+  }
+
+  sh.redundant_pic_cnt = 0;
+  if (pps.redundant_pic_cnt_present_flag) {
+    sh.redundant_pic_cnt = bs.readUE();
+  }
+
+  // P/B slice specific
+  sh.direct_spatial_mv_pred_flag = 0;
+  sh.num_ref_idx_active_override_flag = 0;
+  sh.num_ref_idx_l0_active_minus1 = pps.num_ref_idx_l0_default_active_minus1;
+  sh.num_ref_idx_l1_active_minus1 = pps.num_ref_idx_l1_default_active_minus1;
+
+  if (sh.isB) {
+    sh.direct_spatial_mv_pred_flag = bs.readBit();
+  }
+
+  if (sh.isP || sh.isB) {
+    sh.num_ref_idx_active_override_flag = bs.readBit();
+    if (sh.num_ref_idx_active_override_flag) {
+      sh.num_ref_idx_l0_active_minus1 = bs.readUE();
+      if (sh.isB) {
+        sh.num_ref_idx_l1_active_minus1 = bs.readUE();
+      }
+    }
+  }
+
+  // Reference picture list modification
+  sh.ref_pic_list_modification_l0 = null;
+  sh.ref_pic_list_modification_l1 = null;
+  if (!sh.isI) {
+    // ref_pic_list_modification()
+    const l0_flag = bs.readBit();
+    if (l0_flag) {
+      sh.ref_pic_list_modification_l0 = [];
+      while (true) {
+        const op = bs.readUE();
+        if (op === 3) break;
+        const val = bs.readUE();
+        sh.ref_pic_list_modification_l0.push({ op, val });
+      }
+    }
+    if (sh.isB) {
+      const l1_flag = bs.readBit();
+      if (l1_flag) {
+        sh.ref_pic_list_modification_l1 = [];
+        while (true) {
+          const op = bs.readUE();
+          if (op === 3) break;
+          const val = bs.readUE();
+          sh.ref_pic_list_modification_l1.push({ op, val });
+        }
+      }
+    }
+  }
+
+  // Weighted prediction
+  sh.luma_weight_l0 = null;
+  sh.chroma_weight_l0 = null;
+  sh.luma_weight_l1 = null;
+  sh.chroma_weight_l1 = null;
+  if ((pps.weighted_pred_flag && sh.isP) || (pps.weighted_bipred_idc === 1 && sh.isB)) {
+    // pred_weight_table()
+    sh.luma_log2_weight_denom = bs.readUE();
+    if (sps.ChromaArrayType !== 0) {
+      sh.chroma_log2_weight_denom = bs.readUE();
+    }
+    sh.luma_weight_l0 = [];
+    sh.chroma_weight_l0 = [];
+    for (let i = 0; i <= sh.num_ref_idx_l0_active_minus1; i++) {
+      const luma_flag = bs.readBit();
+      if (luma_flag) {
+        sh.luma_weight_l0.push({ weight: bs.readSE(), offset: bs.readSE() });
+      } else {
+        sh.luma_weight_l0.push({ weight: 1 << sh.luma_log2_weight_denom, offset: 0 });
+      }
+      if (sps.ChromaArrayType !== 0) {
+        const chroma_flag = bs.readBit();
+        if (chroma_flag) {
+          sh.chroma_weight_l0.push([
+            { weight: bs.readSE(), offset: bs.readSE() },
+            { weight: bs.readSE(), offset: bs.readSE() },
+          ]);
+        } else {
+          sh.chroma_weight_l0.push([
+            { weight: 1 << sh.chroma_log2_weight_denom, offset: 0 },
+            { weight: 1 << sh.chroma_log2_weight_denom, offset: 0 },
+          ]);
+        }
+      }
+    }
+    if (sh.isB) {
+      sh.luma_weight_l1 = [];
+      sh.chroma_weight_l1 = [];
+      for (let i = 0; i <= sh.num_ref_idx_l1_active_minus1; i++) {
+        const luma_flag = bs.readBit();
+        if (luma_flag) {
+          sh.luma_weight_l1.push({ weight: bs.readSE(), offset: bs.readSE() });
+        } else {
+          sh.luma_weight_l1.push({ weight: 1 << sh.luma_log2_weight_denom, offset: 0 });
+        }
+        if (sps.ChromaArrayType !== 0) {
+          const chroma_flag = bs.readBit();
+          if (chroma_flag) {
+            sh.chroma_weight_l1.push([
+              { weight: bs.readSE(), offset: bs.readSE() },
+              { weight: bs.readSE(), offset: bs.readSE() },
+            ]);
+          } else {
+            sh.chroma_weight_l1.push([
+              { weight: 1 << sh.chroma_log2_weight_denom, offset: 0 },
+              { weight: 1 << sh.chroma_log2_weight_denom, offset: 0 },
+            ]);
+          }
+        }
+      }
+    }
+  }
+
+  // Decoded reference picture marking
+  if (nal_ref_idc !== 0) {
+    // dec_ref_pic_marking()
+    if (sh.isIDR) {
+      sh.no_output_of_prior_pics_flag = bs.readBit();
+      sh.long_term_reference_flag = bs.readBit();
+    } else {
+      sh.adaptive_ref_pic_marking_mode_flag = bs.readBit();
+      if (sh.adaptive_ref_pic_marking_mode_flag) {
+        sh.mmco = [];
+        while (true) {
+          const op = bs.readUE();
+          if (op === 0) break;
+          const entry = { op };
+          if (op === 1 || op === 3) entry.difference_of_pic_nums_minus1 = bs.readUE();
+          if (op === 2) entry.long_term_pic_num = bs.readUE();
+          if (op === 3 || op === 6) entry.long_term_frame_idx = bs.readUE();
+          if (op === 4) entry.max_long_term_frame_idx_plus1 = bs.readUE();
+          sh.mmco.push(entry);
+        }
+      }
+    }
+  }
+
+  // CABAC init
+  sh.cabac_init_idc = 0;
+  if (pps.entropy_coding_mode_flag && !sh.isI) {
+    sh.cabac_init_idc = bs.readUE();
+  }
+
+  sh.slice_qp_delta = bs.readSE();
+  sh.SliceQPY = 26 + pps.pic_init_qp_minus26 + sh.slice_qp_delta;
+
+  // SP/SI slice specific (rarely used)
+  if (sh.slice_type_mod5 === 3 || sh.slice_type_mod5 === 4) {
+    if (sh.slice_type_mod5 === 3) {
+      sh.sp_for_switch_flag = bs.readBit();
+    }
+    sh.slice_qs_delta = bs.readSE();
+  }
+
+  // Deblocking filter
+  sh.disable_deblocking_filter_idc = 0;
+  sh.slice_alpha_c0_offset_div2 = 0;
+  sh.slice_beta_offset_div2 = 0;
+  if (pps.deblocking_filter_control_present_flag) {
+    sh.disable_deblocking_filter_idc = bs.readUE();
+    if (sh.disable_deblocking_filter_idc !== 1) {
+      sh.slice_alpha_c0_offset_div2 = bs.readSE();
+      sh.slice_beta_offset_div2 = bs.readSE();
+    }
+  }
+
+  // Record where slice data begins (for CABAC or CAVLC)
+  sh.headerBitLength = bs.bitPos;
+  sh._rbsp = rbsp; // keep for CABAC init
+
+  return sh;
+}
+
+export default { parseSPSFull, parsePPSFull, parseSliceHeader };

package/src/codecs/h264-tables.js

@@ -0,0 +1,217 @@
+/**
+ * H.264 Constant Tables
+ *
+ * Lookup tables from the H.264/AVC specification (ITU-T H.264).
+ * Used by both the decoder and encoder.
+ *
+ * @module codecs/h264-tables
+ */
+
+// ══════════════════════════════════════════════════════════
+// CABAC Range Table (Table 9-48)
+// rangeTabLPS[pStateIdx][qCodIRangeIdx]
+// ══════════════════════════════════════════════════════════
+
+export const rangeTabLPS = [
+  [128,176,208,240],[128,167,197,227],[128,158,187,216],[123,150,178,205],
+  [116,142,169,195],[111,135,160,185],[105,128,152,175],[100,122,144,166],
+  [ 95,116,137,158],[ 90,110,130,150],[ 85,104,123,142],[ 81, 99,117,135],
+  [ 77, 94,111,128],[ 73, 89,105,122],[ 69, 85,100,116],[ 66, 80, 95,110],
+  [ 62, 76, 90,104],[ 59, 72, 86, 99],[ 56, 69, 81, 94],[ 53, 65, 77, 89],
+  [ 51, 62, 73, 85],[ 48, 59, 69, 80],[ 46, 56, 66, 76],[ 43, 53, 63, 72],
+  [ 41, 50, 59, 69],[ 39, 48, 56, 65],[ 37, 45, 54, 62],[ 35, 43, 51, 59],
+  [ 33, 41, 48, 56],[ 32, 39, 46, 53],[ 30, 37, 43, 50],[ 29, 35, 41, 48],
+  [ 27, 33, 39, 45],[ 26, 31, 37, 43],[ 24, 30, 35, 41],[ 23, 28, 33, 39],
+  [ 22, 27, 32, 37],[ 21, 26, 30, 35],[ 20, 24, 29, 33],[ 19, 23, 27, 31],
+  [ 18, 22, 26, 30],[ 17, 21, 25, 28],[ 16, 20, 23, 27],[ 15, 19, 22, 25],
+  [ 14, 18, 21, 24],[ 14, 17, 20, 23],[ 13, 16, 19, 22],[ 12, 15, 18, 21],
+  [ 12, 14, 17, 20],[ 11, 14, 16, 19],[ 11, 13, 15, 18],[ 10, 12, 15, 17],
+  [ 10, 12, 14, 16],[  9, 11, 13, 15],[  9, 11, 12, 14],[  8, 10, 12, 14],
+  [  8,  9, 11, 13],[  7,  9, 11, 12],[  7,  9, 10, 12],[  7,  8, 10, 11],
+  [  6,  8,  9, 11],[  6,  7,  9, 10],[  6,  7,  8,  9],[  2,  2,  2,  2],
+];
+
+// ══════════════════════════════════════════════════════════
+// CABAC State Transition Tables (Table 9-49, 9-50)
+// Original tables (pStateIdx only, 64 entries each)
+// ══════════════════════════════════════════════════════════
+
+export const transIdxLPS = [
+   0, 0, 1, 2, 2, 4, 4, 5, 6, 7, 8, 9, 9,11,11,12,
+  13,13,15,15,16,16,18,18,19,19,21,21,22,22,23,24,
+  24,25,26,26,27,27,28,29,29,30,30,30,31,32,32,33,
+  33,33,34,34,35,35,35,36,36,36,37,37,37,38,38,63,
+];
+
+export const transIdxMPS = [
+   1, 2, 3, 4, 5, 6, 7, 8, 9,10,11,12,13,14,15,16,
+  17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,
+  33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,
+  49,50,51,52,53,54,55,56,57,58,59,60,61,62,62,63,
+];
+
+// ══════════════════════════════════════════════════════════
+// CABAC Context Initialization Values (Table 9-12 to 9-23)
+// Each entry is [m, n] where initValue = m * SliceQPy + n
+// Contexts 0-10: mb_type, sub_mb_type, etc.
+// ══════════════════════════════════════════════════════════
+
+// I-slice context init values (cabac_init_idc not used for I-slices)
+// Format: array of [m, n] pairs, indexed by ctxIdx
+export const cabacInitI = [
+  // 0-10: mb_type SI
+  [20,-15],[2,54],[3,74],[20,-15],[2,54],[3,74],[-28,127],[-23,104],[-6,53],[-1,54],[7,51],
+  // 11-23: mb_type I
+  [23,33],[23,2],[21,0],
+  // We need ~460 contexts. The full table is very large.
+  // For practical purposes, we'll initialize from the spec tables at runtime.
+];
+
+// P/B-slice context init values depend on cabac_init_idc (0, 1, or 2)
+// These are used for the majority of syntax elements in P/B slices.
+// The full tables are in the H.264 spec Annex, Tables 9-12 through 9-23.
+
+// ══════════════════════════════════════════════════════════
+// Inverse Zigzag Scan (4x4)
+// Maps coefficient index → [row, col] in the 4x4 block
+// ══════════════════════════════════════════════════════════
+
+export const scanZigzag4x4 = [
+  [0,0],[0,1],[1,0],[2,0],[1,1],[0,2],[0,3],[1,2],
+  [2,1],[3,0],[3,1],[2,2],[1,3],[2,3],[3,2],[3,3],
+];
+
+// Flat index version: position[i] = row * 4 + col
+export const scanOrder4x4 = scanZigzag4x4.map(([r,c]) => r * 4 + c);
+
+// ══════════════════════════════════════════════════════════
+// Inverse Zigzag Scan (8x8)
+// ══════════════════════════════════════════════════════════
+
+export const scanZigzag8x8 = [
+  [0,0],[0,1],[1,0],[2,0],[1,1],[0,2],[0,3],[1,2],
+  [2,1],[3,0],[4,0],[3,1],[2,2],[1,3],[0,4],[0,5],
+  [1,4],[2,3],[3,2],[4,1],[5,0],[6,0],[5,1],[4,2],
+  [3,3],[2,4],[1,5],[0,6],[0,7],[1,6],[2,5],[3,4],
+  [4,3],[5,2],[6,1],[7,0],[7,1],[6,2],[5,3],[4,4],
+  [3,5],[2,6],[1,7],[2,7],[3,6],[4,5],[5,4],[6,3],
+  [7,2],[7,3],[6,4],[5,5],[4,6],[3,7],[4,7],[5,6],
+  [6,5],[7,4],[7,5],[6,6],[5,7],[6,7],[7,6],[7,7],
+];
+
+export const scanOrder8x8 = scanZigzag8x8.map(([r,c]) => r * 8 + c);
+
+// ══════════════════════════════════════════════════════════
+// Quantization
+// ══════════════════════════════════════════════════════════
+
+// LevelScale for 4x4 inverse quantization (Table 8-13)
+// levelScale[qp%6][i][j]
+export const levelScale4x4 = [
+  [10,13,10,13,13,16,13,16,10,13,10,13,13,16,13,16],
+  [11,14,11,14,14,18,14,18,11,14,11,14,14,18,14,18],
+  [13,16,13,16,16,20,16,20,13,16,13,16,16,20,16,20],
+  [14,18,14,18,18,23,18,23,14,18,14,18,18,23,18,23],
+  [16,20,16,20,20,25,20,25,16,20,16,20,20,25,20,25],
+  [18,23,18,23,23,29,23,29,18,23,18,23,23,29,23,29],
+];
+
+// Quantization step sizes for encoder (forward quantization)
+// MF[qp%6] values for 4x4 blocks
+export const quantMF4x4 = [
+  [13107,8066,13107,8066,8066,5243,8066,5243,13107,8066,13107,8066,8066,5243,8066,5243],
+  [11916,7490,11916,7490,7490,4660,7490,4660,11916,7490,11916,7490,7490,4660,7490,4660],
+  [10082,6554,10082,6554,6554,4194,6554,4194,10082,6554,10082,6554,6554,4194,6554,4194],
+  [ 9362,5825, 9362,5825,5825,3647,5825,3647, 9362,5825, 9362,5825,5825,3647,5825,3647],
+  [ 8192,5243, 8192,5243,5243,3355,5243,3355, 8192,5243, 8192,5243,5243,3355,5243,3355],
+  [ 7282,4559, 7282,4559,4559,2893,4559,2893, 7282,4559, 7282,4559,4559,2893,4559,2893],
+];
+
+// ══════════════════════════════════════════════════════════
+// Intra Prediction Modes
+// ══════════════════════════════════════════════════════════
+
+export const INTRA_4x4_V    = 0; // Vertical
+export const INTRA_4x4_H    = 1; // Horizontal
+export const INTRA_4x4_DC   = 2; // DC
+export const INTRA_4x4_DDL  = 3; // Diagonal Down-Left
+export const INTRA_4x4_DDR  = 4; // Diagonal Down-Right
+export const INTRA_4x4_VR   = 5; // Vertical-Right
+export const INTRA_4x4_HD   = 6; // Horizontal-Down
+export const INTRA_4x4_VL   = 7; // Vertical-Left
+export const INTRA_4x4_HU   = 8; // Horizontal-Up
+
+export const INTRA_16x16_V     = 0; // Vertical
+export const INTRA_16x16_H     = 1; // Horizontal
+export const INTRA_16x16_DC    = 2; // DC
+export const INTRA_16x16_PLANE = 3; // Plane
+
+// ══════════════════════════════════════════════════════════
+// Sub-pixel interpolation filter (6-tap)
+// For half-pel motion compensation
+// ══════════════════════════════════════════════════════════
+
+export const SUBPEL_FILTER_TAPS = [1, -5, 20, 20, -5, 1];
+
+// ══════════════════════════════════════════════════════════
+// Macroblock type tables
+// ══════════════════════════════════════════════════════════
+
+// I-slice macroblock types (Table 7-11)
+export const MB_TYPE_I_NxN = 0;   // Intra_4x4 or Intra_8x8
+export const MB_TYPE_I_16x16_BASE = 1; // Intra_16x16 (types 1-24)
+export const MB_TYPE_I_PCM = 25;
+
+// P-slice macroblock types (Table 7-13)
+export const MB_TYPE_P_L0_16x16 = 0;
+export const MB_TYPE_P_L0_L0_16x8 = 1;
+export const MB_TYPE_P_L0_L0_8x16 = 2;
+export const MB_TYPE_P_8x8 = 3;
+export const MB_TYPE_P_8x8ref0 = 4;
+
+// Mapping from I_16x16 mb_type to prediction mode, CBP luma, CBP chroma
+// mb_type 1-24: [intra16x16PredMode, CodedBlockPatternLuma, CodedBlockPatternChroma]
+export const i16x16TypeMap = [
+  // mb_type 1-4: CBP_luma=0, CBP_chroma=0, pred_mode 0-3
+  [0,0,0],[1,0,0],[2,0,0],[3,0,0],
+  // mb_type 5-8: CBP_luma=0, CBP_chroma=1
+  [0,0,1],[1,0,1],[2,0,1],[3,0,1],
+  // mb_type 9-12: CBP_luma=0, CBP_chroma=2
+  [0,0,2],[1,0,2],[2,0,2],[3,0,2],
+  // mb_type 13-16: CBP_luma=15, CBP_chroma=0
+  [0,15,0],[1,15,0],[2,15,0],[3,15,0],
+  // mb_type 17-20: CBP_luma=15, CBP_chroma=1
+  [0,15,1],[1,15,1],[2,15,1],[3,15,1],
+  // mb_type 21-24: CBP_luma=15, CBP_chroma=2
+  [0,15,2],[1,15,2],[2,15,2],[3,15,2],
+];
+
+// ══════════════════════════════════════════════════════════
+// CAVLC Tables (for encoder)
+// ══════════════════════════════════════════════════════════
+
+// coeff_token mapping: given (TotalCoeff, TrailingOnes, nC_range),
+// returns the VLC codeword. Tables 9-5 through 9-8 in the spec.
+// We'll generate these at init time to keep the file manageable.
+
+// Total zeros tables (Table 9-7, 9-8)
+// run_before tables (Table 9-10)
+// These will be implemented in the encoder module.
+
+// ══════════════════════════════════════════════════════════
+// CBP mapping (Table 9-4)
+// Maps codeNum to (CodedBlockPatternLuma, CodedBlockPatternChroma)
+// For Inter and Intra macroblocks
+// ══════════════════════════════════════════════════════════
+
+export const cbpIntraMapping = [
+  47, 31, 15,  0, 23, 27, 29, 30,  7, 11, 13, 14, 39, 43, 45, 46,
+  16,  3,  5, 10, 12, 19, 21, 26, 28, 35, 37, 42, 44,  1,  2,  4,
+   8, 17, 18, 20, 24,  6,  9, 22, 25, 32, 33, 34, 36, 40, 38, 41,
+];
+
+export const cbpInterMapping = [
+   0, 16,  1,  2,  4,  8, 32,  3,  5, 10, 12, 15, 47,  7, 11, 13,
+  14,  6,  9, 31, 35, 37, 42, 44, 33, 34, 36, 40, 39, 43, 45, 46,
+  17, 18, 20, 24, 19, 21, 26, 28, 23, 27, 29, 30, 22, 25, 38, 41,
+];