OA Workflow Metadata
The note that tells Ordinary Animator what your workflow is -- how to add one, every field you can put in it, and what goes wrong when one is missing.
Ordinary Animator never runs your workflow to find out what it is. It reads a note you leave inside the workflow, and everything the product knows about that workflow -- its name, what it produces, which menu it appears in -- comes from there.
That note is a plain ComfyUI Note node with the title OA Workflow Metadata. Inside it you
write one setting per line, in the form field: value. A workflow without that note is imported but
cannot be used: it has no menu to join and nothing that says what it makes.
Most of what goes in the note is optional, because most of it can be worked out from the workflow
itself -- the models it loads, and from those, a name. What it cannot work out is what job the
workflow does, so that one line, operation, is the one you always write.
Adding the note to a workflow that does not have one
This is the most common thing wrong with a workflow you built yourself or downloaded from somewhere else. It takes about a minute.
-
Open the workflow in ComfyUI.
-
Right-click on an empty part of the canvas and add a Note node. Any empty space will do -- the note is never connected to anything, and where it sits makes no difference.
-
Rename the node's title to exactly
OA Workflow Metadata. In ComfyUI you rename a node by double-clicking its title bar. The spelling and the capitals matter; this title is how the platform finds the note. -
Click into the note's text area and type the workflow's details, one per line:
description: Relights a portrait from a reference image. Keeps the pose and the face. output_tags: image operation: image_to_image -
Save the workflow in ComfyUI, then import it into your project again from the Workflows view. The re-import is what picks up the change -- editing the file does not update the copy your project already holds.
A note that exists but is empty is the same as no note at all, so do not leave the placeholder text ComfyUI puts in a new note behind.
The fields
Only the fields below are understood. A field the platform does not recognise is treated as a malformed note, and a workflow with a malformed note is dropped from every menu with no error -- so a typo in a field name is worse than leaving the field out. Check the spelling against this list before you save.
Everything here is optional except operation, description and output_tags, which every
workflow needs. name used to be required and is not any more -- leave it out and Ordinary
Animator writes the name for you, out of the operation and the model. You still have to write one
when a name cannot be made, which is when the operation is custom, when no model is either
declared or worked out from the files, or when nobody can say which build of the model it runs. See
How to name it.
A value that contains a colon has to be quoted
The colon is what separates a field name from its value, so a second colon followed by a space inside the value ends the note early. Put quotes around the whole value and it is read exactly as you typed it:
description: "Put the dialogue under an Audio: heading."
Quote it even though the note may look fine without the quotes. The fields above the offending line keep working, so the workflow shows the right name and description and nothing appears to be wrong, while the note as a whole is no longer something the platform can read with confidence -- and it has to read this note every time the workflow is run, to record which gallery the result belongs to. When that is what has gone wrong, the message you get says so and names the line to fix.
A colon with no space after it -- a time like 10:30, or an address like http://example.com --
is fine unquoted. It is only : that ends the value.
Name, description and output tags
| Field | Required | What it is |
|---|---|---|
name |
Only when one cannot be made for you | The name shown wherever this workflow appears -- menus, the Recipe panel, the Workflows view. Leave it out and one is written for you from the operation and the model, unless the operation is custom, no model is declared or detected, or the model's build is not known. Write your own when the generated one is not the name you want people to read. See How to name it below. |
description |
Yes | A sentence or two saying what the workflow does. It is shown when someone is choosing between workflows, so say what makes this one different. For a video workflow, say how long a clip it produces in seconds -- seconds are the only unit that reaches the person choosing. |
output_tags |
Yes | What the workflow produces, so the result is filed correctly: image, video or audio. Separate several with commas. |
Leave output_tags out and the platform does not know what kind of thing it makes, so the result may
not be filed where you expect.
How to name it
The name is written for you. It is the operation, then the model in brackets:
operation: upscale
models:
- model: Clear Reality V1
shows up everywhere as Upscale (Clear Reality V1). You do not have to type that, and if you later correct the model the name corrects itself.
A name: line of your own always wins. Write one when the generated name is not what you want read
out -- a workflow doing something no single operation describes, or one with no model to name.
You must write one when a name cannot be made for you: when the operation is custom, when no
model is declared or detected, or when a model's build is not known -- neither written in the note
nor readable from the file the workflow loads. Inspect, and the report you are shown before you
import, say so.
The shape to follow is the generated one, because yours will sit in a list beside it:
What it does, then which model does it, in brackets.
References to Image (Qwen Image Edit 2509)
Image to Video (Wan I2V 2.2, first + last frame)
Lipsync (LTX Video 2.3 Dev)
Four things follow from that:
- Start with the words on your operation's heading. A workflow declaring
operation: image_to_videostarts its name "Image to Video". Then a whole section of the picker reads as one list of choices rather than five unrelated titles, and the difference between them -- the model -- is where the eye is already looking. Write a name that starts with something else and Inspect says so, and offers you the generated one. - Name the model the way your model list names it. "Flux Klein 2.0 4B", not "flux2-klein" and not "FluxKlein4B". If the name in brackets is not the name shown against the model you installed, you cannot tell whether the two are the same thing.
- One bracket, at the end. If the workflow is a variation on another one -- two reference images instead of three, a first and last frame instead of a single start frame -- put that in the SAME brackets after a comma, not in a second pair.
- Leave out anything the description should say. Whether it runs in the cloud or locally, how fast it is, how much VRAM it wants, how many seconds of video it makes. None of those belong in a name; all of them belong in the description, which is searched just as the name is.
The one thing a name may say about a build is which build it is, and only when you hold two builds
of the same model for the same operation -- then the generated names read Upscale (Clear Reality V1; fp16) and Upscale (Clear Reality V1; fp8), because that is the only time the build is what
tells them apart. With one build the name never mentions it.
A workflow that needs no model named -- because nothing outside Ordinary Animator does the work -- has no brackets at all. That absence is how the platform's own list shows you which operations run in your browser rather than on a ComfyUI server, and the icon in front of each name says the same thing: a spanner for something that runs in the browser, the ComfyUI logo for a workflow.
Two workflows of yours should never end up with the same name. Nothing stops you, but you will not be able to tell them apart anywhere they are listed.
Nothing reads a name to work out what a workflow is. The name follows from the operation and the model, never the other way round -- so a name that says one model while the workflow declares another does not change which model it is bound to. It only misleads whoever reads it.
Operation -- what job your workflow does
operation is the single line that decides whether your workflow is usable inside the recipes you
already have, or sits on its own with nothing able to reach it. Every workflow needs one. A
workflow without one is imported, listed as needing attention, and offered nowhere until you add it.
| Field | Required | What it is |
|---|---|---|
operation |
Yes | What job this workflow does, and so which dropdown it joins and what it can stand in for. One of the platform's operations, a name of your own beginning with custom_, or custom. |
secondary_operations |
No | Further jobs it also answers, so it is findable under each of them while still having exactly one name. A list, or one line with commas. |
category |
No | The old name for operation. Still read when operation is absent, and mentioned once in Inspect. Do not use it in anything new. |
secondary_categories |
No | The old name for secondary_operations, read the same way. |
A recipe step offers you every workflow with one operation as alternatives to each other. So:
- To sit alongside the workflows you already use, give yours the same operation as the one you
want it to stand in for. A text-to-image workflow of your own declares
operation: text_to_imageand then appears in the same dropdown as every other text-to-image operation. - To start a group of your own, use a name beginning with
custom_-- lower case, with underscores:custom_relight,custom_style_pass. It gets its own heading and can have its own defaults, exactly like a built-in one. A group with a single workflow in it is perfectly normal. - For a workflow that fits none of them, write
operation: custom. It is the "everything else" group and it sits last.
One operation. If yours genuinely does two jobs, declare the one you will reach for most and
list the others as secondary_operations:
operation: pose_transfer
secondary_operations:
- image_to_video
A single line with commas -- secondary_operations: image_to_video, video_to_video -- means the
same thing. The workflow then appears under every one of those headings, and the assistant finds it
under any of them, while still having exactly one name. Do not make a second copy of the workflow to
get a second heading, and do not try to mention the second job in the name. An entry the platform
does not recognise is ignored, and Inspect tells you which one.
The operations the platform uses are the names you already see in a recipe step: text_to_image,
image_to_image, image_to_video, upscale, text_to_speech, and so on. The reliable way to get
one right is to open a recipe step, look at the operation you want to sit beside, and use that name.
An operation that is not recognised -- a typo, or a name of your own that does not start with
custom_ -- is the same as none at all: the workflow appears in no menu. Inspect names it.
category and secondary_categories are the old names for these two fields. Files carrying
them keep working exactly as they did and are never rewritten; Inspect mentions the new name once.
Use operation in anything you write from now on.
Because workflows with one operation stand in for each other, the names of their inputs matter too -- see App inputs and outputs.
Models -- which model your workflow runs
Ordinary Animator works out which models a workflow uses by looking at the files it loads, and most
of the time that is enough -- you never write a models line. Declare one when you need to say
something the files cannot:
models:
- model: Clear Reality V1
build: 4x
| Field | What it is |
|---|---|
models |
The list. One entry per model, the first being the one the workflow is FOR. Leave the whole field out and the models are worked out from the files the workflow loads. |
model |
The model this workflow is for. A name from your AI Models list, or any name at all -- a model the platform has never heard of is kept exactly as you typed it, can be chosen, can be run, and can be made a default. It simply has no card of its own to show you. |
build |
Which build of it the workflow loads -- fp8, fp16, gguf-q4, 4x. Free text. Leave it out and it is read off the file the workflow loads; write it when the file cannot say, because a model whose build nobody knows is one of the three things that means you have to name the workflow yourself. |
The first entry is the model the workflow is FOR. That is the one it is offered under, the one a default is remembered against, and the one the generated name says. List any other models it also uses after it. Leave out the helpers -- an encoder, a detector, a VAE, a background remover used along the way: they are how the job gets done, not something anyone would choose instead.
There are three reasons to write the line:
- A brand-new or obscure model. Nothing recognises the file, so nothing can name it. Declaring it is what makes it usable the day it comes out.
- Several models could be the one. A workflow loading two model files, or calling a provider that offers several, leaves the platform unable to say which one it is about. Inspect says so, and the fix is one line.
- The build matters and the file does not say. A file named without its precision in it tells
nobody what it is;
build:does.
Get the build wrong -- name bf16 on a workflow loading the fp8 file -- and Inspect says which
file it actually loads. Name a model whose files the workflow never loads and it says that too,
because a workflow offered for a model it cannot run is worse than one offered for nothing.
Voice workflows
A workflow that speaks, converts a voice, or trains a voice profile says so with voice_type. It
is what puts the workflow on the voice side of the product rather than the picture side.
| Field | What it is |
|---|---|
voice_type |
One of tts (text to speech), voice-changer (re-voice existing audio), or voice-profile-training (build a reusable voice from samples). |
voice_model |
Which speech model it is built on: chatterbox, qwen3-tts, f5-tts, rvc, so-vits-svc or other. Used to match your workflow to what is known about that model. |
voice_options |
The voices a built-in-speaker workflow offers, separated by a vertical bar. They become the choices for its Voice Id input. Model-specific and rarely needed. |
A text-to-speech workflow also has to take the right inputs -- see Text-to-speech workflows.
Older workflows sometimes carry a field that used to name a render task. There is no longer such a
field: delete that line and use voice_type instead. Left in place it makes the whole note
unreadable, so the workflow disappears from the menus rather than merely ignoring the setting.
Fields that shape how a workflow is run
None of these are required. Add one when the workflow genuinely needs it.
| Field | What it is |
|---|---|
preferred_sizes |
The output sizes this workflow is happy with, as a comma-separated list of WIDTHxHEIGHT, for example 1024x1024,1280x720. The size picker offers these. |
max_size |
The largest output dimension to offer. Use it when a workflow gets slow or fails above a certain size. |
resolution_constraint |
multiple-of-8 or multiple-of-16, when the model only accepts dimensions on that grid. The size picker then cannot produce a size the model will reject. |
default_model_id |
For a workflow where you choose the model at run time, which model it starts on. |
promptCompilerId |
Which model's prompt conventions your prompts should be written for, when this workflow's model has particular habits. |
output_path |
Groups the files this workflow saves on your own machine by shot, character and so on, instead of dropping them all in one folder. |
input_image_1_hint |
A short line of help shown in the drop zone for the first image input -- Front-facing portrait, plain background. Number it for each image slot: input_image_2_hint, and so on. |
input_image_1_wants |
What the slot expects, so the right reference is suggested: for example character-portrait. Numbered the same way. |
list_inputs |
Declares that a set of numbered media slots is really ONE list the person running it fills with as many pictures as they have. Written as Reference Image 1-3 -- the name without the number, the fewest the model needs, the most it accepts -- with commas between several. What it takes to build one is in App Inputs and Outputs. |
chunks |
For a workflow that renders a long clip in repeated chunks: lets OA drop the chunks a short clip does not need. Written as Video S2V Extend 0-2 per 4.9 s of Output Duration. See Repeated chunks. |
notes |
Free text for yourself: quirks, things you tried, why a value is what it is. Nothing reads it. |
Repeated chunks -- drop the ones a short clip does not need
Some video models cannot lengthen a clip from the audio, so the workflow carries the most chunks it will ever need and a short line would still pay for all of them. One line tells OA which chunks it may leave out:
chunks: Video S2V Extend 0-2 per 4.9 s of Output Duration
Video S2V Extendis the name of the repeated chunk. The nodes of each copy have a title ending in the last word of that name and the copy's number --Video S2V Extend 1,KSampler (extend 1),Latent concat (extend 1)-- and OA finds them by those titles.0-2is the fewest and the most copies a run may keep. The part of the workflow outside the copies renders the first chunk.4.9 s of Output Durationis how much of that input one chunk covers. A 3.7 s line keeps no copy, a 5.5 s line keeps one, and so on.
OA removes the last copies a run does not need just before it sends the job, the same way on your own ComfyUI and on Comfy Cloud. Add a number input titled with the block's last word and Count (Int (Extend Count)) and OA writes how many copies it kept there, so the rest of the workflow can work out frame counts and audio length from it. The file itself keeps every copy, so it still runs unchanged in ComfyUI. If the line is not in the form above, or a copy's titles are missing, the workflow is marked Invalid.
Identity LoRA slots -- named nodes, not a field
A workflow can carry a subject's own LoRA -- a character's, a location's, a prop's -- at run time.
It says so not in the note but by giving LoRA loader nodes a title: OA LoRA 1, OA LoRA 2, and
so on. The number of slots is however many such nodes the workflow holds.
- One node per slot for a model whose weights are a single file.
- One node per part for a model that comes in parts, such as Wan 2.2 14B's high and low noise
halves:
OA LoRA 1 highandOA LoRA 1 low. Every part of a slot has to be there, or the slot would load half a LoRA. - Use the loader that matches how the graph loads its model:
LoraLoaderModelOnlybeside a plain model loader,LoraLoaderbeside a checkpoint,WanVideoLoraSelectin a WanVideoWrapper graph. A Nunchaku LoRA loader is refused -- Nunchaku needs a converted LoRA the platform does not make. - Leave the slot bypassed and empty -- no file chosen. The workflow then runs plain until a run puts an identity LoRA in it.
A title that looks like a slot but does not read as one, names a part the model does not have, or sits on a node that is not one of those loaders is reported as a problem with the workflow.
When the file itself is the problem
Two failures happen before any of the above can be looked at, and both mean the file rather than its contents:
- The file is not readable as a workflow. This is almost always a copy-and-paste out of a chat window or an editor that truncated it. Export it again from ComfyUI -- Workflow > Export -- and upload that file.
- The file has no nodes in it. An export taken with an empty canvas open. Open the workflow you meant to send, then export.
A workflow exported from ComfyUI as a PNG keeps the graph inside the image, and the platform
cannot read it from there. Export as .json instead.
Where to go next
- App inputs and outputs -- the other half of making a workflow usable: what the platform is allowed to fill in
- ComfyUI Integration -- adding your own workflow, and checking it will run where you intend to run it
- Workflows -- the view where you import a workflow and ask the assistant what is wrong with one