Migrating workflows to version 0.5
Version 0.5 is backward compatible. Existing 0.4 node ids, positional outputs, widget order, manifests, and checkpoints remain supported. Migration is recommended for clearer graphs and model-free validation, but it is not required merely to open or resume an older workflow.
What changes
Version 0.5 uses one Chain Policy connection for normal authoring. It keeps the audio and transition records independent inside the Plan/checkpoint contract, but removes the need to wire two policy nodes.
| 0.4 audio mode | Final audio | Source reference | Generated continuity |
|---|---|---|---|
generated_audio |
generated | off | on |
source_track |
source | on | off |
source_plus_timeline |
source | on | on |
| 0.4 continuation | 0.5 transition | Default context |
|---|---|---|
| guide with zero context | Cut | 0 frames |
guide |
Guide | 22 frames |
masked_av |
Hard AV | 39 frames |
audio_feathered_av |
Soft AV | 39 frames |
| any other implementation/context pair | Legacy 0.4 Policy Adapter | preserved exactly |
The compact presets derive generated-audio overlap from the same boundary: 0, 22, or 39 frames. A custom audio overlap, Tone/Latent/Detail Guide, Detail AV, Drift-Control AV, old dual-stream Feathered AV, and other raw pairs migrate to the single Legacy 0.4 Policy Adapter node instead. Nothing is approximated. The semantic choice always describes the boundary entering a scene.
Automatic migration
Back up a custom workflow, then run:
python tools/migrate_v05_workflows.py /path/to/workflow.json
Pass several paths to migrate them together. Use --check to report files that
would change without writing them:
python tools/migrate_v05_workflows.py --check /path/to/workflow.json
With no paths, the tool checks or migrates the maintained active examples. It is idempotent: running it again does not add duplicate policy, preflight, or timeline nodes. Exact 0.4 settings become one Chain Policy when they fit the normal presets; other implementation/context pairs become one exact Legacy 0.4 Policy Adapter.
Source-media rewiring
The old source-track graph repeated one full decoded AUDIO value:
Load Audio ─┬→ Loop Start
├→ Current Shot
├→ Tagged Audio Ref
└→ Assemble
The 0.5 graph registers media once:
Load Video ─┐
├→ Source Timeline ─┬→ Preflight / Plan Studio
Load Audio ─┘ └→ Loop Start → Current Shot
└→ scene slice → Tagged Audio Ref
Loop End manifest → Assemble
Path-backed media remains lazy. Current Shot requests only its active window, and manifests carry the descriptor to recovery and assembly. If the only audio input is a tensor, Loop Start materializes one normalized run-owned copy.
Do not return a Tagged Audio fingerprint derived from Current Shot to Plan; that would create a graph cycle. Keep static picture/reference fingerprints on Plan. Structured scene dependencies record the exact source PCM window used by generation automatically.
Preflight and resume
Normal workflows insert Chain Preflight before Loop Start. Studio workflows use the same backend through Plan Studio. It validates duration, source windows, references, compatibility, and resume eligibility without loading H3.
Version 0.5 stores structured per-scene dependencies. A change to the next scene, its incoming transition, or assembly-only media does not invalidate an already accepted predecessor. Old checkpoints without structured records keep their generic hash fallback.
Compatibility guarantee
The migration tool does not renumber the sampling body or change its node types. Loop Start's original optional socket order is preserved so numerical 0.4 workflow slots still deserialize correctly. Legacy full-AUDIO fan-out, direct media paths, Plan widgets, and archived examples remain accepted throughout the 0.5 release.