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

101 lines
7.1 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
`prompt_override` paste** for the ComfyUI-Easy-Media nodes (`easy multiTrackEditor`),
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 **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. The segment files the agent writes on the way there are
plain text too (`segment_NN.txt`: the scene prompt verbatim + one `# handoff:` line; the
approved outline row supplies id, frames, modes and images). JSON appears only where plain
text cannot reach: `prompt_override.json` (a `minimax_prompt_override` payload — written
automatically for stories with media, or with `--json` for continuity modes / track
locks) and `plan.json` (`--plan`, 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 come FROM the approved guide row when a plain-text fragment is loaded — nothing is retyped, so they cannot drift; JSON fragments are diffed against the row at the segment turn AND again at the merge |
| Verbatim media contract | Media paths are typed only in the outline's `media_inventory`: plain-text fragments cannot carry paths at all, and locked tracks are built straight from the outline (a retyped JSON-fragment 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) |
| Fragment hygiene | Plain-text segment files reject `|` (would split the paste), hand-written `[start-end]` markers (the merge appends them), `@` (the editor strips it) and, on zero-media stories, `<Picture N>` tokens (JSON-only); the `# handoff:` line must describe the real final frame (15+ words) |
## 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 → the paste (prompt_override.txt, or .json for
│ media stories); --plan adds plan.json + track_data.json
├── references/
│ └── track-schema.md English translation of the node pack's Chinese
│ multitrack-schema.md (all field names preserved)
└── examples/ worked 3-segment r2v example: outline_sam_park.json, the
plain-text segment_01–03.txt fragments, and the paste they
merge into (prompt_override_r2v_refmod.txt); plus a media-story
guide (outline.json), its JSON payload (prompt_override.json)
and the patch-plan shape (plan.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 plain-text segment
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.txt --index 1 --outline outline.json
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py" segment segment_02.txt --index 2 --prev segment_01.txt --outline outline.json
:: merge to the deliverable (writes ONLY the paste: prompt_override.txt for zero-media
:: stories, prompt_override.json when the story has media; --json / --plan add the rest)
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\build_track_plan.py" outline.json segment_01.txt segment_02.txt segment_03.txt
:: validate the paste
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py" override prompt_override.txt --outline outline.json
:: optional: patch plan for the node pack's own script (dry-run, then write)
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\build_track_plan.py" outline.json segment_01.txt segment_02.txt segment_03.txt --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.