mmprompt/easy-media-track-gate/README.md
Z User ea5c5a71b4 easy-media-track-gate: the h3-plan-gate methodology adapted to ComfyUI-Easy-Media multitrack nodes
Portable self-contained skill (%USERPROFILE%\.agent\skills\easy-media-track-gate\):
- references/track-schema.md: full English translation of the node pack's Chinese
  multitrack-schema.md (resolution DynamicCombo rules, time semantics, task segment
  content, context/context_drift joins, audio locks, shared media, project params,
  patch plan shape); field names cross-checked against patch_workflow.py source.
- verify_track_rules.py (66 KB, stdlib only): mirrors every check the node pack's
  patch_workflow.py performs at apply time (ids, sorting, overlap, frames, source_type
  field matching, <=9 images, continuity enums, one locked audio + one locked video,
  locked-media task coverage, shared_reference rules, resolution tokens, project
  fields) and adds the gates upstream leaves to discipline: outline pins (id/frames/
  modes/image set diffed per fragment AND at the merge), verbatim media contract
  (file_path character-for-character vs media_inventory, closest-match hint on
  rewrite), context prompt rules (self-contained in all modes, keep-then-change
  opener for joins, end-in-motion tail when another join follows), drift all-or-
  nothing + consecutive 10s split unless lengths_user_pinned. Subcommands: outline/
  segment/trackdata/plan/suite; no-outline runs stay schema-only. Embedded suite
  25 cases, prints ~0.7 KB (far under Cline's 8k cap).
- build_track_plan.py: merge re-walks every fragment against the guide, assembles
  TRACK_DATA (task track from fragments; locked master-audio/reference-video tracks
  built from the outline, never retyped), writes plan.json + track_data.json with
  stable UUIDv5 ids; --check mode re-validates.
- examples/: worked 3-segment rooftop example (outline, 3 fragments, plan.json,
  track_data.json) - merge is byte-deterministic and the generated plan dry-run-
  applies to the bundled v1.3.0 blank template with graph_preserved: true.
- SKILL.md: five-move procedure with Cline cap workarounds (never read the 66 KB
  validator, @@CONTINUE@@ split, never read back generated plans), Step 0 media
  paths (upload only on explicit request; never invent a path), approval pause,
  prompt craft rules, delivery through the node pack's own patch_workflow.py
  (dry-run -> --write to a NEW file -> inspect); queueing stays the node pack's
  own flow on explicit user request.
2026-11-01 01:09:26 +00:00

82 lines
5.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Easy-Media Track Gate
A portable, self-contained agent skill that turns a video idea into a **validated MultiTrack
patch plan** for the ComfyUI-Easy-Media nodes (`easy multiTrackEditor` +
`easy multitrackProject`), built with the same outline → approval → one-segment-per-turn →
merge → gate flow as `h3-plan-gate`, adapted to the Easy-Media multitrack schema.
The deliverable is a `plan.json` patch plan that the node pack's own
`skills/easy-media-multitrack-workflow/scripts/patch_workflow.py apply` consumes — it is
not pasted into a widget.
## What the gate enforces
| Layer | Check |
| --- | --- |
| Schema | Mirrors every check of the node pack's `patch_workflow.py` at apply time: track/segment ids, sorting, overlap, frame ranges, media `source_type`↔field matching, ≤ 9 images per task, continuity enum, one locked audio + one locked video max, locked-media coverage of task ranges, shared-reference rules, DynamicCombo resolution tokens, project fields — so a plan that passes here cannot be rejected there for schema reasons |
| Outline pins | Each segment's id, start/end frames (`round(seconds × fps)`), `task_mode`, `continuity_mode` and reference-image set are diffed against the approved guide at the segment turn AND again at the merge |
| Verbatim media contract | Every `file_path` in fragments and locked tracks must be a character-for-character copy of the outline's `media_inventory` entry (the same discipline `h3-plan-gate` applies to refmods; a retyped path fails with a closest-match hint) |
| Context prompt rules | Self-contained prompts in every mode (no "same as before"); context/context_drift joins must open by keeping the delivered tail and must not open with a new composition; a join followed by another join must not end at rest |
| Drift discipline | `context_drift` is all-or-nothing across the task range (first segment included), with the consecutive 10-second split unless the user pinned lengths |
## Folder
```text
easy-media-track-gate/
├── SKILL.md agent procedure (the entry point)
├── README.md this file
├── verify_track_rules.py the gate: outline / segment / trackdata / plan / suite
├── build_track_plan.py merge fragments → TRACK_DATA + patch plan.json
├── references/
│ └── track-schema.md English translation of the node pack's Chinese
│ multitrack-schema.md (all field names preserved)
└── examples/ worked 3-segment example: outline, segments, plan, track_data
```
Standard library only; Windows-first (`py -3`), runs anywhere Python 3.8+ lives.
## Install (portable skills folder)
Copy the whole folder next to your other skills:
```text
%USERPROFILE%\.agent\skills\easy-media-track-gate\
```
`SKILL.md` must sit directly in that folder (not nested one level deeper). Start a fresh
agent task after installing so the skill list refreshes. The node pack's own
`easy-media-multitrack-workflow` skill stays installed independently — this gate produces
its plan input and defers execution to it.
## Quick start
```sh
:: smoke test
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py"
:: validate a guide / one segment / the merged plan
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py" outline outline.json
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py" segment segment_01.json --index 1 --outline outline.json
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py" segment segment_02.json --index 2 --prev segment_01.json --outline outline.json
:: merge everything (writes plan.json + track_data.json)
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\build_track_plan.py" outline.json segment_01.json segment_02.json segment_03.json -o plan.json
:: apply with the node pack's own script (dry-run, then write)
py -3 <ComfyUI>\custom_nodes\ComfyUI-Easy-Media\skills\easy-media-multitrack-workflow\scripts\patch_workflow.py apply WORKFLOW.json --plan plan.json
py -3 <ComfyUI>\custom_nodes\ComfyUI-Easy-Media\skills\easy-media-multitrack-workflow\scripts\patch_workflow.py apply WORKFLOW.json --plan plan.json --output RESULT.json --write
```
## Provenance notes
- The schema reference is a faithful English translation of
`ComfyUI-Easy-Media/skills/easy-media-multitrack-workflow/references/multitrack-schema.md`
(which is written in Chinese); field names, enums and limits were additionally
cross-checked against the node pack's `patch_workflow.py` source, and the generated
example plan was dry-run-applied to the bundled v1.3.0 blank template successfully.
- Upstream leaves prompt quality, outline discipline and id/timing pins to discipline;
this gate makes them machine-checked. Everything upstream checks mechanically is
checked here with the same rules.
- Upload (`/upload/image`) and queue (`submit_workflow.py`) remain the node pack's own
flows and are only used on the user's explicit request.