MiniMax H3 Face Track Assign / 轨迹绑定角色 (Advanced)

This is the node that answers "which face in the video is Alice, and which is Bob?" in the multi-person face-refine pipeline. You hand it the frames, a SAM3.1 track plan (the per-shot face tracks), and your face cast, and it binds every shot-local track to a reviewed character profile. The default identity_mode is sface_cpu_suggest - CPU SFace similarity suggestions, one-to-one within each shot, that fail closed below a similarity or margin threshold. If it's not confident, it says so instead of guessing.

The two thresholds are the heart of it:

• minimum_similarity (0.4) - how close a track's embedding must be to a character's profile before the suggestion counts.
• minimum_margin (0.05) - how much the best match must beat the runner-up. A track that's 0.42 to Alice and 0.41 to Bob has no margin, and a margin failure is exactly the case where auto-assignment goes wrong. Raise this if you're getting flip-flops.

Then the manual escape hatch: manual_assignments_json, which is authoritative. JSON like {"0:0":"Alice","0:1":"Bob"} overrides the suggestion outright - shot index first, track index second. If the video has two people and the similarity engine can't tell them apart because they look alike or the references are weak, you just tell it who's who per shot. That's the whole reason this node exists rather than a black-box matcher: it's built to be corrected by a human reviewer, and the strict identity mode (strict_identity, true) plus the fail-closed thresholds make sure the defaults don't silently overwrite your calls.

Other inputs: frames (the source frames), track_plan (the H3_T8_SAM31_MULTIFACE_TRACK_PLAN from the pack's SAM3.1 tracking node), face_cast (from Face Cast Merge), identity_samples_per_track (3 - how many frames per track get sampled for the similarity vote), and preview_stride (8) for the preview output.

Outputs: identity_assignment (the H3_T8_MULTIFACE_IDENTITY_ASSIGNMENT the downstream per-character refine consumes), assignment_preview (an IMAGE you can inspect), report_json, and track_count.

Where this fits: it's the identity layer between SAM tracking and per-character refinement - without it, the refine nodes have no idea which character's profile applies to which crop. And the pack's framing is worth repeating: the suggestions are CPU matching aids, not forensic identity. This is a production-assist for keeping two characters consistent across a scene, and it's built to let you override the machine when the machine is unsure.

Install: ComfyUI Manager → "MiniMax H3 Audio T8", or:

cd ComfyUI/custom_nodes
git clone https://github.com/T8mars/comfyui-minimax-h3-audio-T8

Restart after. No forced pip deps, no downloads - YuNet/SFace from local OpenCV, SAM3.1 tracks come from the tracking node upstream.