mmprompt/easy-media-track-gate/README.md

95 lines
6.4 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 PRIMARY deliverable is a **plain-text `prompt_override` paste** (`prompt_override.txt`:
the scene prompts joined with `|` on one line, `[start-end(,type)]` markers where scene
lengths differ or a scene is not t2v) for the `easy multiTrackEditor` node's
`prompt_override` input (format `MiniMax`) — the editor splits on pipes and renders one
clip per scene, no JSON needed. `prompt_override.json` (a `minimax_prompt_override`
payload) is the option for what plain text cannot carry (`<Picture N>` media tokens,
continuity modes, track locks), and `plan.json` is the whole-workflow alternative applied
by the node pack's own `skills/easy-media-multitrack-workflow/scripts/patch_workflow.py
apply`.
## 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 |
| Paste payload | `prompt_override` re-checked against the guide in BOTH forms: plain text (scene count/order, `[s-e,type]` markers vs the approved row frames and task types, `@imageN/@audioN/@videoN` refs vs the inventory, `<Picture N>` and stray `@` rejected) and JSON payload (durations, generation/continuity modes, exact `<Picture N>` sets, track locks) |
## 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 / override / suite
├── build_track_plan.py merge fragments → prompt_override.txt/.json + 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,
paste payloads (prompt_override.json + the plain-text
prompt_override_r2v_refmod.txt with its outline_sam_park.json)
```
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 prompt_override.txt + prompt_override.json + 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
:: validate the paste payloads (plain text is the default form; JSON the option)
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py" override prompt_override.txt --outline outline.json
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py" override prompt_override.json --outline outline.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.