Upload 12 files

README.md

@@ -0,0 +1,2481 @@
+from __future__ import annotations
+
+import copy
+import math
+import pickle
+import threading
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+import numpy as np
+import cv2
+import torch
+
+
+# ============================================================
+# ComfyUI Node (pose_data + PKL)
+# ============================================================
+
+_GLOBAL_LOCK = threading.Lock()
+
+
+class KPSSmoothPoseDataAndRender:
+    """
+    Сглаживание + рендер позы.
+    Вход: POSEDATA (как объект/dict; обычно приходит из TSLoadPoseDataPickle).
+    Выход: IMAGE (torch [T,H,W,3] float 0..1), POSEDATA (в том же формате, но сглаженный).
+    """
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "pose_data": ("POSEDATA",),  # <-- ВАЖНО: именно POSEDATA
+                "filter_extra_people": ("BOOLEAN", {"default": True}),
+                # общий набор параметров сглаживания (вместо body + face_hands)
+                "smooth_alpha": ("FLOAT", {"default": 0.7, "min": 0.01, "max": 0.99, "step": 0.01}),
+                "gap_frames": ("INT", {"default": 12, "min": 0, "max": 100, "step": 1}),
+                "min_run_frames": ("INT", {"default": 2, "min": 1, "max": 60, "step": 1}),
+                # пороги отрисовки (в инпут добавляем body/hands, face НЕ добавляем)
+                "conf_thresh_body": ("FLOAT", {"default": 0.20, "min": 0.0, "max": 1.0, "step": 0.01}),
+                "conf_thresh_hands": ("FLOAT", {"default": 0.50, "min": 0.0, "max": 1.0, "step": 0.01}),
+            }
+        }
+
+    RETURN_TYPES = ("IMAGE", "POSEDATA")  # <-- ВАЖНО: именно POSEDATA
+    RETURN_NAMES = ("IMAGE", "pose_data")
+    FUNCTION = "run"
+    CATEGORY = "posedata"
+
+    def run(self, pose_data, **kwargs):
+        filter_extra_people = bool(kwargs.get("filter_extra_people", True))
+
+        # общий набор
+        smooth_alpha = float(kwargs.get("smooth_alpha", 0.7))
+        gap_frames = int(kwargs.get("gap_frames", 12))
+        min_run_frames = int(kwargs.get("min_run_frames", 2))
+
+        # пороги рендера
+        conf_thresh_body = float(kwargs.get("conf_thresh_body", 0.20))
+        conf_thresh_hands = float(kwargs.get("conf_thresh_hands", 0.50))
+        conf_thresh_face = 0.20  # <- НЕ добавляем в INPUT, но фиксируем как ты просил
+
+        force_body_18 = bool(kwargs.get("force_body_18", False))
+
+        pose_data = _coerce_pose_data_to_obj(pose_data)
+
+        # pose_data -> frames_json_like
+        frames_json_like, meta_ref = _pose_data_to_kps_frames(pose_data, force_body_18=force_body_18)
+
+        with _GLOBAL_LOCK:
+            old = _snapshot_tunable_globals()
+            try:
+                # BODY
+                globals()["ALPHA_BODY"] = smooth_alpha
+                globals()["SUPER_SMOOTH_ALPHA"] = smooth_alpha
+                globals()["MAX_GAP_FRAMES"] = gap_frames
+                globals()["MIN_RUN_FRAMES"] = min_run_frames
+
+                # FACE+HANDS (dense) тоже от общего набора
+                globals()["DENSE_SUPER_SMOOTH_ALPHA"] = smooth_alpha
+                globals()["DENSE_MAX_GAP_FRAMES"] = gap_frames
+                globals()["DENSE_MIN_RUN_FRAMES"] = min_run_frames
+
+                globals()["FILTER_EXTRA_PEOPLE"] = filter_extra_people
+
+                smoothed_frames = smooth_KPS_json_obj(
+                    frames_json_like,
+                    keep_face_untouched=False,
+                    keep_hands_untouched=False,
+                    filter_extra_people=filter_extra_people,
+                )
+            finally:
+                _restore_tunable_globals(old)
+
+        # frames_json_like -> pose_data (обратно в pose_metas)
+        out_pose_data = _kps_frames_to_pose_data(pose_data, smoothed_frames, meta_ref, force_body_18=force_body_18)
+
+        # render
+        w, h = _extract_canvas_wh(smoothed_frames, default_w=720, default_h=1280)
+        frames_np = []
+        for fr in smoothed_frames:
+            if isinstance(fr, dict) and fr.get("people"):
+                img = _draw_pose_frame_full(
+                    w,
+                    h,
+                    fr["people"][0],
+                    conf_thresh_body=conf_thresh_body,
+                    conf_thresh_hands=conf_thresh_hands,
+                    conf_thresh_face=conf_thresh_face,
+                )
+            else:
+                img = np.zeros((h, w, 3), dtype=np.uint8)
+            frames_np.append(img)
+
+        frames_t = torch.from_numpy(np.stack(frames_np, axis=0)).float() / 255.0
+        return (frames_t, out_pose_data)
+
+
+# ============================================================
+# PKL / pose_data IO
+# ============================================================
+
+
+class _PoseDummyObj:
+    def __init__(self, *a, **k):
+        pass
+
+    def __setstate__(self, state):
+        # поддержка dict и (dict, slotstate)
+        if isinstance(state, dict):
+            self.__dict__.update(state)
+        elif isinstance(state, (list, tuple)) and len(state) == 2 and isinstance(state[0], dict):
+            self.__dict__.update(state[0])
+            if isinstance(state[1], dict):
+                self.__dict__.update(state[1])
+            else:
+                self.__dict__["_slotstate"] = state[1]
+        else:
+            self.__dict__["_state"] = state
+
+
+class _SafeUnpickler(pickle.Unpickler):
+    """
+    Безопасно грузим PKL из ComfyUI окружения:
+    - ремап numpy._core -> numpy.core
+    - неизвестные классы (WanAnimatePreprocess.*) превращаем в простые объекты с __dict__
+    """
+
+    def find_class(self, module, name):
+        # ремап внутренних путей numpy (частая проблема между версиями)
+        if module.startswith("numpy._core"):
+            module = module.replace("numpy._core", "numpy.core", 1)
+        if module.startswith("numpy._globals"):
+            module = module.replace("numpy._globals", "numpy", 1)
+
+        # конкретные классы метаданных (если встречаются)
+        if name in {"AAPoseMeta"}:
+            return _PoseDummyObj
+
+        try:
+            return super().find_class(module, name)
+        except Exception:
+            return _PoseDummyObj
+
+
+def _load_pose_data_pkl(path: str) -> Any:
+    with open(path, "rb") as f:
+        return _SafeUnpickler(f).load()
+
+
+def _coerce_pose_data_to_obj(pd: Any) -> Any:
+    """
+    Accepts:
+      - dict pose_data
+      - object with attributes like .pose_metas (AAPoseMeta-like)
+      - str path to .pkl
+      - dict wrapper with 'pose_data'
+    """
+    if isinstance(pd, str):
+        obj = _load_pose_data_pkl(pd)
+        return obj
+
+    if isinstance(pd, dict) and "pose_data" in pd:
+        return pd["pose_data"]
+
+    return pd
+
+
+# ============================================================
+# pose_data <-> JSON-like KPS frames
+# ============================================================
+
+
+def _as_attr(x: Any, key: str, default=None):
+    if isinstance(x, dict):
+        return x.get(key, default)
+    return getattr(x, key, default)
+
+
+def _set_attr(x: Any, key: str, value: Any):
+    if isinstance(x, dict):
+        x[key] = value
+    else:
+        setattr(x, key, value)
+
+
+def _xy_p_to_flat(xy: Optional[np.ndarray], p: Optional[np.ndarray]) -> Optional[List[float]]:
+    if xy is None:
+        return None
+    arr = np.asarray(xy)
+    if arr.ndim != 2 or arr.shape[1] < 2:
+        return None
+    N = arr.shape[0]
+    if p is None:
+        pp = np.ones((N,), dtype=np.float32)
+    else:
+        pp = np.asarray(p).reshape(-1)
+        if pp.shape[0] != N:
+            # если вдруг не совпали — подстрахуемся
+            pp = np.ones((N,), dtype=np.float32)
+
+    out: List[float] = []
+    for i in range(N):
+        out.extend([float(arr[i, 0]), float(arr[i, 1]), float(pp[i])])
+    return out
+
+
+def _flat_to_xy_p(flat: Optional[List[float]]) -> Tuple[Optional[np.ndarray], Optional[np.ndarray]]:
+    if not isinstance(flat, list) or len(flat) % 3 != 0:
+        return None, None
+    N = len(flat) // 3
+    xy = np.zeros((N, 2), dtype=np.float32)
+    p = np.zeros((N,), dtype=np.float32)
+    for i in range(N):
+        xy[i, 0] = float(flat[3 * i + 0])
+        xy[i, 1] = float(flat[3 * i + 1])
+        p[i] = float(flat[3 * i + 2])
+    return xy, p
+
+
+def _pose_data_to_kps_frames(pose_data: Any, *, force_body_18: bool) -> Tuple[List[Dict[str, Any]], Dict[str, Any]]:
+    """
+    Делает "как JSON" список кадров:
+      frame = {"people":[{pose_keypoints_2d, face_keypoints_2d, hand_left_keypoints_2d, hand_right_keypoints_2d}],
+               "canvas_width": W, "canvas_height": H}
+    meta_ref: ссылки на pose_metas + тип/доступ, чтобы правильно записать обратно.
+    """
+    pose_metas = _as_attr(pose_data, "pose_metas", None)
+    if pose_metas is None:
+        # иногда называют иначе
+        pose_metas = _as_attr(pose_data, "frames", None)
+
+    if pose_metas is None or not isinstance(pose_metas, list):
+        raise ValueError("pose_data does not contain 'pose_metas' list.")
+
+    frames: List[Dict[str, Any]] = []
+    for meta in pose_metas:
+        h = _as_attr(meta, "height", 1280)
+        w = _as_attr(meta, "width", 720)
+
+        kps_body = _as_attr(meta, "kps_body", None)
+        kps_body_p = _as_attr(meta, "kps_body_p", None)
+
+        kps_face = _as_attr(meta, "kps_face", None)
+        kps_face_p = _as_attr(meta, "kps_face_p", None)
+
+        kps_lhand = _as_attr(meta, "kps_lhand", None)
+        kps_lhand_p = _as_attr(meta, "kps_lhand_p", None)
+
+        kps_rhand = _as_attr(meta, "kps_rhand", None)
+        kps_rhand_p = _as_attr(meta, "kps_rhand_p", None)
+
+        # to flat
+        pose_flat = _xy_p_to_flat(kps_body, kps_body_p)
+        face_flat = _xy_p_to_flat(kps_face, kps_face_p)
+        lh_flat = _xy_p_to_flat(kps_lhand, kps_lhand_p)
+        rh_flat = _xy_p_to_flat(kps_rhand, kps_rhand_p)
+
+        if force_body_18 and isinstance(pose_flat, list) and len(pose_flat) >= 18 * 3:
+            pose_flat = pose_flat[: 18 * 3]
+
+        person = {
+            "pose_keypoints_2d": pose_flat if pose_flat is not None else [],
+            "face_keypoints_2d": face_flat if face_flat is not None else [],
+            "hand_left_keypoints_2d": lh_flat,
+            "hand_right_keypoints_2d": rh_flat,
+        }
+
+        frame = {"people": [person], "canvas_height": int(h), "canvas_width": int(w)}
+        frames.append(frame)
+
+    meta_ref = {
+        "pose_metas": pose_metas,
+        "len": len(pose_metas),
+    }
+    return frames, meta_ref
+
+
+def _kps_frames_to_pose_data(
+    pose_data_in: Any,
+    frames_kps: List[Dict[str, Any]],
+    meta_ref: Dict[str, Any],
+    *,
+    force_body_18: bool,
+) -> Any:
+    """
+    Записывает обратно сглаженные keypoints в pose_metas[*].kps_* / kps_*_p.
+    Остальные поля pose_data сохраняем.
+    """
+    out_pd = copy.deepcopy(pose_data_in)
+    pose_metas_out = _as_attr(out_pd, "pose_metas", None)
+    if pose_metas_out is None:
+        # fallback: вдруг другой ключ
+        pose_metas_out = meta_ref.get("pose_metas")
+
+    if pose_metas_out is None or not isinstance(pose_metas_out, list):
+        raise ValueError("Failed to locate pose_metas in output pose_data.")
+
+    T = min(len(pose_metas_out), len(frames_kps))
+    for t in range(T):
+        meta = pose_metas_out[t]
+        fr = frames_kps[t]
+        people = fr.get("people", []) if isinstance(fr, dict) else []
+        p0 = people[0] if people else None
+        if not isinstance(p0, dict):
+            continue
+
+        pose_flat = p0.get("pose_keypoints_2d")
+        face_flat = p0.get("face_keypoints_2d")
+        lh_flat = p0.get("hand_left_keypoints_2d")
+        rh_flat = p0.get("hand_right_keypoints_2d")
+
+        if force_body_18 and isinstance(pose_flat, list) and len(pose_flat) >= 18 * 3:
+            pose_flat = pose_flat[: 18 * 3]
+
+        body_xy, body_p = _flat_to_xy_p(pose_flat if isinstance(pose_flat, list) else None)
+        face_xy, face_p = _flat_to_xy_p(face_flat if isinstance(face_flat, list) else None)
+        lh_xy, lh_p = _flat_to_xy_p(lh_flat if isinstance(lh_flat, list) else None)
+        rh_xy, rh_p = _flat_to_xy_p(rh_flat if isinstance(rh_flat, list) else None)
+
+        if body_xy is not None and body_p is not None:
+            _set_attr(meta, "kps_body", body_xy.astype(np.float32, copy=False))
+            _set_attr(meta, "kps_body_p", body_p.astype(np.float32, copy=False))
+
+        if face_xy is not None and face_p is not None:
+            _set_attr(meta, "kps_face", face_xy.astype(np.float32, copy=False))
+            _set_attr(meta, "kps_face_p", face_p.astype(np.float32, copy=False))
+
+        if lh_xy is not None and lh_p is not None:
+            _set_attr(meta, "kps_lhand", lh_xy.astype(np.float32, copy=False))
+            _set_attr(meta, "kps_lhand_p", lh_p.astype(np.float32, copy=False))
+
+        if rh_xy is not None and rh_p is not None:
+            _set_attr(meta, "kps_rhand", rh_xy.astype(np.float32, copy=False))
+            _set_attr(meta, "kps_rhand_p", rh_p.astype(np.float32, copy=False))
+
+        # обновим width/height если нужно
+        if isinstance(fr, dict):
+            if "canvas_width" in fr:
+                _set_attr(meta, "width", int(fr["canvas_width"]))
+            if "canvas_height" in fr:
+                _set_attr(meta, "height", int(fr["canvas_height"]))
+
+    # обязательно положим pose_metas обратно
+    _set_attr(out_pd, "pose_metas", pose_metas_out)
+    return out_pd
+
+
+def _extract_canvas_wh(data: Any, default_w: int, default_h: int) -> Tuple[int, int]:
+    w, h = int(default_w), int(default_h)
+    if isinstance(data, list):
+        for fr in data:
+            if isinstance(fr, dict) and "canvas_width" in fr and "canvas_height" in fr:
+                try:
+                    w = int(fr["canvas_width"])
+                    h = int(fr["canvas_height"])
+                    break
+                except Exception:
+                    pass
+    return w, h
+
+
+# ============================================================
+# === START: smooth_KPS_json.py logic (ported as-is)
+# ============================================================
+
+# --- Root+Scale carry (when torso disappears on close-up) ---
+ROOTSCALE_CARRY_ENABLED = True
+CARRY_MAX_FRAMES = 48
+CARRY_MIN_ANCHORS = 2
+CARRY_ANCHOR_JOINTS = [0, 1, 2, 5, 3, 6, 4, 7]
+CARRY_CONF_GATE = 0.20
+
+# --- Main person selection / multi-person filtering ---
+FILTER_EXTRA_PEOPLE = True
+MAIN_PERSON_MODE = "longest_track"
+TRACK_MATCH_MIN_PX = 80.0
+TRACK_MATCH_FACTOR = 3.0
+TRACK_MAX_FRAME_GAP = 32
+
+# --- Spatial outlier suppression ---
+SPATIAL_OUTLIER_FIX = True
+BONE_MAX_FACTOR = 2.3
+TORSO_RADIUS_FACTOR = 4.0
+
+# EMA smoothing for BODY only (online)
+ALPHA_BODY = 0.70
+MAX_STEP_BODY = 60.0
+VEL_ALPHA = 0.45
+EPS = 0.3
+CONF_GATE_BODY = 0.20
+CONF_FLOOR_BODY = 0.00
+
+TRACK_DIST_PENALTY = 1.5
+FACE_WEIGHT_IN_SCORE = 0.15
+HAND_WEIGHT_IN_SCORE = 0.35
+
+ALLOW_DISAPPEAR_JOINTS = {3, 4, 6, 7}
+
+GAP_FILL_ENABLED = True
+MAX_GAP_FRAMES = 12
+MIN_RUN_FRAMES = 2
+
+TORSO_SYNC_ENABLED = True
+TORSO_JOINTS = {1, 2, 5, 8, 11}
+TORSO_LOOKAHEAD_FRAMES = 32
+
+SUPER_SMOOTH_ENABLED = True
+SUPER_SMOOTH_ALPHA = 0.7
+SUPER_SMOOTH_MIN_CONF = 0.20
+
+MEDIAN3_ENABLED = True
+
+FACE_SMOOTH_ENABLED = True
+HANDS_SMOOTH_ENABLED = False
+
+CONF_GATE_FACE = 0.20
+CONF_GATE_HAND = 0.50
+
+HAND_MIN_POINTS_PRESENT = 7
+MIN_HAND_RUN_FRAMES = 6
+
+DENSE_GAP_FILL_ENABLED = False
+DENSE_MAX_GAP_FRAMES = 8
+DENSE_MIN_RUN_FRAMES = 2
+
+DENSE_MEDIAN3_ENABLED = False
+DENSE_SUPER_SMOOTH_ENABLED = False
+DENSE_SUPER_SMOOTH_ALPHA = 0.7
+
+
+def _snapshot_tunable_globals() -> Dict[str, Any]:
+    keys = [
+        "FILTER_EXTRA_PEOPLE",
+        "SUPER_SMOOTH_ALPHA",
+        "MAX_GAP_FRAMES",
+        "MIN_RUN_FRAMES",
+        "DENSE_SUPER_SMOOTH_ALPHA",
+        "DENSE_MAX_GAP_FRAMES",
+        "DENSE_MIN_RUN_FRAMES",
+    ]
+    return {k: globals().get(k) for k in keys}
+
+
+def _restore_tunable_globals(old: Dict[str, Any]) -> None:
+    for k, v in old.items():
+        globals()[k] = v
+
+
+def _is_valid_xyc(x: float, y: float, c: float) -> bool:
+    if c is None:
+        return False
+    if c <= 0:
+        return False
+    if x == 0 and y == 0:
+        return False
+    if math.isnan(x) or math.isnan(y) or math.isnan(c):
+        return False
+    return True
+
+
+def _reshape_keypoints_2d(arr: List[float]) -> List[Tuple[float, float, float]]:
+    if arr is None:
+        return []
+    if len(arr) % 3 != 0:
+        raise ValueError(f"keypoints length not multiple of 3: {len(arr)}")
+    out = []
+    for i in range(0, len(arr), 3):
+        out.append((float(arr[i]), float(arr[i + 1]), float(arr[i + 2])))
+    return out
+
+
+def _flatten_keypoints_2d(kps: List[Tuple[float, float, float]]) -> List[float]:
+    out: List[float] = []
+    for x, y, c in kps:
+        out.extend([float(x), float(y), float(c)])
+    return out
+
+
+def _sum_conf(arr: Optional[List[float]], sample_step: int = 1) -> float:
+    if not arr:
+        return 0.0
+    s = 0.0
+    for i in range(2, len(arr), 3 * sample_step):
+        try:
+            c = float(arr[i])
+        except Exception:
+            c = 0.0
+        if c > 0:
+            s += c
+    return s
+
+
+def _body_center_from_pose(pose_arr: Optional[List[float]]) -> Optional[Tuple[float, float]]:
+    if not pose_arr:
+        return None
+    kps = _reshape_keypoints_2d(pose_arr)
+    idxs = [2, 5, 8, 11, 1]
+    pts = []
+    for idx in idxs:
+        if idx < len(kps):
+            x, y, c = kps[idx]
+            if _is_valid_xyc(x, y, c):
+                pts.append((x, y))
+    if not pts:
+        for x, y, c in kps:
+            if _is_valid_xyc(x, y, c):
+                pts.append((x, y))
+    if not pts:
+        return None
+    cx = sum(p[0] for p in pts) / len(pts)
+    cy = sum(p[1] for p in pts) / len(pts)
+    return (cx, cy)
+
+
+def _dist(a: Tuple[float, float], b: Tuple[float, float]) -> float:
+    return math.hypot(a[0] - b[0], a[1] - b[1])
+
+
+def _choose_single_person(
+    people: List[Dict[str, Any]], prev_center: Optional[Tuple[float, float]]
+) -> Optional[Dict[str, Any]]:
+    if not people:
+        return None
+    best = None
+    best_score = -1e18
+
+    for p in people:
+        pose = p.get("pose_keypoints_2d")
+        face = p.get("face_keypoints_2d")
+        lh = p.get("hand_left_keypoints_2d")
+        rh = p.get("hand_right_keypoints_2d")
+
+        score = _sum_conf(pose)
+        score += FACE_WEIGHT_IN_SCORE * _sum_conf(face, sample_step=4)
+        score += HAND_WEIGHT_IN_SCORE * (_sum_conf(lh, sample_step=2) + _sum_conf(rh, sample_step=2))
+
+        center = _body_center_from_pose(pose)
+        if prev_center is not None and center is not None:
+            score -= TRACK_DIST_PENALTY * _dist(prev_center, center)
+
+        if score > best_score:
+            best_score = score
+            best = p
+
+    return best
+
+
+@dataclass
+class _Track:
+    frames: Dict[int, Dict[str, Any]]
+    centers: Dict[int, Tuple[float, float]]
+    last_t: int
+    last_center: Tuple[float, float]
+
+
+def _estimate_torso_scale(pose: List[Tuple[float, float, float]]) -> Optional[float]:
+    def dist(i, k) -> Optional[float]:
+        if i >= len(pose) or k >= len(pose):
+            return None
+        xi, yi, ci = pose[i]
+        xk, yk, ck = pose[k]
+        if not _is_valid_xyc(xi, yi, ci) or not _is_valid_xyc(xk, yk, ck):
+            return None
+        return math.hypot(xi - xk, yi - yk)
+
+    cand = [dist(2, 5), dist(8, 11), dist(1, 8), dist(1, 11)]
+    cand = [c for c in cand if c is not None and c > 1e-3]
+    if not cand:
+        return None
+    return float(sum(cand) / len(cand))
+
+
+def _track_match_threshold_from_pose(pose_arr: Optional[List[float]]) -> float:
+    if isinstance(pose_arr, list):
+        pose = _reshape_keypoints_2d(pose_arr)
+        s = _estimate_torso_scale(pose)
+        if s is not None:
+            return max(float(TRACK_MATCH_MIN_PX), float(TRACK_MATCH_FACTOR) * float(s))
+    return float(max(TRACK_MATCH_MIN_PX, 120.0))
+
+
+def _build_tracks_over_video(frames_data: List[Any]) -> List[_Track]:
+    tracks: List[_Track] = []
+
+    for t, frame in enumerate(frames_data):
+        if not isinstance(frame, dict):
+            continue
+        people = frame.get("people", [])
+        if not isinstance(people, list) or not people:
+            continue
+
+        cand: List[Tuple[int, Dict[str, Any], Tuple[float, float]]] = []
+        for i, p in enumerate(people):
+            if not isinstance(p, dict):
+                continue
+            pose = p.get("pose_keypoints_2d")
+            c = _body_center_from_pose(pose)
+            if c is None:
+                continue
+            cand.append((i, p, c))
+
+        if not cand:
+            continue
+
+        used = set()
+        track_order = sorted(range(len(tracks)), key=lambda k: tracks[k].last_t, reverse=True)
+
+        for k in track_order:
+            tr = tracks[k]
+            age = t - tr.last_t
+            if age > int(TRACK_MAX_FRAME_GAP):
+                continue
+
+            best_idx = None
+            best_d = 1e18
+
+            for i, p, cc in cand:
+                if i in used:
+                    continue
+
+                thr = _track_match_threshold_from_pose(p.get("pose_keypoints_2d"))
+                d = _dist(tr.last_center, cc)
+                if d <= thr and d < best_d:
+                    best_d = d
+                    best_idx = i
+
+            if best_idx is not None:
+                i, p, cc = next(x for x in cand if x[0] == best_idx)
+                used.add(i)
+                tr.frames[t] = p
+                tr.centers[t] = cc
+                tr.last_t = t
+                tr.last_center = cc
+
+        for i, p, cc in cand:
+            if i in used:
+                continue
+            tracks.append(_Track(frames={t: p}, centers={t: cc}, last_t=t, last_center=cc))
+
+    return tracks
+
+
+def _track_presence_score(tr: _Track) -> Tuple[int, float, float]:
+    frames_count = len(tr.frames)
+    face_sum = 0.0
+    body_sum = 0.0
+    for p in tr.frames.values():
+        face_sum += _sum_conf(p.get("face_keypoints_2d"), sample_step=4)
+        body_sum += _sum_conf(p.get("pose_keypoints_2d"), sample_step=1)
+    return (frames_count, face_sum, body_sum)
+
+
+def _pick_main_track(tracks: List[_Track]) -> Optional[_Track]:
+    if not tracks:
+        return None
+    best = None
+    best_key = (-1, -1e18, -1e18)
+    for tr in tracks:
+        key = _track_presence_score(tr)
+        if key > best_key:
+            best_key = key
+            best = tr
+    return best
+
+
+@dataclass
+class BodyState:
+    last_xy: List[Optional[Tuple[float, float]]]
+    last_v: List[Tuple[float, float]]
+
+    def __init__(self, joints: int):
+        self.last_xy = [None] * joints
+        self.last_v = [(0.0, 0.0)] * joints
+
+
+def _smooth_body_pose(pose_arr: Optional[List[float]], state: BodyState) -> Optional[List[float]]:
+    if pose_arr is None:
+        return None
+
+    kps = _reshape_keypoints_2d(pose_arr)
+    J = len(kps)
+    if len(state.last_xy) != J:
+        state.last_xy = [None] * J
+        state.last_v = [(0.0, 0.0)] * J
+
+    out: List[Tuple[float, float, float]] = []
+
+    for j in range(J):
+        x, y, c = kps[j]
+        last = state.last_xy[j]
+        vx_last, vy_last = state.last_v[j]
+
+        valid_in = _is_valid_xyc(x, y, c) and (c >= CONF_GATE_BODY)
+
+        if valid_in:
+            if last is None:
+                nx, ny = x, y
+                state.last_xy[j] = (nx, ny)
+                state.last_v[j] = (0.0, 0.0)
+                out.append((nx, ny, float(c)))
+                continue
+
+            dx_raw = x - last[0]
+            dy_raw = y - last[1]
+            if abs(dx_raw) < EPS:
+                dx_raw = 0.0
+            if abs(dy_raw) < EPS:
+                dy_raw = 0.0
+
+            vx = VEL_ALPHA * dx_raw + (1.0 - VEL_ALPHA) * vx_last
+            vy = VEL_ALPHA * dy_raw + (1.0 - VEL_ALPHA) * vy_last
+
+            px = last[0] + vx
+            py = last[1] + vy
+
+            nx = ALPHA_BODY * x + (1.0 - ALPHA_BODY) * px
+            ny = ALPHA_BODY * y + (1.0 - ALPHA_BODY) * py
+
+            ddx = nx - last[0]
+            ddy = ny - last[1]
+            d = math.hypot(ddx, ddy)
+            if d > MAX_STEP_BODY and d > 1e-6:
+                scale = MAX_STEP_BODY / d
+                nx = last[0] + ddx * scale
+                ny = last[1] + ddy * scale
+                vx = nx - last[0]
+                vy = ny - last[1]
+
+            state.last_xy[j] = (nx, ny)
+            state.last_v[j] = (vx, vy)
+
+            out.append((nx, ny, float(c)))
+        else:
+            out.append((float(x), float(y), float(c)))
+
+    return _flatten_keypoints_2d(out)
+
+
+COCO18_EDGES = [
+    (1, 2),
+    (2, 3),
+    (3, 4),
+    (1, 5),
+    (5, 6),
+    (6, 7),
+    (1, 8),
+    (8, 9),
+    (9, 10),
+    (1, 11),
+    (11, 12),
+    (12, 13),
+    (8, 11),
+    (1, 0),
+    (0, 14),
+    (14, 16),
+    (0, 15),
+    (15, 17),
+]
+
+HAND21_EDGES = [
+    (0, 1),
+    (1, 2),
+    (2, 3),
+    (3, 4),
+    (0, 5),
+    (5, 6),
+    (6, 7),
+    (7, 8),
+    (0, 9),
+    (9, 10),
+    (10, 11),
+    (11, 12),
+    (0, 13),
+    (13, 14),
+    (14, 15),
+    (15, 16),
+    (0, 17),
+    (17, 18),
+    (18, 19),
+    (19, 20),
+]
+
+_NEIGHBORS = None
+
+
+def _build_neighbors():
+    global _NEIGHBORS
+    if _NEIGHBORS is not None:
+        return
+    neigh = {}
+    for a, b in COCO18_EDGES:
+        neigh.setdefault(a, set()).add(b)
+        neigh.setdefault(b, set()).add(a)
+    _NEIGHBORS = neigh
+
+
+def _suppress_spatial_outliers_in_pose_arr(
+    pose_arr: Optional[List[float]], *, conf_gate: float
+) -> Optional[List[float]]:
+    if not isinstance(pose_arr, list) or len(pose_arr) % 3 != 0:
+        return pose_arr
+
+    pose = _reshape_keypoints_2d(pose_arr)
+    J = len(pose)
+
+    center = _body_center_from_pose(pose_arr)
+    scale = _estimate_torso_scale(pose)
+    if center is None or scale is None:
+        return pose_arr
+
+    cx, cy = center
+    max_r = TORSO_RADIUS_FACTOR * scale
+    max_bone = BONE_MAX_FACTOR * scale
+
+    out = [list(p) for p in pose]
+
+    def visible(j: int) -> bool:
+        if j >= J:
+            return False
+        x, y, c = out[j]
+        return (c >= conf_gate) and not (x == 0 and y == 0)
+
+    for j in range(J):
+        x, y, c = out[j]
+        if c >= conf_gate and not (x == 0 and y == 0):
+            if math.hypot(x - cx, y - cy) > max_r:
+                out[j] = [0.0, 0.0, 0.0]
+
+    for a, b in COCO18_EDGES:
+        if a >= J or b >= J:
+            continue
+        if not visible(a) or not visible(b):
+            continue
+        ax, ay, ac = out[a]
+        bx, by, bc = out[b]
+        d = math.hypot(ax - bx, ay - by)
+        if d > max_bone:
+            if ac <= bc:
+                out[a] = [0.0, 0.0, 0.0]
+            else:
+                out[b] = [0.0, 0.0, 0.0]
+
+    flat: List[float] = []
+    for x, y, c in out:
+        flat.extend([float(x), float(y), float(c)])
+    return flat
+
+
+def _suppress_isolated_joints_in_pose_arr(
+    pose_arr: Optional[List[float]], *, conf_gate: float, keep: set[int] = None
+) -> Optional[List[float]]:
+    if not isinstance(pose_arr, list) or len(pose_arr) % 3 != 0:
+        return pose_arr
+
+    _build_neighbors()
+    pose = _reshape_keypoints_2d(pose_arr)
+    J = len(pose)
+    out = [list(p) for p in pose]
+
+    if keep is None:
+        keep = set()
+
+    def vis(j: int) -> bool:
+        if j >= J:
+            return False
+        x, y, c = out[j]
+        return (c >= conf_gate) and not (x == 0 and y == 0)
+
+    for j in range(J):
+        if j in keep:
+            continue
+        if not vis(j):
+            continue
+        neighs = _NEIGHBORS.get(j, set())
+        if not any((n < J and vis(n)) for n in neighs):
+            out[j] = [0.0, 0.0, 0.0]
+
+    flat = []
+    for x, y, c in out:
+        flat.extend([float(x), float(y), float(c)])
+    return flat
+
+
+def _denoise_and_fill_gaps_pose_seq(
+    pose_arr_seq: List[Optional[List[float]]],
+    *,
+    conf_gate: float,
+    min_run: int,
+    max_gap: int,
+) -> List[Optional[List[float]]]:
+    if not pose_arr_seq:
+        return pose_arr_seq
+
+    J = None
+    for arr in pose_arr_seq:
+        if isinstance(arr, list) and len(arr) % 3 == 0 and len(arr) > 0:
+            J = len(arr) // 3
+            break
+    if J is None:
+        return pose_arr_seq
+
+    T = len(pose_arr_seq)
+    out_seq: List[Optional[List[float]]] = []
+    for arr in pose_arr_seq:
+        if isinstance(arr, list) and len(arr) == J * 3:
+            out_seq.append(list(arr))
+        else:
+            out_seq.append(arr)
+
+    def is_vis(arr: List[float], j: int) -> bool:
+        x = float(arr[3 * j + 0])
+        y = float(arr[3 * j + 1])
+        c = float(arr[3 * j + 2])
+        return (c >= conf_gate) and not (x == 0 and y == 0)
+
+    # 1) remove short flashes
+    for j in range(J):
+        start = None
+        for t in range(T + 1):
+            cur = False
+            if t < T and isinstance(out_seq[t], list):
+                cur = is_vis(out_seq[t], j)
+            if cur and start is None:
+                start = t
+            if (not cur) and start is not None:
+                run_len = t - start
+                if run_len < min_run:
+                    for k in range(start, t):
+                        if not isinstance(out_seq[k], list):
+                            continue
+                        out_seq[k][3 * j + 0] = 0.0
+                        out_seq[k][3 * j + 1] = 0.0
+                        out_seq[k][3 * j + 2] = 0.0
+                start = None
+
+    # 2) gap fill only if returns
+    for j in range(J):
+        last_vis_t = None
+        t = 0
+        while t < T:
+            arr = out_seq[t]
+            if not isinstance(arr, list):
+                t += 1
+                continue
+
+            cur_vis = is_vis(arr, j)
+            if cur_vis:
+                last_vis_t = t
+                t += 1
+                continue
+
+            if last_vis_t is None:
+                t += 1
+                continue
+
+            gap_start = t
+            t2 = t
+            while t2 < T:
+                arr2 = out_seq[t2]
+                if isinstance(arr2, list) and is_vis(arr2, j):
+                    break
+                t2 += 1
+
+            if t2 >= T:
+                break
+
+            gap_len = t2 - gap_start
+            if gap_len <= 0:
+                t = t2
+                continue
+
+            if gap_len <= max_gap:
+                a = out_seq[last_vis_t]
+                b = out_seq[t2]
+                if isinstance(a, list) and isinstance(b, list):
+                    ax, ay, ac = float(a[3 * j + 0]), float(a[3 * j + 1]), float(a[3 * j + 2])
+                    bx, by, bc = float(b[3 * j + 0]), float(b[3 * j + 1]), float(b[3 * j + 2])
+                    if not (ax == 0 and ay == 0) and not (bx == 0 and by == 0):
+                        conf_fill = min(ac, bc)
+                        for k in range(gap_len):
+                            tt = gap_start + k
+                            if not isinstance(out_seq[tt], list):
+                                continue
+                            r = (k + 1) / (gap_len + 1)
+                            x = ax + (bx - ax) * r
+                            y = ay + (by - ay) * r
+                            out_seq[tt][3 * j + 0] = float(x)
+                            out_seq[tt][3 * j + 1] = float(y)
+                            out_seq[tt][3 * j + 2] = float(conf_fill)
+
+            t = t2
+
+    return out_seq
+
+
+def _zero_lag_ema_pose_seq(
+    pose_seq: List[Optional[List[float]]], *, alpha: float, conf_gate: float
+) -> List[Optional[List[float]]]:
+    if not pose_seq:
+        return pose_seq
+
+    J = None
+    for arr in pose_seq:
+        if isinstance(arr, list) and len(arr) % 3 == 0 and len(arr) > 0:
+            J = len(arr) // 3
+            break
+    if J is None:
+        return pose_seq
+
+    T = len(pose_seq)
+
+    def is_vis(arr: List[float], j: int) -> bool:
+        x = float(arr[3 * j + 0])
+        y = float(arr[3 * j + 1])
+        c = float(arr[3 * j + 2])
+        return (c >= conf_gate) and not (x == 0 and y == 0)
+
+    fwd = [None] * T
+    last = [None] * J
+    for t in range(T):
+        arr = pose_seq[t]
+        if not isinstance(arr, list) or len(arr) != J * 3:
+            fwd[t] = arr
+            continue
+        out = list(arr)
+        for j in range(J):
+            if is_vis(arr, j):
+                x = float(arr[3 * j + 0])
+                y = float(arr[3 * j + 1])
+                if last[j] is None:
+                    sx, sy = x, y
+                else:
+                    sx = alpha * x + (1 - alpha) * last[j][0]
+                    sy = alpha * y + (1 - alpha) * last[j][1]
+                last[j] = (sx, sy)
+                out[3 * j + 0] = float(sx)
+                out[3 * j + 1] = float(sy)
+        fwd[t] = out
+
+    bwd = [None] * T
+    last = [None] * J
+    for t in range(T - 1, -1, -1):
+        arr = fwd[t]
+        if not isinstance(arr, list) or len(arr) != J * 3:
+            bwd[t] = arr
+            continue
+        out = list(arr)
+        for j in range(J):
+            if is_vis(arr, j):
+                x = float(arr[3 * j + 0])
+                y = float(arr[3 * j + 1])
+                if last[j] is None:
+                    sx, sy = x, y
+                else:
+                    sx = alpha * x + (1 - alpha) * last[j][0]
+                    sy = alpha * y + (1 - alpha) * last[j][1]
+                last[j] = (sx, sy)
+                out[3 * j + 0] = float(sx)
+                out[3 * j + 1] = float(sy)
+        bwd[t] = out
+
+    return bwd
+
+
+def _apply_root_scale(
+    pose_arr: Optional[List[float]],
+    *,
+    src_root: Tuple[float, float],
+    src_scale: float,
+    dst_root: Tuple[float, float],
+    dst_scale: float,
+) -> Optional[List[float]]:
+    if not isinstance(pose_arr, list) or len(pose_arr) % 3 != 0:
+        return pose_arr
+    if src_scale <= 1e-6 or dst_scale <= 1e-6:
+        return pose_arr
+
+    kps = _reshape_keypoints_2d(pose_arr)
+    out = []
+    s = dst_scale / src_scale
+
+    for x, y, c in kps:
+        if c <= 0 or (x == 0 and y == 0):
+            out.append((x, y, c))
+            continue
+        nx = dst_root[0] + (x - src_root[0]) * s
+        ny = dst_root[1] + (y - src_root[1]) * s
+        out.append((nx, ny, c))
+
+    return _flatten_keypoints_2d(out)
+
+
+def _carry_pose_when_torso_missing(
+    pose_seq: List[Optional[List[float]]],
+    *,
+    conf_gate: float,
+    max_carry: int,
+    anchor_joints: List[int],
+    min_anchors: int,
+) -> List[Optional[List[float]]]:
+    if not pose_seq:
+        return pose_seq
+
+    J = None
+    for arr in pose_seq:
+        if isinstance(arr, list) and len(arr) % 3 == 0 and len(arr) > 0:
+            J = len(arr) // 3
+            break
+    if J is None:
+        return pose_seq
+
+    out = [a if a is None else list(a) for a in pose_seq]
+
+    FILL_JOINTS = {1, 8, 9, 10, 11, 12, 13}
+    FILL_JOINTS -= set(ALLOW_DISAPPEAR_JOINTS)
+
+    def is_vis_flat(arr: List[float], j: int) -> bool:
+        x = float(arr[3 * j + 0])
+        y = float(arr[3 * j + 1])
+        c = float(arr[3 * j + 2])
+        return (c >= conf_gate) and not (x == 0 and y == 0)
+
+    def count_visible(arr: List[float], joints: List[int]) -> int:
+        c = 0
+        for j in joints:
+            if j < J and is_vis_flat(arr, j):
+                c += 1
+        return c
+
+    def root_scale_from_anchors(arr: List[float]) -> Optional[Tuple[Tuple[float, float], float]]:
+        pts = []
+        for j in anchor_joints:
+            if j >= J:
+                continue
+            if is_vis_flat(arr, j):
+                x = float(arr[3 * j + 0])
+                y = float(arr[3 * j + 1])
+                pts.append((x, y))
+        if len(pts) < min_anchors:
+            return None
+
+        rx = sum(p[0] for p in pts) / len(pts)
+        ry = sum(p[1] for p in pts) / len(pts)
+
+        xs = [p[0] for p in pts]
+        ys = [p[1] for p in pts]
+        scale = max(max(xs) - min(xs), max(ys) - min(ys))
+        if scale <= 1e-3:
+            return None
+
+        return (rx, ry), float(scale)
+
+    last_good: Optional[List[float]] = None
+    last_good_rs: Optional[Tuple[Tuple[float, float], float]] = None
+    carry_left = 0
+
+    for t in range(len(out)):
+        arr = out[t]
+        if not isinstance(arr, list) or len(arr) != J * 3:
+            continue
+
+        anchors_ok = count_visible(arr, anchor_joints) >= min_anchors
+        fill_vis = sum(1 for j in FILL_JOINTS if j < J and is_vis_flat(arr, j))
+        rs = root_scale_from_anchors(arr)
+
+        if anchors_ok and rs is not None and fill_vis >= 2:
+            last_good = list(arr)
+            last_good_rs = rs
+            carry_left = max_carry
+            continue
+
+        if anchors_ok and rs is not None and last_good is not None and last_good_rs is not None and carry_left > 0:
+            dst_root, dst_scale = rs
+            src_root, src_scale = last_good_rs
+
+            carried_full = _apply_root_scale(
+                last_good,
+                src_root=src_root,
+                src_scale=src_scale,
+                dst_root=dst_root,
+                dst_scale=dst_scale,
+            )
+            if isinstance(carried_full, list) and len(carried_full) == J * 3:
+                for j in FILL_JOINTS:
+                    if j >= J:
+                        continue
+                    if is_vis_flat(arr, j):
+                        continue
+
+                    cx = float(carried_full[3 * j + 0])
+                    cy = float(carried_full[3 * j + 1])
+                    cc = float(carried_full[3 * j + 2])
+
+                    if (cx == 0 and cy == 0) or cc <= 0:
+                        continue
+
+                    arr[3 * j + 0] = cx
+                    arr[3 * j + 1] = cy
+                    arr[3 * j + 2] = max(min(cc, 0.60), conf_gate)
+
+                out[t] = arr
+                carry_left -= 1
+                continue
+
+        carry_left = max(carry_left - 1, 0)
+
+    return out
+
+
+def _force_full_torso_pair(
+    pose_seq: List[Optional[List[float]]],
+    *,
+    conf_gate: float,
+    anchor_joints: List[int],
+    min_anchors: int,
+    max_lookback: int = 240,
+    fill_legs_with_hip: bool = True,
+    always_fill_if_one_hip: bool = True,
+) -> List[Optional[List[float]]]:
+    if not pose_seq:
+        return pose_seq
+
+    J = None
+    for arr in pose_seq:
+        if isinstance(arr, list) and len(arr) % 3 == 0 and len(arr) > 0:
+            J = len(arr) // 3
+            break
+    if J is None:
+        return pose_seq
+
+    out = [a if a is None else list(a) for a in pose_seq]
+
+    R_HIP, R_KNEE, R_ANK = 8, 9, 10
+    L_HIP, L_KNEE, L_ANK = 11, 12, 13
+
+    def is_vis(arr: List[float], j: int) -> bool:
+        if j >= J:
+            return False
+        x = float(arr[3 * j + 0])
+        y = float(arr[3 * j + 1])
+        c = float(arr[3 * j + 2])
+        return (c >= conf_gate) and not (x == 0 and y == 0)
+
+    def count_visible(arr: List[float], joints: List[int]) -> int:
+        c = 0
+        for j in joints:
+            if is_vis(arr, j):
+                c += 1
+        return c
+
+    def root_scale_from_anchors(arr: List[float]) -> Optional[Tuple[Tuple[float, float], float]]:
+        pts = []
+        for j in anchor_joints:
+            if j >= J:
+                continue
+            if is_vis(arr, j):
+                pts.append((float(arr[3 * j + 0]), float(arr[3 * j + 1])))
+        if len(pts) < min_anchors:
+            return None
+
+        rx = sum(p[0] for p in pts) / len(pts)
+        ry = sum(p[1] for p in pts) / len(pts)
+
+        xs = [p[0] for p in pts]
+        ys = [p[1] for p in pts]
+        scale = max(max(xs) - min(xs), max(ys) - min(ys))
+        if scale <= 1e-3:
+            return None
+        return (rx, ry), float(scale)
+
+    last_full_idx = None
+    last_full = None
+    last_full_rs = None
+
+    for t in range(len(out)):
+        arr = out[t]
+        if not isinstance(arr, list) or len(arr) != J * 3:
+            continue
+
+        rs = root_scale_from_anchors(arr)
+
+        r_ok = is_vis(arr, R_HIP)
+        l_ok = is_vis(arr, L_HIP)
+
+        anchors_ok = count_visible(arr, anchor_joints) >= min_anchors
+
+        if anchors_ok and rs is not None and r_ok and l_ok:
+            last_full_idx = t
+            last_full = list(arr)
+            last_full_rs = rs
+            continue
+
+        if last_full is None or last_full_rs is None or last_full_idx is None:
+            continue
+        if (t - last_full_idx) > max_lookback:
+            continue
+        if not (r_ok or l_ok):
+            continue
+        if r_ok and l_ok:
+            continue
+        if not always_fill_if_one_hip:
+            continue
+        if rs is None:
+            continue
+
+        dst_root, dst_scale = rs
+        src_root, src_scale = last_full_rs
+
+        carried = _apply_root_scale(
+            last_full,
+            src_root=src_root,
+            src_scale=src_scale,
+            dst_root=dst_root,
+            dst_scale=dst_scale,
+        )
+        if not (isinstance(carried, list) and len(carried) == J * 3):
+            continue
+
+        def copy_joint(j: int):
+            if j >= J:
+                return
+            if is_vis(arr, j):
+                return
+            cx = float(carried[3 * j + 0])
+            cy = float(carried[3 * j + 1])
+            cc = float(carried[3 * j + 2])
+            if (cx == 0 and cy == 0) or cc <= 0:
+                return
+            arr[3 * j + 0] = cx
+            arr[3 * j + 1] = cy
+            arr[3 * j + 2] = max(min(cc, 0.60), conf_gate)
+
+        if not r_ok:
+            copy_joint(R_HIP)
+            if fill_legs_with_hip:
+                copy_joint(R_KNEE)
+                copy_joint(R_ANK)
+
+        if not l_ok:
+            copy_joint(L_HIP)
+            if fill_legs_with_hip:
+                copy_joint(L_KNEE)
+                copy_joint(L_ANK)
+
+        out[t] = arr
+
+    return out
+
+
+def _median3_pose_seq(pose_seq: List[Optional[List[float]]], *, conf_gate: float) -> List[Optional[List[float]]]:
+    if not pose_seq:
+        return pose_seq
+
+    J = None
+    for arr in pose_seq:
+        if isinstance(arr, list) and len(arr) % 3 == 0 and len(arr) > 0:
+            J = len(arr) // 3
+            break
+    if J is None:
+        return pose_seq
+
+    T = len(pose_seq)
+
+    def is_vis(arr: List[float], j: int) -> bool:
+        x = float(arr[3 * j + 0])
+        y = float(arr[3 * j + 1])
+        c = float(arr[3 * j + 2])
+        return (c >= conf_gate) and not (x == 0 and y == 0)
+
+    out_seq: List[Optional[List[float]]] = []
+    for t in range(T):
+        arr = pose_seq[t]
+        if not isinstance(arr, list) or len(arr) != J * 3:
+            out_seq.append(arr)
+            continue
+
+        out = list(arr)
+        t0 = max(0, t - 1)
+        t1 = t
+        t2 = min(T - 1, t + 1)
+
+        a0 = pose_seq[t0]
+        a1 = pose_seq[t1]
+        a2 = pose_seq[t2]
+
+        for j in range(J):
+            if not is_vis(arr, j):
+                continue
+
+            xs, ys = [], []
+            for aa in (a0, a1, a2):
+                if isinstance(aa, list) and len(aa) == J * 3 and is_vis(aa, j):
+                    xs.append(float(aa[3 * j + 0]))
+                    ys.append(float(aa[3 * j + 1]))
+
+            if len(xs) >= 2:
+                xs.sort()
+                ys.sort()
+                out[3 * j + 0] = float(xs[len(xs) // 2])
+                out[3 * j + 1] = float(ys[len(ys) // 2])
+
+        out_seq.append(out)
+
+    return out_seq
+
+
+def _sync_group_appearances(
+    pose_arr_seq: List[Optional[List[float]]],
+    *,
+    group: set[int],
+    conf_gate: float,
+    lookahead: int,
+) -> List[Optional[List[float]]]:
+    if not pose_arr_seq:
+        return pose_arr_seq
+
+    J = None
+    for arr in pose_arr_seq:
+        if isinstance(arr, list) and len(arr) % 3 == 0 and len(arr) > 0:
+            J = len(arr) // 3
+            break
+    if J is None:
+        return pose_arr_seq
+
+    T = len(pose_arr_seq)
+    out_seq: List[Optional[List[float]]] = []
+    for arr in pose_arr_seq:
+        if isinstance(arr, list) and len(arr) == J * 3:
+            out_seq.append(list(arr))
+        else:
+            out_seq.append(arr)
+
+    def is_vis(arr: List[float], j: int) -> bool:
+        x = float(arr[3 * j + 0])
+        y = float(arr[3 * j + 1])
+        c = float(arr[3 * j + 2])
+        return (c >= conf_gate) and not (x == 0 and y == 0)
+
+    for t in range(T):
+        arr = out_seq[t]
+        if not isinstance(arr, list):
+            continue
+
+        vis = {j for j in group if j < J and is_vis(arr, j)}
+        if not vis:
+            continue
+
+        missing = {j for j in group if j < J and j not in vis}
+        if not missing:
+            continue
+
+        appear_t: dict[int, int] = {}
+        for j in list(missing):
+            t2 = t + 1
+            while t2 < T and t2 <= t + lookahead:
+                arr2 = out_seq[t2]
+                if isinstance(arr2, list) and is_vis(arr2, j):
+                    appear_t[j] = t2
+                    break
+                t2 += 1
+
+        if not appear_t:
+            continue
+
+        for j, t2 in appear_t.items():
+            last_t = None
+            for tb in range(t - 1, -1, -1):
+                arrb = out_seq[tb]
+                if isinstance(arrb, list) and is_vis(arrb, j):
+                    last_t = tb
+                    break
+
+            if last_t is None:
+                b = out_seq[t2]
+                if not isinstance(b, list):
+                    continue
+                bx, by, bc = float(b[3 * j + 0]), float(b[3 * j + 1]), float(b[3 * j + 2])
+                for k in range(t, t2):
+                    a = out_seq[k]
+                    if not isinstance(a, list):
+                        continue
+                    a[3 * j + 0] = bx
+                    a[3 * j + 1] = by
+                    a[3 * j + 2] = bc
+                continue
+
+            a0 = out_seq[last_t]
+            b0 = out_seq[t2]
+            if not (isinstance(a0, list) and isinstance(b0, list)):
+                continue
+
+            ax, ay, ac = float(a0[3 * j + 0]), float(a0[3 * j + 1]), float(a0[3 * j + 2])
+            bx, by, bc = float(b0[3 * j + 0]), float(b0[3 * j + 1]), float(b0[3 * j + 2])
+
+            if (ax == 0 and ay == 0) or (bx == 0 and by == 0):
+                continue
+
+            conf_fill = min(ac, bc)
+            total = t2 - last_t
+            if total <= 0:
+                continue
+
+            for tt in range(t, t2):
+                a = out_seq[tt]
+                if not isinstance(a, list):
+                    continue
+                r = (tt - last_t) / total
+                x = ax + (bx - ax) * r
+                y = ay + (by - ay) * r
+                a[3 * j + 0] = float(x)
+                a[3 * j + 1] = float(y)
+                a[3 * j + 2] = float(conf_fill)
+
+    return out_seq
+
+
+def _count_valid_points(arr: Optional[List[float]], *, conf_gate: float) -> int:
+    if not isinstance(arr, list) or len(arr) % 3 != 0:
+        return 0
+    cnt = 0
+    for i in range(0, len(arr), 3):
+        x, y, c = float(arr[i]), float(arr[i + 1]), float(arr[i + 2])
+        if c >= conf_gate and not (x == 0 and y == 0):
+            cnt += 1
+    return cnt
+
+
+def _zero_out_kps(arr: Optional[List[float]]) -> Optional[List[float]]:
+    if not isinstance(arr, list) or len(arr) % 3 != 0:
+        return arr
+    out = list(arr)
+    for i in range(0, len(out), 3):
+        out[i + 0] = 0.0
+        out[i + 1] = 0.0
+        out[i + 2] = 0.0
+    return out
+
+
+def _pin_body_wrist_to_hand(
+    p_out: Dict[str, Any],
+    *,
+    side: str,
+    conf_gate_body: float = 0.2,
+    conf_gate_hand: float = 0.2,
+    blend: float = 1.0,
+) -> None:
+    if side == "right":
+        bw = 4
+        hk = "hand_right_keypoints_2d"
+    else:
+        bw = 7
+        hk = "hand_left_keypoints_2d"
+
+    pose = p_out.get("pose_keypoints_2d")
+    hand = p_out.get(hk)
+
+    if not (isinstance(pose, list) and isinstance(hand, list)):
+        return
+    if len(pose) < (bw * 3 + 3):
+        return
+    if len(hand) < 3:
+        return
+
+    hx, hy, hc = float(hand[0]), float(hand[1]), float(hand[2])
+    if hc < conf_gate_hand or (hx == 0.0 and hy == 0.0):
+        return
+
+    bx, by, bc = float(pose[bw * 3 + 0]), float(pose[bw * 3 + 1]), float(pose[bw * 3 + 2])
+
+    if bc < conf_gate_body or (bx == 0.0 and by == 0.0):
+        pose[bw * 3 + 0] = hx
+        pose[bw * 3 + 1] = hy
+        pose[bw * 3 + 2] = float(max(bc, min(hc, 0.9)))
+    else:
+        nx = bx * (1.0 - blend) + hx * blend
+        ny = by * (1.0 - blend) + hy * blend
+        pose[bw * 3 + 0] = nx
+        pose[bw * 3 + 1] = ny
+        pose[bw * 3 + 2] = float(min(bc, hc))
+
+    p_out["pose_keypoints_2d"] = pose
+
+
+def _fix_elbow_using_wrist(p_out: Dict[str, Any], *, side: str, conf_gate: float = 0.2) -> None:
+    pose = p_out.get("pose_keypoints_2d")
+    if not isinstance(pose, list) or len(pose) % 3 != 0:
+        return
+
+    if side == "right":
+        sh, el, wr = 2, 3, 4
+    else:
+        sh, el, wr = 5, 6, 7
+
+    def get(j):
+        return float(pose[3 * j + 0]), float(pose[3 * j + 1]), float(pose[3 * j + 2])
+
+    def vis(x, y, c):
+        return c >= conf_gate and not (x == 0.0 and y == 0.0)
+
+    sx, sy, sc = get(sh)
+    ex, ey, ec = get(el)
+    wx, wy, wc = get(wr)
+
+    if not (vis(sx, sy, sc) and vis(wx, wy, wc)):
+        return
+
+    if vis(ex, ey, ec):
+        Lse = math.hypot(ex - sx, ey - sy)
+        Lew = math.hypot(wx - ex, wy - ey)
+    else:
+        dsw = math.hypot(wx - sx, wy - sy)
+        if dsw < 1e-3:
+            return
+        Lse = 0.55 * dsw
+        Lew = 0.45 * dsw
+
+    dx = wx - sx
+    dy = wy - sy
+    d = math.hypot(dx, dy)
+    if d < 1e-6:
+        return
+
+    d2 = max(min(d, (Lse + Lew) - 1e-3), abs(Lse - Lew) + 1e-3)
+
+    a = (Lse * Lse - Lew * Lew + d2 * d2) / (2.0 * d2)
+    h2 = max(Lse * Lse - a * a, 0.0)
+    h = math.sqrt(h2)
+
+    ux = dx / d
+    uy = dy / d
+    px = sx + a * ux
+    py = sy + a * uy
+
+    rx = -uy
+    ry = ux
+
+    e1x, e1y = px + h * rx, py + h * ry
+    e2x, e2y = px - h * rx, py - h * ry
+
+    if vis(ex, ey, ec):
+        if math.hypot(e1x - ex, e1y - ey) <= math.hypot(e2x - ex, e2y - ey):
+            nx, ny = e1x, e1y
+        else:
+            nx, ny = e2x, e2y
+    else:
+        nx, ny = e1x, e1y
+
+    pose[3 * el + 0] = float(nx)
+    pose[3 * el + 1] = float(ny)
+    pose[3 * el + 2] = float(max(min(ec, 0.8), conf_gate))
+
+    p_out["pose_keypoints_2d"] = pose
+
+
+def _remove_short_presence_runs_kps_seq(
+    seq: List[Optional[List[float]]],
+    *,
+    conf_gate: float,
+    min_points_present: int,
+    min_run: int,
+) -> List[Optional[List[float]]]:
+    if not seq:
+        return seq
+
+    present = [(_count_valid_points(a, conf_gate=conf_gate) >= min_points_present) for a in seq]
+    out = [None if a is None else list(a) for a in seq]
+
+    start = None
+    for t in range(len(seq) + 1):
+        cur = present[t] if t < len(seq) else False
+        if cur and start is None:
+            start = t
+        if (not cur) and start is not None:
+            run_len = t - start
+            if run_len < min_run:
+                for k in range(start, t):
+                    out[k] = _zero_out_kps(out[k])
+            start = None
+
+    return out
+
+
+def _zero_sparse_frames_kps_seq(
+    seq: List[Optional[List[float]]], *, conf_gate: float, min_points_present: int
+) -> List[Optional[List[float]]]:
+    if not seq:
+        return seq
+
+    out: List[Optional[List[float]]] = []
+    for a in seq:
+        if not isinstance(a, list):
+            out.append(a)
+            continue
+        if _count_valid_points(a, conf_gate=conf_gate) < min_points_present:
+            out.append(_zero_out_kps(a))
+        else:
+            out.append(a)
+    return out
+
+
+def _suppress_spatial_outliers_in_hand_arr(
+    hand_arr: Optional[List[float]], *, conf_gate: float, max_bone_factor: float = 3.0
+) -> Optional[List[float]]:
+    if not isinstance(hand_arr, list) or len(hand_arr) % 3 != 0:
+        return hand_arr
+    pts = _reshape_keypoints_2d(hand_arr)
+    J = len(pts)
+    if J < 21:
+        return hand_arr
+
+    out = [list(p) for p in pts]
+
+    def vis(j: int) -> bool:
+        x, y, c = out[j]
+        return c >= conf_gate and not (x == 0 and y == 0)
+
+    vv = [(x, y) for (x, y, c) in out if c >= conf_gate and not (x == 0 and y == 0)]
+    if len(vv) < 6:
+        return hand_arr
+    xs = [p[0] for p in vv]
+    ys = [p[1] for p in vv]
+    scale = max(max(xs) - min(xs), max(ys) - min(ys))
+    if scale <= 1e-3:
+        return hand_arr
+    max_bone = max_bone_factor * scale
+
+    for a, b in HAND21_EDGES:
+        if a >= J or b >= J:
+            continue
+        if not vis(a) or not vis(b):
+            continue
+        ax, ay, ac = out[a]
+        bx, by, bc = out[b]
+        d = math.hypot(ax - bx, ay - by)
+        if d > max_bone:
+            if ac <= bc:
+                out[a] = [0.0, 0.0, 0.0]
+            else:
+                out[b] = [0.0, 0.0, 0.0]
+
+    return _flatten_keypoints_2d([(x, y, c) for x, y, c in out])
+
+
+def _body_head_root_scale_from_pose(
+    pose_arr: Optional[List[float]], *, conf_gate: float
+) -> Optional[Tuple[Tuple[float, float], float]]:
+    if not isinstance(pose_arr, list) or len(pose_arr) % 3 != 0:
+        return None
+    kps = _reshape_keypoints_2d(pose_arr)
+
+    def vis(j: int) -> Optional[Tuple[float, float]]:
+        if j >= len(kps):
+            return None
+        x, y, c = kps[j]
+        if c >= conf_gate and not (x == 0 and y == 0):
+            return (float(x), float(y))
+        return None
+
+    pts = []
+    for j in [0, 1, 14, 15, 16, 17]:
+        p = vis(j)
+        if p is not None:
+            pts.append(p)
+
+    if not pts:
+        return None
+
+    rx = sum(p[0] for p in pts) / len(pts)
+    ry = sum(p[1] for p in pts) / len(pts)
+    root = (rx, ry)
+
+    def dist(a: int, b: int) -> Optional[float]:
+        pa, pb = vis(a), vis(b)
+        if pa is None or pb is None:
+            return None
+        d = math.hypot(pa[0] - pb[0], pa[1] - pb[1])
+        return d if d > 1e-3 else None
+
+    cands = [dist(14, 15), dist(16, 17), dist(2, 5)]
+    cands = [c for c in cands if c is not None]
+    if not cands:
+        return None
+
+    scale = float(sum(cands) / len(cands))
+    return root, scale
+
+
+def _body_wrist_root_scale_from_pose(
+    pose_arr: Optional[List[float]], *, side: str, conf_gate: float
+) -> Optional[Tuple[Tuple[float, float], float]]:
+    if not isinstance(pose_arr, list) or len(pose_arr) % 3 != 0:
+        return None
+    kps = _reshape_keypoints_2d(pose_arr)
+
+    if side == "right":
+        w, e = 4, 3
+    else:
+        w, e = 7, 6
+
+    def vis(j: int) -> Optional[Tuple[float, float]]:
+        if j >= len(kps):
+            return None
+        x, y, c = kps[j]
+        if c >= conf_gate and not (x == 0 and y == 0):
+            return (float(x), float(y))
+        return None
+
+    pw = vis(w)
+    if pw is None:
+        return None
+    root = pw
+
+    pe = vis(e)
+    scale = None
+    if pe is not None:
+        d = math.hypot(pw[0] - pe[0], pw[1] - pe[1])
+        if d > 1e-3:
+            scale = d
+
+    if scale is None:
+        p2 = vis(2)
+        p5 = vis(5)
+        if p2 is not None and p5 is not None:
+            d = math.hypot(p2[0] - p5[0], p2[1] - p5[1])
+            if d > 1e-3:
+                scale = d
+
+    if scale is None:
+        return None
+
+    return root, float(scale)
+
+
+def _smooth_dense_seq_anchored_to_body(
+    dense_seq: List[Optional[List[float]]],
+    body_pose_seq: List[Optional[List[float]]],
+    *,
+    kind: str,
+    conf_gate_dense: float,
+    conf_gate_body: float,
+    median3: bool,
+    zero_lag_alpha: float,
+) -> List[Optional[List[float]]]:
+    if not dense_seq:
+        return dense_seq
+
+    Jd = None
+    for a in dense_seq:
+        if isinstance(a, list) and len(a) % 3 == 0 and len(a) > 0:
+            Jd = len(a) // 3
+            break
+    if Jd is None:
+        return dense_seq
+
+    T = len(dense_seq)
+    out = [None if a is None else list(a) for a in dense_seq]
+
+    norm_seq: List[Optional[List[float]]] = [None] * T
+
+    for t in range(T):
+        arr = out[t]
+        body = body_pose_seq[t] if t < len(body_pose_seq) else None
+        if not isinstance(arr, list) or len(arr) != Jd * 3 or not isinstance(body, list):
+            norm_seq[t] = arr
+            continue
+
+        if kind == "face":
+            rs = _body_head_root_scale_from_pose(body, conf_gate=conf_gate_body)
+        elif kind == "hand_left":
+            rs = _body_wrist_root_scale_from_pose(body, side="left", conf_gate=conf_gate_body)
+        else:
+            rs = _body_wrist_root_scale_from_pose(body, side="right", conf_gate=conf_gate_body)
+
+        if rs is None:
+            norm_seq[t] = arr
+            continue
+
+        (rx, ry), s = rs
+        if s <= 1e-6:
+            norm_seq[t] = arr
+            continue
+
+        nn = list(arr)
+        for j in range(Jd):
+            x = float(arr[3 * j + 0])
+            y = float(arr[3 * j + 1])
+            c = float(arr[3 * j + 2])
+            if c >= conf_gate_dense and not (x == 0 and y == 0):
+                nn[3 * j + 0] = (x - rx) / s
+                nn[3 * j + 1] = (y - ry) / s
+        norm_seq[t] = nn
+
+    if median3:
+        norm_seq = _median3_pose_seq(norm_seq, conf_gate=conf_gate_dense)
+
+    norm_seq = _zero_lag_ema_pose_seq(norm_seq, alpha=zero_lag_alpha, conf_gate=conf_gate_dense)
+
+    for t in range(T):
+        arrn = norm_seq[t]
+        body = body_pose_seq[t] if t < len(body_pose_seq) else None
+        if not isinstance(arrn, list) or len(arrn) != Jd * 3 or not isinstance(body, list):
+            continue
+
+        if kind == "face":
+            rs = _body_head_root_scale_from_pose(body, conf_gate=conf_gate_body)
+        elif kind == "hand_left":
+            rs = _body_wrist_root_scale_from_pose(body, side="left", conf_gate=conf_gate_body)
+        else:
+            rs = _body_wrist_root_scale_from_pose(body, side="right", conf_gate=conf_gate_body)
+
+        if rs is None:
+            continue
+
+        (rx, ry), s = rs
+        if s <= 1e-6:
+            continue
+
+        orig = out[t]
+        for j in range(Jd):
+            x = float(arrn[3 * j + 0])
+            y = float(arrn[3 * j + 1])
+            c = float(arrn[3 * j + 2])
+
+            ox = float(orig[3 * j + 0])
+            oy = float(orig[3 * j + 1])
+            oc = float(orig[3 * j + 2])
+
+            if oc >= conf_gate_dense and not (ox == 0 and oy == 0) and c >= conf_gate_dense:
+                orig[3 * j + 0] = rx + x * s
+                orig[3 * j + 1] = ry + y * s
+
+        out[t] = orig
+
+    return out
+
+
+def smooth_KPS_json_obj(
+    data: Any,
+    *,
+    keep_face_untouched: bool = True,
+    keep_hands_untouched: bool = True,
+    filter_extra_people: Optional[bool] = None,
+) -> Any:
+    if not isinstance(data, list):
+        raise ValueError("Expected top-level JSON to be a list of frames.")
+
+    if filter_extra_people is None:
+        filter_extra_people = bool(FILTER_EXTRA_PEOPLE)
+
+    chosen_people: List[Optional[Dict[str, Any]]] = [None] * len(data)
+
+    if MAIN_PERSON_MODE == "longest_track":
+        tracks = _build_tracks_over_video(data)
+        main_tr = _pick_main_track(tracks)
+
+        if main_tr is not None:
+            for t in range(len(data)):
+                if t in main_tr.frames:
+                    chosen_people[t] = main_tr.frames[t]
+        else:
+            prev_center: Optional[Tuple[float, float]] = None
+            for i, frame in enumerate(data):
+                if not isinstance(frame, dict):
+                    continue
+                people = frame.get("people", [])
+                if not isinstance(people, list) or len(people) == 0:
+                    continue
+                chosen = _choose_single_person(people, prev_center)
+                chosen_people[i] = chosen
+                if chosen is not None:
+                    c = _body_center_from_pose(chosen.get("pose_keypoints_2d"))
+                    if c is not None:
+                        prev_center = c
+    else:
+        prev_center: Optional[Tuple[float, float]] = None
+        for i, frame in enumerate(data):
+            if not isinstance(frame, dict):
+                continue
+            people = frame.get("people", [])
+            if not isinstance(people, list) or len(people) == 0:
+                continue
+            chosen = _choose_single_person(people, prev_center)
+            chosen_people[i] = chosen
+            if chosen is not None:
+                c = _body_center_from_pose(chosen.get("pose_keypoints_2d"))
+                if c is not None:
+                    prev_center = c
+
+    pose_seq: List[Optional[List[float]]] = []
+    for p in chosen_people:
+        pose_seq.append(p.get("pose_keypoints_2d") if isinstance(p, dict) else None)
+
+    if SPATIAL_OUTLIER_FIX:
+        pose_seq = [
+            _suppress_spatial_outliers_in_pose_arr(arr, conf_gate=CONF_GATE_BODY) if arr is not None else None
+            for arr in pose_seq
+        ]
+
+    if GAP_FILL_ENABLED:
+        pose_seq = _denoise_and_fill_gaps_pose_seq(
+            pose_seq,
+            conf_gate=CONF_GATE_BODY,
+            min_run=MIN_RUN_FRAMES,
+            max_gap=MAX_GAP_FRAMES,
+        )
+
+    if TORSO_SYNC_ENABLED:
+        pose_seq = _sync_group_appearances(
+            pose_seq,
+            group=TORSO_JOINTS,
+            conf_gate=CONF_GATE_BODY,
+            lookahead=TORSO_LOOKAHEAD_FRAMES,
+        )
+
+    pose_seq = [
+        (
+            _suppress_isolated_joints_in_pose_arr(arr, conf_gate=CONF_GATE_BODY, keep=TORSO_JOINTS)
+            if arr is not None
+            else None
+        )
+        for arr in pose_seq
+    ]
+
+    if MEDIAN3_ENABLED:
+        pose_seq = _median3_pose_seq(pose_seq, conf_gate=CONF_GATE_BODY)
+
+    if SUPER_SMOOTH_ENABLED:
+        pose_seq = _zero_lag_ema_pose_seq(pose_seq, alpha=SUPER_SMOOTH_ALPHA, conf_gate=SUPER_SMOOTH_MIN_CONF)
+
+    if ROOTSCALE_CARRY_ENABLED:
+        pose_seq = _carry_pose_when_torso_missing(
+            pose_seq,
+            conf_gate=CARRY_CONF_GATE,
+            max_carry=CARRY_MAX_FRAMES,
+            anchor_joints=CARRY_ANCHOR_JOINTS,
+            min_anchors=CARRY_MIN_ANCHORS,
+        )
+
+    pose_seq = _force_full_torso_pair(
+        pose_seq,
+        conf_gate=CARRY_CONF_GATE,
+        anchor_joints=CARRY_ANCHOR_JOINTS,
+        min_anchors=CARRY_MIN_ANCHORS,
+        max_lookback=240,
+        fill_legs_with_hip=True,
+        always_fill_if_one_hip=True,
+    )
+
+    face_seq: List[Optional[List[float]]] = []
+    lh_seq: List[Optional[List[float]]] = []
+    rh_seq: List[Optional[List[float]]] = []
+
+    for p in chosen_people:
+        if isinstance(p, dict):
+            face_seq.append(p.get("face_keypoints_2d"))
+            lh_seq.append(p.get("hand_left_keypoints_2d"))
+            rh_seq.append(p.get("hand_right_keypoints_2d"))
+        else:
+            face_seq.append(None)
+            lh_seq.append(None)
+            rh_seq.append(None)
+
+    if HANDS_SMOOTH_ENABLED and (not keep_hands_untouched):
+        lh_seq = [
+            _suppress_spatial_outliers_in_hand_arr(a, conf_gate=CONF_GATE_HAND) if a is not None else None
+            for a in lh_seq
+        ]
+        rh_seq = [
+            _suppress_spatial_outliers_in_hand_arr(a, conf_gate=CONF_GATE_HAND) if a is not None else None
+            for a in rh_seq
+        ]
+
+        lh_seq = _remove_short_presence_runs_kps_seq(
+            lh_seq, conf_gate=CONF_GATE_HAND, min_points_present=HAND_MIN_POINTS_PRESENT, min_run=MIN_HAND_RUN_FRAMES
+        )
+        rh_seq = _remove_short_presence_runs_kps_seq(
+            rh_seq, conf_gate=CONF_GATE_HAND, min_points_present=HAND_MIN_POINTS_PRESENT, min_run=MIN_HAND_RUN_FRAMES
+        )
+
+        lh_seq = _zero_sparse_frames_kps_seq(
+            lh_seq, conf_gate=CONF_GATE_HAND, min_points_present=HAND_MIN_POINTS_PRESENT
+        )
+        rh_seq = _zero_sparse_frames_kps_seq(
+            rh_seq, conf_gate=CONF_GATE_HAND, min_points_present=HAND_MIN_POINTS_PRESENT
+        )
+
+        if DENSE_GAP_FILL_ENABLED:
+            lh_seq = _denoise_and_fill_gaps_pose_seq(
+                lh_seq, conf_gate=CONF_GATE_HAND, min_run=DENSE_MIN_RUN_FRAMES, max_gap=DENSE_MAX_GAP_FRAMES
+            )
+            rh_seq = _denoise_and_fill_gaps_pose_seq(
+                rh_seq, conf_gate=CONF_GATE_HAND, min_run=DENSE_MIN_RUN_FRAMES, max_gap=DENSE_MAX_GAP_FRAMES
+            )
+
+    if FACE_SMOOTH_ENABLED and (not keep_face_untouched):
+        if DENSE_GAP_FILL_ENABLED:
+            face_seq = _denoise_and_fill_gaps_pose_seq(
+                face_seq, conf_gate=CONF_GATE_FACE, min_run=DENSE_MIN_RUN_FRAMES, max_gap=DENSE_MAX_GAP_FRAMES
+            )
+
+    if FACE_SMOOTH_ENABLED and (not keep_face_untouched):
+        face_seq = _smooth_dense_seq_anchored_to_body(
+            face_seq,
+            pose_seq,
+            kind="face",
+            conf_gate_dense=CONF_GATE_FACE,
+            conf_gate_body=CONF_GATE_BODY,
+            median3=DENSE_MEDIAN3_ENABLED,
+            zero_lag_alpha=DENSE_SUPER_SMOOTH_ALPHA,
+        )
+
+    if HANDS_SMOOTH_ENABLED and (not keep_hands_untouched):
+        lh_seq = _smooth_dense_seq_anchored_to_body(
+            lh_seq,
+            pose_seq,
+            kind="hand_left",
+            conf_gate_dense=CONF_GATE_HAND,
+            conf_gate_body=CONF_GATE_BODY,
+            median3=DENSE_MEDIAN3_ENABLED,
+            zero_lag_alpha=DENSE_SUPER_SMOOTH_ALPHA,
+        )
+        rh_seq = _smooth_dense_seq_anchored_to_body(
+            rh_seq,
+            pose_seq,
+            kind="hand_right",
+            conf_gate_dense=CONF_GATE_HAND,
+            conf_gate_body=CONF_GATE_BODY,
+            median3=DENSE_MEDIAN3_ENABLED,
+            zero_lag_alpha=DENSE_SUPER_SMOOTH_ALPHA,
+        )
+
+    out_frames = []
+    body_state: Optional[BodyState] = None
+
+    for i, frame in enumerate(data):
+        if not isinstance(frame, dict):
+            out_frames.append(frame)
+            continue
+
+        frame_out = copy.deepcopy(frame)
+        chosen = chosen_people[i]
+
+        if chosen is None:
+            if filter_extra_people:
+                frame_out["people"] = []
+            out_frames.append(frame_out)
+            continue
+
+        p_out = copy.deepcopy(chosen)
+        p_out["pose_keypoints_2d"] = pose_seq[i]
+
+        pose_arr = p_out.get("pose_keypoints_2d")
+        joints = (len(pose_arr) // 3) if isinstance(pose_arr, list) else 0
+        if body_state is None:
+            body_state = BodyState(joints if joints > 0 else 18)
+
+        p_out["pose_keypoints_2d"] = _smooth_body_pose(p_out.get("pose_keypoints_2d"), body_state)
+
+        if FACE_SMOOTH_ENABLED and (not keep_face_untouched):
+            p_out["face_keypoints_2d"] = face_seq[i]
+        else:
+            p_out["face_keypoints_2d"] = chosen.get("face_keypoints_2d", p_out.get("face_keypoints_2d"))
+
+        if HANDS_SMOOTH_ENABLED and (not keep_hands_untouched):
+            p_out["hand_left_keypoints_2d"] = lh_seq[i]
+            p_out["hand_right_keypoints_2d"] = rh_seq[i]
+        else:
+            p_out["hand_left_keypoints_2d"] = chosen.get("hand_left_keypoints_2d", p_out.get("hand_left_keypoints_2d"))
+            p_out["hand_right_keypoints_2d"] = chosen.get(
+                "hand_right_keypoints_2d", p_out.get("hand_right_keypoints_2d")
+            )
+
+        _pin_body_wrist_to_hand(
+            p_out, side="left", conf_gate_body=CONF_GATE_BODY, conf_gate_hand=CONF_GATE_HAND, blend=1.0
+        )
+        _pin_body_wrist_to_hand(
+            p_out, side="right", conf_gate_body=CONF_GATE_BODY, conf_gate_hand=CONF_GATE_HAND, blend=1.0
+        )
+
+        _fix_elbow_using_wrist(p_out, side="left", conf_gate=CONF_GATE_BODY)
+        _fix_elbow_using_wrist(p_out, side="right", conf_gate=CONF_GATE_BODY)
+
+        if filter_extra_people:
+            frame_out["people"] = [p_out]
+        else:
+            orig_people = frame.get("people", [])
+            if not isinstance(orig_people, list):
+                frame_out["people"] = [p_out]
+            else:
+                replaced = False
+                new_people = []
+                for op in orig_people:
+                    if (not replaced) and (op is chosen):
+                        new_people.append(p_out)
+                        replaced = True
+                    else:
+                        new_people.append(copy.deepcopy(op))
+                if not replaced:
+                    new_people = [p_out] + [copy.deepcopy(op) for op in orig_people]
+                frame_out["people"] = new_people
+
+        out_frames.append(frame_out)
+
+    return out_frames
+
+
+# ============================================================
+# === END: smooth_KPS_json.py logic
+# ============================================================
+
+
+# ============================================================
+# === START: render_pose_video.py logic (ported to frame render)
+# ============================================================
+
+OP_COLORS: List[Tuple[int, int, int]] = [
+    (255, 0, 0),
+    (255, 85, 0),
+    (255, 170, 0),
+    (255, 255, 0),
+    (170, 255, 0),
+    (85, 255, 0),
+    (0, 255, 0),
+    (0, 255, 85),
+    (0, 255, 170),
+    (0, 255, 255),
+    (0, 170, 255),
+    (0, 85, 255),
+    (0, 0, 255),
+    (85, 0, 255),
+    (170, 0, 255),
+    (255, 0, 255),
+    (255, 0, 170),
+    (255, 0, 85),
+]
+
+BODY_EDGES: List[Tuple[int, int]] = [
+    (1, 2),
+    (1, 5),
+    (2, 3),
+    (3, 4),
+    (5, 6),
+    (6, 7),
+    (1, 8),
+    (8, 9),
+    (9, 10),
+    (1, 11),
+    (11, 12),
+    (12, 13),
+    (1, 0),
+    (0, 14),
+    (14, 16),
+    (0, 15),
+    (15, 17),
+]
+
+BODY_EDGE_COLORS = OP_COLORS[: len(BODY_EDGES)]
+BODY_JOINT_COLORS = OP_COLORS
+
+HAND_EDGES: List[Tuple[int, int]] = [
+    (0, 1),
+    (1, 2),
+    (2, 3),
+    (3, 4),
+    (0, 5),
+    (5, 6),
+    (6, 7),
+    (7, 8),
+    (0, 9),
+    (9, 10),
+    (10, 11),
+    (11, 12),
+    (0, 13),
+    (13, 14),
+    (14, 15),
+    (15, 16),
+    (0, 17),
+    (17, 18),
+    (18, 19),
+    (19, 20),
+]
+
+
+def _valid_pt(x: float, y: float, c: float, conf_thresh: float) -> bool:
+    return (c is not None) and (c >= conf_thresh) and not (x == 0 and y == 0)
+
+
+def _hsv_to_bgr(h: float, s: float, v: float) -> Tuple[int, int, int]:
+    H = int(np.clip(h, 0.0, 1.0) * 179.0)
+    S = int(np.clip(s, 0.0, 1.0) * 255.0)
+    V = int(np.clip(v, 0.0, 1.0) * 255.0)
+    hsv = np.uint8([[[H, S, V]]])
+    bgr = cv2.cvtColor(hsv, cv2.COLOR_HSV2BGR)[0, 0]
+    return int(bgr[0]), int(bgr[1]), int(bgr[2])
+
+
+def _looks_normalized(points: List[Tuple[float, float, float]], conf_thresh: float) -> bool:
+    valid = [(x, y, c) for (x, y, c) in points if _valid_pt(x, y, c, conf_thresh)]
+    if not valid:
+        return False
+    in01 = sum(1 for (x, y, _) in valid if 0.0 <= x <= 1.0 and 0.0 <= y <= 1.0)
+    return (in01 / float(len(valid))) >= 0.7
+
+
+def _draw_body(
+    canvas: np.ndarray, pose: List[Tuple[float, float, float]], conf_thresh: float, xinsr_stick_scaling: bool = False
+) -> None:
+    CH, CW = canvas.shape[:2]
+    stickwidth = 2
+
+    valid = [(x, y, c) for (x, y, c) in pose if _valid_pt(x, y, c, conf_thresh)]
+    norm = False
+    if valid:
+        in01 = sum(1 for (x, y, _) in valid if 0.0 <= x <= 1.0 and 0.0 <= y <= 1.0)
+        norm = (in01 / float(len(valid))) >= 0.7
+
+    def to_px(x: float, y: float) -> Tuple[float, float]:
+        if norm:
+            return x * CW, y * CH
+        return x, y
+
+    max_side = max(CW, CH)
+    if xinsr_stick_scaling:
+        stick_scale = 1 if max_side < 500 else min(2 + (max_side // 1000), 7)
+    else:
+        stick_scale = 1
+
+    for idx, (a, b) in enumerate(BODY_EDGES):
+        if a >= len(pose) or b >= len(pose):
+            continue
+
+        ax, ay, ac = pose[a]
+        bx, by, bc = pose[b]
+        if not (_valid_pt(ax, ay, ac, conf_thresh) and _valid_pt(bx, by, bc, conf_thresh)):
+            continue
+
+        ax, ay = to_px(ax, ay)
+        bx, by = to_px(bx, by)
+
+        base = BODY_EDGE_COLORS[idx] if idx < len(BODY_EDGE_COLORS) else (255, 255, 255)
+
+        X = np.array([ay, by], dtype=np.float32)
+        Y = np.array([ax, bx], dtype=np.float32)
+
+        mX = float(np.mean(X))
+        mY = float(np.mean(Y))
+        length = float(np.hypot(X[0] - X[1], Y[0] - Y[1]))
+        if length < 1.0:
+            continue
+
+        angle = math.degrees(math.atan2(X[0] - X[1], Y[0] - Y[1]))
+
+        polygon = cv2.ellipse2Poly(
+            (int(mY), int(mX)),
+            (int(length / 2), int(stickwidth * stick_scale)),
+            int(angle),
+            0,
+            360,
+            1,
+        )
+
+        cv2.fillConvexPoly(
+            canvas,
+            polygon,
+            (int(base[0] * 0.6), int(base[1] * 0.6), int(base[2] * 0.6)),
+        )
+
+    for j, (x, y, c) in enumerate(pose):
+        if not _valid_pt(x, y, c, conf_thresh):
+            continue
+        x, y = to_px(x, y)
+        col = BODY_JOINT_COLORS[j] if j < len(BODY_JOINT_COLORS) else (255, 255, 255)
+        cv2.circle(canvas, (int(x), int(y)), 2, col, thickness=-1)
+
+
+def _draw_hand(canvas: np.ndarray, hand: List[Tuple[float, float, float]], conf_thresh: float) -> None:
+    if not hand or len(hand) < 21:
+        return
+
+    CH, CW = canvas.shape[:2]
+    norm = _looks_normalized(hand, conf_thresh)
+
+    def to_px(x: float, y: float) -> Tuple[float, float]:
+        return (x * CW, y * CH) if norm else (x, y)
+
+    n_edges = len(HAND_EDGES)
+    for i, (a, b) in enumerate(HAND_EDGES):
+        x1, y1, c1 = hand[a]
+        x2, y2, c2 = hand[b]
+        if _valid_pt(x1, y1, c1, conf_thresh) and _valid_pt(x2, y2, c2, conf_thresh):
+            x1, y1 = to_px(x1, y1)
+            x2, y2 = to_px(x2, y2)
+            bgr = _hsv_to_bgr(i / float(n_edges), 1.0, 1.0)
+            cv2.line(canvas, (int(x1), int(y1)), (int(x2), int(y2)), bgr, 1, cv2.LINE_AA)
+
+    for x, y, c in hand:
+        if _valid_pt(x, y, c, conf_thresh):
+            x, y = to_px(x, y)
+            cv2.circle(canvas, (int(x), int(y)), 1, (0, 0, 255), -1, cv2.LINE_AA)
+
+
+def _draw_face(canvas: np.ndarray, face: List[Tuple[float, float, float]], conf_thresh: float) -> None:
+    if not face:
+        return
+
+    CH, CW = canvas.shape[:2]
+    norm = _looks_normalized(face, conf_thresh)
+
+    def to_px(x: float, y: float) -> Tuple[float, float]:
+        return (x * CW, y * CH) if norm else (x, y)
+
+    for x, y, c in face:
+        if _valid_pt(x, y, c, conf_thresh):
+            x, y = to_px(x, y)
+            cv2.circle(canvas, (int(x), int(y)), 0, (255, 255, 255), -1, cv2.LINE_AA)
+
+
+def _draw_pose_frame_full(
+    w: int,
+    h: int,
+    person: Dict[str, Any],
+    conf_thresh_body: float = 0.10,
+    conf_thresh_hands: float = 0.10,
+    conf_thresh_face: float = 0.10,
+) -> np.ndarray:
+    img = np.zeros((h, w, 3), dtype=np.uint8)
+
+    pose = _reshape_keypoints_2d(person.get("pose_keypoints_2d") or [])
+    face = _reshape_keypoints_2d(person.get("face_keypoints_2d") or [])
+    hand_l = _reshape_keypoints_2d(person.get("hand_left_keypoints_2d") or [])
+    hand_r = _reshape_keypoints_2d(person.get("hand_right_keypoints_2d") or [])
+
+    if pose:
+        _draw_body(img, pose, conf_thresh_body)
+    if hand_l:
+        _draw_hand(img, hand_l, conf_thresh_hands)
+    if hand_r:
+        _draw_hand(img, hand_r, conf_thresh_hands)
+    if face:
+        _draw_face(img, face, conf_thresh_face)
+
+    return img
+
+
+# ============================================================
+# === END: render_pose_video.py logic
+# ============================================================
+
+
+# ============================================================
+# ComfyUI mappings
+# ============================================================
+
+NODE_CLASS_MAPPINGS = {
+    "TSPoseDataSmoother": KPSSmoothPoseDataAndRender,
+}
+
+NODE_DISPLAY_NAME_MAPPINGS = {
+    "TSPoseDataSmoother": "KPS: Smooth + Render (pose_data/PKL)",
+}

load_video_batch.py

@@ -0,0 +1,20 @@
+from .save_load_pose import TSSavePoseDataAsPickle, TSLoadPoseDataPickle
+from .openpose_smoother import KPSSmoothPoseDataAndRender
+from .load_video_batch import LoadVideoBatchListFromDir
+from .rename_files import RenameFilesInDir
+
+NODE_CLASS_MAPPINGS = {
+    "TSSavePoseDataAsPickle": TSSavePoseDataAsPickle,
+    "TSLoadPoseDataPickle": TSLoadPoseDataPickle,
+    "TSPoseDataSmoother": KPSSmoothPoseDataAndRender,
+    "TSLoadVideoBatchListFromDir": LoadVideoBatchListFromDir,
+    "TSRenameFilesInDir": RenameFilesInDir,
+}
+
+NODE_DISPLAY_NAME_MAPPINGS = {
+    "TSSavePoseDataAsPickle": "TS Save Pose Data (PKL)",
+    "TSLoadPoseDataPickle": "TS Load Pose Data (PKL)",
+    "TSPoseDataSmoother": "TS Pose Data Smoother",
+    "TSLoadVideoBatchListFromDir": "TS Load Video Batch List From Dir",
+    "TSRenameFilesInDir": "TS Rename Files In Dir",
+}

openpose_smoother.py

@@ -0,0 +1,351 @@
+import os
+import re
+import shutil
+import subprocess
+import time
+from collections.abc import Mapping
+
+import torch
+import numpy as np
+
+# OpenCV for video decoding
+try:
+    import cv2
+
+    _has_cv2 = True
+except Exception:
+    _has_cv2 = False
+
+
+# =========================
+# AUDIO (встроено из utils)
+# =========================
+ENCODE_ARGS = ("utf-8", "backslashreplace")
+
+
+def _pick_ffmpeg_path():
+    # 1) env override (как в VHS)
+    if "VHS_FORCE_FFMPEG_PATH" in os.environ:
+        p = os.environ.get("VHS_FORCE_FFMPEG_PATH")
+        if p:
+            return p
+
+    # 2) system ffmpeg
+    system_ffmpeg = shutil.which("ffmpeg")
+    if system_ffmpeg is not None:
+        return system_ffmpeg
+
+    # 3) local рядом
+    if os.path.isfile("ffmpeg"):
+        return os.path.abspath("ffmpeg")
+    if os.path.isfile("ffmpeg.exe"):
+        return os.path.abspath("ffmpeg.exe")
+
+    return None
+
+
+ffmpeg_path = _pick_ffmpeg_path()
+
+
+def get_audio(file, start_time=0, duration=0):
+    if ffmpeg_path is None:
+        raise Exception("ffmpeg not found. Put ffmpeg in PATH, or set VHS_FORCE_FFMPEG_PATH env var.")
+
+    args = [ffmpeg_path, "-i", file]
+    if start_time > 0:
+        args += ["-ss", str(start_time)]
+    if duration > 0:
+        args += ["-t", str(duration)]
+
+    try:
+        # как в utils: вытаскиваем raw f32le в stdout
+        res = subprocess.run(args + ["-f", "f32le", "-"], capture_output=True, check=True)
+        audio = torch.frombuffer(bytearray(res.stdout), dtype=torch.float32)
+        match = re.search(r", (\d+) Hz, (\w+), ", res.stderr.decode(*ENCODE_ARGS))
+    except subprocess.CalledProcessError as e:
+        raise Exception(f"Failed to extract audio from {file}:\n" + e.stderr.decode(*ENCODE_ARGS))
+
+    if match:
+        ar = int(match.group(1))
+        ac = {"mono": 1, "stereo": 2}.get(match.group(2), 2)
+    else:
+        ar = 44100
+        ac = 2
+
+    # reshape как в utils: (-1, channels) -> (channels, samples) -> (1, channels, samples)
+    if audio.numel() == 0:
+        # видео без аудио — вернем пустой аудиобуфер, но корректный формат
+        empty = torch.zeros((1, 1, 0), dtype=torch.float32)
+        return {"waveform": empty, "sample_rate": ar}
+
+    audio = audio.reshape((-1, ac)).transpose(0, 1).unsqueeze(0)
+    return {"waveform": audio, "sample_rate": ar}
+
+
+class LazyAudioMap(Mapping):
+    def __init__(self, file, start_time, duration):
+        self.file = file
+        self.start_time = start_time
+        self.duration = duration
+        self._dict = None
+
+    def _ensure(self):
+        if self._dict is None:
+            self._dict = get_audio(self.file, self.start_time, self.duration)
+
+    def __getitem__(self, key):
+        self._ensure()
+        return self._dict[key]
+
+    def __iter__(self):
+        self._ensure()
+        return iter(self._dict)
+
+    def __len__(self):
+        self._ensure()
+        return len(self._dict)
+
+
+def lazy_get_audio(file, start_time=0, duration=0, **kwargs):
+    return LazyAudioMap(file, start_time, duration)
+
+
+# =========================
+# остальной код ноды
+# =========================
+
+
+def extract_first_number(s):
+    match = re.search(r"\d+", s)
+    return int(match.group()) if match else float("inf")
+
+
+sort_methods = [
+    "None",
+    "Alphabetical (ASC)",
+    "Alphabetical (DESC)",
+    "Numerical (ASC)",
+    "Numerical (DESC)",
+    "Datetime (ASC)",
+    "Datetime (DESC)",
+]
+
+
+def sort_by(items, base_path=".", method=None):
+    def fullpath(x):
+        return os.path.join(base_path, x)
+
+    def get_timestamp(path):
+        try:
+            return os.path.getmtime(path)
+        except FileNotFoundError:
+            return float("-inf")
+
+    if method == "Alphabetical (ASC)":
+        return sorted(items)
+    elif method == "Alphabetical (DESC)":
+        return sorted(items, reverse=True)
+    elif method == "Numerical (ASC)":
+        return sorted(items, key=lambda x: extract_first_number(os.path.splitext(x)[0]))
+    elif method == "Numerical (DESC)":
+        return sorted(items, key=lambda x: extract_first_number(os.path.splitext(x)[0]), reverse=True)
+    elif method == "Datetime (ASC)":
+        return sorted(items, key=lambda x: get_timestamp(fullpath(x)))
+    elif method == "Datetime (DESC)":
+        return sorted(items, key=lambda x: get_timestamp(fullpath(x)), reverse=True)
+    else:
+        return items
+
+
+def target_size(width, height, custom_width, custom_height, downscale_ratio=8):
+    if downscale_ratio is None:
+        downscale_ratio = 8
+
+    if custom_width == 0 and custom_height == 0:
+        new_w, new_h = width, height
+    elif custom_height == 0:
+        new_h = int(height * (custom_width / width))
+        new_w = int(custom_width)
+    elif custom_width == 0:
+        new_w = int(width * (custom_height / height))
+        new_h = int(custom_height)
+    else:
+        new_w, new_h = int(custom_width), int(custom_height)
+
+    new_w = int(new_w / downscale_ratio + 0.5) * downscale_ratio
+    new_h = int(new_h / downscale_ratio + 0.5) * downscale_ratio
+    return new_w, new_h
+
+
+def _read_frames_vhs_like(
+    video_path: str,
+    force_rate: float = 0,
+    custom_width: int = 0,
+    custom_height: int = 0,
+    downscale_ratio: int = 8,
+    frame_load_cap: int = 0,
+):
+    if not _has_cv2:
+        raise RuntimeError("OpenCV (cv2) not available. Install opencv-python.")
+
+    cap = cv2.VideoCapture(video_path)
+    if not cap.isOpened() or not cap.grab():
+        raise FileNotFoundError(f"Cannot open video: {video_path}")
+
+    fps = cap.get(cv2.CAP_PROP_FPS)
+    if fps is None or fps <= 0:
+        fps = 30.0
+
+    width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+    height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+
+    ok0, frame0 = cap.retrieve()
+    if not ok0 or frame0 is None:
+        cap.release()
+        raise RuntimeError(f"Cannot retrieve first frame from: {video_path}")
+
+    if width <= 0 or height <= 0:
+        height, width = frame0.shape[:2]
+
+    base_dt = 1.0 / float(fps)
+    target_dt = base_dt if force_rate == 0 else (1.0 / float(force_rate))
+    loaded_fps = 1.0 / target_dt if target_dt > 0 else float(fps)
+
+    new_w, new_h = target_size(width, height, custom_width, custom_height, downscale_ratio)
+    do_resize = (new_w != width) or (new_h != height)
+
+    frames = []
+    time_offset = target_dt
+
+    def _process_frame(bgr):
+        rgb = cv2.cvtColor(bgr, cv2.COLOR_BGR2RGB)
+        if do_resize:
+            rgb = cv2.resize(rgb, (new_w, new_h), interpolation=cv2.INTER_LANCZOS4)
+        return rgb
+
+    frames.append(_process_frame(frame0))
+    if frame_load_cap > 0 and len(frames) >= frame_load_cap:
+        cap.release()
+        arr = np.stack(frames, axis=0).astype(np.float32) / 255.0
+        t = torch.from_numpy(arr)
+        return t, float(fps), float(loaded_fps), float(len(t) * target_dt), 0.0
+
+    time_offset -= target_dt
+
+    while cap.isOpened():
+        if time_offset < target_dt:
+            ok = cap.grab()
+            if not ok:
+                break
+            time_offset += base_dt
+            continue
+
+        ok, frame_bgr = cap.retrieve()
+        if not ok or frame_bgr is None:
+            break
+
+        frames.append(_process_frame(frame_bgr))
+
+        if frame_load_cap > 0 and len(frames) >= frame_load_cap:
+            break
+
+        time_offset -= target_dt
+
+    cap.release()
+
+    if len(frames) == 0:
+        raise RuntimeError(f"No frames could be read from: {video_path}")
+
+    arr = np.stack(frames, axis=0).astype(np.float32) / 255.0
+    t = torch.from_numpy(arr)
+    loaded_duration = float(len(t) * target_dt)
+    return t, float(fps), float(loaded_fps), loaded_duration, 0.0
+
+
+class LoadVideoBatchListFromDir:
+    @classmethod
+    def INPUT_TYPES(s):
+        return {
+            "required": {
+                "directory": ("STRING", {"default": ""}),
+                "force_rate": ("FLOAT", {"default": 0, "min": 0, "max": 120, "step": 1}),
+                "width": ("INT", {"default": 720, "min": 0, "max": 8192, "step": 1}),
+                "height": ("INT", {"default": 1280, "min": 0, "max": 8192, "step": 1}),
+            },
+            "optional": {
+                "video_load_cap": ("INT", {"default": 0, "min": 0, "step": 1}),
+                "frame_load_cap": ("INT", {"default": 0, "min": 0, "step": 1}),
+                "start_index": ("INT", {"default": 0, "min": 0, "max": 0xFFFFFFFFFFFFFFFF, "step": 1}),
+                "load_always": ("BOOLEAN", {"default": False, "label_on": "enabled", "label_off": "disabled"}),
+                "sort_method": (sort_methods,),
+            },
+        }
+
+    RETURN_TYPES = ("IMAGE", "AUDIO", "INT")
+    RETURN_NAMES = ("IMAGE", "audio", "COUNT")
+    OUTPUT_IS_LIST = (True, True, False)
+
+    FUNCTION = "load_videos"
+    CATEGORY = "video"
+
+    @classmethod
+    def IS_CHANGED(cls, **kwargs):
+        if kwargs.get("load_always"):
+            return float("NaN")
+        return hash(frozenset(kwargs.items()))
+
+    def load_videos(
+        self,
+        directory: str,
+        force_rate: float = 0,
+        width: int = 0,
+        height: int = 0,
+        video_load_cap: int = 0,
+        frame_load_cap: int = 0,
+        start_index: int = 0,
+        load_always: bool = False,
+        sort_method=None,
+    ):
+        if not os.path.isdir(directory):
+            raise FileNotFoundError(f"Directory '{directory}' cannot be found.")
+
+        files = os.listdir(directory)
+        if len(files) == 0:
+            raise FileNotFoundError(f"No files in directory '{directory}'.")
+
+        valid_ext = {".mp4", ".mov", ".mkv", ".webm", ".avi", ".m4v"}
+        files = [
+            f
+            for f in files
+            if os.path.isfile(os.path.join(directory, f)) and os.path.splitext(f)[1].lower() in valid_ext
+        ]
+        if len(files) == 0:
+            raise FileNotFoundError(f"No video files in directory '{directory}' (expected: {sorted(valid_ext)}).")
+
+        files = sort_by(files, directory, sort_method)
+        files = files[start_index:]
+        if video_load_cap > 0:
+            files = files[:video_load_cap]
+
+        images_list = []
+        audios_list = []
+
+        for fname in files:
+            path = os.path.join(directory, fname)
+
+            vid, source_fps, loaded_fps, loaded_duration, start_time = _read_frames_vhs_like(
+                path,
+                force_rate=force_rate,
+                custom_width=width,
+                custom_height=height,
+                downscale_ratio=8,
+                frame_load_cap=frame_load_cap,
+            )
+
+            images_list.append(vid)
+
+            # duration based on loaded frames/time
+            audio = lazy_get_audio(path, start_time, loaded_duration)
+            audios_list.append(audio)
+
+        return (images_list, audios_list, len(images_list))

requirements.txt

@@ -0,0 +1,200 @@
+import os
+import re
+import uuid
+import shutil
+
+
+def extract_first_number(s: str):
+    match = re.search(r"\d+", s)
+    return int(match.group()) if match else float("inf")
+
+
+sort_methods = [
+    "None",
+    "Alphabetical (ASC)",
+    "Alphabetical (DESC)",
+    "Numerical (ASC)",
+    "Numerical (DESC)",
+    "Datetime (ASC)",
+    "Datetime (DESC)",
+]
+
+
+def sort_by(items, base_path=".", method=None):
+    def fullpath(x):
+        return os.path.join(base_path, x)
+
+    def get_timestamp(path):
+        try:
+            return os.path.getmtime(path)
+        except FileNotFoundError:
+            return float("-inf")
+
+    if method == "Alphabetical (ASC)":
+        return sorted(items)
+    elif method == "Alphabetical (DESC)":
+        return sorted(items, reverse=True)
+    elif method == "Numerical (ASC)":
+        return sorted(items, key=lambda x: extract_first_number(os.path.splitext(x)[0]))
+    elif method == "Numerical (DESC)":
+        return sorted(items, key=lambda x: extract_first_number(os.path.splitext(x)[0]), reverse=True)
+    elif method == "Datetime (ASC)":
+        return sorted(items, key=lambda x: get_timestamp(fullpath(x)))
+    elif method == "Datetime (DESC)":
+        return sorted(items, key=lambda x: get_timestamp(fullpath(x)), reverse=True)
+    else:
+        return items
+
+
+def _safe_list_files(directory: str):
+    return [f for f in os.listdir(directory) if os.path.isfile(os.path.join(directory, f))]
+
+
+def _format_name(index: int, digits: int, prefix: str, ext: str):
+    """
+    ext ожидается как ".png"/".jpg"/".jpeg" (с точкой).
+    ВАЖНО: underscore после номера ВСЕГДА, потом расширение как есть.
+    Пример: prefix_0001_.png
+    """
+    num = str(index).zfill(digits)
+    left = f"{prefix}_" if prefix else ""
+    return f"{left}{num}_{ext}"
+
+
+def _index_taken(directory: str, digits: int, prefix: str, index: int) -> bool:
+    """
+    Проверяем, занят ли номер index ЛЮБЫМ расширением в папке.
+    Т.е. если есть prefix_0001_.png, то prefix_0001_.jpg уже нельзя.
+    """
+    num = str(index).zfill(digits)
+    left = f"{prefix}_" if prefix else ""
+    start = f"{left}{num}_"
+
+    try:
+        entries = os.listdir(directory)
+    except FileNotFoundError:
+        return False
+
+    for f in entries:
+        p = os.path.join(directory, f)
+        if os.path.isfile(p) and f.startswith(start):
+            return True
+    return False
+
+
+def _find_next_free_index(directory: str, digits: int, prefix: str, start_from: int = 1) -> int:
+    idx = max(1, int(start_from))
+    while _index_taken(directory, digits, prefix, idx):
+        idx += 1
+    return idx
+
+
+class RenameFilesInDir:
+    OUTPUT_NODE = True
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "directory": ("STRING", {"default": ""}),
+            },
+            "optional": {
+                "output_directory": ("STRING", {"default": ""}),
+                "sort_method": (sort_methods,),
+                "start_index": ("INT", {"default": 0, "min": 0, "max": 0xFFFFFFFFFFFFFFFF, "step": 1}),
+                "files_load_cap": ("INT", {"default": 0, "min": 0, "step": 1}),
+                "prefix": ("STRING", {"default": ""}),
+                "digits": ("INT", {"default": 4, "min": 1, "max": 16, "step": 1}),
+            },
+        }
+
+    RETURN_TYPES = ("INT",)
+    RETURN_NAMES = ("COUNT",)
+    FUNCTION = "run"
+    CATEGORY = "InspirePack/files"
+
+    @classmethod
+    def IS_CHANGED(cls, **kwargs):
+        return float("NaN")
+
+    def run(
+        self,
+        directory: str,
+        output_directory: str = "",
+        sort_method=None,
+        start_index: int = 0,
+        files_load_cap: int = 0,
+        prefix: str = "",
+        digits: int = 4,
+    ):
+        if not os.path.isdir(directory):
+            raise FileNotFoundError(f"Directory '{directory}' cannot be found.")
+
+        files = _safe_list_files(directory)
+        if not files:
+            return (0,)
+
+        files = sort_by(files, directory, sort_method)
+        files = files[start_index:]
+
+        if files_load_cap > 0:
+            files = files[:files_load_cap]
+
+        if not files:
+            return (0,)
+
+        inplace = (output_directory is None) or (str(output_directory).strip() == "")
+
+        if not inplace:
+            os.makedirs(output_directory, exist_ok=True)
+
+        count = 0
+
+        # ---------- COPY MODE ----------
+        if not inplace:
+            for fname in files:
+                src = os.path.join(directory, fname)
+                _, ext = os.path.splitext(fname)  # ext = ".png" / ".jpg" / ...
+
+                next_idx = _find_next_free_index(output_directory, digits, prefix, start_from=1)
+                new_name = _format_name(next_idx, digits, prefix, ext)
+
+                dst = os.path.join(output_directory, new_name)
+                shutil.copy2(src, dst)
+                count += 1
+
+            return (count,)
+
+        # ---------- INPLACE RENAME ----------
+        temp_map = []
+        used_temp = set()
+
+        def _make_temp_name(old_name: str):
+            while True:
+                t = f"__tmp__{uuid.uuid4().hex}__{old_name}"
+                if t not in used_temp and not os.path.exists(os.path.join(directory, t)):
+                    used_temp.add(t)
+                    return t
+
+        # phase1 -> temp
+        for fname in files:
+            old_path = os.path.join(directory, fname)
+            tmp = _make_temp_name(fname)
+            tmp_path = os.path.join(directory, tmp)
+
+            os.rename(old_path, tmp_path)
+            temp_map.append((tmp, fname))
+
+        # phase2 -> final
+        for tmp, original_name in temp_map:
+            tmp_path = os.path.join(directory, tmp)
+            _, ext = os.path.splitext(original_name)
+
+            next_idx = _find_next_free_index(directory, digits, prefix, start_from=1)
+            new_name = _format_name(next_idx, digits, prefix, ext)
+
+            new_path = os.path.join(directory, new_name)
+            os.rename(tmp_path, new_path)
+            count += 1
+
+        return (count,)

save_load_pose.py

@@ -0,0 +1,2 @@
+numpy
+opencv-python