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

448 lines
30 KiB
Markdown
Executable File
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.

---
name: easy-media-track-gate
description: Turn a video idea into a validated MultiTrack plan for ComfyUI-Easy-Media
(the `easy multiTrackEditor` node). Use when the user wants to plan task segments/shots
on the multitrack timeline, write or extend a MultiTrack timeline, arrange prompts,
reference images, master audio or reference-video locks, regenerate one task segment,
or produce the `prompt_override` paste for the multitrack editor node — plain text
`scene1|scene2|...` by default — plus the optional patch plan JSON that
`patch_workflow.py apply` consumes. The scripts and
references live next to this SKILL.md (the skill's install folder); run them from the
user's working folder, where all generated files are written.
---
# Easy-Media Track Gate — agent procedure
Goal: produce the `prompt_override` paste for the `easy multiTrackEditor` node in five
moves: the user gives a video idea and a segment count (or an existing workflow to edit) →
you build a timeline guide (`outline.json` — the ONLY JSON the default flow ever writes)
and show it for **approval** → with the approved guide you compose the task segments one
at a time (about 10 seconds each) as PLAIN TEXT files (`segment_01.txt`, …): each file is
ONE scene's complete prompt plus a one-line `# handoff:` note — no ids, no frames, no
media paths, no JSON, because the approved outline row supplies all of that → the scripts
verify timing, continuity and prompt craft across the whole chain →
`build_track_plan.py` merges the fragments and writes the deliverable. The deliverable is
`prompt_override.txt` — PLAIN TEXT, the scene prompts joined with `|` on one line (the
editor splits on pipes; no JSON), which the user pastes into the multitrack editor node's
`prompt_override` input (format `MiniMax`) — the editor then renders one clip per scene,
chained back-to-back. The merge adds `[start-end]` / `[start-end,type]` markers per scene
when the story needs them (unequal lengths, or a scene that is not the plain-text default
t2v — e.g. r2v). `prompt_override.json` (a `minimax_prompt_override` payload) exists only
for what plain text cannot carry: `<Picture N>`/`<Audio N>`/`<Video N>` media tokens
(stories with media — the merge writes it automatically then), per-segment continuity
modes or track locks (`--json`). The patch plan (`plan.json` via `--plan` for the node
pack's `patch_workflow.py`) is the optional whole-workflow alternative. Never deliver a
paste that did not pass validation, and never compose a segment from a guide the user has
not approved. Never hand the user any other JSON as the paste: a non-
`minimax_prompt_override` value in `prompt_override` falls back to the editor's
`|`-separated text parser and renders the whole story as ONE clip over the entire
timeline — and never put `|` inside a scene prompt for the same reason.
## Paths and Python (read first — these exact forms prevent most errors)
- **SKILL_DIR** is the folder this SKILL.md was loaded from — the skill's install folder
(default on Windows: `%userprofile%\.agent\skills\easy-media-track-gate`; macOS/Linux:
`~/.agent/skills/easy-media-track-gate`). The scripts, the schema reference and the worked
example all live in SKILL_DIR, not in the working folder. Every command below uses the
Windows default install path; substitute your real SKILL_DIR if it differs.
- Work in the user's **working folder** (the folder open in the editor). Write generated
files there: `outline.json`, `segment_01.txt`, `segment_02.txt`, …, and the merge's
`prompt_override.txt` — that is the whole default set. `prompt_override.json` appears
for stories with media (or with `--json`), `plan.json`/`track_data.json` only with
`--plan`. Never write generated files into SKILL_DIR.
- Python command: Windows `py -3` (or `python`); macOS/Linux `python3`. If the working
folder has a `.venv`, its interpreter works too (`.venv\Scripts\python.exe`). The scripts
need only the Python standard library — nothing to install.
- Start every task by running the smoke test under "Before you start". If it fails because
SKILL_DIR is missing files, stop and tell the user the skill folder is incomplete.
- **Never read `verify_track_rules.py`** — run it and work from its printed output. Cline's
read_file is capped by hard-coded budgets that do NOT grow with the model's context
window: about 48,000 characters per read, 2,000 lines per read. The ~110 KB validator
arrives cut no matter how large the context window is. A truncation notice is Cline's
read cap, not repo corruption — do not "fix" truncated files. `build_track_plan.py`
(~15 KB) and `references/track-schema.md` (~26 KB) are safe to read whole.
- **Never read back `prompt_override.txt`, `prompt_override.json`, `plan.json` or
`track_data.json` once real segments exist** — a 10-segment plan passes the read caps
today and exceeds them tomorrow. Validate with the `segment` / `override` commands (the
`override` command takes BOTH the `.txt` paste and the `.json` payload) and trust the
one-line OK summary; the shipped `examples/segment_01.txt`–`segment_03.txt` (the worked
plain-text fragments), `examples/outline_sam_park.json` (their guide),
`examples/prompt_override_r2v_refmod.txt` (the paste those fragments merge into),
`examples/prompt_override.json` (2.5 KB) and `examples/plan.json` (6.8 KB) are safe to
read if you need to see a shape.
- Cline's editor rejects writes over 6,000 characters ("Editor input too large"). A segment
fragment with a rich prompt often does. NEVER write part 2 with write_to_file — it
replaces the whole file and part 1 is lost. Split instead: write the first part ending
with the bare marker line `@@CONTINUE@@`, then replace_in_file with SEARCH `@@CONTINUE@@`
and REPLACE the remaining content. The finished file must not contain the marker.
- Cline also cuts command output at 8,000 characters. The embedded suite prints well under
1 KB when it passes; a failing validation prints one actionable line. If output ever
arrives truncated, re-run the single-file command (`segment`, `outline`, `plan`) — its
output is tiny.
## Before you start (smoke test)
```sh
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py"
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\build_track_plan.py" --check "%USERPROFILE%\.agent\skills\easy-media-track-gate\examples\plan.json"
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py" segment "%USERPROFILE%\.agent\skills\easy-media-track-gate\examples\segment_02.txt" --index 2 --outline "%USERPROFILE%\.agent\skills\easy-media-track-gate\examples\outline_sam_park.json" --prev "%USERPROFILE%\.agent\skills\easy-media-track-gate\examples\segment_01.txt"
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py" override "%USERPROFILE%\.agent\skills\easy-media-track-gate\examples\prompt_override_r2v_refmod.txt" --outline "%USERPROFILE%\.agent\skills\easy-media-track-gate\examples\outline_sam_park.json"
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py" override "%USERPROFILE%\.agent\skills\easy-media-track-gate\examples\prompt_override.json" --outline "%USERPROFILE%\.agent\skills\easy-media-track-gate\examples\outline.json"
```
Expect the suite to print `SUITE PASS (57/57 cases)`, the `--check` to print `PLAN OK`
with `total_length 720 frames = 30.00s`, the `segment` check to print `SEGMENT 2/3 OK
(plain-text fragment): butterfly_chase_miss frames [240, 480)`, the first `override` to
print `OVERRIDE OK (plain text): 3 scenes split on '|' with [start-end,type] markers,
total 30.00s at 24 fps` and the second `OVERRIDE OK (JSON payload): 3 prompts, duration
10 (default), total 30.00s`.
## Step 0 — Media paths come first (never invent one)
Every `file_path` in the plan must be a real path on the user's ComfyUI instance. Before
writing the outline, establish the media inventory one of two ways:
- The user names the exact input paths (they know their `input/` subfolders). Use their
strings verbatim — they become the pinned inventory.
- The user explicitly asks you to upload → upload first and record the returned relative
path (`subfolder/name`, `source_type: "input"`) for every file. Upload uses the node
pack's own API (`POST /upload/image` with a `subfolder` like `codex/<project>`); never
write a local absolute path into the plan.
- If there is no real path and no upload request, stop and ask. A plan is still deliverable
with obviously-fake placeholder paths only if you say plainly it cannot run until real
media replaces them — never dress a placeholder up as a real path.
Upload and execution are external state changes: only upload/queue when the user explicitly
asked (Step 5).
## Step 1 — Build the timeline guide (outline)
Read SKILL_DIR's `references/track-schema.md` once (safe whole-file read; it is the English
translation of the node pack's Chinese schema doc). Then write `outline.json` — the guide
for the whole timeline, and the only JSON the default flow ever writes — in exactly this
shape (the shipped `examples/outline.json` is the worked model). Everything downstream is
derived from it: frames, task types, continuity modes, images and ids all come from the
approved rows, so the outline is also the single place media paths and resolution tokens
are ever typed.
```json
{
"title": "short_snake_case_name",
"lengths_user_pinned": false,
"editor": {
"format": "MiniMax",
"resolution": { "resolution": "width x height (megapixels)",
"aspect_ratio": "16:9 (Widescreen)", "megapixels": 0.8 }
},
"defaults": { "frame_rate": 24, "segment_seconds": 10 },
"media_inventory": [
{ "key": "SONG", "kind": "audio", "source_type": "input",
"file_path": "codex/rooftop/song.wav", "file_name": "song.wav" },
{ "key": "POSE_REF", "kind": "image", "source_type": "input",
"file_path": "codex/rooftop/pose_ref.png", "file_name": "pose_ref.png" }
],
"tracks": {
"master_audio": { "key": "SONG", "lock": true, "name": "Master Song", "role": "why it drives the timeline" },
"reference_video": null
},
"project": { "project_save": "override", "segment_start_number": 1,
"segment_count": -1, "sampling_plan": "medium", "sampling_mode": "single" },
"segments": [
{ "index": 1, "id": "seg_one_open", "start_seconds": 0, "duration_seconds": 10,
"task_mode": "ref", "continuity_mode": "shot",
"images": [ { "key": "POSE_REF", "shared_reference": false } ],
"beat": "one sentence: what happens AND where the segment ends",
"prompt_brief": "1-2 sentences: what the prompt keeps first, changes later, ends on" }
]
}
```
Field rules the validator enforces:
- `media_inventory` keys are UPPERCASE; every `file_path` is copied from Step 0 sources —
this inventory is the **machine-checked verbatim source**: every segment's image items and
every locked media track are diffed against it, so a retyped path fails on the spot. A
paraphrase in the inventory cannot be repaired later. Order matters too: the inventory's
image rows map to the editor's `image` input positions (`<Picture 1>`, `<Picture 2>`, …),
audio rows to `audio` input positions, video rows to `video` input positions — the user
wires the media into those node inputs in inventory order.
- `tracks.master_audio` / `tracks.reference_video` name the ONE locked audio and ONE locked
video track (the schema allows at most one of each). Lock the master song for MV/lyric/
dance/beat projects, the narration track when narration drives the cut, and the reference
video when the user supplies one for subject/partial replacement. Ordinary BGM/SFX/ambience
is never locked. If two candidates could be the master, stop and ask the user — never pick
by track order or duration.
- Resolution: copy the user's intent into the exact DynamicCombo tokens — `16:9` means
`16:9 (Widescreen)`, `0.9mp` means megapixels mode with the number taken verbatim; never
convert MP into width/height. Keep the current workflow resolution when the user expressed
no intent (then omit nothing — still write the block the user approved).
- Segments: `start_seconds` are cumulative (previous start + duration + gap); ids are unique
lowercase snake_case, never renamed later; `duration_seconds` about 10 unless the user
says otherwise; only the last segment may come to rest. `continuity_mode` per segment:
`shot` (standalone/new composition), `context` (continues the previous segment's real
delivered tail), `context_drift` (context + subject/partial replacement from the locked
reference video). **context_drift is all-or-nothing**: if any segment drifts, all do,
first included; without user-pinned lengths the drift split is consecutive 10-second
pieces (last takes the remainder) — set `lengths_user_pinned: true` only when the user
actually specified the lengths.
- `images` per segment: at most 9, each an inventory image key with its `shared_reference`
flag. Reference images define IDENTITY, not composition. When several context segments
reuse one image, prefer explicit private items (`shared_reference: false`, fixed ids,
same file) over shared-image metadata — the current front-end regenerates UUIDs for
sparse shared images, and unverified shared data risks unstable loads.
- `project`: `project_save: "override"` with `segment_count: -1` deletes saved segments
after the start index on execution — warn the user before choosing it. `upscale_by` is
only written when the user asked (default 1.250, three decimals); the editor resolution
is the first-pass size, and dual-sampling second pass = `round(editor_size * upscale_by /
32) * 32`.
## Step 2 — Present the guide for approval (do not skip)
Show the user the finished guide in plain language — one line per segment: number, id,
seconds, continuity mode, what happens and where it ends — plus the media inventory, the
locked tracks, the resolution block and the project parameters. Then STOP and wait for
their reply. The user approves it or asks for changes; apply every change to `outline.json`
and, if anything changed, show the changed rows again. Start Step 3 only after an explicit
approval. The approved guide is the contract: segments are composed from it, ids, frames
and modes are never silently altered, and new story ideas from the user go through the
guide first — never straight into a segment file.
## Step 3 — Compose the segments one at a time (plain text)
Work only from the approved guide. In story order: compose ONE segment file, validate it,
fix it until it passes, and only then move to the next. Since you wrote the previous file
yourself, open it and reuse its `# handoff:` line as the opening state of the next context
join. Rewrite a segment as many times as it takes. If Cline rejects a write with
'Editor input too large', split it with the marker pattern from the rules above.
**A segment file is plain text** (`segment_01.txt`, `segment_02.txt`, …): the scene's
complete prompt, written exactly as it will sit inside the paste — multi-line section
structure (`subject_definitions:`, `[Shot 1]`, sound cues) survives into the clip — and
ONE trailing `# handoff:` line naming the real final frame. No id, no frame numbers, no
task mode, no media paths, no JSON: the approved outline row supplies all of that when
the scripts load the file, so none of it can be mistyped. The `# handoff:` line is the
contract the next segment's join opens inside — pose, motion in progress, camera state
(15+ words); it is stripped before anything reaches the model.
```text
subject_definitions:
<Subject 1> identity: Sam is a 9 year old boy with his blonde hair in pigtails …
summary:
[reference generation]
detailed_description:
[Shot 1] …the full scene prompt, multi-line, ending in motion…
overall_soundscape:
…
# handoff: Sam stands tipped onto his toes at the path's edge, both hands still reaching,
# fingers an inch short of the hovering butterfly's orange wings, the camera holding low…
```
(The shipped `examples/segment_01.txt`–`segment_03.txt` are the worked model — the same
story the example paste merges from, byte-identical.)
**What the plain-text form forbids** (the validator fails the file on the spot): no `|`
(it would split the scene in the paste), no `[start-end]` markers (the merge appends
them itself), no `@` (the editor strips it), and no `<Picture N>`/`<Audio N>`/`<Video N>`
tokens on a zero-media story (JSON-only). On a story with media the tokens are allowed
and diff-checked against the row's approved images. **Media copy rule, reduced to one
sentence:** media paths are typed ONLY in `outline.json`'s `media_inventory` — segment
files cannot carry them at all.
**JSON fragment escape hatch:** only when a segment needs `user_prompt_variant: "b"` or a
custom `system_prompt` (both rare, both user-requested) write that ONE segment as JSON —
`{"id": row id, "start_frame": row start, "end_frame": row end, "content": {"task_mode":
…, "continuity_mode": …, "images": […], "user_prompt": …}, "_handoff": {"end_state":
…}}` (full shape in `references/track-schema.md`). Frames and ids still come from the
row, and the merge takes `.txt` and `.json` fragments in any mix.
```sh
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
```
(`--total` is optional with `--outline`; `--prev` chains the previous file and enforces
consecutive frames `[0,240), [240,480), …` — never an extra frame at a boundary. `.txt`
and `.json` fragments both work in every position.)
### Prompt craft rules (violations fail the validator)
- Every task segment renders standalone — the model never sees any other segment's prompt.
Fully restate scene, light and subject identity inside each prompt; never say "the same
one", "as before", "the previous shot". This ban is checked in every mode.
- Reference images define identity only: they are not the first frame or a composition
anchor; context joins never use image anchoring or `[video continuation]`.
- **context segments open by keeping the delivered tail** — the join starts from the
previous segment's real last frames (about 0.92 s earlier than the saved boundary at
24 fps), whose framing can differ from what the previous prompt imagined: open with the
camera keeping its direction and the subject keeping pose, motion and light. Give the
hold an action (a breath, a weight shift) so it does not render as a freeze-frame.
- **Keep first, change later**: before about `00:02.000` no cut, no new key action; a
required composition change is written as an explicit cut later in the prompt. For a
genuinely new composition use a `shot` segment instead of `context`.
- **End in motion**: a context segment followed by another context segment never ends at
rest — no "comes to a stop", "settles", "holds still", "falls asleep" in the closing
lines. Only the timeline's final segment may come to rest.
- Compose, never summarize: subject anchor with its look, blocking, one camera idea,
performance beats, physical texture (wardrobe behavior, weather on skin and fabric,
light), and a concrete mid-action exit state. Decompose every action into ordered
body mechanics ("bends his knees, grips the handle with his left hand, then stands"),
naming the limb; camera, light and weather each get their own ordered visible stages.
The validator trips a thin-prompt floor (60 words) — never pad to a band, and never
hand in a one-liner.
- `system_prompt` stays `""` unless the user asked for one: an empty system prompt lets the
node auto-append the MiniMax reference rules for context joins; a custom one disables
that (and needs the one-segment JSON escape hatch above).
- The `# handoff:` line must be truthful — it is the contract the next join opens inside.
## Step 4 — Verify the chain, merge to the paste
Once every segment file passes, the merge is the continuity check: `build_track_plan.py`
re-walks every fragment against the guide (ids, frames, modes, verbatim media paths, prompt
rules, handoff chain — all pinned by the outline rows), builds the paste from the same
validated fragments, and writes ONE file by default. Never write the paste by hand and
never edit fragment prose during the merge.
```sh
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\build_track_plan.py" outline.json segment_01.txt segment_02.txt segment_03.txt
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py" override prompt_override.txt --outline outline.json
```
Zero-media stories get `prompt_override.txt` (the plain-text paste — THE deliverable);
stories with media get `prompt_override.json` instead (the only form that carries
`<Picture N>`/`<Audio N>`/`<Video N>` tokens). Two opt-ins: `--json` also writes the
payload for a zero-media story that needs per-segment continuity modes or track locks,
and `--plan plan.json` also writes the patch plan (plus `track_data.json` for inspection)
for the whole-workflow patch path (Step 5B). Segment, track and image ids are stable
UUIDv5 values derived from the project title, so a re-merge keeps ids consistent. The
`override` command re-checks the paste against the guide: one scene per segment in order;
plain text — `[start-end]`/`[start-end,type]` markers equal to the approved row frames and
task types (or, without markers, equal row lengths), @imageN/@audioN/@videoN refs matching
the inventory, no `<Picture N>` (JSON-only), no stray `@`, no `[number-number]` prose (the
parser eats it as a frame range); JSON — durations inside the runtime's 2–15s window and
equal to the approved rows, per-segment generation/continuity modes, the exact
`<Picture N>` / `<Audio N>` / `<Video N>` reference set per prompt (a missing token
renders with no reference media; a stray one attaches the wrong image), and the track
locks.
## Step 5 — Deliver (plain-text paste first, patch script as the alternative)
### 5A — Default: the plain-text `prompt_override` paste
**The paste is plain text — `scene1|scene2|...` — unless the story needs the JSON option
below.** Deliver `prompt_override.txt` (the merge's default output): the scene
prompts joined with `|` on ONE line, one scene per pipe-chunk. The editor splits on pipes
with no JSON at all: one clip per scene, back-to-back; a trailing `|` is a no-op. Newlines
INSIDE a scene survive — multi-section prompt structure is fine — but `|` inside a scene
would split it. For unequal scene lengths or a scene that is not the plain-text default
t2v (e.g. r2v), the merge ends each scene with a `[start-end]` / `[start-end,type]`
marker (`[0-240,r2v]|[240-480,r2v]|[480-720,r2v]` — the marker sits at the scene END,
sets the frame range and task TYPE, and is stripped from the text before it reaches the
model; the worked example `examples/prompt_override_r2v_refmod.txt` shows the full
multi-section r2v form). A story with media needs the JSON option: `<Picture N>` tokens
are NOT parsed in this path — they would stay literal text (the text path attaches media
via `@imageN`/`@audioN`/`@videoN` only).
Deliver `prompt_override.txt` with these instructions:
1. In the editor node set `format` to `MiniMax`.
2. Zero-media story: wire nothing — the editor demands no media inputs. (A story with
media cannot go through this path — see the JSON option.)
3. Select the `prompt_override` widget, clear it, paste the one-line plain text. The
editor rebuilds the task track: one clip per pipe-chunk, back-to-back, frame ranges
and task types as marked (or even splits of the editor's `total_length` when no
markers are present — keep that length equal to the story total).
4. **Rendering walks the timeline through `easy multiTrackTaskOutput` — and that node
outputs ONE task segment per pass, selected by its `task_index` int input (default 0 =
only the FIRST clip).** A workflow whose `task_index` stays 0 renders only the first
scene no matter how many scenes the paste carries. Two ways to render all clips:
- **Loop workflow (proper multi-shot):** use the node pack's
`example_workflows/MinimaxH3_ForLoop_MultiShot.json`. Its `forLoopStart` takes
`total` from `easy multiTrackInfoOutput.TASK_COUNT` (via a math node that also lets a
PrimitiveInt pick one segment: -1 = all), and its index feeds
`multiTrackTaskOutput.task_index`; each iteration generates one clip, batches it, and
`mergeVideosFromPaths` concatenates everything after the loop. Paste the override
into THAT editor and set the PrimitiveInt to -1.
- **Manual fallback (no rewiring):** set `task_index` to 0, queue; then 1, queue; then
2, queue. Three clip files, join them afterwards. (`task_index = -1` outputs the whole
timeline's pre-rendered MEDIA — it is not a 3-clip generation.)
5. **Optional LLM polish slot** (only if the user asks for it): inside the loop,
`TaskOutput.SYSTEM_PROMPT/USER_PROMPT` may feed an LLM node whose output replaces the
prompt at the render node, with an ifElse bypass back to raw `USER_PROMPT`. The skill's
prompts are already final — leave the bypass OFF unless requested. Ways to fill the
slot: any ComfyUI LLM node (system+user in, string out), or the pack's
`easy multiTrackPromptEnhancer` with model `openai_compatible (local)` pointed at the
user's own endpoint (`base_url` accepts any OpenAI-compatible server: Ollama, LM
Studio, vLLM, llama.cpp server). Full wiring: `references/workflow_wiring.md`.
**JSON option (`prompt_override.json`) — only for what plain text cannot carry:**
`<Picture N>`/`<Audio N>`/`<Video N>` media tokens (stories with images/song/reference
video — the merge writes this payload automatically for them), per-segment continuity
modes or track locks on a zero-media story (re-run the merge with `--json`). The payload
is minimal by design — the parser requires only `type` and `prompts`; optional keys
appear only when non-default (duration is SECONDS, `generation_type` defaults to `r2v` in
the pack's code) — and is self-contained: one prompt per clip, media reference tokens
inside the prompts, no frame fields anywhere. The paste steps are the same three as above
(format MiniMax; wire the inventory's image rows into the editor's `image` input in
inventory order, the master song into `audio`, the reference video into `video` — the
`<Picture N>`/`<Audio N>`/`<Video N>` tokens resolve against those input lists
positionally; clear the widget and paste the one-line JSON), and the same
`task_index`/loop wiring applies afterwards.
**The paste target is the `prompt_override` input and only these two forms.** Never give
the user a `plan.json`, an outline, an H3 plan or any other JSON to paste there: without
`"type": "minimax_prompt_override"` the editor falls back to its `|`-separated text parser
and renders the whole thing as ONE clip spanning the timeline (the single-clip failure).
Never add `|` inside a scene for the same reason.
### 5B — Alternative: the node pack's patch script (whole-workflow patch)
When the user wants the timeline written into a workflow file directly (or needs `edit`
task modes / extra tracks the paste payload cannot express), first produce the patch plan
by re-running the merge with `--plan plan.json` (it also writes `track_data.json` for
inspection), then apply it with the Easy-Media node pack's script — find it under the
node pack folder (typically
`<ComfyUI>\custom_nodes\ComfyUI-Easy-Media\skills\easy-media-multitrack-workflow\scripts\patch_workflow.py`;
ask the user for the path and the workflow JSON if they are not at hand):
```sh
py -3 <node-pack>\skills\easy-media-multitrack-workflow\scripts\patch_workflow.py apply WORKFLOW.json --plan plan.json
py -3 <node-pack>\skills\easy-media-multitrack-workflow\scripts\patch_workflow.py apply WORKFLOW.json --plan plan.json --output RESULT.json --write
py -3 <node-pack>\skills\easy-media-multitrack-workflow\scripts\patch_workflow.py inspect RESULT.json
```
Always dry-run first; only write to a NEW output file (`--output RESULT.json --write`),
never over the user's source workflow. `inspect` must show the editor's resolution, format,
frame rate, `total_length`, the task track with all segments and the locked tracks with
their media. Report: base workflow path, output file, editor/project node ids, resolution,
timeline summary, media paths, continuity modes, locked tracks and whether the node graph
stayed untouched (`graph_preserved: true`).
Actually opening the workflow in ComfyUI or queueing it (`submit_workflow.py`, UI-tab
submission) is a separate authorization — only on the user's explicit request, and it is
the node pack's own flow (see its `references/execution-api.md`). "Queued" never means
"generated"; wait for the real completion status before reporting success.
## Revising after approval
- Guide-level change (timings, beats, modes, segment count, media): update `outline.json`
first, show the changed rows, then rewrite only the affected segment files against it
and re-run the Step 4 merge so the paste refreshes (plus the `--json`/`--plan` outputs
when they were requested).
- One segment reads badly: rewrite that `segment_NN.txt` (the outline row still pins its
id and frames), re-validate it with the `segment` command, then re-merge. Never patch
`prompt_override.txt`, `prompt_override.json` or `plan.json` directly — the merge
rebuilds the paste from the fragments every time.
## If you cannot run Python
Say plainly that the result skipped script validation. Follow the rules manually: copy the
`examples/` shapes exactly, compute frames as `round(seconds * frame_rate)`, copy every
`file_path` and resolution token by selection (never retyping), and hand-assemble the
paste the way Step 4 describes. Hand-write the paste as plain text — scene prompts
joined with `|` on one line, one `[start-end(,type)]` marker at each scene end when
lengths differ or the scene is not t2v, exactly like
`examples/prompt_override_r2v_refmod.txt` — and use the JSON payload only when the story
needs `<Picture N>` tokens, continuity modes or locks. Manual assembly is error-prone —
prefer getting Python running (any of `py -3`, `python`, a `.venv`) over hand-building
the paste.