Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
Changelog
All notable public changes to sprite-gen are recorded here. Versions track the version: field in SKILL.md and pyproject.toml.
v4.3.0 - Shaded sides and tops on the prop plate found as shades of prop_plate.rgb and erased with their edge lines, palette exclusion, and side contact warning (video-frames --prop-plate)
Upgrading from 4.2.0: runs without --prop-plate give the same files, frames reports, stdout, and stderr byte for byte as 4.2.0, except the engine fingerprint implementation_sha256 (in producer of the loop report and other reports that carry one, and in measurement_engine and receipt_engine fields), which hashes every file in sprite_gen/video (only sprite_gen/video/prop_plate.py changed, and video-frames reaches it only with --prop-plate). Runs with --prop-plate now also find and erase shaded sides and tops a video model draws on the plate, erase pale green codec ringing and dark reddened box-edge lines within 4 px of what the plate's pixels and the colour rules took, exclude the side and top and their 4 px rim from --decontam palette learning, add side_px and side_touch_px to each frame row and side_touching to the frames report's prop_plate, print a third warning line when the plate's shaded side or top meets the subject, and refuse a canvas report without prop_plate.rgb before keying (video-canvas --prop-plate has always written it). video-canvas --prop-plate is unchanged. No new dependency, no model call.
- Fix:
video-frames --prop-platefinds and erases shaded box sides and tops drawn on the plate, using the plate colour from the canvas report. With the camera following the body, a video model can draw the flat plate as a box with thickness: a shaded side beside its front and a top above it in darker shades of the plate's colour. 4.2.0 matched only the bright front (pixels within 48 of the plate's colour on every channel), leaving any side wider than the 4 px rim in keyed frames and every cut from them as a vertical band of dark magenta, or a grey line where the side was thin.video-frames --prop-platenow readsprop_plate.rgbalong withprop_plate.boxfrom the canvas report (refusing a report withoutrgbbefore anything is keyed withvideo-frames: --prop-plate: <path> holds no plate colour (prop_plate.rgb); make the canvas again with video-canvas --prop-plate) and finds the front, the side and top, and the light span of the blend line by that one colour. In each frame, after the front is found as before,findlocates the side and top: pixels that are a shade of the plate's colour, meaning the plate's colour times a least-squares brightnessk(pixel dot colour over colour dot colour) between 0.4 (SHADE_LEAST) and 1, with each channel withink * 48ofktimes the colour so the tolerance darkens with the colour. They count only when joined to the front side by side or at corners (directly or through other shades), and only in pieces of shades holding at least 1% of the plate's area on the frame each (PIECE_SHARE, the same floor as the front's pieces). What is not read as a side: a shade the subject holds apart from the plate; dark magenta codec mixing where the subject's outline crosses the plate (too thin a piece;side_pxis 0 in every frame of the synthetic clips without a side); a sliver of side the subject hides all but less thanPIECE_SHAREof (the 4 px rim takes that sliver); black and the plate's colour at 0.35 of its light (at 0.4 it is a shade); and skin tones (of eight skin tones tested, mixed with the plate's colour as a codec blends an edge, the darkest (92, 51, 23) is read as a shade only from 0.47 of the plate's colour and a light one (238, 206, 178) from 0.78). Each frame's reportedboxspans the front and the side and top (seeding the next frame's search window), whiletiltis measured on the front alone. Erasure and--decontampalette exclusion now cover the front, side, and top and the 4 px rim around them. - Fix: the third erasure rule measures its 4 px reach from what the plate's pixels and the colour rules took. In 4.1.0 and 4.2.0, opaque pieces remaining after the magenta and blend-line rules were erased only when they lay wholly within 4 px of the plate's pixels. They now go when they lie in a piece (opaque pixels joined side by side or at corners) wholly within 4 px of what the plate's pixels (front, side, and top) and the two colour rules took. This erases a box's far edge drawn darker and redder than any shade along with the grey line beyond it, and the pale green a codec rings just past the line the plate's edge blends into the key with, while keeping the subject reaching past that 4 px reach (with the rest of the line where its pixels touch it).
- New:
--prop-plateprints a third warning line when the plate's shaded side or top meets the subject. When opaque pixels stay within 4 px of the side and top (side_touch_px > 0), a run printsvideo-frames: warning: --prop-plate: the plate's shaded side or top meets the subject in N frame(s) (...): they went with the plate, and within 4 px of them the subject's pixels stay but for those tinted magenta; look at the subject's edge there, naming the first six frames and counting the rest. - The frames report's
prop_plateaddsside_touching(the frames withside_touch_pxabove 0), and each found row inrowsaddsside_px(pixels of the side and top found joined to the front;plate_pxstays the front's) andside_touch_px(opaque pixels that stay within 4 px of the side and top). - Python callers:
sprite_gen.video.prop_plate: newshade(rgb, colour)andSHADE_LEAST(0.4);read(report)returnsrgbtoo and refuses a report without it;findrows gainside_px;region(row, size, part="pixels")gainspart("sides": the reach round the side and top alone);erasereportsside_touchingand rowsside_touch_px;warningsadds the third line. - Docs: video-pipeline.md "Prop plate:
--prop-plate" subsection and canvas paragraph,SKILL.mdplate paragraph, and the module docstring ofsprite_gen/video/prop_plate.py. - Tests:
tests/video/test_prop_plate.py(28 synthetic tests, up from 19 in 4.2.0). Adds theboxedclip: the camera pans 4 px a frame, from its fifth frame the plate is drawn as a box with a shaded side (178, 0, 166) and a top (200, 0, 196) a pixel wider each frame up to 10 px and a dark line along the side's far edge, and in its eighth frame the figure rests a hand on the plate's top by its side. Checks: no pixel of the plate, its side or top, or the line round them, and no magenta, in any keyed frame of the three clips (filmed,panned,boxed); each row'sside_pxbetween the drawn side and top shrunk and grown by 1 px (none before the side is drawn, none in the two clips without a side), andplate_pxwithin 5% of the drawn front where the figure is clear of it;side_touchingnaming the frames the figure meets the side or top in, the hand's among them, but not one where the figure hides all of them but a sliver below the piece floor; the third warning line; skin-to-shade distance across eight skin tones (pinning at least 0.45 for the darkest (92, 51, 23), actual 0.47, and at least 0.75 for a light one (238, 206, 178), actual 0.78; black and 0.35 of the plate's light rejected, 0.4 accepted); a direct picture of a box (a 10 px side, a top, the dark edge line, and its grey) where all of it goes and a patch of the side's own colour 12 px past the side stays; the plate found by the report's colour (told blue, no frame finds it) and a report without a colour refused; a direct picture where a 2 px pale green past the left edge line and a thin side reddening toward the key go while a denim bar under the plate keeps every pixel; the figure, its hand included, losing only edge pixels the codec tinted magenta (at most 2 a frame inside its core; in the hand frame 12 of the arm's 942 pixels go against 9 in 4.2.0, none of its core); and the frames away from each frame's plate byte-identical to the frames keyed without--prop-plate. Red first on 4.2.0: 7 of the 28 fail, and theboxedclip keeps plate pixels in 7 of its 16 frames (175, 189, 370, 572, 738, 738, and 738 px, up to 540 of them magenta). Each new rule undone fails a test: no piece floor for the side's pieces reads false sides in the clips without one (2 fail); shades read without being joined to the front erase the apart patch (1 fails);SHADE_LEASTat 0 or 0.3 reads black or too dark a colour as a shade (1 fails); a tolerance not darkened withkfails the skin to shade test and the reddened side test, at its find check (2 fail); and the third rule measured from the plate's pixels alone, as in 4.2.0, leaves the pale green and the reddened side in columns 34 to 37 and 58 to 61 (1 fails).
v4.2.0 - Cut with --fill-held off kept as cycle.source/ beside filled loops so alignment needs no clip frames, with cycle_source in the loop report (video-loop, video-cycle-align)
Upgrading from 4.1.0: loops with no held cell made and cuts with --fill-held off give the same files byte for byte as 4.1.0 except the report's producer.implementation_sha256 (four of seven cuts measured before and after: a synthetic walk with a held frame cut with --fill-held off, a synthetic walk with nothing held, and the application's walk flags on a synthetic strider with the fill off and with the fill on where its fill made no cell); cuts that are not loops (played once or an effect's lifetime) and cuts with --out-fps were not measured and are unchanged because the new step does not run for them. For a loop at the clip's rate whose held cells were made again, the delivered cycle/, <name>.strip.png, <name>.strip.json, <name>.gif, and <name>.webp are byte for byte as in 4.1.0 and the report differs only in cycle_source and producer.implementation_sha256 (the other three measured cuts: the held walk, the same with jump repair on, and a walk whose last cells were held), while video-loop now cuts the clip's frames a second time with --fill-held off to keep cycle.source/ beside it (0.31 to 0.40 times the loop's output size on test walks, 19.0 to 19.8 KB beside 48 to 64 KB; cut time 0.41 s to 0.75 s on the synthetic walk and 0.83 s to 1.63 s with jump repair on; 14 RIFE binary calls instead of 12 on an Apple GPU on rife-v4.25 and rife-v4.6 where the second cut repairs a ghost), adds cycle_source to the loop report and summary JSON, and writes stderr lines around the second cut. An app that cuts in one place and runs video-cycle-align in another must carry cycle.source/ with each loop's cycle frames, strip, strip record, and report so alignment needs no clip frames; loops cut by 4.1.0 or earlier have no cycle.source/ and align as before.
- New:
video-loopkeeps the cut with--fill-held offbeside a filled loop ascycle.source/. When a cut is a loop at the clip's rate (no--out-fps) and its held cells were made again (held_fill.madeorheld_fill.again.made), once the filled cut has passed every gate and its GIF and WebP are writtenvideo-loopcuts the clip's frames again with--fill-held offfrom the report'scut_argsandframes_dirthroughloop.cut_again. It builds the cut in.cycle.source.cut/beside the loop; if it takes the same clip frames (cycle_drawingsstart and length), its frames,<name>.strip.png, and<name>.strip.jsonare put in place ascycle.source/by one rename and.cycle.source.cut/is removed. Stderr printsvideo-loop: <name>: its held cells were made again, so it is cut again with the fill off and that cut is kept as cycle.source/ for video-cycle-align; the lines below until it is kept are that cut'sbefore the second cut's lines andvideo-loop: <name>: the cut with the fill off is kept as cycle.source/after; if the second cut fails or takes other frames, stderr printsvideo-loop: warning: <name>: its held cells were made again and no cut with the fill off is kept beside it (<reason>): video-cycle-align cuts it again from the clip's frames, or stops on it without themand the filled loop is still delivered. - Fix:
video-cycle-alignaligns filled loops fromcycle.source/without needing the clip's frames. Up to 4.1.0, aligning a loop whose held cellsvideo-loopmade again always re-cut the clip's frames with--fill-held off, stopping when a set was aligned away from those frames. Wherecycle.source/beside a loop holds a strip record showing no cell was made,video-cycle-alignnow aligns from it directly and cuts nothing, giving byte for byte the same cycle frames, strip, GIF, WebP, andcycle.source/as aligning from the clip's frames, and the same strip record exceptcycle_align.cut_again(written only when the alignment itself cuts again). Only wherecycle.source/is absent (a 4.1.0 or earlier loop, a failed second cut, or a folder not carried along) does it cut again from the clip's frames or stop without them, saying to carry thecycle.source/video-loopkept beside it (its cut with the fill off) or cut it again withvideo-loop --fill-held offand align that. - The loop report and printed summary JSON record
cycle_sourcewhen a loop's held cells were made again at the clip's rate:kept(true),dir("cycle.source"),fill_held("off"),cells(cells of the cut with the fill off), andmade_before(held_fill.made), orkept(false) andwhywhen no cut with the fill off is kept. Loops with no cell made and cuts with--fill-held offrecord nocycle_source. - Python callers:
sprite_gen.video.loop: newkeep_unfilled(report, out_dir, name, cut, **asked)(the cut again with the fill off kept ascycle.source/; ValueError naming why it is not), newfilled(meta)andCUT_AGAIN_DIR(both moved fromalign);sprite_gen.video.align.filledandalign.CUT_AGAIN_DIRkeep their names and refer to those;align.unfilled_sourcealigns from a kept cut and otherwise callskeep_unfilled. - Docs: loop-repair.md section 7 ("An alignment: aligned as filmed, filled at the end") and section 4 ("The cut as filmed is kept"); video-pipeline.md section 4 (held cells, and what a refusal removes);
--fill-heldhelp ofvideo-loopandvideo-cycle-align. - Tests:
tests/video/test_no_repeat_default.pyaddstest_a_set_with_a_filled_direction_is_aligned_without_the_clip_s_frames_as_it_is_with_them,test_video_loop_keeps_a_filled_loop_s_cut_with_the_fill_off_beside_it_and_an_unfilled_one_s_as_it_was, andtest_a_filled_loop_whose_cut_with_the_fill_off_fails_is_delivered_and_says_why_nothing_is_kept, and removescycle.source/first in two existing alignment tests (covering 4.1.0 loops and the updated stop message);tests/video/test_loop_prop_seam_held.pycheckscycle_sourceon the loop report and nocycle_align.cut_againon the aligned strip record;tests/video/test_ghost_given_way.pymoves the RIFE binary call pin on the synthetic strider from rife-v4.25 10 to 12 and rife-v4.6 12 to rife-v4.25 12 to 14 and rife-v4.6 14 (the test's pin per model holds on every machine, including the Linux llvmpipe lane; its new values were measured on an Apple GPU, where the app walk ran the binary 12 times at 4.1.0 and 14 times now on both rife-v4.25 and rife-v4.6; 17 call-pin tests run, none of the others moved).
v4.1.0 - Prop plate tracked and erased per frame across camera pans, with palette exclusion and contact warnings (video-frames --prop-plate)
Upgrading from 4.0.0: runs without --prop-plate take the same code path as 4.0.0 (every new argument is None) and give the same keyed frames, frames report, stdout, and stderr byte for byte as 4.0.0, with --decontam palette and --spill auto as well as by default. Runs with --prop-plate: keyed frames and every cut from them change (the plate is erased in each frame where it is found, and the 3.12.0 median rule no longer erases anything), the frames report's prop_plate records per-frame tracking instead of a fixed box, and the edge pass learns the subject palette without the plate. The canvas side (video-canvas --prop-plate) is unchanged. No new dependency, no model call.
- Fix:
video-frames --prop-platetracks and erases the plate per frame on decoded frames instead of inside one fixed box. In 4.0.0 and since 3.12.0, erasure was confined to the canvas report'sprop_plate.boxscaled to the frame plus a 3 px rim (erase_box). When camera pan or push-off turned the plate, it left that box after initial frames, leaving the plate in keyed frames andvideo-loopcuts (strip, GIF, WebP). The 3.12.0 whole-clip channel median rule (within 40) is removed because it assumed a stationary plate. Now,start_boxmaps the canvas box to frame coordinates rounded outward without a rim. Each frame searches within a window extending the plate's diagonal (onstart_box) past the reference box on every side:start_boxon frame 1, and the last found box on later frames (retained if not found). Plate pieces are connected components (joined side by side or at corners) within 48 of (255, 0, 255) on every channel (PLATE_TOLERANCE), each holding at least 1% of the frame's plate area (PIECE_SHARE); the plate spans all matching pixels within the pieces' bounding box, finding plates cut in two by the subject whole. Erasure applies within 4 px (RIM, was 3) each way and diagonally on decoded frames: a pixel goes if (a) red and blue lead green by more than 35 and are within 90 of each other (plate, edge, codec-tinted subject edge); (b) it sits on the plate-to-key blend line within 2 px (BLEND_REACH) of the key colour (each channel within 48 of key), Rec. 601 luma within 40 (LUMA_SLACK) of the plate-to-key luma span, and red and blue within 40 (BLEND_BALANCE) plus 0.35 (BLEND_SLOPE) of their mean's distance from green; or (c) it forms an opaque piece wholly within the rim, removing blue-grey codec ringing that colour rules cannot tell from denim. Foreground subjects keep their pixels: skin, cloth, and hair lie off the plate-to-key axis, dark outlines fall below the luma span, white exceeds it, and parts crossing the rim are not wholly inside it. Limits: subject grey touching the plate between plate and key goes with the blend line; subject fragments cut off wholly within the rim go with the plate; and frames where no plate is found (subject covers it or it moved further than its diagonal) keep visible plate pixels. Refused runs keep the plate in their refused folder;video-loopcuts of erased frames carry no plate;video-setdoes not paint or erase a plate. - Fix: the edge pass (
--decontam) learns the subject palette without the plate. In 4.0.0, the plate stood as opaque as the subject on the first frame, causing the edge pass (defaultautoinvideo-frames) to learn the plate's magenta as a subject colour. With--prop-plate, the first-frame plate region (its pixels and the 4 px rim) is excluded from the 32-colour subject palette sample and from the interior check deciding whether the palette is key-free. Without--prop-plate, the pass learns as before. - New:
--prop-plateprints warning lines for undetected plates and subject contact. A run printsvideo-frames: warning: --prop-plate: no plate found in N frame(s) (...)naming frames where no plate was found (nothing erased), andvideo-frames: warning: --prop-plate: the plate meets the subject in N frame(s) (...)naming frames where opaque pixels remain within the rim ("look at those frames"). Each lists the first six frames and counts the rest. - The frames report records
prop_plate:canvas_report,start_box,rim(4),frames,frames_changed,erased_px,not_found,touching, androws. Replaceserase_boxwithstart_boxand per-frame entries inrows:frame,found, and where foundbox(frame px, right and bottom one past),plate_px,tilt(degrees the plate's long axis is turned from upright, clockwise on the frame positive),erased_px, andtouch_px. - Python callers:
sprite_gen.video.prop_plate: newfind(files, plate),region(row, size),not_subject(row, size),warnings(done);erase(files, decoded, rows, plate)(waserase(files, plate));frame_boxno longer adds the rim; new constantsKEY,BLEND_REACH,PLATE_TOLERANCE,PIECE_SHARE,LUMA_SLACK,BLEND_BALANCE,BLEND_SLOPE,NAMED;RIMis 4;STILL_TOLERANCEremoved.sprite_gen.frames.decontam:not_applicable(..., not_subject=None),subject_palette(..., not_subject=None),decontaminate(..., not_subject=None).sprite_gen.frames.extract.remove_chroma_background(..., decontam_not_subject=None);sprite_gen.frames.cutout.cutout(..., decontam_not_subject=None)andextract_route(..., decontam_not_subject=None).None(the default) keeps 4.0.0's behaviour. - Docs: video-pipeline.md "Prop plate:
--prop-plate" subsection rewritten; chroma-alpha.md decontam section points to it;SKILL.mdplate guidance. - Tests:
tests/video/test_prop_plate.py(19 synthetic tests: fixed plate shifted 1 px in two frames; panned clip sliding 4 px a frame with one frame turned 12 degrees and one frame without the plate; crossing figure in both; clip with a pink patch on the figure). Verifies no plate or magenta pixels remain in keyed frames; each frame row (boxwithin 2 px of drawn plate,plate_pxwithin 5% andtiltwithin 1 degree in clear frames,not_found,touching); the two warning lines; crossing figure losing at most 2 codec-tinted pixels a frame; byte-identical frames away from the plate compared to runs without--prop-plate(edge pass off); search initialized from the canvas report box (unrelated box finds and erases nothing); direct image check where plate edge and blue-grey blend line go while a denim bar crossing the rim keeps all pixels; early refusal of canvas reports without plates;frame_boxarithmetic; palette exclusion ensuring no palette colour within 48 of the plate and preserving pink within 24 (versus plate colour included without--prop-plate); and cleanvideo-loopcuts. Red first on the 4.0.0 engine: 9 of 18 tests failed. The fixed clip kept 376 and 188 plate pixels across the two shifted frames; the panned clip kept the plate in 13 of 15 frames (up to 3572 px, the whole plate); the turned frame kept 667 px (404 magenta). The median rule erased 4, 89, 100, and 104 untinted figure pixels in four frames. The learned palette contained a colour 3 away from the plate. Under the new rules: without rule (c) the blue-grey line beside the bar remained (column 76); with a 3 px rim a line 4 px from the plate remained (column 56); with both, all 19 passed. When the plate region is not excluded from palette learning, the test fails by including a colour within 48 of the plate (nearest was 3 away on its farthest channel); with exclusion, it passes.
v4.0.0 - Game features removed leaving only sprites, no picture shown again by default (--fill-held off) save meant holds, inspect-holds compares deliveries with hold lists, and video-chain plays keyed clip pieces as one timed move
Upgrading from 3.15.0: sprite-gen sound, sprite-gen game-pack and sprite-gen ui-kit are removed, with gen --layout-guide ui-kit and background-tile --axis xy. These game-making features were added for building games. Making games is outside the scope of this engine, which makes sprites; features that belong to sprites stay. Files an earlier version wrote (sound folders, game packs, UI kit folders) stay on disk; nothing reads them.
Upgrading from 3.15.0: no picture is shown again by default. Output changes where a picture was shown again: a loop whose last cells or wrap step showed one picture, a loop whose repairs left a run, an aligned set whose loops or alignment showed one, a stalled video-stop, a scene layer cut from a clip shown faster than its cells, and the cell-boundary frames of 24, 60 and 15 fps strips in a scene. Every output that showed no picture again is unchanged (the six cuts pinned before, a stop with no held cell, a set aligned with no held cell, pinned on commit 4f5ccd5, and scenes at 25, 20, 30, 12 and 48 fps), and so is every output cut with --fill-held off (except the scene boundary-frame fix, which --fill-held off does not undo). Metadata grows: the strip fps and holds; the loop report cut_args, held_fill.again, held_fill.wrap_held, held_fill.before.wrap and keep on kept runs; cycle_align.cut_again; the Grok report held; bake.json held; the scene report's inspection.repeats and fill_held.
Removed
| Removed | Use |
|---|---|
sprite-gen sound (ElevenLabs sound effects and instrumental music with Opus and AAC exports, a SQLite request cache and a browser loop helper), the package sprite_gen.audio (sound, provider, cache, processing, manifest, playback and the browser helper sprite-gen-audio-v2.mjs, which the wheel no longer carries), docs/sound.md |
No replacement. |
The ElevenLabs provider: sprite_gen.gen.address.ELEVENLABS and its entry in address.PROVIDERS, SPRITE_GEN_ELEVENLABS_BASE_URL, sprite_gen.gen.retry.ELEVENLABS_BUSY and the ElevenLabs rows of retry.UNTAKEN and retry.ACT_FIRST; ELEVENLABS_API_KEY is no longer read |
No replacement. sprite-gen capabilities no longer lists the sound verb or the elevenlabs provider; its providers are openai, xai and anthropic. |
sprite-gen game-pack (game atlases with playback policies, sounds, version 2 images, tiles and UI nine-slice entries), sprite_gen.compose.game_pack, docs/game-pack.md |
compose-atlas and export-aseprite (Phaser and Flame) for engine exports. |
sprite_gen.spec.assets.load_asset_states, which only game-pack called |
load_asset and PLAYBACK_FIELDS stay. |
sprite-gen ui-kit (splitting a game UI kit sheet into nine-slice elements), sprite_gen.frames.ui_kit, docs/ui-kit.md |
No replacement. Its "Alpha cleanup" section moved to docs/sheet-slicing.md ("Alpha cleanup" under "Transparent sheets"); slice-sheet --alpha-floor and --alpha-edge are unchanged. |
gen --layout-guide ui-kit, gen.ui_kit_guide_size and the ui_kit_guide argument of gen.still_prompt |
No replacement. The bare --layout-guide and --layout-guide figure are unchanged. |
background-tile --axis xy (one tile that repeats both ways, made for game ground tiles), sprite_gen.background.tile.inspect_tile_xy and the cyclic seam it used |
No replacement. --axis x and --axis y are unchanged, and so are their reports. |
- Stays the same: non-looping playback (the
video-looponce cut, theloop,hold_lastandend_framemetadata, the play modes), effects (pixel-draw --kind effect, brightness alpha, lifetime cuts),video-stop,slice-sheet --scale sheetand--fit contain, the alpha haze cleanup, the refusal of a painted transparency checkerboard,logo,compose-atlasandexport-aseprite. - Command line:
sprite-gen sound,sprite-gen game-packandsprite-gen ui-kitend as an unknown command with argparse exit code 2;gen --layout-guide ui-kitandbackground-tile --axis xyend as an invalid choice with argparse exit code 2. - Dependencies: the removed features declared no Python dependency.
ffmpeg,ffprobeand the AAC encoder stay required by the video features that use them (face-bake, the video source reading,sprite-gen video); only the sound checks for them were removed. - Old changelog links: the links in the v2.45.0 section that pointed at
docs/game-pack.mdanddocs/ui-kit.mdnow point at those files in thev2.45.0tag on GitHub; their wording is unchanged. - Tests: Removed
tests/audio/(test_sound.py,render_playback.mjs,prepare_playback_fixture.py),tests/compose/test_game_pack.py,tests/compose/test_game_pack_audio.py,tests/compose/test_game_pack_v2.py,tests/frames/test_ui_kit.pyandtests/background/test_tile_xy.py; the game pack test oftests/video/test_stop.pyand oftests/frames/test_slice_sheet_scale.py, theload_asset_statestest oftests/spec/test_assets.py, the three UI kit guide tests oftests/gen/test_layout_guide.py, and the ElevenLabs cases oftests/gen/test_provider_address.pyandtests/workflow/test_capabilities.py. Changed:tests/gen/test_painted_checkerboard.pyrefuses the checkerboard throughgenwith the figure layout guide;tests/workflow/test_capabilities.pyreads a flag's--no-alias offprepareand a required exclusive group offvideo-sway;tests/packaging/test_curation_asset_packaging.pychecks that the wheel carries the face playersprite_gen/video/sprite-gen-face-v1.mjs.
No picture shown again by default
The clip is a walk 24 frames long whose loop comes back to its first picture and stays there: when cut to 26 cells, its last two cells (24 and 25) show the same picture as cell 0, so three cells in a row across the loop's wrap show one picture and the foot stops there on every loop. Both panels cut the same frames with rife-v4.25 and default settings. The left panel is the cut made by 3.15.0, labelled "3.15.0 poses 25/26", which kept those two last cells as filmed because a run that ended on a loop's last cell was not filled and the step across the wrap was not read, while the right panel is the cut made by 4.0.0, labelled "4.0.0 poses 26/26", where 4.0.0 reads the loop as a ring and makes cells 24 and 25 again with RIFE between cell 23 and cell 0 (cell 0 unchanged), each cell RIFE made is outlined in blue on the right, and the foot keeps moving through the wrap.
![]()
- Changed:
video-loopreads a loop as a ring, so a run that ends on the loop's last cell and a cut one cell too long are made again (held_fill.wrap_same,held_fill.before.wrap,held_fill.wrap_held). Before, a run that ended on a loop's last cell was kept as filmed and the last cell and the first were never read as a run. Now the run that ends on the last cell is made again between its first cell and the loop's first cell (its next pose is the first cell, across the wrap); the first cell is never changed. When the last cell (or last cells) shows the picture of the first cell, the wrap steps from a picture to the same picture: those last cells are made again between the cell before them and the first cell, and the first cell stays, read on the cut's frames as filmed (held_fill.wrap_same). A run joined across the wrap (cells at the end plus cells at the start, all one picture) longer thanHOLD_MAX3 cells in total is a hold the motion means: both parts are kept as filmed. A frame made at the wrap is judged as every frame the fill makes; refused, the cells are kept as filmed and awarning:line names them and the faults.held_fill.before.wraprecords the run across the wrap (start,length,joined,filled,made),held_fill.wrap_heldsays the cut as filmed showed one picture across its wrap, and a loop's last cell that shows its first cell's picture is not counted as a pose. - New: the cut is read again after its repairs (
held_fill.again). The fill runs where it ran before: after the anchor andsource_projection, before the ghost screen, the wrap blend, the part pop and the jump repair. Once the repairs have run (the jump repair, the ghost RIFE frames, the eased retime, the overlapped wrap, the wrap blend, the part pop, the seam bridge), the cut is read again for held cells, and a run a repair left (one the first fill did not see) is made again the same way, judged the same way, with the same keeps. It is recorded asheld_fill.againin the loop report and the strip metadata (before,made,frames,cells,poses,held_runs); itswarning:lines start withread again after the repair:. A filmed ghost the repair gave way to the frame beside it (ghost_given_way) is not tried again; its own warning already names it. The repairs themselves are unchanged: they keep the cut's cell count and beat and are not a fill.--fill-held offturns the read-again off too. Measured on the tests' synthetic walker without a staff: its repairs left four runs and one wrap step showing a picture again (42/48 poses/cells); read again, it is 48/48. - New: a run kept as the motion means it carries
keep,held_fill.KEEPSnames the kinds, and the strip metadata gainsholdsandfps(held_fill.intended,held_fill.strip_holds). The rules for a hold the motion means are unchanged: a run longer thanHOLD_MAX3 cells (motion-hold); every run of a cut drawn on twos or threes (drawn); the opening pose (opening) and the closing pose (closing) of a cut played once (one-shot, once, once-return);hold_last; atlas clones. Each run kept for one of these reasons carrieskeep(its kind) inheld_fill.before.held_runs, andheld_fill.KEEPSnames the kinds:motion-hold,drawn,opening,closing. The strip metadata (<name>.strip.json) gainsholds: a list of{from, to, kind, reason}, one per kept run, as cells of the strip (fromandtoboth included), the same list form a renderer's hold list uses;inspect-holdsandscene-renderread it as holds meant.held_fill.intended(record)gives the runs,held_fill.strip_holdsmaps them onto the strip's cells. The strip metadata also gainsfps, the strip's exact rate (cells over the cycle's seconds, rounded to 6 places), next todelay_ms, which stays rounded to hundredths. - New: the loop report records
cut_args, andloop.cut_againcuts the same frames again.cut_argsis every argument the cut was asked with.loop.cut_again(report, out_dir, report_path=..., **changes)cuts the same frames again with those arguments and the changes given (for examplefill_held="off"), with no provider call. It refuses a report from beforecut_argswas recorded, and frames that moved. - Changed:
video-cycle-align(andvideo-set --align-cycles auto) aligns as filmed and fills at the end (cycle_align.cut_again,cycle.source/,--fill-held); newvideo-cycle-align --out-fps. The alignment makes its frames between from frames as filmed, never from frames the fill made. A loop never aligned whose held cellsvideo-loopmade again (held_fill.made, orheld_fill.again.made) is cut again from its frames with--fill-held off, using its report'scut_args(no provider call); that cut is kept ascycle.source/(its frames, strip and strip record) and aligned, andcycle_align.cut_againrecordsreport,fill_held(off),cells,made_before. If it cannot be cut again (no report beside it, a report from before cuts recorded their arguments, frames moved, the cut again took another window of frames), the alignment stops, names the loop and why, and says: cut it again withvideo-loop --fill-held offand align that. Then each loop as aligned is read for held cells and filled at the end (--fill-held auto, the default), asvideo-loopfills a loop: its first cell kept, a loop drawn on twos or threes and a hold longer than three cells kept, each frame made judged with theheldfault among the others; this also catches a frame the alignment's own resampling took twice (--between nearest, or a frame made refused and the nearer source frame taken). The strip record's and the report row'sheld_fillsay what was done;holdslists what was kept.--fill-held offdelivers the aligned loops as they come out of the alignment.--out-fps Fgives every loop of the set at F, above the loops' own rate, once aligned: each cell at its own time, made between the cells beside it, never a cell shown again, every loop the same number of cells; the strip metadata saysout_fpsandsource_fps; a rate not above the loops' own is refused; a loop already aligned at a higher rate is aligned again from itscycle.source/at its source rate. A set whose loops show no held cell is aligned as before, pinned by a picture digest measured on the engine before this change (commit 4f5ccd5). - Changed:
video-setcuts the walks and runs it aligns with--fill-held offand lets the alignment fill them; an item no alignment took is cut again filled (loop.cut_again.whynot aligned);video-set --out-fpswith alignment is no longer refused. The walks and runs a set aligns (filmed in two or more directions,--align-cycles auto) are cut with--fill-held off; the alignment fills them at the end. A standalonevideo-loopand every other item still fill as before. An item cut to be aligned that no alignment took (for example the alignment was skipped) is cut again with the fill on (loop.cut_again), so what the set delivers is filled. The aligned walks and runs are given--out-fpsonce aligned (video-cycle-align --out-fps), the rest byvideo-loop --out-fps. Each item'sloop.posesandloop.held_fillare those of the loop as delivered (after the alignment where it ran). - Changed: an effect's lifetime is named, not filled. A
lifetimecut is read for held cells and each run is named in awarning:line (cells A-B of the effect's lifetime show one picture, played as filmed, an effect's lifetime is not filled). No frame is made. Measured on four synthetic effects (a slash, sparks, a burst, a flame; glowing on black, keyed by brightness alpha, 24 fps), three stalls each, filled with rife-v4.25: 12 frames were made and the judge refused none, all on the first try; two were broken (the sparks smeared into one grey mass, the flame double-exposed) and a third left a flash that should have faded as a grey disc. The ghost screen read none of the four (drawn part-covered), so the judge cannot tell a bad frame of an effect. Filling would deliver those frames, so the lifetime stays a warning. - Changed:
video-stopfills held cells by default (--fill-held auto); its sidecar recordsheld_fillandholds. Before, a stop was read for held cells and recordedheld_fillwithmodeoff; it never made a frame. Now each held run's cells after its first are made again with RIFE between the run's first cell and the next pose, asvideo-loopmakes a cut played once. The opening pose, the closing still, a run longer than three cells and a clip drawn on twos or threes are kept.--fill-held offplays every frame as filmed, as before, with a warning line for each held run. A frame between refused keeps its run as filmed with a warning; with no RIFE installed every held cell is played as filmed with a warning naming the install command andheld_fill.unmade. A RIFE that is found but fails stops the stop (reportstatus: failed) with: fix RIFE, or pass--fill-held off. A stop with no held cell is the same pictures as before. - New:
video,video-extend,video-edit,video-resume(Grok clips) andface-bakeread for a frame shown again and warn; the report gainsheld,bake.jsongainsheld. The published mp4 is read for a frame shown again (frames decoded by ffmpeg, theheld_fill.same_stepsrule; an opaque clip's background, the most common colour of a 4 px border when it covers half the border, is left out). A run that is not an opening, a closing or a run longer than three frames printsvideo: warning: clip.mp4 shows one picture on frames A-B .... Nothing is filled: the clip is kept as the provider made it;video-loopmakes such cells again when the clip is cut. Without ffmpeg the report saysread: falseand a warning line, and the clip is published as before.face-bakereads the baked body cells; a run within a clip, across the loop's wrap or where a clip comes back to the loop printsface-bake: warning: frames A-B show one body picture .... Runs the clip means (longer than three frames, the opening or closing of a clip played once, cells a body row of the pack lists asholds) are recorded without a warning. No frame is made and the verdict does not change. - Fixed:
scene-renderandscene-inspectread a strip's cells atdelay_ms, rounded to hundredths, so a scene frame on a cell boundary showed the cell before it (spec.assets.frame_seconds,SNAP_MS).delay_msis 41.67 ms for 24 fps. Where the rounded delay is longer than the exact one (24, 60 and 15 fps strips), a 24 fps strip in a 24 fps scene showed its first cell twice, and in a 20 fps scene frames 5, 10 and 15 showed cells 5, 11 and 17 where 0.25 s x 24 = 6, 12 and 18 are right. The cells are now read at the strip'sfpswhere its sidecar gives one, and a strip from before (nofps) whosedelay_msis within 0.01 ms of a whole rate is read at that whole rate. Those boundary frames change;--fill-held offdoes not undo this. Strips at 25, 20, 30, 12 and 48 fps render byte for byte as before (pinned). - New:
scene-render --fill-held autogives a layer cut from a filmed clip at the scene's times; the report gainsinspection.repeatsandfill_held; newscene-render --between-cache DIR. By default, a layer whose asset is a cut of a filmed clip (avideo-looporvideo-stopstrip, its sidecar namessource_cut) and would show a cell again at the scene's frames (a 24 fps cut in a 60 fps scene, aplayback_rateunder 1) is given at the scene's times: each frame the cell its time falls on, or RIFE's frame between the two cells either side at its own time, judged asvideo-loopjudges a frame made for a held cell. Held on purpose stays held: before the layer's start, a one-shot's end andhold_last, a run its strip lists inholds, and every layer that is not a video cut (a still, an atlas row, a pixel drawing), which holds its cells as drawn. A layer that shows no cell again keeps its cells as its timing picks them (at the strip's exact rate) and makes no frame; every strip's cells are now read at its exact rate, so a frame on a cell boundary of a 24, 60 or 15 fps strip can change (a 24 fps strip in a 20 fps scene showed frames 5, 10 and 15 as cells 5, 11 and 17 before, and now as cells 6, 12 and 18); strips at 25, 20, 30, 12 and 48 fps render byte for byte as before (pinned in tests). A frame between refused shows the nearer cell again and is named; with no RIFE installed the cells are given as cut and a warning names the frames and the install command; a RIFE that fails stops the render, naming--fill-held off.--fill-held offgives every layer's cells as its timing picks them.inspection.repeatsis each layer's table of scene frames that show the cell the frame before shows: each run, the cell, whether it is held on purpose and why;fill_heldis in the report.--between-cache DIRkeeps the frames made between cells across renders, under the bytes of the two cells, the time and the RIFE that made them, and takes them from there on the next render; the report'sbetween_cachecounts hits and misses. Nothing is kept without it. - New:
sprite-gen inspect-holds(qa) reads a delivery for frames that show a figure's picture again and compares them with hold lists (--holds,--gate,--key,--box,--log,--log-figure). It reads frames with alpha, a keyed clip with--key, a figure's box with--box, or a renderer's log of cells with--logand--log-figure, with the same rule asheld_fill.same_stepson the figure's pixels. It compares them with hold lists (--holds, a strip'sholds, the list form a renderer uses) and reports listed and unlisted holds;--gateexits 1 where any hold is on no list. A render that draws a figure at a new scale or sub-pixel place on every frame is read by its--log. Its full documentation isdocs/asset-tools.md"Frames shown again". - Fixed:
inspect-holdsreads a frame's largest part as a figure however few pixels it has, reads nothing in a--boxthat holds no pixel, exits 2 where no frame was read against the frame before, and reportsstepsandinspected; the Grok clip reading ofvideo,video-extend,video-editandvideo-resumedoes not read a clip whose every frame is the canvas alone. A part is a speck, and is not read, where it holds under 2 % of the pixels of the frame's largest part, or under 64 px; the 64 px floor applied to every part, the frame's largest included, so a frame whose only figure had under 64 px read no figure at all: a 7 x 9 block (63 px) shown on three identical frames of a 24 x 24 clear canvas read an empty table and--gateexited 0 with nothing on stderr, although its frames 1 and 2 show the picture of the frame before, where an 8 x 8 block (64 px) read 2 unlisted holds and--gateexited 1. Now the 64 px floor is never more than half the frame's largest part, so the largest part is always a figure and a part half its size or more is a figure too (two small figures in one frame are both read); both blocks read 2 unlisted holds (frames 1-2) and--gateexits 1, and where a frame's largest part has 128 px or more the rule is exactly what it was. Dots of 1, 2 and 3 px far from the figure, the same on every frame, are still not read. With--box, two frames whose box held no pixel with alpha over 8 (clear there, or past the frame's edge) read as one picture shown again, so a box over clear frames, or past the frame's edge, read a hold on every frame after the first; now such a frame shows no figure there and two such frames are no picture shown again. The report gains each figure'ssteps(its frames read against the frame before; on a loop read across its wrap, the wrap is one step) andinspected(the number of figures read on one step or more); the other fields are unchanged, exit 0, 1 and 2 keep their meanings, and a reading that reads no frame against the frame before is now one of the errors (exit 2). A reading that reads no frame against the frame before (no frame: an empty folder,--framesthat starts past the last frame of a folder, a video, a strip or a log, a log of no line; no figure on any frame: clear frames, frames whose every pixel has alpha 8 or under, a key that leaves nothing, a box that holds nothing, a log whose--log-figurekeys name no cell on any line; no figure shown on two frames in a row, for example one frame) is an error: it exits 2 with or without--gate, its report is still printed on stdout and written to--reportwithinspected0, and one line on stderr says why. Before, most of these passed--gate(exit 0, an empty table, nothing on stderr); an empty folder and a log of no line exited 2 but printed no report; a strip given--framespast its last cell was refused with the wrong reason (as opaque frames); a box over nothing failed the gate on frames that showed nothing. In Python,inspect(...)andread(...)insprite_gen.qa.holdsraiseNothingRead, aValueErrorwhosereportattribute is the report, withinspected0. The Grok clip reading ofvideo,video-extend,video-editandvideo-resumeread a clip whose every frame is the canvas alone (no pixel left once the canvas colour is taken out) as one run of all its frames, recorded as a hold the motion means, and said nothing; now such a clip is not read, its report'sheldisreadfalse withframes,backgroundand awhy, the warning line says its frames were not read for a picture shown again, and the clip is still published. - New:
sprite-gen video-chainplays pieces of keyed clips as one move at the caller's time (--piece,--bridge,--out-fps,--places,--holds,--refuse,--fill-held,--gate). It joins keyed clips of matching canvas, key and rate, making frames between join points or retimed places with RIFE. A run of frames showing one picture, unless a list of holds meant names it, is made again between the poses beside it, and any unlisted frame showing the picture before it fails the run. Pieces that disagree in size, key, or rate, opaque frames, overlapping paths, or places off the chain refuse the run before anything is touched. By default every fault the judge finds refuses a frame;--refusenames those that do; which to leave out is the caller's to decide by looking at the material;held, the bar a frame made off its time must stand under and the final reading refuse whatever it says; a fault left out stays on the frame's record and awarning:line; the judge and its bars do not change.held_fillgainsFAULTSand arefuseargument onat_timesandfill,loop.fill_cutgainsrefuse,framesgainsKEYS_READandkey_kind, aheld_filltry gainsjudgedand, withrefuse,kept_faults, and thevideo-framesreport gainskey_read. - Python callers.
held_fill: newwrap_same,KEEPS,intended,again,strip_holds;premultiplied(was_premultiplied);fill(..., wrap=, drawn_on=);reading(..., wrap=).loop: newcut_again;fill_cut,fill_lines,out_fps_lines(were_fill_held,_fill_lines,_out_fps_lines).align: newfilled,unfilled_source,CUT_AGAIN_DIR;align_set(..., fill_held=, out_fps=).batch: newheld_summary,loop_summary,cut_again_unaligned;align_gaits(..., fill_held=, out_fps=).spec.assets: newframe_seconds,SNAP_MS,FrameSequence.index_at.scene.render.Renderer(..., fill_held=, interpolate=, between_cache=). New modulesprite_gen.qa.holds.stop.make_stop(..., fill_held=, interpolate=). - Tests:
tests/video/test_no_repeat_default.py,tests/scene/test_scene_fill_held.py,tests/qa/test_inspect_holds.py,tests/gen/test_video_held.py,tests/video/test_face_bake_held.py(new);tests/video/test_held_fill.py,tests/video/test_stop.py,tests/video/test_face_layer.py,tests/video/test_root_motion.py,tests/video/test_loop_prop_seam_held.py,tests/video/test_follow_read_on.py,tests/video/test_motion_anchor.py(changed).test_no_repeat_default.pycovers a loop's last cells, a cut one cell too long, the read again after the repairs, the strip'sholds,cut_argsandcut_again, the lifetime warning, the alignment's end fill, its cut again with the fill off and its refusal,--out-fpsonce aligned, a set with no held cell aligned as before, andvideo-setcutting aligned items as filmed and cutting again the ones no alignment took.test_held_fill.py's wrap tests: a run at a loop's wrap is made, a last cell showing the first again is made and the first kept, a hold across the wrap longer than three cells kept whole, a cut played once reads no wrap.test_stop.py: the stop fills by default; with no held cell and with--fill-held offit is the pictures pinned before.test_face_layer.py,test_root_motion.pyandtest_loop_prop_seam_held.py: the strip metadata growsfpsandholds, the old pins otherwise unchanged.test_motion_anchor.py: its anchored cells 5 to 7 differ by one pixel, so the test cuts with--fill-held offto check the anchor's own cells. No-repeat outputs keep their pictures: the six cuts pinned before, a stop with no held cell, a set aligned with no held cell (pinned on commit 4f5ccd5) and scenes at 25, 20, 30, 12 and 48 fps. Two alignment tests now reach the RIFE binary through the alignment's fill at the end:test_cycle_align_aligns_a_two_step_loop_as_the_one_cycle_it_isintest_loop_prop_seam_held.pyandtest_the_first_alignment_records_the_cut_it_was_made_from_and_later_ones_keep_itintest_follow_read_on.py. Like the other tests the default fill sends to the binary often (the rule indocs/release.md), each now has a timeout of its own,@pytest.mark.timeout(900), and pins the binary's calls by model withas_pinned(exactly forrife-v4.6, between a floor and a top forrife-v4.25), and the second test is now markedslow, so the fast bundle (a plainpytest) leaves it out.
v3.15.0 - RIFE is rife-v4.25 from TNTwise's 20250112 release by default, padded to 128 with no augmentation, the old rife-v4.6 kept by name (SPRITE_GEN_RIFE_MODEL_NAME), and sprite-gen rife install run again
Upgrading from 3.14.0: RIFE is rife-v4.25 by default, so every frame RIFE makes changes, sprite-gen rife install must run again, and the old model is one variable away. The engine runs TNTwise's rife-ncnn-vulkan 20250112 and its rife-v4.25 with no augmentation, each image padded to 128; 3.14.0 ran nihui's 20221029 and rife-v4.6 with -x -z. A cut with no held cell and no repair runs no RIFE and keeps its bytes (tests/video/test_held_fill.py::test_a_cut_with_no_held_cell_runs_no_rife_and_is_the_same_bytes_whichever_model); a cut whose held cells are filled, a repaired walk and a set's alignment get rife-v4.25's frames, and can take more or fewer poses. Run sprite-gen rife install once (an 830 MB zip, 45 MB kept, into a new directory beside the old install). A 20221029 binary on PATH holds no rife-v4.25/ and now reads as RIFE not installed: install, or set SPRITE_GEN_RIFE. SPRITE_GEN_RIFE_MODEL_NAME=rife-v4.6 runs the old model as it ran, its frames 3.14.0's to the byte. A --between-cache keys frames by model, so frames kept by 3.14.0 are not taken. With the torch backend, sprite-gen rife install --backend torch again; an executor and its host must name the same model.
RIFE
- Changed: the default interpolator is rife-v4.25, padded to 128, with no augmentation (
rife.MODEL,rife.MODELS,rife.Model,rife.RELEASE20250112,rife.padded). Practical-RIFE recommends 4.25 "by default for most scenes", and it was measured on five loop cuts, three public (tests/fixtures/rife-cuts) and two private. The binary pads 4.25 to 64 itself; the engine hands it each image padded with zeros to a multiple of 128, as Practical-RIFE pads it at scale 1, and cuts the frame back: on Pip's jump, padded to 64 it took 64 poses from 48 frames, padded to 128 67 from 53, the frames PyTorch takes from the published weights. Known limit: the knight's walk takes 40 poses, two fewer than rife-v4.6's 42; cells 2, 34 and 36 are refused by the binary and by Practical-RIFE's PyTorch alike, and cell 6, which Practical-RIFE's PyTorch takes at t 0.2, is refused by the binary: its frame there has no fault, but made off its time its ghost band reads 0.00602, overalign.RETIME_WINDOW_MAX(0.006), and nearer t 0.4 its frames fail the outline and ghost readings. docs/loop-repair.md. - New:
SPRITE_GEN_RIFE_MODEL_NAMEnames the model (rife.model_name(),rife.held_model()).rife-v4.25(the default) orrife-v4.6.SPRITE_GEN_RIFE_MODELnames the model by its directory, which must be named as its model (the binary reads the version from the name); an unknown name, a directory named otherwise and a name and directory that disagree are each refused.rife.tta()takes the model: rife-v4.6 keeps-x -zandSPRITE_GEN_RIFE_TTA; rife-v4.25 refuses any augmentation (TNTwise's README marks-xand-zdeprecated with it).rife.TTAis gone (rife.MODELS[...].tta). - Changed:
sprite-gen rife installdownloads TNTwise's release 20250112 (rife_install.URL,ZIP_SHA256,ZIP_TOP,SOURCE;zip_name()is<platform>.zip). Each platform's zip SHA-256 is pinned and checked before unpacking, and both models' files againstrife.MODEL_SHA256, now{model: {file: {platform: sha256}}}(the Windows zip'sflownet.paramhas CRLF line ends). It keeps the binary,rife-v4.25/,rife-v4.6/,LICENSEandREADME.md(and the DLLs on Windows); the check frame and the report'smodelare the model the engine runs. Nothing is vendored. - Changed: the torch backend runs rife-v4.25 (
rife_torch.NETS,rife_torch.Net,rife_torch.Head,rife_torch.layers,IFNet(name),state_from_ncnn(files, name)). Practical-RIFE 4.25's IFNet, an encoder on each image and five blocks at scales 16 to 1, written again, its weights read from the release'srife-v4.25files (the publishedflownet.pkl, SHA-2566615790efd627772917205db291f51cd392528a157ecbb2ecaeec3bff8eb6de2, as converted to float16), the betas held apart and the encoder's two copies checked equal. On the CPU it makes Practical-RIFE's own frame from those weights, byte for byte. No pkl mirror: the weights come from the same GitHub zip as the binary. - Changed: reports and identities name the model.
interpolator.modelin reports; the torch runner's and executor's identity carrymodel, so a frame kept for one model is never taken for the other, and a host whose executor answers with another model is refused as the RIFE is made. - Licences:
NOTICEgains TNTwise's rife-ncnn-vulkan (MIT, © 2020 nihui) and Practical-RIFE's 4.25 model (MIT, © 2021 hzwer). - Tests:
tests/video/test_rife_models.py,tests/video/test_rife_cuts.py,tests/video/test_rife_torch_v425.py,tests/fixtures/rife-cuts. The default and the named model, their refusals and pins; the 128 padding (frames a multiple of 128, zeros outside) for rife-v4.25 and rife-v4.6 handed as before; cache keys apart by model; three public cuts (a knight's walk, Pip's run and jump, lossless WebP, their RGBA pinned) filled 24 → 60 fps by the binary (real_rife) and by the torch backend (torch_rife): the knight's walk at least 40 poses, Pip's run and jump within one of 39 and 67, Pip's jump the very frames PyTorch took, and every frame rife-v4.6's feet windows caught dragged 2 px caught for rife-v4.25 too; the rife-v4.25 IFNet's layer order, betas and refusals.tests/video/test_held_fill.pyadds the unheld-bytes test above; Tests that pin the binary's calls pin them by model throughas_pinnedintests/conftest.py(0 calls where the binary is not found, the same asrife_located()false before), which reads a pin as an int, held exactly, or as a pair(floor, top), held from floor to top with both ends allowed, given by model (a dict keyed by model name) or for every model alike: rife-v4.6 the count exactly, as before, and a pair for any model but rife-v4.25 refused (ValueError); rife-v4.25 between a floor and a top, where before it was held only at most the pin, since a reviewer pointed out that a change that skipped interpolation (no calls, or too few) would still pass. The floor is the calls the cut makes when no frame is made again at another fraction, two calls for each frame the cut asks for, each asked once at its own time; the top is the larger of the counts measured on an Apple GPU and on llvmpipe (the CPU Vulkan driver of the Linux lane), because rife-v4.25 runs with no augmentation, in float16, so its frames differ with the GPU's arithmetic, and with them the frames refused and made again at another fraction. The floor counts the frames the cut asks for, not every cell of a held run it sets out to fill: a refused frame with no other fraction left to try ends that run's fill, and on four of the cases the cut then calls the binary fewer times than one frame for each cell would take (the 35 pinned cases were run on both machines, 24 of them reaching the binary; in every case both machines asked for the same number of frames at their own time, so each floor is one number; the counts were the same on both machines except on one synthetic walk, 8 calls on the Apple GPU and 10 on llvmpipe; in 9 of the 24 no frame was made again, so the floor equals the top and the count is held exactly; rife-v4.6's counts were the same on every machine measured); the purpose of the pin is unchanged, each call seconds on a CPU's Vulkan driver, so a change that asks for more calls fails on the count, not on the test's time limit, and now a change that asks for fewer frames fails on the count too. rife-v4.25 asks for more calls on some synthetic cuts and fewer on others, refusing a frame between held cells that shows a neighbour's picture again and making it at another time, or keeping the cells as filmed:tests/video/test_play.py(once-return, 30 to 44 against 36),tests/video/test_ghost_given_way.py(8 to 10 against 8),tests/video/test_ghost_screen.py(8 to 28 against 20),tests/video/test_wrap_blend.py(8 to 24 against 16),tests/video/test_gait_fallback.py(4 to 16 against 22 and 4 to 16 against 14),tests/video/test_explicit_window.py(6 to 20 against 6 and 4 to 16 against 22),tests/video/test_walk_steps.py(ten cases, the least 2 against 6, the most 12 to 30 against 12).tests/release/test_rife_pins.pyholds howas_pinnedreads a pin: rife-v4.25 from its floor to its top (0 calls, and fewer than the floor, fail), rife-v4.6 exactly, a pin not by model exactly for every model, a pair for rife-v4.6 refused, and 0 calls where the binary is not found. The test that the binary and the torch backend judge the walkers alike on one machine, which ran them with the default model, rife-v4.25, and failed on the Linux lane on one pair, bfar50 (the binary on llvmpipe read a cross-fade look over its bound, 0.01645 against 0.015, the torch backend on the CPU 0.01198, the faults the same; on the Apple GPU the binary read 0.0113), now judges each model on the pairs picked for it, listed intests/fixtures/rife-walkers/walkers.jsonunderalike: rife-v4.6, run by name, on its seven, and rife-v4.25 on six picked 2026-11-01 by the same rule from the same ten candidates, near25, far50, mid50, cross50, bnear50 and bfar33 (nine met the rule, near50, far25 and swap50 among them and not added; bfar50 did not, its verdicts differing on llvmpipe with a least margin of 0.097 of the bound; no rife-v4.25 pair checks the cross-fade look, since with rife-v4.25 no candidate reads it clear of its bound, where rife-v4.6's bfar50 still does). The torch backend judging the walkers as the binary did on a machine with no binary stays on rife-v4.6's seven pairs and the binary's recorded rife-v4.6 frames.tests/video/test_loop_overlap.py: rife-v4.25 drags the third walker's hand apart at weight 0.5 (refused as torn), and at 0.7 keeps it whole and reads under the bar (TORN_AT). Tests calibrated on rife-v4.6's augmentation name it.
v3.14.0 - A walk whose arms swing past its sides is witnessed where its middle rows read a body rising whole, one on a picture swaying once a cycle or slower held named, the body's word one line in both places
Upgrading from 3.13.0: some walk cuts and crossing readings change, and a set's alignment can change with them. The body's word is now one line, its top line or its first solid row, rising and falling twice an interval on the screen and over its feet, the same line in both places, and where a band of the upper body moves on the beat the rows down the middle of the body tell a body rising whole from a picture zoomed with it. Now witnessed: a walk whose arms swing past its sides where the rows down its middle read a body rising whole; such a cut stands, or a crossing interval that was left on steps is read as a cycle, and its cut can change: the search's cut stands, or a shorter two-step cut is chosen. Now held, named: a walk rising and falling on its legs on a picture swaying up and down once a cycle or slower. It was witnessed over its feet alone, but a head rising twice in one step said the same in one place, and a half cycle stood on it, so a line must now say so in both places. Its loop says cycle-unwitnessed, and video-cycle-align --cycles <loop>=1 settles it where it is one cycle. Also held now: a head rising twice in one step, and a line on a beat of its own over feet that do the rising and falling, which stood before. video-loop run on its own can now write four steps on a cut of two cycles it used to hold cycle-unwitnessed; video-set leaves it out of alignment (cycle-four-steps) and video-cycle-align run on its own stops on it. A set's alignment can change: a loop newly witnessed joins it, so the set's length, and the frames made between for the others, can change.
Walks that stay held, named: a walk whose rows down its middle fit a zoom as well as they fit standing; a walk whose top line a tail takes and whose first solid row says so only on the screen, the shape of a head rising twice in one step; a walk whose body rises and falls once in the cut; a cut whose line over the feet does not read twice the cut; a search's cut kept where no two-step cut closes. video-cycle-align --cycles <loop>=1 settles each that is one cycle.
Walk and run loops
- Changed: the body's word is one line in both places (
local_cycle.body_word,local_cycle.TOP_LINES,local_cycle.bob_word(..., line=),local_cycle.read_cycles,local_cycle.cut_word).local_cycle.body_word(signals, interval)reads each line oflocal_cycle.TOP_LINES({'top': 'its top line', 'first_row': 'its first solid row'}), in that order, withlocal_cycle.bob_word(signals, interval, feet=False, line='top')in both places oflocal_cycle.CUT_LINES, and says"cycles"where one line says so on the screen and over its feet, the same line in both, never one line on the screen and the other over the feet.read_cyclesreads it on the crossing interval, andcut_wordreads it on the cut L, L/2 and 2L throughlocal_cycle._cut_lines, saying"two steps","four steps"or"one step"only where the same line says so in both places. On the screen alone a head rising twice in one step reads as two steps, and the feet leave no such rise and fall over them; over the feet alone the two feet's heights, taken in by turns, read as the body's, and the screen line has none of them. Two lines are read becausetoppasses over what is narrower than half the frame's widest row, so a tail or a cape lifted over the head takes it off the head where the first solid row stays on the body's top, and the first solid row takes an ear's or a hat's tip in; neither is the better line. The price is the design's: a walk whose rise and fall shows in one place only is not witnessed.whystrings that said "its top line" now say the line's name, and the cut'swhywhere nothing says is each place's why, repeated ones once, joined by "; ". - New: the rows down the middle of the body (
legs.body_signalsfirst_row,strips,legs.STRIP,legs.DEEP,local_cycle.body_depth,BOB_RIGID,STRIP_FLOOR,STRIP_SHIFT,STRIP_SHIFT_MIN).legs.body_signals(frames)also returnsfirst_row(per frame, the first solid row) andstrips(per frame, the rows down the middle of the body:legs.DEEP= 0.7 of its median height from the first solid row,legs.STRIP= 0.12 of that height either side of the mean column of the solid pixels among them, each row's mean premultiplied colour and mean cover, shape frames by rows by 4, values 0..1); neither is recorded in any report, andlegs.strike_signalsandgait.silhouette.signalsare unchanged.local_cycle.body_depth(signals, interval)reads the strip at the top of the rise against the bottom: the frames where the rise and fall twice an interval of the line over its lowest row stands a half or more of the way to the top and to the bottom, each set's strips in a median, each fit moved as it fits best, in steps of a twelfth of the most and at least half a row, at mostSTRIP_SHIFT(0.03) of the body's height either way and at leastSTRIP_SHIFT_MIN(3) rows. It returnsneed,risen,rigid,zoom,ratio(zoomofrigid),movedandframes, or None where no strip is read, the rise and fall is none, a set holds under two frames or the frames at the top are not the taller.local_cycle.own_beatreads the body's own onless_lowestalone whereratioisBOB_RIGID(1.0) or more, holds where it is under, and leaves the bands to decide where it is not read: nodepth, ormovedunderSTRIP_FLOOR(CUE_FLOOR*legs.TONE, half the step the colours are drawn in, about 0.00196: under it the strip is as good as plain to that zoom). A body rising whole carries those rows as they are; a zoom as far as the rise draws them longer; arms swinging across the bands hardly touch them. So a walk whose arms swing past its sides on the beat is witnessed where the rows down its middle read a body rising whole, and the bands no longer hold it there. A body one flat colour down its middle has no strip to read, and the bands decide as they did. A picture zoomed on the beat with every band seen drawn against the zoom and a strip as plain is still read as the body's own. - New: a line must be at least
BOB_OWNof what is left against the lowest row on the screen (local_cycle.bob_word). After theless_lowestgate and before the bands, wherebeatis underBOB_OWN(0.3) timesless_lowest, nothing is witnessed, andwhysays "its lowest row does the rising and falling: {name} does so twice an interval {beat} rows on the screen, {percent} of the {less_lowest} left against its lowest row (at least 30%), and the body's own is not told from it". Read every four frames, a line on a beat of twelve leaves nothing of it twice an interval of 24, and still correlates there; what is left against the lowest row is then all the lowest row's. - Changed: report fields.
cycle.step_count.cycles.bobgainstop_line, the line that said so, where it says"cycles", andfeet, the record over the feet, itssaysandtop_linethe same.bodyinbob,lines.*.bobandlines.*.ongainsdepth: null or{need, risen, rigid, zoom, moved, ratio, frames}(need,rigid,zoomandmovedrounded to 5 places,risento 2,ratioto 3), a measure recorded as the other measures are, not a verdict.cycle.cut_witness.byis["screen", "feet"]or["order"], never one place;cut_witness.lines.screen.saysandlines.feet.saysare the body's word, the same in both, the cut's word wherebyis["screen", "feet"]and the body's reading as it stood where it is["order"];lines.*.bob,lines.*.onandoncarrytop_line. No report key tells a right hold from a false one.whystrings changed asdocs/loop-repair.mdsays: the line's name in place of "its top line", "on the screen and over its feet" in the crossings' why, the new gate's why, the strip's why, the band gate's why extended with what the rows down the middle tell, andmarkread of the line that stood. - Changed: Python callers. New
local_cycle.body_word,local_cycle.body_depthandlocal_cycle.TOP_LINES;local_cycle.bob_wordtakesline, aTOP_LINESkey;local_cycle._cut_lineandlocal_cycle.CUT_WORDSare gone. - Tests (
tests/video/test_walk_steps.py,tests/video/test_cycle_align.py,tests/video/test_loop_silent_pass.py). Renamedtest_a_walk_rising_on_its_legs_on_a_picture_swaying_once_a_cycle_or_slower_is_held_as_cut_named(was..._is_witnessed_one_cycle),test_a_walk_whose_feet_meet_once_a_cycle_its_arms_swinging_past_its_sides_is_cut_one_cycle(was..._is_cut_two_intervals_with_a_warning) andtest_a_walk_whose_arms_swing_past_its_sides_reads_as_one_whose_arms_swing_within_them(wastest_a_walk_whose_arms_swing_past_its_sides_is_never_witnessed_its_crossings_left_on_steps_or_its_cut_held).test_a_fixed_cut_of_one_cycle_whose_crossings_mark_cycles_is_counted_two_stepsnow says a walk seen from behind on twos, its arms swinging past its sides, is counted two steps, the same as one whose arms swing within its sides, because the rows down the middle of the body read a body rising whole (it used to say its crossings were left on steps, its fixed cut counted one step, and failed). New tests for a top line on a quick beat of its own over feet rising twice an interval, a head rising twice in one step, a cape taking the top line off the head, a line on the screen and another over the feet, the rows down the middle of a body, a reason both lines of a body give (naming neither) said once, on a crossing interval and on a cut, andvideo-cycle-alignon its own stopping on a walk its body reads four steps. Synthetic frames only.
v3.13.0 - A walk whose feet meet once a cycle is cut one cycle long only where a witness says so, video-set cuts a searched walk or run with motion-auto by default, contract strings written once, read by name
Upgrading from 3.12.1: walk and run cuts and the video-set default change, while the contract strings work changes no output. video-set without --anchor used to cut everything with --anchor none. It now cuts each walk and run item whose loop is searched with --anchor motion-auto and passes the item's view to video-loop, so those items get a different cut and different bytes. --anchor none gives the old cut, its pictures and reports byte for byte apart from the engine hash (producer.implementation_sha256). Idle, attack, once-hold, lifetime and once-return items are cut as before. In video-loop --anchor motion-auto, crossings are read as marking cycles, not steps, only where a witness that reads no leg says the interval holds two steps. This is asked where feet are seen together over half the interval at a pass (crossings.HIDE_SHARE, 0.5), or where --view is given and is not side (video-set passes the view); video-loop --view is new. There are two witnesses. One: the body's top line, less the picture's own flow, rises and falls twice an interval, and that rise and fall is the body's own, read against its lowest row and its upper body, so the picture moved or zoomed with it witnesses nothing. Two, from the front, the back or a diagonal only, never from the side: the order the feet are drawn in. The view's foot cue only refuses. A walk 3.12.1 cut two cycles long is now one cycle, with new bytes. A walk where 3.12.1 kept the search's cut with no steps keeps its cut, and the strip and report now record steps: 2. A walk whose crossings mark steps (brief passes, or from the side) keeps its cut and its pictures. Where nothing witnesses, the crossings stay on steps with a warning naming cycle-unwitnessed. Every walk or run cut is now held to the witness's word before it is cut, in video-loop --anchor motion-auto with --cycle auto or periodic. A cut nothing witnesses as whole cycles keeps its length exactly as chosen, is named cycle-unwitnessed in the warnings and the report (cycle.cut_witness), and is never lengthened or shortened. A walk that starts or stops inside its take gets a retake record (reason: "start-stop", remedy: "retake"). Its cut is kept and is not refused, and video-set names it in its warnings and in table.md. video-set leaves cycle-unwitnessed, cycle-four-steps and start-stop loops out of cycle alignment, names them under left_out, keeps those loops as cut, and aligns the other directions. Standalone video-cycle-align now reads the cut report beside each loop. On a held or four-step cut it stops under its default --multi-cycle fail before rewriting any file. --multi-cycle warn aligns with a warning, and --cycles settles it. Reports gain stands and run_limit where a clip stands still, cycles where cycle reading is asked, and cycle.cut_witness only in reports of --anchor motion-auto cuts; --anchor none reports are unchanged. Report fields step_count.search.same_picture and step_count.same_picture and the count code same-picture are removed.
The contract strings work changes no output: every output, report, JSON body, JSON key order, CLI choice and order, --help text, refusal and warning text keeps its bytes, and nothing a user runs behaves differently because of it, apart from two effects. First, frames/extract.py and frames/decontam.py changed, so engine_revision changes; the curation view's heal re-extracts each existing run once when it is next opened, and the frames it writes have the same pixels. Second, python -m sprite_gen.serve.serve_curation, scripts/serve_curation.py and scripts/interpolate_frames.py now load the image providers (sprite_gen.gen) when they start, so a malformed SPRITE_GEN_GEN_TIMEOUT_SECONDS stops them at start with its ValueError instead of when a reroll or interpolate button is pressed (sprite-gen curation already loaded them and is unchanged). python -m sprite_gen.video.loop and scripts/video_loop.py load the image providers too, and a malformed SPRITE_GEN_GEN_TIMEOUT_SECONDS stops them with its ValueError, even for --help (sprite-gen video-loop already did), while importing sprite_gen.video.loop still loads no provider code.
Walk and run loops
- New: crossing cycle detection (
local_cycle.read_cycles,local_cycle.bob_word,local_cycle.off_flow,local_cycle.twice_an_interval,local_cycle.own_beat,local_cycle.cue_word,crossings.HIDE_SHARE,crossings.Reading.hides,legs.body_signals,CYCLE_SLACK,CUE_FLOOR,CUE_SWAPPED,BOB_TWICE,BOB_FLOOR,BOB_ROWS,BOB_OWN,BOB_SCALE,BEAT_FRAMES,UNWITNESSED). In gap mode on a readable reading, when feet can hide behind one another (reading.overlapovercrossings.HIDE_SHARE, 0.5) or when the view is given and is notside, crossing intervals are checked to see if they mark full cycles rather than single steps.repeat_at(distances, span)reads the mean distance of frames to those lagged byspanover the clip's mean step from frame to frame. Comparing distances at half, one, and two intervals, crossings mark cycles whenone < halfandone <= two + CYCLE_SLACK(0.5), only where a witness that reads no leg says the interval holds two steps, the body's own rise and fall twice an interval: its top line (legs.strike_signalstop) less its flow, read against its lowest row and upper body. New functionlocal_cycle.off_flow(values, interval)returnsvalues(per frame) less their flow: each frame minus the mean of the interval about it (a moving average one interval long, its two end frames weighted by the part of a frame the interval covers), kept only over the frames the interval fits about (the first and lastceil(interval/2 - 0.5)frames drop out), and what is left minus its least-squares straight line; a rise and fall once or twice an interval averages to nothing over one interval and is left whole, while a flow slower than the interval is taken out wholly where it bends no more than a cubic (a constant, a straight drift, an arc, a cubic) and in part where it is a slow sway a few intervals long.local_cycle.bob_word(signals, interval)reads the body's top line less its flow (off_flow(top, interval)), not the raw line;swingis the range of the line left over the body's median height, androwsis that range in pixel rows. Where the clip is under an interval long so nothing is left,saysis null andwhysays its top line less its flow is not read; whereswingis underBOB_FLOOR(0.005) orrowsis underBOB_ROWS(2),saysis null,whysays the line's range less its flow is under 0.5 % of the body's height or 2 rows, so it does not rise and fall (the top line is read in whole pixel rows, so a picture drifting up or down makes the line step a row up and down as it rounds, and that rounding, less its own mean over an interval, stays under 2 rows), andhalfandquarterare not read. Otherwise it reads the line left's correlation half an interval on (half) and a quarter of an interval on (quarter), both withcrossings.correlation_on(each the larger of the two whole lags about the span), saying"cycles"only wherehalfisBOB_TWICE(0.28) or more andquarteris-BOB_TWICE(-0.28) or less (the line is as it was half an interval on and turned over a quarter on, which is a rise and fall twice an interval; a step's bob is turned over half an interval on, and any flow left over is as it was at both half and a quarter of an interval on so it cannot pass the quarter test), null otherwise withwhygiving both values. Where any frame's lowest solid row is the frame's last row (legs.body_signalsedge),saysis null,why: "its lowest row is the frame's last row in {n} of {N} frames: the feet may run off the frame, and the picture moving is not read off them" (there the lowest row is the frame's, not the feet's).local_cycle.twice_an_interval(values, interval)readsvalues(per frame) less their flow (off_flow), then a least-squares fit of a mean, the harmonic twice an interval (cos and sin of 4 pi k /interval) and the harmonic once an interval (cos and sin of 2 pi k /interval), k the frames left counted from the first; it returns the twice-an-interval harmonic as a complex amplitude (its cos coefficient less i times its sin coefficient), in the values' units (a line rising and falling a rows either way twice an interval reads a in magnitude; lines read so over the same frames and interval subtract as they move), or None where fewer thanBEAT_FRAMES(8) frames are left; where none,saysis null,why: "its top line's rise and fall twice an interval is not read against its lowest row and upper body: under 8 frames are left less the flow".local_cycle.own_beat(signals, interval)reads three lines withtwice_an_interval: the top line (top), the lowest solid row (reach) and the lowest opaque row (sole); it returns, in rows up and down (twice the magnitude):beat(the top line's),lowest(the lowest row's),sole,less_lowest(the top line's less the lowest row's: the picture moving taken out),bands({rows, width, zoom, beat, reads, less}, per band: its rows below the first solid row, its width in the median frame andzoom, in pixels,beatin pixels,readsis the band'sbeatover itszoom(the share of the zoom making the line's rise and fall that the band reads), read whatever its turn: a zoom moves a band's width in step with the line it lifts, but the band's own parts swinging across it (arms, a cape) move it too, in step with the line, against it, or a quarter of the beat off, and the zoom's part is not told from theirs.lessis what is left of the top line's rise and fall twice an interval less as much of the zoom as the band reads:less_lowesttimes (1 -reads), and nothing wherereadsis 1 or more, so a band whose width moves against the line adds nothing to what is left,readsandlessnull where the band is not seen),less_bands(the leastless, null where no band is seen),still_bands(the number of bands seen whosereadsis at most 1 -BOB_SCALE, 0.4: they hold still on the beat), andown, the smaller ofless_lowestandless_bands(None where a line is not read). The floor is the larger ofBOB_ROWSandBOB_FLOORof the body's median height; whereless_lowestis under the larger ofBOB_OWN(0.3) timesbeatand the floor,saysis null,why: "its lowest row rises and falls with it: less the lowest row's, its top line's rise and fall twice an interval is {x} rows of {beat} ({percent}; at least 30% and {floor} rows): the picture moves with the body, and the body's own is not told from it"; where no band is seen (less_bandsnull),saysis null,why: "no band of its upper body would show the picture zooming: zoomed in as far as its top line rises and falls twice an interval against its lowest row ({less_lowest} rows of {height}), no band's width moves 1 px (at most {largest zoom}): the picture zooming with the body is not told from the body's own"; whereless_bandsis under the largest ofBOB_OWNtimesbeat, the floor, andBOB_SCALE(0.6) timesless_lowest,saysis null,why: "its upper body's width changes with it: less as much of the zoom as its band {a}% to {b}% of its height below its top reads, its top line's rise and fall twice an interval is {x} rows of {beat} ({percent}), {ratio} of the {less_lowest} left against the lowest row (at least 30%, {floor} rows and 0.6): the picture may zoom with the body, and the body's own is not told from it"; otherwisesays"cycles". This tells them apart because a body rising and falling on its legs leaves its planted foot, the lowest solid row, on the ground, and carries its upper body's bands whole and leaves their widths: the picture moved up and down carries the lowest row with the top line by the same rows, so nothing is left of the line's rise against it, while the picture zoomed in and out widens each band as it lifts the line, as far as the band's outline lets it, so nothing is left once the zoom is taken out too. Where no band would show the zoom, or any band that would moves on the beat (arms swinging past the body's sides, a cape, or the picture zooming), nothing tells the picture zooming from the body's own, and nothing is witnessed; one band holding still says only that no zoom shows in that band (a head drawn narrower as the picture zooms in holds still so). Two limits the code does not catch: (a) a picture zoomed on the beat with every band seen drawn against the zoom, so that each band holds still, is read as the body's own (its band widths are those of an upper body rising whole on its legs; measured on one such drawing, every band within 0.78 px of such a body); (b) a body that rises and falls twice a step on its own legs reads as two steps an interval of one. A walk whose arms swing past its sides on the beat is not witnessed where a band seen moves on the beat (itsreadsover 0.4). Where a walk is not witnessed, its crossings stay on steps, or its cut is held, and either way it is named, never handed out as a cycle unnamed. Newlegs.body_signals(frames)reads per framebands, each band's mean width in alpha, in pixels, read on the same rows in every frame, those of the clip's median body height (legs.BANDS=((0.02, 0.10), (0.10, 0.18), (0.18, 0.26), (0.26, 0.34), (0.34, 0.42), (0.42, 0.50))), andedge, 1 where the lowest solid row is the frame's last row, else 0; only the step count's witness reads them, merged byloop.read_stepsinto the signals it passes tolocal_cycle.read_cycles;legs.strike_signalsis unchanged, so the loop report'sgait.silhouette.signalsis unchanged, and--anchor nonestill gives the old cut, its pictures and reports byte for byte apart from the engine hash. The directional foot cue (legs.shade_cuefrom the side or diagonal,legs.depth_cuefrom the front or back) is read with a view given bylocal_cycle.cue_word(cue, interval, step=None)and can only refuse cycles: underCUE_FLOOR(0.5) of the step it is drawn in (legs.TONE, 1/255, or a pixel row of median body height) it says"alike"; where it turns over one interval on (crossings.correlation_onat or belowCUE_SWAPPED,-0.2) it says"steps", refusing cycles because the other leg leads there; otherwise null. With no view no cue is read at all. Where the view's cue says"steps", the count stands (two steps); else where the bob says"cycles", cycles are marked; otherwise crossings stay on steps withunwitnessedtrue (local_cycle.UNWITNESSED) and a warning (cycle-unwitnessed). When cycles are marked,Reading.mark_cyclessetsperto 2 and halvesstepandstep_range: a cut one interval long is two steps, and the search's cut (--anchor motion-auto) taken on it writessteps: {count: 2, by: crossings}. A fixed cut (--cycle fixed,fixed_count) and the loop as it plays round (ring_steps) read the same; a fixed cut one interval long is counted two steps and not refused, and still writes nosteps. - Removed: the same-picture rule (
local_cycle.same_picture,local_cycle.same_picture_count,local_cycle.SAME_PICTURE_MAX, count codesame-picture, report fieldsstep_count.search.same_pictureandstep_count.same_picture). It kept the search's cut, with nosteps, where the count said one step; it never cut one cycle where the search had found two.local_cycle.read_cyclestakes its place. - New: walk start-stop retake reporting (
loop.stand_retake,crossings.Reading.stands). In gap mode, runs where the feet stay together longer thanrun_limit(√2 times the median whole pass run) are recorded inReading.stands. Where a clip shows its steps, containsstands, and the cut kept does not count two steps (verdictis nottwo) with no two-step cut closing between the standing frames,loop.stand_retakeemits aretakereport (reason: "start-stop",remedy: "retake"), keeping the cut as cut without refusal under--unfixed refuse. Where a part also pops, oneretakenames both (loop.retakes): the first reason's record,reasons: ["part-pop", "start-stop"], and each reason's numbers under its own key (part_pop,start_stop). - Changed:
video-setdefaults gait anchoring tomotion-auto(batch.anchor_for). Without an explicit--anchor,video-setcuts each walk and run item whose loop is searched (cycle_forreturnsautoorperiodic) withmotion-auto, and assignsnoneto idle, attack, once-hold, lifetime, and once-return items; explicit--anchoroptions are applied to every item as before.video-setpasses each item's view tovideo-loop. Any item whose loop names a retake carriesloop.retake, appears in the set'swarnings, and appends(film again: <reasons>)totable.md. - Changed: cycle alignment leaves out start-stop retake, cycle-unwitnessed and cycle-four-steps loops (
batch.align_gaits,video-set --align-cycles auto,local_cycle.four_steps). Takes flagged withstart-stopretakes loop no two steps, loops whose cut nothing witnesses whole cycles (cycle-unwitnessed: crossings left on steps unwitnessed, or a cut the cut witness held) may hold half a cycle or two, and the warning says so, and loops whose cut witness says four steps (cycle-four-steps) hold two cycles where their strip counts two steps (steps: 2, whichvideo-cycle-alignreads as one cycle) and would play twice as fast if aligned as one cycle; all are excluded from gait cycle alignment, keeping their loops as cut while aligning the remaining directions. Excluded items are recorded underleft_out({item: reasons}, listing["start-stop"],["cycle-unwitnessed"],["cycle-four-steps"], or["start-stop", "cycle-unwitnessed"]) with a stderr warning and a set warning; if fewer than two directions remain, alignment is skipped (applied: false,why: "fewer than two directions left to align"). A left-out loop whose step screen suspects one step is told in its warning what settles it (video-loop --steps 1), asvideo-cycle-alignsays when it stops on such a loop, andbatch.left_out_whytakesone_step. - New: a walk's cut is held to its body's word before it is cut (
loop._witnessed,local_cycle.cut_word,local_cycle.unwitnessed,local_cycle.held_verdict). Invideo-loop --anchor motion-auto(--cycle autoorperiodic), afterloop._by_stepschooses the cut and before frames are cut,loop._witnessed(cycle, frames=...)holds the cut s/L tolocal_cycle.cut_word(signals, length), which readslocal_cycle.bob_wordon two lines,local_cycle.CUT_LINES('screen'on the screen, less its flow, and'feet'over its feet withlocal_cycle.over_feet,feet=True), at length L, L/2 and 2L (a picture swaying up and down once a cut or slower hides the body's rise and fall twice the cut on the screen, where the line over the feet reads it; a walk whose lean changes slowly on its feet tilts the ground under them, so the line over the feet takes in the two feet's heights by turns and reads no rise and fall, where the line on the screen reads it) and says the first either line says inlocal_cycle.CUT_WORDS:"two steps"(a cycle),"four steps"(two cycles),"one step"(once in the cut), or null. On two steps or four steps the cut stands ({cut: [s, L], ...cut_word's record}; where the cut stands and its lowest row rises and falls twice the cut more than its top line on the screen, the record carriesmark; it holds nothing), and a cut of four steps (two cycles), its strip still counting two steps, makeslocal_cycle.four_steps(cycle)true, andvideo-setleaves the item out of cycle alignment (left_out["cycle-four-steps"]); anything else is held exactly as chosen (two clip crossing intervals where counted, else the search's cut), settingcut_witness.heldto"unwitnessed", warningcycle-unwitnessed(local_cycle.held_verdict(cycle)vialocal_cycle.step_verdict), and markinglocal_cycle.unwitnessed(cycle)true sovideo-setleaves the item out of cycle alignment (left_out["cycle-unwitnessed"]), while cuts the step count already held recordheld: "step count". A reading of"one step"is held and never cut again two long because a body rising and falling once in the cut cannot be distinguished between half a cycle of legs drawn alike and a full cycle of a limp or bouncing legless body without reading legs, and the witness never lengthens or shortens a cut; walks whose body rises once a cycle, legless bodies bouncing once in the cut, and walks carried whole with no rise of their own are held and named even where a cut is a whole cycle. It now reads the cut_two_lengthshanded it, so what it reads is the cut that will play: a cut made two lengths long is read at that length, and it stands, or is held and named, as any other cut. - Changed: the body's own rise and fall is read against the lowest opaque row as well (
legs.body_signalssole,legs.OPAQUE,local_cycle.own_beat).legs.body_signals(frames)now returnssoleper frame, taking the lowest row with an alpha oflegs.OPAQUE(255) or the lowest solid row where none is opaque.local_cycle.own_beat(signals, interval)readssolewithtwice_an_intervaland takesless_lowestas the top line's rise and fall less the lowest solid row's or less the lowest opaque row's, whichever leaves less, returningsoleas rows up and down. This prevents a translucent shadow drawn fixed on the screen under the feet from acting as the lowest solid row and registering picture shake twice an interval as the body's own rise against it, since opaque feet move with the picture. - New: the order the feet are drawn in witnesses a walk's steps (
legs.feet_order,legs.CONTACT,local_cycle.order_word,ORDER_ROWS,ORDER_TRAVEL,ORDER_SWAY,ORDER_REACH,ORDER_SLACK,ORDER_WORDS).legs.feet_ordertracks which foot is drawn lower in each frame, andlocal_cycle.order_wordgates side changes to witness one, two, or four steps across a span from non-side views. From the front, the back, or a diagonal, the foot nearer the viewer is drawn lower, and the nearer foot changes sides once a step, twice a cycle. The view's label is not taken for it, because a generated walk's label may be wrong: the clip must show that its two sides of feet are its two legs, or nothing is witnessed.read_cyclesandcut_wordread the foot drawing order when body cues do not witness crossings or cuts, and search cuts that failed to close are held unwitnessed rather than stood by foot order. A diagonal walk whose feet pass each other on the screen, one foot always drawn lower and the other passing it on either side, shows the same changes a side walk does, and the order does not witness it; a side walk is never read on the order. Before its gates,local_cycle.order_wordleaves out frames whose contacts touch no column of anything standing on the lowest row in any frame, recorded inoff_ground, so a dipping tail is not read as a foot and changing sides to count half a cycle as a whole, at the cost of leaving out feet lifted over columns where nothing ever stands. As a named limit, a tail hanging over the columns the feet stand on is still read as a foot, held only by the gates after the reading (the sliding check, the ground travelled, and the upper body's sway). - Changed: standalone
video-cycle-alignstops on held or four-step cuts (align.held_cut).video-cycle-alignrun on its own reads the cut report beside each loop throughalign.held_cut(loop_dir, meta_path, meta). Where nothing witnessed the cut whole cycles (cycle-unwitnessed) or the cut spans four steps (cycle-four-steps), the loop is named underheldand the aligner stops under--multi-cycle failbefore rewriting any files, adding "and nothing witnessed some of the cuts whole cycles". Under--multi-cycle warnit aligns the loop with a warning, matchingvideo-setinstead of aligning held loops as one cycle without a word. - CLI:
video-loop --view front|back|side|front_diagonal|back_diagonal(default none) sets the clip view for cycle detection and foot cue selection. - Report fields:
cycle.step_count.cycles({asked, interval, overlap, half, one, two, slack, cue, bob, cycles, unwitnessed, why}, wherecueandbobare recorded only where the picture passes,cue: {range, floor, swapped, one, says, why}only with a view,oneabsent wheresaysis"alike",bob: {swing, rows, floor, twice, half, quarter, edge, body: {beat, lowest, sole, less_lowest, less_bands, still_bands, own, bands: {rows, width, zoom, beat, reads, less}, share, scale, least, scale_least, band_floor}, says, why},half,quarter,edgeandbodyabsent under the floors,bodyabsent where under 8 frames are left, andwhyabsent where it says"cycles", andunwitnessedtrue only where nothing witnessed); the loop's warnings (jolt.warnings);step_count.standsandstep_count.run_limit;loop.retake({reason: "start-stop", reasons, start_stop: {stands, run_limit, crossings, cut, verdict, code, why}, remedy: "retake"}); the set report's itemloop.retake({reason, reasons, remedy}) and itemloop["cycle-unwitnessed"](true), and its state'scycle_align.<state>.left_out({item: reasons}); the loop report'scycle.cut_witness({cut, says, by, lines, on, why, held, mark},lines({screen, feet}, each{says, bob, on, why}), the feet line'sbobandonwithover,byonly where it says a word,onwith itslineandintervalonly for four steps or one step,whyonly wheresaysis null,heldonly where held, andmarkonly where marked); the printed summary'scycle.cut_witness({cut, says, by, held, mark}, each where present).cycle.step_count.cycles.orderandcut_witness.orderrecord foot-order metrics (apart,swing,floor,changes,slides,spacing,travel,sway,tilt,per,says,why,off_ground), andvideo-cycle-alignreports held suspect loops underheldwith{reason, report}. - Python callers: new
local_cycle.read_cycles(reading, distances, view=None, cue=None, cue_step=None, signals=None),local_cycle.bob_word(signals, interval, feet=False),local_cycle.twice_an_interval(values, interval),local_cycle.own_beat(signals, interval),local_cycle.cut_word(signals, length),local_cycle.over_feet(signals, interval),local_cycle.unwitnessed(cycle),local_cycle.four_steps(cycle),local_cycle.held_verdict(cycle)(refuses with aValueErrora cut held on one step whose record names no line it was read on (nobyorlines)),legs.OPAQUE,local_cycle.BOB_OWN,local_cycle.BOB_SCALE,local_cycle.BEAT_FRAMES,legs.body_signals(frames),legs.BANDS,legs.band_rows(median),legs.band_widths(alpha, rows),legs.zoomed(alpha, scale),local_cycle.BAND_FLOOR,local_cycle.off_flow(values, interval),local_cycle.cue_word(cue, interval, step=None),local_cycle.BOB_TWICE,local_cycle.BOB_FLOOR,local_cycle.BOB_ROWS,local_cycle.CUT_LINES,local_cycle.CUT_WORDS,local_cycle.UNWITNESSED,local_cycle.FOUR_STEPS,local_cycle.CUE_FLOOR,legs.TONE,local_cycle.repeat_at(distances, span),batch.anchor_for(state, cut, anchor),batch.left_out_why(reasons, stands=False, one_step=False),loop.stand_retake(cycle),loop.retakes(*records),loop.STAND_REASON;crossings._alternationis now publiccrossings.correlation_on(values, span);align._feet,align._depth_cue,align._shade_cue, andalign.SHADE_BANDare moved tolegs.feet_halves,legs.depth_cue,legs.shade_cue, andlegs.SHADE_BAND(alignkeeps_depth_cueand_shade_cuealiases);crossings.Readinggainsinterval,per,cycles,hides, andmark_cycles(said).local_cycle.read_cyclesandlocal_cycle.cut_wordtakeorder,cut_wordtakesdeclined, andalign.held_cutchecks loop cut reports. - Tests:
tests/video/test_walk_steps.pycovers these synthetic walker cases (the walkers' bodies rise and fall on legs whose soles stay on the ground unless held still or drawn carried whole; the walkers whose body is witnessed (and those the cut's witness reads one step of) swing their arms within the body's sides, 8 px either way of its middle (ARMS_IN), the body's sides 28 px apart; the other walkers seen from the side, from behind or on a front diagonal swing them 16 px either way of the body's middle, past its sides; the walker seen from the front swings its arms up and down beside its body, and some walkers have no arms):- a walker seen from behind whose far foot hides behind the near one (feet together over half the interval) across cycles of 20 frames on twos, 24 on threes, and 17.5 and 18.5 on ones: its top line rises and falls twice an interval, cutting one cycle within a frame with
cyclestrue,steps: 2, and no cue read with no view, its bob'sbody.shareat least0.3,body.scaleat least0.6,edge0, every band seen holds still on the beat (still_bandsequals the bands seen), and itswhynaming the body's own; the same walker with its far leg drawn as the near one (legs alike), with no view and with--view back_diagonal, is still cut to one cycle because the view's cue says"alike"(which no longer refuses) and the bob witnesses; - a front-diagonal walker whose near foot steps out toward the camera and passes the far one apart (feet together under half the interval, cycle 16 and 18): with
--view front_diagonalcut to one cycle because its foot cue moves over the floor and does not turn over one interval on (saysnull) and its top line rises and falls twice an interval; without a view it is not asked and is cut to two cycles (32, 36 frames); its cut witness says"four steps", its strip sayssteps: 2, andlocal_cycle.four_stepsis true; - the walker seen from behind (17.5 on ones; no view and
--view back_diagonal) and the front-diagonal walker (16,--view front_diagonal) with their bodies held still: the top line does not rise and fall (the line left underBOB_FLOORof the body's height and underBOB_ROWSrows), keeping two intervals (two cycles) withcyclesfalse,unwitnessedtrue, and the warning naming the cut; - a side walker whose two steps are one silhouette (46-frame cycle, near and far a tone or four apart), passes brief: not asked with no view or
--view side, keeping two steps at 46 frames; the cut's witness then reads the cut: the arms move the bands they swing over on the beat, so nothing that reads no leg witnesses the cut whole cycles, and the cut is held as cut and named (cycle-unwitnessed, the warning), its why naming the upper body's width; - the same 46-frame walker filmed as a front diagonal, its far leg four tones off the near one,
--view front_diagonal: the picture passes, but the foot cue turns over one interval on (says: "steps"), keeping two steps at 46 frames; its cut is held as cut and named by the cut's witness (the warning), for the same reason; - the same 46-frame walker with its legs drawn alike (arms still four tones apart) asked with
--viewset tofront,front_diagonal,back, andback_diagonal: the picture passes, the cue says"alike", and its top line rises and falls once an interval (a step), so itshalfcorrelation is negative, leaving nothing to witness and keeping two steps at 46 frames withunwitnessedtrue and the warning; - the same 46-frame walker with its legs drawn alike and twice as wide (10 px either side of its line instead of 5), so the feet are seen together over half the interval and a pass could hide: asked with no view and with
--viewset toside,front_diagonal, andback, keeping two steps at 46 frames withunwitnessedtrue and the warning (with a view the cue says"alike", and with no view no cue is read); - the wide alike walker lit by a light fixed on the screen, lighter to the right (up to 12 tones across the feet), with no view and with
--viewset toside,front_diagonal, andback_diagonal: the shade of the feet moves with how far apart they are drawn and turns over half an interval on, but nothing witnesses, keeping two steps at 46 frames with the warning; - the alike walker (legs 5 px) with the leg swinging forward lifted 6 px at its pass and a light fixed on the screen varying top to bottom (12 tones), asked with
--viewset tofront,front_diagonal,back, andback_diagonal: the cue moves with the swing whichever leg swings and turns over half an interval on, but nothing witnesses, keeping two steps at 46 frames with the warning; - the wide walker with its far leg four tones off the near one (where a pass can hide): with
--view sideorfront_diagonalthe cue turns over one interval on ("steps"), keeping two steps at 46 frames with no warning, while with no view no cue is read and nothing witnesses, keeping 46 frames withunwitnessedtrue and the warning; - the wide legs-alike side walker (46-frame cycle, crossings every 23 frames, a pass can hide), carried up and down with the whole picture: along a smooth arc 24 px deep, and, with its body held still, along the same arc, along a sway 12 px either way, four intervals long (92 frames), and down a ramp 24 px over the clip, a row every three frames; each is cut two steps, 46 frames, with
unwitnessedand the warning; for the bobbing walker itshalfis-0.28or less (less its flow its line rises and falls once an interval); for the still one itsrowsis underBOB_ROWS; before this change every one of the four was cut one step, counted two, and no warning said so; - the walker seen from behind whose far foot hides behind the near one (cycle 17.5 frames on ones, legs drawn alike), carried along the arc and the cubic: cut one cycle; the bob says
"cycles"with itsquarterat-0.28or less; - synthetic units meeting every 15 frames verify that where a pass can hide (feet together 9 frames at each meeting), a top line rising and falling every 7.5 frames (twice an interval) marks cycles (15 frames kept as one cycle,
steps: 2), while rising and falling every 15 frames (once an interval) or held still keeps two steps of 15 (30 frames) withunwitnessedtrue and the warning; brief meetings with no view orsideare not asked; on front diagonals with brief meetings, a cue turning over every 15 frames (one interval on) keeps two steps of 15 (30 frames) whatever the body does, and a cue turning over half an interval on and holding one interval on is no witness (30 frames with the warning when the top line is once an interval, 15 frames and one cycle when twice an interval); a still cue (range far under half a tone) or one flickering every 4 frames refuses nothing, letting the body decide (twice an interval: one cycle of 15; held still: 30 with the warning) on front diagonals with brief meetings, back diagonals where a pass can hide, and with no view where a pass can hide; andbob_wordon an interval of 15 frames for a body 100 rows tall says"cycles"with 3 rows either way every 7.5 frames, says null every 15 or 30 frames, and says null under the floors at 0.2 rows either way without readinghalforquarter(swingandrowsare the range ofoff_flow's line), while for a top line in whole rows on a picture held still or carried along an arc 24 rows deep, a cubic 48 rows either way, a sway 12 rows either way four intervals long, or a ramp of 6 rows over the clip, rising and falling twice an interval says"cycles"under every one, once an interval, or not at all, says null under every one, and not rising at all, on the still picture, the arc, the cubic or the ramp, the line left is underBOB_ROWS, andoff_flowover intervals of 15 and 17.5 frames takes a cubic flow out wholly and leaves a rise and fall once or twice an interval as it was (less its straight line) over the frames the interval fits about; - the walker seen from behind whose far foot hides (cycle 17.5 frames on ones, no view) and the front-diagonal walker whose near foot steps out (cycle 16,
--view front_diagonal), their bodies rising and falling twice an interval carried whole, feet and all: cut two intervals,unwitnessed, the warning; the bob'shalfis0.28or more and itsquarter-0.28or less (the top line alone rises and falls twice an interval), itsbody.shareis under0.3, and itswhysays its lowest row rises and falls with it; - the wide legs-alike side walker (46-frame cycle, its crossings its steps every 23 frames, a pass can hide), held still or rising and falling on its legs once a step, on a picture shaken up and down 3 px twice an interval (dy = round(3 sin(4 pi k / 23))): two steps, 46 frames,
unwitnessed, the warning; held still, its bob'shalfis0.28or more andquarter-0.28or less, and itswhysays its lowest row rises and falls with it; - the walker seen from behind (17.5, rising and falling twice an interval on its legs), its frames cut at the soles' row so the lowest row is each frame's last: two intervals,
unwitnessed, the warning,edgeover 0 and awhynaming the frame's last row; twice_an_intervalover intervals of 15 and 17.5 frames: a line rising and falling 3 rows either way twice an interval, with a rise and fall of 2 rows once an interval and a cubic flow 48 rows either way laid on it, reads 3 rows (within 0.15); the same rise and fall on a constant reads within 0.15 of it; 14 frames over an interval of 15 read None;bob_wordover an interval of 15 frames, the body 100 rows tall, its lines in whole rows: a top line rising and falling 3 rows either way twice an interval with the lowest row still says"cycles"(shareover 0.9,scale1); the same rise and fall with the lowest row rising and falling with it (the body carried up and down whole, or held still on a picture shaken twice an interval: the same lines) says null, itswhynaming the lowest row; a rise and fall of 3 rows of its own on a picture shaken 12 rows with it (its own a fifth of the line's, underBOB_OWN) says null;bob_word: the body zoomed in and out twice an interval with the picture about its feet (3 % either way: the top line 3 rows, the lowest row still) or about its middle (6 %: the top line and the lowest row 3 rows either way, turned over from each other), its upper body's width and height scaled with it: null,scaleunder0.6, itswhynaming the upper body's width;bob_word: the planted rise and fall says"cycles"; the same with the lowest row on the frame's last row in one frame of 73 says null,edge1,why"in 1 of 73 frames";- read off drawn frames with
legs.strike_signalsandlegs.body_signals: five walkers that do not rise and fall twice an interval on their legs (the wide legs-alike side walker, interval 23, held still, carried whole bobbing once a step, or rising and falling on its legs once a step; the walker seen from behind, legs alike, interval 17.5, held still or carried whole rising and falling twice an interval), each moved up and down with the whole picture 3, 6 or 12 px either way every d/4, d/2, d or 2d frames (d its interval) at four phases: none is witnessed. Three of them (the side walker held still and on its legs, the walker from behind held still) zoomed in and out 0.5, 1, 2 or 4 % either way every d/4, d/2 or d frames about the feet, the middle or the head, at two phases: none is witnessed; - the wide walker, its head's top flat, round, pointed or two ears' tips, held still or rising and falling on its legs once a step, zoomed in and out 4 % either way with the picture about its feet, middle or head every quarter, half or whole cycle (11.5, 23 or 46 frames): never two steps an interval of a step (23 frames), nor a cut of a step said to be a cycle or two, nor a cut of two cycles (92) said to be one; cut through the loop, the walker with a pointed head or ears zoomed every quarter cycle (11.5 frames), and the walker with a pointed head held still zoomed about its feet twice a step, are never cut half a cycle unnamed;
- a top line rising and falling twice an interval on legs whose feet stay on the ground witnesses two steps an interval on a body whose sides run straight down; on a cone from a point at its top (where a zoom would move no band a pixel) or where any band of its upper body moves on the beat: every band widening and narrowing 2 px either way twice an interval a quarter of the beat on, with or without the band across its head's top holding still, is held by default, the word saying why ("its upper body's width changes with it"); with every band holding still the word says "cycles";
- the walker seen from behind whose far foot hides (17.5 on ones, no view) and the front-diagonal walker whose near foot steps out (16,
--view front_diagonal), rising and falling 3 px on their legs once a step as the walkers cut one cycle do, their arms swinging 16 px either way of the body's middle, past its sides: cut two intervals,unwitnessed, the warning;body.less_lowestat leastBOB_OWNofbody.beat,body.scaleunder0.6, the largest bandreadsover0.4,still_bandsfewer than the bands seen, and the why naming the upper body's width and that the picture may zoom with the body. - the walkers the tests witness, or whose cut the cut's witness reads one step, drawn instead with their arms swinging 16 px either way of the body's middle, past its sides (nineteen forms,
PAST_ITS_SIDES): none is a silent half cycle. A walk whose feet meet once a cycle (the walker whose far foot hides, 18.5 frames on ones, 20 on twos and 24 on threes; the same with its legs drawn alike, 17.5 and 20, with no view and with--view back_diagonal; the front-diagonal walker whose near foot steps out, 18,--view front_diagonal; the walker whose far foot hides, legs alike, carried along the arc and the cubic; the same walker turned 15 degrees about its feet over the clip) is cut two intervals,unwitnessed, the warning, its bob'swhynaming the upper body's width. Any other cut is held as chosen (cut_witness.held"unwitnessed", its word null, the warning): 46 frames for the wide walker with its far leg four tones off (--view sideand--view front_diagonal), 23 for the sliding foot and for the walker held still over a shadow on a picture shaken twice a step, 30 for the limp, and a cycle for the walks on a picture swaying once a cycle or slower. - the wide walker held still on its legs, zoomed in and out 4 % either way with the picture about its feet twice a step (every 11.5 frames), its head drawn narrower as the picture zooms in, and the body under it swinging on the beat: its torso's half width 4 px either way a quarter of the beat off the zoom, in step with it, or against it; or a crown 13 rows deep drawn narrower as the picture zooms in over a cape widening and narrowing 4 px either way a quarter of the beat before the zoom: cut through the loop it is held (
unwitnessed), never cut 23 frames (half a cycle) as two steps unnamed; read off its frames at an interval of 23, its top line rises and falls twice an interval (halfat leastBOB_TWICE,quarterat most-BOB_TWICE), at least one band holds still on the beat, and the word says null, its why naming the upper body's width. - read off 128 drawn frames at an interval of 16, a column 20 px wide on feet planted at row 140, its top rising and falling 3 rows either way twice an interval, its crown (11 rows) and the column under its shoulders holding still, and its shoulders (the 41 rows under the crown) widening and narrowing 2 px either way a quarter of the beat on: five bands are seen, one holds still and four move on the beat, and the word says null, its why naming the upper body's width.
- the side walker rising and falling on its legs once a step (its crossings its steps), running: both soles lifted up to 1, 2, 3 or 6 px off the ground while the body is high; still or on a picture moved 6 px either way every d/2 (two phases) or every d frames: never witnessed;
- the side walker drawn as a view from behind or a diagonal draws feet, each sole up to 6, 12 or 24 px lower the further back its foot is, the foot moving forward lifted 8 px (the lowest row is the planted foot, sliding down the screen through its step); still, or on a picture moved 3, 6 (four phases) or 12 px either way every d/2 frames, or 6 px every d: never witnessed;
- synthetic start-stop clips with feet together for 15 frames at the head and 14 at the tail alongside passes of 8 and 3 frames flag retakes when the cut is uncertain, omit retakes when counted as two steps, and report no
standswhen feet only pass. cut_wordunits on a cut 16 frames long with a body 100 rows tall on feet that stay on the ground report "two steps", "four steps" (on.interval8), "one step" (on.interval32), and null as its top line rises and falls 3 rows either way every 8, 4, or 16 frames or is held still: both lines say the word,byis both lines; where null, each line's why is inwhy.- a record held on one step with no
byorlines(built fromcut_word's record of a top line rising and falling once in a cut 16 frames long, its reading over the feet kept at its top) is refused by name, aValueError, throughheld_verdictand throughstep_verdict; the same with nothing read (saysnull, its why kept) gives one warning naming its why andcycle-unwitnessed. - a unit with the body on a picture moved 3 rows up and down twice an interval of 15 frames and a translucent shadow fixed on the screen as its lowest solid row yields
saysnull with "its lowest row rises and falls with it" when read against the lowest opaque row, and reports "cycles" with the lowest opaque row where the lowest solid row is. - the shadow walker: through the loop it is drawn with its arms swinging past its sides, leaving the step count no feet to read so the search cuts 23 frames, held at 23 and named with null whether it rises and falls on its legs or is carried whole; drawn with its arms within its sides and read off its frames (
cut_wordon the cut's length), the word says "one step" when it rises and falls on its legs and null when carried whole; so drawn, the loop refuses it: its wrap jumps (the seam ratio over 2.0), as it does where the walker is held still on its legs. - the same walker swinging its arms within its sides with each sole drawn up to 12 px lower the further back its foot is and the foot moving forward lifted 8 px has the step count count the search's 23 frames as two steps, returning "one step", held and named.
- the same walker over a shadow fixed on the screen apart under its feet on a picture shaken 12 px up and down every half step counts two steps by the crossings with a cut of 14 frames or under, held and named.
- the same walker on a picture moved 12 px up and down every two thirds of a step has the search cut 16 frames or under, held and named.
- the same walker swinging its arms within its sides held still on its legs over a shadow fixed on the screen touching its soles on a picture shaken 6 px twice a step reads no feet, cuts 23 frames; on the screen its top line rises and falls twice the cut with the picture (
halfat leastBOB_TWICE,quarterat most-BOB_TWICE), and its lowest opaque row (the feet's) with it, more than the lowest solid row (the shadow), its why saying its lowest row rises and falls with it; over the lowest opaque row (oversole) its top line holds still (underBOB_ROWSrows: "does not rise and fall"); neither line witnesses the cut, and it is held and named (read over the lowest solid row alone, the shadow holding still, the picture's shaking witnesses "two steps" with every band of its upper body holding still on the beat). - a walk rising and falling on its legs once a step, swinging its arms within its sides, its feet on the ground, on a picture swaying up and down once a cycle or slower (the wide walker with its legs drawn alike, crossings every 23 frames, a cycle of 46 frames, the picture swaying 12 px either way every 46 frames or 24 px every 69 frames; and the walker whose far foot passes hidden, 20 frames a cycle on twos, the picture swaying 24 px every 40 frames, up first) is cut one cycle, its cut witnessed
"two steps"by the line over its feet (byincludesfeet), read overreachorsole, not held, no warning (read on the screen alone, the sway hides the body's rise and fall twice the cut, and the cycle would be held). - the walker whose far foot passes hidden behind the near one, its legs drawn alike, its feet meeting once a cycle (17.5 frames), rising and falling on its legs once a step, turned 15 degrees about its feet over the clip (k/72 of it in frame k, on a canvas 60 px taller above and below: a lean changing slowly on its feet), swinging its arms within its sides: it cuts one cycle (within 1 frame of 17.5), the count reading its crossings as cycles (
cyclestrue,steps: 2); on the screen the top line, less its flow, rises and falls of its own twice the cut, every band of its upper body seen holding still on the beat: the cut's witness says "two steps", the screen among the lines that say it (by), not held, no warning; read off its frames on a cut of 18, the line over its feet says null: it does not rise and fall twice an interval (the lean tilts the ground under the feet, and the line over them takes in the two feet's heights by turns), where the line on the screen says "two steps" (bythe screen alone). - a side walker whose legs four tones apart tell its steps apart on a 30-frame cycle, swinging its arms within its sides, filmed 100 frames, with its body sinking 3 px once a cycle and not at each step (a limp) is cut 30 frames by the search, two steps by the crossings, returning "one step", held and named, and is never cut 60 frames long.
- the legless body bouncing every 16 frames: the search cuts one bounce (16 frames, within 1) and the cut stands as cut, never cut again two long; it squashes as it bounces, so its upper body's widths, read on rows below its top, change with it on that beat: nothing witnesses the cut (
saysnull), and it is held and named; read on twice its cut, its top line rises and falls twice that interval and the word says null, its why naming the upper body's width. - the walker seen from the front whose feet stay apart (stepping foot drawn up to 3 px under the ground, the other as far over it; right foot swinging in to meet the left only while it is drawn higher, the other foot drawn lower and nearer the viewer, and back out before it is drawn lower; no foot standing on the ground sliding along it; arms swinging within the body's sides; body not rising and falling), 20-frame and 24-frame cycles,
--view front: cut one cycle,steps2,cycles.order.says"two steps", zero slides, travel underORDER_TRAVELof spacing, body word null,cut_witness"two steps" by["order"]; with--view side: cut two intervals,cut_witness.held"unwitnessed", no order read (previously cut two intervals with a warning). - the walker from the side with legs drawn alike (46 frames, swinging leg lifted 6 px at pass) with no view and with
--viewfront, front_diagonal, back, and back_diagonal: cut 46 frames,steps2; crossing check hascyclesfalse,order.whyvalue stating a foot passes under the body; cut never stands on order. - the walker whose feet stay apart (cycle 30) tested across spans in
local_cycle.order_word: spans of 30, 60, and 15 frames,saysvalue "two steps", "four steps", and "one step", span 22 none, also checking that no foot slides and that the upper body's sway stays underORDER_SWAYof the tilt; picture rocked 10 degrees either way about feet once a cycle, feet drawn level and still,saysnull,whyvalue stating it may rock on its feet; the same walker drawn with its right foot sliding along the ground, planted, to meet the left as both stand level and back out,saysnull,whyvalue stating a foot slides (the order is not read where a foot on the ground passes under the body toward the other side); lifted-foot side walker with legs 5 and 10 px either side of line,saysnull,whyvalue stating a foot passes under the body; rear walker with soles on one row,saysnull,whyvalue stating feet are drawn level. - the walker whose feet stay apart cut 20 frames,
--view front, underloop._witnessed: cut stands on order,by["order"]; with step countdeclinedrecord set: cut held,cut_witness.held"unwitnessed",order.read"two steps",order.whyvalue stating order does not stand a length the closing refused. - the walker seen from the front whose feet stay apart (cycle 30 frames, body still), its feet meeting on the screen once a cycle, or once a step where
each_stepis set (the left foot swinging in to meet the right while drawn higher), drawn with a tail (_dipping_tail: from the hip to a tip 28 px to its left, rising and falling 8 px either way on a 17-frame beat of its own, dipping into the foot band about a third of the time, never as low as the feet nor over a column they stand on):order_wordover 30 frames (meeting once a cycle) says "two steps", over 15 frames (once a cycle) and over 15 frames (once a step) "one step", what the same walker drawn without the tail says, never "two steps" where the walker holds one, withoff_groundexactly the frames whose left side is the tail and no counted change falling on them (before: the tail's frames were read as feet, and over 30 frames the walker meeting once a cycle said nothing). - the 46-frame side walker lifting its swing foot 6 px, drawn with the tail 40 px behind:
off_groundis the tail's frames,saysis null and its why says a foot passes under the body (before: null as well, the tail's frames read as feet). - slow test of the walker meeting once a step with the tail,
--view front: its crossings are never read as cycles, the cut witness stands a cut on the order (by["order"]) only where the cut is within 1.5 frames of the 30-frame cycle, and no cut under three quarters of the cycle is handed out without a warning naming it (before:video-loopstopped on the division by zero). - the walker meeting once a cycle (cycle 30, body still, no tail):
cut_wordreturns on every cut length from 10 to 46 frames; on cuts of 25, 26, 34 and 35 frames it says null with a why containing "its top line holding still" (before: it stopped on cuts of 13, 17, 25, 26, 34 and 35 frames).
- a walker seen from behind whose far foot hides behind the near one (feet together over half the interval) across cycles of 20 frames on twos, 24 on threes, and 17.5 and 18.5 on ones: its top line rises and falls twice an interval, cutting one cycle within a frame with
- Tests:
tests/video/test_gait_guard_anchor_wide.pyandtests/video/test_cycle_align.pycover batch anchoring and cycle alignment:batch.anchor_forassignsmotion-autoto walk and run loops while assigningnoneto cheer, walk with--anchor none, and pinned idle items, propagating loop retakes to item records, warnings, and markdown tables;batch.align_gaitsexcludes loops with astart-stopretake, a loop withcycle-unwitnessed, or a loop with both, names its reasons underleft_out(["start-stop"],["cycle-unwitnessed"],["start-stop", "cycle-unwitnessed"]) and in the stderr warning, aligns remaining directions, and leaves the state unaligned when fewer than two directions remain.batch.align_gaitswith three directions, two loops of one cycle (20 and 24 frames) and one loop of two cycles (40 frames) whose strip sayssteps: 2and whose cut witness says four steps: the two-cycle loop is left out underleft_out(["cycle-four-steps"]) and named in the warning, its loop and strip kept as cut (40 frames,steps: 2), and the other two are aligned to their median length.- three walker loops with reports beside them, the third loop marked held (
cut_witness.held"unwitnessed") or four steps (cut_witness.says"four steps", stripsteps: 2, walker two cycles long): standalonevideo-cycle-alignstops with one suspect,heldvalue{reason, report},settlevalue=1and=2, nothing rewritten;--multi-cycle warnaligns and names reason;--cycles1 or 2 aligns it, suspectstatus"counted" (previously aligned as one cycle without a word).
- Tests:
tests/video/test_one_step_cut.py: a side walker whose cycle (42 frames) the walk window cannot hold is cut one step long (21 frames) by the pixel search, its feet read as unseen, and the step screen names it; before, the test said nothing else speaks (nostepsand no warning about steps), whereas now there are still nosteps, the walker is carried whole on its legs, so its cut witness holds the cut (cut_witness.heldis"unwitnessed",local_cycle.unwitnessedis true), and the one warning that speaks of steps is the witness's (local_cycle.held_verdict), namingcycle-unwitnessed. In a set of two items, the same walker on a 25-frame cycle (front, cut a whole cycle) and the one-step side walk, their rows now carry the marksrun_setrecords (cycle-unwitnessedfromlocal_cycle.unwitnessed, andstep_screen) instead of rows built without them; both are left out of the alignment (left_out["cycle-unwitnessed"]each,why: "fewer than two directions left to align"), each warning says nothing witnesses its cut whole cycles and it may hold half a cycle or two, only the side walk's warning adds that it may be one step (cut it again withvideo-loop --steps 1if it is),video-cycle-alignrun on the items' loops reads the step screen in the report beside the side walk's loop and stops on it (one_step), naming--steps 1, and the set table still marks the side walk's cycle(one step?). The walker carried whole on its legs across the two set tests:video-cycle-alignnow stops on both loops, each namedheld,reason"cycle-unwitnessed", the side loop also suspected one step; a count of one cycle for each settles it. - Tests:
tests/video/test_cycle_suspects.pyandtests/video/test_loop_prop_seam_held.pycover standalonevideo-cycle-alignon loops whose cut reports hold their cuts:- three synthetic loops in
tests/video/test_cycle_suspects.py(S and E one stride of 24 frames each, NE two strides of 15 frames, 30 frames held on twos, as a two-cycle cut leaves it, with NE's cut report beside it asvideo-loopwrites it holding its cut because nothing witnesses it whole cycles): stopping the set, run twice, names NE with its report beside it both for what the report holds (held, reasoncycle-unwitnessed, with the report's path: it may hold half a cycle, one or two, and the message namesvideo-loopto cut it again if it is one step) and for its return at 15 frames (it may also hold 2 cycles of 15 frames), while with the report removed (a loop cut by other means) it is named only for its return with noheldand no mention ofvideo-loop, both offering settle=1and=2with nothing rewritten (previously one run, NE named only for its return, and the message never namedvideo-loop);--multi-cycle warnaligns the set as it is, NE's warning starting with nothing having witnessed its cut whole cycles and adding that it may also hold 2 cycles (previously the warning started with it may hold 2 cycles); the command line (align.main) without a count exits naming the held cut and the return at 15 frames, and with--cycles NE=2aligns as before (previously the exit named only the return). - two synthetic loops in
tests/video/test_loop_prop_seam_held.py(one cut two steps long, one cycle, stripsteps: 2, and one cut one cycle with nosteps, neither walker's body rising and falling and its feet never passing, so both reports hold their cuts, nothing witnessing either whole cycles): on copies whose reports the test rewrites to witness their cuts (cut_witnesssaying "two steps" by the screen, nothing held), the aligner works as before: the two-step loop returns half way at its second step, which is no suspect (status"steps",steps2, candidates[2]), and both loops are resampled to the median of their lengths as cut, nothing kept twice as long, the strip of the two-step copy still sayingsteps: 2, the other none; on the loops as cut,video-cycle-alignstops on both, each namedheldwith reasoncycle-unwitnessed; a count of one cycle for each (cycles, the caller's word) aligns them as they are, to the same median length, each suspectstatus"counted"; a count of 2 for the two-step loop (and 1 for the other) still takes one half out of it, and its strip no longer sayssteps; two copies of the loop with no held part, aligned with a count of one cycle each, are written as before: nocycles_keptand nostepsin their rows, their strip metadata with the same keys, and the cut's source (source_cut) as the cut wrote it (previously both aligned with no count, the two-step loop's return read as its steps). - the synthetic cut of 13 cells with its record of its cells, aligned by
video-cycle-alignto 17 cells, intests/video/test_sway_read_on_recut.py(with--between rife(a blend standing in for RIFE) the aligned strip record holds nocell_record,cycle_align.cells_fromgives 17 cells, each{"source": i}cell is cell i of the cut pixel for pixel and each{"between": [i, j], "t": t}cell is a copy of no cell of the cut,cycle.source/run.strip.jsonis the cut's record with 13 cells, source frames 1 to 13, andvideo-sway --read-on-cutis refuseduncertainon the pair the kept record gives (source frame 4), naming the first made cell, the loop as it was; with--between nearestevery one of the 17 cells is one of the cut's, and--read-on-cutpairs source frame 4 with the cut's cell 3 at shift (3, 2) and carries it through,cut_cellsequal to thecells_fromsources).
- three synthetic loops in
Contract strings
- Internal: one declaration per contract string: a key, kind, mode, provider name or key colour that two or more places write, read or branch on was spelt again at each place, so a one-letter typo passed every test (for example the curation server's
extractOkspeltextractOKmade the curator warn on every row with the suite green). Each is now declared once and every use names it:- curation and composer servers: every key of the JSON the curator and composer read, in
serve_curation.Wire(112 keys and theX-Filenamedownload header) andserve_compose.Wire(16 keys, plusTYPE_DIR,TYPE_IMAGE); the heal report and progress file keys inframes/extract.py(HEAL_*,PROGRESS_*,PROGRESS_PHASE_COMPONENTS);curation.CURATION_KIND,REF_ANCHOR,REF_BASIS,REF_GUIDE,BREATHE_PIXEL,BREATHE_SMOOTH. - image provider names
PROVIDER_CODEX,PROVIDER_GROK,PROVIDER_OPENAIingen/base.py, withgen.PROVIDERSand the other provider sets written with them; the curator's two buttons gated by one set,serve_curation.CURATOR_PROVIDERS; the reroll default isgen.HARD_DEFAULT_PROVIDER; the interpolate default isinterpolate.DEFAULT_PROVIDER(codex, its own documented choice from the three-way comparison); the HTTP host namesaddress.OPENAI,XAI,ANTHROPIC,ELEVENLABS;retry.ELEVENLABS_BUSY;audio.manifest.KIND,SFX,BGM; the workflow guide's journey, field and access names inworkflow/catalog.pyandworkflow/access.py;video-prompttakesgen.video.DEFAULT_MODELinstead of a second copy; the choice to stop and ask when codex cannot run isgen.CODEX_UNAVAILABLE_ASK, whichgen.CODEX_UNAVAILABLE_CHOICES,gen.CODEX_UNAVAILABLE_DEFAULTand the workflow catalogue read; the guide reports that choice undergen.CODEX_UNAVAILABLE_SETTING, the name it is saved by;xai.AUTH_SOURCE_API_KEYisxai.AUTH_ENV;claude_login.CHILD_DROPreadsanthropic_api.AUTH_ENV; the codex binary's name iscodex_provider.BINARY;pixel_draw.EFFORTSisanthropic_api.EFFORTS, the copy removed. - key colours and modes:
cutout.KEY_TARGETSwithMAGENTAandGREENbeside it is the one table of key colours (gen.chroma.KEYSis built from it,logo_matte.KEYSis it,slice_sheet.CHROMA_KEYSis removed, the hex values inprepare,unpack-atlasand the curation server are derived from it);cutout.KEYSis cutout's own--keyset;OFF, AUTO, PALETTE = DECONTAM_MODESandCHROMA_RGB, CHROMA_YCBCR = CHROMA_MODESare declared inframes/extract.py, andframes.decontam.DECONTAM_MODESandvideo.frames.DECONTAM_MODESare that same tuple; every--decontam,--chroma-modeand--keychoice reads its declaration;logo_matte.LETTERING_BOX,UNMIX;prompt_parts.CONFLICT,REPEAT;gen.chroma.KEY_BACKGROUND_TEXT,gen.logo.KEY_COLOUR_WORDSand a scene report'skey_like_pixelsare keyed bycutout.GREENandMAGENTA;prop_plate.RGBreadsKEY_TARGETS[MAGENTA];video.frames.DECONTAM_DEFAULTisextract.AUTOand video-frames' decontam branches readOFF,AUTOandPALETTE;video-frames --alpha-modereadseffect.ALPHA_MODES; themethodagen.chromareport states readsextract.CHROMA_YCBCRandbase.TRANSPARENCY_NATIVE. - kinds:
loop.REPORT_KIND,loop.REPORT_PASSED;spec.assets.ASSET_KIND,SET_SHEET_KIND(set_sheet.KINDnames it);qa.motion.REPORT_KIND;video.evidence.SOURCE_KIND;nonloop.GAIT_STATES(the copies inqa.handedandvideo.batchremoved);body_plan.BIPED,QUADRUPED,LEGLESS;effect.STATEread byvideo-setandvideo-prompt;pixel_gates.SPRITE,ICON,TILE,EFFECT(pixel_draw.KINDSis that tuple); new namesspec.runio.REQUEST_KIND,video.frames.REPORT_KIND,video.align.REPORT_KIND,unpack_atlas.UNPACK_SOURCE_KIND;video-canvaswritesprop_plate.CANVAS_REPORT, the name the report is read by; thekindof a pixel-draw effect strip ispixel_gates.EFFECT; avideo-cycle-alignsame-foot refusal statesalign.RETAKE_FEET_REASON. - other copies:
sprite-request.jsonandcuration.jsonare read asrunio.REQUEST_FILENAMEandcuration.CURATION_FILENAMEeverywhere they are written, opened or checked;pixel_grid.PNG_MAGICisbase.PNG_MAGIC;restoration.ARTIFACT_SUFFIXESis the one table of a restoration's five files (restoration.ARTIFACTSis its keys, the demo script reads it);game_pack.SIDESisui_kit.SIDES;video-canvas --facing,video-loop --facingand a lateral view's check ingen.handednessreadgen.facing.FACINGS;effects.breathe.SIDE_NAMESis keyed byextract.FRAME_SIDES. - Values that no test bound before and that now cannot drift: the legless anatomy sentence key,
effectinvideo-set's states pinned to their first frame, the pixel-draw pick sheet's tile branch, the loop report kindvideo-cycle-alignreads (its typo passed the fast bundle).
- curation and composer servers: every key of the JSON the curator and composer read, in
- Python callers: every name above is importable. Downstream imports keep the same objects:
sprite_gen.video.frames.DECONTAM_MODES,sprite_gen.frames.cutout.KEY_TARGETS,sprite_gen.gen.chroma.KEY_BACKGROUND_TEXT,set_sheet.KIND,pixel_draw.KINDS,batch.GAIT_STATES. Removed:slice_sheet.CHROMA_KEYS(usecutout.KEY_TARGETS).clip_prompt.DEFAULT_MODELisgen.video.DEFAULT_MODEL, imported (the same object).qa.handed.GAIT_STATESis now a frozenset (was a tuple); every use is a membership test.sprite_gen.frames.cutoutnow importsframes.extractwhen it loads (for the decontam defaults), so importing it loads more modules than before;pixel_draw.EFFORTS,game_pack.SIDESandpixel_grid.PNG_MAGICstay importable as the same objects;loop.FACINGSis removed (usesprite_gen.gen.facing.FACINGS). - Curator: the JS mirror
BREATHE_MODESmoved fromstore.jstobreathe.js, withBREATHE_SMOOTHbeside it;gen-trigger.js's provider select mirrorsserve_curation.CURATOR_PROVIDERS. No screen changes;BREATHE_ROUND_KEYSmoved fromstore.jstobreathe.js, beside the refusal that spelt the two keys. - Tests: new
tests/serve/test_curator_wire_keys.py: every key the curator and composer read is found in the scripts with the object it is read from, built from the declared value; every declared key is read or listed as unread, the unread ones spelt out in the test; the servers write no wire key, and send no header the curator reads, as text; everyWire.Xthe servers name exists.tests/serve/test_curation_view_contract.py: the reroll and interpolate buttons followCURATOR_PROVIDERSand their declared defaults, and node runsgen-trigger.jsto hold its select toCURATOR_PROVIDERSin order.tests/effects/test_breathe_sidecar_roundtrip.py: the curator's save payload kind isCURATION_KIND.tests/frames/test_cutout.pyandtests/frames/test_chroma_decontam.py: every key table is the one table, every--key,--decontamand--chroma-modeflag reads its declaration,cutout.KEYSpinned as written.tests/gen/test_codex_unavailable.py(the codex-unavailable choices in order),tests/gen/test_openai_provider.py(adapter names equalgen.PROVIDERS),tests/audio/test_sound.py(the two ElevenLabs busy codes),tests/workflow/test_capabilities.py(the video model default),tests/gen/test_prompt_assembly.py(a repeat note's kind). The two absence guards that searchedserve_curation.pyfor a key's spelling (tests/serve/test_pixel_grid_always_available.py,tests/curate/test_logical_height_contract.py) now search for its name; with the old spelling they would have passed while testing nothing. Red first: at 3.10.1 the new binding tests fail (for example the wire-key test finds 217 keys written as text inserve_curation.pyand 55 inserve_compose.py; 8--decontamparsers held their own copy;video-set's--keywas a copy). Mutation check: one character changed in a declared value fails a test in every family; before, 16 of 25 sampled curation key changes, the provider adapter name, either ElevenLabs busy code, the video model default and the loop report kind under the fast bundle left the suite green.tests/frames/test_cutout.py(no table in the package keys a key colour by its spelling (an AST scan ofsprite_gen)),tests/gen/test_codex_unavailable.py(the guide reports the codex choice under the name it is saved by),tests/gen/test_pixel_draw.py(the effort order is the API's),tests/compose/test_game_pack_v2.py(a nine-slice's sides areui_kit's),tests/gen/test_facing.py(video-loop --facingtakes the facingsgen.facingdeclares),tests/effects/test_breathe_reference_key.py(the JS frame sides and border share equalextract.FRAME_SIDESandBORDER_MIN_FRACTION),tests/spec/test_assets.py(the kinds written to disk are pinned as written),tests/gen/test_codex_login.py(the codex binary pinned as written),tests/video/test_source_restoration.py(a restoration's five file suffixes pinned as written).
v3.12.1 - A one-shot cut where no pair returns names its closest return, ratio and moved, and the report gains cycle.closest_return
Upgrading from 3.12.0: Thresholds, the search window, which clips are cut, and every cut's pictures and report values are the same as 3.12.0. Only the refusal text changes where no pair of frames returns, and --report gains cycle.closest_return. The refusal now names the closest return, its frames, its ratio of departure, and that pair's moved instead of reporting moved 0.00. Where a pair returns but what lies between is not an action, or where no pair departs at all, the refusal line is the 3.12.0 line as before.
- Fix: A one-shot cut where no pair of frames returns now names the closest return, its ratio and its moved instead of reporting
moved 0.00. In 3.12.0 and earlier, where no pair of frames returned, the refusal saidthe clip never leaves its rest pose and returns with observed endpoints (moved 0.00, need 0.4). The moved it reported was the largest moved among pairs that had returned, and because none had, it always read 0.00; a body that jumps across the canvas therefore read as one that never moved. Where no pair returns, the refusal now names the closest return: the pair of frames whose return distance over departure is the least of every pair the search read, that ratio, and that pair's moved. After the fixed prefix, the line isthe clip does not come back to a pose it left: the closest return, frames A-B, is R of its departure away, over 0.25 (moved M, need 0.4). On a synthetic leap whose body lands 240 px along a 360 px canvas, the new line readsframes 0-34, is 1.12 of its departure away, over 0.25 (moved 0.36, need 0.4). The report written with--reportgainscycle.closest_returnwith keyspair,ratio,seam,departureandmoved. Where a pair does return but what lies between is not an action (too little contrast or moved, fewer than four active frames, or a departure under three times the steps between its frames), or where no pair departs at all, the 3.12.0 line is printed as before. - Python callers:
loop.ONE_SHOT_RETURN_MAXnames the return bound (0.25). TheCycleSelectionErrordiagnostics ofdetect_one_shotcarryclosest_returnwhere some pair departed. - Docs: video-pipeline.md (section "One-shot actions") documents the return bound
ONE_SHOT_RETURN_MAX, the refusal line,cycle.closest_return, and cutting canvas-crossing jumps with--cycle once --start S --length Lfrom the closest return's frames.SKILL.mdupdates its single-play motion guidance with the same command and refusal quote. - Tests:
tests/video/test_one_shot_refusal.pyadds five tests drawn with rectangles and no real footage: (1) a leap whose body crosses the canvas is refused on its closest return, naming the pair with the least return over departure in the searched window and matchingclosest_returnin the report; (2) the same leap in place is cut from rest to rest; (3) in place, a take-off crouch and a landing crouch that are two different pictures, ending in the landing stance, is refused on its closest return; (4) a stand moved up to 3 px along and up or down every frame is refused across twelve seeds (the test runs one seed); (5) a clip that never departs is refused with the 3.12.0 line and noclosest_return. Red first: on 3.12.0, 2 failed and 3 passed (tests 1 and 3 refused withmoved 0.00); on 3.12.1, 5 passed.
v3.12.0 - Prop plate painted on the canvas (video-canvas --prop-plate) and erased from keyed frames (video-frames --prop-plate
Upgrading from 3.11.0: runs without the new options produce unchanged outputs: every canvas, frame, strip, GIF, WebP, and report keeps its exact bytes (with only the loop report's producer.implementation_sha256 changing with source code changes).
- New:
video-canvas --prop-platepaints a flat magenta plate, RGB (255, 0, 255), on the canvas in front of the subject (--facing) standing on the subject's foot row, sized bycanvas.subject_box(height 0.49, thickness 0.20, near side 0.84 of subject height ahead of the subject's front). Requires a green key and--report. Refuses non-green keys, missing--report, stateeffect, or plates extending past the canvas edge. The report recordsprop_platewithbox,rgb,subject, andof_subject_height. - New:
video-frames --prop-plate <canvas report json>reads the plate box from the canvas report, scales it outward to frame coordinates with a 3 px rim (erase_box), and erases the plate from keyed frames before handover. Pixels are erased where red and blue lead green by more than 35 and are within 90 of each other, or where each channel (including alpha) is within 40 of the whole-clip median. Refused runs keep the plate;video-loopcuts of erased frames carry no plate;video-setdoes not paint or erase a plate. The report recordsprop_plate. - Limits: the video model must keep the plate in place; a one-pixel shift leaves grey blend lines down the sides (188 and 95 pixels in synthetic tests). Subject edge pixels tinted magenta by the codec are erased (2 pixels in each of two frames in synthetic tests). No other guard, retry, or measurement is added.
- Python callers:
sprite_gen.video.prop_plate(place,paint,read,frame_box,erase; constantsRGB,HEIGHT,WIDTH,GAP,RIM,MAGENTA_LEAD,MAGENTA_BALANCE,STILL_TOLERANCE);canvas.run_canvas(..., prop_plate=False);frames.run_frames(..., prop_plate=None);frames.key_frames(..., plate=None). - Docs: video-pipeline.md section 1 subsection and section 3 pointer;
SKILL.md;docs/README.md. - Tests:
tests/video/test_prop_plate.py(12 synthetic tests: canvas painting facing right and left, unchanged canvas without option, refusals for bounds, key, and report, frame erasing, one-pixel model shifts, subject crossing preservation, frames outside the box, erase reading the canvas report box, refusal for report without plate or not a canvas report, frame box arithmetic, loop cuts without magenta). Red first: median without alpha lost 47, 47, 136 and 136 outline pixels in frames 8 to 11; with alpha, 2, 2, 0, and 0 codec-tinted pixels. Mutation check: median without alpha fails test 7; no magenta rule fails tests 6 and 12; no median rule fails test 6; rim 0 fails three tests; unscaled box fails two.
v3.11.0 - Sway regions laid over the figure (--region-over), rims widened for shear (--region-shear), figure membranes (--region-membrane), and recut strip pairing by cell records (--read-on-cut)
Upgrading from 3.10.1: video-loop writes cell_record into every strip record <name>.strip.json, and video-sway gains options that shape a --region-mask region alongside --read-on-cut. Strips, frames and records keep their bytes by default, but video-sway --read-on-cut reads cuts by that record alone and refuses cuts made without it. New options --region-over and --region-shear shape the region mask and its rim; both are off by default, and when not given, strips, frames, and records remain byte for byte what they were. With --region-crease the wear wears the crease in as before; laid over the figure the region reaches down to the crease again in every cell, changing those runs' output. Runs with --region-over and runs with --region-membrane draw differently than in 3.10.1; the four new membrane options are off by default and byte for byte as before when not given. New options --region-over-solid, --region-rim-round, --region-membrane and --read-on-cut are off by default; when not given, strips, frames, and records remain byte for byte what they were. Runs with --read-on alone behave as before, except that its no-match message now names --read-on-cut. The refusal for --region-over or --region-shear given without --region-mask keeps refusing the same runs, and its message now names the new options too: "--region-over, --region-over-solid, --region-rim-round, --region-shear and --region-membrane shape a region mask; they need --region-mask" (it was "--region-over and --region-shear shape a region mask; they need --region-mask").
- New: laying a region over the figure and widening the rim for shear (
--region-over,--region-shear).--region-overlays the region over the figure under it instead of pinning its lower edge, freeing held pixels under the edge (solid or not), moving the band within reach, drawing the layer over the band by alpha, drawing the air by the move, and showing the figure under its lower edge at the move where it lifts. Its soft edge moves with the region (except under the lower edge where touching a solid pixel outside keeps it in the band), its solid outline against air goes with the layer, and--hold-maskleaves pixels the region mask does not cover out of the layer and band while pixels it covers move with the region.--region-shear Swidens the rim across and down so a move one way rises across the rim the other way by at most S px per px (shear_floor), preventing tears along the sides. With either option, the ledger records move steps between neighbouring pixels, still strips left standing, and tip outline shapes, and--region-overrecordslifted_px. Both require--region-mask, are off by default, and leave strips, frames, and records byte for byte what they were when not given. See video-pipeline section 6. - Changed: wearing the crease row in like every other edge of the mask and reaching down to the crease only when laying a region over the figure (
--region-crease,--region-over). Removed: the step that filled each crease column back down to the crease row after the mask was worn in (crease_keptis gone). Now--region-creaseends the mask on the crease before the wear and the wear (--region-shrink) wears the whole mask in, the crease row too, like every other edge. So the record'smask.boxends--region-shrinkrows above the crease row (2 rows at the default), as it did beforecrease_kept. New, under--region-overonly: in every cell the region reaches down to the crease again (crease_reach): the crease's rows (its columns and rows on the cell the mask was drawn on; a column between two crease columns takes the nearer one's row, the left one's on a tie) are carried into the cell by the mask's carry there (the column rounded to the nearest, half to even; the row rounded down), and in each crease column where the region holds a pixel, the cell's solid pixels from the region's lowest pixel down to the crease's row join the region. The crease is the picture's own edge, so the layer reaches it in every cell while the wear still wears the mask in everywhere else. Without--region-overnothing reaches back down: the worn mask is the region. - New: solid under-edges, round rims, figure membranes, and recut strip pairing (
--region-over-solid,--region-rim-round,--region-membrane,--read-on-cut).--region-over-solidfrees only solid pixels (alpha 128 or more) under the lower edge into the band while keeping softer pixels as anchors, and carries the region's soft edge with it under the lower edge.--region-rim-roundholds the rim round beside the region across the wider of its two widths (max(Lx, Ly)), preventing steep downward steps below corners where the lower edge runs lower.--region-membrane Nmoves the figure under the lower edge within N + 1 px as a membrane by solving 4-neighbour figure means in passes instead of conjugate gradients (from a cos² start, at most 1200 passes, leaving no piece out) so the figure stretches rather than slides, drawing membrane pixels by their move and reporting membrane-specific fold refusals.--read-on-cut STRIPpairs regions read on another cut of the same clip by matching source frame numbers and applying a whole-pixel shift across crops on unaligned and aligned loops alike. The shift is taken on the frame as filmed, less where each cut's body or motion anchor moved that frame. Each cut is now read by its record of its cells alone:cell_recordin the strip's record (<name>.strip.json), whichvideo-loopnow writes, bound to the strip bycell_record.strip_sha256(the sha256 of the strip PNG), with one entry per cell:source_frame,anchor_move_px(where the anchor moved that frame before the crop, whole px across and down),scale(size_holdandgait_fallback: the factor each step that holds a clip's frames to one size scaled that frame by, 1 where it did not hold them) andas_filmed(true where the cell's pixels at the end of the cut are its pixels anchored before any repair, the receiptsource_projection.before_repair_pixels_sha256in the cut's report, and no step held the clip's frames to one size). On a loop aligned from its cut it reads the cut's own record, whichvideo-cycle-alignnow keeps beside the cut's frames as filmed (cycle.source/<name>.strip.json) and which must be bound to the strip the alignment's origin names (cycle_align.origin.strip_sha256). It refuses, no-match, saying which and naming the field: a cut with nocell_record(any cut made before this release), a record bound to another strip, a record that does not give its cells asvideo-loopwrites them (a field missing or not of its kind, in any cell), a loop aligned from its cut with no kept record, a paired cell a hold scaled or not cut as filmed, and two paired cells that are not the same pixels where they overlap at the shift (a record changed to call a cell as filmed is held to the cell's pixels). The report beside a cut is no longer looked for or read. All four options are off by default and leave strips, frames, and records byte for byte what they were when not given. See video-pipeline section 6. - New: the membrane's own keys (
--region-membrane-unpin,--region-clear-alpha,--region-floor-beside,--region-own-outline).--region-membrane-unpinmakes what the membrane moves no anchor of the rim either, so the region's move does not fall to none at its first rows under its lower edge.--region-clear-alpha A(a whole number from 1 to 127) reads a pixel under alpha A as clear by the sets the region moves and holds and by the membrane's figure while the cell's bytes stay its own, so a speck of dust beside the figure holds nothing.--region-floor-beside Nsets the lower edge beside the region's columns to the lowest pixel of its columns within N px of that side, not that of its nearest column alone.--region-own-outline Ggrows the region G 4-neighbour steps over the cell's solid pixels within G 4-neighbour steps of a clear pixel before the sets (never under its lower edge's line and never over pixels--hold-maskleaves out), moving the outline its carried mask leaves out with the region. All four require--region-mask, shape nothing without--region-membrane(leaving the same bytes and record, naming none of them), are off by default, and leave strips, frames, and records byte for byte what they were when not given. See video-pipeline section 6. - Output change:
cell_recordin strip records,source_projectionfor motion anchors, and kept cut strip records.video-loopnow writescell_recordinto every strip record it writes (the fields above). The strip PNG, the GIF, the WebP and the frames ofcycle/keep their bytes; the strip record gains this one key. A cut's report gainssource_projection(recipe,wrap_dx_px,before_repair_pixels_sha256) at--anchor motionand--anchor motion-autotoo, withrecipemotion-anchor-correction-v1there; it was written only at--anchor noneandbodybefore (unchanged there).cell_recordis written in the strip record only, not in the report's copy of it.video-cycle-align's first alignment of a loop now also writescycle.source/<name>.strip.json, the loop's strip record as cut, byte for byte, before it rewrites<name>.strip.json; later alignments leave it as it is, and a new cut withvideo-loopremoves it withcycle.source/. The aligned strip's record does not carrycell_record(it is the record of another strip). The pair policyRECUT_POLICYis nowsame-clip/source-frame/whole-px-shift/2. At--out-fps(3.8.0: cells each made at a time of their own, more cells than the cut has frames), and at--out-fpswith the air retimed, the report'sheld_fill.out_fpsgainssource_frames(per cell, the frame of the cut it is, or null where it was made), andcell_recordnow reads a retimed cut the same way as a cut at--out-fps:source_frameis the frame the cell is, and for a cell made between two frames the cut's frame at or before its time (the frame the seam reads it as), with that frame'sanchor_move_pxandscale.as_filmedis true only where the cell's pixels are that frame's pixels anchored before any repair, so a cell that repeats a frame unchanged is as filmed, and a cell made between two frames, a cell moved onto the parabola or along, and every cell of a cut the retime laid on a larger canvas are not as filmed, andvideo-sway --read-on-cutdoes not pair them. The cells before the take-off that the retime neither moved nor laid on a larger canvas stay as filmed. - Python callers:
sway_loop,sway_frames,read_requestandread_askacceptregion_over(bool; default False) andregion_shear(float; None: off). New insprite_gen.video.sway:shear_floor,layer_sets,lay_over,cover_depth,still_strip,tip_shapeandmove_steps; constantsOVER_POLICY,TIP_COLS,TIP_AIR,TIP_RING,TIP_OFFandTIP_SEARCH;RegionMaskgainsover,shear,holdandedges();Maskedgainssheared,left_outandleft_out_in(k);rim_bandsgainsfloor(None: as before). - Python callers:
sway_loop,sway_frames,read_requestandread_askacceptregion_over_solid(bool; default False),region_rim_round(bool; default False) andregion_membrane(int; None: off);sway_loopandread_requestacceptread_on_cut(Path; None: off, refused bysway_frames). New insprite_gen.video.sway:membrane_sets,membrane_move(free, figure, own, outline, move, reach),recut_pair,recut_askandread_cut; new insprite_gen.video.loop:ramp_offset; new insprite_gen.video.motion_anchor:laid_at; constantsOVER_SOLID_POLICY,MEMBRANE_POLICY,RECUT_POLICY,RECUT_DRIFTandRIM_ROUND_POLICY;RegionMaskgainsover_solid,membraneandrim_round;Requestgainsread_on_cut;layer_sets(..., solid_only=False)gainssolid_onlyand returns the new setbelow;read_on_relation(..., cut=False)gainscut; andtransported_motion(..., paired=None)gainspaired. New insprite_gen.video.sway:cell_record(record, strip_sha256)(the record of a strip's cells, a ValueError naming what it does not give),recut_same(pair, cut_cell, cell, read_on)(refuses two paired cells that are not the same pixels at the shift) andaligned_from(loop_dir, meta_path, meta)(the cut's record an alignment kept, or None);recut_pair(meta, cut, read_on, *, strip_sha256, kept=None)takes this loop's strip sha256 and the kept record;read_cutreturns the strip picture understrip;Requestgainsaligned_from; new insprite_gen.video.loop: constantsCELL_RECORD,CELL_SCALE_STEPSandMOTION_RECIPE. - Tests: new file
tests/video/test_sway_region_over.pycovers these cases on synthetic figures (the region test's body and its striped part over the torso's right side and past it over the air, with a dark crease under it on the torso; an arm block beside the part's lower left; a dark outline row under the part where it hangs over the air). Each case first reads what a sway writes with the new options (its cells, its record), so on a release without them the same input fails on what comes out:- without the new options nothing of them is read or written (cells and record as before, from Python with them passed off);
- with
--region-creasethe wear wears the crease in with the rest (the worn mask's lowest row on the torso 2 rows over the crease, its box ending there), nothing under the crease moves, and laid over the figure the region reaches down to the crease again in every cell (its lowest pixel on the crease's row in each crease column); - laid over the figure under it, the lower edge moves as much as the part above it does (at gain 2.5 and 1.25), while without
--region-overthe crease pins it; - the layer draws the band where it lands, no read of the move taken there, and keeps its bytes elsewhere; the move draws the air (reads are taken there); a read in the air that takes the held figure beside it (the torso's soft side past the band) is walked back, in the air alone and never on the band (4, 9 and 6 reads in three cells, none in the others); nothing outside the region, its soft edge, the air and the band changes; the layer covers no deeper than the band; nothing folds;
- where the part lifts it shows the figure under it: each pixel there is read at its whole move, none read short, its alpha the source's read there; read wholly on opaque pixels it stays opaque and shows the torso and the crease, not the stripes; beside the torso's soft side one column of the part's, within 2 px of that side, is as soft as its read of that side and the air past it (in 7 of the 12 lifting cells); in the rows the part leaves, its column over the torso's soft side shows thinner than that side in exactly the cells where the part moves toward the torso;
- its outline against the air goes with it and leaves the air behind, and its outline against the figure (the crease) keeps its bytes;
- two new cases for
--hold-maskwith--region-over: the pixels it names that the region mask covers (a piece in the arm's colour inside the part) are the region's, no anchors, and move with the part (one PNG carried and a folder per cell); the pixels it names that the region mask does not cover keep their bytes in every cell, and on a band (--band autowith the same--hold-mask) every pixel it names keeps its bytes while the part moves round them; - where the part lifts off a piece in the arm's colour right under its lower edge, left out with
--hold-mask, the part's reads that would take the piece are read from their other pixels (10 in every lifting cell), none of them lifted and all opaque: no hole opens and the piece keeps its bytes; --region-shear0.5 and 0.25 widen the rim to the least it asks, so the drawn move's step across the rim stays within the bound, and less than without it;- the still strip is read from the region to its side (beside the arm, the px the mask left short; over the air, 0);
- the tip is read on the side over the air; a tip moved whole is 0 px off its own shape, its shift found;
move_stepsreads the most step both ways where both pixels are shown;--framesgives the strip's cells and the same record;- each refusal leaves the loop as it was.
tests/video/test_sway_region.py's crease case now reads the worn mask's box ending 2 rows over the crease row.tests/video/test_follow_inspect.pynow names--region-overand--region-shearamong the argumentsvideo-swaytakes andvideo-sway-inspectdoes not.
- Tests: updates to
tests/video/test_sway_region_over.pyand new filetests/video/test_sway_read_on_recut.pycover these cases on synthetic figures (the region tests' body with a striped part over the torso's right side and past it over the air; the read-on runner):- over-solid: only solid pixels under the lower edge are free and drawn over; the not-opaque rest stays, an anchor, with bytes kept; the soft edge under the lower edge beside the torso goes with the part, while sliding over without the flag it belongs to the figure;
- the membrane at reach 3 and 6: under the lower edge within reach + 1 px, never the outline over the band; each pixel's move is the mean of its figure 4-neighbours' to within less than
MEMBRANE_STEP(what one more pass would move it), and the record namesstep_pxandpasses_most; the seam step down from the part's last row is at most half of the one sliding over; drawn by the move, never laid over; - the membrane never moves a piece left out (stops at its sides); without the membrane the layer is as it was;
- a membrane too short for the move is refused by its name, writing nothing;
- below the corner of a part whose lower edge falls from its left side, with
--region-rim-roundthe move rises down by at most pi/2 of its size over the rim's wider width, and more than that without the flag; - the refusals list gains each new option's refusal;
- without the membrane the four new options shape nothing (the same bytes and record);
- the four new options' refusals (each without
--region-mask, and the values--region-clear-alpha0 and 128,--region-floor-beside-1,--region-own-outline-2) leave the loop as it was; - two defect shapes, each red on the engine before this change: a part laid over the figure with a few pixels not opaque (alpha 60 and 30) a few rows under its lower edge over the air and a near-clear speck (alpha 3), with
--region-over-solid,--region-membrane 6and--region-shear 0.35: with--region-membrane-unpinand--region-clear-alpha 8the lower edge over the air moves with the part (lag 0.25 px or under), without them it stays short of the move (0.5 px or more), and under the clear alpha the speck is neither held nor the membrane's; and a part whose outline over the air takes one or two pixels past its mask in a row that changes from cell to cell, with--band-up 0.4and--region-membrane 6: with--region-own-outline 2those pixels are the region's and the side moves by each row's share of the move (lag 0.25 px or under), without it they are anchors and the side bends at a row that changes from cell to cell (0.5 px or more); --region-floor-beside: beside a region whose lower edge falls 1 px a column, the lower edge past each side is that of its lowest column within N of that side (directly onlayer_sets);- the frames path gives the strip's cells with
--region-membrane 6; - in new file
tests/video/test_sway_read_on_recut.py, a cut again at the same frame with a wider crop moves the regions and the mask by the crop's shift and gives the sway on the regions drawn there by hand; - a cut again at another start moves the mask onto the cell that is that frame, pixel for pixel, with every pixel outside it kept;
- a cell elsewhere in either cut that its record calls scaled or not as filmed leaves the pair as it is;
- a loop aligned from the cut again carries the pair through the alignment; the alignment keeps the cut's strip record byte for byte beside its frames (
cycle.source/<name>.strip.json), bound to the strip its origin names, and a second alignment keeps it as it was; the aligned strip's record holds nocell_record; - on a loop aligned from its cut, these are refused, each saying which: a kept record that is gone, a kept record that holds no
cell_record, a kept record bound to another strip, a paired cell its kept record calls not as filmed, and the read cut's cell drawn between the frames either side with its record changed to call it as filmed; - two cuts at
--anchor bodywhose ramps move frame 4 by nothing in the first and by -6 px in the second pair that frame where each ramp moved it: shift (0, 0), no drift, the moved mask is the patch where the second cut drew that frame, pixel for pixel; the crops alone set it 6 px apart; - two cuts at
--anchor bodywhose ramps move no frame (bothwrap_dx_px0) pair by their crops alone, as before, the mask landing on the patch there; - two cuts at
--anchor motion(head and torso regions on each cut's first frame) pair the frame where each correction laid it: the shift is the crops' less where the first correction laid that frame plus where the second laid it, not the crops' alone, and the mask lands on the patch there; each cell'sanchor_move_pxis the correction's place and every cell is as filmed; the report'ssource_projectionnames the motion recipe; video-looprecords each cell of its strip in the strip's record bound to its PNG: the source frame, the body ramp's move, no hold's scale, as filmed; the record is written beside the strip and not into the report, whose receipt holds one digest per frame;- a cell the jump repair gave way (a filmed ghost, no RIFE) is recorded not as filmed, every other cell as filmed;
- refusals: a frame this loop does not hold, a record with no clip it is cut from, and without
--read-on-cutthe relation's refusal as ever, each leaving the loop as it was; - a record of its cells not there or not as
video-loopwrites it is refused naming the field, on either cut: none, not an object, bound to another strip or none, no cells or one too few, a cell's entry, itssource_frame,anchor_move_px,scale, andas_filmedmissing or not of its kind (float, text, boolean, zero, NaN); - a paired cell its record calls scaled by the size hold or the gait fallback, or not as filmed, is refused saying which, on either cut;
- a cell an interpolator made, on either cut, is refused whatever its record says: as
video-looprecords it (not as filmed), and with its record changed to call it as filmed (its pixels are not the other cut's at the shift); - a loop aligned from its cut (
video-cycle-align) named by--read-on-cut, and a cut of another clip, are refused, and what the key is refused for leaves the loop as it was; - the walk away from the camera of the gait fallback tests, cut by
video-loopwith and without the size hold: the record gives the factor the size hold scaled each cell by, equal to the report'ssize_hold.cut_frames, and calls none of the held cells as filmed; - the same walk cut twice by
video-loopas a walk with the size hold on for one cut, for the other, and for both is refused, leaving the loop as it was, the record of the held cell naming its factor; - the same walk held in one cut with every trace of the hold and walk taken out of the report and strip record (the report's
size_hold, the report'sstate, the report's strip'sstate, the strip record'sstate) is refused by the record of its cells; with the record's factors andas_filmedtaken out too, refused naming the field; with the strip record'scell_recordtaken out, refused as a record with none; with the record changed to call every cell as filmed, refused by its pixels on either cut; - the command line reads the relation
recut.tests/video/test_follow_inspect.pynow names--region-over-solid,--region-membrane,--read-on-cut,--region-rim-round,--region-membrane-unpin,--region-clear-alpha,--region-floor-besideand--region-own-outlineamong the argumentsvideo-swaytakes andvideo-sway-inspectdoes not.
v3.10.1 - A frame made that shows the same picture as a frame beside it is refused; it is made again only on the side away from the picture it showed, or its run kept as filmed
Upgrading from 3.10.0: Every cut with no held cell, every cut whose frames between are real new pictures, and every --fill-held off run give the same cells as 3.10.0. A run that 3.8.0 to 3.10.0 reported as filled although its frame between repeated a picture beside it is now made at another fraction where one passes, or kept as filmed with a warning. Its faults in held_fill.before.held_runs list held. At --out-fps and in an air retimed with --air-retime, such cells are now listed in out_fps.shown_again or air_retime.shown_again with a warning instead of being counted as made. On twelve tests of the suite that run the binary, 3.10.0 runs the binary 146 times and 3.10.1 runs it 188 times because 3.10.0 took frames between that showed a picture beside them again, while 3.10.1 refuses them and makes them again at other fractions. So a cut whose frames between show a picture beside them again asks the binary for more runs, and takes longer, than in 3.10.0.
- Fix: A frame made that shows the same picture as a frame beside it is refused as
held, made again only on the side away from that picture, or its run kept as filmed. In 3.8.0 to 3.10.0, an interpolator that gave back one of the two frames it was handed, or the same picture for two different times, made no frame between at all. The run was recordedfilled: true, its cells listed inmade, with no retry and no warning, while poses over cells remained unchanged. A frame made must not read as the same picture as either frame it is made between, nor as the cell delivered just before it; otherwise it receives the faultheldand is refused. A refused frame is made again at the nearest other fractions ofRETIME_Twithin half a cell, but only on the side away from the picture it showed: later where it showed the frame before or the cell before it, earlier where it showed the frame after, and not again where it showed both. Because frames between run from one pose to the next, a fraction nearer a picture it showed shows that picture too. If none passes, the run is kept as filmed with awarning:line naming its cells. At--out-fpsand in an air retimed with--air-retime, a cell refused this way is the nearer frame, listed inshown_againand named in awarning:line. On the synthetic cuts of eight tests that reach the binary through the default fill, 3.10.0 took all 44 frames between it asked for, and 19 showed a picture beside them again. Version 3.10.1 makes 26 cells. Poses over cells are 324/383 as filmed, 341/383 in 3.10.0, and 348/383 in 3.10.1. Runs of the binary on them are 90 in 3.10.0, 124 in 3.10.1, and 214 in a first version that retried a refused frame at every fraction within half a cell on both sides. On a Linux runner with a CPU Vulkan driver, that first version made each of those eight tests run longer than its 120 s limit, so each of them timed out and failed. - Python callers: New function
held_fill.same_picture(frame, others).held_fill.judge(..., before=)takes the cell delivered before the frame, and its reading namesshows(which ofa,bandbeforethe frame shows again). Each try the loop report records (tries) namesshowswhere it showed one. - Docs: loop-repair.md section 7 documents the rule, the side a refused frame is made again on, their measurements, and the
--out-fpscells. video-pipeline.md andSKILL.mdare updated. release.md notes that a test that reaches the binary through a cut's default fill and runs it often enough to pass the default 120 s limit on a CPU's Vulkan driver carries the 900 s limit and pins its runs of RIFE withrife_runs. - Tests:
tests/video/test_held_fill.py(stalled walk with runs of two and three held cells kept as filmed when returning the frame before or after, 24/27 poses/cells, nine frames asked for, pictures matching--fill-held off, warnings naming cells 5-6 and 14-16; frame showing both poses refused with no retry; interpolator drawing the half way time making the run of two and trying the second cell of the run of three only later at 0.6667 to 0.8;--out-fps60 from 24 with eight cells listed inout_fps.shown_again; synthetic fall refused asheldat 0.5 and 0.55 and made at 0.6 in changed testtest_a_once_cut_and_a_one_shot_have_their_held_cells_made_too);tests/video/test_root_motion.py(synthetic jump air retimed twice as long with ten cells listed inair_retime.shown_againand named in a warning, each tried at 0.5 and then only later). Twelve tests that run the RIFE binary on a synthetic cut (the eight that timed out in the first version: three rows oftests/video/test_explicit_window.py, two tests oftests/video/test_gait_fallback.py,tests/video/test_ghost_given_way.py, one test oftests/video/test_one_step_cut.py,tests/video/test_play.py; and four more: the step screen test oftests/video/test_one_step_cut.py, the checkpoints test oftests/video/test_wrap_blend.py, a test oftests/video/test_once.py, and a test oftests/video/test_ghost_screen.pymarkedreal_rifethat hands frames torife.Rifeitself; the other eleven reach the binary through a cut's default fill) carry@pytest.mark.timeout(900)with a comment naming their calls of the binary, and each pins its runs of RIFE (between 6 and 36): eleven throughrife_runsintests/conftest.py(0 whererife_located()finds no binary), thetests/video/test_ghost_screen.pytest throughRife.calls. With no binary found, every count is 0 and the two tests markedreal_rifeskip. On the first version, nine of the twelve fail on the count, with run counts of 18 to 38: the eight, and the checkpoints test oftests/video/test_wrap_blend.py(20 against 16). The other three ask for the same runs in both versions. Red first for two test files,tests/video/test_held_fill.pyandtests/video/test_root_motion.py: 10 failed and 46 passed on 3.10.0; 56 passed on 3.10.1. Mutation check over those two files: with the new reading switched off, ten tests fail; without comparison to the cell before, two; without comparison to the frame after, three; without "only later" after the frame before or cell before, eight; without "only earlier" after the frame after, three; with the cell before not counted for the side, two.
v3.10.0 - Root motion on single-play cuts, their air retimed on a given gravity, length and speed (--air-retime), and a caller-named single play (--cycle once --start --length)
Upgrading from 3.9.0: a cut played once with a body (video-loop --cycle once, once-return, one-shot, and so video-set's single-play states) gains root_motion in its report and strip metadata: each cell's root, what it stands on, and its airs. Its cells and every other key keep their bytes and values. The air is drawn again only when asked (--air-retime).
- New: root motion on every cut played once.
root_motiongives each cell's root (the subject's mass centre, asinspect-motion'scentroid_px, in cell px), the floor's row (ground_y), the runs of cells on the ground or in a contact the caller names (--contact hand=12:20, frames of the clip), and each air: its take-off and landing cells, the seconds between them, its apex and the cell it peaks in. With--meters-per-px Mit adds each root in metres from the first cell's (root_m) and each apex in metres. A game readsrootto place each cell and moves the body on its own physics.video-loopprints each air in one line (air 0.42 s, apex 0.21 m) andvideo-setputsloop.airon each item. - New:
video-loop --air-retime gravity=G,air=T,speed=V(andvideo-set --air-retime). Each air with its take-off and landing in the cut is givenTseconds,Gm/s² andVm/s along, any of them, each the clip's own where not given;GandVneed--meters-per-px. The air's cells are spread evenly over its new seconds, each the clip's pose at the same share of its air, made with RIFE between two frames where it falls between them (the held-cell fill's frames, judged the same way), and moved whole onto the parabola from the take-off's root to the landing's; the landing and the cells after it move along with it, so a planted foot stays planted. The take-off, the landing and the cells on the ground before it are the frames as filmed. The strip metadata'sair_retimerecords each air's seconds and apex before and after, the gravity and speed used, how far along it moved, the cells made and the poses over cells. With no RIFE and a frame to make, the air is cut as filmed and a warning names the motion and the install line. A loop, or a cut with no such air, is cut as filmed and says why. A retimed cut is not restored from its source frames (video-loop-repair). - New:
video-loop --cycle once --start S --length Lplays exactly those frames once (terminal.kind: given): a move cut out of a longer motion that settles on no pose, such as a vault in a run. Before, a single-play cut refused--startand--length. - Python callers:
sprite_gen.video.root_motion(parse_retime,parse_contacts,clip_floor,root,touching,reading,read,sidecar,said,apex,retime,public);held_fill.at_times(a cell at each given time, taken out ofupsample);qa.motion.centroidandqa.motion.contact_spans(were_contact_spans);nonloop.on_floor,nonloop.GROUND_PX,nonloop.given_ending;loop.run_loop(..., air_retime=, meters_per_px=, contacts=);batch.run_set(..., air_retime=, meters_per_px=). - Docs: video-pipeline.md section 4, "Root motion" (the keys, how a game reads
root, the mass centre and not a body part,--cycle once --start --length, the air retimed, what it takes from sprite-gen);SKILL.md(tell the user each air's seconds and apex). - Tests:
tests/video/test_root_motion.pywithtests/video/jump_inputs.py(a synthetic jump whose mass centre flies a parabola under a known gravity: the root read within half a pixel, the air's cells, seconds and apex, the ground and a named hand contact; the air doubled peaks at g T²/8 with twice its cells, every cell on the parabola, none shown again, the take-off and the ground before it byte for byte, the landing moved along whole, and through real RIFE (real_rife) every between made and judged; the air alone keeps the clip's gravity; no RIFE cut as filmed with the motion named; the six cutstests/video/test_held_fill.pypins keep their pictures as decoded (tests/picture_digest.py) and every metadata value but the new key, the keyed clip's file sha read against the run's own files; the refusals;video-sethands the handle on).
v3.9.0 - Provider address environment variables, subscription logins off, and the capabilities verb
Upgrading from 3.8.0: nothing changes unless you set one of the new variables. Each provider's calls can go to another address (SPRITE_GEN_OPENAI_BASE_URL, SPRITE_GEN_XAI_BASE_URL, SPRITE_GEN_ANTHROPIC_BASE_URL, SPRITE_GEN_ELEVENLABS_BASE_URL), SPRITE_GEN_LOGINS=off runs every call on its API key, and the new verb sprite-gen capabilities prints every verb and argument as one JSON line. Unset, every request goes where it went with the same bytes, and every output keeps its bytes except sprite-gen --help, which lists the new verb.
- New: provider addresses. Each of the four providers sprite-gen calls over HTTP has a variable that replaces its documented address (the API root with its version path,
https://api.openai.com/v1,https://api.x.ai/v1,https://api.anthropic.com/v1,https://api.elevenlabs.io/v1). It is read when each request is made, not at import, so a value set or changed after the engine is imported is followed. Unset, empty or blank is the documented address. It moves every direct call: OpenAI images, edits and vision checks; Grok images, edits and vision checks, the video facing check, the video requests, polls andvideo-resume; Anthropic messages and Message Batches; ElevenLabs sound. A value that is not anhttp://orhttps://address with no query or fragment stops the call naming the variable. - New: a URL a provider hands back is fetched through the same address. With
SPRITE_GEN_XAI_BASE_URLset, the finished clip is downloaded asGET <value>/sprite-gen/fetch?url=<the clip's URL, percent-encoded>, first without a token and once more with the bearer token after a 401 or 403, as before. WithSPRITE_GEN_ANTHROPIC_BASE_URLset, a batch's results file comes the same way with the API key. A relay that forwards the provider's API forwards these too. Unset, the URL is fetched where it points. - New:
SPRITE_GEN_LOGINS=off. No subscription login is read: the grok login file (andGROK_HOME) is not looked at andXAI_API_KEYis used,claude auth statusis not run andANTHROPIC_API_KEYis used, and codex is not usable (codex login statusis not run; a default codex asks or runs what you chose for a codex that cannot run, naming the variable, and--provider codexstops). Each key keeps its rule: set but empty is refused, and a missing key stops the call naming the key and the variable. Unset or empty ison, the order as before; any other value is refused. - New:
sprite-gen capabilities. One JSON line: every verb (domain, description, old names, sub-verbs) and every argument as the CLI's parser holds it (spellings, type, how many values, default, required, choices, groups of which one is given), the providers each verb may call and whether it may be billed (video-resumecalls xAI and buys nothing), and the provider and login variables. It is read off the parser, so a verb or flag added to the CLI is listed with nothing else written. At this release it is 42,227 bytes, where every--helptogether is 158,857. - Python callers: new module
sprite_gen.gen.address(PROVIDERS,base,url,fetched,FETCH_PATH),sprite_gen.gen.base.LOGINS_ENV,LOGINS_OFFandlogins_on, new modulesprite_gen.workflow.capabilities(document,PROVIDER_CALLS,NO_PURCHASE). Removed: the module constantsxai.API_BASE,openai_provider.API_BASE,anthropic_api.API_BASEandsprite_gen.audio.provider.BASE, which kept a provider's address where a variable could not move it;videono longer copies the xAI address at import. - Tests:
tests/gen/test_provider_address.py(every call site against a local relay, the address unset, empty and blank, a value changed after import, the relay given the request's bytes, the clip and results file fetched through it, refused values, no module but the registry naming an address and none reading it at import),tests/gen/test_logins_off.py(each route on and off, the empty key refusal kept, codex's question and refusals, the access check),tests/workflow/test_capabilities.py(the document against the parser and every verb's printed options, a verb or flag added is listed, the providers, the size against every--help).
v3.8.0 - Held cells found and filled with in-betweens by default, and a cut given above its clip's frame rate (--out-fps)
Upgrading from 3.7.0: video-loop (and so video-set) now finds neighbour cells of a cut that show the same picture and, by default, makes them again with RIFE's frames between. A cut with no such cell comes out byte for byte as before. A cut with them comes out with its held cells made, its length, beat, first and last cells and wrap unchanged. --fill-held off cuts as before. Every cut's report and strip metadata gain held_fill.
- New: held cells found on every cut. A frame shown twice or three times in a row (a model that stalls, a rate carried to another by repeating frames, a cut mapped to a higher rate by taking the nearer frame) is read on the analysis thumbnail used to choose the cut and on the frames as cut. A step where at most 0.5 % of the subject's pixels change by more than 0.1 in both readings is the same picture. The report and the strip metadata record
held_fill: the cells, the poses (the cells less those showing the picture before them again), and the held runs (first cell, how many), before and after.video-loopprintsposes/cellsin its summary andvideo-setputsloop.poseson each item. - New: held cells filled by default (
--fill-held auto). Each run's cells are made between the run's first cell and the next pose at their own times (a run of three a third and two thirds of the way), judged asvideo-cycle-align's frames are (smear, outline, ghost, hole, doubled) and for a part standing still on both sides (a foot planted, a hand on a ledge: its outline must stand where it stood, the faultcontact). A frame refused is made again at a nearby fraction, else the run stays as filmed with a warning. Kept as filmed: a run longer than three cells (a hold the motion means), the opening and closing pose of a cut played once, a loop's last cells (their next pose is across the wrap), and every run of a cut drawn on twos or threes. In that case, its held-drawings reading (cycle_drawings, asvideo-cycle-alignreads it) holds 2 or 3 and every run is that long (held_fill.drawn): limited animation, as filmed. A clip carried to a higher rate by repeating frames reads a hold too, but its runs are two and three cells by turns, and it is filled. With no RIFE the cells are delivered as filmed, never a failure, and a warning names the motion andsprite-gen rife install. - New:
video-loop --out-fps Fandvideo-set --out-fps F. A cut given above its clip's rate is made of frames between at each cell's own time, never frames shown again: a loop keeps its cycle's seconds, a cut played once runs from its first frame to its last. The strip metadata saysout_fpsandsource_fps, andsource_cut.timesin place ofsamples. With no RIFE the cut is delivered at its own rate with a warning.video-cycle-alignandvideo-stoprefuse such a loop;video-setrefuses it with the cycle alignment on (pass--align-cycles off). - A cut whose cells were made is read by the seam gate on its rendered cells, is not restored from its source frames (
video-loop-repair:source-processing-unsupported), andvideo-cycle-alignreads its drawings on its own cells. - Python callers:
sprite_gen.video.held_fill(same_steps,runs,reading,fill,upsample,times,still_kept,judge,public,said);loop.run_loop(..., fill_held=, out_fps=);batch.run_set(..., fill_held=, out_fps=). - Docs: loop-repair.md section 7 (the reading, the fill, the higher rate, the paths that give frames at a higher rate, what it takes from sprite-gen); video-pipeline.md section 4 (the default step: find, fill, read again; poses over cells in one line);
SKILL.md. - Tests:
tests/video/test_held_fill.py(synthetic clips and a stand-in interpolator that draws the clip again at the time asked: six cuts with no held cell pinned to their decoded pictures on the engine before the change (commit 886936e); a stalled walk filled at a half, a third and two thirds, every other cell as filmed;--fill-held offbyte for byte as before; no RIFE delivered as filmed with the motion named; a hold of five kept; a walk drawn on twos kept as filmed, byte for byte as--fill-held off; a walk carried from 24 to 60 fps by repeating frames filled to 60 poses in 60 cells; a once and a one-shot cut filled; a planted foot kept still, and a frame between that drags it or cross-fades two poses refused; the ends of a cut played once and a loop's last cells kept; codec-like copies are the same picture and a pixel's move is not; a whole figure moving under a thumbnail pixel is not the same picture; a walk at 60 fps made of 60 poses in 60 cells; a one-shot at 60 fps keeping its first and last frames; no RIFE at its own rate; a rate under the clip's refused; the switches throughvideo-loopandvideo-set; restoration, the alignment and a stop refusing what they cannot read).
v3.7.0 - Breathe row width and height minimum and maximum sizing, and curator breathe editor range inputs
Upgrading from 3.6.0: a Breathe row's breath can now be sized by the two ends it travels between, across and up, instead of a strength (width_min, width_max, height_min, height_max; flags --width-min, --width-max, --height-min, --height-max). Every existing sidecar, flag and output keeps its bytes, and so does every normalized sidecar; the curator's breathe editor shows four range inputs in place of the two depth selects.
- New: a breath's width and height as minimum and maximum (pixel and smooth). Each is a share of the original. Width is how much the torso widens at the row where the breath is fullest (pixel: the row where the envelope peaks; smooth: the chest's peak P), negative narrower. Height is how far the head top (pixel) or the chest (smooth) rises, as a share of the body below the neck, negative down. Each lies in -0.20 to 0.20 with minimum at most maximum; a bound left out is 0, and null is left out. A minimum of 0 keeps the breath from going under the original size. The curve's shape and beat (
breaths,breath_peaks,lag,inhale) are unchanged. In pixel, one gain widens a row by 1 + g and shortens it by 1 / (1 + g), so the top of the curve is (width_max,height_min) and its bottom is (width_min,height_max). In smooth, rest is at both minimums and the top of the in-breath is at both maximums, so a minimum other than 0 moves the rest cell off the source. - A strength converts exactly. A pixel row of
depthd has height [-0.9009 d, 0.9009 d] (0.9009 is the breath curve's peak,breathe.WAVE_PEAK) and width [-a, a], with a = 0.9009 ×depth_x(ordepth) × the amplitude norm × the envelope's peak; a smooth row has height [0,depth] and width [0,depth_x]. Written as minimum and maximum, these bake the same bytes.sprite-gen breatherecords the row'srange({"width": [min, max], "height": [min, max]}) inbreathe.jsonfor that conversion. Pixel rows move whole rows and columns, so the extremes measured on a plate are within one cell of the values written. - Refused, not silently resolved: a row with both a strength (
depth,depth_x) and minimum or maximum keys, a value out of range or not a number (booleans included), a minimum above its maximum, and minimum or maximum keys on a round chest row. The row strain limit (0.25) is checked at the largest gain the curve reaches, and its refusal names the keys to reduce. The pixel clip refusal now says to reduce the breath's size (depth, or minimum and maximum) where it said depth. - Python callers:
breathe.WAVE_PEAK,breathe.envelope_peak,breathe.pixel_gains,breathe.breathe_range,curation.BREATHE_RANGE_KEYS,curation.BREATHE_RANGE_MAX.breathe.smooth_liftis the chest's rise from rest to the top, whichvideo-sway --breatheand--avoid-regionread: (height_max-height_min) × the basis height for a minimum and maximum row. - Curator: the breathe editor's two depth selects are four inputs (width minimum to maximum, height minimum to maximum, in %, 0.1 % steps, -20 to 20). A strength row shows the range its strength travels; editing one input moves the row to the four keys, the untouched ones carried at their exact values so that axis bakes the same bytes. The inputs are off for a round chest row and, on a pixel strength row, until the anatomy arrives. Loading a sidecar now keeps a strength row's
depth_x,axis_xandtorso_half, which the first autosave dropped before. A new row inherits a sibling row's minimum and maximum keys as it inherited a depth. The preview mirror bakes minimum and maximum rows byte for byte as the bake does. - Tests:
tests/effects/test_breathe_min_max.py(synthetic figures: strength rows keep their bytes and normalized sidecar; minimum 0 is never narrower nor taller on any row or phase; the written extremes are what the plate measures, within one cell; a strength's range written as minimum and maximum bakes its bytes; smooth from 0 is the old smooth; refusals and the strain limit), new cases intests/effects/test_breathe_js_mirror.py(minimum and maximum parity,breatheRange), the value-shape matrix over the four keys and the keptdepth_xand band intests/effects/test_breathe_sidecar_roundtrip.py, and the mirrored constants intests/effects/test_breathe_reference_key.py.
v3.6.0 - Two step walk and run loop cuts with half step warnings, loop search past untracked anchor frames, body turn loop exclusion, round chest breathing with sideways arms, and sway region mass movement
Upgrading from 3.5.0: video-loop walk and run cuts change for two-step cuts and half steps under --anchor motion-auto, opening frames the motion anchor cannot track, and body turns, while new sprite-gen breathe and video-sway options are off by default. In video-loop, a walk or run cut shorter than its state's gait floor, its steps not counted, is now cut two steps long under --anchor motion-auto where the clip as filmed comes back nearer two lengths on than one, and says so where it does not (cycle.half_step and a warning line); every other cut keeps every byte. A walk or run whose first frames the automatic motion anchor cannot track is now searched after them, as after a lead-in, where it was refused; every clip the anchor tracks from its first frame keeps every cut and byte. A clip whose cut held a turn is now cut where a window without the turn holds a cycle, while clips with no turn, clips that are not read, and clips with a turn and no turn-free cycle under warn keep every cut and byte. A pixel Breathe row can now breathe round from the chest, with the arms moving sideways (chest_round, arms_x), and sprite-gen breathe takes cells held still (--hold-mask), what the arms hold (--props-mask), pieces held behind the body (--props-behind-mask), and props grouping (--props-groups). All are off by default: every existing sidecar, flag and output keeps its bytes, and so does every normalized sidecar. video-sway can move each region as one mass with --band. When --band is left out, strips, frames, and records remain byte for byte what they were. Passing --band PX|auto moves each region's ellipse and an outer margin at full weight, with the weight falling to 0 by cos² over a band of pixels around it, while carrying the region by its own pixels rather than the body's outline lay. The fifth region number flat and --stretch-floor are refused when --band is specified. In the strip's metadata, follow gains band (and sway.json gains band for --frames), while stdout JSON gains band with band_px, margin_px, and lay_cells. The legacy command name video-follow accepts the same flags. video-sway --band can now hold pixels with --hold-mask, leaving them as they are while regions move round them. It is off by default, and when not given, strips, frames, and records remain byte for byte as before. video-sway can now move a region's own pixels with --region-mask, holding every visible pixel outside it and its soft edge while the weight falls over an inner rim read off the move. It is off by default, and when not given, strips, frames, and records remain byte for byte what they were (with --band, with --band and --hold-mask, and with neither).
- New:
video-loopnames a half-step cut. A walk or run loops on an even number of steps (two, one cycle). The half-period guard reads the gait floor (LoopProfile.min_seconds) in whole frames, rounded, so a run cut 8 frames long at 24 fps (0.33 s, under the run's 0.35 s) is taken as two steps. Such a periodic cut whose steps nothing counted (nocycle.steps) is kept, recorded incycle.half_step(rule,state,seconds,gait_floor,why,two_steps; in the stdout summary too) and named in a warning line that suggests--steps 1; the line repeats no refusal's words. Python callers:loop.half_step,loop.half_step_verdict,loop.HALF_STEP_RULE. Docs: video-pipeline.md section 4. Tests:tests/video/test_loop_half_step.py. - Changed:
video-loop --anchor motion-autocuts such a cut two lengths long where the clip says it holds two steps. One step on, the legs are back in place with near and far swapped, and where they are drawn alike the silhouette repeats; the body's turn, the shading across the torso and the folds of the clothes come back only two steps on. Each length of [2L − 1, 2L + 1] is cut as--steps 1cuts it, and about each cut's wrap (two frames either side of its first) the frames as filmed are read two lengths on over one length on; the nearest at most 0.85 (period.STEP_RATIO_MAX, the step screen's bound) whose seam and seam pop gates pass is taken, recordedcycle.steps{"count": 2, "by": "two-lengths", ...}andcycle.two_lengths(first_cut,tried,cut,taken; in the stdout summary too). It is read on the frames as filmed, not on the search's distances, which move every frame by one vertical slope fitted over the clip: a slope tilted by frames that open higher moves frames two steps apart further than one step apart where the body runs in place, so two lengths on read no nearer there. A cut the clip gives no two is kept and named as above, the warning line saying why (cycle.half_step.two_lengths). Python callers:loop.two_lengths_on,loop.TWO_LENGTHS_AROUND. Tests:tests/video/test_loop_two_lengths.py. - Fixed:
video-loop --anchor motion-autono longer refuses a walk or run for its opening frames alone. Whereauto_motion.discoverfinds no two regions through the whole clip (automatic motion anchor needs two separated regions trackable throughout the clip, orfound no stable textured region), the analysis is read again on the clip after the fewest frames it opens on, fewer than the window's shortest cut, with which the anchor finds its two regions through the rest (auto_motion.analyse_after_opening, new exceptionauto_motion.RegionsUnfound). A clip filmed from a still opens on that still and on the standing pose the body sets off from, and the regions the middle of the clip shows may be out of the anchor's reach there; the refusal came before the search, so the gait fallback never ran. Those frames are left out of the search as a lead-in is (lead_in.search_from, every frame number the clip's own), recorded in the report's newuntracked_opening(frames,first,shorter_than,refused) and, once a cut is found, a warning linevideo-loop: warning: the automatic motion anchor found its two regions from frame <k> on, not from the clip's first frames: ...that does not repeat the refusal's words. Where no such opening leaves the clip tracked, it is refused in the same words as before, followed by— nor through the clip after any of its first 1 to <n> frames left out (an opening shorter than the shortest cut, <n + 1> frames); where the cut the search took holds no two regions when its frames are read again for the correction, the refusal now ends— on the cut the search took (frames <a>-<b>). Tests:tests/video/test_auto_motion_opening.py(a synthetic walker whose first three frames carry its head and torso 90 px forward: refused as filmed before, now cut after them with every frame number the clip's own; the same walker without them unchanged; the lean again mid-clip refused with the new words). - New:
video-loopdetects torso turns in walk and run clips and avoids them during the cut search. A video model asked to walk at the still's angle sometimes turns the body inside the clip: a back-diagonal walk turns to a full back view half way and back. A loop cut across the turn plays the body swinging round. Until now the engine had no reading of this: the cut search could not avoid it, and a clip that held no cycle for it was refused only asvideo-loop: no periodic cycle found, so an app could not name that the body turned as the reason to film it again. The new modulesprite_gen/video/body_turn.pyintroduces readingtorso-side-v2on every walk or run under--anchor motion-auto, reading each frame's torso crop against the clip's first frame, the still the clip was filmed from, a standing pose. It does so whether or not the clip opens on a lead-in (the video model reframing the still to the walk's size over the first frames, which the cut search leaves out). It does not read against the first frame after the lead-in: that frame is a stride's pose, and a walk draws the mirror of a stride's pose half a cycle later, so a synthetic walk that does not turn, read against it, read a turn every stride (least -0.34). Read against the still filmed small, the same synthetic walk (its first 8 frames filmed from 0.6 of its size) reads +0.87 at least where it does not turn (+0.92 without the lead-in); turning over frames 30 to 40, its turn over frames 32 to 38, the same frames as without the lead-in, least -0.71 (-0.63 without the lead-in). The torso crop runs from the neck down half the body below it, centred on the head's centre, as wide as the first frame's torso. Each crop is cut about the head's axis between pixels, and the still and every frame are read at their nearest about the axes withinGUARD(2.5 px) andTOL(2 px),STEP(0.25 px) apart, so a piece beside the head that moves its centre 1.4 px moves no turn. Under the module constantMASS_SHARE= 0.01, the box's top is read as the row with more than a hundredth of the frame's solid pixels above it, and the still's torso width is read about the head's centre from the columns of the still's torso rows with more than a hundredth of those rows' solid pixels beside them. Reading them by mass prevents a piece apart from the body from moving the box or the torso width. The box's bottom is the frame's last solid row, the one end of the box not read by mass: where the legs cross each stride they lay their pixels over each other, and a bottom read by mass (the row with a hundredth of the frame's solid pixels under it, as the top is read) rises with them (on the lead-in walker, a row over its last solid row in most frames and 3 rows over where the legs cross, moving the crop's rows with it), though read either way, the walkers turning over frames 30 to 40 and the 4-frame turns drawn from 8 places, with the lead-in and without it, read their turns over the same frames. UnderHEAD_CORE= 0.5, the head's centre is read as the middle of the head band's columns that hold at least half the solid pixels of the band's fullest column, before being read again withinHEAD_REACHas before. This stops a fleck or a cut-loose ornament beside the head from shifting the head's centre and falsely reading a turn across the clip or hiding the walk's turn. The neck is the narrowest row of the first frame between 10 % and 55 % of its height (the topmost on a tie, or row 0.11 on a hooded walker). Each frame'ssidecorrelation is(v.s - v.m) / (1 - s.m), where each correlation is taken at its nearest about the axes withinTOL. Under module constantsSIDE_SHOWN_MIN= 0.08,TURN_SIDE_MAX= 0, andTURN_RUN_MIN= 4 consecutive frames, candidate windows whose cut holds a frame of a turn are refused withthe body turns (clip frames a-b), two-step cuts holding one are left out (step_count.turned_out), and held-side windows two lengths long are excluded. A new bound,HEAD_REACH= 0.3, re-reads the head's centre (the middle of the solid pixels of the top 15 % of the body) on the pixels withinHEAD_REACHof the body's height of it until it settles, leaving the plain mass centre as before where no pixel of those rows lies further out. Clips without turns (or unread) are searched once as before with the same cut and bytes. A walk that reads square against a still that shows a side is not read either and is cut the same way, with a warning line (WALK_SIDE_MIN). Where no window without the turn holds a cycle,--body-turn warn(the default) reruns the cut search as before and keeps the cut with a warning line naming the turn, or refuses as before (video-loop: no periodic cycle found) after a warning line if no cut holds a cycle; while--body-turn refuse(requiring--anchor motion-auto) printsvideo-loop: the body turns in the walkas its first line, prescribes filming it again with the torso and hips kept at the still's angle, hands over nothing, and setsstatus: failed, supporting app retake rules such asloop-body-turned. - Report fields (
<name>.loop.report.json): every walk or run report under--anchor motion-autoadds thebody_turnobject containingreading(torso-side-v2),bounds(SIDE_SHOWN_MIN,WALK_SIDE_MIN,TURN_SIDE_MAX,TURN_RUN_MIN),reference(0: the frame read against, the clip's first, lead-in or not),still_side,walk_side,read(true or false),why(where not read),neck,torso_still_side,side(each frame's reading),turns(each{from, to, least, at}),mode(warnorrefuse),verdict,refused(how many windows were refused for it),cut(frames, the cut's first and last clip frame, andholds, the turned frames it holds),avoiding(the search's refusal where the search that avoided the turn found nothing), andunread(a list of{frames, why}, each reason with the frames it applies to, appearing only where at least one frame was not read). Theverdictfield records one ofnone(read, no turn),not-read(a square still, a walk seen square, a first frame with no body, or a first frame the reading cannot read (no head to centre on, no solid pixel across its torso rows, or a crop of no width or with nothing in it)),clear(a turn, and the cut holds none of it without refusing anything),avoided(windows were refused for the turn and the cut leaves it out),kept(no cut without the turn holds a cycle; the cut taken before is kept, warned),unfound(no cycle with the turn or without it; refused as before, warned), orrefused(--body-turn refuse). Where the still passesSIDE_SHOWN_MINand the walk is seen square,video-loopprints one warning line under--body-turn warnandrefusealike, beginningvideo-loop: warning: the walk reads square against a still that shows a side (still_sideand endingcheck the loop's facing. The command's JSON summary also gainsbody_turn(verdict,turns,cut) where a turn was read. - Python callers: new module
sprite_gen.video.body_turnprovidesread(frames),square(reading),turns(side),turned(reading),neck(body),torso_rows(at), classTurn(reading, skip=0)(callable as(start, length), returning the refusal reason or None,held(start, length), counterrefused),refusal(...),kept(...),unfound(...), constantsREADING,SIDE_SHOWN_MIN,WALK_SIDE_MIN,TURN_SIDE_MAX,TURN_RUN_MIN,MODES(warn,refuse),NECK_RANGE(0.10, 0.55),HEAD_REACH(0.3),MASS_SHARE(0.01, the same value asframes.SPECK_MIN_FRACTION),HEAD_CORE(0.5),GUARD(2.5),TOL(2.0) andSTEP(0.25). Functionslocal_cycle.detect,local_cycle.by_stepsandlocal_cycle.countedtake a new keyword argumentturn(aTurn, default None: as before). Functionloop.run_looptakesbody_turn(default"warn"). - Output changes: a new named bound of the reading,
HEAD_REACH= 0.3, re-reads the head's centre on the pixels within 0.3 of the body's height of it. The full test suite caught why it is needed: its side walker with a 60 px tail on a 45-frame beat (tests/video/test_walk_steps.py, the half-step case) read a turn on every swing (frames 8 to 15 and 53 to 60, least -0.19), because the tail swung up into the head's rows and pulled the head's centre aside. WithHEAD_REACHit reads no turn (least +0.11) and is cut as before. Where no solid pixel of those rows lies withinHEAD_REACHof their middle, the top's parts lie apart on either side of the middle (a prop held as high as the head and apart from it, or a body too small for any pixel to lie that near), and the top does not tell which part is the head, so the frame is not read instead of taking the largest part and centring on a prop that can weigh what the head does (on the test suite's 132 px synthetic staff walker, the ornament and the head hold the same number of solid pixels in those rows, 513 each, with no pixel within 39.6 px of the middle) and reading turns the body does not make. Where that frame is the first frame, the clip is not read and the cut search runs once as on any unread clip; cut byvideo-loopunder default--body-turn warn, that synthetic staff walker is not read and is cut 11/24 (start 11, 24 frames), every byte as 3.3.0 cuts it. - Output changes: a new named bound of the reading,
WALK_SIDE_MIN= 0.045, and report fieldwalk_sideinbody_turnkeep front and back walks whose still shows a side (from arm swings or pieces beside the head) from reading turns every stride. For each frame after the still, its head and shoulders (top 45 % of body) cropped about its head are compared with the still's head and shoulders and their mirror withinGUARD(2.5 px);walk_sideis the median of frame nearness to the still minus nearness to the mirror (v.s - v.m), where a frame that flips underHELD_MAX(0.5 %) of the drawing last counted's solid pixels (alpha 128 or more) is not counted, so each drawing counts once andwalk_sideis the median of the walk's drawings, not of the time the clip gives each drawing; a clip in which every frame flips 0.5 % or more of the frame before's solid pixels reads exactly as before. The synthetic walker seen square from behind (the walker's still was taken 6 frames into its stride and the clip is 147 frames), each drawing of the first half of each stride held 3 frames and the second half 1 frame, previously lay 0.075 and read turns over frames 19 to 29, 67 to 77 and 115 to 125 that it does not make, but counting each drawing once it now lies 0.000 and is not read, with the warning line. Through the codec and keying (libx264 andvideo-frames), at most 2 of its 74 held frames came back the same pixels as the frame before, so it previously lay 0.076 to 0.083 and read turns that it does not make, but counted once underHELD_MAXit lies at most 0.013 and is not read. Held against the drawing last counted, a large or slow body is counted each time it has movedHELD_MAXfrom the drawing last counted; the synthetic walker over one stride, each drawing reached from the one before over frames that each flip under 0.4 % of the frame before's solid pixels: seen square from behind (its still taken 6 frames into its stride) itswalk_sidelies underWALK_SIDE_MINand it is not read; seen at an angle itswalk_sidelies overWALK_SIDE_MINand it is read. Where the still passesSIDE_SHOWN_MINandwalk_sidelies between -0.045 and +0.045, the walk is seen square:readis false,verdictisnot-read,whystarts "the walk is seen square", and cuts match search alone. Angled walks lie 0.061 or more (the 447 synthetic turn windows 0.090 or more), whereas square walks now all lie at 0.000 (the front walker with a 70 px tail moved from 0.013 to 0.000). When square,video-loopprints one warning line under--body-turn warnandrefusealike, beginningvideo-loop: warning: the walk reads square against a still that shows a side (still_side, giving the still's side andwalk_sidein that parenthesis, naming a front or back walk or a body that turned for much of the walk to face the camera or to its mirror, saying its facing is not read, and endingcheck the loop's facing. Readingwalk_sidecosts one more crop per frame. - Named limits: a piece apart from the body over a hundredth of body pixels is read as body: on synthetic walkers (3849 solid pixels), a 7 px fleck over frames 30 to 39 (49 px) tops the box, reading a turn. The box bottom is the last solid row: pieces under the feet (3 to 10 px square, 1 to 45 px under, across frames 30 to 39) stop turn reads, or return a verdict of
not-readfrom about 25 px under in the still. Neck rows spaced 2 % of height apart shift grid steps on 1 px box changes. A piece beside the still's head and shoulders (its head or an arm) can leave the clip unread: of 863, 372, 808 and 148 placements of a piece under a hundredth of the body about the heads and torsos of four walkers that do not turn (in the still alone, in every frame but the still, or over frames 30 to 39), 11, 1, 22 and 0 leave the clip unread, each a piece in the still alone (21 of 34 right or left of the head at 6 or 20 px, 13 beside an arm) laying the still's head and shoulders under 0.08 off their nearest mirror. The piece-in-the-still case is now closed byWALK_SIDE_MIN: that square walker's still is read whenSIDE_SHOWN_MINis lowered to 0.06 (orGUARDset to 2, orSTEPto 1), but its walk is not (walk_side0.000); only withWALK_SIDE_MINalso at 0 does it read turns (frames 15 to 21 and 39 to 43).GUARDandTOLare pixels of the frame, so a larger body's margin narrows: the plain walker drawn 1.5, 2 and 3 times as large, with the 3 by 12 px column drawn as many times as large beside its head in the still moving the centre 1.8, 2.7 and 4.0 px, the walk reads least +0.78, +0.44 and +0.31 without turning. (a) A walk turned to the still's mirror over about half its frames lies as near the mirror as the still at the median and is not read, with the warning line: the synthetic walker turned to its mirror over 39 to 41 of its 73 frames about their middle (38 to 41 hooded), that is 52 to 56 % of the clip; over 38 or fewer (37 hooded), or 42 or more, it is read with its turn. (b) A walk that turns in every cycle over 14 to 16 frames of each 24-frame cycle (58 to 67 %) is not read, with the warning line; over 13 or fewer it is read. (c) A walk turned to square and held there (a side walk that turns to face the camera and walks on toward it, or turns its back and stays) over 41 or more of its 73 frames (56 % and more; 40 or more hooded) is a square walk by its frames and is not read, with the warning line; for example the walker turned square at frame 24 and held to the end (49 frames) lies 0.006. (d) A frame is counted once only where underHELD_MAXof the drawing last counted's solid pixels flip: a part of the stride that a clip plays slower in drawings of its own (not held), or a held frame under noise overHELD_MAX(at crf 28, some of the synthetic walker's held frames), counts frame by frame, so a square walk played that way lies off the still's mirror at the median toward that part; overWALK_SIDE_MINit is read and reads turns it does not make. And a drawing that flips underHELD_MAXof the drawing last counted (a large or slow walker where its stride turns) is taken for that drawing held and is not counted. - New: the round chest (pixel;
chest_round,arms_x, flags--chest-round,--arms-x). When either is above 0, a pixel row bakes the round chest instead of the envelope squash. Both are shares of the body below the neck (0 to 0.20). The rim of the chest ellipse (smooth'schest_*keys) moves out from its peak bychest_round. Inside the ellipse the body stretches evenly from the peak; outside it the body is pushed whole, so a 1 px outline stays 1 px. Above the peak the chest goes up and out; below the peak it goes sideways only, fading to nothing at the feet. The head above the rigid boundary keeps its place and bytes, as in smooth. Below the rigid boundary, the sideways share (the chest's sideways push and the arms) turns on over the longer of 0.15 of the neck band and 1.5 times the sideways px (chest_roundplusarms_xin px), and the body's following of a held piece turns on over the longer of 0.15 of the neck band and 1.5 times the largest piece move in px (if it turns on over less, rows just below the head line slide more than one cell per row against each other and an outline crossing the head line breaks; with 1.5 times, no row slides more than about one cell against the next because the steepest slope of the smooth turn on is 1.5 over its length). The arms (the columns outside where appendage protection starts) are pushed whole by the chest and then sideways byarms_xon top, never stretched; the torso's sides take the stretch over 12 times that push. The breath is smooth's one-sided curve (inhale,breaths,breath_peaks,loop_cells,start_cell), so a cell at phase 0 is the source byte for byte. Every output cell is a cell of the source: no new colour, and no row or column is folded. A round row refusesdepth,depth_x,lagand smooth-only shape keys; smooth refuseschest_roundandarms_x. See breathing, "둥근 가슴". - New: held cells (
--hold-mask), held props (--props-mask), props behind the body (--props-behind-mask), and props grouping (--props-groups). All are PNGs the size of the frames; their light opaque pixels (lightness 128 or more, alpha 128 or more) are the cells. A cell may be in only one of the three masks; a cell in two is refused. Empty cells inside a props mask are not drawn; only the drawing's opaque cells of a piece move. A held cell keeps its bytes in every frame, because the field is 0 there (smooth and round rows; an envelope row refuses). Each piece of the props mask (8-connected, cells within 2 px of each other joined, as a hilt and blade parted by the hand) moves whole and sideways, as far as the hand holding it: the chest's sideways push where the piece touches the body, plus the fullarms_xof the arm on its side. The body within 2 px of it moves the same whole cells, so no gap opens between hand and grip. A whole arm can move as one rigid block by masking it from the sleeve below the shoulder down to the hand together with what it holds as one--props-maskpiece (one colour), starting below the sideways turn on rows. Where a piece moves onto held cells, held cells stay on top and those cells are not drawn; the engine counts them per piece and per frame inprops.pieces[i].hiddenandhidden_maxofbreathe.json, printing one warning line on stderr of the formbreathe: warning: --props-mask piece K of N (C cells) goes under held cells in F of T frames, up to M cells (frame X); those cells are not drawnfollowed bybreathe.json props.pieces[K-1].hidden. In each row, the engine looks at the first cell right behind the moved piece: when that cell is a held cell, it repeats over the cells the piece left (water fills where a blade left the water band; a held back fills where a sleeve moved away), and otherwise the body fills it; no empty cell is made up. The engine counts cells a piece fills by repeating a cell or left by the field where the body does not follow fully rather than moving them inprops.pieces[i].filledandfilled_maxofbreathe.json(held cells themselves are never counted), printing one warning line on stderr of the formbreathe: warning: --props-mask piece K of N (C cells) leaves cells it fills by repeating a cell in F of T frames, up to M cells (frame X); those cells are made up, not movedfollowed by a space andbreathe.json props.pieces[K-1].filled. Pieces held behind the body (--props-behind-mask, off by default) take the same sideways move, but the body stays in front, does not follow, and the piece is drawn under held cells, under the body, and under pieces held in front; all pieces behind the body are drawn first, then all pieces in front, including pieces that do not move in that frame (so a resting front piece is not covered by a behind piece), and held cells are always on top; where it pulls out from behind the body, the piece's cell touching the body in that row repeats over the cells it left (making the piece look wider by that many cells, as the shield's edge column repeats), while cells left where nothing was in front become empty; the cells it fills by repeating a cell are counted inprops_behind.pieces[i].filledandfilled_maxwith a warning line on stderr of the formbreathe: warning: --props-behind-mask piece K of N (C cells) leaves cells it fills by repeating a cell in F of T frames, up to M cells (frame X); those cells are made up, not movedfollowed by a space andbreathe.json props_behind.pieces[K-1].filled; its hidden cells (under held cells, the body, or a front piece) are counted inprops_behind.pieces[i].hiddenandhidden_maxwith a warning line readinggoes under held cells, the body or a piece held in front of itand naming--props-behind-mask. A piece ledger maintains a source map of which source cell each output cell shows, reading all counts off this map in every frame. Before drawing, each piece is checked at its whole-cell destination and refused if pushed off the cell (naming the mask flag, piece as i/n with its cell count, opaque cells leaving, side crossed with its count like왼쪽 변 밖 3, cell size, and move, advising to widen the cell margin or lowerchest_roundorarms_x; covering behind pieces, rows above the head line, and rounding edges); the body's own off-cell refusal now counts body cells only and names the side crossed with its count. Two pieces of one layer landing on one cell are refused (advising--props-groups colouror moving one to the other mask); a behind piece and the body in front moving apart to leave empty cells is refused (advising to mask only the part showing outside the body as--props-behind-maskor give it as--props-mask); and in every frame the cells shown at destination plus hidden cells must equal the piece's opaque cells in the still, refusing as an engine defect if not. With--props-groups colour(defaultpiece; refused without a props mask), both props masks are read by colour: light opaque cells of one colour form one group moving by the whole cells read where the group touches the body, allowing unheld elements like reflections to follow a prop.breathe.jsonrecordshold,props, andprops_behind(path, sha256, cells, each piece'sshift_px,hidden,hidden_max,filled,filled_max), with each piece carryingcolourand the mask carryinggroups: "colour"andcolourswhen grouped by colour.sprite-gen breathealso takes--axis-xand--torso-half, the sidecar's existing overrides, so a figure whose arms lie inside the measured torso can name them. - Curator: a round row is kept as written and its preview and video export are refused, as for smooth rows; the mirrored key lists are checked against the bake's.
- New: banded sway moving regions as one mass (
--band,--band-margin,--band-up).--band PX|autokeeps the weight at 1 over each region's ellipse expanded by the margin in every direction (the flat part), falling from 1 to 0 by cos² over a band ofPXpx past it, leaving pixels outside the band unchanged byte for byte.--band-margin PX|auto(defaultauto,ceil(reach) + 1) sets how far past the ellipse the weight stays 1.--band autosets the band toceil(reach x pi / 2) + 1, the narrowest band that does not fold. Reach is evaluated first at the requested--gain, after which band and margin are determined in two stages. The fold rule reads the narrowest band instead of radius, refusing moves wherereach x pi / (2 x band) >= 1or lowering gain under--on-fold lower.--band-up FLAT[,PX|auto]shapes the area above the centre separately, stopping the flat partFLATof the vertical radius above the centre and falling overPXpx (defaulting to the band orHANG_PASTof 3 px above the top, whichever is further) so upper regions yield while the rest moves whole. Where the flat ellipse and the outer one differ in shape (above the centre under--band-up, where the flat part is short and the band long), the band measured across its ring is narrower than its px, so the weight falls steeper than the fold rule reads. After the fold rule, each region's steepest slope along the move is read over every pixel of every cell (band_steepest: per unit of gain, the most of the move at gain 1 dotted with the weight's gradient, the gradient read between each pixel's neighbours, and the cell where it is). A pixel moved by gaingkeeps1 - g x steepestof its area, so a region folds whereg x steepest >= 1. Then--on-fold refuserefuses, saying that--band's weight falls steeper than its px where the band is narrower across its ring, in which cell and what area a pixel keeps at the gain asked, and to lower--gainor give a wider--band(or--band-up, when it was given);--on-fold lowerlowers that region's gain to the largest whole number of0.01steps, no more than the gain it had, whose steepest slope stays under 1 (steepest_gain); a region that would have to go under gain 1 is held, and the run is refused only when every region is held, as the fold rule does. Each region is carried across cells in the loop's order from the cell the region was read on by its own solid pixels under the ellipse withinCARRY_SEARCH(9) px of where the cell before had the region's pixels (around the cell's own body lay only where the cell before was carried by the lay, or is the cell the region was read on; or, with--reference, for the first cell) using least squared difference of premultiplied colour and subpixel parabolic fitting; uncertain matches revert to the outline lay and warn on stderr. See video-pipeline section 6. - New: holding pixels through banded sway (
--hold-mask).--hold-mask MASK.png|DIRleaves pixels as they are while a band moves its regions round them, requiring--bandand off by default, byte for byte as before when not given. The mask is a PNG drawn on the cell the regions were read on (holding pixels where alpha is 128 or more; where the PNG has no alpha, grey 128 or more) or a folder of PNGs giving one mask per cell in file-name order. One mask is split into 8-connected pieces, each carried into every cell by its own solid pixels withinCARRY_SEARCH(9) px by least squared difference of premultiplied colour and parabolic fitting (reverting to body lay with a warning on stderr when uncertain or covering no solid pixel), then grown byHOLD_GROW(3) px. Each cell keeps byte for byte the mask pixels, soft edges, and air withinceil(reach) + HOLD_EDGE(2) px. Other pixels are read short of kept pixels along the move direction byf = min(s, h)px, wherehisHOLD_SLOPE(0.5) times free distance to kept or margin pixels (HOLD_MARGINof 1 px), bounded to rise by at mostHOLD_SLOPEper pixel (read_share). Reads touching forbidden pixels are renormalised or walked back by 1/HOLD_STEPS(1/16) of their move. Metadata gainsfollow.hold(andsway.jsongainsholdfor--frames), while stdout JSON gainsholdwithpieces,lay_cells, andread_folded_px_max. - New: a region given as a mask (
--region-mask,--region-rim,--region-shrink,--region-crease).--region-mask MASK.png|DIRgives the region as a mask of the part's own pixels instead of the ellipse's weight, moving the part while holding every visible pixel outside it and its soft edge in every cell, off by default and byte for byte as before when not given. The mask is a PNG drawn on the cell the regions were read on (alpha 128 or more, or grey 128 or more where it has no alpha) or a folder of PNGs giving one mask per cell in file-name order. When requested,--region-creasealigns the mask's lower edge to the median darkest row fromCREASE_UP(5) rows above toCREASE_DOWN(3) rows below overCREASE_SPAN(2) columns either way, and--region-shrink PX(defaultSHRINK_DEFAULT, 2) wears the mask in by 4-neighbour steps. One mask is carried into each cell by its own solid pixels withinCARRY_SEARCH(9) px by least squared difference of premultiplied colour, searching round the cell before and the body's lay, keeping the carry of the cell before when neither settles. The region and its soft edge (pixels not opaque withinREGION_SOFT, 2, px of the region, not beside another solid pixel) move, and the air (clear pixels withinceil(reach) + REGION_AIR, 2, px of the region) is where they may move into; every other visible pixel is held. Inside the region, its soft edge and the air, weight rises bysin²(pi/2 x d)from 0 at held pixels to 1 across a rim scaled by--region-rim SCALE(defaultRIM_DEFAULT, 1.0) and widened until slope is at mostRIM_SLOPE(0.9), preventing folding. With--band-up, weight is the lesser of the rim and the upper yield. Strip metadata gainsfollow.region_mask(andsway.jsongainsregion_maskfor--frames), while stdout JSON gainsregion_maskwithkept_cells,rim_px,move_most_px, andwalked_px_max. See video-pipeline section 6. - Python callers:
sway_loop,sway_frames,read_request, andread_askacceptband,band_margin, andband_up(band_upas(flat, px_or_"auto")or command-line string). New insprite_gen.video.sway:band_weight,band_shapes,carry_match,carry_own,band_steepest,steepest_gain,band_ledger,band_notes, andjacobian(moved fromsway_inspect, which retains it under the same name); constantsBAND_POLICY,CARRY_BASIS_BAND,CARRY_SEARCH,HANG_PAST,PRESSED,STRETCHED,MOVED_PX, andAUTO; and methodsAnswer.band_field(k, xx, yy)andAnswer.band_record().sway_loop,sway_frames,read_request, andread_askaccepthold_mask(a Path to a PNG or folder; None: off); new insprite_gen.video.sway:Hold,read_hold,Held,hold_sets,free_back,read_share,draw_held,hold_ledger,hold_notes, andcarry_mask; constantsHOLD_POLICY,HOLD_GROW,HOLD_EDGE,HOLD_MARGIN,HOLD_SLOPE,HOLD_ROUND, andHOLD_STEPS;Ask.hold,Answer.hold,Answer.held_cell(k), andAnswer.hold_record(); andcarry_ownnow callscarry_mask(same behaviour). - Python callers:
sway_loop,sway_frames,read_request, andread_askacceptregion_mask(a Path to a PNG or a folder; None: off),region_rim(float; None: 1.0),region_shrink(int; None: 2), andregion_crease(bool); new insprite_gen.video.sway:RegionMask,Masked,crease_of,carry_region,rim_bands,rim_distance,region_sets,region_ledger, andregion_notes; constantsREGION_POLICY,RIM_SLOPE,RIM_DEFAULT,SHRINK_DEFAULT,REGION_SOFT,REGION_AIR,CREASE_UP,CREASE_DOWN, andCREASE_SPAN;Ask.mask,Answer.mask,Answer.mask_field(k, xx, yy),Answer.masked_cell(k), andAnswer.mask_record(); anddraw_heldgainsshort(default true; false reads every pixel at its whole move). - Record fields:
follow.bandin strip metadata andbandinsway.jsonrecordpolicy(own-pixels/margin-band-cos2/1),asked({band, margin, up}),reach_px,band_px, andmargin_px. They record per-regionflat_pxandband_px(across, above, below); per region infollow.band.regions[i],steepest:per_gain(the slope per unit of gain),cell, andratio(the region's gain timesper_gain, under 1 on any written strip);carrywithsearch_px(9) and per-cell, per-regionpx,from(base,pixels, orlay),whyfor lay,least, andcurvature;layentries for cells carried by lay; andledgerlists per cell (with<key>_maxvalues) forband_on_regions_px,pressed_px,stretched_px,pressed_box,stretched_box,area_least,area_most,outside_moved_px, andjacobian_min. Only the four counts warn:band_on_regions_px,pressed_px,stretched_px, andoutside_moved_px. For each that is not 0 in some cell, one warning line on stderr says in how many cells, up to how many px and in which cell (forpressed_pxandstretched_pxalso the least or the most area and where), and ends with the record key:follow.band.ledger.<key>on--loop-dir,sway.json band.ledger.<key>on--frames. The lay warning names its record key the same way:follow.band.layon--loop-dir,sway.json band.layon--frames.jacobian_min(the least area of the source any pixel of a moved cell takes, per cell) gives no warning: it is recorded, and 0 or under in any cell refuses the run as the last check, named the engine's fault, nothing written. Command stdout JSON gainsbandcontainingband_px,margin_px, andlay_cells. - Record fields:
follow.holdin strip metadata andholdinsway.jsonrecordpolicy(own-pixels-grown/kept-edge-air/read-short-sloped/1),asked(per_cell, andsha256: the file's, or a list per file for a folder),grow_px(3; null for a folder),edge_px,margin_px(1),slope(0.5),round_px(1), andsteps(16). They recordpieceswith each piece'spxandbox(x0,y0,x1,y1) on the cell it was drawn on (empty for a folder);carrywithsearch_px(9) and per-cell, per-piecepx,from(base,pixels, orlay),whyfor lay,least, andcurvature(null for a folder);layentries ({cell, piece, why}) for pieces carried by lay; andledgerlists per cell (with<key>_maxvalues) forheld_px,soft_px,air_px,short_px,renormalised_px,walked_px,read_folded_px,read_folded_edge_px,read_least,read_turn_folded_px, andread_turn_least. Warning lines on stderr report a piece carried by the lay (in how many cells and why), ending with the record key:follow.hold.layon--loop-dir,sway.json hold.layon--frames. Forrenormalised_px,walked_px, andread_folded_px, when not 0 in some cell, one warning line on stderr says in how many cells, up to how many px and in which cell, ending with the record key:follow.hold.ledger.<key>on--loop-dir,sway.json hold.ledger.<key>on--frames. Command stdout JSON gainsholdcontainingpieces,lay_cells, andread_folded_px_max. - Record fields:
follow.region_maskin strip metadata andregion_maskinsway.jsonrecordpolicy(own-pixels-mask/held-outside/rim-sin2/1),asked(per_cell,sha256: the file's, or a list per file for a folder,rim: the scale,shrink_px,crease: true/false, andup:{flat, band}or null),soft_px(2), andair_px(ceil(reach) + 2). They recordrim(across_pxfor Lx,down_pxfor Ly,least_px: the two bands it started at,slope: the steepest(pi/2) x sqrt(...)over the cells, andslope_bound: 0.9);mask(px: its pixel count as worn in,box, andcarried_by_px: the solid pixels it was carried by; null for a folder);crease(per mask,rows: each column's row, keyed by column, andfree_columns; null when not asked);carry(search_pxof 9 andcells: per cellpx,from:base,pixelsorbefore,guess:beforeorlaywhere carried by its pixels,whywhere it kept the cell before's carry,least, andcurvature; null for a folder);keptentries ({cell, why}) for cells keeping the carry of the cell before;upcontaining the upper yield's shape as a band's record (reach_px,band_px,margin_px, per regionflat_px,band_pxandsteepest, itscarryandlay; null without--band-up); andledgerlists per cell (with<key>_maxvalues) forregion_px,soft_px,air_px,held_px,held_changed_px(0),move_most([px, x, y] of the region pixel that moves most; null where none moves) withmove_most_max,pressed_px,pressed_box,area_least,stretched_px,stretched_box,area_most,folded_px,jacobian_min,read_held_weight([weight, x, y]; null where none),read_held_half_px,renormalised_px, andwalked_px. Warning lines on stderr report cells that kept the carry of the cell before (endingfollow.region_mask.kept), a region whose--band-upyield was carried by the lay (endingfollow.region_mask.up.lay), and forheld_changed_px,pressed_px,stretched_px,read_held_half_px,renormalised_pxandwalked_pxwhen not 0 in some cell, one line reports in how many cells and up to how many px (with area and location for pressed and stretched), ending withfollow.region_mask.ledger.<key>on--loop-dirorsway.json region_mask.ledger.<key>on--frames. Command stdout JSON gainsregion_maskcontainingkept_cells,rim_px([Lx, Ly]),move_most_px, andwalked_px_max. - Tests: synthetic tests in new test file
tests/video/test_loop_body_turn.pyverify a 73-frame, 24-frame cycle back-diagonal walker seen from behind (legs side by side swinging half a cycle apart, arms either side swinging opposite, the arm on the facing side bright and the other dim, a light panel on the torso and the cheek toward the facing) whose turn moves its facing over to the still's mirror and back. Tests verify boundary turnovers: a torso reading of exactly 0 is not turned and one just under it is; three turned frames in a row are not a turn and four are; a frame not read ends a run; andSIDE_SHOWN_MINset to the walker's own still side reads the clip and set just above it does not. The walker that turns reads one turn inside the frames it turns over and none elsewhere; the same walker not turning reads none; drawn square from behind it is not read. The same turn drawn on twos reads the same frames as on ones (within a frame), in fewer drawings. On a lead-in where the first 8 frames are filmed from 0.6 of the size (which the search leaves out), the report'sbody_turn.referenceis 0, the turn reads over the frames it reads over without the lead-in (under -0.1), and the walk where it does not turn stays over +0.1; read from the first frame after the lead-in, the walk that does not turn is not read, and withWALK_SIDE_MINat 0 it reads a turn every stride. A hooded walker with no neck reads its neck at the top row of the range (0.11) and finds the turn too, and finds none where it does not turn. The walker facing past its mirror 3 frames in a row reads no turn (however deep); 4 frames in a row read one turn of 4 frames. The suite's half-step side walker with a 60 px tail reads no turn atHEAD_REACH0.3 and a turn every swing at 0.35. Red to green tests verify that for a walker turning over frames 30 to 40 (read as 32 to 38, least -0.63), 3.3.0 cuts 22/24 (frames 22 to 45) across the turn, while this version refuses the windows that hold it and cuts 41/24 (frames 41 to 64); and turning over frames 14 to 24 and 24 to 34 where 3.3.0 cut 11/24 and 17/24 across the turn, this version cuts 35/24 and 41/24. When a walker turns in every cycle,warnkeeps the cut the search took before, byte for byte, with the warning line, whilerefuserefuses it withvideo-loop: the body turns in the walkas the first line and hands nothing over. Walkers that do not turn and walkers drawn square are cut byte for byte as the search alone cuts them. The walker that turns (over frames 30 to 40) is cut with the cycle search replaced by one that finds no cycle in any window (as on a clip that holds no repeat), and its feet are not read;warnrefuses it in the words it was refused in before (video-loop: no periodic cycle found), after the warning line naming the turn;refuserefuses it withvideo-loop: the body turns in the walk. Passing--body-turn refusewithout--anchor motion-autois refused. New synthetic tests intests/video/test_loop_body_turn.pyverify that the staff walker's still is not read; the staff over frames 20 to 29 and a 2 pixel sliver at frame 40 leave those frames null with their reason, every other frame reading as it reads without them; a pennant apart above the walker leaves the still's torso rows empty and the still unread; the pennant over frames 20 to 29 only leaves those frames' torso crops empty, so they are null, not 0; a head on a pole (one column under the head's centre) gives a crop of no width and the still is not read, and a frame of one solid pixel is null; a clip with no frames is not read; and under the defaultwarn, the staff walker and the walker with the pennant in its first frame alone are cut byte for byte as the search alone cuts them, and the report says why they were not read. Fortorso-side-v2, new synthetic tests intests/video/test_loop_body_turn.pyverify that the 42 named walkers each read as drawn (a turn inside the frames it turns over, none where it does not, unread where the still cannot be read), the 7 px fleck reading its frames turned as the named limit; the antenna or whisker cut loose with a 3 px fleck at 186 placements reading no turn (marked slow); a piece apart under the feet over frames 30 to 39 (3, 6, 7 and 10 px; 1 to 45 px under) reading no turn;MASS_SHAREon both sides (the 6 px fleck and the antenna cut loose read no turn at 0.01, the 7 px fleck reads its frames turned at 0.01, the antenna tops the box and the walk reads three turns at 0.005, the 7 px fleck reads no turn at 0.0125, and the walker's 3849 px put a hundredth between 36 and 49);HEAD_COREon both sides (at 0.5 neither the fleck beside the head in the still nor the ornament moves the still's centre, the fleck's walk reads no turn and the ornament walker reads its turn; at 0.3 the fleck moves the still's centre more than 1 px and less thanTOLand the walk still reads no turn; at 0.35 the ornament moves it less thanTOLand the turn still reads). The walker drawn in one grey crops as its own mirror about its head's axis (head and shoulders and torso under 1e-6 off it), and in its own tones its still lies 0.10 to 0.11 off its mirror; with the still's centre read 0.25 to 1 px off either way the walk reads no turn and no frame's side moves 0.07; a 6 by 6 px square or a 3 by 12 px column 6 px right of the head in the still, or the column over frames 30 to 39 of the lead-in walker, reads no turn, and the same walkers turning read their turn inside frames 30 to 40; the hooded, lead-in and plain stills lie between 0.08 and 0.11 off their nearest mirror, and the walker seen square with a 3 by 12 or 2 by 18 px column or a 6 by 6 px square against its head or 6 px from it in the still is not read (its side between 0.05 and 0.07); withGUARD2,STEP1 orSIDE_SHOWN_MIN0.06 the square walker with the 3 by 12 px column has its still read but its walk not ("the walk is seen square"), and withWALK_SIDE_MINat 0 as well it reads turns;TOL0 reads the lead-in walker with the column over frames 30 to 39 turned there; and the side walker with a 60 px tail and its arms reads no turn with every frame's centre read 3 px left, where atTOL1 it reads a turn with them 2.25 px left. The square walker taken 6, 3 or 9 frames into its stride, or 1, 2 or 11 frames with a 6 by 6, 3 by 12 or 2 by 18 px piece beside its head in the still, has its still overSIDE_SHOWN_MIN,walk_sideunder 0.005, and is not read, while withWALK_SIDE_MINat 0 it reads three turns. The walker seen square from behind whose still shows a side, each drawing of one half of its stride held 2, 3 or 4 frames and each of the other half 1 frame (taken 2, 3, 6, 9 or 11 frames into its stride; alone, or with a 6 by 6, 3 by 12 or 2 by 18 px piece beside its head in the still), is not read, with the warning line, and itswalk_sideis the same as drawn on ones (within 0.002 with a piece); withWALK_SIDE_MINat 0 it reads turns. The plain, hooded, turning and hooded turning walkers held the same way have the samewalk_sideas on ones, read their turn over the frames that hold the drawings they turn over (drawings 30 to 40), and read none where they do not turn. The square walker held 3 and 1 frames over the two halves of its stride (taken 6 frames into its stride, alone or with a 6 by 6 px piece beside its head in the still), each held frame with 6 of its edge pixels cleared (under 0.2 % of its solid pixels), has the samewalk_sideas without the noise and is not read (withHELD_MAXat 0 it is read, with turns), while the turning walker held the same way with the same noise has the samewalk_sideas without it and reads its turn over the frames that hold drawings 30 to 40. Through libx264 (its default crf 23) andvideo-frames' keying (a slow test, skipped without ffmpeg), the square walker held 3 and 1 lies under 0.02 and is not read, and the turning walker held the same way reads its turn over the frames that hold drawings 30 to 40. The walker over one stride, each drawing reached from the one before over frames that each flip under 0.4 % of the frame before's solid pixels, seen square from behind (taken 6 frames into its stride) is not read (walk_sideunderWALK_SIDE_MIN), and seen at an angle is read (walk_sideoverWALK_SIDE_MIN).walk_sidelies between 0.08 and 0.11 for the plain, hooded, lead-in, turning, hooded turning, turning-every-cycle and on-twos walkers, between 0.07 and 0.075 for the side walker with a 60 px tail on a 45-frame beat, and under 0.005 for the square walker taken 3, 6 or 9 frames on, andWALK_SIDE_MINis 0.045. The walker turned to its mirror over frames 18 to 53 (36 of 73) is read with its turn over frames 20 to 51 and no warning, over 16 to 55 (40) is not read (walk_sideunder 0.005) and gets the warning (naming the turn to its mirror), as does the walker turned over 15 frames of each 24-frame cycle, and over 14 to 57 (44) is read with its turn over frames 16 to 55,walk_sideunder 0 and no warning. Cut byvideo-loop, the walker turned square at frame 24 and held to the end is not read (verdictnot-read,walk_sideunder 0.01), prints exactly one warning line beginningvideo-loop: warning: the walk reads square against a still that shows a side (still_sideand endingcheck the loop's facingthat gives the still's side andwalk_sideand names the turn to face the camera or to its mirror, and is cut every byte as the search alone cuts it, while the diagonal walker that does not turn and the walker drawn square print no such line. - Tests:
tests/effects/test_breathe_round.py(on a synthetic figure: the rest is the source and the head never moves; the chest swells round from one point, the line above the peak rises and the line below it does not; no new colour, no fold, a 1 px outline; the arms move sideways whole; a bar held in the hand moves with it and no gap opens; held cells keep their bytes under the round chest and under smooth; a bar going under a held water band is counted per frame inbreathe.jsonand warned on stderr, held cells keep their bytes and the cells it left in the water rows are water (no gap); a reflection painted the bar's colour with--props-groups colourfollows the bar by the same cells in every frame, the cells it left show the still's water, and no new colour appears; a shield given as--props-behind-maskslides out from behind a held arm with its rim cell filling the space and no gap, while given as--props-maskthe held arm's outline fills that space instead;--props-groupswithout a props mask is refused; the new keys off keep every byte; wrong keys are refused; the CLI bakes what the library bakes and records both masks; a piece pushed off the canvas, behind the body or in front, is refused with its name and the side, and no folder is left; a piece above the head line pushed off the canvas is refused; the body pushed off the canvas names the side; the cells a piece fills (a shield sliding out from behind an arm, a bar leaving a held water band) are recorded per frame inbreathe.jsonand warned, and match a count made independently from a tag picture (every cell carries its own index); in eight scenes every cell of every piece is drawn at its destination or counted as hidden in every frame, and the filled count matches the independent count; two pieces of one layer landing on one cell are refused; a piece in front stays over a piece behind, whether it moves over it or the behind piece moves under it; a piece behind the body moving apart from it is refused; the ledger changes no byte of seven scenes baked before it (no masks, held legs only, the held bar, the bar in the water, the colour group reflection, the shield behind and in front); a row with only held cells records no piece ledger) andtests/effects/test_breathe_round_curator.py(the mirror refuses a round row; the round trip keeps a round sidecar as written and keeps a refused one with a notice; the mirrored key lists). - Tests: new file
tests/video/test_sway_band.pycovers these cases on synthetic figures. Each case first reads what a sway writes with or without the band (its cells, its fold, whether it refuses, what it says on stderr) and the band's own record after, so a release without the band fails on what comes out:- without
--band, the strip and the record are as before (noband, nocarry_basis); autoreads the margin and the band off the move's reach at the gain asked, and the fold rule reads the band;- a band narrower than the move needs is refused, or the gain lowered under
--on-fold lower; - a band narrower across its ring than its px (flat to a tenth of the radius above the centre) is refused by its steepest slope, or lowered to the largest gain whose slope stays under 1, every cell's least area over 0, while the same band without
--band-upkeeps the gain asked; --band-upstops the flat part over the centre and runs its band past the region's top: below the centre the cells are those of the band without it, above it the upper part gives;- what cannot go with
--bandis refused with its reason (a flat share,--stretch-floor,--band-marginor--band-upalone) and leaves the loop as it was; a flat share of 0 is four numbers and takes a band; - out-of-range values are refused by the command line with exit 2 and the flag's message;
- the flat part moves by the cell's offset itself, and past the band no byte changes, also just past its rim;
- a part that slides on the body is carried by its own pixels, not the lay;
- a part that slides 3 px a cell to 12 px from the lay, held there and back, is found around where the cell before had it and moved whole in every cell;
- cloth with no pattern, and a part that jumps further than the search from where the cell before had it, are carried by the lay and named in a warning;
- cloth dotted every 4 px is a tie and carried by the lay;
- the ledger's counts, boxes and warning lines;
--framesgives the strip's cells, and a turned loop under--read-onis the cut's banded sway cell for cell.tests/video/test_follow_inspect.pynow names--band,--band-marginand--band-upamong the argumentsvideo-swaytakes andvideo-sway-inspectdoes not.
- without
- Tests: new file
tests/video/test_sway_hold.pycovers these cases on synthetic figures. Each case first reads what a sway writes with and without the mask (its cells, whether it refuses, what it says), so a release without the mask fails on what comes out; the hold's record and ledger are read after:- without
--hold-maskthe band is as before (noholdin the record); - an arm over the chest, a belt below it, a half-clear edge beside the arm and a clear notch at the waist keep their bytes in every cell; no arm-coloured pixel is drawn off the arm, and no pixel solid within 2 px of the arm is left clear; without the mask the band moves the arm and draws its colour on the chest; record: pieces, carry by own pixels where the body carries them, no lay, some reads short;
- pixels no read round the mask comes near are the band's byte for byte;
- a steep band beside the mask (the band's own least area under 0.2, the gain lowered by the fold rule): the arm keeps its bytes and no read takes the source backwards, checked by a direct computation and by the ledger (
read_folded_px0 in every cell, and where the read turns from the whole move to its share,read_turn_folded_px0 and the least area over 0); - a folder of the carried masks gives the same strip and ledger as the one mask;
--framesgives the strip's cells and the same hold record;- under
--read-on: a mask drawn on a cut's first cell (on its chest's rim); the held sway differs from the band alone in more than half of the cells, and a loop turned from that cut and swayed with--read-onon the cut's reading and the same mask gives the cut's held cells, cell for cell in the turned order, with the read-on relationtransportedand the same carried pixel count per piece in each cell, in the turned order (this case uses the read-on tests' runner figure); - each refusal leaves the loop as it was;
- a piece on cloth with no pattern is carried by the lay, held all the same, and the record, the warning line, the stdout JSON and the ledger keys say so.
tests/video/test_follow_inspect.pynow names--hold-maskamong the argumentsvideo-swaytakes andvideo-sway-inspectdoes not.
- without
- Tests: new file
tests/video/test_sway_region.pycovers these cases on synthetic figures (a body whose striped part, round above and cut straight below, lies over its torso's right side and past it over the air, soft against the air, with a dark crease under it on the torso; the band tests' part on cloth with no pattern; the read-on tests' runner, cut and turned). Each case first reads what a sway writes with the mask (its cells, whether it refuses, what it says), so on a release without the mask the same input fails on what comes out; the record and the ledger are read after:- without
--region-maskthe sway is as before, plain and with--band(noregion_maskin the record), from the command line and from Python; - every visible pixel outside the part keeps its bytes at gain 2.5, at 1.25 and at 6.0, while without the mask the outside changes;
- inside its rim the part moves whole, and it moves into the air beside it and no further;
- the part's soft edge moves with it, and a soft pixel beside the torso is held;
- the mask is carried round where the cell before had it first (a part sliding on the body, and one ramping away from the lay), and the record says so;
- a part whose body jumps further than the search is found round the lay;
- where neither guess settles (cloth with no pattern), the carry of the cell before is kept, never the lay, and the record, the warning line and the stdout JSON say which cells and why;
- the rim is read off the move and the weight is sin² of the distance to the held pixels, at gain 2.5 and 6.0: the fold rule reads no radius, nothing folds, no read is walked back and no read puts half its weight on a held pixel;
- a wider rim (
--region-rim 1.5) moves less of the part whole; --band-upyields above the centre: the weight is the lesser of the rim's and the yield's, and below the centre it is the rim's;- a mask drawn 2 px large holds the belly once it is worn in by the default 2 px;
--region-creaseends the mask on the darkest row under it before it is worn in;- a folder of the carried masks moves the part as the one mask does;
--framesgives the strip's cells and the same record;- a loop turned from a cut and moved under
--read-onon the cut's reading is the cut's, cell for cell; - each refusal leaves the loop as it was;
- the ledger counts each cell, and the warning lines and the stdout JSON say what is in it.
tests/video/test_follow_inspect.pynow names--region-mask,--region-rim,--region-shrinkand--region-creaseamong the argumentsvideo-swaytakes andvideo-sway-inspectdoes not.
- without
v3.5.0 - Widened square canvas framing for side walk and run stride and trailing parts, measured background matte cutout for flat backgrounds of any colour, and failure when a cutout removes nothing
Upgrading from 3.4.0: video-set now frames a walk or run filmed from the side on a square widened by the room its still lacks, and a background the chroma engine did not recognise, which used to come out with nothing removed, is now cut out. A still that leaves less than GAIT_ROOM clear in front of its silhouette (0.15 of the silhouette's height) or behind it (0.25) gains the columns it lacks on that side; the square gains the same number of rows above the still. A still that leaves the room keeps its canvas to the byte. Every other state, a front, back or diagonal view, --shape and --fit tight are framed as before. Each side walk or run's canvas.report.json, and its item in set.report.json, gains room. video-canvas gains --view and reads the room only with --view side. Backgrounds the chroma engine already recognised key byte for byte as before. A pure or recognised magenta/green background still goes to the chroma engine and a bright achromatic one to the white matte, with the same bytes.
New: the walk's room (
canvas.gait_room,GAIT_ROOM,ROOM_VIEWS). Filmed from the side, a walk's stride reaches in front of the standing silhouette, and behind it the stride and a part that trails behind the body (a big tail, a long coat) swing past it. Where either met the left or right edge,video-framesrefused the clip, and the walk had to be filmed again with--shape wide. Thewalkandrunrows now read the still's room: the empty columns between the silhouette and the left and right edges of the square the row makes of the still, in front and behind, as a fraction of the silhouette's height. A side under itsGAIT_ROOM(more behind than in front) gains what it lacks, and the frame stays square: the clip keeps the 1:1 a walk is filmed at, and the still is never scaled. The report'sroomrecords the view, the silhouette, the room on each side, the bound,short,added_px(columns per side) andadded_rows, and a widened canvas'swhysays why.--shape squarekeeps the still's own square.--shape wideis still the walk's 16:9 row (GAIT_WIDE). See video-pipeline section 1.Changed:
canvas.subject_rowsis nowcanvas.subject_box, which reads the columns as well as the rows.--fit tightreads its rows from it, byte for byte.New: the measured background matte (
sprite_gen/frames/measured_matte.py, rule in docs/chroma-alpha.md "The measured background"). It reads the background's colour and spread from a ring inside the image's edges, keys that colour and its hue in shade (a drop shadow, a gradient), thin dark strips along the edges, and enclosed pockets of a saturated background, then unmixes a 2 px edge between the local background and the nearest solid subject colour. No colour needs a route of its own: a muted yellow-green, an off-cyan, a grey or an off-white key the same way.Fixed:
cutout --key green|magentaandextract_routeon a background the engine does not recognise as that key. Such a background was keyed against the pure key and nothing came off, andcutoutexited 0; a green behind dark edge strips was routed to the white matte. It is now measured (route: measured,chroma_key_paintedthe measured colour), sovideo-canvasrepaints such a still to the exact key, andcutoutkeys the frames of such a clip one by one.video-frameskeeps keying a clip from one exact key: it still refuses such a clip, with the same bytes and report, and its guidance to normalise the still withvideo-canvasnow works on these backgrounds.Fixed:
cutoutfails when it made nothing transparent, likegen/chroma.py, instead of reporting success.CLI:
cutout --key measuredforces the measured matte;autosends a corner that is neither a key nor bright and achromatic to it.Report fields (
route: measured):background,background_spread,background_ring_share,shade,tolerance,edge_strips,keyed_pixels,pocket_pixels,edge_pixels,band,key_residue_px.Python callers:
extract_route(..., measure_unrecognised=True)andcutout(..., measure_unrecognised=True, refuse_empty=True)(video-framespasses both False); newcutout.key_recognised(image, kind),measured_matte.measured_matte(image, band=2),measured_matte.measure_background(rgb),measured_matte.background_like(rgb, colour, tolerance, shade).Tests: new
tests/frames/test_measured_matte.py, synthetic only: a subject with a dark outline, skin and hair colours on muted green, deep green, off-cyan and yellowish backgrounds with noise, a gradient, a darker shade round the subject, dark strips on two edges and a pocket of background inside; an off-white background measured on request; the routing of a green request on a muted green throughextract_route,cutoutandvideo-canvas; a cutout that keys nothing fails.Tests:
tests/video/test_walk_canvas_room.pycovers these cases:- a side walk whose tail reaches 6 px of the edge behind, facing either way, gets a square widened behind and above by what it lacks, the still unscaled, through
video-set's item and report; - a person with room keeps the default row's canvas byte for byte;
- front, back, diagonal and unnamed views are not read;
- each bound flips one pixel either side of its
GAIT_ROOM, the one behind larger than the one in front, and both short sides each gain their own lack; - a still taller than it is wide is read in its square;
- a white base is read on its corner colour;
- a run is read at the walk's bounds;
--shape square,--shape wide,--fit tightand another state are not read;--viewworks from the command line.
Four
video-settests' canvas stubs now takeview, andtest_edge_speck_lead_in.pyreads the walk's own row.- a side walk whose tail reaches 6 px of the edge behind, facing either way, gets a square widened behind and above by what it lacks, the still unscaled, through
v3.4.0 - Loop part pop retakes, cycle alignment walk beat repair and broken beats, ghost limb faults, and same foot, filmed jump, and seam jump retakes
Upgrading from 3.3.0: A walk or run loop in video-loop is cut to the same bytes, whether a part pops in it or not, and video-cycle-align changes only alignment outputs whose beat broke or where a made frame has a limb seen through under --between auto. For video-loop, every walk and run report gains part_pop and retake; --unfixed refuse also refuses a loop recorded retake reason part-pop, whatever --repair; no flags are added, no frames are made and no other cut is taken. video-cycle-align now reads ghost bands in windows of the body to catch limbs seen through, keeps frames given way on the beat under --between auto by making them again at clean fractions or widening jolts across neighbouring frames, changing only alignment outputs whose beat broke (a jolt of 0.25 beat or more) or where a made frame has a limb seen through (ghost window over 1.4 %); loops keeping the beat, loops with no frame given way, and video-loop (and video-set) keep their bytes for strip PNG, GIF, WebP, and cycle frames, while gaining beat, ghost_window, (on back and back_diagonal views) same_foot, and retake reasons (broken-beat, same-foot) in alignment strip.json and reports; every aligned loop's strip.json and report gain screen, and loops whose cut jumps gain the reasons filmed-jump and seam-jump, frames unchanged; and clip_feet in video-loop's strip.json and reports for every walk or run cut; all outputs from video-loop-compare and video-loop-repair are unchanged, bytes included, and --same-foot defaults to warn so nothing is refused by default.
- New: The part reading and the
retakerecord. Squares 8 % of the body height are followed drawing to drawing and a part whose jerk leaves the curve its steps either side draw pops at the wrap. The cut stays and the report records a take to film again (retake, reasonpart-pop):remedyisretakewhere the engine's search chose the cut, andrecut-or-retakewhere the cut was given (--cycle fixed, orpinned);searchedsays which. See loop-repair section 2, "The part pop". - New: a made frame's ghost band is now also read in windows of the body (
rife.ghost_window, constantrife.GHOST_BAND= 0.10) to catch limbs seen through. On frames the cycle alignment makes,rife.ghost_windowcounts the same part-covered pixels in regions at leastrife.GHOST_THICK(5 px) thick thatrife.ghostcounts, but in windows a tenth of the body high sliding a quarter window at a time down the body, each as a share of the solid pixels in that window, reading the largest window's share and where it lies as fractions of the body from the top (ghost_window_at). Overinterpolation_quality.GHOST_WINDOW_WARN= 0.014 (1.4 % of a window's solid pixels), the made frame has the faultghost(though whole-bodyghoststays under 0.3 %) and gives way, or is made again at another fraction, warning that it carries a limb seen through (for example: "carries a part-covered band over 2.40 % of the solid pixels in a band 10 % of its body high (60 to 70 % down it), at least 5 px thick, though 0.18 % of its whole body, a limb seen through, a ghost"). This catches RIFE blending coverages over a gap beside a limb; it is not read onvideo-loop's jump repair frames or filmed frames. - New:
video-cycle-alignreads the loop's beat and keeps frames given way on it under--between auto, checks for the same foot stepping twice, andvideo-looprecords whether each cut steps the same foot twice (clip_feet). On every aligned loop,video-cycle-alignreads the leg path over the lowestLEG_PATH_BAND= 0.10 of the figure box (BLOCK8 x 8 px,SEARCH12 px,MATCH_BAD40 of 255,READ_HEIGHT410 px) and measures the beat jolt across each gap (BEAT_JOLT= 0.25 beat). Under--between auto(the default), where a loop's beat breaks from frames given way to the nearer source frame, the frames given way are taken in runs of neighbouring frames and made again at clean fractions (align.RETIME_T= 0.15 to 0.85, step 0.05) withinBEAT_JOLTof their times, or their jolt is spread over neighbouring frames (align.WIDEN= 2, then 3 frames each side) moved off their own times and made by RIFE. A frame made only to keep the beat is taken only where its window reading is underalign.RETIME_WINDOW_MAX= 0.006, well under the 1.4 % fault limit, besides having no fault. Runs that cannot be kept stay on the nearer source frame, are named inbeat.named, and carry thebroken-beatreason under--between autoin theretakerecord when beat gaps remain atBEAT_JOLTor more. On views where feet stand side by side (STEP_VIEWS= back, back_diagonal),video-cycle-alignreads whether the same foot steps twice in a row (FOOT_ROWS= 0.03,LIFT_MIN= 0.010,LIFT_CELLS= 2,DOWN_MAX= 0.006), recording reasonsame-foot, and warns under--same-foot warn(the default) or stops the set before anything is rewritten under--same-foot refuse. Each reason has one warning line replacing earlier separate beat and same-foot lines, naming what is likely to fix it ("retake", "recut", or "recut-or-retake"), and the report'sretakelist carries these loops like the others (under--between nearesta broken beat is recorded inbeatbut is no reason).video-loopreads every cut of the cut's length on keyed frames of walks and runs, recording for every cut whether that cut, looped, steps the same foot twice (clip_feet) instrip.jsonand its report. - New:
video-cycle-alignreads a jump the take films between two of its frames, or at the cut's seam, on the screen as well as the beat. For each step of the cut's own frames (cycle.source/, step i from frame i to i + 1, the last step from the last frame to the first, which is the cut's seam),cadence.screen_steps(frames)reads the mean absolute luminance difference over white (0 to 255) of the box every frame's figure fits in (whole) and of its lowestcadence.SCREEN_ROWS= 0.30 (legs; a strip cell's lowest 125 of its 406 px), read atREAD_HEIGHT410 px. The beat reads only the leg path where the feet go (the lowest 10 % of the box); two drawings filmed a pose apart (legs wide apart in one, crossed in the next, the tail up) move the feet little and change the picture much, so the beat passes them, but the screen sees them. It is read on the cut's own frames, not on the aligned frames (an aligned frame spans two or three of the cut's frames, which spreads a jump over the drawing changes beside it and hides it), on every aligned loop whatever its view and whatever--between. Undercadence.screen_record, a step is a jump when, over the box or on its leg rows, it is at leastcadence.SCREEN_JUMP= 2.0 times the cycle's typical step and at leastcadence.SCREEN_ALONE= 1.3 times every other step of the cycle. The typical step is the upper quartile of the cycle's steps: on ones every step is a drawing change, on twos or threes most steps change nothing and the upper quartile is a drawing change. A cycle whose drawing changes are all alike names none; so does a cycle with two steps alike however large (neither is 1.3 times the other). A jump inside the cut gives theretakereasonfilmed-jump(detailsfilmed_jump:steps,at,whole,legs,remedy"recut-or-retake"), because the take jumps between two poses there and the alignment does not change the poses a take shows; where the clip films another cycle without the jump, a cut of the same clip from there removes it, and where it does not, a new take does. A jump at the seam givesseam-jump(detailsseam_jump, same keys,remedy"recut-or-retake"), because another cut of the clip may close on a pose it holds, or a new take may not need the cut to close there (limitsscreen_jump,screen_alone,screen_rows). Warning lines name what is likely to fix it (for example: ": cut it again or film this direction again (filmed-jump): the take jumps between two of its frames, from frame 30 to 31 of cycle.source/ the picture changes 22 of 255 over the figure's box and 36 on its legs, 2.10 and 2.50 times the cut's typical step and 1.50 and 1.80 times any other step (the loop's frames 13 to 14); the alignment does not change the poses a take shows. Where the clip films another cycle without the jump, a cut there fixes it; where it does not, a new take does", or for a seam jump: ": cut it again or film this direction again (seam-jump): the cut's seam jumps, from frame ... ; another cut of the clip may close on a pose it holds, a new take may not need the cut to close there"). - Report fields:
cycle_align.beatinstrip.jsonand report rowbeatrecordjolt,gap,over,jolts,limit(0.25),band(0.1), andpath(read,on-time, orunreadwithwhy). Eachsmearrow (and a frame made again, underretimed) recordsghost_windowandghost_window_at([from, to] fractions of the body); both arenullwhere the ghost screen does not read the loop. A retimed frame's row insmearhasmethod: "retimed"(besiderifekept andnearestgiven way), keeps its first frame's measures andfaults, and gainsretimed:t,from_t,off, measures,faults: [],look. Every frame given way in a loop whose beat broke gainsretime:between,tried(each fraction recordingghost_window, andwindow_overwhere it had no fault but read over the bar),off_nearest. Retimed frames count inmade_atandmade_by_rife, notnearest_atorreplaced; the report gains a set-wideretimedcount, andbeat.retimedlists them per loop. Widened runs record inbeat.widened(run,width, andmovedwithat,off, new source or pair and fraction); moved frames carrysmearmethod: "moved"withmovedand count inmade_at. Runs kept on the nearer source frame record inbeat.named.cycle_align.same_footinstrip.jsonand the report row recordsread,order,steps(half,frames,peak,lift),twice, andclip.clip_feetinstrip.jsonand thevideo-loopreport recordslength,cuts,same_foot,alternate,unread,seam_in_step, andsame_foot_at. Each loop row andstrip.jsoncycle_aligngainscreen:wholeandlegs(every step),typical(per region),jumps(each:step[i, i + 1] as frames of cycle.source/,seamtrue for the last step,wholeandlegseach [change, times the typical step, times the next largest step],atthe gaps [k, k + 1] of the aligned (turned) loop that show it), andlimits(jump,alone,rows). Under--same-foot refuse, a refused report is written withapplied: false,refused: "same-foot", andsame_foot; the report'ssame_footkey names the mode. A loop'sretakerecord (keeping its shape:reasonthe first,reasonsall, details under each reason's snake_case key,limits) gains reasonsfilmed-jump(detailsfilmed_jump:steps,at,whole,legs,remedy),seam-jump(detailsseam_jump:steps,at,whole,legs,remedy; limitsscreen_jump,screen_alone,screen_rows),broken-beatunder--between auto(detailsbroken_beat:jolt,gap,over,named,remedy; limitbeat_jolt) andsame-foot(detailssame_foot:order,twice,clipcountinglength,cuts,same_foot,alternate,unread,seam_in_step, or null,remedy; limitslift_min,lift_cells,down_max), in order: held-drawings, filmed-ghost, filmed-jump, seam-jump, broken-beat, same-foot;remedyis "retake", "recut", or "recut-or-retake", and the report'sretakelist carries these loops like the others. - Python callers: new module
sprite_gen/video/cadence.pywithleg_path,Beat,beat_record,turned,same_foot,clip_feet,view_reads_feet,screen_steps,screen_recordand constantsLEG_PATH_BAND(0.10),READ_HEIGHT(410),BLOCK(8),SEARCH(12),MATCH_BAD(40.0),BEAT_JOLT(0.25),STEP_VIEWS,FOOT_ROWS(0.03),LIFT_MIN(0.010),LIFT_CELLS(2),DOWN_MAX(0.006),SCREEN_ROWS(0.30),SCREEN_JUMP(2.0), andSCREEN_ALONE(1.3); insprite_gen/video/rife.pyghost_windowandGHOST_BAND(0.10); insprite_gen/video/interpolation_quality.pyGHOST_WINDOW_WARN(0.014); insprite_gen/video/align.pymeasure_made(frame, a, b, t, reads=...)(returning every measure a made frame is judged by),retake(..., beat=None, feet=None, screen=None),RETAKE_JUMP_REASON("filmed-jump"),RETAKE_SEAM_REASON("seam-jump"),RETAKE_BEAT_REASON,RETAKE_FEET_REASON,REMEDIES,RETIME_WINDOW_MAX(0.006),RETIME_T,WIDEN(2, 3),SAME_FOOT("warn", "refuse"),align_set(..., same_foot="warn"), andresamplefacts gainingbeat. - Output changes: under default
--between auto, alignment outputs where frames given way broke the beat change when retimed or widened to keep the beat underBEAT_JOLT(0.25 beat), or where a made frame has a limb seen through (ghost window over 1.4 %) and gives way or is made again; loops whose frames given way keep the beat, loops with no frame given way or faulty made frame, and all outputs under--between nearestandrifekeep their exact bytes across strip PNG, GIF, WebP, and cycle frames (gaining thebeatrecord,ghost_window,retakereasons, and where--viewis back or back_diagonalsame_footinstrip.jsonand reports; under--between rifethe alignment keeps the made frame and names it a ghost); every aligned loop'sstrip.jsonand report gainscreen, and loops whose cut jumps gain the reasons, frames unchanged. Forvideo-loop(and the loopsvideo-setcuts),strip.jsonand report files gainclip_feeton every walk or run cut, while strip PNG, GIF, WebP, and cycle frames keep their exact bytes. All outputs fromvideo-loop-compareandvideo-loop-repairare unchanged, bytes included. - Tests: synthetic test suite in
tests/video/test_cycle_align_beat.pyuses figures with an outlined body over two outlined feet 16 px wide (two blocks) on the ground, sliding together by 8 px (a block) at each drawing forward half the cycle and back, with the interpolator drawing them at the fraction and smearing the body where told the pair breaks, and feet standing side by side lifting in turn. Tests cover: a cut of 54 frames on threes aligned to 24 where every fourth frame falls half way between drawings with RIFE smearing at fractions 0.45 to 0.55, the nearer source frame leaving a jolt of 2/3 of a beat (which 3.3.0 failed) and the fix making each again at 0.4 (0.13 of a beat early, largest jolt 0.13, nothing named); a fraction made again with no fault but a block the background shows through (its window between 0.6 % and 1.4 %) is passed over for the next clean fraction (0.6 instead of 0.4), its try recordingwindow_over; a cut of 20 stretched to 30 with two neighbouring frames given way, where making each again nearest its own fraction jolts the gap between them 0.325 beat but the run's choice (0.55 and 0.2) keeps every gap under 0.25 beat (largest 0.2), and where 0.55 is not clean both stay on the nearer source frame (named, largest jolt 1.0); a frame whose pair breaks at every fraction within the limit, half a beat late on the nearer frame, where two frames each side are moved a third and a sixth of a beat late and made there (every gap jolting a sixth of a beat); a cut of 40 squeezed to 24 with one frame given way a fifth of a beat off on the nearer frame delivered as before without remaking; every frame at its own time giving jolt 0 without reading legs;--between nearestrecording the jolt it leaves; same foot detection on back loops reading "RRL" (twice) and alternating "RL" round the ring, dipping underLIFT_MINwithout reachingDOWN_MAXreading one step and reachingDOWN_MAXreading two steps, front, front diagonal, side, and no view not read, one half stepping not read, the clip that steps the same foot twice every cycle reading 29 of its 49 cuts so and 20 with their seam inside a step, the alternating clip reading 33 cuts alternating and 16 with their seam inside a step, a cut shorter than the cycle whose seam joins two right lifts reads, as a loop, right then left (alternating), and a clip holding just that cut counts it apart (seam_in_step1, neither alternating nor the same foot), and a cut 1.5 cycles long joining a step to the same foot's next; a loop whose beat still breaks and a loop that steps the same foot twice carrying reasonsbroken-beatandsame-footwith remedies (--between nearestand a beat with no gap over being no reason); integration throughvideo-loopandvideo-cycle-alignrecordingclip_feet,--same-foot refusestopping the set with strip untouched and report refused, and naming the same-foot loop "film this direction again (same-foot)", withremedy"retake" and the clip's counts. New synthetic test suite intests/video/test_inbetween_seen_through.pyuses a wide body over two legs, the near leg's outer 8 columns cut back over 60 rows in the first source frame (a gap open to the space between the legs) and whole in the second; the frame made between them has that strip at alpha 0.35 in the leg's colour: its whole-body ghost is under 0.3 % and its hole 0, so with no window reading (3.3.0) it has no fault; its window reads over 1.4 %, in the legs, and it is judgedghost; under--between rifethe alignment keeps it and names it a ghost; a band at alpha just outside 0.1 to 0.9 is not read. In tests/video/test_inbetween_doubled.py the frame "drawn between, smeared along the step" (the mean of drawings from t 0.35 to 0.65) is no longer among the clean frames: its feet are part-covered over 4.5 % of their window, so it is now judged a ghost (smeared half as far it is not); and in tests/video/test_held_drawings.py and tests/video/test_ghost_retake.py, loops whose frames the stand-in interpolator cross-fades and gives way now also carrybroken-beatamong theirretakereasons (a loop drawn every frame with frames given way, a held loop squeezed past on twos, the filmed-ghost loops), held-drawings and filmed-ghost staying first where they apply. New tests intests/video/test_screen_jump.pyexercise screen jumps synthetically with an outlined body over an outlined bar 80 px wide in the leg rows, sliding by the drawing: a cut on threes whose bar slides 4 px a drawing except one drawing change of 20 px names that one step a jump (not the seam); cuts whose drawing changes are all 4 px name none on ones, twos, and threes; a cut with two 20 px changes names none; a cut that slides out all the way and comes back in one step at the seam names a seam jump; retake records and warning lines are covered for both reasons; and throughvideo-loopandvideo-cycle-alignat the cut's own length, the jump is named with the aligned loop's frames that show it, recorded instrip.json, while a cut whose changes are alike names nothing. Alsotests/video/test_loop_prop_seam_held.pynow expectsscreenamongcycle_align's keys. - Tests:
tests/video/test_loop_part_pop.py(the four bounds flip the pop; flung and stays; a pop over two steps reads as their mean; an ease through a fast bell does not pop; a fist jumping 2.5, 3.5 and 5 % passes the flow and surge readings and is named; a walk whose tail, foot and eye move across the wrap, and a run, have no pop; an ordinary walk is cut to the bytes it was; a cut given whose fist pops is named,retakerecut-or-retake,--unfixed refuserefuses, and underwarnit is the bytes it was; a clip whose fist drifts through every cut keeps the search's cut to the bytes it was,retakeretake; a clip no part pops in is cut to the bytes it was).
v3.3.0 - PyTorch RIFE backend for CUDA and CPU, executor for a GPU on another machine, and Linux CPU and cloud T4 release lanes
Upgrading from 3.2.0: Defaults stay unchanged, cache keys update once, reports show the backend, install checks model hashes, and schemas are unchanged. With SPRITE_GEN_RIFE_BACKEND unset (the default), RIFE is the rife-ncnn-vulkan binary as before. Its frames are the same bytes as 3.2.0. Measured: the binary's frames and sixteen-pass readings through the changed engine equal the old engine's, byte for byte. A --between-cache directory kept by 3.2.0 is made again once. The key now names the backend (backend: "ncnn"). The engine's rife.py changed, and its sha256 is part of the key anyway. Reports take interpolator.kind from what made the frames: rife-ncnn-vulkan as before for the binary, or rife-torch for the new backend. The overlapped wrap's and the seam bridge's records count binary_calls for the binary as before, or runs for the torch backend. SPRITE_GEN_RIFE_EXECUTOR (new) is unset by default, and RIFE runs in this process. sprite-gen rife install now checks the model's two files (rife-v4.6/flownet.param, flownet.bin) against pinned SHA-256 after unpacking, for either backend. A model that differs installs nothing. The line a missing RIFE is reported with (install in records, warnings) is sprite-gen rife install for the binary. Where the torch backend is chosen, that line is: pip install "sprite-gen[torch]" && sprite-gen rife install --backend torch. No command-line flags of video-loop / video-cycle-align / video-set change. No restoration schemas change: source-restoration-v5, repair report schema_version 4, comparison schema_version 6.
- New: RIFE's torch backend runs rife-v4.6 in PyTorch for compute GPUs without Vulkan.
SPRITE_GEN_RIFE_BACKEND=torchruns the same rife-v4.6 in PyTorch (sprite_gen/video/rife_torch.py). It serves a GPU the binary cannot run on: rife-ncnn-vulkan needs Vulkan, and a GPU offered for compute alone (CUDA with no Vulkan driver) has none. The network is rife-v4.6's IFNet written again from Practical-RIFE'sIFNet_HDv3(MIT, notice in NOTICE). Its weights are read out of the binary's own model files (SHA-256 pinned, the binary's float16 weights), with no other download. One run does what one call of the binary does with-x -z. The pair is turned eight ways and run both ways in time, with flows averaged at each of four levels. The loop follows rife-ncnn-vulkan'sRIFE::process_v4(MIT, notice in NOTICE).SPRITE_GEN_RIFE_DEVICEnamescuda(default) orcpu.SPRITE_GEN_RIFE_TTAmeans the same for both backends. The default augmentation stays-x -z. To install:pip install "sprite-gen[torch]"(new extra:torch>=2.13.0,<3). Then run:sprite-gen rife install --backend torch(new flag; defaults toSPRITE_GEN_RIFE_BACKEND). This unpacks the model, and makes a check frame through PyTorch onSPRITE_GEN_RIFE_DEVICE. It reads the model only, so a Linux ARM machine the binary does not run on is not refused. A CPU-only host installs PyTorch's CPU build first:pip install torch==2.13.0 --index-url https://download.pytorch.org/whl/cpu(192 MB, against the CUDA build's 527 MB plus its CUDA libraries). Nothing falls back. With torch chosen the binary is never looked for or run.cudawhere PyTorch finds no CUDA is refused naming why (a CPU-only PyTorch, or a CUDA that finds no GPU) and does not run on the CPU.mps(Apple's GPU) is refused (no lane measures it; on a Mac the binary runs on the GPU already). A backend or device named wrong is refused. A device that fails as the network is put on it or as a frame runs (out of its memory, its driver or CUDA failing) is a RIFE that fails, in PyTorch's own words: the loop fails with its record, and the install's check frame fails. PyTorch not installed, or no model where the backend looks (SPRITE_GEN_RIFE_MODEL, else the install root), is RIFE not installed, as the binary missing is. Under--repair autothe loop is cut as filmed with the warning, and its record names the torch install line. On CUDA each frame runs with cuDNN deterministic, its benchmark off and convolutions in IEEE float32 (no TF32). The same frame twice is the same bytes on one GPU, driver and PyTorch. What made a frame is the RIFE's identity: backend, model bytes loaded, network code, PyTorch, on CUDA the GPU, driver, CUDA, cuDNN and those settings; on the CPU its instruction set. Because of this identity,--between-cachenever hands one backend's or GPU's frame to another. Measured on synthetic walkers: Seven walker pairs (clean, outline lost, ghost, torn, a cross-fade to look at) get the same verdicts from the binary on an Apple GPU, the binary on Mesa llvmpipe and the torch backend on a CPU. The torch frame lies 0.005 to 0.052 of 255 on average from the binary's Apple GPU frame. The binary's own llvmpipe frame lies 0.007 to 0.25. A 960 x 960 frame of a synthetic walker with-x -z: On an Apple M4 Max CPU (12 threads), 3.3 to 3.6 s; the binary on that Mac's GPU takes 1.27 to 1.37 s. In a Modal container of two CPUs (the app's job size), 22.6 to 28.5 s on two threads; the binary on Mesa llvmpipe in the same container takes 127.7 to 131.5 s. On an NVIDIA T4 rented from Modal (CUDA), 1.36 to 1.41 s. The torch backend's frames are not the binary's bytes, which is one reason the binary stays the default. loop-repair section 1 - New: a host with no GPU sends the torch backend's frames to a GPU elsewhere (
SPRITE_GEN_RIFE_EXECUTOR). The host names a send of its own,SPRITE_GEN_RIFE_EXECUTOR=module:attr: a function from a request's bytes to its answer's. It reachessprite_gen.video.rife_torch.serveon the GPU's machine, the same sprite-gen with PyTorch and the model installed there. The engine knows nothing of what carries the bytes, and the host needs no PyTorch. A frame is one call (its two runs made there), and a read is one call (its two runs and sixteen passes, the passes reduced there to how far they disagree). A RIFE asks the executor what it is once, as it is made (the probe, which takes the cold start), so avideo-loopmakes at most 53 calls. The RIFE holds that answer for its life, and every request carries it. An executor that is not it any more (another GPU, driver or image) makes nothing, and the RIFE fails naming what differs (gpu: Tesla T4 -> NVIDIA L4). An answer from another identity is not handed on. So one RIFE never hands on frames of two GPUs, and a frame taken from--between-cacheis the frame it would make; the next RIFE asks again and keys its frames anew. Refused: an executor named with the binary's backend or withSPRITE_GEN_RIFE_DEVICE(the device is the executor's), a send that cannot be imported, and an executor whoserife.pyor protocol is another (run the same sprite-gen on both sides). A send that raises, an answer that does not read (not the format, damaged or cut short on the way, or not the frame's size) and the executor's own failure are each a RIFE that fails, in its words; nothing is asked again or run elsewhere. The host names one GPU type for the executor (no fallback list) and does not deploy it anew while a run goes on. Requests and answers are a compressed NumPy archive, read withallow_pickle=False, each member whole so its CRC-32 is checked before its array is read: an answer damaged on the way hands on no other pixels. Reports nameexecutorand the executor'sdeviceandgpu; the overlapped wrap countsrunsandexecutor_calls. Measured on an NVIDIA T4 rented from Modal, from a host of two CPUs without PyTorch: a 960 x 960-x -zframe of a synthetic walker takes 1.49 to 1.52 s, 0.1 to 0.2 s more than in the T4's own process, a read as long, and the frames and readings are the same bytes as there. loop-repair section 1 - Lane:
scripts/linux_lane.shtests PyTorch 2.13.0 CPU after the suite. After the suite, PyTorch 2.13.0 CPU is installed into the same environment. It runssprite-gen rife install --backend torch's check frame. It runs every test markedtorch_rifewithSPRITE_GEN_RIFE_DEVICE=cpu, with none skipped.--rife-onlyruns the same.--rife-unmeasuredletstorch_rifetests skip as it letsreal_rifeones. CUDA is not measured by this lane. - Lane:
scripts/t4_lane.pytests the torch backend on an NVIDIA T4, rented from Modal.modal run scripts/t4_lane.pybuilds the checked-out commit's tree into an image as the Linux lane installs a clean clone: Python 3.14, PyTorch 2.13.0 from PyPI (its Linux wheel is the CUDA 13 build), the tree with.[dev], and the model bysprite-gen rife install --backend torch, where the engine looks for no binary. On one T4 it makes the install's check frame on CUDA and runs every test markedtorch_rifeand notreal_rifeon CUDA, with none skipped.--whole-suitefirst runs the whole suite in that environment, PyTorch in it, as the Linux lane's RIFE-less run does. A commit passes the lanes where the Linux lane passed at it and one T4 lane run at it exited 0. release - Tests:
tests/video/test_rife_torch.py(the eight ways undo themselves and are the single passes' eight turns; flows of a textured patch run alone each of the sixteen ways and turned back point alike, where a wrong sign, a transpose's x/y, or a backward swap puts one elsewhere;-zand-xgive the same frame the other way in time and flipped; the install check frame's disc lands half way; the model loads strict and other bytes are refused by SHA-256; the same frame twice is the same bytes and the identity names what makes it; seven recorded synthetic walker pairs intests/fixtures/rife-walkersare judged as the binary judged them with no binary, the frame within twice the binary's own GPU-to-GPU gap, and alike to this machine's binary where both run; a device that fails as the network is put on it or as a frame runs (out of its memory, its driver, CUDA not starting, a CUDA call deferred to its start) is a RIFE that fails in PyTorch's words, a TypeError there is raised as it is, a loop whose device fails as the network is put on it fails with its record, and the install's check frame fails; without PyTorch: torch chosen and not installed is RIFE not installed and the binary is never run, a loop's record names it, a backend or device named wrong is refused before anything is looked for, cuda where there is none is refused, a model not the pinned one is refused; with a runner stood in: reports name rife-torch and count runs, the loop and the alignment name the torch backend, and a frame kept by one runner is not taken for another);tests/video/test_rife_executor.py(a frame is one call and a read one call, and the RIFE probes once as it is made, their bytes the same device's in this process with this host's augmentation; every request names the engine code and the identity held; the host runs without PyTorch; the identity is the executor's as the RIFE was made; a T4 frame kept is the RIFE's own after the executor turns L4, which it then refuses to make anew, and the next RIFE misses and keeps the L4 frame under its own key; an executor whose GPU, driver, network code, weights, PyTorch, cuDNN or determinism changed makes nothing, the field named; an answer from another identity is neither handed on nor kept; another container of the same identity runs on, and the next RIFE takes every frame with its probe alone; a T4 and L4 pool is refused at the first L4 request; a frame made while this host's augmentation changed is not kept; other engine code or another protocol is refused before anything loads; a request that does not read, is pickled or was damaged on the way is answered so, in the reading's words; a send, an answer or an executor that fails is a RIFE that fails, in its words; an answer damaged in a member's local header, a compressed block, an array's header or its own bytes, or its end record, or cut short, is a RIFE that fails in the words of what reading it raised, which is its cause, and undamaged is the frame made here; each byte of the probe's, a frame's and a read's answer damaged in turn fails the RIFE or reads as it was made, nothing else raised and no other pixels handed on; a reading that cannot read whatpackwrites raises as it is, a fault of the code; an answer that is not bytes does not read; an executor named with the binary, with a device, or not there is refused and the binary never runs; a loop names the executor, and a loop whose executor's answer was damaged on the way fails with its record (failed, in the decompressor's words, the gait fallback's frames removed); markedtorch_rife:rife_torch.servemakes the frame and the read of the backend in this process, loaded once);tests/video/test_rife_install.py(a zip whose model is not the pinned one installs nothing for both backends;--backend torchinstalls on a machine the binary does not run on and checks its frame through torch);tests/release/test_lane_rife_collection.py(a test RIFE decides carriesreal_rifeortorch_rife);tests/release/test_t4_lane.py(the T4 lane installs the PyTorch and the Python the Linux lane does); new pytest marktorch_rife(skipped where PyTorch, the model or the named device is missing).
v3.2.0 - Cycle alignment hole and doubled faults, and loop repair for size held cuts
Upgrading from 3.1.0: video-cycle-align now gives way to the nearer source frame on made frames with enclosed limb holes under --between auto, changing only alignment outputs with such holes while made frames without them and all outputs from video-loop, video-loop-compare, and video-loop-repair keep their bytes.
- New:
video-cycle-alignnow reads a newholefault on frames RIFE makes between source frames and gives way to the nearer source frame. On every frame RIFE makes between two source frames,video-cycle-alignreads a new fault,hole("a hole through a limb"). Under--between auto(the default) a made frame with this fault gives way to the nearer source frame, like the other faults (smear,outline,ghost); under--between rifethe frame is kept and named in the warnings.video-set --align-cycles autoruns the same alignment. RIFE runs a frame's colour and its coverage as two separate runs. Where a step opens a gap between the legs in one source frame and not the other, the coverage run can carry that gap into a leg the colour run keeps whole: the made frame shows a transparent band through the leg with the leg's fill on both sides. Nothing is added (nosmear), there is no part coverage (noghost), and the leg's own fill is the only line round the band. The faultoutlineneeds both outline readings: the dark line (outline_loss) counts a fill darker than 70/255 (dark tights, a boot) as outline, and the rank reading (outline_shift) reads the band's edge as lost only where it is 50/255 lighter than the source frames' lines at the same rank, which light lines elsewhere on the art (fur, hair drawn without a dark line) can hide; so such a frame passes every fault and is delivered. The readingrife.hole(made, a, b, t)measures pixels under solid (alpha under 0.5) that the outside of the picture cannot reach without crossing its solid body (enclosed holes). A pixel of a made frame's hole is the source frames' own when either source frame is under solid within 4 px (rife.HOLE_REACH, a square neighbourhood) of where that pixel lay at that frame's time, read in place (the background, still, and a gap kept, or opened by a step where the frame that shows it open has it) and carried with the whole figure along the motion the two source frames show for the whole figure. Where a made frame sits at fractiontof the way from source frame a to source frame b, a pixel of it lay in a attof the motion back and lies in b at1 - tof it on (rounded so the two are the whole motion apart). The motion is measured only from the two source frames, never from the made frame and never from RIFE's own flow: over the box round all three frames' solid bodies, each pixel is read in a where it lay and in b where it lies for a candidate motion; the motion whose mean absolute difference of premultiplied colour and coverage over the box is least is the motion there, ties going to the smaller motion. It is followed up to 20 % of the body's height each way (rife.HOLE_TRAVEL, 0.2), coarse to fine: the whole range on a level pooled in square blocks of a power of two, the smallest for which the range is at most 24 px each way (rife.HOLE_COARSE, 24), then within 2 px of twice the coarser motion on each finer level, down to the pixel. A hole those two readings leave is the source frames' own, whatever carried it (a part moving over a body that stays, plain or patterned, turning, growing, sheared or swinging), where it is one hole of each source frame. A hole is an 8-connected piece of a frame's enclosed pixels: the made frame's count where they keep a pixel opened by a 5 px square, a source frame's where they keep one opened by a 3 px square (rife.HOLE_SOURCE_THICK, 3). Each is read for its area, its centroid, its shape (the logarithms of its pixels' two principal second moments, each plus 1/12, over its area, which turning and growing keep) and the colour round it (the mean premultiplied colour of the frame's solid pixels 5 to 8 px out). The two source frames' holes: areas within 4 times of each other (rife.HOLE_PAIR_AREA, 4.0), shapes within 2 times on each moment (rife.HOLE_PAIR_SHAPE, 2.0), colours within 0.12 on each channel (rife.HOLE_COLOUR, 0.12), centroids at most sqrt(2) times the reach and 4 px apart. The made frame's hole: area within a quarter of their range (rife.HOLE_AREA, 0.25), shape within 1.3 times of theirs (rife.HOLE_SHAPE, 1.3), colour within 0.12 of each, and centroid within 4 px and 0.1 of their distance (rife.HOLE_PATH, 0.1) of the point atton the line between theirs. Pairs are taken one to one: no hole of any frame is in two pairs taken, so each source frame's hole explains one of the holes paired. A hole of the made frame that the first two readings give the source frames takes no pair, being theirs already, and the pairing reads only the holes those readings leave: of the sets of pairs that can be taken together, the set taken pairs the most holes, and of those, has the least summed cost (the same frames always giving the same set), so alike holes moving together each keep their own two. Pairs sharing a hole form a group, read apart: an exact search first asks whether one set pairs every hole of the group, cutting branches where the holes left cannot each keep a hole of each source frame of their own; where it finds one, every hole of the group is paired, and where there is none, a second exact search finds the set pairing the most. Each search takes at most 5000 steps per group (rife.HOLE_PAIR_STEPS, 5000): where the first runs past them, the second runs; a group whose second search runs past them pairs none of its holes, and the frame gives way to the nearer source frame. The made frame is never used to measure a motion, and RIFE's flow is never read. The motion is read only on frames that keep a hole after the in-place reading, and the pairing only on frames that keep one after the whole figure's motion; a frame with no hole in place is read with no further cost. The regions at least 5 px thick (rife.HOLE_THICK, opened by a 5 px square, so a pinhole or an antialiased crevice a pixel or two wide is not counted) are taken after each step, as a fraction of the made frame's solid pixels, or 0 where the frame has no solid body. The faultholeis any reading over 0 (interpolation_quality.HOLE_WARN, 0.0). A band cut through a leg's edge, reaching the outside, is not an enclosed hole and is left to the outline readings as before. - Report fields: each row of a loop's
smearlist in thevideo-cycle-alignreport (and incycle_aligninstrip.json) gainshole. A frame given way for it carriesfaults: ["hole"]andmethod: "nearest", and gets a line inwarnings; the line says the frame opened a transparent hole inside its outline over the given share of its body, at least 5 px thick, where neither source frame beside it has one, a gap through a limb, and that the nearer source frame was taken there. The--betweenhelp says the same. - Python callers: new
rife.hole(made, a, b, t),rife.HOLE_TRAVEL(0.2),rife.HOLE_COARSE(24),rife.HOLE_REACH(4),rife.HOLE_THICK(5),rife.HOLE_SOURCE_THICK(3),rife.HOLE_PAIR_AREA(4.0),rife.HOLE_PAIR_SHAPE(2.0),rife.HOLE_AREA(0.25),rife.HOLE_SHAPE(1.3),rife.HOLE_PATH(0.1),rife.HOLE_COLOUR(0.12), andrife.HOLE_PAIR_STEPS(5000); newinterpolation_quality.HOLE_WARN(0.0);interpolation_quality.faults(measure)returns"hole"where the measure carries aholereading overHOLE_WARN, and measures without aholekey are judged as before. - Output changes: an alignment whose made frame has an enclosed hole 5 px thick or more that neither source frame beside it has within 4 px, in place, carried by the whole figure's motion, or paired with one hole of each source frame as above, now delivers the nearer source frame at that cell instead of the made frame, and counts it in
replacedandnearest_atrather thanmade_by_rifeandmade_at. Made frames without such a hole, and frames whose holes the source frames have, in place, carried or paired, are delivered as in 3.1.0 with the same bytes; the report gainsholeon every made frame. Synthetic numbers (the figure of the tests below): the frame between with a band 8 px wide and 40 px tall through its far leg readsoutline_loss0,outline_shift11.3 % (so nooutlinefault, which needs both over 5 %),ghost0, andhole2.69 %; in 3.1.0 it is kept, now the nearer source frame is taken. The frame drawn between, the same with the arm's gap moved 3 px, and the same with a pinhole 3 px wide through the leg readhole0 and are kept. A frame whose hole both source frames have, carried by a part (moving over a body that stays, plain or patterned, turning, growing, sheared or swinging within reach), is delivered as in 3.1.0 with the same bytes. Figure 5: a body that stays, patterned, with a part on it and a hole through the part's middle, the part moved from one source frame to the next, each frame between drawn exactly at its place. (i) The checkpoint validator's frame: a body 200 by 180 px with stripes 3 px wide every 6 px (a lighter colour by 40 levels), on a 260 by 220 px canvas, a part 24 px square with a hole 10 px square, moved 32 px across: the in-place reading leaves the hole whole, 100 pixels or 0.28 % of the body, and the whole figure's motion is 0; it is one hole of each source frame, alike and on its way, so it is paired:hole0, and both made cells are kept as made, byte for byte. (ii) A body 240 by 260 px on a 300 by 300 px canvas in five patterns (stripes 3, 2 and 6 px wide every 6, 4 and 12 px running up and down; stripes 3 px wide every 6 px running across; checks 4 px square) at contrasts 15, 40 and 120, parts 24, 40 and 60 px square with holes 10, 17 and 25 px square: moved 32 and 48 px across and diagonally at t 0.5 (the moves listed in the test), these frames, and the same three parts moved 16, 32 and 48 px across and diagonally at t 0.25 and 0.75 over the 3 px stripes at contrast 40, every one readhole0. Resampled to eight frames (t 0.25, 0.5 and 0.75 each way), parts of 24, 40 and 60 px moved 32 px diagonally and the 24 px part moved 48 px over stripes at contrast 120 keep every made frame, byte for byte. Figure 6: a torso 120 by 260 px that stays, patterned in blocks 4 px square each lighter by its own whole number up to 200 levels, with an arm beside its right edge: the upper arm and the forearm lie along that edge and are joined by the arm's outer side, so the gap between arm and torso, 16 by 12 px, has the torso's edge on its left and the arm on its other three sides; the arm reaches 48 px above and 52 px below the gap and moves 40 px down from one source frame to the next. The gap lies where the arm covers it in the other source frame, so the in-place reading leaves it, and the whole figure's motion is 0; it is one gap of each source frame, alike and on the arm's way, so it is paired:hole0 at t 0.25, 0.5 and 0.75, and resampled to eight every made frame is kept, byte for byte. A frame with a gap only one source frame opens, on a part moving over a body that stays, plain or patterned, which neither the in-place reading nor the whole figure's motion carries and which has no hole in the other source frame to pair with, gives way to the nearer source frame where 3.1.0 kept it. The boundary, pinned by a test: a part 30 px square moving 32 px across a body that stays, a hole 14 px square open through it in one source frame and closed in the other, 8 px square in the frame between (half open): over a plain body and over the 3 px stripes alike it readshole0.10 % (its 64 pixels) and both made cells are given way to the nearer source frame, withfaults: ["hole"]. Figure 7: the plate of the tests (a body 240 by 260 px that stays, striped or plain, with a plate on it and a gap through the plate, 11 by 31 px, each frame between drawn exactly at its place). The third checkpoint validator's frame, the plate turning 60 degrees as it moves 48 px over the stripes, readshole0 and is delivered as in 3.1.0, both made cells byte for byte, resampled to four and to eight; so are the plate turned 90 degrees, grown 2 times and sheared by 0.6 as it moves 48 px, and swung 45 degrees, over the stripes, and 125 such frames readhole0. A frame between with a hole unlike both source frames' (the gap drawn 16 by 40 px:hole1.04 %; drawn 18 by 18 px: 0.52 %; the plate growing 2.2 times as it moves 48 px, the source frames' gaps more than 4 times apart in area: 0.55 %), off its way (the plate drawn 12 px across it: 0.55 %; drawn where it is at t 0.8 in a frame made at t 0.5: 0.30 %), or out of reach (the plate swung 60 degrees, its centre moving 100 px, where 77.5 px is let through on this body: 0.55 %; the plate moving 80 px: 0.55 %) gives way to the nearer source frame withholeamong its faults. Figure 8: the plate 120 by 40 px with a row of four holes 8 px square, 24 px apart, moving 32 px down: the frame between drawn exactly, and with the row a pixel taller, readhole0 and are delivered as in 3.1.0; with one hole more (midway between two, between the last two, past the end, or one of the row moved to a midway) it reads 0.10 % and gives way to the nearer source frame. Figure 9: on the same striped body, a plate with a row of two, three or four holes 8 px square, 12 px apart, moving on a curved way, int(40 t + 20 t (1 - t)) px across and int(32 t) px down at time t, the plate moving with the holes or staying while they move through it (with two holes it is the fourth checkpoint validator's frame): the frame between drawn exactly readshole0 and is delivered as in 3.1.0, both made cells byte for byte, for two, three and four holes, the plate moving or staying; with one hole more before the row, or with the row's last hole shut in the second source frame, it reads 0.10 % and gives way to the nearer source frame. Figure 10: on the same striped body, a plate 40 by 90 px with a column of three holes 8 px square, 24 px apart, moving 32 px down, the middle hole shut in the second source frame: the frame between drawn exactly readshole0 and is delivered as in 3.1.0: its middle hole, one more than the second source frame has, lies against holes of both source frames and the in-place reading takes it for theirs; the last hole pairs with its own two. Figure 11: on the same striped body, a plate 105 px square with a hole 8 px square that the first source frame and the frame between have in place and the second source frame shuts, beside a hole moving 52 px across and 48 px down, drawn at its exact midpoint 10 px from the first (the fifth checkpoint validator's frame): the frame between readshole0 and is delivered as in 3.1.0, both made cells byte for byte, and so with the hole in place kept by the second source frame instead. Figure 12: a body 200 by 260 px outlined in black on a 400 by 400 px canvas, moving whole, with holes through it; what the reading does not tell: the body moving 32 px down with a row of four holes 8 px square, 24 px apart, and one hole more midway between the middle two readshole0 and is delivered as in 3.1.0 (so is figure 8's row standing still, drawn a pixel taller, with one hole more midway); moving 48 px across and 48 px down with a gap 5 by 30 px and one gap more 10 px beside it in the frame between, it readshole0 and gives way foroutline, as in 3.1.0; with the gap more 11 px beside, and a gap 8 px wide with its twin 13 px beside it, they readhole0.29 % and 0.45 % and give way as in 3.1.0, now withholeamong their faults besidesoutline. The jump repair ofvideo-loop, its eased retime and overlapped wrap,video-loop-compare, andvideo-loop-repairdo not readhole; their measures and outputs are as in 3.1.0. A--between-cachedirectory written by 3.1.0 is not taken from by this version: the code ofrife.pyis part of what a kept frame is keyed by, so those frames are made again. - Tests: new
tests/video/test_inbetween_hole.py, synthetic only: figure 1 (a 160 by 200 px figure of rectangles outlined in black, legs filled darker than 70/255, the near leg drawn over the far one, an arm joined to the body above and below with an 8 px gap between them in every frame; one source frame with its legs side by side, the other with a gap between them) checks that the band through the far leg reads as a hole over exactly its own 320 pixels as a share of the solid body, and the drawn frame, the arm's gap, that gap moved 3 px, a 3 px pinhole and an empty frame read 0; that the readings before this one pass the band (outline_loss0,outline_shiftover 5 %,dark_excessbelow 0,ghost0,partial_excess0, no fault) and that withholethe fault is["hole"]; that resampling the two frames to four under--between autotakes the nearer source frame at both made cells (cells 1 and 3) with the fault named in the warning words, while--between rifekeeps them named; and that the clean frame and the frame with the moved arm gap are delivered as the very frame made. Figure 2 (a body 120 by 180 px of one colour with a gap 8 by 40 px through it, on a 240 by 220 px canvas, moved whole from one source frame to the next by 0, 4, 8, 12, 24 and 32 px, across and diagonally) checks that at every move it is resampled to four with both made cells delivered as the very frame made, no fault, and readshole0, each source frame moved half the way giving the frame between byte for byte. Figure 3 (a body 90 px wide over two legs 24 px wide, each standing in a boot that reaches under the other leg, so a gap a step opens between the legs is closed by the boots below; in one source frame the legs touch, in the other they are parted), still and moving 30 px between source frames, is kept the same way and reads 0; and moving with an 8 by 40 px band through its body, it reads exactly its 320 pixels as a share of the solid body, in either order of the source frames, with both made cells given way to the nearer source frame andholeamong their faults. Figure 4 (a body 200 by 180 px of one colour that stays, with a part on it 40 px square and a hole 14 px square through the part, the part moving 32 px from one source frame to the next) is kept the same way and reads 0. Figure 5 (a body that stays, patterned, with a part on it and a hole through the part's middle, the part moved from one source frame to the next, each frame between drawn exactly at its place: the checkpoint validator's frame with a body 200 by 180 px with stripes 3 px wide every 6 px, a lighter colour by 40 levels, on a 260 by 220 px canvas, a part 24 px square with a hole 10 px square, moved 32 px across; and a body 240 by 260 px on a 300 by 300 px canvas in five patterns, stripes 3, 2 and 6 px wide every 6, 4 and 12 px running up and down, stripes 3 px wide every 6 px running across, and checks 4 px square, at contrasts 15, 40 and 120, parts 24, 40 and 60 px square with holes 10, 17 and 25 px square): figure 5's validator frame resampled to four, and its parts of 24, 40 and 60 px moved 32 px diagonally and the 24 px part moved 48 px over stripes at contrast 120 resampled to eight, keep every made frame as made; the wide grid of figure 5 (every pattern and contrast at each listed move at t 0.5, and the three parts moved 16, 32 and 48 px at t 0.25 and 0.75) readshole0 and is marked slow, so it runs withpytest --full. Figure 6 (a torso 120 by 260 px that stays, patterned in blocks 4 px square each lighter by its own whole number up to 200 levels, with an arm beside its right edge: the upper arm and the forearm lie along that edge and are joined by the arm's outer side, so the gap between arm and torso, 16 by 12 px, has the torso's edge on its left and the arm on its other three sides; the arm reaches 48 px above and 52 px below the gap and moves 40 px down from one source frame to the next) readshole0 at t 0.25, 0.5 and 0.75 and keeps every made frame resampled to eight. The boundary test (a part 30 px square moving 32 px across a body that stays, a hole 14 px square open through it in one source frame and closed in the other, 8 px square in the frame between) checks that the half-open gap on the moving part, over a plain body and over the stripes, reads its 64 pixels as a share of the body and gives both made cells way to the nearer source frame withfaults: ["hole"]. Figure 7: a body 240 by 260 px on a 300 by 300 px canvas that stays, in stripes 3 px wide every 6 px (lighter by 40 levels) or plain, with a plate on it (|u| < 24 and |v| < 28 px in its own axes) and a gap through the plate (|u| < 6, |v| < 16), each frame between drawn exactly at its place in one motion: the plate's centre moving across as the plate turns, grows or is sheared about it, or the plate swinging from a point 100 px above its centre. One test checks that the third checkpoint validator's frame (the plate turning 60 degrees as it moves 48 px over the stripes), resampled to four, keeps both made frames as made, and resampled to eight (t 0.25, 0.5 and 0.75 each way) every one; that the plate turned 90 degrees, grown 2 times and sheared by 0.6 as it moves 48 px, and swung 45 degrees, resampled to four over the stripes, keep both made frames; and that over the plain body each of these readshole0. A test marked slow (it runs withpytest --full) checks that 125 frames readhole0: the plate turned 0 to 90 degrees, grown 1.1 to 2 times or sheared by 0.15 to 0.6 as it moves 0, 24 or 48 px, or swung 10 to 45 degrees, over both bodies at t 0.5, and turned as it moves over the stripes at t 0.25. A boundary test checks that, on the plate over either body, a frame between with its gap drawn 16 by 40 px or 18 by 18 px, with the plate drawn 12 px across its way or where it is at t 0.8 in a frame made at t 0.5, with the plate growing 2.2 times as it moves 48 px (the source frames' gaps more than 4 times apart in area), with the plate moving 80 px, and with the plate swung 60 degrees, gives both made cells way to the nearer source frame withholeamong their faults. Figure 8: the same body with a plate 120 by 40 px on it and a row of four holes 8 px square, 24 px apart, through the plate. Its test checks that, the plate moving 32 px down over either body, the frame between drawn exactly and the same with the row a pixel taller keep both made frames as made; that with one hole more midway between two of the row's, between the last two, past the row's end, or with one of the row's moved 12 px to a midway, both made cells give way to the nearer source frame withholeamong their faults; and that, the plate standing still, the row drawn a pixel taller keeps both made frames. Figure 9: the striped body (240 by 260 px that stays, stripes 3 px wide every 6 px) with a plate on it and a row of two, three or four holes 8 px square, 12 px apart, through the plate, moving on a curved way from one source frame to the next, int(40 t + 20 t (1 - t)) px across and int(32 t) px down at time t; the plate moves with the holes or stays while they move through it. With two holes it is the fourth checkpoint validator's frame. One test checks that, resampled to four, the frame between drawn exactly keeps both made frames as made, for two, three and four holes, the plate moving or staying. Figure 10: the same striped body with a plate 40 by 90 px on it and a column of three holes 8 px square, 24 px apart, through the plate, the plate moving 32 px down from one source frame to the next. A boundary test checks that, with two and four holes, the plate moving or staying, a frame between with one hole more before the row, and a frame between whose second source frame has the row's last hole shut, give both made cells way to the nearer source frame withholeamong their faults; and that withrife.HOLE_PAIR_STEPSset to one step, both searches (the search for a set pairing every hole, and the search for the set pairing the most) run past it and the frame between of two holes gives both made cells way as well. Figure 11: the striped body with a plate 105 px square on it, through it a hole 8 px square that the first source frame and the frame between have in place and the second source frame shuts, beside a hole moving 52 px across and 48 px down, drawn at its exact midpoint 10 px from the first; the fifth checkpoint validator's frame. Its test checks that, resampled to four, both made frames are kept as made, and so with the hole in place kept by the second source frame instead. Figure 12: a body 200 by 260 px outlined in black on a 400 by 400 px canvas, moving whole, with holes through it. Its test pins what the reading does not tell: it checks that the body moving 32 px down with a row of four holes 8 px square, 24 px apart, and one hole more midway between the middle two keeps both made frames as made, and so do figure 8's row standing still, drawn a pixel taller, with one hole more midway, and figure 10's frame with the middle hole shut in the second source frame; that, the body moving 48 px across and 48 px down with a gap 5 by 30 px, one gap more 10 px beside it in the frame between readshole0 from either source frame to the other; and that the gap more 11 px beside, and a gap 8 px wide with its twin 13 px beside it, give both made cells way withholeamong their faults. The test on triples alone: twenty alike holes, each with its own two holes and up to five more pairs near its own at seeded random costs. It checks that all twenty are paired, and that none is where the search for a set pairing every hole runs past the steps (the search for the set pairing the most runs past them on this group).
Upgrading from 3.1.0: video-cycle-align now gives way to the nearer source frame on made frames with double outlines under --between auto, changing only alignment outputs with such outlines while made frames without them and all outputs from video-loop, video-loop-compare, and video-loop-repair keep their bytes.
- New:
video-cycle-alignnow reads a newdoubledfault on frames RIFE makes between source frames and gives way to the nearer source frame. On every frame RIFE makes between two source frames,video-cycle-alignreads a new fault,doubled("a double outline"). Under--between auto(the default) a made frame with this fault gives way to the nearer source frame; under--between rifethe frame is kept and named.video-set --align-cycles autoruns the same alignment. Where RIFE's flow does not follow a line (the top of a boot one source frame tilts and the other plants), it can fade the line out in place instead of moving it, and the made frame shows that source frame's line, lighter, in its own place, beside the line the frame drew: a double outline. Its coverage is whole (noghost), nothing darker is added (nosmear), the line is inside the body and the edge keeps its line (nooutline), and there is no hole; the cross-fade reading (crossfade) only names frames to look at. So such a frame passed every fault and was delivered. The readingrife.doubled(made, a, b): a frame's line is its solid pixels darker by more than 50/255 than its own luma closed by a square 2.5 % of the made frame's body height wide (rife.DOUBLED_WIDE, 0.025; a stroke narrower than that is a line, a dark fill wider is not). A pixel of one source frame's line is left at part strength where the three frames are solid, the other source frame draws no line within 4 px (rife.DOUBLED_SHARED, 4) and is lighter there by more than 50/255, and the made frame is darker than the other by more than 50/255 (still seen) but by no more than 0.8 of the line's contrast (rife.DOUBLED_PART, 0.8), there and at its darkest pixel within 2 px (no line at full strength beside it). Such pixels count in regions 3 px thick (rife.DOUBLED_THICK, 3); widened by 3 px, those that touch make one run; the reading is the longest run's length (sqrt(12) times the root of its pixels' larger second moment) over the made frame's body height. The faultdoubledis a reading over 0.03 (interpolation_quality.DOUBLED_WARN). Kept as the source frames' own: a line both draw within 4 px of each other, at any strength; a line carried at more than 0.8 of its contrast (the source frame's own drawing); the soft edge of a line the flow moved (the full line lies within 2 px); a line left less than 50/255 darker than the other source frame there (not seen); a dark patch wider than the closing; a run of 3 % of the body or less. A line only one source frame draws (a crease that comes or goes), left at part strength, is a double outline too. - Report fields: each row of a loop's
smearlist in thevideo-cycle-alignreport (and incycle_aligninstrip.json) gainsdoubled. A frame given way for it carries"doubled"infaultsandmethod: "nearest", and gets a line inwarningswith these words: "left a line one source frame beside it draws at part strength in its own place, over a run 10.21 % of its body high, a double outline, so the nearer source frame was taken there (--between auto)". The--betweenhelp names it. - Python callers: new
rife.doubled(made, a, b),rife.DOUBLED_WIDE(0.025),rife.DOUBLED_SHARED(4),rife.DOUBLED_PART(0.8),rife.DOUBLED_THICK(3); newinterpolation_quality.DOUBLED_WARN(0.03);interpolation_quality.faults(measure)returns"doubled"where the measure carries adoubledreading overDOUBLED_WARN, and measures without adoubledkey are judged as before. - Output changes: an alignment whose made frame shows a double outline over 3 % of its body height now delivers the nearer source frame at that cell instead, counted in
replacedandnearest_atrather thanmade_by_rifeandmade_at. Other made frames are delivered as before with the same bytes; the report gainsdoubledon every made frame. A frame RIFE cross-fades so that both drawings' lines stay at part strength inside the silhouette over a long enough run now gives way too, still named to look at for its cross-fade (look); such frames were kept before because the cross-fade reading is no fault (it also reads over its line on a clean drawing between far-apart drawings, which reads no double outline and is kept). Synthetic numbers (the figure of the tests): a coat over two legs in boots outlined 3 px in near-black, the near boot lifted 18 px in one source frame and planted in the other; the frame drawn between with the first source frame's near-boot lines laid over it at 0.45 of their strength readsoutline_loss0,outline_shift0,ghost0,hole0,crossfade0 anddoubled0.102; in 3.1.0 it is kept, now the nearer source frame is taken. The frame drawn between, blurred, or smeared along the step, a hand moving 60 px over the coat, boots drawn with a second line, a hem drawn with two lines and softened, and a light crease carried at its own strength readdoubled0 and are kept. The jump repair ofvideo-loop, its eased retime and overlapped wrap,video-loop-compare, andvideo-loop-repairdo not readdoubled; their measures and outputs are as before. A--between-cachedirectory written before this version is not taken from: the code ofrife.pyis part of what a kept frame is keyed by, so those frames are made again. - Tests: new
tests/video/test_inbetween_doubled.py, synthetic only: the figure above; checks that the line left at 0.45 passes every earlier reading and readsdoubled0.102, as do both source frames' lines left at half and the colour blended inside the drawing's coverage; that resampling two frames to four under--between autotakes the nearer source frame at both made cells with the fault in the warning's words, while--between rifekeeps them named; that a crease only one source frame draws, left at 0.3 to 0.6, gives way, left at 0.25 reads 0, and the frames that draw it or not keep their bytes; that nine clean, soft or source-drawn frames read 0 and are delivered as the very frame made; that the walker oftests/video/test_crossfade.pykeeps its drawing between far-apart legs (16 to 3 degrees) in grey and black outlines, reading 0, while its cross-fade gives way, and its 10 to 5 degree cross-fade reads 0.0195 and is kept; and where each bound turns (seen at 0.30 of the line's contrast, not at 0.28; part strength up to 0.80, not 0.82; a boot moved 9 px, not 8; a stroke 3 px wide, not a patch 10 px square; a run over 7 columns, 0.0343, not 6, 0.0294), and that a hand smeared back over a source frame's line reads as that line left (0.063).tests/video/test_crossfade.py: the alignment test of the cross-fading stand-in now expects its frames across the legs' long steps to give way underautoas double outlines, still named to look at, and to be kept and named to look at under--between rife; its 10 to 5 degree cross-fade underautois kept withdoubledunder the line.
Upgrading from 3.1.0: video-loop-repair can now restore damaged cells on held fixed cuts by reading source frames through recorded frame holds. Fixed cuts held with --size-hold auto now record per-frame holds in size_hold.cut_frames. A 3.1.0 report of a held fixed cut lacks this record and stays source-processing-unsupported; cut it again with this version to enable repair. A report of a cut that was not held restores as before.
- New: Held fixed cuts can now be restored from source frames. Source projection applies each cut frame's recorded move and
padding_ltrbbefore scrub, small-component cleanup, optional integer body ramp, one shared integer crop, and standard resampling. Unmodified cells must reproduce exactly, and cut frames must matchsource_projectionhashes; a changed move on a replaced cell is refused assource-processing-receipt-mismatch. Reports withoutcut_framesstayunknownandsource-processing-unsupported. Malformedcut_framesexit nonzero without writing a candidate. Cuts with--anchor motion,motion-auto, cycle alignment, wrap blends, or follow warps remain unprojected. - Report fields (
<name>.loop.report.json):size_holdrecordscut_frameson held fixed cuts, giving an ordered list of exact float entries withscale,foot_point_px([x, y]), andlift_px(ornull). - Repair records:
projectionin repair reports and candidaterestorationreceipts gainsize_hold(padding_ltrb,cut_frames) on held cuts, binding proposal IDs to recorded moves. - Python callers: new
gait_fallback.frame_hold(k, measured, lift=None)returns a frame's move dict, andgait_fallback.hold_frame(frame, move, pad)applies it to one frame.gait_fallback.undo_scaleuses both and preserves previous byte outputs. - Output changes: on a synthetic walk away (15.0 % smaller over 73 frames, feet 20 px higher) cut on frames 24 to 47 with
--anchor body, projection reproduces 24 of 24 cells. Restoring smeared cell 9 (25 pixels) yields verdictimprovedand recovers the cell byte for byte: 119 px tall with feet on row 129 (held loop cells run 119 to 120 px tall, feet on rows 129 to 130; cut with--size-hold off, cell 9 is 111 px tall on row 120, and the loop spans 107 to 113 px tall, feet on rows 116 to 122). In 3.1.0 this request endedunknown,source-processing-unsupportedwith no candidate. For six synthetic cuts (174 files),video-loopmatches 3.1.0 exceptproducerandsize_hold.cut_frames. For five non-held cuts (110 files),video-loop-repairmatches 3.1.0 exceptmeasurement_engineand candidate report digests. - Tests:
tests/video/test_held_cut_restoration.pychecks that the synthetic walk away cut on frames 24 to 47 with--anchor bodyrestores smeared cell 9 byte for byte with verdictimproved, matching first-cell height and row while the filmed source frame is under 0.95 height and 8 px or more higher; checks exact cell reproduction; checks that reports lackingcut_framesstaysource-processing-unsupported; checks that four malformed records exit nonzero with no candidate; checks that a 1 % scale alteration triggerssource-processing-receipt-mismatch; and checks thatframe_holdround-trips through JSON to matchundo_scalewith and without feet held.
v3.1.0 - Walk and run loop gates for held animation and seam pops, size hold for fixed cuts, talking face layer and default chroma decontamination
Upgrading from 3.0.0: Fixed walk or run cuts and clips whose feet climb or sink now hold size and feet before cutting, changing bytes when size changes by 1 % or more. Application scan numbers change for held clips, and held fixed cuts are not restored by video-loop-repair. Loops cut with --size-hold off, clips changing size by under 1 %, held motion-auto cuts on one row, and non-walk cuts keep their bytes. The report records size_hold on fixed walk or run cuts, size_hold.feet when size is held, size_hold.anchor_regions under --anchor motion, and size_hold.at_cut on fixed cuts; producer names the new version.
- New: Fixed cuts hold size before the cut is read. Walk or run cuts using
--cycle fixedwith any anchor (none,body,feet,motion) now hold size over the whole clip before reading the cut. A fixed cut is held only where the cut itself shows the change, comparing each frame of the cut with the frame one cycle of the cut's length later, or, where the clip ends before that frame, with the frame one cycle earlier: the median of those ratios must show at least half (AT_CUT_SHARE, 0.5) of the clip's predicted change over that length, and feet move only where the cut shows them move the same way. Where the cut does not show the change, it is cut as filmed, and the report says why (size_hold.why,size_hold.feet.why). The report'ssize_holdgainsat_cuton a fixed cut the clip reads a change on (pairs,share,change,feet_px,expected,feet_expected_px,size,feet). Seams, foot crossings (cycle.step_count), the gate, and application scans are read on held frames. Under--anchor motion, target regions are read where held (size_hold.anchor_regions). Passing--size-hold offkeeps filmed frames pixel for pixel, recordingsize_hold: {"applied": false, "why": "--size-hold off"}. Automatic searches with--anchor body,feet, ornone,--cycle pinned, and idle cuts are not held. - Changed: The size hold moves climbing or sinking feet to the first frame's row. Where size changes by 1 % or more and feet climb or sink by 1 % of first-frame height or more (
FOOT_HOLD_MIN), frames shift so feet stay on the first frame's row. Foot drift is read one cycle on (gait_fallback.foot_drift), preventing settling poses from reading as climbing feet. This stops wrap jumps from shifting into position where motion search (motion_anchor.SEARCH_RADIUS, 28 rows) or body anchors cannot correct them. Level clips keep their bytes.size_holdrecordsfeet(min: 0.01,method:one-cycle-on,change_px,held). - Note: What --size-hold off leaves in place. With
--size-hold off,motion-autokeeps its gait fallback: if the first search finds no cycle, size changes of 3 % or more (SCALE_DRIFT_MIN) are scaled back one cycle on with feet where filmed (gait_fallback.scale_undone). Cuts withoffkeep their previous bytes. - Changed: Held fixed cuts are not restored from source frames.
video-loop-repairreads cuts through source projection, which treatssize_hold.appliedassource-processing-unsupported. Recuts or scans of held fixed clips are not restored from source frames. - Output changes Fixed walk or run cuts, scans, and
motion-autocuts of clips with climbing or sinking feet change bytes when size changes by 1 % or more. Across ten synthetic walkers cut four ways withautoandoff, 62 of 80 keep their bytes. Changed cases are the fixed body cut and scan of eight walks changing size by 1 % or more (shrinking 7 % and 2 %, growing 20 % and 2.5 %, slow walk shrinking 7 %, two walks away, settling walk growing 2.5 %), plusmotion-autoof the two walks away. On a walk away (15 % smaller, feet 20 px higher), a fixed body cut refused at seam ratio 6.83 passes held at 1.25 (size alone failed at 10.03); shrinking 2 % moves from 3.80 to 1.46; a walk whose feet climb 96 px refused undermotion-autoat 13.03 passes held at 1.08. Scan ratios drop on the 7 % shrinking walk from 1.16 to 0.52, and on the walk away from 1.66 to 0.42. Shrinking 7 % cut by hand drops from 7.97 to 2.04 (still refused), and a slow walk shrinking 7 % from 18.31 to 4.48. The walk away undermotion-automoves from 0.79 to 1.41 because feet are held on row before cutting rather than closed by motion ramps. On test fixtures, a run filmed from a standing start that raises and waves its arm and crouches reads 6.9 % smaller over the clip while its cut shows 0; a walk of 26 frames cut 20 long reads 2.5 % larger over the clip while its cut shows 0; walkers that grow or shrink show 0.94 to 1.07 of predicted change at the cut; and every synthetic case gives the same bytes with this rule as without it. - Python callers
gait_fallback.foot_drift(frames, measured)returnsmin,method,change_px,held, andlift(frame shifts in px, None when not held).gait_fallback.FOOT_HOLD_MIN(0.01) is added.gait_fallback.undo_paddingandundo_scaletakelift=None.gait_fallback.held_box(box, k, measured, pad, lift=None)maps filmed framekboxes to held coordinates.gait_fallback.at_cut(frames, measured, feet, *, start, length)is added and returns that record;gait_fallback.AT_CUT_SHARE(0.5) is added. - Tests In
tests/video/test_gait_fallback.py: fixed cuts of the walk away and 2 % shrinking walker pass held under 2.0 seam ratio, wrap changes matching internal steps (size-only hold fails on feet);motion-autoon the 96 px climbing walk passes held on row with motion anchor applied;--size-hold offgives filmed frames pixel for pixel and records why; stable walkers keep identical bytes underautoandoffand record not held; idle fixed cuts omitsize_hold; foot drift reads 21 px for the 20 px walk away, 0 for level walks, and 0 for settling poses (fitted lines read 2.7 px); held walks away need no top room andheld_boxaligns head boxes;--anchor motionregions match held positions; forward walks mark feet not held while walks away close at feet; a hand cut of the run with earlier motion and of the short walk is not held,size_hold.at_cutshows 0 over all pairs, the report says why, and strip and frames match--size-hold off; held fixed cuts show the change at the cut (size_hold.at_cut.size, andfeetfor the walk away); a synthetic walk away from the camera (15 % smaller by the end, feet 20 px higher), cut by hand on the last 24-frame cycle of a 72-frame clip with 0, 1 or 5 of the cut's own first frames repeated after it, and the same walk cut on its first cycle with 0, 1 or 5 of the cut's last frames placed before it, is held each time on 24 pairs, one for each frame of the cut (the repeated frames show no change against the cut), and the loop passes the seam gate. Intests/video/test_loop_silent_pass.py: the walk away jitter test passes--size-hold offso feet climb crop rows as before.
Upgrading from 3.0.0: Bakes retain the same bytes for figures whose anatomy is unchanged. The pixel refusal message now names the sides and pixel counts. A figure that had face-absent may now have a face, with a lower rigid boundary only when that face ends below the neck. video-sway-inspect records use schema 3, and a cell whose every offset is 0 is now copied as it was, including colour under clear pixels with --gain 0; the other changes add options, and without them the strip, records and inspection stay as before. Smooth bakes that leave the in-breath share out keep their bytes. A smooth breathe.json config and a breath sway's drive record now carry inhale, Python callers of smooth_wave and smooth_shoulder_wave must pass the share, and breathe.INHALE is gone. A smooth breathe.json config and a breath sway's drive record now also carry start_cell (0 when left out) and loop_cells (null when left out), and a record without them reads as the loop itself from its first cell.
The Breathe layer still supports pixel and smooth.
Changed: Pixel refusal.
pixelstill refuses stretched content past the top, left, or right of a cell instead of cropping it. The message names each side and its opaque pixel count. A pixel past a corner counts on both sides. When an overflowing side is the drawing's own border, the message also gives the number of pixels covering that edge. It advises--mode smoothor sidecarmode: "smooth"for an illustration cut by its frame. It advises a wider cell margin or lowerdepthfor a pixel sprite. It warns that padding, baking, and cropping back silently loses pushed off content. The curator preview uses the same refusal wording. The border reading follows the 2% rule in video pipeline section 3. See breathing for behavior at frame edges.New: Second eye pair search. It runs only when the existing search finds no pair. Its minimum eye area is 0.2% of opaque pixels above the neck. Its eye width to height limit is 3.0, and its minimum eye center distance from the body axis is 0.02 of content width. Pair placement, separation, size similarity, and row overlap conditions remain the same. A face found by this search clears
face-absent. It lowers the boundary only if the face ends below the neck.Faster: Breathe bakes. Array operations speed up pixel outline thinning, appendage weights, and row mapping.
smoothsolves displacement only for pixels that move. Anatomy and settings checks run once per row, andsprite-gen breatheshares one anatomy measurement between its report and bake. On synthetic 960 x 960 cells with Apple M1, bake time fell from 0.20 s to 0.10 s forsmooth. For an outlined figure with arms inpixel, it fell from 0.98 s to 0.05 s. These measurements exclude PNG reading and writing.bake_breathe_sequence(images, cfg, anat=None)andanatomy_report(images, cfg, anat=None)accept measured anatomy.protect(anat)accepts one column or an array of columns.New: Sway on a cycle's frames.
video-sway --framesmoves full-size frames and writes them withsway.jsonto a new folder. A wholecycle/can supply its frame time; other damped-mass runs require--fps.New: Sway on the breath.
--breathedrives the move from a checked smoothbreathe.json, with--lagsetting how late the part follows. The first cell, rests and close have zero offset.New: A region moved whole. A fifth
--regionnumber,flat, keeps the centre at full weight before the weight falls to the rim.New: Across apart from down.
--gain-acrosssets the across gain separately from--gain, which sets the gain down.Changed: Zero-offset cells. A cell where no region moves is copied byte for byte, including colour under clear pixels.
Changed: Inspection seams.
video-sway-inspectdrops a pair's seam points covered by a third moving region. Its record usesschema_version3.New: Breathe beat chosen to miss the hands. In
smoothmode,--avoid-regionchooses a breath beat whose peaks keep the chest above the hands' own rise and records the choice inbreathe.json.New: The in-breath share. The smooth sidecar key
inhaleis the share of one breath the in-breath takes; the in-breath peaks at that phase and the rest of the breath is the out-breath. Default 0.40, range 0.2 to 0.8 with both ends allowed; out-of-range values are refused, not clamped, and a pixel row refuses the key. With the key left out or at 0.40 every bake is byte-identical to before. Withbreath_peaks, the rest between peaks p and q is at p + (1 - inhale) x (q - p).sprite-gen breathe --inhale Ssets it, and the normalized smooth config inbreathe.jsonalways carries it.--avoid-regionscores every candidate on the row's owninhalecurve, the curve the bake uses. Sway--breathetakes the chest curve, the late curve and the phase check at the record's share, sobreath_peaksphases written at another share are accepted when they match. A record without the key reads as 0.40 and sways exactly as before, and a hand-written record for a breath made elsewhere can state its share. The sway record'sdrivenow also carriesinhale. The curator sidecar round trip keepsinhaleas written and its range table mirrors 0.2 to 0.8.New: A stretch of a loop. A loop set has an idle loop and short pieces that leave it or join it part way through a breath, and such a piece can now be breathed and swayed on the loop's own breath instead of being padded into a sequence and cut out by hand. The smooth sidecar key
loop_cellsis the number of cells of the loop the row carries the breath of, an integer of 2 or more, andstart_cellis the loop's cell the row starts at, an integer from 0 to loop_cells minus 1, default 0. Cell i of the row has the phase of the loop's cell (start_cell + i) mod loop_cells, the very same floating point value, the beat (breaths, orbreath_peakswhose cells are cells of that loop) is the loop's, and the row's first cell is then not necessarily at rest. Withloop_cellsleft out or null the row is its own loop, with both keys left out phases and bakes are byte identical to before, and the normalized smooth config inbreathe.jsonalways carriesstart_cell: 0andloop_cells: null.sprite-gen breathe --loop-cells N --start-cell Ksets them;--avoid-regionis refused with either, since the beat is chosen on a whole loop's frames and a stretch carries on its loop's beat.sprite-gen breathe --reference FRAME.png, in any mode, measures the row's anatomy (head line, chest, how far it rises and its place in the frame) on that frame instead of the row's first frame, normally the loop set's first cell, andbreathe.jsonrecordsreferencewith the file'spathandsha256. Sway--breathereadsstart_cellandloop_cellsfrom the record, recomputes the phases with them and offsets a stretch's cell i exactly as the loop's cell (start_cell + i) mod loop_cells, from the stretch's first cell on, with nothing wound up before it. The fold rule and--stretch-floorread the loop's whole breath, so a stretch moves by the same gain as its loop and the seams between them do not jump; the record'sreach_px,foldblock andleast_cellare the loop's, andleast_cellis a cell of the loop.sprite-gen video-sway --reference FRAME.png, only with--frames, names the frame the regions were read on; each frame's body motion is read with it laid first,body_px,body_worn_pxandbody_bob_pxcome from or span it, andsway.jsonrecordsreferencewithpathandsha256. The sway record'sdrivenow also carriesstart_cellandloop_cells, and a record without the keys reads as the loop itself from its first cell and sways exactly as before. Refused, never clamped or wrapped: either key on a pixel row, a negative or non integerstart_cell, aloop_cellsunder 2 or non integer,start_cellat or aboveloop_cells,start_cellat or above the row's cell count withloop_cellsleft out (at the bake),breath_peakswhose last peak is within one cell of the end ofloop_cells, a--referenceof another size on either command, and--referencewith--loop-dir. The curator sidecar round trip keepsstart_cellandloop_cellsas written and its range check mirrors the Python refusals.Changed: Breath curve functions.
breathe.smooth_wave(t, inhale)andbreathe.smooth_shoulder_wave(t, lag, inhale)now require the share. The module constantbreathe.INHALEis removed; the default lives incuration.BREATHE_SMOOTH_SHAPE["inhale"], andbreathe.smooth_inhale(cfg)returns a row's share.breath_beat.choose(images, lift, inhale, avoid, anchor, frame_ms)andbreath_beat.nudged(n, k, inhale)take it as well.Tests:
tests/effects/test_breathe.pychecks border counts, advice, smooth edge preservation, and the second face search.tests/effects/test_breathe_js_mirror.pychecks curator refusal wording and byte identity with the pixel bake.tests/effects/test_breathe_smooth.pychecks pixel and smooth byte goldens and shared anatomy and strain measurements, and that the in-breath takes the row's share: at share 0.42 the cells at phases 0.21 and 0.42 are byte-identical to the default row's cells at 0.20 and 0.40,breath_peaksrests at the share, out-of-range and pixel values are refused, and the CLI flag is honoured.tests/effects/test_breathe_smooth_curator.pychecks that the sidecar round trip keepsinhale.tests/effects/test_breathe_publish.pychecks that the stand-in bake accepts the new argument.tests/video/test_sway_frames.py,tests/video/test_sway_breath.py,tests/video/test_sway_flat_across.py, andtests/video/test_sway_seams.pycheck the Sway paths, drives, weights, gains and seams.tests/video/test_sway_breath.pyalso checks that the sway follows the share the record says forbreathsandbreath_peaks, that a record without the key sways as the default, and that the default breath sways the same bytes as before the change.tests/effects/test_breathe_smooth.pyalso checks that a stretch's cell i has the loop cell (start_cell + i) mod loop_cells phase forbreathsandbreath_peaks(inside the loop, past its close, the whole loop, and the loop turned), that a stretch has exactly the phases the pad hand step gave, that a row without the keys is its own loop, the stretch refusals, that the CLI bakes what the sidecar bake bakes, and that--referencemeasures the anatomy on that frame, bakes with it and records it.tests/effects/test_breathe_smooth_curator.pyalso checks that the round trip keepsstart_cellandloop_cellsand that rows the bake refuses are kept and reported.tests/video/test_sway_breath.pyalso checks, on a synthetic bust, that a 17 cell way out of a 48 cell loop of two breaths, starting at the loop's cell 13 with its body 0 to 3 px across, is offset as the loop's cells are, at the gain the loop is lowered to by the fold rule, a gain at which the 17 cells alone would not fold; that engine commands give the pad hand step's phases, offsets, fold, gain, reach, carry and cells byte for byte; that without--referencethe carry is off by where the body lies in the first frame; that old records without the keys sway as before; and the--referencesize and--loop-dirrefusals.tests/effects/test_breath_beat.pychecks beat choice and refusals, and that each beat candidate is read on the row's share.tests/video/test_follow_stretch_floor.pyandtests/video/test_follow_inspect.pycover the changed inspection schema and frames options.Tests: A plain
pytestruns a fast bundle: tests markedsloware deselected, the header points topytest --full, and the summary counts deselections.pytest --fullruns every test. The release lane,scripts/linux_lane.sh, passes--fullto bothpytestcalls, including-m real_rife, so its gate still runs every test.tests/release/test_fast_bundle.pychecks both calls and probes selection with and without--full. Theslowrule inpyproject.tomlis 1 s per case or 5 s across a function's cases on an 8-core M1 running the whole suite; marking a function marks every case. Five tests remain unmarked as the only fast callers ofvideo-stop,workflow,defaults,video-sway, andexport-aseprite. Three fixture-first tests remain unmarked because other fast tests build their fixtures. Intests/frames/test_ui_kit.py, the fast bundle keeps 16 of 512 scattered-drawing grid seeds, 8 of 256 full-size-frame band grid seeds, 9 of 256 missing-element sets, 2 of 17 counterexample sheets, and one placement and start in each publish sweep.tests/curate/test_anchor_selection.pyextracts each run once per module instead of repeating 1.5 to 2.6 s of setup per test; 25 of 27 affected tests are now fast. Removedtests/video/test_loop_overlap.py::test_a_tail_on_its_own_beat_is_closed_at_the_wrap_with_the_clips_frames_a_cycle_apart[on]; its wordless case makes the same call with the default "on". Removedtests/video/test_walk_steps.py::test_cycle_align_takes_a_loop_cut_two_steps_as_one_cycleandtests/video/test_one_step_cut.py::test_cycle_align_takes_the_loop_cut_again_on_its_count;tests/video/test_loop_prop_seam_held.py::test_cycle_align_aligns_a_two_step_loop_as_the_one_cycle_it_iscovers alignment from recordedsteps: 2. Mergedtests/video/test_loop_overlap.py::test_the_cli_passes_overlap_wrap_off_and_on_is_its_defaultintotests/video/test_loop_overlap.py::test_with_the_overlapped_wrap_off_nothing_is_read_for_the_wrap_and_the_gate_refuses_the_cut_as_filmed, retaining both sets of assertions on one CLI cut with--overlap-wrap off. In a new virtual environment, the former suite ran 7,881 tests (7,880 passed, 1 skipped) in 21 minutes 54 seconds;pytest --fullnow runs 7,881, including two new release tests, and the fast bundle runs 6,555 in about 6 minutes. Package code, commands, and outputs are unchanged.
Upgrading from 3.0.0: the sprite-gen logo text checks read a refused image once more before refusing it, and on codex they read on a fixed model and effort. A mood or logo reading of mismatch or no-text is read again, up to logo.MAX_READS readings, which is 2. One reading that spells the asked text passes. An image is refused only when every reading differs. A logo now costs four to six calls: two images and two text checks, each read once or twice. Beyond a check's second reading nothing is sent again on its own. On codex the text checks no longer follow the login's ~/.codex/config.toml. They read on gpt-6-sol at reasoning effort high, and the report names the model and effort of every reading. sprite-gen logo refuses a chroma key that is one of the title's own colours, and a cut that is see-through inside its letters. A letter colour in the key's hue is, by its pixels, a mix with the key, so the matte cuts it see-through. --chroma-key auto now skips a key whose hue covers 5 % or more of the title's box in the mood image, or 1 % when the brief names a colour in that hue. When both keys are the title's colours, the run is refused at the new step key before the lettering image is bought. After the matte, see-through pixels walled in by the lettering, farther from it than the logo's own glow reaches, refuse the logo at matte on 1 % of the visible lettering or more. A run that went through before with a key in the title's hue, or with a see-through cut inside its letters, is now refused at key or at matte instead of passing with status: ok. Runs whose title carries neither key's hue pick the same key as before.
- A misreading is read once more before it refuses an image. Before, each check read the image once, and one misreading refused it. A model reading stylised lettering can read the same picture two ways, so a correctly drawn title could be refused on one reading. Both checks use the one rule,
logo.read_text. A call that fails is not asked again. With no reading before it, the check isunverifiedas before. With a misreading before it, the misreading stands and the image is refused. A refusal message names every reading, for examplethe mood image reads ['IO'] and then ['I0'], not ['ION']. docs/logo.md records a measurement on a synthetic pixel title drawn one stroke short (the Hangul syllable 쿠 drawn as 구, the middle bar of ㅋ left out). The codex reader at gpt-6-sol/high read it as 구 in 10 readings of 10 and never as 쿠, so neither one reading nor a check of two readings (0 of 5) passed the wrong picture. A second reading can only pass a wrong picture if the reader writes a stroke that is not drawn. logo.report.json:text_check.moodandtext_check.logokeep the deciding reading'sverdictandreadand gainmax_readsandreadings, each reading in order with itsreadingnumber,verdictandreadlines, orreasonwhen it could not be read.callslists a check's call once per reading, each withreading(1 or 2) andeffort(nullwhere the provider names none).- Codex reader: the text checks run
codex exec --model gpt-6-sol -c model_reasoning_effort="high", named on each call, so a check's verdict does not change with the machine it runs on. Before, each machine read on its own config and the report recordedmodel: null. The values arefacing_vision.CODEX_READ_MODELandfacing_vision.CODEX_READ_EFFORT.--modelstill names the images' model only. The facing check still runs on the login's config, unchanged. The xAI and OpenAI text checks read on their own fixed models, as before. - Python callers:
logo.read_textreturns(check, calls), a list of call records, instead of(check, call).facing_vision.codex_inspecttakes optionalmodelandeffortkeyword arguments. Without them its command line is as before. - With
--chroma-key auto, a key in the title's hue is not chosen.logo_matte.choose_keyrules out a key whose hue is 5 % or more of the title's box (logo_matte.CLASH_HUED_PCT), or 1 % (logo_matte.NAMED_CLASH_HUED_PCT) when--styleor--scenenames a colour in its hue (logo.KEY_COLOUR_WORDS: green, mint, lime, emerald, jade, chartreuse for green; magenta, fuchsia, pink, purple, violet, plum, orchid for magenta). A word alone never rules a key out; the pixels decide. The keys left are scored as before. When both keys are the title's colours there is no third: the run is refused atkey(refused_at: key) before the lettering image is bought. The message gives each key's share and the brief's words for it and says to restyle the title without one of the two hues or to name the key to lose with--chroma-key(--mood <mood.png>skips the mood image). An explicit--chroma-keyis kept; when it is one of the title's colours, a warning says so. Before, such a cut passed withstatus: ok, no warning,key_hue_left0 and a matching text check. - A cut that is see-through inside its letters is refused at
matte.logo_matte.see_through_insidemeasures see-through pixels (coverage under 240 of 255) walled in by opaque lettering and farther from it than the logo's own glow reaches beside it. Walled in means no way out to the picture's edge except across opaque pixels: the way out starts from the transparent pixels on the edge of the trimmed logo and runs through transparent pixels and see-through ones; a see-through gap of 2 px or narrower does not count as a way, a transparent gap of any width does. A hole joined to the outside, even through one pixel, is outside; a transparent hole walled in by the letters (an O's counter, or a letter colour cut all the way to nothing) is no way out, and a see-through patch round such a hole is still counted inside. Transparent pixels are never counted, only see-through ones. The same way out decides the glow's reach (glow_reach_px): the 99th percentile of how far the see-through pixels that have a way out to the picture's edge lie from the opaque lettering, and at least 2 px. On 1 % of the visible lettering or more (logo_matte.INSIDE_MAX_PCT) the logo is refused before its text is read, the cut is kept aslogo.rejected.pngand the preview is written. The message says to generate the lettering again on the other key or to restyle the title without that colour. Only the logo matte's own cut (method: logo-unmix) is refused; a lettering image returned with its own alpha is measured, not refused. A glow fades out beside the letters and pools in a counter no farther than it reaches there, so glows are not counted. logo.report.json:steps.key.scores.<key>gainsnamed,clash_at_pctandclashes, andsteps.key.keyisnullwhen refused atkey.logogainssee_through_insidewithpx,pct_of_visible,glow_reach_px,max_pctandwide.refused_atcan now bekey.- Python callers:
logo_matte.choose_key(mood, box=None, named=None)takesnamed, the brief's colour words per key fromlogo.named_colours(style, scene), and returnskey: Nonewhen both keys are the title's colours.logo_matte.see_through_inside(image)is new. - Tests:
tests/gen/test_logo.pychecks that one matching reading is the whole check, that a misreading read again as asked passes at either check, that two misreadings refuse the mood image and refuse the logo and keep it aside with a refusal naming both, that a check reads no more thanMAX_READS(set to 3, a third reading is taken), that a failed call is not asked again, that a misreading stands when the second call failed, and that the report names the reader model and effort of every reading. The existing refusal tests now script two misreadings.tests/gen/test_vision_read.pychecks that codex reads on the named model and effort, passed before the image list, that docs/logo.md names both values, and that the facing check's command carries neither.tests/frames/test_logo_matte.pychecks that a title in both keys' hues (synthetic patchwork letters: pink and plum in magenta's hue, mint in green's) gets neither key, that a colour in a key's hue rules the key out, that a colour the brief names rules it out at the smaller share while the same share unnamed and the word with no such pixels do not, that on green the mint patches are cut see-through and found inside (9.5 % of the visible lettering) while the other key keeps them and finds nothing, that six glow fixtures (a white glow, an outlined cyan glow, a cyan glow pooled in an O's counter on green and on magenta, an orange glow on green, pixel lettering) find nothing inside, that a mint patch walled in by a navy letter on green is still found inside, with the glow's reach at 2 px, when one or four squares of the key in it are cut to nothing, that a hole glued to the letter's edge is inside while sealed and outside once one pixel joins it to the key round the letter, and that big hollow O and A letters find nothing inside, plain or with a glow pooled round a counter whose middle stays clear (three glows).tests/gen/test_logo.pychecks that a title in both keys' hues is refused atkeybefore the lettering is bought, that a named key in the title's hue is kept and the warning says so, that a see-through cut is refused atmatteand kept aside with no text check, with or without a 9x9 square of the key in the middle of its patch, and that a glowing title is not see-through inside.tests/logo_lettering.pygains thequiltfixture: square fabric patches in outlined pixel letters, one with a counter, on a key. It also gainswalled_patch(a navy letter with a mint patch on pure green, with squares or a pixel of the key painted in) andhollow_letters(the big O and A shapes), whichletteringdraws through its newshapesargument.
Upgrading from 3.0.0: Existing runs and commands do not change. This release adds two verbs and a JavaScript player. The wheel now also carries sprite_gen/video/*.mjs.
sprite-gen video-facebuilds a face pack from a reference, a keyed talking clip, and keyed body motions.sprite-gen face-bakeruns the pack's player through node to bake a voice onto body frames, with optional MP4 and beside video output.- Face request kind
sprite-gen-face-request, version 1, records face geometry, clip placement, a rest loop, and optional own-mouth spans or timelines. - Face pack kind
sprite-gen-face-pack, version 1, carries sprites, body cells, anchors, keeps, rules, a report, a copied player, and SHA-256 digests. - The lower-face layer covers the mouth, jaw line, cheeks, and chin. The body's own dark grey and black that reach in from the layer's boundary, such as a headset boom or a choker, the body's own lines in the layer's feather, and a hand that reaches over the face from outside the layer stay above it.
- Each body frame receives a place, size, and tilt anchor. The pack records anchor residuals and corrects outlying readings against neighbouring frames. A body frame whose own mouth is closed has its place read again on a ring of skin round the mouth, because a head that turns moves its hair, headset, and cheeks further than its mouth, and a frame whose mouth is open takes the move of the read frames round it. The pack records each frame's move and the frames read on the ring.
- Talking frames are assigned to smile or neutral sets by closed-mouth lift. Entry chooses a matching set and rest.
- The player
sprite-gen-face-v1.mjscontains the voice flap, face pick, scene plan, and live canvas playback rules. - A clip's own mouth and sound finish before a requested line starts. The voice and layer then wait together for the first frame whose switch to the chosen rest is within the 1.4 jump line. Layer exit also uses that jump line.
- The live player keeps one queue of every
playandsayrequest, in the order the calls are made, and starts each request on the frame after the one before it has ended, so two voices never overlap. A line placed right after a clip with its own mouth is planned together with that clip, the planplanScenemakes andface-bake --playbakes, and its voice and layer start at the plan'sline_startafter the own-mouth span. The queue has no length limit and drops nothing: a request whose sound does not load or decode, or whose lineplanScenerefuses, rejects its promise when its turn comes, and the next request goes on. - Bakes check pack digests, changed pixels outside the weight, and composite jumps. Refused bakes retain their frames for inspection.
- See docs/face-parts.md for the request, pack, player, commands, and limits.
- Tests:
tests/video/test_face_layer.pyusestests/talking_face.pyto check smile and neutral sets; clip entry set and rest; own-mouth timelines, including a close during voiced sound and refusal of a missing or never-closing timeline; a head 60 px from its place and tilted 3 degrees; a head that turns, tilting up to 5 degrees about its mouth while its hair, headset, and cheeks move up to 12 px sideways and its mouth stays where it is, with two of its eleven frames open, whose anchor place is within 1 px of the mouth on closed frames and within 2 px on the two open frames and whose tilt is the band's, below minus 2.5 degrees where the turn is fullest; hand, headset boom, and choker keeps; a tongue in the body's own open mouth, joined to a hand by a finger at its corner, covered by the layer; unchanged pixels outside the weight; synthetic cells keeping the key's colour under no coverage; digests and new-folder pack writes; the player flap against its original numpy rule and the pick against the draft Viterbi over every frame; a line waiting for a clip's own mouth and for a frame its layer can come on at; the live player run by node on a fake audio clock, with two lines requested during a greeting's own mouth, three lines requested on the loop, one line requested during the own mouth and one after it, a line whose voice loads late, a line requested right after a clip whose sound loads late, a line whose voice loads only after the greeting's own mouth has ended or only after the greeting has ended, which waits for the greeting to end while the greeting plays to its end with the layer off, a line that plays on the loop when requested right after a clip whose sound fails to load, and a request that fails; loop and post-greeting bakes with greeting frames unchanged byte for byte; and refusal of a changed pack.
Upgrading from 3.0.0: This release changes defaults for video frames.
Outputs that change bytes are frames from video-frames and video-set on a green or magenta key.
These changes occur within 6 px inside the keyed silhouette only.
Video frames keyed with explicit --decontam palette also change bytes, because they use the same video fit.
Outputs that do not change bytes include runs on a white key, subjects with no interior, and runs with --alpha-mode brightness.
Stills (cutout, gen) and row extraction (extract, inspect) do not change bytes.
Runs with --decontam off also give the 3.0.0 bytes back exactly.
To get the 3.0.0 frames back, pass:
--decontam off
Default change:
video-framesandvideo-setnow default to--decontam auto(before:off). This release updates these defaults to clean chroma-bleed edges automatically.On a chroma key, H.264 4:2:0 chroma mixes key colour into strands one to three pixels wide. With decontamination off, a red hair strand on green keeps an olive rim. The
autopass restores the subject's own colour to those edges.The video default stayed
offuntil now out of caution rather than any known defect. The pass was benchmarked on a green key only. The video fit is less decisive than the still fit. In the documentation's benchmark table, the video-fit row (10.8 % residual contamination, 9.38/8.73 halo, 91.4 % recall) was measured in September 2026 with flank recovery. It has not been remeasured since flank recovery was dropped, because those benchmark inputs and tools are not at hand. The diagnosis table indocs/chroma-alpha.md(itsdecontamsection) has the current video fit's numbers. Still-fit rows in that table are unchanged.Earlier fixes resolved the Grok-magenta regression through the key-hue cap and corrected the frame-edge interaction. No blocking defect remains known.
On synthetic diagnosis clips (CRF 18,
--spill small, 6 frames, one machine),autoreduced key contamination on red strands on painted green from 24.2 % to 10.2 %, and on pure green from 27.4 % to 10.9 %. Halo composite error on dark and white backgrounds shifted from 11.6/12.1 to 9.6/10.1 on painted green, and from 12.0/11.9 to 10.0/9.9 on pure green. Strand recall stayed at 91.4 % on painted green and 92.4 % on pure green. Strand recall no longer rises with the pass, because that gain came from the flank that the video fit no longer recovers. Halo gains are smaller than before for the same reason. On these moving scenes, key contamination is about one point higher than with the hold and settle alone, because a change of call now takes a few frames to reach the fit's colour.Key contamination dropped from 3.4 % to 0.5 % on magenta, and from 5.4 % to 1.8 % on Grok darker magenta. Halo shifted from 15.0/19.6 to 12.7/16.4 on magenta, and from 20.7/31.5 to 19.3/30.0 on Grok darker magenta (compared to 17.1/24.7 when flank recovery was present). Strand recall shifted from 87.0 % to 86.9 % on magenta and from 73.3 % to 73.2 % on Grok darker magenta. Outline ink CIELAB error shifted from 19.3 to 20.2 on magenta, and from 21.7 to 22.6 on Grok darker magenta. Red hair counts as key-coloured material there, so the palette is not key-free and the warning line appears.
Contamination dropped from 20.6 % to 8.8 % on a translucent glow scene (halo 12.6/9.4 to 11.7/8.5, strand recall 85.7 % to 85.4 %). It dropped from 23.8 % to 11.4 % on a small green charm scene (halo 11.8/12.9 to 10.0/11.1, strand recall 90.7 %).
Changed pixels make up about 2.4 % of each frame (4.7 % in translucent scenes). All changed pixels lie within 6 px inside the silhouette. Nothing outside the silhouette changes any more. Interior pixels remain byte-identical.
Stills (
cutout,gen) and row extraction (extract,inspect) still default tooff. The row extractor frames are a derived cache thathealre-derives, so changing their default would silently rewrite existing runs. Stills remain as they were.Temporal fit: The video fit holds edge decisions across frames, blends a change of call over frames, settles still pixels, and drops flank recovery. With default
auto, the edge of a subject standing still sparkled from frame to frame where--decontam offremained calm. Codec noise pushed edge pixels across the pass's threshold tests from frame to frame. These tests decide blends, tints, material behind, explained pixels, palette colours, and flank coverage. Each crossing changed the written colour by far more than the noise itself did. The raw matte withofffollows codec noise smoothly, staying calm despite keeping an olive rim.video-framesandvideo-setnow maintain a clip history in clip order. This history passes to each frame throughdecontaminateashistory(decontam_historyincutoutandremove_chroma_background).Each test now holds its previous outcome at that pixel until current evidence passes the bar the other way by 16 (an RGB distance,
VIDEO_HOLD). A palette colour picked in the previous frame stays unless another colour's line passes closer by 16. Moving pixels change their evidence far beyond 16 and are decided afresh. Only near-threshold calls stick. With the hold alone, a call that did change could still move a still edge through the whole gap between the matte and the fit in one frame.The blend mixes two renderings made from this frame's evidence at every pixel the pass examines. One is the matte with its key hue capped, and the other is the fit's palette colour at the pixel's light, with the fit's coverage where the call refits coverage and the matte's coverage elsewhere. For a palette-colour change, the fit's rendering mixes the two colours' renderings. A new palette colour waits until the change in hand is done, while a return to the old colour turns that change around. The mix moves toward this frame's call by at most 0.2 a frame (
VIDEO_BLEND). It moves less if needed to limit the output change to 4 (VIDEO_STEP) plus 0.25 (VIDEO_STEP_MOTION) per unit the source moved, measured in premultiplied colour or coverage across its 3x3 box. A pixel new to the band starts at its call if it was transparent in the previous frame, and otherwise starts from the matte. Both renderings follow a moving subject at once; the change of call is spread over frames.A still pixel whose mix moved, has not reached its call, or came into or left the band moves at most 4 a frame from its previous output, measured in premultiplied colour and coverage. Here, still means its source moved by at most 8 in any channel anywhere in its 3x3 box (
VIDEO_STILL). A pixel the hard cut keyed in this frame stays transparent.Still pixels settle toward the current fit when their mix is at its call in both frames. When a pixel was written in both frames in the same palette colour, and its source is still, it settles. It moves a tenth of the way (
VIDEO_SETTLE0.1) toward this frame's fit and stays within 12 per channel (VIDEO_SETTLE_REACH) of it. When it must catch up to get within 12, it now moves at most 4 a frame in premultiplied colour and coverage instead of moving all at once. This dampens codec noise while following real slow changes within 12 levels.The video fit also drops flank recovery. It no longer gives coverage back to keyed pixels (hard cut background within 3 px of the subject). Decoded chroma blur created faint blends on keyed pixels, and codec noise carried them back and forth over the noise floor. This filled dark gaps between strands with a faint smear that came and went across frames. The video fit now examines the band only (subject pixels within 6 px of the keyed background). The still fit keeps its flank recovery unchanged.
With history enabled, frame bytes depend strictly on previous frames in clip order and remain deterministic. A single video-fit call without history gives the same band bytes as before, leaving keyed flank pixels as the matte keyed them.
On a synthetic still scene under decoder noise (red strands 1 to 3 px wide on painted green, 8 frames, sigma 2): Mean edge change between frames on a dark background was 2.34 with
off(99th percentile 8.3). With the hold and settle alone, the mean was 2.27 (99th percentile 8.3). With the blend and still steps, the mean is 2.25 (99th percentile 8.0). Key contamination on that scene was 6.5 % withoff, 2.3 % with the hold and settle alone, and 2.4 % now.On a second synthetic scene, decoder noise changed between two frames and the source then stayed still for 19 frames. With the hold and settle alone, changed calls appeared in one frame and their pixels stopped moving when the source stopped. Now those edge pixels keep moving toward their new calls, by no more than 4.31 premultiplied a frame including uint8 rounding, and arrive by frame 14.
Per-frame stats and clip totals include
held_px,blending_px, andsettled_px.held_pxcounts pixels where a held outcome or colour differed from an independent fit.blending_pxcounts pixels showing a mix of two calls rather than this frame's call.settled_pxcounts pixels the settle or a still step moved from the previous frame's output. In video,recovered_pxis now 0.Keying cost was remeasured on an Intel i5-7500 with a 1080x1920 synthetic clip at CRF 18 and
--spill small, six frames, one process per run, in the same session. Keying took 1.14 s a frame withoff, 3.25 s with the hold and settle alone, and 3.36 s now. Peak memory was about 400 MB withoff, 945 MB with the hold and settle alone, and 1155 MB now, adding about 365 MB overoffper megapixel. Becausevideo-setkeys three items at once by default, it can use about 2.3 GB more thanoffat that size.Guards: Two new guards protect key-coloured details and material behind edges in the video fit. The still fit output is unchanged byte for byte, but explicit
--decontam paletteruns in video also use these guards.The key-coloured parts guard protects small details that share the key colour. A subject can own a key-coloured part too small for the palette to keep, such as a green charm on red hair under a green key. When such a part covers under 0.5 % of the interior, the palette learns key-free colours. Without the guard, the pass repainted the rim in the nearest key-free colour, turning the green charm's rim brown.
Now, when the palette is key-free, band pixels within 6 px of such a part keep the matte's bytes. There is no flank in video any more, so this guard covers band pixels only. This applies to pixels near parts that are opaque, deeper than 6 px, and have key hue above 8. The key-hue cap leaves those pixels alone.
On synthetic tests, the share of the charm's key-coloured edge pixels that lost half their key hue or coverage was 0.77 with
offand 0.82 now. Its colour error was 41.7 withoffand 45.6 now (64.9 without the guard in the diagnosis).The material-behind guard preserves edges where subject material continues to the silhouette boundary. A band pixel keeps the matte's bytes when its colour, observed directly or at its own luma, falls within the opaque margin of the mean colour of subject pixels right behind it. This check reads subject pixels deeper than 2 px within a 3 px box radius. Such pixels are treated as material continued to the edge rather than blends or tints. The key-hue cap still applies to them. Unlike the still fit, this guard does not require the pixel to be free of the key's hue, because decoded chroma blur gives every edge some key colour.
Diagnostics: A one-line stderr warning and new report fields track skipped frames and guard activity.
video-framesprints a single line on stderr after its JSON summary when edge decontamination warrants attention. The line starts withvideo-frames: warning: decontam auto ...and ends by naming--decontam offas the way to keep the matte as it is.The warning prints when
autoran on no frames, whenautoskipped some frames, or when the subject owns key-coloured material so the palette is not key-free. On magenta keys, the red hair's blue channel sits more than 8 above its green, making the hair key-coloured material (9.6 % of the interior on magenta and 6.6 % on Grok's darker magenta) and triggering this warning. The warning also prints when the key-coloured part guard kept edge pixels, reporting how many and noting that thin details farther out may be repainted. A few key-hued pixels deep inside from codec noise guard no edge and raise no warning. Brightness alpha raises no warning.video-setprefixes this warning line with the item name and records it underwarningsin the set report.The JSON report adds
decontam.reasonfor the first skip reason anddecontam.skipped_frameswhen frames are skipped. Per-frame stats and clip totals in the video fit addkey_part_kept_px,behind_kept_px,held_px,blending_px, andsettled_px. Whereautocannot run, frames remain exactly as the matte keyed them. The report records "the white matte has no key colour to remove" for a white key. It records "no interior to learn the subject's colours from" when no pixel lies deeper than 6 px inside the silhouette. Under--alpha-mode brightness,autodefaults to off, recording{"mode": "auto", "applied_frames": 0, "reason": "brightness alpha has no key colour to remove"}. Explicit--decontam palettewith brightness alpha remains refused.Known limits apply to this release.
The hold works on pixels that stay put. A change of call on a still edge arrives at most 4 a frame. The largest change, between the matte's full coverage and a faint fit, can take up to about 64 frames, or about 2.7 s at 24 fps. Until it arrives, the edge shows a mix of the matte's colour and the fit's. A strand that moves is decided afresh in every frame, while its change of call is spread over a few frames and both renderings follow it. A moving edge still changes from frame to frame as its colour does, so a red rim moving over a dark background changes more than the olive rim
offleaves. Pixels whose call changes show a mix of the two calls for a few frames.The settle follows a slow change within 12 levels per channel and catches up past that at most 4 a frame.
The video fit gives back no coverage the hard cut keyed. Outer pixels of a soft edge that the cut erased stay erased. Only on stills, outside a dark outline the flank can give a few faint pixels in the subject's colour.
A thin feature whose colour is absent from the interior can be read as a palette colour plus key. For example, a thin yellow line beside red hair with a pink highlight turned pink (colour error 26.2 with
off, 47.5 now).--decontam offkeeps that line.A thin key-coloured detail farther than 6 px from any key-coloured interior is repainted in a palette colour.
The thinnest strands retain some olive because decoders share chroma across aligned 2x2 blocks, leaving a one-pixel strand with half the key's chroma. A block-aware fit is planned separately.
Pixel-art rows binarizing alpha, the green-only benchmark, and increased processing time and memory remain known limits.
Tests:
tests/frames/test_chroma_decontam.pychecks that both video verbs default toautoand that still verbs and the row extractor do not. It checks thatoffgives the engine's original bytes. It checks thatvideo-sethands its value tovideo-framesand lists the warning. It checks that a white key, a subject with no interior, and brightness alpha give the same bytes asoffwith the reason.A new section tests the video fit over time on the red-strand scene standing still while decoder noise changes every frame (luma per pixel, chroma per aligned 2x2 block, eight frames). The default's edge changes from one frame to the next no more than
off's, in mean and at the 99th percentile. The edge is still cleaned, with key contamination at most half ofoff's. Clip totals count held and settled pixels, and the first frame has none. A frame given twice comes out with the same bytes both times. Another test decodes one frame of the red-strand scene, then holds a second noise draw (sigma 3) still for nineteen frames. After the source stops changing, the default keeps moving toward the calls the noise changed. No pixel moves more thanVIDEO_STEPin one frame in premultiplied colour or coverage, plus one for uint8 rounding. It arrives by the last frame. Clip totals countblending_px, and the first frame has none.The video fit leaves every pixel the hard cut keyed transparent and recovers nothing. The still fit still recovers its flank.
Changed tests reflect dropped flank recovery in video. A head 6 px under the top frame edge passes the edge gate under the default and keeps the blur rows below the edge band as the matte keyed them. For magenta skin tone in a 4:2:0 frame, the video fit's halo is read on the band where it acts (at most 0.9 of
off's), and the keyed flank keeps the matte's bytes. The still fit keeps its halved halo.The rim of a small green charm keeps the matte's pixels and loses at most 0.1 more than
offwhile strands away from it are cleaned. On magenta and Grok magenta, halo and alpha error do not rise.A few key-hued pixels deep inside raise no warning.
video-framesprints the warning line on stderr.tests/video/test_gait_guard_anchor_wide.pyhas its stand-in forrun_framestakedecontamand checks that the set'sautoreaches it.
Upgrading from 3.0.0: Walk and run loops now pass a step gate and fixed walk or run cuts are counted, so some cuts that passed before are refused. Against 2.45.3, on which this change was built, every cut 2.45.3 passed that neither new reading refuses gave the same loop files byte for byte (strip, sidecar, frames, GIF and WebP bytes, the same stderr save new warning lines), measured on a batch of walk clips cut with caller arguments (the automatic walk cut, cuts by hand, forced cuts). The report gains step_gate on walk or run loops and cycle.step_count on fixed walk or run cuts, producer names the new version, and the CLI summary gains step_gate, whose jitter names the frames entered by steps over 2.5 that are a pixel's jitter, along with jump_repair.unfixed. Refusals outside the new readings keep their lines word for word, except the seam line's end where warning lines name a part on a beat of its own. Callers matching failure lines by first words need rules for video-loop: loop step ratio (the clip jumps inside: film again), video-loop: loop step count refutes the fixed cut (cutting again by hand failed), and video-loop: loop frames left off the flow only if passing --unfixed refuse; failure reasons can also be read from seam_refusal. Any --seam-max past 2.5 lifts the step gate and the count refusal, and forced delivery passes --seam-max 1000 together with --seam-pop-max off, because --seam-max does not lift the seam pop gate described below. Reading feet on a fixed walk or run cut costs less than the distance matrix read by every cut.
Behavior change: Walk and run loops that play round now pass a step gate that inspects spacing between drawings. After the seam gate, cells are read between drawings rather than frame by frame, so held animation on twos or threes does not appear uneven when drawings span multiple frames. The largest step from one drawing to the next, the wrap included, over the mean of the others, must be at most
STEP_RATIO_MAX(2.5), else the loop fails withvideo-loop: loop step ratio <ratio> exceeds 2.5 (<kind> length <L> frames from <start>, into frame <frame>, read between its <n> drawings); the loop jumps inside — regenerate the clip, with jump repair reason: frame <frame> lies off the walk's flow, and the jump repair's frame there was refused (<faults>), so it plays as filmedbefore— regenerate the clipwhere present. A step over 2.5 is exempt from the bound when it is a pixel's jitter (loop.step_jitter): the move that aligns its drawing with the previous drawing with the least coverage difference, measured on alpha so colour has no effect, is at mostSTEP_JITTER_PX(1.5) pixels of the frames as filmed, and the step with that move taken back is within 2.5 of the mean. In a walk going away from the camera, foot rises of a whole crop row measure 2.5 to 3.6 times the mean as drawn, black or grey, but move one pixel and pass without a warning line. One frame of a 400 px tall walk cut moved 6 px and back moves 2 pixels of the frames as filmed, and the gate refuses the loop in every colour, including black. The report recordsstep_gateon every walk or run loop (drawings,hold,mean_step,largest_ratio,largest_from,largest_into,wrap_ratio,max,jitter,lifted,kept;skippedfor fewer than three drawings). The bound is the larger of 2.5 and--seam-max, so any--seam-maxpast 2.5 lifts it; a scan or forced delivery with--seam-max 1000keeps a loop whose largest step is over 2.5 with warningvideo-loop: warning: the loop's largest step between drawings is <ratio>x their mean (into frame <frame>), over 2.5: it jumps inside — kept, as --seam-max <seam-max> lifts the step gateandstep_gate.kept.Behavior change: Fixed cuts fail when foot crossings count an odd number of steps. Manual walk or run cuts using
--cycle fixednow read the clip's foot crossings and evaluate the cut, matching--anchor motion-auto. The report recordscycle.step_countwithchosen_by: caller. A cut counted an odd number of steps fails withvideo-loop: loop step count refutes the fixed cut <start>/<L> — the clip's crossings count one step, each seen where a walk loops on two, and an odd count swaps the legs at the wrap; cut it again two steps long (about <2 steps> frames). An even count is not refused by the count check, and the exemption--anchor motion-automakes for a pass hidden among feet held together (the clip a cut on the same picture) applies identically through sharedlocal_cycle.same_picture_count. The strip is unchanged, and there is nostepsfield. Any--seam-maxpast 2.5 lifts this refusal; a scan or forced delivery with--seam-max 1000keeps an odd step cut with warningvideo-loop: warning: the clip's crossings count the fixed cut <start>/<L> one step, each seen: a walk loops on two steps, and an odd count swaps the legs at the wrap — kept, as --seam-max <seam-max> lifts the step gateand recordscycle.step_count.lifted.New: Refused jump repair drawings are listed in
jump_repair.unfixedand can fail the command. When jump repair refuses a frame group, its frames remain as filmed; where the playing loop still reads a drawing of it 3.0 or more of its window's usual steps off the flow, that drawing is recorded injump_repair.unfixedalongsiderefused(the faults). Everyunfixeddrawing prints warning linevideo-loop: warning: frame <frame> of the loop lies <off>x its window's usual step off the walk's flow after the jump repair: the group that would bring it back was refused (<faults>), so it plays as filmed — a jump played as filmed; --unfixed refuse refuses such a loop (docs/loop-repair.md section 2). A new flag--unfixed warn|refuse(defaultwarn) controls handling:refusefails such a loop with an error line startingvideo-loop: loop frames left off the flow —. This failure is not lifted by--seam-max.Fix: The seam gate failure line explains the cause where warning lines know it. The first words of the failure line stay the same up to
the cycle does not close —; where warning lines name a part on a beat of its own (an--anchor motion-autocut two steps long by the clip's crossings whose wrap the gate refuses), the rest says so and names what became of the overlapped wrap, for examplevideo-loop: loop seam ratio <ratio> exceeds 2.0 (periodic length <L> frames from <start>); the cycle does not close — the cut covers two steps by the clip's crossings, and a part on a beat of its own (a tail, a held prop) closes on no cut of two steps: the overlapped wrap was not made (turned off (--overlap-wrap off)) — regenerate with that part moving on the walk's beat. Elsewhere the line is word for word as before. Every refusal by the wrap, steps, or count recordsseam_refusalin the report (reading:wrap,stepsorcount). Forwrap, it recordsratio,max,reason(own-beator null), andoverlap_wrap. Forsteps, it recordsratio,max,into,reason(repair-refused,unfixedor null), plusframesandrefusedwhere a reason was found. Forcount, it recordscut,verdict,k,why, andtwo_steps.Tests —
tests/video/test_loop_silent_pass.py: a side walk in place with a middle frame moved 10 px fails the step gate while its wrap passes, recordingstep_gateandseam_refusal, kept by--seam-max 1000with a warning line; an eight drawing walk on threes passes when frame by frame steps exceed 2.5; melted ponytail outlines and smeared stand in RIFE frames stayunfixedwith faults, cite the refused frame in step gate lines, and fail under--unfixed refuse; CLI tests confirm--unfixeddefaults towarnand rejects other words. Hand cuts fail on one step, pass at two, keep one step cuts under--seam-max 1000, and exempt hidden far feet on twos. A walker whose tail swings on its own beat fails seam checks with the reason in its line andseam_refusal; a sideways wrap shift keeps its line word for word withseam_refusal.reasonnull. The walk going away from the camera passes with foot rises of a whole crop row as drawn, black and in a grey near the backdrop: its steps over 2.5 times the mean move one pixel and are recorded instep_gate.jitter. A standing side walk with a frame moved 2 px and back fails on that step as drawn, black and in that grey, with every frame's alpha the same. Intests/video/test_body_anchor_gate.py, the sliding side walk with its first frame moved 3 px is refused on the step into frame 1: those 3 px take up the sideways slide at the wrap and put the jump inside the loop. The seam still reads the source frames and is not read again.Fix: Windows run dir lock handling. Every command that writes a run dir (for example
extract,compose-atlas,export-pngs,unpack-atlas) takes a single-writer lock: the entry.sprite-gen.lockinside the run dir. Before this fix, on Windows only, when that name held a link pointing at a file that does not exist, the writer followed the link and made the lock file at the link's target, outside the run dir, and that file was left behind when the writer released the lock; also on Windows only, a folder at that name, a link to a folder, or a link whose target is written with forward slashes ended the command with a bareOSError(EACCESorEINVAL) instead of the named refusal. Now on Windows a link or a folder at that name is refused by name, the same as on macOS and Linux (run dir lock ... is not a lock file (a link or a folder)), and nothing is followed, made or removed, while macOS and Linux behave exactly as before. The test istests/spec/test_run_dir_lock.py.
Upgrading from 3.0.0: commands that write beside what they read now check and refuse any input that overlaps a file or folder the run replaces or deletes, even with --force. This judgment is defined in docs/run-contract.md and enforced by runio.refuse_overlap before any command creates output. A run is stopped whenever an input matches an output, lies inside it, or passes through anything inside it, and the refusal names both paths.
- Behavior change: Overlap refusal for inputs and outputs. Twelve commands now call
runio.refuse_overlapbefore making anything, with or without--force:unpack-atlas,video-loop,video-stop,video-frames,correction-loop,logo,video-extend,video-edit,video-loop-compare,video-loop-repair,video-source-manifestandshadow. Inputs include paths given to read and files found inside them (such as frames in--frames-dir), followed viarunio.follow_path. Outputs include each file written, folder replaced or emptied, and report, but not folders only added to (which is why--out-dirforvideo-loopandvideo-stopis not compared). Comparisons check real path and file identity (runio.same_folder,runio.inside_folder), treating links and different spellings on volumes that ignore case as identical, while input link loops are refused by name. A link at a written file is refused if it leads to an input, even where the run would replace the link rather than write through it, whereas paths passing through an output and exiting with..(such asout/cycle.source/../keyed) are permitted. Inlogo, the folder's ownmood.pngandlettering.pngremain permitted for--moodand--letteringwhile any other output file is refused, andcorrection-looppermits an--out-dirinside the run dir or one holding an earlier loop's attempts, best candidate and report. - Fix: Directory recursion and casing collisions on volumes that ignore case. Before,
correction-loopcompared only--out-diritself with the run dir, so with a linkattempt-1in its--out-dirleading to the run dir, the loop wrote its attempt into the run it read. Separately, before, the best candidate's copy of the run dir copied itself into itself until the path was too long. (The default--out-dir,<run-dir>/correction-loop, lies inside the run dir; the copy now leaves it out.)correction-loopnow takes an earlier loop's candidate away before the provider makes the next one there.video-sway-inspectnow refuses an--out-dirthat is the loop directory spelt in capitals on a volume that ignores case, instead of writing boards into it. In addition,video-loop-compare,video-loop-repair,video-source-manifestandshadownow callrunio.refuse_overlapso reports or outputs spelt in capitals on volumes that ignore case are refused instead of overwriting inputs, whilebackground-tile,inspect-motion,scene-inspect,scene-render,game-pack,ui-kitandvideo-sway-inspectverify their single output withrunio.same_folderandrunio.inside_folder. - Behavior change: Unique working folders via stage names. Any folder a run writes into and then deletes is now created with
runio.new_stageand named.<name>.<pid>-<random><suffix>. These include the framesvideo-loopscales back for a size hold or gait fallback (.gait-fallback-frames.<pid>-<random>, removed however the run ends), the PNG frames built into animated WebP files beside the WebP forvideo-loop,video-stop,video-cycle-align,video-swayandvideo-loop-repair(.<name>.webp.<pid>-<random>.frames), the working foldervideo-frameskeys into (.keyed.<pid>-<random>.work), and the working folder oflogo(.logo-work.<pid>-<random>). Folders at old fixed names (.gait-fallback-frames,.webp-frames,.keyed.work,.logo-work), whether holding an input or belonging to anyone else, are never written into or removed. - Behavior change: Input protection, staging, and locks in
unpack-atlas.unpack-atlasnever touches its inputs, refusing before making anything and with or without--forceany input that is the run dir, lies inside it, goes through anything inside it, or holds it. Guarded inputs include--pngs-dir,--atlas,--manifest, the atlas a manifest names, and what the import reads in--pngs-dir(every frame,_baseimage,_refsPNG,meta.json, and every folder it reads one from, any of which may be a link). Refusals name the first entry the input goes through inside the run dir, while paths that only pass through the run dir itself (such asrun/../incoming) are not refused. The command builds runs in a dedicated staging folder beside the run dir (.<name>.<pid>-<random>.sg-staging) and moves prior content aside into a backup folder inside it (.sg-backup.<pid>-<random>), never reusing or removing existing staging or backup folders and putting every prior file back on a failed publish. The run dir's single writer lock is the entry.sprite-gen.lockitself (runio.acquire_run_dir_lock, every writer) and belongs to the process that took it, and a link or a folder at that name is refused by name and never followed, read or removed, so reclaiming a stale lock deletes only a stale lock file.
Upgrading from 3.0.0: A held walk or run whose wrap fell between two drawings, refused before, may now pass. A walk drawn a frame each gives the same loop files byte for byte. Reports record seam_read (read, drawings, hold) on every walk or run whose seam ratio gates the cut, and seam_after_anchor gains the same three fields when cells are read again, with strip.json and the failure line of the seam gate unchanged.
- Behavior change: Walk and run loops gated by their seam ratio now measure the seam between drawings. For any walk or run whose cut is gated by the seam ratio (neither pinned nor played once), the seam is read between drawings using each drawing's first frame (
loop.seam_drawings, built onrepair.flow_drawings), matching the reading used by the step gate. This applies in three places: the seam gate itself, both on source frames (seam_measurement: source-frames) and rendered cells (rendered-cells); the body anchor ramp rule, reading the wrap and every step between the cells' drawings; and candidate evaluation under--anchor motion-auto(loop.seam_on_cellsthroughloop.wrap_on_cells) when selecting two-step cuts or testing overlapped wrap attempts. Loops showing fewer than three drawings continue to be read on every frame (seam_read.read: cells). - Report: Reports record whether the seam gate read frames or drawings. On every walk or run whose seam ratio gates the cut,
seam_readrecordsread(cellsordrawings),drawings, andhold. When--anchor bodyramps cells and triggers a re-read,seam_after_anchorrecords those same three fields for the cells that play, and itslargest_step_intonames the first frame of a drawing. Strip sidecarstrip.jsondoes not change. - Known limits: Measuring between drawings allows cuts from a third of the stride short to a sixth long on twos, and from a third short to a quarter long on threes, to pass. On synthetic 24-frame stride walks standing in place, cuts of 16 to 28 frames on twos (ratio 1.02 to 1.67; 30 refused at 2.06) and 16 to 30 frames on threes (0.95 to 1.48) pass the seam gate, whereas drawn on ones cuts of 16 to 22, 28, and 30 are refused (2.38 to 4.07). A shifted final drawing passes up to 2 px on twos (1.66; 3 px refused) and up to 4 px on threes (1.73; 6 px refused). Under
--anchor bodysliding 0.2 px a frame, cuts of 16 to 28 frames pass on twos and 16 to 30 on threes, tolerating shifts of 2 px on twos and 6 px on threes. The step gate already passed these cuts (largest step 1.26 to 1.86), while the earlier frame-by-frame seam gate refused them all. For full synthetic limits and ramp discretization behavior, seedocs/loop-review.mdsection "The body anchor and the seam gate". - Tests:
tests/video/test_held_walk_seam.py: a held walk cut between its drawings passes the seam gate on twos and threes; a walk drawn a frame each is read on every frame and its ratio is the frames' own; a held walk whose last drawing is moved 10 px is refused between its drawings; a held sliding walk passes on the drawings the ramp plays, and a jump the ramp moves into a held walk is refused as the source frames refuse it; a held walk motion-auto cuts passes on its cells between their drawings (a side walk on twos, a side walker on threes); motion-auto's seam gate reads a held cut between its drawings, and a last drawing with a band of its body gone is over the limit.tests/video/test_walk_steps.py: the walker on threes with a tail on its own beat records its tried two-step cut within the seam gate between drawings, declined as out of phase; the search's cut stands as before.
Upgrading from 3.0.0: walk and run loops whose seam pop exceeds the bound are now refused by default. The check is governed by --seam-pop-max BOUND|off (default 10). The flag --seam-max does not lift this gate. Callers that force delivery with --seam-max 1000 or scan fixed cuts with lifted gates must add --seam-pop-max off beside --seam-max 1000 to deliver what they delivered before. Callers matching failure lines by their first words need a rule for video-loop: loop seam pop. Loops that pass the gate, loops with an unreadable top band, and pinned clips produce the exact same files as before, save an --anchor motion-auto cut taken in place of a first choice the gate would have refused before the cut.
- Behavior change: seam pop is now a gate. A walk or run loop whose
popis over the bound is refused, while a pop exactly at the bound passes. The gate applies to all walk or run loops gated by seam ratio (--cycle fixed, periodic searches,--anchor motion-auto, and--repair off), but does not gate pinned clips (--cycle pinned). The check runs after the seam gate and step gate; cuts refused by earlier gates fail with their existing lines. On refusal, the failure line isvideo-loop: loop seam pop <pop> exceeds <bound> (<kind> length <L> frames from <start>): the top of the silhouette jumps into the loop's first frame up or down <percent> % of the body height, <ratio>x its median step — the loop does not close at its top; cut it where it does, or regenerate the clip, detailing the pop, bound, cut, and directional jump metrics, without printing a warning line or adding tojolt.warnings. Loops whose top band cannot be read pass with verdictunreadableand retain their warning line. The flag--seam-maxdoes not lift this gate, because seam pop measures top band placement rather than seam ratio distance. - New:
--seam-pop-maxflag.video-loop --seam-pop-max BOUND|offsets the seam pop bound. It defaults to 10 (repair.SEAM_POP_REFERENCE) and accepts any number over 0, oroffto turn the gate off. - Behavior change:
--anchor motion-autoevaluates candidates for seam pop before cutting. Before a cut is taken, candidate cuts are evaluated usingloop.corrected_cutandrepair.seam_pop_of. If the search cut would be refused, the engine evaluates up to four candidates (local_cycle.SEAM_TRIES) in search order (equivalent cuts earliest first, then remaining best first) and selects the first passing cut; if all four fail, the first choice stays and fails on the loop. For step counts, foot crossing cuts passing the seam gate are checked for pop, taking the first of four cuts that passes both gates. Every motion-auto run now corrects the search cut once before taking the cut. - Report:
seam_pop_gaterecord and step count fields. Walk and run reports and CLI summaries addseam_pop_gatecontainingverdict(passed,refused,unreadable,off, ornot-applicable),max,pop, andwhy. Failed reports include this record as well. Motion-auto searches recordcycle.seam_pop_gatewithmax,tried,applied, andwhy. In addition,step_count.seam_gate.triedrows andstep_count.searchgainpop,pop_gate, andpop_skipped. - Tests: synthetic and unit coverage. Synthetic tests in
tests/video/test_seam_pop_gate.pyverify a standing rod walk where an 11 px tip drop reads a pop of 11.0 and is refused, while a 9 px drop reads 9.0 and passes. Tests confirm that bound 12 or--seam-pop-max offkeeps the 11 px loop with identical files,--seam-max 1000alone does not keep it, unreadable tops pass asunreadable, pinned clips reportnot-applicable, and--anchor motion-autoswitches from a cut with pop 6.0 (5.0 on twos) to a passing cut with pop 0.0 under bound 3. Unit tests coverrepair.seam_pop_gate,local_cycle._pop_gate,detect, andby_steps. Intests/video/test_loop_prop_seam.py, fixed cuts with dropping staff tips are preserved under--seam-pop-max off.
v3.0.0 - Remove rig layer composition
Upgrading from 2.46.0: sprite-gen compose-layers and its other launch forms are removed, and rig layer declarations are no longer read. compose-atlas no longer writes a manifest rig block or animation.rows.<state>.track for a run that declared a rig. Runs that never declared rig, layers or a state track get the same manifest as before. Existing run files and layers/ folders stay on disk.
Breaking
The rig layer feature has no replacement in 3.0.0:
| Removed | Use |
|---|---|
sprite-gen compose-layers, python -m sprite_gen.compose.compose_layers, scripts/compose_layers.py |
No replacement. The CLI verb now ends as an unknown command with argparse exit code 2. |
sprite_gen/compose/layers.py (declaration checks for rig profiles, row tracks and composite stacks), sprite_gen/compose/compose_layers.py (baking declared stacks into <run>/layers/) |
No replacement. |
sprite-request.json keys rig, layers and states.<state>.track |
Remove them with sprite-gen migrate-request <run> --apply. |
sprite_gen.spec.runio.normalize_retired_fit_keys |
normalize_retired_keys, which returns a list of keys moved or left out, or an empty list. |
docs/layer-tracks.md |
No replacement. Its links are gone from the other docs, READMEs and SKILL.md; the skill description no longer lists "rig layers". |
preparedrops the retired keys from--requestand--request-json, naming them in its existing stderr note. Code no longer reads them. On the first read of an old run's request, the process prints one stderr line naming the keys, treats them as absent in memory and leaves the file byte for byte unchanged. Unrelated request rewrites, including reroll and interpolate takes and curation fps edits, preserve those keys as they were.sprite-gen migrate-request <run>lists the keys it would remove without writing.--applyremoves them from the file; a second apply has nothing to move. The changed bytes moverun_revision, and the command names the curation rows it will drop before writing. The command also retains its existingfit.pixel_perfecttofit.pixel_unfakemigration.runio.migrate_request_filenow returns the list of keys moved or left out instead of a boolean.- Talking face parts are planned as a new feature in a later 3.x minor release.
- Tests: Added
tests/spec/test_request_retired_rig_keys.pyto check the one-time stderr note and unchanged old request bytes, migration dry runs and repeated applies, preservation on unrelated edits, and named drops inprepare. Removedtests/compose/test_layer_compose.py,tests/compose/test_layer_contract.pyandtests/packaging/test_layer_cli_entrypoint.pywith the feature.
v2.46.0 - Changed loop and framing defaults, recognition of cyan or yellow leaning green border keys, Breathe smooth mode and Sway commands
Upgrading from 2.45.3: Some existing runs produce different bytes because defaults changed.
video-loop --cycle pinned with --anchor none now blends the wrap when the pin passes its gate and the pinned last frame redraws the first.
A redraw means the first cell differs from the pinned frame by more than --seam-max (default 2.0) times the cut's median step at full size.
Those cuts have different cycle/ cells over the last half second, and a different strip, GIF and WebP.
video-set takes this default for idle and attack clips filmed with their first frame as the last; a walk or run cut the same way is blended too.
The blend does not read the state, and --wrap-blend off cuts as filmed.
Every pinned cut gains the report key wrap_blend, which also appears in strip metadata where the blend applied.
A source projection reads a blended strip as source-processing-unsupported.
Under --repair auto or --repair on, a loop that is not a walk or run and is cut to play as a loop now has its wrap read against the steps beside it.
This excludes --cycle once, once-return and an effect's lifetime.
When the wrap step exceeds --seam-max times the mean of the three steps on either side and exceeds 0.005, RIFE makes one, two or four frames round the wrap again.
Such a loop can have different cells, strip, GIF and WebP, or pass where 2.45.3 refused it.
Its report now reads jump_repair.reading: "seam" instead of "why": "not a gait state (...)".
Without RIFE, a wrap needing the bridge is cut as filmed and a warning: line names sprite-gen rife install; with --repair on, the run is refused.
The bridge reads the wrap after the blend, so a pinned idle or attack can receive both.
A pinned clip whose pin the gate refuses is not bridged and is refused on its pin as before.
Walk and run loops retain their 2.45.3 bytes except when cut pinned with --anchor none and a last frame that redraws the first; --wrap-blend off restores those bytes.
For a loop that is not a walk or run, --repair off --wrap-blend off restores the 2.45.3 cells, strip, GIF and WebP, with "why": "--repair off" in the report.
Do not use --repair off to restore a walk or run: it also disables the jump repair that ran by default in 2.45.3.
The default video-frames edge check (edge_policy) is now border instead of refuse.
A clip whose first-frame subject covers at least 2 % of the outermost row or column on the top, left or right now passes where 2.45.3 refused every frame as "framed too tight".
If the first frame crosses no side, it is judged and worded as in 2.45.3; --allow-subject-edge-contact and --allow-edge-contact also judge as before.
In a refusal, the top, left and right numbers now count pixels the border does not take.
The video-frames report gains edge_border, and each contact row gains rim.
A refused video-frames run leaves frames in keyed.refused/, removes keyed/ even from an earlier run, and writes a report with status set to passed or refused.
A refused video-loop run removes an earlier cut's cycle/, strip, strip metadata, GIF, WebP, cycle.source/ and follow.source.png from the output folder; a cut already written is kept as cycle.refused/.
A passing run delivers the same bytes as before, while a caller that misses a refusal's exit code no longer finds an earlier run's files.
Borders already recognised as a green key in 2.45.3 key byte for byte as before under the same key.
A border green leaning toward cyan or yellow, such as #00B140, now uses the green key: cutout --key auto and video-frames use it instead of the position-based white matte, video-canvas repaints such a still to the exact key and accepts --key green, and video-frames --spill auto reads it as full.
Those outputs can change; Python callers of extract.detect_background_key_rgb can pass the new threshold argument, which the engine supplies from --key-threshold (default 96).
New commands are sprite-gen breathe, video-sway and video-sway-inspect, and Breathe gains a smooth mode for large illustrations and video frames.
Breathe without mode or with mode: "pixel" keeps the same bytes and sidecar; new Breathe values set to 0 or omitted also keep the same bytes.
video-follow and video-follow-inspect keep their names and files, including the follow record, follow.source.png strip and follow-inspect.* inspection files.
Moving the written names to sway is a later change made together with the tools that read them.
Every command now reopens stdout and stderr as UTF-8 where needed so it can print on Windows consoles or pipes using cp949 or cp1252; importing sprite_gen leaves the caller's streams alone.
Restoration schemas remain source-restoration-v5, repair report schema_version 4 and comparison schema_version 6, while the report's producer names the new version.
2.45.3 changed only the --anchor body seam check, so detailed comparisons below with 2.45.2 for keying, framing and video-frames also hold for 2.45.3.
- Changed (default): A video model given the first frame as the last draws that frame again (softer or sharper, another tone, hair strands a pixel over).
The pin gate reads the pose and passes.
The drawing stays, so the loop's wrap shows one jump in sharpness where every other step shows the motion.
Over the cut's last half second (K = min(round(0.5 s x fps), floor(L / 4)) cells, 12 at 24 fps), wrap blending adds back j/(K+1) of the redraw's difference (first cell minus pinned frame, premultiplied) on the j-th cell.
Each pose stays the cell's own, and its drawing turns into the first cell's by the wrap.
Only a redraw is ramped.
A pixel is held where the two ends hold a part, a line or a dot in different places, and where a ramp cell does not stand where the pinned frame stands.
This check applies after one softness match of at most 0.7 px.
A pixel is held if it is more than 12 levels outside what the other end holds within 1 px on a 7x7 mean or a 7 px run, over black and over white.
It is also held if its value is more than 12 outside the other end's 1 px range where the other end has under half this end's range there, in any direction, length or width.
Held pixels are widened 3 px and the weight feathered 7x7.
A pixel of weight 0 is the filmed byte.
A ramp that steps more than the cut already does, or that does not shrink the wrap, is not used: the cut is written as filmed and a
warning:line says so. A wrap still over--seam-maxafter blending also gets awarning:line. New flag (defaultauto, andvideo-settakes the default):video-loop --wrap-blend auto|offNew report keywrap_blendon every pinned cut (applied,why,K,cells,residual_ratio,wrap_ratio_before,wrap_ratio_after,ramp_step_max_ratio,bound_ratio,pose_share,presence_share,never_settled,equalize,after_check,seconds).wrap_blend: {cells, K}appears in the strip metadata where it applied, and in the CLI summary. loop repair - Tests:
tests/video/test_wrap_blend.pyon synthetic clips: a redraw of tone and 0.5 px softness has its wrap brought from 7.31x to 0.57x the median step and only the ramp's cells, strip, GIF and WebP differ from off; an arm still coming down in the ramp stays the filmed arm; a part moved 2 to 64 px, or present at one end only, is never drawn twice (the 14 px part on a flat figure is cut as filmed with a warning); 1 px lines moved 2 to 32 px on a flat figure are byte for byte; stripes swinging inside the ramp keep their swing; a strand against the silhouette is held over white where black alone lets it through; the softness match blurs the sharper end, never past 0.7 px; the idle-still fixture gives every output byte for byte; fixed cuts, body-anchored pinned cuts and refused pins are not touched; a ramp that steps past the cut is refused with a warning; a 1 px line at slope 1/3 moved 8 px is held line for line, thin structures change by at most 2 levels and busier quiet grounds by at most 3, strands off the silhouette by none. - Changed:
video-loopbridges a jumping wrap on idle and action loops (repair.seam_bridge). Under--repair auto(the default) or--repair on, a loop whose state is not a gait (idle, jump, attack, or a generic in-place action) has its wrap read against the steps beside it; where it jumps, one, two, or four frames round the wrap are made again by RIFE between the frames either side; the loop is not read for its flow (an idle's own motion would leave it). See loop repair. - Tests:
tests/video/test_seam_bridge.pycovers the synthetic idle with wrap jump J = 2.6 closed by one frame and passing the gate, J = 5 tried at one and two frames then closed by four, J = 12 refused without frames made, J = 1 closed loop untouched without an interpolator, whole-pixel stepped motion not bridged, near-still loop under the noise floor not bridged, loop drawn on twos skipped, real RIFE (rife-v4.6 with augmentation) closing J = 2.6 without faults, frames made with a fault (a stand-in painting a dark patch: smear at every width, seven calls, nothing taken, gate refuses as before), missing RIFE where the wrap is cut as filmed with the install line injump_repairand awarning:line, a wrap that reads as a step saying nothing,--repair onrefusing with the install line, a pinned clip whose pin the gate refuses skipped without reading and refused on its pin, the CLI summary naming the frames made, and the report naming the RIFE that made them; a--repair onrun without RIFE, in an output folder where an earlier cut passed, refused on a wrap needing the bridge and leaving none of that cut'scycle/, strip, strip metadata, GIF or WebP, and nocycle.refused/because the new cut was not yet written. - Default change: A drawing cut by its own frame is no longer refused as framed too tight. A bust or half-length drawing runs off the frame itself (its sleeve cut off at the left, its hair at the top), so in every frame of its clip the subject touches those edges and no canvas gives it room there. In 2.45.2 the default
video-framesedge check refused every frame of such a clip with "the subject touches the frame edge ... framed too tight". Only a flag let it through:--allow-subject-edge-contact, which also lets through a subject that really leaves the frame, or--allow-edge-contact, which turns the check off. The default (edge_policyis nowborder, wasrefuse) reads the drawing's own border on the clip's first frame, keyed with its specks erased: a side (top, left, right) whose outermost row or column the subject covers for at least 2 % of its length (frames.BORDER_MIN_FRACTION) is a border side. Subject contact there is accepted in every frame, wherever along the side. Subject contact on any other side is still refused as framed too tight (a bust cut at the top and left whose hand leaves the right). The top / left / right numbers in a refusal are now the pixels the border does not take, so a caller that reads them to choose a taller or wider canvas reads the side that needs room. Leftover key is still refused, except the body's rim the matte cut loose: a key-only piece is accepted only on a border side the same frame's subject reaches, holding fewer than 8 pixels in all (SPECK_MIN_PX) and lying wholly within 10 px of the frame's body (frames.RIM_REACH, counted each way and diagonally; the body is the largest piece holding a pixel off the key). A thin outline blended with the key leaves such pieces at the edge between strands. Larger pieces, farther pieces, pieces on other sides or on a side the frame's subject left, and a detached stain beside a sleeve on the same side are refused as in 2.45.2. A clip whose first frame crosses no side is judged and worded exactly as in 2.45.2, byte for byte. The two flags judge as in 2.45.2. Taking a side as the border prints one stderr line. The report gainsedge_border(frame,sides,outer_px,min_fraction,rim_reach,rim_under_px); each contact row gainsrim, and under the defaultborder(pixels taken) andoff(pixels not taken, by side). Known limit: a hand that newly leaves the frame on a side that is already a border side is accepted; by position it cannot be told from the sleeve moving along the edge. video pipeline, section 3. - Default change: A refused run hands nothing over. A caller that does not read the exit code used a refused run's output as if it had passed. In 2.45.2 a refused
video-framesrun left its keyed frames inkeyed/and wrote no report.keyed/was not emptied before keying, so a pass after a longer earlier run in the same folder also held the earlier run's extra frames. A refusedvideo-looprun could leave a mixed set: for example after the pin gate refused,cycle/and the strip were the refused run's while the GIF and WebP were an earlier run's; a refusal before the cut left the earlier run's whole set. Nowvideo-frameskeys into a hidden working folder and hands overkeyed/only when the run passes. A refused run (the edge check, or a frame keyed to 0 % transparency) leaves its frames askeyed.refused/and nokeyed/, not even an earlier run's. A pass removeskeyed.refused/. The report is written either way, withstatus(passedorrefused); a refused report addserror,refused_dirandkeyed_dir: null. Keyed frames that pass are the same bytes as before. Everyvideo-looprefusal that writesstatus: failed(selection, motion anchor, jump repair, jolt, pin, seam, a strip with no body, a GIF or WebP that could not be written or verified) removescycle/,<name>.strip.png,<name>.strip.json,<name>.gif,<name>.webp,cycle.source/andfollow.source.pngfrom the output folder. A cut it had already written is kept ascycle.refused/, which the next pass removes. A strip with no body and a GIF or WebP that could not be written now also write the failed report. Argument errors touch nothing. video pipeline, sections 3 and 4. - Tests -
tests/video/test_edge_border.py(a bust cut at the top and left passes and the report names its border; a padded jump whose head leaves the top and a first frame with a 2 px wisp on the top are refused with the 2.45.2 message, byte for byte; a key-only patch with no border is worded as in 2.45.2; a hand leaving the right of a bust is framing, its message counting only the right; a hand leaving a border side elsewhere is accepted (the known limit); leftover key that is not the body's rim is refused (a patch on the right, a 48 px fringe beside the sleeve, a patch where the sleeve left, a detached 20 x 90 stain, 2 px pieces 11 and 14 px from the sleeve, pieces of 8 px and more, stripes hugging the head, stains beside the head, a fringe on a side that is not the border, a fringe above a head clear of the top band, a stain round a fleck of the body's colour); 1 px dots are judged piece by piece; 2 px pieces 2 to 10 px from the sleeve and a 7 px piece are the rim; an 8 px piece with 4 pixels in the band and a 7 px piece 11 px away are refused; the two flags judge as in 2.45.2;classify_edge_contactcounts the rim; a refusedvideo-framesrun leaveskeyed.refused/, nokeyed/and a refused report; a pass after a refusal leaveskeyed/alone; a pass over a longer run holds its own frames only; a frame keyed to 0 % transparency is refused the same way; an argument error touches nothing; avideo-loopcut refused after it was written hands nothing over and keepscycle.refused/, removed by the next pass; a cut refused before it was written hands nothing over; a loop argument error touches nothing),tests/video/test_canvas_key_normalize.pyandtests/video/test_fit_tight.py(the 2.45.2 default's framing and mixed-contact tests now move the contact after the first frame and read the refused frames fromkeyed.refused/),tests/video/test_edge_speck_lead_in.py(the default policy is namedborder, and the refused frames are read fromkeyed.refused/),tests/frames/test_chroma_key_relative.py(the edge-contact split states therimcountclassify_edge_contactnow gives). - Fix: Green screens that lean toward cyan or yellow are now recognised as border keys. A green screen that leans toward cyan or yellow was not recognised as the key on the border. Examples: the studio chroma-key green
#00B140, (0, 177, 64); (0, 200, 90), which leans toward cyan; (90, 210, 0), which leans toward yellow. Each sits more than 96 from pure green. With--key greenthe whole background stayed opaque, andvideo-canvasrefused--key greenon such a still; but with--key autothe old rule did not take the green route at all:cutoutandvideo-framesrouted the frame to the white (position-based) matte, andvideo-canvastreated the still as a non-key base and did not normalize it.video-frames --spill autodid not always choosefull: when the reference still had the same leaning green,autoread the surviving background as key material and chosesmall; when it chosefull(a reference whose own background the old rule did recognise), the clip's surviving background was despilled to a blue-grey instead of being erased. The cause was that the border ruleextract.is_border_key_candidateheld every unkeyed channel under 64. That bar was set between magentas, whose one unkeyed channel (green) tells a painted magenta from hot pink. Green has two unkeyed channels, and a green screen leans on one of them. For the fix, the darkest unkeyed channel keeps the bar (under 64, and at most 35 % of the brightest keyed channel). The brightest one only has to stay under half of the brightest keyed channel (extract._BORDER_KEY_MAX_LEAN_RATIO, 0.5), that is a hue nearer green than yellow or cyan (between 90 and 150 degrees). The border detector,extract.detect_background_key_rgb, reads the lean second. It first counts, on their own, the candidates the 2.45.2 rule admitted. When those make up at least 12% of the samples, it returns the mean of their most populated bin, exactly the colour 2.45.2 returned. Below 12%, the samples only the lean admits join them, but their most populated bin gives the colour only where the declared key's own cut would leave that background on the border. Two conditions, both needed: the samples only the lean admits that lie farther from the declared key than the cut (the radius the caller keys with: the newthresholdargument ofdetect_background_key_rgb, which the engine sets from--key-threshold, 96 by default), in that most populated bin or in a bin beside it on every channel, make up at least 2% of the samples; and the candidates outside that bin and the bins beside it make up less than 12% of the samples (the border holds one key-coloured background). Otherwise the declared key is kept, as in 2.45.2. A leaning border the declared key clears by itself gains nothing from the leaning colour; its ball would only reach further into a subject near that colour: (0, 210, 80) sits 91.8 from pure green, inside the cut of 96, so the declared key erases that background on its own, and a teal subject (0, 154, 149), 180 from the key, is kept; read as the painted colour, (0, 210, 80), 88.9 from the teal, let the ball reach the teal subject through the background and erase all of it, with no background gained. The 2% keeps the soft rim where a subject meets an edge of the frame (its blend with the background crossing the cut there) from being read as background the cut left; and a background whose tail past the cut is under 2% of the border keys as before the lean, the few pixels past the cut included. A second key-coloured colour on the border may be the subject's own (a leaf along an edge, another green); read as part of the background it would let the ball take a subject colour near the dominant one.cutout, the reference windowvideo-frames --spill autokeys, and the YCbCr path's decontamination pass hand the detector the radius they key with, as the engine does. The painted key's erase ball, the spill judgment's subject window and thevideo-framesedge-contact split take the lean only from a painted colour that leans itself (extract._painted_key_leans). A colour found the first way never leans itself (magenta has no lean; for green the floor of the mean of one 8-wide bin of 2.45.2 candidates is always one of them), so they read it as 2.45.2 did.cutout --key autoandvideo-canvas --keyclassify the flat corner colour with the border rule, lean included (there the question is what the painted colour can be): a corner colour 2.45.2 took routes as before, and a leaning corner colour now routes to green. The magenta key is exactly as before (its one unkeyed channel is both the darkest and the brightest), so hot pink (250, 77, 150) and purple (213, 112, 246) are still refused. For green, nothing that was a candidate is dropped. Ivory, cyan, teal, sea green, a grey-green with both unkeyed channels lit and a green as near cyan as green are still refused. The interior ruleis_key_familyis unchanged. As a consequence, every image whose border the 2.45.2 rule recognised (its candidates at least 12% of the corner and border samples) keys byte for byte as in 2.45.2 under the same key, whatever leaning green is mixed into that border and in whatever share. Under the same key, every image is keyed either exactly as in 2.45.2 or exactly as with the leaning colour read. As in 2.45.2: wherever the 2.45.2 rule recognised the border (its candidates at least 12% of the corner and border samples), wherever the declared key's cut clears a leaning border by itself, and wherever the border holds a second key-coloured colour. With the leaning colour: where the key's cut leaves the border's one leaning background. Read together, a sample admitted only through the lean can share the 8-wide bin of a background 2.45.2 already found and move its mean, while leaning samples in a bin of their own that outnumber the background would take the mode. A leaning-green part of the subject on the corners and the border can be taken as the painted colour only where the 2.45.2 rule's candidates make up less than 12% of the samples, the key's cut leaves it and no other key-coloured colour holds 12% of the border, that is, only where the subject crowds the border. A leaning-green patch buried in the subject on such a background is kept. chroma-alpha, the 2026-10-21 paragraph. - Tests -
tests/frames/test_chroma_key_relative.py(the border table with the three leaning greens accepted and a grey-green and a cyan-midpoint green refused; the detector still refuses hot pink, purple, ivory, cyan, (30, 60, 30), teal, sea green and those two; over the whole RGB cube the lean adds nothing for magenta, drops nothing for either key, and adds for green only hues between 90 and 150 degrees; without the lean the candidate field is the old rule colour for colour over the whole RGB cube; the engine andcutout --key greenkey the leaning greens out with the subject byte-identical;cutout --key autoroutes a leaning green toextract:green; a leaning-green patch ((0, 160, 75) or (10, 120, 50)) buried in the subject is kept byte for byte on (8, 162, 24) and keyed with the background on (0, 200, 90); the edge-contact split reads a leaning piece as residual when the frame was keyed from a leaning background and as the subject's when it was keyed from (8, 162, 24); on (0, 200, 64) with a leaning green, (0, 200, 71) in its bin or (0, 200, 90) in a bin of its own, over the top-left corner (20.5% of the samples) or everywhere but a 32 x 32 block of the background (77.3%), the detector returns (0, 200, 64) and the frame keys exactly as from that colour pinned, a teal subject (0, 154, 149) just outside the ball keeping every pixel; a leaning-green border on (0, 200, 90), past the cut, with no 2.45.2 candidate, or with a block of one under 12% of the samples, is found through the lean and keys out; and over every 8-wide bin of green, the floor of the mean of 2.45.2 candidates is one of them; on (0, 210, 80), inside the key's cut, with no 2.45.2 candidate on the border or with 11% of the samples an interior-family green, the detector keeps the declared key and the frame keys exactly as with the key pinned, a teal subject (0, 154, 149) losing no pixel; a leaning-green leaf of the subject along the bottom edge over a leaning background the key clears, a second leaning green in a corner, and a soft rim crossing the cut where the subject meets the side edges each keep the declared key; with 1.5% of the border a step past the cut the key is kept, and with 2.5% the leaning colour is read; (0, 200, 90) is read with a cut of 96 and not with a cut of 110; over a sweep of borders around the cut every answer is the 2.45.2 answer or the answer that reads the lean, and both occur, as do borders where the two differ and the key is kept),tests/frames/test_key_detect_banded.py(the whole-image reference now states this rule, and leaning-green borders (past, across and inside the cut, and two leaning greens on one border) join the images the banded detector is checked against),tests/video/test_canvas_key_normalize.py(video-canvasrepaints a leaning-green still to the exact key and accepts--key greenon it), andtests/video/test_video_spill.py(on a leaning green,--spill autoreads the reference asfullwith no key material, and the frame keys with no opaque background pixel and no edge contact, the subject byte-identical, with--decontam offandpalette). - New: The Breathe layer adds
mode: "smooth"for large illustrations and video frames. Set per row:states.<state>.breathe = {"mode": "smooth", "depth": ..., "breaths": ...}.pixelstays the default. The head and everything above the measured neck line stays in place, byte for byte, in every cell. The figure's bottom stays put. It reuses the automatic anatomy: rigid row, body axis, torso half width, and basis rows. It also uses the neck's width, measured once on the row's first cell. The whole row uses that placement. The chest breathes from its centre. It uses a round (cos^2) weight on the body axis atchest_yof the body below the neck. The weight ischest_rxx torso half width wide, andchest_ryx the body below the neck tall. The chest centre rises bydepthx basis rows at the in-breath and puffs out bydepth_xfrom P (not from the ellipse centre). Two shoulder weights, on either side just below the neck, rise byshoulderx the chest's rise. They riseshoulder_lagof a breath later. The neck and the collar beside it hold still. Whole rows do not move. For a figure whose body axis is pulled to one side (for example by long hair), the chest is not on the axis:chest_xmoves the chest ellipse's centre off the body axis, in torso half widths (-1 to 1). The shoulders stay where they were (relative to the body axis). For a turned body:chest_tilt(degrees, clockwise on screen) andchest_dir(degrees from straight up, negative = up-left).chest_biasmoves the chest weight's peak P along the chest ellipse's long axis, as a share of its horizontal half width (-0.9 to 0.9, negative is the screen's left).chest_bias_ymoves the peak P across the long axis, as a share of the vertical half height (-0.9 to 0.9, positive is down). The weight falls from P to the ellipse's rim along the ray from P through each point, so the near side falls off over a short distance and the far side over a long one. P must stay inside the ellipse:chest_biasandchest_bias_ytogether at most 0.9 of the radii (refused otherwise).chest_flatis the share of the way from the peak P to the rim that rises in full (0 to 0.9). These default to 0; at 0, nothing changes. One breath is a bump from rest (in-breath 40 %, out 60 %). A cell at phase 0 is the source byte for byte. Seams and joins between loops are untouched.breathsis a whole number.breath_peaksis a list of cells where each in-breath peaks, for timing the breath from outside (for example to keep the breath's peaks off a big hand movement in the clip). The breath count is the number of peaks (breaths, if given, must match). The first cell stays at rest and the loop closes at rest: breaths are separated by rests at cell 0, between two peaks where the out-breath has taken 60 % of the gap and the next in-breath 40 %, and at the loop's end. Refused, never silently clamped:lagon smooth (it would move the first cell), a stretch past the per-row strain cap (0.25) or a fold, opaque pixels pushed off the canvas, out-of-range values,chest_biasandchest_bias_ytogether past 0.9 of the radii, a peak at cell 0, peaks not increasing or closer than two cells, a last peak within one cell of the loop's end, mismatchedbreaths, and shape keys orbreath_peakson a pixel row. With the default shape nothing leaves the canvas. A figure cut by the frame at its sides or bottom is not refused. Defaults:depth0.0085 (about 0.5 % of the frame height on a bust illustration),depth_x0.028,chest_y0.31,chest_rx0.83,chest_ry0.28,shoulder0.5,shoulder_lag0.08, andchest_tilt,chest_bias,chest_bias_y,chest_dir,chest_x, andchest_flat0. Performance is about 0.2 s per 960 px frame. - New:
sprite-gen breathe <frames> <out>lays the Breathe layer over a folder of loop frames outside curation. This lays the Breathe layer (either mode) over a folder of loop frames that is not a curation run, such as a video loop's cells. It takes the sidecar's values through the same checks and the same bake:--mode,--depth,--depth-x,--breaths,--breath-peaks(for example--breath-peaks 30,102),--lag, and--rigid-row. It also takes the smooth shape flags:--chest-y,--chest-rx,--chest-ry,--shoulder,--shoulder-lag,--chest-tilt,--chest-bias,--chest-bias-y,--chest-dir,--chest-x, and--chest-flat. The same values give the same bytes as a curation bake. It writes the frames under their names andbreathe.json(config, phases, the anatomy used) into a new folder all at once. Before creating or deleting anything, it refuses if<out>and<frames>are the same folder, if either lies inside the other based on real disk location (following symbolic links and treating two spellings on a case-insensitive disk as the same folder), or if<out>already exists and is not empty, while an existing empty folder is accepted. It never writes anything into<frames>, and it never changes or deletes any frames or other files there. It builds the result in a temporary folder of its own next to<out>, with a name no other folder has, and moves it into place in one step, deleting only that temporary folder if a run cannot finish while leaving alone folders it did not make, such as a leftover temporary folder of an earlier run. When<out>is a symbolic link to an empty folder, the result is placed in the folder the link points to, and the link stays. - Output change: The curation webview does not preview a smooth row. The live preview mirrors the pixel warp only. It shows the original frame with a notice. Its row video export refuses. Saving keeps a smooth sidecar exactly as written instead of filling pixel defaults.
- New: The follow-through is now the Sway layer, replacing
video-followwithvideo-sway.video-swayandvideo-sway-inspectreplacevideo-followandvideo-follow-inspect. Their Python modules aresprite_gen.video.sway,sway_loop,sway_offsets, andsprite_gen.video.sway_inspect.video-followandvideo-follow-inspectremain as aliases with the same results and their own name in messages. A loop's record is read underswayorfollow. Behaviour is unchanged. - New:
Anatomygainsoriginandneck_spanvalues. It does not put these two values in the sidecar or the manifest.originrecords where the measured frame's figure sits.neck_spanrecords the neck's span on the rigid row. Pixel Breathe does not use them. - Fix: every command prints on a Windows console or pipe in a legacy code page. A line a command prints can hold an em dash, Korean or a path in any script; on cp949 (Korean Windows) or cp1252 Python could not encode it, and the command died at the print after its work was done (
background-tileon Korean Windows). Each command's entry now reopens stdout and stderr as UTF-8 where they are not already (sprite_gen.util.console.utf8_streams, called first by everymain()and bysprite-gen); importing sprite_gen leaves a program's streams alone. Test:tests/util/test_console.py.
v2.45.3 - The seam check reads the frames that play when the body anchor spreads a sideways slide; such a cut passes again, as it did in 2.44.0
Upgrading from 2.45.2: Every cut 2.45.2 passed, and every --anchor motion-auto run, gives the same bytes as 2.45.2. Only --anchor body cuts that 2.45.2 refused because of the walk sliding sideways before the anchor can now pass, read on the frames that play. Refused cuts print the same error line as before, the report's producer field names the new version, and there are no restoration schema changes.
- Fix:
video-loop --anchor bodyno longer refuses an evenly sliding walk whose wrap the ramp closed when flow repair makes no frame. Up to 2.44.0 jump repair remade any frame after a step 1.4 times the median, reading rendered cells. Since 2.45.0 flow repair makes no frame for an evenly sliding walk, so the gate read source frames and refused a wrap the ramp closed: on the tests' synthetic walk (0.1 px right a frame, 2.4 px over 24 frames), 3.08 on source frames, 1.33 on cells that play. Now, where source frames refuse the wrap,wrap_dx_pxis not 0, no frame was made, and the cut is seam-gated, the gate reads the cells that play again (seam_as_filmed). It passes the cut on them (seam_measurement: rendered-cells,resampled_seam_ratio) when the wrap and largest step against the mean step are both within--seam-max. Every step is checked because the ramp moves wrap jumps inward. The report gainsseam_after_anchor(source_seam_ratio,seam_ratio,largest_step_ratio,largest_step_into). Passed cuts remain the same bytes, including--seam-max 1000;--anchor motion,motion-auto,noneandfeetdo not change, nor do pinned clips, flags, or restoration schemas. The reading is only as fine as the limit: half a stride with swapped legs reads 1.93 on cells that play and passes; without slide it reads 2.19 and is refused. loop review - Tests —
tests/video/test_body_anchor_gate.py(the sliding walk cut by hand from four starts with the repair off passes on the cells that play, and so does the walk cut by hand with the repair on and the stride the search finds, the repair making no frame; the source frames' refusal is the one--anchor nonegives the same cut; a wrap the ramp does not close is refused with the same error line as--anchor nonegives for one, two, three or four frames at the wrap moved 4 or 10 px sideways, a frame torn across, holed, or moved 8 px down, and cuts of 18 and 28 frames off the stride; a cut the source frames pass is not read again for the walk without the slide, the sliding walk under--seam-max 1000, and a first frame moved 3 px; a pinned clip of the sliding walk is gated by its pin and read on its source frames).
v2.45.2 - The new video-loop --overlap-wrap off turns the overlapped wrap off on its own; the motion anchor's fine search is faster and gives the same values
Upgrading from 2.45.1: By default a run delivers the same bytes as 2.45.1, sooner, and only --overlap-wrap off changes what is delivered. With the default --overlap-wrap on, the loop files, the frames and the report are the same bytes as 2.45.1 (the report's producer field names the new version), and video-loop --anchor motion-auto finishes sooner. With --overlap-wrap off, the overlapped wrap is not tried (the report's wrap_overlap.skipped reads turned off (--overlap-wrap off), no RIFE calls), a warning: line is printed, and the seam gate refuses the cut as filmed, so the run fails on its seam instead of spending minutes of CPU on RIFE. No restoration schemas change: source-restoration-v5, repair report schema_version 4, comparison schema_version 6.
- New:
video-loop --overlap-wrap offturns the overlapped wrap off alone. Each frame the overlapped wrap makes is RIFE's frame read with its sixteen single passes, 34 calls of the binary: where RIFE runs on a CPU that is minutes a frame (on two CPU cores with the augmentation off, 160 to 174 s for a frame of a 960 × 960 synthetic walker), and a wrap refused at its first frame costs minutes a run, so a caller that stops the loop at a deadline stopped it before the loop could fail on its own seam. With--overlap-wrap off(the default stayson) nothing is read or made for the wrap: the report'swrap_overlapsaysskipped: "turned off (--overlap-wrap off)"with notriesandcalls0, awarning:line says the overlapped wrap was not made, and the seam gate refuses the cut as filmed (video-loop: loop seam ratio … exceeds …). Nothing else changes: the jump repair, the eased retime and the gate run as with it on, and--repair offstill turns it off with them. - Faster: the motion anchor's fine search reads a row of shifts at once, to the same values.
video-loop --anchor motion-autocorrects every two-step cut its seam gate tries before one is taken (up to four,local_cycle.SEAM_TRIES) and then the cut it takes, and each correction runs the fine search six times (motion_anchor._register: 29 × 57 shifts, two masked regions). The search read each shift's masked patch alone, numpy reducing a patch a pixel row at a time, and on a CPU that was most of a walk's cut: on two CPU cores a 960 × 960 cut's correction took 63 s, and the 960 × 960 synthetic walker whose gate tries four cuts was cut (alone,--repair off) in 92 s. It now gathers the patches of a row of side-by-side shifts together, a block of mask pixels at a time (motion_anchor.ROW_BLOCK), and runs the operations one patch read alone takes in the same order — a patch's mean sums its pixels one after the other, its other two sums run over that patch alone — so every cost is the same value, and the match, the report, the cut and the frames are the same bytes as before. On the same two cores the correction takes 7 s and the walker's cut 27 s. - Tests —
tests/video/test_loop_overlap.py(with the overlapped wrap off, the front walker whose tail swings on its own beat has nothing read for its wrap, records it turned off and fails on its seam with the warning line; the closed wrap is the same for the default and an expliciton;video-loop's argv carries--overlap-wrap offwith no RIFE installed,onis the default and another word is refused);tests/video/test_motion_anchor.py(the fine search against one patch at a time, kept in the test as it was: the same match, costs, search-boundary measurement or none, compared by repr, on the walker, shifts that lay a region off the frame, the search boundary, noise with a flat half or a hole, and a flat frame, with a region past one block of mask pixels; a 960 cut corrected in under half the time this host takes one patch at a time).
v2.45.1 - An eased stretch that stops the legs is refused; the loop keeps the flow repair
Upgrading from 2.45.0: An eased stretch that puts the body off its beat is refused, its RIFE calls are still spent, and the round records its beat. Under video-loop --repair auto (and --repair on), an eased stretch is played only where every window of the rest of the body steps, in each step, as far as it did there in the loop as played, to within a quarter of its usual step (repair.EASE_BEAT, 0.25); otherwise it is refused for the body off its beat (listed in rejected_for), and the loop is delivered as the flow repair left it. RIFE calls made for the retime remain spent (up to 9 calls), the eased round's record gains a beat field (bound, off, off_max), and no command-line flags or restoration schemas change: source-restoration-v5, repair report schema_version 4, comparison schema_version 6.
- Fix:
video-loop --repair auto(andon) no longer plays an eased stretch that stops the legs. A frame RIFE makes is the whole picture at one time, so the times that spread a rushing tail gave the legs, the arms and the head the same times: they slowed to a stop where the tail was given its time and hurried on after (on the synthetic walkers of the tests, a leg 1.5 to 2.7 of its ordinary step off its step as filmed). The stretch is still read, made and recorded, and is played only where every window of the rest of the body steps, in each step of it, as far as it did there as the loop played, to within a quarter of its usual step (repair.EASE_BEAT, the round'sbeat); otherwise it is refused forthe body off its beatand the loop keeps the flow repair, each frame made at its own time. The calls the stretch made are still spent. loop-repair section 2, "The body's beat". - Tests —
tests/video/test_loop_ease.py(whatever spreads a rush, the two legs and the feet of four walkers step as filmed to within a quarter of their ordinary step, the flow repair alone as the control; the stretches 2.45.0 took — 24 frames, 16, 14, 48 on twos, mirrored, throughvideo-loop, at the half-loop cap — read, made and refused for the legs' beat alone, their frames made rebuilt to show the legs stop, the loop the flow repair's; with the bound lifted, a stretch is played as made).
v2.45.0 - Walk loops repaired along their flow, eased, closed from the clip's next cycle and cut two steps from their feet; RIFE runs with its augmentation; frames between kept for a later alignment; video-stop, play modes and logo
Upgrading from 2.44.0: RIFE costs more a frame, the jump repair names its readings anew, and a default codex that cannot run asks. Every RIFE call runs the binary's augmentation -x -z (rife.TTA), 15 to 19 times a plain call's CPU on a machine without a GPU: a caller on CPU sets SPRITE_GEN_RIFE_TTA (-x, -z, both, or empty for none) where it cannot afford it, and a call past 600 s is a RIFE that failed. Under video-loop --repair auto (and on) a loop may now call RIFE up to 3 times for the flow repair, up to 9 for the eased retime and, where a part on its own beat leaves the wrap open, 34 calls a frame for the overlapped wrap. jump_repair reports off_max_before / off_max_after in place of score_max_before / score_max_after, in the summary and in video-set's item record too, and repair.JUMP_RATIO is gone; a walk cut two steps from its crossings records cycle.steps and strip.json steps: 2. A call that names no provider, where codex cannot run, exits 75 with one question unless SPRITE_GEN_CODEX_UNAVAILABLE or sprite-gen defaults save --codex-unavailable chose another provider, and preferences.json is written as version 2, which 2.44.0 refuses. The restoration contract is unchanged: source-restoration-v5, repair report schema_version 4, comparison schema_version 6.
Fix:
video-loop --anchor motion-autokeeps the pixel search's cut where the clip's crossings miss a pass, and where no cut of two steps closes in its place. Seen from behind on a diagonal, the far foot passes hidden behind the near one, so the feet are seen apart once a cycle and together through the other step, its pass among them; in a clip on twos or threes a pass can also fall between two drawings. The count then sees one crossing a cycle, calls the clip's own cycle one step, and cut two cycles withsteps: 2— which the set alignment read as settling its two-cycle screen, so the loop walked twice as fast as the rest of the set. A cut the count calls an odd number of steps has the legs swapped a cut on; where a pass can hide — the feet seen together at a pass over more than half a step, the median of the runs the clip shows whole (crossings.Reading.overlap,HIDE_SHARE) — and the clip a cut on is the same picture instead — frame by frame along the cut, its frame a cut on at most 1.0 of the cut's playback steps off (local_cycle.same_picture,SAME_PICTURE_MAX) — no legs were swapped, the count missed a crossing, and the search's cut stands, its countuncertain(same-picture,step_count.search.same_picture), nostepswritten. Both are asked: from the side, legs drawn alike, a step on can draw as near as the next frame, and there the feet pass briefly and the count stands. A walk whose feet stand together through most of a step and whose two steps draw nearer than a frame apart is cut one step long, as the search cut it before the count. And a search's cut the count does not refute — a two out of phase, or uncertain — whose own seam the gate passes now gives way only to a two-step cut that passed the gates (in phase, its top calm, its wrap within the seam gate of its step, its seam under the flow limit) and whose seam the gate passes; where none does, the search's cut is kept (step_count.declined,step_count.search.seam, a warning line), where before a cut whose seam the gate refuses replaced a loop it passed. A search's cut the gate refuses too, or one the count refutes — one step or three, each seen — still gives way to the two-step cut, closing or not: its wrap may yet be closed by the overlapped wrap. On the synthetic walkers the far foot hiding behind the near reads 0.03 and 0.27 playback steps a cut on (on twos and on threes), the feet together 0.60 and 0.63 of a step, and the half step drawn with a tail on its own beat 2.12; a side walker whose two steps are one silhouette, near and far a tone apart, reads 0.89 a step on — the picture alone kept its half step — and is cut two steps, its feet together briefly; a clip the search finds no cycle in and whose crossings miss a pass a cycle is still cut two cycles long (loop-repair section 3, "The step count").Tests —
tests/video/test_walk_steps.py(a walker seen from behind on a diagonal, on twos and on threes, whose far foot passes hidden: the clip's one cycle, not two, nosteps; a walker on threes whose big tail closes on no cut of two steps: the search's cut, which passes, where the two-step cut failed the seam gate; a side walker whose two steps are one silhouette, near and far a tone or four apart, cut one step by the search: two steps, its feet passing briefly, where asking the picture alone kept the half step; the half-step walker reads over the same-picture bound; onby_stepsitself, a search's cut two steps out of phase whose own seam passes stands where every two-step cut's seam fails the gate and gives way where one passes or where its own seam fails too, a cut refuted one step gives way to a two-step cut whose seam fails, a one-step cut that is the same picture a cut on is kept where the feet stand together through a pass, and given up for two steps where they pass briefly).New:
video-loop --anchor motion-autocloses a two-step cut's wrap that a part on its own beat leaves open, with the clip's frames a cycle apart. A walk cut two steps long by the clip's crossings closes for the legs; a tail swinging round on a beat of its own closes on no cut of two steps, so the seam gate refused every one — and the eased retime does not reach it, since the part turns back at the wrap, where its frames read off the flow against the way. The clip goes on past the cut, and its frame a cycle after one of the cut's shows the legs at the same point of the walk. Under--repair auto(andon), where such a cut's wrap reads over--seam-maxon its frames as corrected (loop.wrap_on_cells), the frames beside the wrap are made again before the jump repair (repair.overlap_wrap): each by RIFE between its two frames of one time — the clip's frame a cycle apart, moved by the analysis translation between the two and corrected as the cut frame was (loop.cycle_apart), and the cut's own — so the wrap plays a step the clip filmed and the part goes over to the cut's way over those frames, each frame at its own time. The weights (repair.overlap_weights) are the ease in and out x²(3 − 2x), held off it only in the steps where the rest of the body or a body measure, read on the line between the two frames, would go past its bound; a weight of 0 or 1 shows a frame whole, with no call, and a frame at one weight is made once, whatever the run. Four frames, then six, eight, ten and twelve (OVERLAP_WIDTHS), on the side — after the wrap or before it — whose frames a cycle apart differ least, never past half the loop; a run is taken only where no made frame has an interpolation fault — a part torn among them, below — the gate passes it, the loop played round still covers two steps (loop.ring_steps), no body measure — the foot line, the torso, the ground — moves a pixel past the largest step of the stretch as the loop plays it (the eased retime's bound on the same torso, never the clip's frames a cycle apart: the part going over pulls the body's mass, which is reported, while a torso the clip's frame a cycle on shows elsewhere would slide) — the part steps no further than over the stretch, no new rush is read, no window of the rest of the body steps further than its own largest step over the stretch, and no frame is left further off the flow over its limit (rejected_for). The jump repair after it makes nothing from, beside or again over those frames (jump_repair.overlapped). A frame made between two frames a cycle apart bridges the part's whole move at once, and where the part swings over a smaller one — a tail across a hand — RIFE drags the small part apart with it, which on art painted without a line no other reading sees: each frame is also read with RIFE's sixteen single passes (rife.Rife.read: the binary's eight flips and transposes, both ways in time, run one at a time with no augmentation and turned back,rife.passes) and refused astornwhere the forward passes' mean and the backward passes' mean put the colour and coverage more than 0.05 apart over more than 0.21 of a window a tenth of the body high (rife.torn,interpolation_quality.TORN_WARN); the frame delivered is still the binary's own. The frames are made the weight nearest a half first, and the first frame with a fault ends its run, the rest of it not made (unmade), so a clip whose part crosses another on every run is refused the overlapped wrap and kept as filmed for the gate to refuse. The report carrieswrap_overlap(each try with the weights chosen, the frames made in play order and in the order made, and the run taken; the binary's calls), the summary names it, a warning line names the frame that ended each refused run, and without RIFE the wrap is cut as filmed with a warning line (--repair onrefuses). Each frame made costs the binary 34 calls (its frame, and its sixteen passes in colour and coverage); at most forty frames, where every width is made whole and refused. On the test walker (front, 26 frames a cycle, the tail on a 41-frame beat) the cut 29/26 reads 6.23 at the gate as filmed and 3.17 after the jump repair alone; four frames after the wrap rush the tail and are refused, six are taken, and the loop passes at 1.04, two steps, in ten calls. On a second walker whose big tuft bobs on the loop and a cycle on is carried 8 px aside a frame, the walker in its place, four frames are taken at the ease (3.41 → 1.53 at the gate, four calls): the torso moves 0.05 px, the body's mass 3.95 px against the stretch's 0.71, reported; where the whole walker also stands 3 px aside a cycle on, its torso sliding, every run is held at 0.85 of the cut's own frame next to the wrap, the wrap stays open and the cut is kept as filmed for the gate to refuse. On a third walker, painted without a line and seen from behind, whose big tail swings from 48 to −8 degrees across its hand between two frames a cycle apart, the real RIFE's frames at weights 0.5 and 0.7 read torn 0.44 and 0.26 with no other fault; swung 10 degrees past no hand, its frames read 0.04 at most (loop-repair).Tests —
tests/video/test_loop_overlap.py(a front walker whose tail swings round on its own beat, refused at the seam on every cut of two steps, is closed at the wrap: each frame beside it made between the clip's frame a cycle apart and the cut's own at its eased weight, once a frame and weight, four frames refused for a rush and six taken, two steps on the loop played round, the body within its drift, the rest of it no faster, every other frame the clip's own and nothing made by the jump repair; on a walker whose big tuft a cycle on is carried aside, every run's drift bound is the stretch's own as the loop plays it — the torso's, which stands still there, never the clip's frames a cycle apart — and the body's mass is reported beside it; with the tuft alone carried over the run is taken near the ease, the torso within its pixel while the mass moves 2 px and more past its own; with the whole walker also standing aside a cycle on, its torso sliding, no run moves it more than a pixel in a step on the frames shown, drawn again, the frame next to the wrap is held off the ease and the cut is kept as filmed;--repair offrefused as before; without RIFE cut as filmed with a warning, and with--repair onrefused asking for it; a made frame with a fault ends its run there — the frame nearest a half made first, the rest not made — every width refused and the cut kept as filmed; a stand-in whose passes disagree over a patch of the body ends every run at its first frame as torn, the warning naming it; the real RIFE (markedreal_rife) drags the painted walker's hand apart between its frames a cycle apart and the frames are refused as torn, no other reading refusing them, while a swing past no hand reads nothing; a weighting search on lines drawn by hand: the ease where nothing binds, held off it in the one step a window of the rest of the body is bounded in, none where a body measure may not move);tests/video/test_rife.py(Rife.readmakes the frame as every call does and then sixteen single passes with no augmentation, the pair flipped and transposed and run both ways in time: with a binary that hands back its first frame, turned back, they disagree by exactly how far the pair differs and only there;rife.tornreads a patch a window wide where the passes disagree and not lines a pixel or two wide, scattered pixels, a faint patch or a frame with no body).Behavior change:
video-loop --anchor motion-autocuts a walk two steps long — the left foot forward once and the right once — wherever the clip shows its feet pass. Left foot forward and right foot forward are nearly the same silhouette from the side or a diagonal, so the pixel search could take one step for a cycle (a half step loop: one foot goes forward), three steps where a tail on its own beat repeated there (the wrap puts the nearer foot back: a stomp in place), or refuse a slow walk whose cycle its window could not hold. The feet are now read (crossings.read): where they are seen apart, each run of frames with them together is a crossing; where they never are (front, back), the foot band's lean about the body's axis changing side is, and the lean must turn over a step on. Every crossing counted is one the clip shows whole: a run cut by the clip's first or last frame counts only where its twin confirms it, every step a cut plays — on both sides of its wrap — lies within √2 of the clip's own step, and a cut is two steps only when the walk's phase advances by two over it, its wrap joins two points of a step within [1/√2 − 1, √2 − 1] of each other under every bound of what the clip does not show, and the loop as played shows two crossings too (two;refutedone or three steps; anything elseuncertain, never two). The search's cut is kept, every image as before, where it is a two within 1.5 frames of phase; otherwise the cut is the two-step cut in phase whose top band does not pop at the wrap, whose wrap is within the seam gate of its step and whose seam is the smoothest by the flow reading (both seam frames underrepair.FLOW_LIMIT, within 0.5 of the smoothest, the wrap nearest the clip's own way on), read on the frames moved as the cut will be corrected, of any length the count allows inside an explicit--min-len/--max-len(method: observed-two-steps-v1); of the first four, the first whose seam the gate will pass, read as the gate reads it (loop.seam_on_cells), is taken. A window that holds no two steps of a walk whose steps are seen is refused, naming both (no cut of two steps in --max-len 25: …), never cut one step long. A clip whose feet are not read is cut exactly as before. The report recordscycle.step_count(the crossings, the step range, the verdict of the cut taken and of the search's cut,chosen_by); a cut on two steps recordscycle.steps{count: 2, by: crossings}andstrip.jsonsteps: 2, sovideo-cycle-alignreads its half-way return as its step, and the step screen's pixel suspicion is settled (pixel_suspect). Where the clip shows its steps but no cut of two, the search runs again refusing the cuts the crossings refute, and a refusal lists each window's count, those refuted last.--stepsis still the word on the search's cut.repair.clip_flow_statesandrepair.ring_scoresread the flow of every cut of a clip on one path;flow_scoresand the repair read as before (loop-repair section 3, "The step count").Tests —
tests/video/test_crossings.py(a walk that stalls proves no two steps across the stall, on either side of the wrap; a hold before or after the cut, a stall with the feet apart, a stand with them together, a stomp in place, the stance a clip opens on, a pass the first frame cuts with or without a twin that confirms it, a change the clip ends on: none two; half a cycle and three steps refuted, a wrap half a step off and a wrap that slips feet together in uncertain; noise at the threshold and a wobble at the axis no steps; a hold the step range absorbs stays two and a longer one does not; two crossings set no range; a lean that does not turn over is not read; every two lies in the lengths two steps cover; the lean and gap off drawn frames),tests/video/test_walk_steps.py(on synthetic walkers the pixel search alone cuts one step, one step past its window, three steps by the gait fallback, nothing at all, and across a stalled step: each is cut two steps long, in phase, the strip sayingsteps: 2; a walk the search already cuts two steps in phase is cut byte for byte as before; a legless body is cut as the search cuts it; a count given is the word; the set aligns a loop cut on two steps as one cycle;detectrefuses what the crossings refute and orders a refusal by the count), the step screen's tests intests/video/test_one_step_cut.pyand the pixel search's intests/video/test_auto_motion.py,tests/video/test_loop_prop_seam.pyandtests/video/test_loop_prop_seam_held.py(a walker whose legs open and close once a drawing and never pass each other, which the count reads as one step a drawing) read their walker's feet as unseen (tests/conftest.py,feet_unseen), andtests/video/test_explicit_window.pyrefuses a--max-len 25that holds one step of the 42-frame walker.New:
video-loop --repair auto(andon) eases a part that rushes on its way — the frames either side of the rush are made again at times that spread it, the body's own steps kept. A part can keep its way and still jump: a tail that runs short of the cycle rushes on at the wrap, covering in one step what it covers in eight elsewhere, and each frame there lies near enough the line between its neighbours that the flow reading lets it pass, or takes the frame at the wrap out and leaves the rush over two steps.repair.surgesreads the speed on the flow reading's own path and windows: a run of one or two steps whose mean step is at least 3.0 usual steps and 3.0 times the mean of the three steps either side, the part going on the way it came through it (a step that turns back is a frame flung, the flow repair's). After the flow groups, the worst rush is eased over three or four drawings either side, made from the frames as filmed (a frame the flow made inside is made again,supersedes) and kept between two frames as filmed, never leaving more than half the loop made with the rounds before it (as much asvideo-loop-comparereads back as the repair's):repair.ease_timesgives every frame a time, on a grid of a twentieth of a step, where the part's step changes from one step to the next as little as it can — from the speed it came in with to the speed it goes on with — while the foot line's centre (loop.foot_centre), the torso and the lowest solid row move in a step no further than the stretch's largest step as it played and half a pixel, and every other window of the flow reading no further than its own largest step there; the torso is the head and torso the motion anchor tracks (repair.Torso:auto_motion.discoveron the loop as cut, each frame matched by the anchor's masked NCC within its own fine search, 14 px across and 28 down, x to a fraction of a pixel), so a part swaying on its own beat — a tail, the hair's ends — which pulls the body's mass along and is what the repair moves, is not drift; where the anchor finds no head and torso, or one reaches the edge of that search on a frame of the loop, the body's mass (loop.body_centre) stands in, and the mass is reported beside the drift either way (drift.body_mass,torso); within 2 % of that, the timing nearest the frames' own. How far the part has gone is the path of its coverage's centre in the windows that read the rush, which grows as far as the part moves where a blurred distance stops growing. RIFE makes each drawing between the frames as filmed either side of its time, one call a drawing, at most nine, outside the three of the flow groups; the stretch is taken only where no frame made has an interpolation fault, no body measure moves a pixel past the stretch's largest step, the part's largest step falls, no frame is left further off the flow and over its limit, no new rush appears in the rest of the body, and no window of the rest of the body steps further on the frames made than its own largest step over the stretch as it played (rejected_for,the rest faster: the search reads the rest of the body on the line between the frames as filmed, and the frames made, which go the body's own way between them, step further where a part moves far between frames). On the synthetic walker drawn over 24 frames a cycle, the tail a quarter short goes, after the flow repair, from 5.3 usual steps into the wrap to 3.4 with no rush left; over 16 frames, 15 % short and under the flow reading's limit, from 3.6 to 1.7; over 36 frames every stretch is refused, the rest of the body 1.5 % to 19 % past its own largest step on the frames made; ordinary walks and a flung frame read no rush. A loop with no rush costs one more reading and no call.jump_repaircarriessurge,surge_after,ease_skipped,ease_callsand the roundwhy: ease(itsrest: per window the rush is not read in,step_max_before,step_max_afterandfaster),replacedits frames, and the summaryeased; without RIFE the rush is cut as filmed with a warning line, and--repair onrefuses (loop-repair section 2, "The eased retime").Tests —
tests/video/test_loop_ease.py(a tail that rushes on at the wrap after the flow repair is eased over three or four drawings either side, in play order, made only from frames as filmed — the flow's frame at the wrap made again — every frame outside as it was, the part's largest step down by a quarter or more and the body's feet, torso and ground within the stretch's own steps and a pixel (the torso read as the round read it, the body's mass beside it), and every window of the rest of the body within its own largest step, read again on the loop as it plays; a rush under the flow reading's limit eased, none left; over 36 frames, the stretch whose frames made step further in the arm, the head and the legs than they did there refused for that alone, the loop as the flow left it; ordinary walks, drawn every frame and on twos, have no rush and nothing is made; a frame flung against the way is not a rush; on twos each drawing made once and shown on both its frames; a made frame pushed sideways refuses the stretch for drift, and one with its outline melted for a fault, the loop left as the flow left it; without an interpolator the rush named and nothing made; the same frames whichever way the body faces; a fourteen-frame loop eased three a side where four would leave more than half of it made; the search keeps every frame at its own time where the part moves evenly, and spreads a rush as far as the body's bound lets it;video-loopplaying the frames made in a loop as long, a rush without RIFE cut as filmed with a warning line,--repair onwithout RIFE refused), andtests/video/test_loop_flow.py's walker draws its dark parts whole on asking (dark_whole), so that a frame drawn between two phases has no more dark pixels than they have.Behavior change: a frame the jump repair or the cycle alignment makes between outlined drawings loses its outline only where it is lighter than its neighbours' edge rank by rank, too. The fault
outlineread the made frame's edge against one dark line (a solid pixel under 70/255 within 2 px,outline_lossover 5 %), so art outlined in a mid tone — a brown or a painted line whose tone lies about 70/255 — had its line on the near side of the line in the drawings and on the far side wherever the flow softened it by a few tones: every frame made between two such drawings read as melted, and the repair and--between autorefused it.rife.outline_shift(made, a, b)reads the same edge, each pixel by how dark the darkest solid pixel within 2 px of it is, in order, against the lighter neighbour's edge at the same rank, and counts it where it is lighter by more than 50/255 (rife.OUTLINE_SHIFT). The faultoutlinenow needs both over 5 %: a softened line is lighter by less at every rank and is kept, whatever tone the art outlines in; a line gone to the fill beside it is lighter by its whole contrast and is lost. Art outlined near-black reads the same on both, and art outlined lighter than 70/255 is still not judged by the outline. On the two-tone walker of the tests, the drawing between with its line 20 to 45 tones lighter readsoutline_loss57 % andoutline_shift0 (refused before, kept now); with its legs' line turned to fill, 24 % and 48 % (refused). A line less than 50/255 darker than the fill it melts into is not read as lost. The rank reading is read only between outlined drawings:rife.outlined(frame)is the share of a frame's edge whose line, the darkest solid pixel within 2 px, is darker than its fill, its colour from twice the bleed's depth inside (rife.LINE_DEPTH), by more than 50/255, and both neighbours must read at least 75 % (rife.OUTLINED); elsewhereoutline_shiftisnulland the dark line judges alone, as before. Art painted without a line has no line to lose, and a part the flow melts there — a boot washed pale — can come out lighter by less than 50/255 at every rank: read rank by rank it would be kept and delivered, where refused it is replaced by the nearer filmed frame. On the walker of the tests painted without a line (outlined on 4 % of its edge), the drawing between with its near boot washed 40 tones lighter readsoutline_loss7.8 % and, rank by rank, 0: refused. The 75 % is set on frames made between drawn walks and judged by eye so that no frame seen as broken that the dark line alone refused is kept. The jump repair's proposals and the alignment'ssmearrows carryoutline_shift, and the alignment's warning line names it where it was read;video-loop-compareandvideo-loop-repairkeep their versioned measures,rife.smearalone, and judge the outline on the dark line as before (loop-repair section 4).Tests —
tests/video/test_outline_shift.py(a mid-tone line drawn lighter is kept and one gone to fill is lost; the versioned measures judge on the dark line alone, and so does a measure whose rank reading was not read; art outlined near-black reads the same on both; a frame with no edge reads 0 and neighbours with none are not read; the jump repair takes a lighter line and refuses one gone to fill; the alignment keeps the one and takes the nearer frame for the other; on the walker painted without a line, a boot washed 40 tones lighter is refused by the jump repair and replaced by the alignment, and the two-tone and black walkers read outlined on all their edge; through RIFE, a short step of two-tone legs keeps its outline and legs crossing far lose it on both).Behavior change: every RIFE call runs the binary's test-time augmentation,
-x -z(rife.TTA).-xruns the pair as its eight flips and transposes and-zboth ways in time, and the results are averaged, so a frame made from a to b is the one made from b to a. Neither rife-ncnn-vulkan nor Practical-RIFE has released a model since 2024; the model staysrife-v4.6. On the synthetic pairs oftests/video/test_rife.py,-x -zis the one setting of the four (none,-x,-z, both) that makes legs crossing far the same both ways with no ghost, and it keeps the most of a short step's outline. On the Mac's GPU it adds a tenth to half a second a frame; on Modal's CPU it costs 15 to 19 times a plain call's CPU — 12 to 30 s a 280 × 520 frame on two cores, 44 to 61 s a 960 × 960 frame.SPRITE_GEN_RIFE_TTAnames another (-x,-z, both, or empty for none; anything else is refused before a frame is asked for), for a CPU-only machine that aligns sets. The interpolator a report names (jump_repair.interpolator, the alignment'sinterpolator) carriestta. A call past 600 s (120 s before) is stopped and reported as a RIFE that failed, where it used to end in Python's own timeout (loop-repair section 1, "Which setting").Tests —
tests/video/test_rife.py(every call asks for-x -zand never-g;SPRITE_GEN_RIFE_TTAnames either mode, both or none, and anything else is refused; a call past its time is a RIFE that failed; the real-RIFE pairs read with the augmentation: legs crossing far melt the same both ways and leave no ghost, a short step stays outlined, legs walking through each other add no dark where they cross; a refused repair names its faults whole, not by the first of a sorted list),tests/conftest.py(every test runs the engine's own augmentation, whatever the calling shell sets).New: the flow reading of a walk loop (
repair.flow_scores,repair.flow_targets) — the frames that leave the way a part is going, by direction and speed, not by the size of a step. Each frame is a point of the loop's path, its coverage and shading blurred by 3 % of the body height, read in nine windows of the union box: how far it lies off the straight line between its neighbours (the second difference, the acceleration), in that window's usual steps. A clip filmed on twos or threes is read on its drawings, the holdheld.measure's.flow_targetstakes the worst frame at or over 3.0 first and names the fewest frames around it — one, then two — whose straight in-between brings every frame it touches under 3.0, never made from a frame taken before; what two cannot bring under isunfixed. On the synthetic walks an ordinary loop reads at most 1.65 where the jump score names 8 to 18 steps, and a tail flung 5 % of the body height against its sway reads 2.8 to 4.1. The methods weighed beside it — interpolation error with RIFE, optical flow, a periodic fit, a Kalman predictor, Savitzky–Golay, a Hampel test — and their sources are in docs/loop-repair.md section 2, "The flow reading".Behavior change:
video-loop --repair auto(andon) takes out the frames off a walk's flow and makes them again between the frames either side, each at its own time. The frames are the flow reading's (repair.flow_targets), not the jump score's: a step 1.4 times the loop's median no longer remakes the frame after it, so the quick swing of an ordinary walk is left as filmed, and a frame flung against the way a part is going, which the jump score read no larger than a swing, is taken out. A group is one or two drawings in a row; RIFE makes each drawing between the first frame of the drawing before the group and of the drawing after, at the drawing's own time (repair.between_time: a half for one frame, a third and two thirds for two, a half for a drawing on twos), and shows it on every frame the drawing was — the loop keeps its length, every frame its time, a loop on twos its hold. One call a drawing, at most three a loop; one made frame with an interpolation fault refuses its whole group, which keeps its frames as filmed, and nothing is made from or beside a frame made, given way or refused. Of the groups that bring the reading under the limit,flow_targetsnow takes the one whose every drawing the in-between moves furthest (move): two frames flung together are taken out whole, where the frame beside the pair was taken before and the pair left standing. A loop whose only large steps are the steps into and out of a few jumps no longer reads as held (HELD_RUNS: three in four runs must be the hold, a frame more or less): read on those false drawings its jumps read as ordinary, and a drawing made would have stood for five frames.jump_repairreadsreading: flow,limit,span,hold,drawings,refused,unfixed,left,off_max_before/off_max_after(in place ofscore_max_before/score_max_after, also in the summary and invideo-set's item record), and per roundwhy: flowwith its group andmade(per drawing:frames,t,original,proposal,faults,look);unmadenames the group'sframes,neighboursandoff.repair.JUMP_RATIOis gone;repair.jump_scoresstays, the size readingvideo-loop-compare's jump guard reads with the recordedfacing(loop-repair).Tests —
tests/video/test_loop_flow.py(an ordinary walk the jump score would remake is left alone and RIFE is not called; a flung frame made again half way between its neighbours, every other frame the video's own; two flung frames made again at a third and two thirds; on twos a flung drawing made once from the frames two before and two after it and shown on both its frames; a group with one made frame at fault keeps both frames and is not tried again; the calls go to the worst frame first and stop at three, the group left named; no interpolator names the group; mirrored, the same) andtests/video/test_loop_repair.py(on its block walker: one flung frame, two side by side, the pair flung at the wrap taken out whole and made from the frames beside it rather than smoothed at its edges, jumps a few frames apart read a drawing a frame and not on threes, three outline-melted groups refused within the budget, groups made only from frames as filmed;video-loopplaying two frames made again at their own times in a loop as long, and the flow numbers when no RIFE is installed); the ghost and cross-fade proposals oftests/video/test_ghost_screen.py,tests/video/test_crossfade.pyand the real-RIFE case oftests/video/test_rife.pyread through a group the flow reading is made to name.Tests —
tests/video/test_loop_flow.py(an ordinary walk whose quick swing the jump score names has no frame taken; a frame flung against the sway is the one frame taken, read behind the body and turning back; a tail that snaps back at a wrap that does not close takes a frame at the wrap; the same whichever way the body faces; a walk on twos read on its drawings, a drawing flung the two frames that show it; two frames flung in a row one group of two; three flung frames three groups, none made from a frame taken before; a span too short namedunfixed; a loop of three drawings left alone; a loop with no body refused).New:
video-cycle-align --between-cache DIRcaches frames made between source frames so later alignments take kept frames instead of making them again. Previously, running alignment a second time to specify--footor after a retake remade every interpolated frame, even though source frames and fractions did not change. Now, every frame RIFE makes between two source frames is saved inDIRas a PNG keyed by the sha256 of its inputs and interpolator identity, and any later run with identical inputs reuses the kept frame. The interpolator identity is read for every frame, so a binary, model, augmentation (SPRITE_GEN_RIFE_TTA) or host that changed makes the frame again. A frame made while its inputs changed is handed on but not kept (not_kept). The user passes--between-cache DIR(orbetween_cache=pathin Python) and removesDIRwhen the alignment is done. The summary and report recorddir,hits,misses,unreadable, andnot_keptunderbetween_cache, which isnullwithout the flag (loop repair).Tests:
tests/video/test_between_cache.py(two passes under--between rifeand--between auto: the second takes every kept frame, with matching files and report; one changed source pixel remakes only the frames made from it while the others are taken; another length gives the same loops as a pass without the directory; swapped frames, another fraction (even one a float apart) or one moved pixel miss; frames that are not RGBA are refused; under onerife.Rifeobject, with a stand-in RIFE that runs and picks its output by its model's and its own bytes: its model's bytes written over, its binary written over, a file added to its model, and its model files under another directory name each make the frame again, and every frame taken equals the frame the same object makes without the directory; a frame kept without augmentation is made again under the default-x -zand under-zalone, and taken again without; a RIFE whose model directory is gone fails as a RIFE that fails; under onerife.Rife: another host name or OS build, NumPy or Pillow version, or engine code loaded anew make the frame again, whilerife.pywritten over on disk after the import (no code that runs) takes the frame the loaded code made; a frame made while its model was written over between RIFE's two runs is handed on as made and not kept (not_kept), and the next pass makes it again; corrupt, truncated or overwritten kept files are made again and written over; the directory and its files are readable and writable by the user only (no group or other permission bits); alignments without the flag store nothing; injected interpolators without anidentity()method are refused; the summary and report record the cache counts; areal_riferun matches the sha256 of fresh frames). Synthetic fixtures only.Behavior change: a call that names no provider stops and asks when codex cannot run, unless you chose what to do.
gen,logo,gen-setandvideo-set's mid-step redraw run on codex when no--provideris named. When codex was not signed in, they used to switch togrokwithout asking (said on stderr, kept in the report) — and with no Grok login that meantXAI_API_KEY, billed per call. Now codex that cannot run — not signed in (codex login status), or its usage used up (codex execends on one of the errors codex classes as its usage limit) — follows a choice:ask(the default) generates nothing and ends with one stderr line,sprite-gen ask codex-unavailable: {…}(the cause, the reason, the question and the flag that runs each answer), and exit 75;grokoropenairuns that provider, said on stderr and kept in the report asprovider_fallback(now withcauseandchosen_by),openaiwith its per-call charge line as always. The choice isSPRITE_GEN_CODEX_UNAVAILABLE, elsesprite-gen defaults save --codex-unavailable ask|grok|openai, elseask; the guidedworkflowasks it once and saves it. A usage limit is known only aftercodex execran, so the call runs again on the chosen provider. A named--providerruns as named: a named codex whose usage is used up still fails with codex's own words, exit 1.gen-setandvideo-setwhose child asked stop with the same question and exit 75 (naming--provider, or--still-provider), their reports and tables keep it underasked, andgen-set --providernow takesopenai.openairuns only when you chose it: named, or as this answer — still never a default, never the guided image provider (gen, SKILL).The usage-limit signal is codex's own words, read from its source (codex-rs at
rust-v0.160.1andrust-v0.153.4):codex exec --jsoncarries only the message of codex's usage-limit errors (UsageLimitReached,QuotaExceeded,UsageNotIncluded, which codex classes asUsageLimitExceeded), socodex_provider.usage_limitmatches the start of each message as codex's tests pin it — "You've hit your usage limit" with either apostrophe (0.153.4 writes it ASCII, 0.160.1 as U+2019), "Your workspace is out of credits.", "You hit your spend cap set", "Quota exceeded. Check your plan and billing details." and "To use Codex with your ChatGPT plan, upgrade to Plus". Any other codex failure is a failure, not the question.Preferences file version 2.
preferences.jsonkeeps, beside thespriteandimageprofiles, thegeneralsettings every profile shares (codex_unavailable). A version 1 file still reads, with nothing chosen; the next save writes version 2, which an earlier sprite-gen refuses as unknown.defaults save --codex-unavailableneeds no--kind.Tests —
tests/gen/test_codex_unavailable.py(no codex on PATH and nothing chosen: a realgenexits 75 with one question line and no image or report; each of codex's usage-limit sentences, synthesized ascodex exec --jsonprints them, asks the same; a codex failure that is not its usage limit fails and is not switched; savedgrokruns grok and the report and stderr say whose choice; savedopenairuns the API on a fake transport with one charge line; a usage limit with savedgrokruns grok after codex; the environment before the saved choice, an unknown value refused; settings read only when codex cannot run;logoresolves the same way; a named provider runs as named whatever was chosen; a realgen-setwhose rows asked exits 75 with one question naming--provider, its report and table keeping it; avideo-setwhose mid-step redraw asked stops naming--still-provider; the guide asks once and not after the answer is saved, nor over the environment; the choice kept beside the profiles, a version 1 file read; thedefaultsCLI; SKILL.md names the exit code, the line and the three answers). Every test now runs on its own settings directory with no provider environment (tests/conftest.py).Behavior change: a refused provider request is sent again only within the time limit of its call, and the waits count in that limit. Previously a request its provider documents as not taken (a 429, an overload) was sent again after 8 s and 16 s, or after the answer's
retry-after(at most 120 s), twice, whatever time the call had left, and the time limits did not count those waits:SPRITE_GEN_GEN_TIMEOUT_SECONDSbounded each send of an OpenAI or Grok image and of the OpenAI facing check on its own, the Grok facing check's 120 s each read, the clip's poll timeout counted from the send xAI accepted, and a Message Batch's status and results reads waited outside--batch-wait. A caller that stops the run at its own ceiling, set above those limits, could kill a request taken after two refusals and hear nothing from the engine. Now each limit counts from the first send and holds the waits: the image calls and the OpenAI facing check countSPRITE_GEN_GEN_TIMEOUT_SECONDS, the Grok facing check its 120 s, each of their sends reading only what is left of it; the clip its poll timeout (SPRITE_GEN_VIDEO_TIMEOUT_SECONDS; the POST itself is still not cut, its answer being the one way to the request id); a batch's reads--batch-wait. A wait that would reach the limit is not waited: the refusal ends the call as any refusal does, after one stderr line,[gen] openai refused the request (429 rate_limit_exceeded); nothing was made — not asking again: the 16s wait would reach the time limit (12s left). The limit is read again after the wait, right before the send, as a sleep may wake later than it was asked to: one that woke at the limit or past it sends nothing either, and the refusal ends the call the same way (… — not asking again: the time limit came during the 8s wait). A clip's polls and downloads read their poll timeout the same way: a poll or download whose wait woke at it or past it is not sent, and the run ends unfinished on the last one as it came, where the one the transport found no time left to send was counted as a poll or download that got no answer (timed out). A realtimepixel-drawcall has no time limit of its own and is unchanged.Tests —
tests/gen/test_retry.py(a request sent again only while its wait ends before the time limit; the answer'sretry-aftercounted the same; a wait that ends at the limit not waited; a wait that woke at the limit or past it sends nothing, the limit read by one judgment,too_late, before the wait and right before the send; every direct provider call handsretryits limit; the Grok facing check and a Message Batch read whose wait woke past their limit send nothing),tests/gen/test_openai_provider.pyandtests/gen/test_grok_provider.py(with 20 s, the second send waits only the 12 s left and the second 429 ends the callsent 2 times; with 8.01 s, an 8 s wait that woke 20 ms late sends nothing and the 429 ends the image call, or the OpenAI facing check, as it came),tests/gen/test_video.py(the poll timeout counts from the first send; a 429 whose next wait would reach it ends the run with its status, and so does one whose 8 s wait woke 20 ms past an 8.01 s timeout, with no second POST; a poll or a download whose wait woke past the timeout is not sent, and the run ends on the last one as it came),tests/gen/test_pixel_draw.py(each batch read is handed the end of--batch-wait).tests/http_answer.pyis one offline HTTP answer the provider tests share, read whole or a chunk at a time under a deadline.Behavior change: requests can pack sound without images. Previously, a version 1 request required a nonempty
assetslist (refused with "assets must be a nonempty list"), and version 2 required at least one asset, image, tile, UI kit or icon (refused with "game pack request declares nothing to pack"), preventing games drawn in code from packing audio alone. In both versions,assetsmay now be empty or absent when sound is declared (see docs/game-pack.md#sound-only-packs). A sound-only request writes exactlygame-pack.json,audio-<id>.ogg,audio-<id>.m4aandsprite-gen-audio-v2.mjswithout atlas pages; its manifest setstexturesto[]andanimationsto{}(version 2 also keeps emptyimages,tilesandui), while audio entries, sound files and helper module bytes remain identical to packs with images. Requests declaring no assets, scene entries or sounds are refused in both versions with "game pack request declares nothing to pack: give it an asset, a scene entry or a sound" and write nothing. Packs with images (with or without sound) and packs without sound remain byte-for-byte unchanged, and repacking a sound-only request returns the same output. Tests:tests/compose/test_game_pack_audio.py(sound-only requests in versions 1 and 2 withassetsempty or absent write only the manifest, sound files and helper; manifest matches image packs except for emptytexturesandanimations; sound files and helper match bytes; repacking returns identical results; requests with neither images nor sound are refused without creating an output directory for version 1 and version 2). Synthetic fixtures only.New verb:
video-stopcuts a walk or run that stops from the clip's own start played backwards. Given the clip's keyed frames and a walk or run loop (--frames-dir,--loop), it writes a one-shot strip (<name>.strip.png), sidecar (loop: false,hold_last: true), GIF, WebP, and report (<name>.stop.report.json). The stop leaves the loop from the cell nearest the entry (from_cell), the first frame after the opening rest withinSAME_POSE(0.35 steps) of a loop cell, and ends on the clip's first frame, the still as filmed. A seam past the jump line (1.4 steps,--seam-max) is refused byvideo-stopwith exit code 1 andstatus: "failed"in the report, and so is another motion in the run-up between the rest and the entry, however short: a run-up frame back withinSAME_POSE(0.35 steps) of a pose the clip had left byTURN_BACK_AWAY(one step) or more (the still, or the run-up's own), refused with "the run-up turns back — another motion, that the stop would play backwards", naming the three frames (turn_back, the nearest such comeback, is reported either way). A run-up longer thanRUN_UP_MAX_CYCLES(1.5 cycles) —source_cut.lengthframes, overridden by--run-up-max— which plays strides unlike the loop's, is refused with "strides unlike the loop's, that the stop would play backwards";--run-up-maxbounds only that length and never lets another motion through. The seam refusal, the another-motion refusal and the run-up refusal can all be named in one message. Drift is taken out by laying the entry on its cell and the first frame on the loop's ground and mean coverage, moving frames between by a straight share of the difference per step; a run leaning away moves the still a few pixels, and drift not straight leaves a little of itself. Strips wider than 32,000 px are refused,--speed 2plays every other frame (still kept last),--max-frames Nspaces frames evenly, and frames shown pass the ghost screen (interpolation_quality) as filmed. The pose thumbnails (gait_fallback.poses, 48 px cut about the feet) are now public, as the verb reads poses with them (video-pipeline).Fix: the poses of one image row keep one size and stay on their anchor. Each pose of a row was shrunk into its cell on its own, so a raised or extended weapon shrank that pose's body (PR #107 gave the row one shrink ratio). That ratio fitted the widest pose by its own width, and
fit_to_cellthen placed it with itsalign_xanchor (the legs, by default) on the cell's centre line: a weapon held far out crossed the cell and the pose was pushed back in, body and all, so the body jumped back in that frame alone (a greatsword thrust: 39 px in a 256 cell). The ratio is now one function,fit_scale, which keeps every pose inside the safe area where its anchor puts it;fit_to_celltakes it for a frame alone, the row takes it over every pose, andqa/inspectfits a row the same way instead of pose by pose. Withbbox-centernothing changes. A weapon held far to one side now costs size in a square cell: give such a row a wider cell (pixel-unfake). Test:tests/frames/test_row_scale.py.New: a motion plays as its request says —
--play loop|once-return|once-hold|lifetime— andvideo-set --motiongives each state or item its own motion text. A state's name used to fix its sentence, its end-frame pin, its cut and whether its strip loops, so every new motion (a punch, typing at a desk, a block, a tool swing) was a change to the engine.video-set --play STATE=MODEorITEM=MODEandvideo-prompt --play MODEtake the mode as a value of the request, andvideo-set --motion STATE=TEXTorITEM=TEXTthe caller's words in place of the state's sentence (an item's own value wins over its state's; a key that names neither, a key given twice or a mode the state cannot play is refused before any clip). A word the engine does not name is filmed under that name in that mode: a once-return is pinned to end on its first frame, asked for as one action that returns to the first pose, and cut whole by the newvideo-loop --cycle once-return(every frame, the last too, gated by the pin), itsstrip.jsonsayingloop: false,hold_last: false,returns: truewith the first pose in its first and last cells; a once-hold is cut at its held pose (once), the first settled pose whose drawing is not its first — a shield raised inside a body outline that keeps its size and floor is one, the first drawing come back, in place or slid sideways, is not — while the six terminal states keep their body-geometry screen (any other state cut--cycle onceis screened by its drawing too); a lifetime is framed and filmed as an effect whatever its name; a loop asked for is searched as a loop (periodic) and never failed over to a single play. Named states are presets: without--playevery state is filmed, prompted and cut as before, and an attack played once-return is the same prompt and the same pinned clip, cut whole and played once.effect, the six terminal states and the cyclic states refuse any other mode.set.report.jsonrecords each item'splay(andmotion);video-prompt --jsonrecordsplay. Not measured on a clip model: the sentences for a motion of your own (video-pipeline).Tests —
tests/video/test_play.py(every named state given no mode is pinned, prompted and cut as before, and the same when its preset is named, save that a loop asked for is never failed over; a mode a state cannot play is refused; a once-return asked for pinned with its return sentence and cut whole, or searched where the source cannot pin; the attack played once-return is the attack's prompt; a named state played another way takes the mode's sentence; a once-hold with its end frame; a once-hold of your own ending on a new drawing inside the same body box cut at its held pose, the same clip ascaststill refused by its body geometry, and one that comes back to its first drawing, in place or slid sideways, refused; a lifetime filmed as an effect whatever its name; a loop of your own;video-setmodes and texts per state and per item, refused before any clip when a key or mode is wrong; a once-return that does not come back refused; a once-return cut subsampled with both ends kept and played once; the CLIs) and the once-return item filmed end to end intests/video/test_clip_prompt.py, its strip's first and last cells the first pose. Synthetic fixtures only.Behavior change: the UI kit cut reads the drawing with one exact judgment instead of a centring heuristic. Previously, each part went to the box that holds its centroid, with every box widened by half the gap. When that left a box empty, the layout was fitted to the drawing (least squares of box centres to the centres of what the boxes held, then assign again, at most 8 rounds) and kept when it left fewer required boxes empty, or as many and fewer boxes in all, reported as
layout_fit. The only refusal of the cut was an empty frame. With several band elements missing on a drifted sheet, a drawn element could be cut under a neighbour's name, a drawn part named missing, or an undrawn element present; a drawing that fit the layout in two ways was cut silently under one of them; and a fit dragged by a small element placed off its box's centre gave wrong readings. The cut is the one reading within 1 px of the least cost, found by one exact search over the drifts the cut considers (a scale from 0.875 to 1.125 and an offset of at most 120 px at 1024), and every refusal comes from that one result (ui-kit). Every drawn element is cut under its own name, or the sheet is refused. A drawing that fits the layout in two ways is refused, naming both readings. New refusals: drifted further, ambiguous, off-centre, and off the layout. A sheet drawn on its guide is cut exactly as before, report bytes included. A sheet whose every part lies at least 1 px inside its box under some drift within the accepted range (along each axis a scale from 0.9 to 1.1 and an offset of at most 96 px at 1024), with all seven frames drawn, is cut exactly as drawn or refused as fitting the layout in two ways, never refused for another reason. A sheet with stray marks (parts in no box under the drift it was drawn with) is outside it.Tests — synthetic sheets cover the change: the two-way ambiguous sheet (512 × 768 px, seven 20 × 8 px frames, one dot on
pip_onand squeezedpip_off) with an 18 px and a 60 px dot, refused bysplit_ui_kitand the CLI; the control sheet cut aspip_off; 512 sheets of small drawings and 256 sheets of full-size frames with small band drawings cut as drawn or refused as ambiguous, with three sheets previously refused as drifted now cut as drawn; each of the 256 sets of missing band elements under random accepted drifts; squeezes from the top by 0.90 to 0.99; a 17-sheet counterexample search; sheets refused as drifted further (20 % shorter), off-centre (dot in the gap), and required (each frame left out); a 2:3 sheet drawn on its guide with a mark 4 px wide and 20 px tall centred in the gap between the boxes of the two dots (pip_onabove,pip_offbelow), refused as ambiguous (pip_on, pip_off); and 4 px scattered squares proved off the layout within 10 seconds. A square sheet and a 2:3 sheet drawn on their guide are cut byte for byte as before, with nolayout_fit.Fix: the test suite runs on Windows.
pyproject.tomlnamed pytest-timeout'ssignalmethod, and Windows has no SIGALRM, so pytest stopped with an internal error before its first test unless-o timeout_method=threadwas given. The method is now left to pytest-timeout, which takessignalwhere SIGALRM exists (Linux, macOS: unchanged) andthreadon Windows. Test:tests/packaging/test_project_metadata.py.tests/video/test_one_step_cut.pyskips where img2webp is missing, as the other loop tests do, instead of failing all twelve of its tests.Fix:
sprite-gen prepare --requestkeeps the request'sstyle. The subcommand declared its own copy of prepare's options, with--styledefaulting to the default style sentence and--cell-sizeto 256, so a flag nobody gave counted as given: the request'sstylewas replaced by the default sentence under a note that--style, --cell-sizewere given both ways (scripts/prepare_sprite_run.pyandprepare.runwere right). The subcommand now takes prepare's own declaration (prepare.add_arguments), which also gives it--directionsand--mirror, missing until now. A request with no style and no cell still gets the default sentence and 256. Test:tests/gen/test_flags_over_spec.py(throughsprite-gen prepare: a request alone keeps its style and cell with no note, a given--stylewins and says so, the subcommand takes every option prepare declares).New verb:
logomakes a transparent typography logo from a mood image. Lettering asked for alone comes back as a font with an effect; drawn into the picture it belongs to, it takes the scene's materials and light.sprite-gen logo --text … --style …letters the title (and an optional--subtitle, in an optional--language) into a 16:9 title screen or a 2:3 poster (gen), has the provider read its text back and refuses a title it dropped or misspelt before buying the next image, redraws only the lettering from that picture as an image edit on a chroma key (gen --ref), and cuts it out with the new logo matte, trimmed with a 2 px margin; the logo's text is read again and a logo whose letters differ is refused and kept aside aslogo.rejected.png. Both checks compare what the text spells: every letter and digit and every mark written on one (an accent, a vowel sign, a virama), with case, compatibility forms, the characters drawn as nothing, enclosing marks, spaces, punctuation and symbols folded away. Files:mood.png,lettering.png,logo.png,logo.preview.png(the logo on a dark and a light backdrop) andlogo.report.json(status, every step's prompt and numbers, the alpha coverage, the key hue left, both text checks, and every call with itsroute:subscriptionorper-call).--moodstarts from a picture you have;--letteringcuts a lettering image again with nothing generated.--chroma-key autoscores both keys on the colours in the title's box (the mood check returns it): a letter in a key's hue counts against it, and a key wins by how long a glow's mix with it keeps its hue. Nothing in the path draws a font (logo).New: the logo matte (
frames.logo_matte) keeps a glow's fade and leaves no key hue. The sprite matte ramps coverage over a short chroma distance, so on a white glow it is opaque half way to white with the pink mix of glow and key as its colour, and cuts the fade's last fifth to nothing. The logo matte measures the key as a quadratic surface with its noise, keeps material (far from the key, without its hue, minus rim pixels that are a mix of the key with the colour just inside) as drawn, gives a letter's antialiased edge its coverage on the letter's own colour, takes every other mix at the least coverage any colour could have, measures a glow's last trace on its faint neighbours, clears the faint seam a generated picture often has on its outer rows and columns, and writes each colour with the key's share taken out. Known limit: a glow carrying none of the key's hue, pooled dense and flat in a counter, is kept opaque; on the key whose hue it shares more it keeps its fade (logo).New: every provider's vision call takes the question asked (
inspect_image). The facing check's question and request body are unchanged;logoasks what the lettering spells, on the provider and credential that drew it.Tests —
tests/frames/test_logo_matte.py(synthetic lettering with a known coverage and colour, no font drawn: solid letters opaque in their colour; a white glow's fade within 0.04 of the truth, never opaque short of 80 %, and its faint trace kept; no key hue on a dark or a light backdrop; a shaded key; an outlined letter with a cyan glow; a pooled cyan glow on green, and the known limit on magenta; the green key; pixel lettering hard-edged; a seam on the picture's edge; refusals of a border that is not the key and of an empty key; the trim, the coverage and the key choice),tests/gen/test_logo.py(the three steps through a stand-in provider: prompts, references, files and report; the text check on a plain backdrop; empty text refused before any call; a dropped title refused before the lettering; differing letters and no text refused with the cut kept aside; a check that could not run said, not passed; subtitle and language;--mood,--letteringin place, the key from the title box, an explicit key; no font drawn; a failed lettering leaves nothing in its place; a painted checkerboard refused; per-call routes; the comparison across scripts: a Devanagari vowel sign, virama or nukta, a Thai tone mark or a Latin accent dropped, or Arabic vowel marks changed, is a mismatch, and a vowel sign dropped is refused at both checks; Hangul as jamo or syllables, half-width katakana, a Roman numeral form, a variation selector, a keycap and a zero-width joiner are the same spelling) andtests/gen/test_vision_read.py(the question and detail carried on codex, grok and openai; the facing body unchanged).Behavior change:
pixel-drawruns on your Claude subscription first, and onANTHROPIC_API_KEYonly without one — the ordercodexandgrokkeep. Whenclaude auth statussays Claude Code is signed in with a subscription (claude.aioroauth_token), every call — the drawings, the row repairs, the pick — goes through the unmodifiedclaudebinary in print mode, from an empty directory, with no tool, no session written and no CLAUDE.md, hook, skill, plugin or MCP server loaded, and costs nothing per call:report.jsonsaysauth_source: claude-login, each call'smodeissubscriptionand itscost_usd0, its usage kept. The child never seesANTHROPIC_API_KEY, which print mode would use instead of the login. Without a subscription login the run uses the key as before, billed per call and said on stderr; with neither it is refused naming both, before the run folder is made. A login that refuses a call, has expired or has reached its usage limit fails the call; the run never switches to the key on its own.--batchis the API's Message Batches and runs on the key even when signed in. An answer the binary continues past the output cap is read whole from every message, not from itsresult, which holds only the last part; one it cannot finish is read asstop_reason: max_tokens, so the one redraw one effort lower happens on either route. One call may take up toSPRITE_GEN_CLAUDE_CALL_TIMEOUT_SECONDS(1800). When candidates ask at once, none of their requests leaves before the billing line has been printed.report.json'sauth_sourceis what the calls ran on by their records,mixed(withauth_sources) for a run resumed under the other credential. A--resumethat reads every call back no longer prints the billing line (pixel-draw).Behavior change: every metered call says so on the terminal, and every report names what a call ran on. How codex is signed in is one reading,
codex_provider.codex_login(codex login status), for the default provider resolution,gen --provider codex, the codex facing check andworkflow: a codex signed in with an API key used to run with no word about it and the workflow called it a subscription; it now prints the per-call charge line beforecodex execruns, its report recordsextra.auth_source: codex-api-key(codex-loginon ChatGPT), andworkflowasks to confirm the API credit. A codex that is not signed in is refused with the reason before it runs.gen-setandvideo-setkeep each item's output in its log, but a child's billing line and a default provider switch now also print on the terminal as they happen (base.run_logged), eachgen-setrow recordsauth_source, and eachvideo-setclip result too.soundprints the same billing line as every other metered route (it printed its own) and its receipt recordsauth_source. One function reads a provider key from the environment (base.env_api_key: a key, none, or a refusal of an empty one) for Anthropic, OpenAI, xAI and ElevenLabs; one function says what to do when xAI rejects a credential (xai.rejected_fix), sogen --provider groknow gives the samegrok modelsrefresh asvideo.workflowprobes a provider once for its images and videos (they share one credential) and asks the API-credit question by that provider's name rather than always about Grok video. Docs: the credential table in the README, grok'sXAI_API_KEYroute in the help and SKILL.md, the sound billing line,SPRITE_GEN_GEN_TIMEOUT_SECONDSandSPRITE_GEN_CLAUDE_READ_TIMEOUT_SECONDS, andgen-set --provider(codexorgrok).Tests —
tests/gen/test_claude_login.py(the login before the key, the key only without a login, neither refused naming both, a batch on the key without asking the login, an unreadable status refused rather than read as no login, the child's environment without a key or the calling session, a message mapped onto the binary's flags and stdin with its image and schema, the stream-json answer, a cut answer read as max_tokens, a refused or limited login an error and not a switch to the key, no result, a timeout and a missing binary), the subscription, batch and read-back cases intests/gen/test_pixel_draw.py, andgen.base.env_api_keyintests/gen/test_gen.py;tests/gen/test_codex_login.py(ChatGPT, an API key and not signed in; the default resolution,generateandworkflowread the same login; an API-key login announces the charge and records it),base.run_loggedintests/gen/test_gen.py, the ElevenLabs billing line and key refusals intests/audio/test_sound.py.New:
background-tile --axis xymakes one tile seamless in both directions and measures both joins. It quilts along x, then along y with a cyclic seam: the second seam's two ends, which meet across the x wrap, may differ by one step at most, so the second quilt cannot break the first one's join. The report measures the finished tile on both axes (axes.x,axes.y, each with its join, quilt seam,statusand reasons); the top-levelstatusisneeds-reviewwhen either axis is, and each reason names its axis. Two separate one-axis runs had no such rule, and the second run's report measured only its own axis.inspect_tile_xy(image)measures both joins of any tile (asset-tools).New:
pixel-drawdraws a set of up to 64 frames, four a call. One call still draws at most four frames, so the frames of one answer share a palette and a design; a longer set — a hand-drawn motion of several seconds — is drawn four at a time, one call after another. Every call's prompt names all the frames and which ones it draws; each call after the first writes the first call's palette again — a colour it adds is refused and the rows that use it go to the row repair, a colour it changes is put back, both recorded in G1'srecovered(palette_added,palette_changed) — and is shown the first frame and the four just before its own, as the grid it writes (about 6,000 input tokens at 48 px, by the characters a token Opus's own answers wrote). The row repair and the one redraw are each call's own (c1-part2-gen1,c1-part2-gen1-fix1,c1-part2-gen2), the gates run once every frame is drawn,--resumereads every call back, and stderr says before the first request how many calls and tokens the set may take. A--specframe may be{"name": ..., "pose": ...}, which puts that pose on the frame's own line of its call's prompt. Previews put the frames in rows of eight, and a pick sheet larger than Claude reads unscaled (2576 px on the long edge, 4784 patches, read off Claude's vision page on 2026-10-15) is drawn at the largest smaller whole enlargement that fits, nearest-neighbour, instead of being blurred by the API's downscale. The report's candidates carryparts. An effect stays 2–8 frames in one call (pixel-draw).New:
pixel-draw --style TEXTdraws in a style of your own. It takes the place of the kind's style sentence (a sprite's "a dark (not pure black) outline around the silhouette, 2-3 shades per material, light from the top-left …") and of nothing else: the transparent background, the safe area and the floor row, a tile's seams and an effect's centre stay. The pick judges craft against the same words in place of its fixed "clean silhouette and outline". Without--styleboth prompts are byte for byte what they were. Same name and meaning asprepare --style; spec keystyle;request.stylein the report (pixel-draw).New:
pixel-draw --motion TEXT: the frames, in their order, are one motion. The prompt says so in your words, and G6 takes the rule of one motion, written once in the header ofpixel_gates.py: a frame off the ground row still fails, but a height that changes (an arm raised over the head, a blade swung past it) is asked whether the body changed size or only its pose, by the readingvideo-loop --body-heightalready makes of a cut (video.gait_fallback.size_changeon height, mass and breadth) — a pose is an info line, a body drawn at another size warns — and a frame drawn twice is a hold, an info line.gates.G6then hasrule: "motion",size_change,resized,posedandholds. Same name and meaning asvideo-prompt --motion; spec keymotion; also on--grid(pixel-draw).Behavior change: a
pixel-draw --walk-cycleis one motion. Its two passing frames drawn alike, or a height that changes by more than a pixel with the pose, no longer fail G6: they are info lines, and a body drawn at another size warns. A walk cycle still fails off the ground row, and still warns when its legs barely change sides.New:
pixel-draw --duration-ms Ntimesanim.gif(and an effect'sdelay_ms), 150 ms by default as before, at least 10; spec keyduration_ms, also on--grid. Same name and meaning ascompose-cycle --duration-ms.Docs:
pixel-draw's note that only effort xhigh spent every token thinking and wrote nothing is corrected — a set of four 48 px frames at effort high did too (2026-10-14).Tests —
tests/gen/test_pixel_draw_frames.py(a set of six drawn in two calls, the second holding the first's palette with a colour it added refused and repaired, shown the frames before it and carrying its frames' poses, read back whole on--resume; a later call shown the first frame and the four just before its own; a call drawn again on its own one effort lower; a call that fails ending its candidate; each call its own batch; spec frames refused;--stylein the drawing and the pick of every kind with the structure kept; the default drawing and pick prompts frozen byte for byte from before;--motionrefused for one frame and for an effect; a synthetic 48 px set of 46 frames of one motion — an arm raised for ten frames and held for four — passing--gridwith--motion, and failing without it;--duration-msinanim.gifand an effect's strip; a pick sheet of 46 frames for two candidates drawn at ×3 within Claude's unscaled size),tests/gen/test_pixel_gates.py(G6 of one motion lets a raised arm and a hold through, fails a frame off the ground and warns a body drawn larger; a walk cycle is one motion) andtests/gen/test_pixel_grid.py(a palette held, with a colour added and one changed; parts joined; previews in rows of eight).Fix: a
pixel-drawanswer that writes its block more than once is read from the last block that reads whole. An answer sometimes writes a first try — the palette andENDwith no frame — then "Corrected:" and the whole block (seen 2026-10-15 on a 16 px icon); G1 read the first block, found the frame missing and drew the candidate again. Now every block is read and the last one that reads whole is the answer (when none does, the last whose rows the row repair can fix), recorded in G1'srecoveredasblock_manywith which block was read. An answer of one block is read as before.Tests —
tests/gen/test_pixel_grid.py(several blocks read from the last whole one, or the last with rows to repair; one block as before) and an answer of two blocks drawn once intests/gen/test_pixel_draw.py.New: alpha haze cleanup for transparent sheets (
frames.alpha_floor.clear_haze). Pixels at or above a floor, and faint pixels within a few pixels of them (an object's anti-aliased edge), are kept byte for byte; every other faint pixel becomes fully transparent. The report measures the haze share before and after and counts the solid and edge pixels that changed (0). Used byui-kit(on by default) andslice-sheet --alpha-floor N(off by default; writes<prefix>alpha-cleanup.json).slice-sheet --chroma-key nonecuts a sheet that is already transparent on its own alpha (sheet-slicing).New verb:
ui-kitsplits a game UI kit sheet into nine-slice elements.gen --layout-guide ui-kitattaches a fixed square layout (panel, button, pressed button, card frame, HP and XP bar frames, timer badge) and asks for each element in its box.ui-kit --sheet uikit.png --out-dir ui/clears the haze, assigns parts to boxes by centroid, and writes each element's PNG andui-kit.json(or--report PATH, which must end in.json; each element'sfileis its PNG's path from the report's directory, so a report written outside--out-dirstill finds its elements): its rectangle, its stretch (xy,xfor the bars,nonefor the badge), nine-slice insets measured so that every corner ornament and end cap lies in a fixed slice, and the content padding (a bar frame's track, a panel's text area). An ornament in the middle of an edge, an empty box or a stray part is reported or refused (ui-kit).--layout-guidealone is still the one-slot figure guide.New:
game-packrequest and manifest version 2 withimages,tilesandui. Single images (props) are atlas frames with an anchor and an optional footprint ("base"measures where the image meets the ground); tiles are their own PNG and WebP files with their stored and on-screen sizes;ui.kitreads aui-kitreport into nine-slice entries (frame, size, stretch, insets, padding) andui.iconsadds fixed icons. Every number is in pixels of the stored image. A version 1 request is packed byte for byte as before, and a version 1 request naming the new sections is refused (game-pack).New:
slice-sheet --scale sheetkeeps the sizes a sheet was drawn at, and--fit containkeeps every cut whole. The default gives each cell's main subject the target height on its own, so the props of one sheet came out the same height, and lets the canvas cut whatever that scale puts past its edge, so a subject wider than the canvas lost its sides.--scale sheettakes one factor for the whole sheet (the tallest main subject reaches--target-height), so a prop drawn twice as tall stays twice as tall.--fit containlowers the factor until the whole cut fits the canvas, with the main subject still centred on its base; with--scale sheetthe sheet takes the smallest factor any cell fits at. Every cell of a sheet keeps one canvas size, so a game pack that gives the cells onedisplayheight keeps their sizes too (sheet-slicing).New:
slice-sheetwrites<prefix>slice-sheet.json. It names the scale and fit, the sheet's factor and where it came from, and per cell the factor, the main subject's size on the sheet and on the canvas, the cut's box on the canvas, theanchor(the centre of the main subject's base, ready for a game pack'simages[].anchor) andclipped_px, the pixels the canvas cut (report). A run also prints a line for each cell the canvas cut. The PNGs of a default run are unchanged byte for byte; a sheet with an empty cell now fails before any cell is written, where it used to write the cells before it.New: a 2:3 UI kit sheet holds the whole kit: bar fills, an item slot, a counter plate, on and off dots and a joystick.
gen --layout-guide ui-kit --aspect-ratio 2:3draws the square layout's seven frames at the same places and, in a band below them,hp_bar_fillandxp_bar_fill(x),slotandbadge(xy),pip_on,pip_off,joystick_baseandjoystick_knob(none, so round parts keep their proportions; the guide draws them as circles, and a cut with filled corners, a round part drawn on a square plate, makes the reportneeds-review).ui-kitpicks the layout from the sheet's shape, so a square sheet is cut, measured and packed exactly as before. Padding is measured only for elements that hold content; fills, dots and joystick parts get0. Each fill's report entry hasinside: its bar frame, that frame's content rectangle and the factor that makes the fill as tall as it, and the report isneeds-reviewwhen the fill's ends would overflow it.game-pack(still version 2) stores each fill at exactly its frame's content rectangle, ends kept and middle columns repeated or dropped, withinsidein its entry, and refuses a fill whose frame is missing or whose ends do not fit (ui-kit, game-pack).Behavior change: a 2:3 UI kit sheet that leaves a band element out still makes a kit, without it. The seven frames (
panel,button,button_pressed,card,hp_bar_frame,xp_bar_frame,timer_badge) are required: an empty frame box still failsui-kitwith<element>: its box holds no element; generate the sheet again, now naming every empty frame box at once (panel, card: their boxes hold no element; …). The eight band elements (the fills, the slot, the badge, the dots and the joystick parts) are optional: an empty band box leaves that element out. It gets no PNG and noelementsentry, the report names it undermissing(every 2:3 report hasmissing,[]when nothing is missing), and the command's line ends with; missing, left out of the kit: ….statusstays about the elements that are there.game-packis unchanged: it packs the elements a report has, so a missing element has noui.nine_sliceentry and a game falls back for exactly that part. A square sheet's report, elements and packs are unchanged byte for byte, and its report has nomissing(ui-kit).Behavior change:
ui-kitwrites a kit whole into a new directory and refuses one that holds anything.--out-dirmust not exist yet or be an empty directory. One that holds an earlier kit or any other file is refused with its name and what it holds, and left as it was, where a rerun used to rewrite the kit in place one file at a time and a failure partway left two kits mixed under one report. The kit is written into a hidden directory beside--out-dirand renamed into place in one step, so a run that fails or is killed at any step leaves either nothing or the whole kit, and of two runs into one new--out-dirthe second is refused. A--reportoutside--out-dirmust be a new path: it takes its name after the rename, in a step that fails when another run took the name first. One step publishes the kit, the rename or, with the report outside, the report's own step: a run that fails or is stopped with Ctrl-C before it takes everything it made back out, and one stopped after it leaves the whole kit and its report, so a report never names a PNG that is not there. A killed run can leave its hidden directory (.<out-dir>.ui-kit-*) or report temp beside them, and, with the report outside, the whole kit without its report. A run that is interrupted again while it is removing what it made (for example, a second Ctrl-C during that clean-up) cannot finish the clean-up either: it can leave the same things a killed run leaves, and never leaves part of a kit under--out-dir's own name:--out-dirholds nothing or the whole kit (ui-kit).Fix: a UI kit sheet drawn a few percent shorter than its guide is cut instead of refused. An image model may draw the layout a few percent shorter than the guide; the lower an element, the farther it sits above its box, until its centroid lies in the widened box above its own. That box held two elements and the element's own box none, so
ui-kitrefused the sheet with<element>: its box holds no elementalthough every element was drawn. When a box is left empty,ui-kitnow fits the layout to the drawing (a scale and an offset along x and y, least squares from the box centres to what the boxes hold, repeated until the assignment comes out the same) and assigns the parts again. The fit is kept when it leaves fewer required boxes empty, or as many and fewer boxes in all. A kept fit is in the report aslayout_fit, and eachboxis then the fitted box. A sheet whose every box holds its element is cut exactly as before (ui-kit).Behavior change: a key background painted as a transparency checkerboard is refused before keying. Asked for a magenta or green key, a model sometimes paints the grey and white checkerboard editors show behind transparent pixels. The matte read the checkerboard as the key and keyed nearly the whole image away, so a UI kit sheet had nothing left to cut. Every chroma key in
gennow checks the raw first (chroma.painted_checkerboard: two greys alternating in squares of one size along a horizontal edge and a vertical edge), and fails with its own reason,chroma: the background is a painted transparency checkerboard (… px squares along the … edges), not the magenta key the image was asked for; keying it would erase the image — generate it again, publishing nothing. A ref run whose raw is a drawn checkerboard was keyed before; it is refused now. Key backgrounds, plain or striped grey backgrounds, and a checkered subject inside a key background are not refused (gen).Tests —
tests/frames/test_ui_kit.py(the frames required and the band optional; an empty band box, several, or the whole band leaves those elements out of the report, the PNGs and the pack; an empty frame box, alone, several at once, or on a squeezed sheet (each frame in turn), refuses the sheet by that frame's name; a kit is written into a new or empty directory, and one that holds a kit, any other file or a hidden one, or a file at its path, is refused and left byte for byte as it was; one failure, interrupt or kill injected just before or just after each filesystem step of the publish, with the report in and outside--out-dirand--out-dirabsent or empty (and removed first, as on Windows), leaves nothing before the step that publishes the kit and the whole kit from it on; an interrupt of any kind (SIGINT, SIGTERM through a handler that exits, any other exception) at each step from the rename on, with no function replaced, the same; a sweep in which an interrupt of each kind (SIGINT, SIGTERM through a handler that exits, any other exception) is raised once per run at each line, and at each instruction, of the publish, with the report in and outside--out-dirand--out-dirabsent, empty, or empty and removed first, and every run ends with that interrupt and leaves either the start, with nothing hidden, or the whole kit; a run whose--out-diror outside report another run reaches first is refused and removes what it made; a 2:3 sheet drawn 7 % shorter than its guide, which the layout's own boxes refuse, is fitted and every element is cut whole inside its fitted box; a square report has nomissing),tests/gen/test_painted_checkerboard.py(checkerboards of 8, 12 and 32 px squares at any phase and greys, with elements across two edges, are found; key, plain grey, gradient and striped backgrounds and a chessboard inside a key background are not;key_transparentand a--layout-guide ui-kitrun refuse a checkerboard before the matte runs and publish nothing), and the drawn-checkerboard ref run intests/gen/test_gen.py, which now refuses.Tests —
tests/background/test_tile_xy.py(an exact doubly periodic crop, a join that stays visible on one axis names that axis, the cyclic seam),tests/frames/test_alpha_floor.py(a haze ring cleared, thin strokes and their anti-aliased edges kept),tests/frames/test_ui_kit.py(a synthetic sheet on the layout: insets to the pixel over corner ornaments, a long flourish, a bar's end gem and cap; badge padding inside its ring; a packed kit at four scales keeps ornament fringes out of the stretched middle; a report in, beside, below or above--out-dirnames the PNGs from its own directory and packs the same bytes),tests/frames/test_slice_sheet_transparent.py,tests/compose/test_game_pack_v2.py(the manifest field by field, refusals, and a version 1 manifest and page pixels frozen from 2.44.0),tests/compose/test_game_pack_audio.py(a version 1 pack with sound keeps its file list, manifest bytes and page pixels from 2.44.0; a version 2 pack with sound adds only its tile files) the--layout-guide ui-kitcases intests/gen/test_layout_guide.py(square and 2:3, any other ratio refused), the 2:3 sheet intests/frames/test_ui_kit.py(every element cut from a synthetic sheet; fills fit their frame's content area in the report and, packed at three scales, to the pixel with their ends unchanged; dots and joystick parts never stretch and one drawn on a square plate is flagged; slot and plate insets to the pixel; a square sheet's report, element pixels and packs frozen from before the 2:3 sheet) and the fill cases intests/compose/test_game_pack_v2.py, andtests/frames/test_slice_sheet_scale.py(synthetic sheets: drawn heights kept within a pixel with--scale sheet, after the alpha cleanup too; a 2:1 subject whole on a square canvas with--fit containwhile the default still cuts it and says so; one factor every cut fits; sliced cells packed as game-packimageskeep one size and stand on the reported anchor; refusals).Bump audio processing recipe to version 4, measure BS.1770-4 loudness over normalized PCM frames and gated blocks, support a peak-limited loudness goal, normalize loudnorm-unanalysable short clips via limiter passes instead of refusing them, encode AAC using
-aac_coder fast, recordnormalization.pcm_lufsandpcm_true_peak_dbtprequired to load version 4 bundles, keep recipe version 3 bundles loadable in game packs by their own rule (target loudness, decoded files re-measured with loudnorm), reject recipe version 1-2 bundles, and reject recipe version 1-3 output directories insprite-gen soundwhile reusing cached provider audio.Bump audio processing recipe to version 3, require
ffprobeonPATH, export M4A with-movie_timescale 48000, and validate AAC stream duration withffprobe.Add bounded one-frame decoded length tolerance, preserving loop duration, trimming one-shots, and rejecting shorter buffers and undersized overlaps at export.
Configure loop playback in
createAudioSourceusing an internally cached L+1 guard frame buffer while preservingprepareAudioBufferframe contracts.Upgraded sound generation and game-pack audio integration to version 2: removed file-level crossfades and boundary tapers in favor of complete normalized exports with integer frame
playbackcoordinates, removed legacy loop seconds and taper metadata, and bundled standalone runtime helpersprite-gen-audio-v2.mjsfor Web Audio loop preparation.Added
sprite-gen soundCLI and game-pack audio integration for ElevenLabs SFX/BGM generation, featuring SQLite request deduplication, cosine loop crossfading, multi-pass FFmpeg loudnorm/alimiter normalization, dual Opus/AAC encoding, and Web Audio loop boundary metadata.Added
--cycle oncenonloop motion support with automatic selection fordeath,fall,land,cast,hurt_hold, andtransform, rejection on cyclic states, no seam gate or wrap correction, and a terminal stability gate searching the whole clip for the first stable terminal window ($K = \max(4, \lceil\text{fps} \times 0.2\rceil)$) after action departure (ending at window end, discarding later recovery or shaking), with conservative candidate end pose geometric screening (alpha >= 8 body boxes; height <= 80% of initial fordeath/fall, changed geometry for the other named states) and retained cut edge contact validation (ignoring discarded tail).Added nonloop-only flags
video-prompt --end-frame final.png(refuses--no-last-frame, prints instructions without image validation) andvideo-set --end-frame ITEM=PATH(checks final canvas dimensions and corner key match initial canvas), with clip cache tracking end-image SHA256 where changed end pins reject until user explicitly--forceregenerates.Added endpoint-preserving strip downsampling with candidate events (
events:[{"frame": n, "name":"motion_peak"}]using zero-based output cell indices mapped to keyed source frames viasource_cut.samples) andoncepreview handling, with nonloop cycles insisting on existing--anchor noneand--fit statewhile rejecting non-none anchor and tight fit.Behavior change: a flag given together with a file that holds the same key wins, and one stderr line says so — for
prepare --request/--request-jsonandpixel-draw --specalike.pixel-drawrefused the pair;preparelet the flag win for most keys in silence, and let the request win for three:--style,--cell-sizeand--safe-marginwere dropped when the request carried a style, a cell size or a margin. Now every such key takes the flag and the run says[prepare] --style, --cell-size given both as a flag and in --request-json: the flag wins(gen.base.flags_over_spec, the one answer, run contract). A cell flag replaces the measure however the request spelled it (size,width,cell_width).prepare's note no longer lists a request'ssubjectamong the keys it drops — it was always carried.Behavior change: an answered provider request is sent again only when the provider documents the answer as a request it did not take — one rule for every direct call.
gen's OpenAI and Grok image POSTs, the facing check and the clip POST of the video verbs were never sent again, andpixel-draw's Anthropic transport sent 429 and every 5xx again after 10 s and 30 s. Now each asksgen.retry: OpenAI 429 (but its billing codes — a spent credit balance, a spend or usage limit,insufficient_quota— which ask you to act) and 503 overloaded; xAI 429; Anthropic 429 (but its spend cap), 500 and 529 — read off each provider's error and rate-limit pages on 2026-10-13 (a refused request sent again). Not sent again any more: Anthropic 502, 503 and 504 (timed out while processing). The wait is the answer'sretry-afterwhen it is at most 120 s (a longer one is not cut short: the request is not sent again), else the doubling the video polls already waited by, 8 s then 16 s; twice at most, each on stderr as[gen] openai refused the request (429 rate_limit_exceeded); nothing was made — asking again in 8s (1 of 2). A refusal still there ends the call as before, its line sayingsent 3 times, no provider fallbackin place ofno retry or provider fallback. A request with no answer it could read is still never sent again.video-setruns each clip once: its own rerun of a clip whose log saidHTTP 429(15 s, 30 s) is gone, as it made every POST a second retry loop on top of the first. The video polls and downloads also ask again on529.Fix: a refusal whose body broke on the way is no answer on every transport.
xai.http_jsonalready said so;openai-genlet the broken read escape as a traceback, andpixel-draw's Anthropic transport read it as a refusal with an empty body (and sent a 429 or 5xx again). Both now end as a request that got no answer — the server may have taken it — through the one reader of a refusal's body,xai.error_body. An OpenAI answer cut short (IncompleteRead) is that line too, not a traceback.Fix: a hex colour is six hex digits, the
#optional — read and written in one place (util.hexcolor).recolor's map,slice-sheet --chroma-key,handed-check --marker/--strapand the curation view's pixel edits took a sign or an underscore as a digit (#-1-1-1read as (-1, -1, -1); a non-hex six-letter edit stopped the request); each now refuses it in its own words, and the curation view skips it as it skips a value of the wrong length.prepare --chroma-keyalso takesRRGGBBwithout the#, as the other flags did. Written colours are unchanged: upper case, and lower case inrecolor's report and palette draft.Fix: a Python call of
gen.run, the video verbs'run,pixel-draw'srunorinspect-motion'srunwithout a required flag is a TypeError naming it, as the other verbs'run(**kwargs)always said; these four read their keywords by hand and went on withNone. One reader for all,util.cli_kwargs.namespace_from_kwargs, in place of twelve copies and four hand-made readings.Internal:
pixel-draw's G8 sizes a frame by the image path's opaque box,frames.extract.solid_alpha_bbox, in place of its own count of opaque rows and columns — the same box, read in one place;gates.G8is unchanged.New:
anthropic_api.billed_tokens(usage)— a Claude call's tokens by the price each is billed at, the splitcost_usdpriced inline, now one public functioncost_usdasks: input, output, cache reads, and cache writes by their lifetime (usage.cache_creation's five-minute and one-hour counts; a reply that does not split them wrote for five minutes), keyed asPRICE_PER_MTOKprices them, each count as the reply gave it. A caller that prices the calls at rates of its own reads the same split instead of keeping a copy.cost_usdis unchanged.Tests —
tests/gen/test_retry.py(the rule per provider and status, every direct call asking it, a broken refusal body is no answer on all three transports),tests/gen/test_flags_over_spec.py,tests/test_cli_kwargs.py,tests/test_hexcolor.py(each verb reads through the one function; a second copy turns them red), and the provider, video, video-set and G8 tests moved to the new answers.New (experimental):
sprite-gen pixel-draw— Claude Opus draws pixel art of 8–48 px directly, as a pixel grid. The model writes a palette and one line of keys per pixel row (a character grid, or JSON with--format json); code checks it and renders it.--subject(or--spec),--size8–48 (32),--kind sprite|icon|tile,--frames(up to four, drawn in one call;--walk-cyclefor contact, passing, contact, passing),--palette free[:N]|pico8|#hex,…|file,--candidates(2),--effort medium|high|xhigh(high),--batch(Message Batches, half price),--max-tokens(32000 for one frame, 64000 for more),--pick vision|human. G1 reads every answer strictly; a row one key too long or short, a key outside the palette or rows missing at the end go back to the model on their own with a column ruler and are spliced in (two rounds), and an answer still broken — or broken beyond its rows — is drawn once more; a single frame written without itsFRAMEline is recovered and recorded. A sprite or icon is drawn to the engine's safe area —prepare's margin, 9.4% of the side, floored, taken frompreparerather than copied — as a target for the body's average size, not a wall: at 32 px the body is about the size of the central 26×26 (16 → 14, 24 → 20, 48 → 40), a pose or a detail that needs the room (a raised weapon, a long blade, an effect, a wide stance) may reach past it into the margin, up to the canvas edge, and a sprite's feet stand on the safe area's bottom row, the rowprepare's fit grounds a frame on, in every frame; the prompt says it in rows and columns counted from 1. G2 palette, G3 alpha and G6 frames (one ground line, heights within a pixel, no two frames the same — a sprite's or icon's measured inside the safe area, so a staff or a spark that reaches into the margin in one frame is not a taller figure) fail a candidate; G4 tile seam, G5 stray pixels and a walk whose legs barely change sides warn. G3, G4 and G5 ask judgments sprite-gen already makes rather than keep their own, each lifted out of its owner unchanged: G3 is whether a frame's background is really transparent by the verdictgenreads a generated raw by (chroma.alpha_verdict, out ofclassify_raw_alpha: at least 5 % of the pixels and half the one-pixel border alpha 0 for a sprite or icon, with something drawn and the four corners clear; no alpha-0 pixel for a tile); G4 isbackground-tile's join measure (inspect_tile), asked of a tile along x and along y, and warns with its reasons where it saysneeds-review; G5 counts the lone pixels the YCbCr matte cleanup erases (frames.extract.isolated_dots, out of_cleanup_alpha_ycc: no opaque pixel among the eight neighbours), so each pixel of a one-pixel diagonal stroke, which touches the next at a corner, is no longer a stray pixel. G8 safe area never fails a candidate: it takes the judgment the pixel snap already makes — one function,safe_area_fitinframes/extract.py, lifted out of the snap with its lines unchanged — on each frame's opaque box: past the physical cap (the canvas's width, its height less the margin under the floor row, 32×29 at 32 px) warns, a reroll candidate; past the safe area but within the cap is an info line,infoin the report, which asks for nothing; and a sprite whose feet are off the floor row warns. Of two or more candidates that pass, one vision call at effort low picks (G7). An answer that spent every token thinking is drawn once more one effort lower; a refusal is reported as it came (refused by the provider's content policy (stop_reason=refusal category=…)); nothing falls back to another model. The run folder holdsgrid.txt(the truth: edit it and re-render with--grid),palette.json,frame-<name>.pngwritten by an encoder whose bytes depend on the pixels alone,preview-x<s>.png,tiled-3x3.pngfor a tile,anim.giffor several frames, every call undercalls/andreport.jsonwith each call's model, effort, usage (thinking tokens included), price, seconds and request id, the gate results and the repair history. A batch is recorded the moment it is submitted, and--resumecollects it — and reads every answered call back — instead of buying it twice. It runs onANTHROPIC_API_KEY, billed per call and said so on stderr; the transport is urllib, so the dependency surface stays Pillow and NumPy — docs/pixel-draw.md.Fix: a poll xAI answers 429 or 5xx asks the same request again — the clip is bought once.
video,video-extendandvideo-editended the run on any non-2xx poll, after xAI had accepted the request and may bill it, and the line read(HTTP 429)— whatvideo-set, and any caller that backs off on a refused submission, answers by submitting the clip again: a second clip paid for, the first never published. A poll answered429,500,502,503or504is now asked again on the samerequest_id, after a wait that doubles from 8 s up to 60 s while the polls are refused and goes back to 4 s on an answer; a stderr note says each, the status in plain digits. The poll timeout (SPRITE_GEN_VIDEO_TIMEOUT_SECONDS) still bounds the whole poll, a pending poll's waits included (and, below, the downloads). A refused POST is still never sent again, and a400or404poll still ends the run with its status (a401or403poll is unfinished, below).Output change: a generation the poll timeout cut short is unfinished, named by its
request_id. Polls still pending or still refused at the timeout end the run with a line that namesrequest_id=<id>, says the generation may still finish and be billed, and carries no(HTTP <n>), a refusal line's status — a caller that reads(HTTP 429)there sends the request again, unbilled only when it was refused. The pending line keeps its front (still 'pending' after N polls — poll timeout;). With--reportthe run leaves asprite-gen-video-unfinishedreport there (verb,auth_source,model,request_id,out,polls,polls_refused,last_poll,elapsed_seconds) and prints nothing on stdout; Python callers catchGenerationUnfinished, aSystemExit. The success report gainspolls_refused, how many of itspollsxAI answered 429 or 5xx (docs/video.md, An unfinished generation).tests/gen/test_video.pyscripts the polls: each of the five statuses refused twice, then pending, then done, is asked on the one request with waits 8, 16, 4 and published withpolls_refused2; polls refused until a 300 s timeout wait 8, 16, 32, 60 × 4, ask no poll whose wait would reach the timeout and end unfinished after eight with no(HTTP n)and noHTTP 429on stderr; a pending timeout names the request; a 400 or 404 poll ends at once; a refused POST is sent once; the CLI leaves the unfinished report and an empty stdout. The 500-poll case of the failure table is a 404 now, the status that still ends a run.New verb:
video-resumeasks again for a generation a run left unfinished — by itsrequest_id, with no new POST. A run cut short named the request to ask for again, but no verb could ask for it: a caller had to submit the clip again, a second purchase, or give the clip up.sprite-gen video-resume --request-id <id> --out clip.mp4 [--report r.json]pollsGET /v1/videos/{id}as the generating verbs do — the same retries, backoff and poll timeout — then downloads, verifies and publishes the clip. Nothing is submitted, so nothing is bought twice and theXAI_API_KEYroute prints no charge notice. Its report is asprite-gen-video-reportwithmode: "resume", the samerequest_id,inputs: {}andduration_requested: null; cut short again it is unfinished on the same id,verb: "video-resume",model: null; an id xAI does not know ends with its(HTTP 404). The id is refused before any call unless it is letters, digits,.,_and-. A resumed clip is checked as an mp4 only —video-extend's length rule needs the input clip (docs/video.md,sprite-gen video-resume).Fix: a poll that gets no answer, or whose credential xAI rejects, leaves the request's id. After xAI had accepted the request, a poll whose connection failed or timed out ended the run with the transport's line and no
request_id, and a poll answered401ended it with its status. A poll that gets no answer is a GET, which buys nothing, so it is now asked again with the refused polls' backoff (a refused poll and a lost one are two failures in a row) and a stderr note,poll N of generation <id> got no answer (<reason>); asking again in 8s; lost until the poll timeout, the run is unfinished. A poll answered401or403— the credential stopped working after the POST, typically an expired login — ends the run unfinished at once, naming the credential's fix (refresh the grok login, or checkXAI_API_KEY) before the request to ask for. A POST that gets no answer ends as before: norequest_idcame back.xai.http_jsonraisesxai.TransportErrorfor a request that got no answer, still aSystemExitwith the same line, the socket's words inreason.Output change: the unfinished line names the command that asks again; reports count the polls that got no answer. The line reads
ask for request_id=<id> again with `sprite-gen video-resume --request-id <id> --out <out>` instead of submitting a new request,request_id=<id>kept as it was. The success and unfinished reports gainpolls_unanswered, how many ofpollsgot no answer, each asked again; the unfinished report'slast_pollgainserror, what the socket said, when its last poll got none (httpthennull).tests/gen/test_video.pyasks again by id and loses polls:xai.http_jsonraisesxai.TransportErrorwith the old line for a DNS failure, a timeout and a reset; lost, pending, refused, lost, done is asked on the one request with waits 8, 4, 8, 16 and published withpolls_unanswered2; lost until a 30 s timeout waits 8 and 16 and ends unfinished withlast_poll.error; a lost POST is sent once and is not unfinished; a 401 or 403 poll, on the login or on the key, ends unfinished at once naming its fix;video-resumepolls with no POST and announces no charge, ends unfinished on the same id when refused, lost or pending past the timeout or when its credential is rejected, ends with(HTTP 404)for an unknown id, refuses eight ids that cannot be one before any call, and its CLI writes the resume report, the unfinished report and an empty stdout; the unified CLI routes it undergen.Fix: a poll whose answer is cut short, garbled or not JSON is asked again on the same request — the run no longer ends with no
request_id. A poll answer that broke after it began — a body that closed before itsContent-Length(http.client.IncompleteRead), a status line that is not one (BadStatusLine), a refusal's body cut the same way — escapedvideo,video-extend,video-editandvideo-resumeas a raw exception, with norequest_id, no unfinished report and no resume command, so a caller could only submit the clip again and buy it twice; a200poll whose body is not JSON ended the run onxai: response was not valid JSON, also with no id. Both are now a poll that got no answer it could read, as a lost one is: asked again on the samerequest_idwith the same backoff and stderr note (got no answer (IncompleteRead(10 bytes read, 190 more expected)),got no answer (response was not valid JSON)), counted inpolls_unanswered, and unfinished at the poll timeout with that reason inlast_poll.error. A POST so answered still ends at once and is never sent again — norequest_idcould be read: on the transport's line for a broken answer (a raw exception before), on the not-JSON line it always had.xai.http_jsonraisesxai.TransportErrorfor every answer it cannot read whole, each with the line it always had;reasonis thehttp.clientexception's repr for a broken answer,response was not valid JSONfor the other.tests/gen/test_video.pyanswers over a real socket from a local server:xai.http_jsonraisesxai.TransportErrorfor a body closed 10 bytes into its 200, a 503 body cut the same way, a garbage status line (the transport's line) and a whole non-JSON200(the not-JSON line); cut, garbled, not JSON, cut refusal, pending, done is asked on the one request with waits 8, 16, 32, 60, 4 and published withpolls_unanswered4; a resumed poll cut short is asked again and published; cut until a 30 s timeout, the CLI leaves the unfinished report withlast_poll.errortheIncompleteReadand an empty stdout; a cut POST is sent once and is not unfinished.Fix: a clip that is done and whose download fails leaves the run unfinished on its
request_id— never a second purchase. Once the poll said done the clip is made and may be billed, yet a failed download endedvideo,video-extend,video-editandvideo-resumewith norequest_id, no unfinished report and no resume command: a refused connection onvideo: cannot download the clip: …, a body cut short of itsContent-Length(http.client.IncompleteRead) or a read that timed out as a raw exception, a refused download onvideo: download failed with HTTP <n>, and bytes that are not an mp4 on… refusing to publish— so a caller could only submit the clip again and buy it twice. A download that gets no answer it can read, or that the clip's host refuses with429,500,502,503or504, is now downloaded again after 8 s and then 16 s, three downloads in all, with a stderr note before each (download N of generation <id> got no answer (<reason>); downloading again in 8s,… was refused (503); …); one still failing, one refused with another status (a401or403still asked once more with the bearer token first), or bytes that are not an mp4 end the run unfinished on that id:… is done, but its download got no answer (last: <reason>) after 3 attempts; the clip is made and may be billed — ask for request_id=<id> again with `sprite-gen video-resume --request-id <id> --out <out>` …, no(HTTP <n>)on it.video-resumepolls afresh, so it downloads from the URL the new poll names.video.http_downloadraisesxai.TransportError(its line stillvideo: cannot download the clip: <reason>) for a download that got no answer andvideo.DownloadRefused, aSystemExitcarryingstatus, for a refused one;xai.NO_ANSWERandxai.no_answerare the transport's classifier, now shared by both.Output change: bytes that came whole and are not an mp4 are unfinished, not a refusal. xAI's one content-policy signal is
respect_moderation: falseon the done poll, read before any download; anything else at the clip's URL — an expired link's page, a proxy's error page served200— is a fault in delivering a clip that is made, and therequest_idis the only way back to it.video-resumecosts a poll and asks for a fresh URL; a refusal left only a new submission. The same URL brings the same bytes, so the run does not download it again itself (docs/video.md, An unfinished generation).video.verify_mp4is gone.Output change: reports count the clip's downloads. The success report gains
downloads, how many downloads the clip took, the last one whole (1 unless one failed). An unfinished report of a clip that could not be downloaded gainsdownloadsandlast_download—httpthe status the clip's host refused it with, elsenull;errorwhat the transport said, ornot an mp4 (no ftyp box)with thebytesthat came — and itslast_pollis the done poll; an unfinished report of a poll is unchanged.tests/gen/test_video.pydownloads the clip over a real socket from the local server: a clip body closed 10 bytes into its 76, a read held open past a 1 s timeout and a connection to a port nothing holds are each downloaded three times with waits 8 and 16, and the CLI leaves the unfinished report naming the request withdownloads3,last_download.errorthe transport's words and an empty stdout; a cut download, then a503, then the whole clip publishes withdownloads3; a503three times and a404once end unfinished withlast_download.http, no(HTTP n); 34 whole bytes of HTML end unfinished at once withlast_download.bytes; and a run left unfinished by its downloads is published byvideo-resumeon the id its report names, from the fresh URL of a new poll and with no POST. The fake transport's non-mp4 refusal test is that HTML test now. A port held bound and not listening is no refused port on macOS (its SYN is dropped and the connect times out), so the test takes a free port and lets it go.Fix: the poll timeout bounds the clip's downloads and every read — a caller that stops the run at a hard limit gets the
request_idback before it. The downloads after a done poll ran outside the poll timeout — up to three, each with its own 120 s read timeout, 8 s and 16 s between — and a poll in flight when the timeout came could read on for its own 120 s. A run could so outlive a limit its caller set a little over the timeout and be killed before it wrote its unfinished report: norequest_id, and a clip that may be billed could only be bought again. The poll timeout (SPRITE_GEN_VIDEO_TIMEOUT_SECONDS) is now the one time limit of an accepted request, counted from the POST's send. Every poll and download reads only what is left of it — one that stalls, or whose bytes come too slowly for a read's timeout ever to fire, is cut when it comes (timed out) — a poll or download whose wait would reach it is not asked, and the run is unfinished on therequest_idthen:… is done, but its download got no answer (last: timed out) until the poll timeout (210s, 1 attempt); …,… was refused (last answer 503) until the poll timeout (20s, 2 attempts); …. The POST is not cut by it, its answer being the one way to the id; one answered after the whole timeout is unfinished before any poll (… was accepted after the poll timeout (600s) had run out, before any poll; …,polls0).xai.http_jsonandvideo.http_downloadtakedeadline=, atime.monotonic()instant, and read the body a chunk at a time by it (xai.read_whole,xai.time_left); without one they read as before (docs/video.md, step 3).Output change: the poll timeout ends the run when the next poll's wait would reach it, not with a last poll at it. That poll would have no time left to be answered. A run cut short by the timeout ends up to one wait before it (4 s while pending, up to 60 s while refused), with one poll fewer: a 300 s timeout of refused polls ends after 8 polls at 296 s, where it asked a ninth at 300 s.
Fix: a done poll that names no URL to download is unfinished on its
request_id. It ended on<verb>: generation <id> is done but reported no video url, with no unfinished report, and aurlthat is not a string or not a web address escaped as a raw exception: a clip xAI says is made, and may bill, left only a second purchase. A done poll with nohttp(s)://URL — none, empty,null, not a string, novideoobject — now ends… is done, but its poll named no video url to download; the clip is made and may be billed — ask for request_id=<id> again with `sprite-gen video-resume …` …, the report'slast_pollthe done poll and nodownloads;video-resumepolls it afresh.respect_moderation: falseis still the content-policy refusal it was.tests/gen/test_video.pyruns the time limit on the real clock against the local server, with a 1.5 s timeout: a clip download that stalls past it (its read timeout longer than what is left) or comes a byte every 20 ms is downloaded once and cut at the timeout, and the CLI leaves the unfinished report by then (last_download.errortimed out,elapsed_secondsunder 2.5); a poll that stalls or trickles is cut the same way. A503download whose next wait would reach a 20 s timeout is not downloaded again; a POST that took 12 of 20 s leaves the polls 8 s, and one that took 25 s is unfinished before any poll. A done poll with no url, an empty, null or numeric one, one with no scheme or novideoobject is unfinished on its id forvideoandvideo-resume.xai.http_jsonreads a cut, garbled or not-JSON answer as no answer with a deadline as without one. The poll-timeout cases end a poll earlier: refused polls until 300 s wait 8, 16, 32, 60 × 4 and end after 8 polls at 296 s; lost or cut polls until 30 s wait 8 and 16 and end after 3; pending polls until 10 s end after 3. The failure table's done poll with an emptyvideoexpects the unfinished line.Output change: an
openaiimage report carries the response's rate-limit headers —extra.rate_limit. The provider dropped the response headers, so what the account may spend per minute and has left could not be read off real traffic.extra.rate_limitnow holds everyx-ratelimit-*header the response carried, names lower-cased and values as sent, and{}when none came (docs/gen.md).openai_provider.http_imagereturns the response headers as a third value.tests/gen/test_openai_provider.pyanswers with headers: the report holds exactly thex-ratelimit-*ones among others of any case, and{}for a response without any.
v2.44.0 - A filmed ghost in a loop delivered as cut is given way, or named a take to film again; restoration reads the ghost; the RIFE lane runs every real-RIFE test
Upgrading from 2.43.0: the restoration contract moves with the version. Source restoration is now metric source-restoration-v5 under policy key-protected-source-copy-one-step-cap-jump-ghost-guard-v1, and writes repair report schema_version 4 and comparison schema_version 6 (sprite_gen.video.restoration: METRIC, POLICY, REPAIR_SCHEMA, COMPARISON_SCHEMA); a consumer that checks these values raises all four with its pin. Nothing source-restoration-v4 (2.40.0 – 2.43.0) wrote is read as v5: a v4 repair report given to video-loop-compare is an input error, and a request whose baseline carries a v4 receipt in its loop report is shared unknown, restoration-receipt-policy-unsupported. A loop restored under v4 therefore goes on from its origin, not its v4 baseline: the origin itself is still a valid first request (the same five files as origin and baseline). Proposal IDs change with the versions. video-loop-compare without the origin and the source (same-sample-defects-v1) is unchanged.
- Fix: the Linux lane's
--rife-onlyruns every test of the real RIFE, not one file. It rantests/video/test_rife.pyalone, while--rife-unmeasuredskips every test that needs the realrife-ncnn-vulkan— so a real-RIFE test in another file (2.43.0's intests/video/test_crossfade.pyandtests/video/test_ghost_screen.py) was measured by neither run. Such a test now carries one mark,real_rife(registered inpyproject.toml):tests/conftest.pyskips the marked tests whererife.locate()finds no RIFE, andscripts/linux_lane.sh --rife-onlyrunspytest -m real_rifeover the whole suite, none skipped. A new real-RIFE test is run by--rife-onlyonce it is marked.docs/release.mdsays what each run measures. - The lane's RIFE-less run fails a skip that
--rife-onlywill not run.--rife-unmeasuredruns the suite aspytest --rife-unmeasured, wheretests/conftest.pyreads every skip — by a skip mark, in a fixture or the test body, or of a whole file at import: one whose test is not markedreal_rifefails by name, unlessNOT_RIFE_SKIPSin the same file names it as skipping for an input the lane does not give (theSPRITE_GEN_CHROMA_REAL_STILLSstills). Such a skip would be measured by neither run. tests/release/test_lane_rife_collection.pycollects the suite twice, once with a stand-in RIFE whererife.locate()looks (SPRITE_GEN_RIFE,PATH, the install root) and once with none: a test the two collections skip or collect differently and that is not markedreal_rifefails it by name — a test collected only where RIFE is reachable never reaches the RIFE-less run. It also runs a marked test and each unmarked way to skip without RIFE throughpytest --rife-unmeasured: the marked one skips, every other fails by name.- Correction to 2.43.0's cross-fade measure: "the windows step by half their size, so one lost pixel is counted in up to four of them" holds where the window is an even number of pixels wide. The step is half the width rounded down, so an odd-width window counts one pixel in up to nine. The
rife.crossfadedocstring anddocs/loop-repair.mdsection 4 now say "up to four of them (nine where the window is an odd number of pixels wide)". The measure is unchanged. - Output change: a filmed ghost with no clean frame beside it is a take to film again —
retakereasonfilmed-ghost. Since 2.43.0video-cycle-aligndelivers a filmed ghost only where the source frames on both sides of its time are ghosts too, and said so in a warning line alone: the loop'sretakestayednull, so a pipeline that films a direction again onretakedelivered the ghost. Such a loop is now named: its row'sretake(and the report's, andvideo-set's) readsreason: "filmed-ghost"withghost— the cellskept, their frames ofcycle.source/(sources), the highest reading (ghost_max) and the screen'slimit— andlimits.ghost_kept_min(one cell,align.RETAKE_GHOST_KEPT_MIN), with a line "film this direction again (filmed-ghost) — …".retakestays one object:reasonis the first that applies (held-drawings, thenfilmed-ghost), the newreasonslists every one (["held-drawings"]for a held loop as before), and the held numbers stand only where that reason applies. Eachghost_atcell that keeps its ghost says why (kept:no-clean-frame, under any--between, orbetween-rifewhere--between rifekept it beside a clean frame — the aligner's choice, not counted). The set is aligned as before (applied: true, exit 0). Docs:docs/loop-repair.mdsection 4 (filmed ghost),docs/video-pipeline.md. - Fix: a made frame given way at a cell that keeps its ghost no longer says the nearer source frame settled it. Its line said "so the nearer source frame was taken there" where that frame was itself a filmed ghost, delivered for want of a clean one; it now says "the nearer source frame, a filmed ghost, was kept there, the frames beside it being filmed ghosts too". A ghost
--between rifekept with no clean frame beside it is named "film this direction again", no longer told to align withautofor a clean frame that is not there. - Output change: a walk delivered as cut gives its filmed ghost way —
video-loop's jump repair stage. A walk filmed in one direction never meetsvideo-cycle-align, which takes a clean frame beside a filmed ghost, so its strip, GIF and WebP delivered the ghost as cut: 2.43.0 named it in awarning:line and changed no pixel, and only a band wide enough to read as a jump was replaced, by the jump repair, by chance. The ghost screen now reads the cut as filmed, before the jump repair (ghost_screennames a ghost the repair replaced, where it was read after it before), and each ghost it names is a round of that repair, first and outside its three-call budget (why: "ghost"; the jump rounds now saywhy: "jump"): RIFE's frame between the two frames beside it where both are clean and the frame has no fault (taken: "rife"), else the clean frame beside it — the one after, else the one before, the alignment's own choice at a time on a ghost (interpolation_quality.clean_beside,taken: {"source": k}) — else, both being filmed ghosts too, the ghost kept (taken: null). A ghost round also recordsneighbours,outcome(accepted,given-way,kept) andno_proposalwhere no frame was made. A cell given way is injump_repair.replaced, so the jumps are read after it and never made beside it, and the source projection reads it as a repair hint. The seam gate reads a cell given way to the frame beside it as filmed (seam_as_filmed, frames of the cut): that frame shown twice in a row is a step of nothing and a step of two, and at the wrap — a ghost at the cut's first frame given way to its second, or at its last given way to its first — the step of two would refuse a walk that closes ("the cycle does not close") and the step of nothing would pass a cut that does not. A loop that only gave its ghosts way to the frames beside them is gated on its source frames (seam_measurement: source-frames, as filmed); one with a frame made — RIFE's, for a jump or a ghost — on its rendered cells, the cell given way read on the strip the cut makes with that frame as filmed.--anchor body'sseam_ratio_after_anchorreads the wrap the same way. The report and its summary carryghost_given_way(frame,ghost,taken) andghost_kept(frame,ghost), and the strip metadata each where it is not empty —cycle/is the alignment'scycle.source/, whose screen no longer sees a ghost given way, so an alignment carries the record over. Awarning:line names each ("… a filmed ghost; given way to RIFE's frame between frames 9 and 11", "given way to frame 11 beside it, shown twice in a row", "kept … — film this direction again"). Without RIFE,--repair autostill gives each ghost way to the clean frame beside it and says a jump frame was not repaired only where a jump was left (unmade: the step, target and score the jump search stopped at;repair.repair_jumpswith no interpolator no longer raises on a jump);--repair onrefuses a ghost between two clean frames as it refuses a jump.--repair offand the states other than walk and run are unchanged. A loop with no filmed ghost is cut as before: the same cells and strip metadata, its report adding the two records empty. docs/loop-repair.md section 2. - Fix: a GIF or WebP that holds a frame shown twice in a row passes its check. Both formats hold two identical frames in a row as one frame of twice the delay, and
video-loopchecked its GIF and WebP for one frame per cell: a cut with two identical frames in a row — what giving a ghost way to the frame beside it leaves — failed (walk.gif failed verification: 19 frames, expected 20).video-loopandvideo-follownow check for one frame per run of identical cells, asvideo-cycle-alignalready did (loop.shown_runs), and the restoration's playback check (playback.verify) reads such a run as one frame held for the sum of its delays (in hundredths of a second in the GIF, as it stores it); itsstrip_indicesstill lists every scheduled cell. - Output change: source restoration reads the ghost — the ghost guard. A cell
video-loopgave a filmed ghost way is a cell the jump repair replaced, and its source frame is the ghost: the source's pixels clear any fault the cell carries, the smear and outline faults measure a frame only against its neighbours, and partial coverage was read only beyond the source reference's own, which is the ghost — sosource-restoration-v4could propose the cell and accept the ghost back. Now no cell whose source frame the cut's ghost screen names (interpolation_quality.ghost_screenon the cropped source frames, at their own size, as the cut read them) is a target; every final cell's faults carry its own ghost reading where the screen reads the loop; and the comparison's newaxes.ghostreads each cell's ownrife.ghoston final pixels (baseline,candidate,reference,threshold0.003,filmed— the screen), any rise of the excess over the limitregressedwithghost:regressed. A loop the screen does not read is not judged (reason: "loop-drawn-part-covered"). docs/loop-comparison.md. - Contract versions: repair report schema 4, comparison schema 6, metric
source-restoration-v5, policykey-protected-source-copy-one-step-cap-jump-ghost-guard-v1. A restored cell's pixels are made as in v4. Evidence and receipts ofsource-restoration-v4(2.40.0 – 2.43.0) are refused, never read as v5: a v4 repair report given tovideo-loop-compareis an input error, and a request whose baseline carries a v4 receipt in its loop report is sharedunknown,restoration-receipt-policy-unsupported. The origin itself is still a valid first request. Proposal IDs change with the versions.video-loop-comparewithout the origin and the source (same-sample-defects-v1) is unchanged. tests/video/test_ghost_given_way.pydraws the walk oftests/video/test_cycle_align.pywith a band of 0.3 coverage beside the foot: a small one, four times the ghost limit and no jump, delivered as cut before and now given way to RIFE's frame between its neighbours (a stand-in that draws the walk's true frame) or, without RIFE, to the frame after it, the GIF and WebP holding it as one frame; two identical frames in a row passing the check; three ghosts in a row, the middle one kept and named; a wide band that also reads as a jump, named by the screen read before the repair;--repair offand--repair onwithout RIFE; an alignment reading the cut given way and carrying its record; with the default seam gate, the walk cut where its wrap is an ordinary step, its ghost at the cut's first frame given way without RIFE or with RIFE's frame a ghost too (refused before, 2.17 times the mean step), at its last given way to its first (read 0.0 before), both beside a frame made, ghosts at its first and last frames at once given way inward (refused before, 2.40), and a cut that does not close whose last frame gives way to its first (delivered before), under--anchor noneand--anchor body; under--anchor body, the walk's default, the strip'sseam_ratio_after_anchorreading a ghost given way at the cut's first frame, its last or both as--repair offreads it (read oncycle/before: 0.0 at the last); the side walker oftests/video/test_one_step_cut.pycut with the application's walk flags (--anchor motion-auto --size-hold auto --body-height 160), through a stand-in and through the real RIFE (markedreal_rife); and the cut's source projection proving every other cell and listing the cell given way, a restoration request reading its playback and proposing nothing there.tests/video/test_source_restoration.pyadds a source frame that is a filmed ghost the smear and outline faults pass, whose cell v4 proposed first: it is no target, and the ghost restored there regresses.tests/video/test_ghost_retake.pyreproduces on the synthetic legs oftests/video/test_ghost_screen.pya ghost kept at a whole time (three in a row), one kept at a time made between two (the stand-in RIFE, and the real one making each frame beside a ghost, markedreal_rife), and a held loop on twos that keeps ghosts too (both reasons,held-drawingsfirst); under--between rifeonly the ghost with no clean frame beside it is counted; the fault line names the kept cell as it is.
v2.43.0 - No loop delivers a ghost frame unmeasured; a cross-fade inside one silhouette is named, not judged
- Fix: no loop path delivers a ghost frame unmeasured —
video-cycle-aligntakes a clean source frame beside it. A video model filming a walk held on twos or threes sometimes leaves a frame half drawn between two drawings: a band of part coverage where a leg was and is going. The alignment took such a frame as filmed at its own time, never measured, and a frame RIFE made beside it carried the band and passed —--between autojudged a made frame only against its two neighbours (dark_excess,outline_loss), and a neighbour that is itself the ghost leaves nothing in excess. Now every frame delivered is read on its own coverage (rife.ghost: part-covered pixels, alpha 0.1–0.9, in regions at least 5 px thick, over the frame's solid pixels; a ghost over 0.3 %,interpolation_quality.GHOST_WARN). The source loop is screened first (ghost_screenper loop row and incycle_align:limit,thick_px, the loop's ownlevel,reads, and each filmedghostsframe ofcycle.source/); a loop whose median frame is over the limit is drawn part-covered (a glow, a translucent cape) and is not judged. Underautoandnearesta time on a filmed ghost takes the frame after it (or before it), a made frame that is a ghost gives way to the nearer source frame (faultghost), and where that nearer frame is the ghost the other frame beside the time is taken;rifekeeps both, named. Each such cell is listed inghost_at(at,source,ghost,taken) with a warning line; a ghost with no clean frame beside it is kept and the line says to film the direction again. A loop already the set's length is screened the same way. Made frames insmearcarry theirghostreading. - The same screen in the other loop paths.
video-looprecords the screen of the cut it delivers for a walk or run (ghost_screenin its report and summary, awarning:line per ghost namingcycle/frame-NNN.png): a loop delivered as cut, never aligned, shows its ghost. The jump repair rejects a proposal that is a ghost, its rounds'originalandproposalcarryingghost.video-loop-compareandvideo-loop-repairkeep their versionedrife.smearmeasures and do not read it. Not seen by the screen: a made frame that blends two drawings inside one silhouette with its outline whole — no part coverage to read; the cross-fade reading below names it. A loop the screen does not read (reads: false, drawn part-covered) is now said on stderr too:video-loopprints awarning:line for its cut (and carriesghost_screenin its summary), andvideo-cycle-aligna line inwarningsper such loop — before, only the report said so. - Named, not judged: a made frame that cross-fades two drawings inside its silhouette. Where the legs trade places across a gap wider than the flow follows, RIFE can move the coverage and cross-fade the colour — both drawings' boots at part strength inside one whole outline. That frame has no band of part coverage, nothing darker inside the body, and loses its outline only where the art outlines in near-black: the outline rule counts pixels under 70/255 as outline, so the same cross-fade outlined lighter than 70/255 (grey, a light brown) passed every fault — caught or passed by the palette's accident.
rife.crossfade(made, a, b, t)reads it relative to the source frames' own edges: in windows 8 % of the body's height where the two source frames differ, pixels at their plain blend at the made frame's fraction (in patches 5 px thick) together with the made frame keeping under 60 % of the sources' strong edges there (local range over 7 px, wider than RIFE's blur) — the strong-edge pixels lost there, over the frame's solid pixels (the windows step by half their size, so one lost pixel is counted in up to four of them). Over 0.015 (interpolation_quality.CROSSFADE_LOOK,looks) a made frame is named to look at:cycle_align.smearrows carrycrossfadeandlook, and a kept frame gets awarningsline ("may cross-fade two drawings inside its outline … kept"). It is no fault —autokeeps the frame and the retake rule does not count it — because checked against frames labelled by eye it does not part them: on synthetic legs over 32 palettes (outline black, brown, grey or none; boots dark, mid, light or none) the colour-blended, coverage-whole frame reads over the line in 209 of 384 (74 of 96 outlined in grey, where the fault rules catch 2; 11 of 96 drawn without outlines) and a clean drawing between two far-apart drawings in 29 of 384. The jump repair takes such a proposal and names it (its round'slook, the proposal'scrossfade, avideo-loopwarning:line).video-loop-compareandvideo-loop-repairkeep their versioned measures. tests/video/test_crossfade.pydraws the outlined legs with boots three times the size, the outline grey or black: a frame whose colour run cross-faded inside the drawing's own coverage reads over the line in both, the outline rule catching only the black; the drawing between reads under it, and a clean drawing between legs 13 degrees apart in grey over it (why it is no fault); the alignment keeps a cross-faded frame and names it, where the black one still gives way to its outline fault; an alignment through a stand-in whose colour run blends names each kept frame in a warning line; the jump repair takes a cross-faded proposal and names it; through the real RIFE, where installed, a short step reads no cross-fade; and a loop drawn part-covered is named on stderr byvideo-loopand in the alignment's warnings.tests/video/test_rife.pypins the real RIFE's whole verdict on the melted crossing (outlineandghostone way,outlinethe other, no cross-fade either way), where it pinned only the first fault.tests/video/test_ghost_screen.pydraws outlined legs with a band of 0.3 coverage between the feet: the measure reads the band and not a softened edge; the alignment takes the clean frame beside a ghost at a whole time and beside a made frame that carries one, keeps it named underrifeor with no clean frame beside it, screens a loop already that long and leaves a loop drawn part-covered as before;video-loopnames the ghost in its cut; the jump repair rejects a ghost proposal; and through the real RIFE, where installed, no resampled cell carries the filmed ghost.
v2.42.0 - A set's directions on one sheet, standing on one ground line; a loop whose strip as cut is missing is refused by name
- New
sprite-gen video-set-sheet: the directions of one set on one sheet, standing on one ground line. Each direction is cut on its own and a strip is the union of its own cycle's bodies, so laid side by side the directions stand at different heights and cell sizes.video-set-sheet --loop-dir <dir> --view <view> …(the views asvideo-cycle-aligntakes them; a strip turned over to face the other way is a direction like any other) writes<name>.sheet.pngand<name>.sheet.json: a row per direction in the compass order S, SW, W, NW, N, NE, E, SE whatever order the loops are given in, a frame a column; one cell that holds every pixel of every cell of every direction, centred on the pivot each strip declares (anchor) or else its bottom centre, so every cell's pivot is its bottom centre; one ground line,baseline_y, the lowest body pixel (alpha 8 and over, asvideo-loopreads a body) of any cell — a fainter pixel, a soft shadow, is kept in the cell below the line and is no body — (a direction whose strip leaves room under its feet stands that much above it, as cut:body_bottom_y); and every row as cut, pixel for pixel — nothing is scaled direction by direction, one size across a set isvideo-loop --body-height's.--center <still>stands a transparent still (the set's base) with its body on the same line at the rows' standing height (the median of theirbody_h, against the still's own asvideo-loopreads one), centred, in<name>.center.png. Loops of different lengths, in frames or frame time, are laid all the same, the shorter rows' last cells empty, withsame_length: falseand a warning. The record carriesorder,columns,cell_w,cell_h,baseline_y,anchor,same_length, per row itscode,view,frames,delay_ms, stripname,input,strip_sha256,body_handbody_bottom_y, and the centre'spng,input,sha256,standing_h,body_h,scaleandbox. A direction given twice, a front or back view with a side, a--viewcount other than the loops', a loop directory without one strip and its sidecar, an opaque centre still and a centre beside rows withoutbody_hare refused before anything is written. The loop directories are only read. Every other verb writes what 2.41.0 writes. docs/video-pipeline.md. tests/video/test_set_sheet.pylays synthetic strips of different sizes, one standing above its strip's bottom and one with a declared pivot: the rows come out in compass order from any order given, every cell is its strip's cell pixel for pixel with no alpha lost, the lowest body pixel of any cell is the ground line and the floating direction stands its gap above it, a soft shadow under the feet is kept below the line with no alpha lost, the cell is the bodies' union about the pivot and touches it where they do, and a declared pivot lands on the cell's centre. A sheet laid by hand — every strip centred in one wide cell and stood on its bottom, the ground line the lowest pixel of any cell — is the engine's sheet cropped by one offset, cell for cell, its ground line the same line. A centre still drawn twice the rows' size and wider than them, with a faint shadow, stands its body on the line at the rows' median standing height, centred, the cell made to hold it and its shadow. Rows of 12 and 10 frames, or of one length at two frame times, are laid and said to differ; each refusal writes nothing.- Fix:
video-cycle-alignrefuses a loop whose strip as cut is missing, by name, before any loop of the set is touched. Since 2.41.0 a loop's first alignment reads its strip as cut (<name>.strip.png, orfollow.source.pngwhere a follow-through moved it) to recordcycle_align.origin. A loop directory holdingcycle/and itsstrip.jsonwithout that PNG ended in aFileNotFoundErrortraceback, with no report andcycle.source/already copied into every loop of the set. It is now refused as a loop cut beforecell_height_capwas recorded is:video-cycle-align: <loop dir>: no <name>.strip.png — …, exit 1, every loop of the set file for file as it was (undervideo-set, that state's alignment fails and its loops stay as cut). It is still not aligned without its origin, whichvideo-follow --read-oncarries regions by: put the strip back, or cut the loop again. A loop aligned before keeps the origin it recorded and is aligned again without its strip, as before. docs/loop-repair.md section 4. tests/video/test_cycle_align.pytakes the strip out of one loop of a synthetic set: the refusal names it, and both loop directories are as they were, with nocycle.source/and no report. A loop aligned once is aligned again without its strip, its origin kept.
v2.41.0 - Regions read on the cut follow the loop aligned from it, cell for cell; a floor on the stretch, by direction and never above the fold rule; the bend and the seam written down
- New
video-follow --read-on <sha256>: the strip the regions were read on, and the reading carried from it. The regions of a follow-through are where somebody looked, in the first cell of the strip they were read on.video-cycle-alignturns a loop to start on a foot strike, so its first cell is another, andvideo-followgiven the same regions read the motion again from that cell 0: the regions landed on another place of the body, and a stretched loop moved them by a motion read anew.--read-onnames the strip they were read on by its file's sha256 (as cut, before any follow-through). This loop's own strip as cut issame: the follow-through is the one without the flag, byte for byte. The cut this loop was aligned from istransported: each cell is carried by the cut's reading of the cut's cell it is, the regions stay on the cut's cell 0, and the damped mass is solved on the loop's own order, length and frame time — a turned loop gives the cut's follow-through cell for cell, a loop stretched by the nearer frame the new cycle's offsets on the cut's motion. A cell made between two frames of the cut, or one that is not the cut's cell pixel for pixel (a crop or a scale changed and nothing records how, or a cell drawn again), is refuseduncertain: a made cell has no reading of its own, and none is taken from the nearer frame by rounding (a cut made before its strip recorded its crop is judged by its cells' pixels alone). Any other strip is refusedno-match. Without--read-onnothing of this is read or written and the record holds no new key; with it the record carriesread_on(sha256,relation, and fortransporteditspolicyandcut_cells).video-follow-inspecttakes it too. docs/video-pipeline.md. - Output change:
video-cycle-alignrecords the cut it aligns from and where every cell is from.cycle_align.cells_fromholds, per cell of the rebuilt strip,{"source": i}(frame i ofcycle.source/, as many times as it is taken) or{"between": [i, j], "t": t}(a frame made between two); the report's loop rows carry it too. The first alignment of a loop also records the strip as cut, read before anything is rewritten (cycle_align.origin: its file's sha256 —follow.source.png's where a follow-through had moved it —, cell size, scale, crop origin,sample_indices, each cell's pixels by sha256, and the body's motion asvideo-followreads it there), and every later alignment keeps it as it is. The strip, cycle frames, GIF and WebP are unchanged; the aligned meta gains these two keys. A loop aligned before this release has no origin and gets none: its cut is no longer there to read. docs/loop-repair.md. - New
video-follow --stretch-floor D: a least area every moved pixel keeps, read by the way the region moves. The fold rule keeps a region from folding and so lets its steepest pixel take nearly nothing of the source. A move (ox, oy) of a cos² region leaves 1 − (π/2)·hypot(ox/rx, oy/ry) of a pixel's area; each region takes the largest gain, in steps of 0.01, that keeps D in every cell, and never one above the fold rule's — where the direction would allow more (a region moving along its long axis) the fold rule's gain stands, so the floor only lowers. Under it the fold rule's handling stands: a region taken under 1 is held and named, every region held is refused, and--on-fold refuserefuses a move under the floor. It is opt-in with no default value: without it the fold rule alone decides, byte for byte, and a floor the move already keeps draws the same strip, GIF and WebP. The record carriesstretch(policy,floor, per regionper_gain,least_cell,rule_gain,floor_gain,gain,held,least_area,under_measured), and stderr names what lowered a region, the fold or the floor. On an aligned loop, with--read-on, the floor is read on the cut's motion, so a turned loop is lowered, held or refused as the cut is. docs/video-pipeline.md. - Output change:
video-follow-inspectwrites schema 2 — the bend and the seams beside the least area. A move stretches the picture (jacobian_min, D), tilts a line by its steepest slope, |offset|·π/(2·smaller radius) (bend, G, withbend_deg= atan G; the same number asfold_ratio, named for what it does — at 1 a line tilts 45°), and where two regions overlap bends it where the larger move changes hands.cells[k].seamsand the record'sseamsgive, per pair of moving regions that meet, the largest jump of the move's gradient on that curve and its angle (jump,deg, the pointat, thecell); a held region has none.regions[i]adds the largestbendandbend_deg.inputs.settingsaddsread_onandstretch_floor,inputs.policythe names of the ways a reading is carried and a floor kept, both ininput_id; andcarry_basissays what carries a region (outline-lay) and that whose pixels it holds isunverified.video-follow's own record changes only where a new flag is given, and then also carriescarry_basis. docs/video-pipeline.md. tests/video/test_follow_read_on.pyandtests/video/test_follow_stretch_floor.pyuse synthetic strips. A runner turned byvideo-cycle-alignand followed with--read-onis the cut's follow-through cell for cell, and the same turned loop followed as before moves other pixels; a loop stretched by the nearer frame is carried cell for cell, duplicates and all; made cells, a crop that narrowed when a frame was dropped and a cell drawn again are refuseduncertainwith the loop left as it was; another clip and an unknown or malformedread_onare refused; a floor on a turned loop decides as on the cut. Every cell keeps the floor; where the fold rule is stricter its gain stands, where the floor is it lowers; a floor already kept draws the same bytes, and a floor of 0 is the fold rule, not the direction alone. A lowered round region bends a line just under 45°; two overlapping regions record a seam at the point where their weights are equal, its jump the norm of the gradients' difference there. Two strips alike in alpha whose chest patch moves differently are carried alike and say the region is unverified, and an arm added to the outline carries nothing.
v2.40.0 - A restored cell that brings back the jump the repair took out is not an improvement
- Output change: source restoration's comparison reads the jump around the restored cell (
axes.jump). A cell the restoration rebuilds is one the jump repair replaced, because a step into or out of its source frame jumped. The source frame's pixels clear the in-between's melt and can bring that jump back, and the comparison read only the melt.video-loop-compare(and the preview invideo-loop-repair) now scores the final cells of both loops with the jump repair's own step score (repair.jump_scores: per step, the change of coverage over the whole body and over the hair behind it, each over its median in the loop, the larger of the two), on the source cells' union box and with thefacingthe loop report'sjump_repairrecorded. A changed cell reads the larger score of the step into it and the step out of it; more than the baseline's isregressed, reasonjump:regressed, as on every other axis. No bound is read (JUMP_RATIOincluded) and no constant is added: the baseline is the measure. A cell the jump repair made is now restored only where its in-between jumped more than the source frame does, as when it lost coverage; where the in-between was the smoother step and only its drawing melted, the delivered in-between stays. The guard reads coverage, not colour.axes.jumpcarries both loops' step scores and their whole-body and hair parts, the facing, the hair box, the box and, per changed cell, its two steps and both readings. A loop report whose jump repair names replaced cells but no facing (rightorleft) is sharedunknown,jump-repair-facing-unverified; a loop whose repair replaced nothing needs none and stays a no-op. docs/loop-comparison.md. - Contract versions: comparison schema 5, metric
source-restoration-v4, policykey-protected-source-copy-one-step-cap-jump-guard-v1. The repair report stays schema 3, and a restored cell's pixels are made as in 2.39.0. Evidence and receipts ofsource-restoration-v3(2.39.0) are refused, never read as v4: a v3 repair report given tovideo-loop-compareis an input error, and a request whose baseline carries a v3 receipt in its loop report is sharedunknown,restoration-receipt-policy-unsupported. The origin itself is still a valid first request. Proposal IDs change with the versions. scripts/dev/source_restoration_demo.pystill ends with both requestsimprovedand the third a no-op, its 25 checks unchanged: each melted in-between there left the feet a pale ghost, a larger jump than the source frame's. Its stand-in loop report now records the jump repair'sfacing, asvideo-loopwrites it.tests/video/test_source_restoration.py, facing right and left: a restored cell whose source frame stands six pixels to one side of its neighbours clears the melt and isregressedwithjump:regressedalone, while the other proposal staysimproved; a restored cell that gives the steps back the source's reads no higher than the in-between; the axis is the jump repair's own score on the source cells' box. A record without a facing, or with another word, is sharedunknown, and a loop with nothing replaced is still a no-op. Receipts and evidence of v3 are refused.
v2.39.0 - A damaged cell is restored from its own source frame; a faulty in-between is no longer adopted; a follow-through is shown in every cell
- Output change: a jump repair adopts RIFE's in-between only when it has no interpolation fault. In a walk or run loop (
video-loop --repair auto|on), the frame that breaks a jump used to be replaced by whatever RIFE drew between its two neighbours. RIFE's frame is now a proposal, measured against those neighbours withrife.smearand adopted only without a fault: a smear inside the body (dark_excessover 0.001), a lost outline (outline_lossover 0.05) or an empty frame keeps the filmed frame. These are the bounds cycle alignment already used, now one policy for both (sprite_gen/video/interpolation_quality.py). The limit of 3 (MAX_REPAIRS) counts interpolation calls, rejected proposals included; a rejected target is not tried again in that run, and a target next to a frame already made is skipped while an independent one remains, where it used to end the search. The report'sjump_repairaddsattempts,blockedand, per round,target, theoriginalandproposalmeasurements,faultsandoutcome(acceptedorrejected). A rejection keeps the filmed frame and its jump: it is not a verdict on the loop. docs/loop-repair.md. - Output change: a loop records the source it was cut from.
video-loop's report addssource(one sha256 over the ordered keyed PNGs' own sha256s, their count and the fps, read before cleanup, size hold and anchoring),producer(a fingerprint of the measuring code), for a walk or rungait(cut-local silhouette signals,status: "unverified": they do not identify the character's own feet), and under--anchor noneorbodysource_projection(the cleanup recipe, the body ramp and each frame's pixel digest before the jump repair). The strip's meta addssample_indices,source_rect(null under--anchor feet) andsource_cut(the source, the cut's start and length, and the source frame of each cell). The cells, the GIF and the WebP are what 2.38.0 writes but for the jump repair above. - New
sprite-gen video-loop-compare: the loop shown now against a candidate, read from the final files. It reads each side's final strip and meta (aftervideo-follow, if that ran) and its loop report for provenance only, never for a seam score or a pass, and writes asprite-gen-video-loop-comparison(schema 1,same-sample-defects-v1): the sha256 and size of every file as given, a digest of the decoded cells, and per axis the two values and whether they compare. It orders only defects measured at the same source samples, timing, crop and scale: smear and outline loss frame by frame against each frame's actual neighbours, without averaging a worse frame away, and the seam over the native canvas; a worse axis isregressed.improvedalso needs every sample's coverage byte for byte the same, and colour changes only in frames that failed the interpolation bounds and now pass them. Another cut, an aligned strip without a proven source mapping, missing or inconsistent evidence and changed coverage areunknown; equal pixels and timing arenon_regressing, neverimproved; the gait staysunverified. Every verdict,unknownincluded, exits 0; invalid input, disagreeing geometry and I/O failures are errors. An application that replaces a result on its own should take onlyimproved. docs/loop-comparison.md. - New source restoration:
video-source-manifest,video-frames --source-manifest,video-loop-repair, andvideo-loop-comparegiven the origin and the source. A cell the loop report lists as made by the jump repair, which carries a smear or outline fault that the source frame at the same time does not, is rebuilt from that source frame, with no interpolation. In that cell a pixel that differs from the source becomes the source's, unless the source's pixel would raise the key-colour guard there: where that excess is exactly one step that the cell's resample made out of source pixels with none, the source's pixel is written with the keyed channels one step lower and its own coverage; anywhere else the delivered pixel stays, and if that leaves a coverage the source does not have, the proposal endsunknownand writes nothing. Nothing is blended, moved or taken from another frame; the cut, the metadata bytes, every other cell and the GIF and WebP schedules stay as delivered.video-source-manifest(orvideo-frames --source-manifestwith--reference) receipts the clip, the canvas, the frames report, the ordered keyed PNGs and the clip's presentation timestamps.video-loop-repairtakes the current five files (strip, meta, loop report, GIF, WebP), the origin's (the five the first restoration started from; on a first request the same five again) and the source, and writes one candidate into a new--out-dirand a repair report, for one of up to three independent cells (--proposal-index). Every request rebuilds the current loop from the origin and the source and recomputes the receipt kept in the loop report rather than trusting it.video-loop-comparewith the same origin, source and repair evidence measures the five final files again:improvedneeds the one changed cell to be exactly that copy with the source's coverage, a measured fault cleared, no other cell, metadata byte or playback interval changed, and no protected axis worse; key excess is counted per pixel, so less of it elsewhere does not hide new spill. A correspondence the engine cannot prove exactly (legacy evidence it cannot explain, a follow-through, cycle alignment, size hold, motion anchoring) isunknown, not a guess; source, origin or evidence files that are missing or changed are an error. Only a finalimprovedis grounds to adopt a candidate. Repair report schema 3, comparison schema 4, metricsource-restoration-v3, policykey-protected-source-copy-one-step-cap-v1; evidence of the two unreleased drafts (source-restoration-v1,-v2) is refused, never read as v3. The cell resample is unchanged and caps nothing; it now publishes the source pixels each cell pixel is mixed from (resample.mix_windows), which the restoration reads. docs/loop-comparison.md. - A synthetic example, end to end:
scripts/dev/source_restoration_demo.py. It draws a small walker (twelve keyed frames at twice the cell's size, and a clip of them over green for real timestamps) and a stand-in for a delivered loop whose cells 4 and 9 are in-betweens that melted: outline and two-colour belt drawn in the body's colour, feet a pale ghost. From there only the verbs above run:video-source-manifest, twovideo-loop-repairrequests, each comparedimprovedbyvideo-loop-compare, the second on the first's adopted files with the same origin, and a third that is a byte-exact no-op. It ends with an error unless every other cell, the metadata bytes, the GIF and WebP schedules and the origin's files are unchanged, each restored cell has the source's coverage and its outline fault cleared, no key excess is introduced, and the belt's one-step excess, which the resample makes where its two colours meet, is capped in each restored cell. Itssummary.jsonholds no path or time. It is a new synthetic example, not a measurement of any delivered loop; the GIFs below are its two engine GIFs with each pixel drawn 3 × 3. tests/video/test_loop_compare.py,tests/video/test_source_restoration.py,tests/video/test_loop_repair.pyandtests/video/test_strip_resample.pyuse synthetic loops. Identical pixels are neverimproved; an outline restored with the bob kept isimprovedand its inverseregressed; a follow-through is measured from the final pixels; another cut with a better report ratio, a flattened pose and flattened colour motion cannot win. Restoration keeps normal motion and timing, offers the next independent proposal within the budget, is a no-op on a clean loop, refuses forged or changed source receipts and tampered final files, keeps key spill out while restoring the rest of the cell, ends a proposal whose protected pixel has another coverage, caps a one-step excess the resample made and keeps a deeper one or one a source pixel carries, and rebuilds every later request from the origin. A blocked worst jump does not hide an independent one; faulty proposals keep the originals and use the call budget; with the real RIFE (tests/video/test_rife.py) an in-between that loses the outline is rejected and the filmed middle frame kept. The resample's published windows hold every pixel its colour filter mixes, and a mix can carry more key hue than the colours under it.- New
sprite-gen video-follow-inspect: where a follow-through carries each region in every cell, with nothing moved.video-followis given an ellipse in the strip's first cell and carries it with the body into every other; inside the carried ellipse every pixel moves, whatever it is a picture of. For the first cell somebody looked. For the others nobody did: an arm that swings across a chest is inside the chest's ellipse there and moves with it, and so does a sleeve of the chest's own colour, which no count of colours finds. Where the ellipse lies in those cells was written nowhere — the record keeps the body's bob and the strip's rounded offsets, from which the carry cannot be worked back for a strip of more than thirteen cells, and--boarddraws two cells.video-follow-inspecttakesvideo-follow's arguments (all but--board), reads the strip as cut and solves it with the same code, and writes into--out-dirfollow-inspect.jsonand two boards of every cell. The record has, per cell, how far the regions are carried (carry_px, whole pixels) and per region the carried ellipse, its own offset and reach, how near that is to folding it, the least area of the source a pixel of the moved cell takes (jacobian_min: 0 where the picture stops and one line of the source is drawn across many — a region lowered by--on-fold loweris drawn nearly stopped where it moves most, not folded and stretched), the pixels the ellipse covers and how many are body, and the pixels the move changes; per region its gain and whether it is held; and the follow-through asvideo-followrecords it. It names what it was read from: the strip's and the meta's sha256, the regions, the settings, the way the motion is read (follow.POLICY) and the engine's version, andinput_id, one sha256 over those — the same before and aftervideo-followis run on the loop, another after a new cut, an alignment, a changed region or setting. It holds no path and no time: the same loop asked the same way writes the same record byte for byte.follow-inspect.source.pnghas the cells as cut andfollow-inspect.moved.pngthe cells asvideo-followwould write them, each region's carried ellipse ringed just outside it; they are two files so that whoever says what is inside an ellipse can read the cells as cut alone, and each has apixels_sha256over its pixels beside its file's. The engine does not read what is inside an ellipse and does not guess it: every region isownership: "unknown"in every cell, from its centre to its rim, andvideo-followstill moves every cell. The loop directory is only read — not the strip, not its meta, not thefollow.source.pngthatvideo-followkeeps — and an--out-dirat or under it is refused; whatvideo-followrefuses, the inspection refuses in the same words under its own name.video-followwrites what 2.38.0 writes: strip, GIF, WebP, record, printed summary, messages and--help, byte for byte. Its body is nowfollow.read_request(the request, read and checked),follow.solve(anAnswer: the motion, each region's gain, every cell's move) and the writing, and the inspection reads the first two;follow.move_fieldandfollow.region_weightare the move and the weightmove_regionsdraws with. docs/video-pipeline.md. tests/video/test_follow_inspect.pydraws a figure whose head and torso sway by whole pixels, across once a cycle and down twice: the carry of every cell is the sway as drawn, and the ellipse is carried by it. The record'sfollowis whatvideo-followthen writes to the strip's meta; every pixelvideo-followchanged is inside the carried ellipse the record gave, counted alike; each cell is on both boards at its box, as cut and as written, with the ring only on the board pixels just outside the ellipse. Three regions take a gain each, and the one held is carried and ringed and moves nothing; regions given in the other order keep their numbers and swap their places. The loop directory is the same before and after, byte and time, as cut and after a follow-through, and a loop inspected first is followed byte for byte as one that was not. The same loop asked twice writes the same three files; aftervideo-followthe id is the same; a cycle turned by one cell, one more pixel in one cell, another delay or another key in the cut's record is another id; so is each of gain, freq, zeta, on-fold and every number of a region, and not the boards' scale or columns. Whatvideo-followrefuses is refused in the same words and writes nothing. The least area is the steepest of the weight along the move, to 0.05, and under 0.15 for a region lowered to its limit. A forearm of the torso's own colour across the chest in five cells leaves the carry and the record'sfollowas the bare figure's, is on the board of the cells as cut inside the ring, moves with the chest on the other board, and is marked in no cell.
| As delivered: cells 4 and 9 are melted in-betweens | After two video-loop-repair requests, each compared improved |
|---|---|
v2.38.0 - A body that is not one person stands square from behind and walks from behind without turning
- Output change: a body that is not one person stands square from behind, and walks or runs from behind without turning. With
--body-plan(a quadruped, a body without legs, a scene of several figures), the back still's view sentence (STILL_VIEW_TEXT_ANY_BODY["back"], read bystill_view_textandgen --direction back) now also says the body is square to the viewer and symmetric left to right: the back of the head centred above the body, neither side showing more than the other, any tail rising from the middle. A walk or run seen from behind says, after what the body stands on, that it stays level, square and straight the whole time, never turning or angling to either side so neither side comes into view, and does not sway from side to side, any tail held raised where it is with only its tip swaying (BACK_GAIT_TEXT_ANY_BODY; for a scene, every figure), in the built-in sentence and after a caller's--motionalike. A four-legged back still drawn from a three-quarter reference had come out turned, its head to one side and its tail to the other, and the walk filmed from it turned further until a flank showed and swayed; with both sentences the still was drawn straight behind and the walk held square. A person's prompts are unchanged, byte for byte; the front, side and diagonal views and every other state are unchanged. tests/video/test_body_plan.pyholds the horse's back still and back walk as written, and checks that the square sentence comes after what the body stands on in a walk or run seen from behind, for a quadruped, a body without legs and a scene, with the built-in sentence and a caller's paragraph, and in no other view or state and in no person's prompt.
v2.37.0 - A lead-in or a stray speck no longer costs a walk its loop; follow-through reads the body and moves each part on its own gain; a diagonal still turns its body; the same cut on every machine
v2.36.0 was cut but not published on its own: its release was held for a cut that differed by machine, fixed here. This release is the first to carry its changes too — see v2.36.0 in CHANGELOG.md.
Output change: a diagonal still turns its chest or back and its legs, not only its head (
STILL_VIEW_TEXT["front_diagonal"],["back_diagonal"], read bystill_view_textandgen --direction; an app that draws its own still takes it too). The sentences said the turn, the head and the feet, and a still that turns only its head and shoes, the chest (back) and the legs standing as from the front (straight behind), meets those words. They now say what that angle shows: not a front (back) view with only the head turned, the middle of the chest (back) and of the waist about three quarters of the way across the body toward its far edge, the near shoulder and side seen broad, the far shoulder and arm partly hidden, the legs at the same angle with the far foot set a little higher and partly behind the near leg, and not to follow a reference picture's angle.STILL_VIEW_TEXTtakes{other}, the side opposite{facing}(the near side of a front diagonal, the far side of a back one); facing left is the same sentence with the sides swapped. The clip's view sentences (VIEW_TEXT,VIEW_MOTION_TEXT,GAIT_HOLD_TEXT) and the body plan's (STILL_VIEW_TEXT_ANY_BODY) are unchanged. The words were chosen by a before-and-after comparison on the still model; its measurements are kept in private evidence and none is recorded here (video-pipeline).tests/video/test_video_pipeline.pyholds both diagonal still sentences, facing right and left: the chest (back) and hips turn with the head, where the middle of the body sits, the near side broad, the far shoulder, arm and foot on the far side, the reference picture not followed, and facing left the same sentence with the sides swapped.tests/gen/test_prompt_freeze.pylists the two 2.22.0 sentences and the words measured in their place (MEASURED): the still prompts that hold the old words are compared with the measured ones, those prompts and no others differ from 2.22.0, and a measured sentence reworded again fails as any other prompt would.Fix: a key-tinted rim joined to the subject at the edge is the subject. The edge check split its contact pixels by their raw colour alone: the key's hue was leftover background. A body that reaches an edge band brings its antialiased rim there first — hair tips, the crown's outline, the key blended into them — and on a frame where only that rim was in the band,
--allow-subject-edge-contactrefused the clip as leftover background. Each key-tinted contact pixel is now read with the piece of the keyed frame it is in (its opaque pixels, corners joining them, the piecesdrop_specksreads): it isresidualonly when nothing in its piece is off the key's hue — background on its own — andsubjectwhen it is joined to the subject. A frame with such a rim in the band passes with--allow-subject-edge-contactand is recorded as the subject's contact; refused by default, it says the subject was framed too tight, and a mixed refusal no longer counts the rim's frames as carrying leftover background. Key-coloured background apart from the body is refused as before. A clip with no key-tinted pixel in a band, or none joined to the subject, keys and reports as before, byte for byte. docs/video-pipeline.md.tests/video/test_edge_speck_lead_in.py: a body that rises until only the key-tinted rim over its crown is in the top band was refused as leftover background with the subject allowed; now it passes as the subject's contact, and by default is refused as framed too tight. A strip of the key's colour against the edge, apart from the body, is still refused as leftover background.tests/frames/test_chroma_key_relative.py: Grok's magenta in the band is residual cut off from the rest, and the subject's when joined to it.Output change:
video-canvas --shape widegives a walk or run no head-room. A forced-wide canvas gave every state a jump's 35 % above the still, and above a square still that head-room set the width as well (2800 × 1575 for 1024 × 1024, 1216 columns in front of the still); a walker that small in its frame is one a video model may reframe. A walk or run forced wide now has a row of its own (canvas.GAIT_WIDE, read throughSTATE_SHAPE_CANVAS): 28 % in front, 20 % behind, nothing above — 1969 × 1108 for a 1024 × 1024 still. A jump, and every other state forced wide, keeps the forced-wide row (WIDE_OVERRIDE) and its canvas byte for byte;--headroomstill sets the room above. docs/video-pipeline.md.tests/video/test_edge_speck_lead_in.py: a walk or run forced wide is 1969 × 1108 with nothing above, a jump still 2800 × 1575.Fix:
video-loopleaves a walk's lead-in out of the search. A video model may reframe a small subject in a clip's first frames — the body grows or shrinks by a third or more in under half a second, then walks at its new size. Searched with those frames, the motion analysis read the reframing as the clip's motion and lost the walk's repeat, and the gait fallback, scaling back by a line through the clip, read the step as steady growth and shrank the walk. A walk or run's sizes are now read one cycle on (gait_fallback.cycle_drift, the size hold's model) and a clip whose first frame's height and size (the square root of the frame's coverage) are both off it by 10 % or more, the same way (LEAD_IN_MIN), opens on a lead-in (gait_fallback.lead_in) that runs while the height stays that far off — a reframing scales the whole body, a pose such as an item held up from the second frame on changes the height alone;--cycle autoandperiodic— the size hold, the motion analysis, the cycle search and the gait fallback — read the clip after it as a clip of its own, window included. Every frame number the report gives is the clip's own:cycle.start, each candidate'sstartandcontext_pair_range, a refusal's windows too, so--cycle fixed --starttaken from them cuts the frames they name. Every walk and run report gainslead_in(frames,height_change,first_off,first_off_size,min,method,search_from); a clip too short to read its size one cycle on has none (why). A cut the caller names (fixed,pinned) is the caller's frames.cycle.coveragecounts the frames the search read. The gait fallback now scales back by the size read one cycle on, as the hold does, so a first pose settling into the walk no longer hides a body that grows from it (gait_fallback.scale_driftgainsmethod: one-cycle-onin the report); a clip that reaches the fallback with 3 % or more of change is scaled by that model now, and its pixels and the drift its refusal quotes can differ in the last places. A walk or run with no lead-in that the first search cuts is cut as before, its strip, GIF, WebP, cycle frames andstrip.jsonbyte for byte. docs/video-pipeline.md, docs/loop-review.md.Fix:
--body-heightreads the standing height on the cut's first frame where the cut is filmed at another size than the clip's first. The clip's first frame is the still's pose as filmed, but a video model may reframe the subject after it, by a lead-in or by less, and then the walk is filmed at another size than that pose: read there, the standing height scaled a walk after a lead-in up into the cell cap, and delivered a walk reframed by 7 % over its first frames 7 % too large. A walk or run cut for a--body-heightnow has its size read against the first frame's (gait_fallback.size_change) on three lengths at once — the height, the mass (the square root of the summed coverage) and the breadth (the widest row of the upper half of the body), each the middle of the cut's frames over the first frame's. A pose moves them apart (a walk is shorter than its standing pose and broader; an item held up is taller and no heavier) and a reframing moves all three the same way, so the change is the least of the three when all go one way and none when they part. At 1 % or more (SIZE_HOLD_MIN) the standing height is read on the cut's own first frame, andstrip.jsonsays so (body_ref: cut-first-frame,body_ref_frame, the clip frame);video-cycle-alignrebuilds such a strip at the same height. The report gainscut_size(change,height,mass,breadth,min,method) on every walk and run cut for a--body-height. A cut the size of its first frame reads the first frame as before, and its strip, GIF, WebP, cycle frames andstrip.jsonare as before. docs/video-pipeline.md.tests/video/test_edge_speck_lead_in.py: a walker filmed at 0.63 of its size and reframed over 9 frames: a lead-in of 5 frames, found no cycle before, now cuts its 24-frame walk after it, every frame number its own; one filmed at 1.3 of its size has a lead-in too, and one that holds an item up from its second frame on has none; too slow a walk after the same lead-in is refused with windows that all start after it; a fixed cut there reads its standing height on its own first frame, andvideo-cycle-alignkeeps it; a walker reframed from 0.93 of its size, or from 1.07, opens no lead-in, and a fixed cut after it read the first frame's height (7 % too large or small) and now reads its own first frame's; a first pose that settles into the walk, an item held up from the second frame on and an arm swung out are each read as a pose, on the first frame. A walker that settles from its first pose and grows 5 % reads 2.8 % on a line and was refused; read one cycle on it is scaled back and cut.Fix:
video-frameserases a speck far from the body before the edge check. A fleck the model drew drifting across the background survives the matte as a few pale pixels; where it crossed an edge band in one frame, the edge check read it as the subject framed too tight and refused the clip, andvideo-loop --anchor motion-auto, which never cleans a frame, kept it in the loop and widened every cell to reach it. Now every keyed frame has its specks erased before anything reads it (frames.drop_specks): a piece of the frame — its opaque pixels, corners joining them — under 1 % of the body (SPECK_MIN_FRACTION, at least 8 px) and more than a tenth of the body's height from it (SPECK_APART). Small pieces near the body are the subject's own and stay: the outline's loose pixels, a shadow drawn under a shoe, a part of a shoe the matte cut loose. Each report row gainsspecks, how many its frame lost, and the reportspecks(dropped,framesand the rule's numbers); a frame with no speck is not written again, so its bytes are as before.video-loop's own pass on a cut that is not motion-reviewed (--anchor none|feet|body) erases every island of solid pixels under the same 1 % as before, pixel for pixel, through the same function (a run-based labelling, about twenty times faster than the pixel-by-pixel search it replaces). docs/video-pipeline.md.tests/video/test_edge_speck_lead_in.pykeys a body on magenta with five pale pixels in its right edge band in one frame: before this the frames were refused as framed too tight, now the fleck is erased (specks: 1) and no frame touches the edge; a shadow under the feet, a loose pixel by the outline and a far block too large to be a speck are kept;video-loop's own reading still erases the loose pieces. A walker on magenta with a fleck drifting far from it, keyed and cut--anchor motion-auto, is cut 49 px wide, the walker alone (147 px before).Output change:
video-followreads the body's motion off the body, not off whatever is at its top. The motion was the top row of the silhouette and the middle of the band under it, so whatever came to the top was the body: a tail tip rising over the head, a flopping ear, a ponytail, a sword or a rod held up. Where such a part took the top in some cells and not in others, the read jumped by the part's whole swing from one cell to the next; where it held the top, the bob was the part's own swing. The follow-through then answered the tail, the ears or the weapon, the region was carried off its part, and large parts were refused. Now each cell is laid where its silhouette, worn down by every whole number of pixels from a quarter to half of the first cell's depth, overlaps the first cell's, worn alike, most: the overlaps of every level summed, counted in whole pixels (the FFT's rounding is gone, so the same strip reads the same on every machine), a tie going to the smaller move. What swings on the body and is thinner than it is worn away, the deepest of the body counts most, and a torso that is shallower in one cell (an arm swung away from it) still counts. A part as thick as the body outlasts the wearing — ears as wide as the head — and a cell that has it elsewhere than the first cell does, laid on the first cell alone, lies ears on ears with its body tens of pixels off, so the read jumped there too. The cells are therefore laid twice: laid on the first cell, each is moved back by its lay and the cells are counted — per level and pixel, how many more of them are in that level there than are not, and none where no more are — and each cell is then laid on that count the same way; its lay less the first cell's own is the motion. The head and torso are at one place in every cell and count in full; ears up in some cells and flopped onto the face in others, or a leg forward and back, are at any one place in half of the cells or fewer and count nothing. A thick part that keeps one place in most of the cells is body to this read, which sees outlines only. Every follow-through moves differently, the strips whose top is the head included — no strip is written byte for byte as before: the head nods and leads the torso, and the read is now the torso's. The record gainsbody_worn_px, the first and last level the silhouette was worn down to. A cell with nothing in it a quarter as deep as the first cell's body is refused:video-follow: cell <k> has no body as deep as a quarter of cell 0's (<px> px); so is a strip with no part of the body at one place in more than half of its cells:video-follow: no part of the body is at one place in more than half of the cells. Reading the motion is two lays of every cell: on an Apple M1, one thread, 0.5 s for 24 cells of 210 × 240 px, 16 s for 24 cells of 630 × 720 px (11 s for one lay), and 110 s for 64 cells of 700 × 700 px around one disc 640 px across (58 s for one lay). docs/video-pipeline.md.tests/video/test_follow.pyfollows a chest on a walker with a thin tail whose tip swings over the head, and on one holding a sword up and swinging it over the head: the record (bob,dx_px,dy_px, reach, gain, fold) and the chest's moved pixels are the bare walker's. Before this, the chest was refused on both: the read made the move at gain 1 20.8 and 17.5 px, so the chest could take no more than gain 0.52 and 0.61, where on the bare walker it moves at 2.5. A strip with a cell no deeper than a line is refused untouched. It also follows a chest on a bunny whose lop ears, more than half as thick as its body is wide, swing down and back up once a cycle: the record and the chest's moved pixels are the earless bunny's. Laid on the first cell alone, the body was read as dropping with the ears by up to 30 px in 8 of the 24 cells and as jumping back in the next, and the chest was refused (a move at gain 1 of 16.1 px, no more than gain 0.94). A strip whose cells share no place — a bar, and in each other cell a block at a different place along it — is refused untouched.Fix:
video-followreplaces the loop's files only once all of them are written. The strip, the GIF and the WebP were written over the loop's before the record was, so a run that failed on the record —follow.follow_loopgiven numpy numbers, an int64 of which has no JSON form (TypeError) — or on an animation's check left a moved strip beside a record that did not say so. Now the strip, GIF, WebP and record are written and checked in a scratch directory beside the loop (.follow.*), each under its own name, and moved over the loop's files after the record is written; a run that fails on the way leaves all four as they were (the strip as cut is still kept asfollow.source.png, as on a refusal).follow_loopreads its regions,gain,freqandzetaas the floats the command line gives, so numpy numbers, or plain ints, write the strip and record that the same numbers as floats write, byte for byte (a caller that passed plain ints finds them recorded as floats,80.0where it was80).loop.verify_animationcloses the file it checks. The command's output, its strip, GIF, WebP and record, and--helpare as before, byte for byte. docs/video-pipeline.md.tests/video/test_follow.pymoves a chest and a smaller head region given as int64, int32, float32, float64 and plain int coordinates, as the rows of an int64 array, and with a float32gain: each writes the strip, GIF, WebP and record the float coordinates write, byte for byte (before this the int64 run failed on the record with the strip already moved). A run made to fail on its record or on its WebP's check, on a loop as cut and on one already followed, leaves the strip, GIF, WebP and record as they were, and nothing beside them butfollow.source.png.Output change:
video-follow --on-fold lowergives each region a gain of its own. One gain for the strip, set by the region with the smallest radius, let the smallest ellipse decide for every part: a small one (an ear) lowered a large one (a chest) to its own gain, and where that gain went under 1 refused the whole strip, so the chest did not move either. Now a region that folds at--gaintakes the largest gain that does not fold it (in steps of 0.01), a region that does not fold keeps--gain, and one that would have to go under 1, the mass as measured, is held: it does not move, and stderr names it by its--region(video-follow: --region <cx,cy,rx,ry> folds at --gain <g>, under 1 (the mass as measured): it is held, and does not move); a region lowered while another keeps its gain is named the same way (video-follow: --gain 2.5 folds --region <cx,cy,rx,ry> (a move of <px> px); lowered to --gain <g> for it). The strip is refused only when every region is held, and that message names the largest region (… folds a region of radius <r> px over itself (the largest of <n> regions: every one folds), and --on-fold lower would have to go under --gain 1 …); with one region it reads as before. Where regions of different gains overlap, the larger move wins (follow.move_regionstakes groups of regions, each with its own offset), and the move there is nowhere steeper than either region's own. In the record eachfold.regionsentry gainsgain(0 when held) andheld, the strip'sgainis the largest any region moved by (dx_px,dy_pxandreach_pxare that gain's),fold.ratiois the nearest any region came to folding andfold.loweredsays whether any region was lowered or held; the printed summary gainsregion_gains. A strip whose regions all take one gain — one region, regions that fold alike, or none that folds — is written as before, strip, GIF, WebP and record byte for byte.--on-fold refuse, the default, is unchanged. docs/video-pipeline.md.tests/video/test_follow.pymoves a chest with a region on the head too small to move at gain 1: before this the strip was refused, now the head region is held and the strip is the chest's alone, byte for byte (and at--gain 0.9the chest still moves at 0.9). A head region that folds at 1.75 beside a chest that does not fold takes 1.75 while the chest keeps 2.5, each region's pixels those of the region moved alone at its gain; a small region inside a larger one folds nowhere; a strip whose every region is held is refused untouched; two regions that fold alike are written with the one-gain record and the strip their gain asked for gives; the command names the region it lowered and the one it held.Fix:
video-loop --anchor motion-autoreads the same motion from the same pixels on every machine. A patch of its region search that sits on a flat fill matches equally at several offsets; the FFTs that score them round differently between numpy builds (about 1e-14), and that rounding chose the offset. From the same frames a synthetic walk was tracked differently on Linux than on macOS, its distance matrix differed in most entries, andtests/video/test_loop_prop_seam_held.pyfailed on CI only (first choice popping 2.4 there, 11.7 on macOS). Now costs within 1e-9 of the lowest are one match (auto_motion.MATCH_TIE) and the offset nearest the centre the search was put on is taken; regions whose qualities tie on that grain are ranked by their box; and the drift lines that move the analysis frames are least-squares lines with exactly rounded sums (auto_motion._line, nowsprite_gen.util.lsq.line), notnp.polyfit, whose LAPACK solve rounded differently and tipped bilinear samples of those frames. The tracked offsets, the analysis frames and the distance matrix are now bit-identical on macOS arm64 and Linux x86-64; only the last digits of reported costs and scores differ. Footage whose patches never tie is cut as before: the same regions, offsets and cut, its analysis translations moved only in their last bits (about 1e-14), which can tip a bilinear sample and move a score in its sixth decimal. Drawn, flat-filled frames, where ties are the rule, are tracked — and may be cut — otherwise than v2.36.0 tracked them on any one machine.tests/video/test_auto_motion.pyperturbs every FFT correlation by up to 1e-12 of its largest value, seed by seed: the tied offset taken on the flat torso, the regions found and every tracked offset are the same under all of them (under v2.36.0 eight seeds took six offsets, 14 px apart, and four seeds found four different region pairs), and the drift line isnp.polyfit's to 1e-12 and bit-identical in any order of its points.test_a_held_part_that_swings_with_the_step_is_cut_one_step_longdraws its pennant on a 53-frame beat (phase 0.75): its first choice pops 12.6, no other candidate's top over 8.5, the cut taken closes below the hand at 0.0; on v2.35.0 with this fix it fails where v2.35.0 reads nothing below the top.Fix: the size hold and the gait fallback of
video-loop --anchor motion-autoscale the same frames on every machine. Both scale every frame back about a foot point read off a fitted line, and size the room the frames need from it. The line wasnp.polyfit's, whose LAPACK solve rounds differently between builds (Accelerate on macOS, OpenBLAS on Linux; on the 10-05 synthetic grid their lines lay a few 1e-13 px apart). Feet that stand on the frame's bottom edge in every frame sit exactly where that rounding decides: on a synthetic walker growing 3 %,np.polyfiton Linux put them 4 units in the last place past the edge, and with its coefficients moved by up to 1e-12 of themselves, four seeds in eight gave the frames 2 px of room below and four none — another frame size, and so other frames for the cut search. The lines are now least-squares lines with exactly rounded sums (sprite_gen.util.lsq, the lineauto_motionalready drew its analysis drift with, moved there): feet on the edge read exactly the edge, and the foot point, the room and every held pixel are the same under any rounding. A clip the hold leaves as filmed and the fallback does not scale is cut as before.tests/video/test_gait_fallback.pyholds a synthetic walker whose feet stand on the frame's bottom edge withnp.polyfit's coefficients moved by up to 1e-12 of themselves, seed by seed: the foot point, the room and every held pixel are the same under all of them (under v2.36.0 eight seeds gave eight foot points and two paddings); a walker that neither moves nor grows reads its box's foot point and height to the bit.tests/test_lsq.pychecks the line againstnp.polyfitand in any order of its points (moved fromtest_auto_motion.py).
v2.36.0 - A slow walk cut one step long is named, and cut again on a count; a staff that closes only on two steps is cut as one cycle
Not published on its own: it ships in v2.37.0.
- New record:
cycle.step_screenon every walk and runvideo-loop --anchor motion-autocuts. A walk slower than its window holds (0.5 to 1.6 s, at most half the clip) is cut one step long where its legs are drawn alike: the step repeats in pixels, the loop walks on one leg, its arms jump at the wrap, and a set aligned with it plays one step where its other directions play two. Nothing said so — the two-cycle screen looks only below the cut. Now the cut is screened the other way, over the whole clip (period.step_screen): the lag within 3 frames of twice the cut that repeats best (lag,searched), its distance over the cut's own over the same frames (ratio,pairs), its dip under the clip's profile (depth), how much of a second cycle the clip holds past it (coverage), and the step signal's peaks over the cut (leg_peaks, a record only). A repeat there (depthat least 0.15) better than at the cut (ratioat most 0.85,period.STEP_RATIO_MAX) is asuspect. Nothing is cut on it: a cycle on a frame count that is not whole repeats better at its double too, so only a count of the steps settles it. Images,strip.json, warnings and stderr are as before, byte for byte; the report'scycleand the printed summary gainstep_screen. docs/loop-repair.md. - New option:
video-loop --steps 1|2(with--anchor motion-auto), the count of steps in the cut it takes without it, from whoever looked at the loop.1cuts the walk again in the window [2L − 1, 2L + 1] — not bounded by half the clip, but held inside an explicit--min-len/--max-len(below) — with the same search, the equivalent cut whose wrap the clip itself plays taken (choice: "closure") and no window twice that; a clip too short to see that window repeat is cut all the same, the count standing for the repeat (method: "counted-window-v1",unseen).2keeps the cut. Either waycycle.stepsrecords the count (by: "given",given, and for1first_cutandwindow),strip.jsonsayssteps: 2, andcycle.coverageis (n − L) / L. New warning: a cut two steps long whose clip holds under 0.25 of a cycle past it (loop.COVERAGE_MIN) —the cut is two steps long (… frames, one cycle) and the clip holds … of a cycle past it (under 0.25): its repeat is barely seen — the seam says whether it closes; a longer take shows it repeat. It is cut, not refused; the seam gate judges it. - Output change: an explicit
--min-len/--max-lenwindow is the window, on every path that sets a cut's length.--anchor motion-autocut the caller's ceiling back to half the clip, so asking for a slow walk's cycle (--min-len 41 --max-len 43on 73 frames) searched [41, 36] and failed. Only the state's default window is bounded by half the clip now. The window is worked out once (loop.CutWindow) and every search reads its own off it — the first search, a window two steps long, the count (--steps 1), the gait fallback, the one-shot failover — so none sets a bound of its own: the--cycle autoone-shot failover of an action state widened an explicit--max-lento nine tenths of the clip (a 16-frame hop asked under--max-len 14was cut 36 long) and the one-shot search took no--min-lenat all; both are held to the caller's bounds now (detect_one_shothonoursmin_len;run_looppassesONE_SHOT_MIN_LENunless--min-lenis given, so a run without one cuts as before), and a one-shot the bounds leave no room for says so (no complete one-shot return … — in 8-14 frames, inside --min-len 8 --max-len 14). Whatever chose the cut,--cycle fixedandpinnedincluded, a cut outside an explicit bound fails:the cut is … frames long (…), outside --max-len N. A count and a window with no length in common fail:--steps 1on a 21-frame step under--max-len 25cut 42 frames; now--steps 1: the cut of 21 frames from 18 is one step, so the cycle is 41-43 frames long, and --max-len 25 leaves none of that: the count and the window disagree — drop one, or give a window that holds the cycle(exit 1, the failed report'scycle.stepswithcounted_window,window: nullandrefused). Where they share part of the window, only that part is read (cycle.steps.window,counted_windowbeside it). A run with no explicit bound cuts byte for byte as before. - Output change: once the top of the silhouette jumps at its first choice,
video-loop --anchor motion-autoreads the held part below its top too, and may cut two steps long — one cycle. A staff turns about the hand as the arm swings, once a cycle; one step on it is back in place at the top band moving the other way. Where the legs are drawn alike the search takes that step as the cycle: v2.35.0 chose again on the top band alone, took such a cut — the top closed — and the shaft under the hand swung back at the wrap, with no warning. Now, behind the seam pop only, the side of the body the top band sits on is read row by row on the silhouette's outer edge (repair.held_side,repair.side_edges,repair.held_edgeon the frames the search chooses from,loop.HeldEdge): per row, the cut's first and last frames against the clip's frames after its last and before its first, in place and in speed, over the row's median step in the loop; the 80th percentile over the rows is the held seam, closing under 1.2 (repair.HELD_EDGE_REFERENCE). Among the candidates whose top does not jump, one whose held side closes is taken (the usual 15 % of the best score, then the smallest held seam). Where none closes, windows twice a candidate's length are read — two steps of a confirmed repeat, one cycle, not themselves seen repeating — and one whose held side closes and whose top does not jump is cut:cycle.stepsis{"count": 2, "by": "held-edge", "step_lengths": [...]}(the candidates it is two of, each one step),cycle.period_localits own length,cycle.coveragerecorded, andstrip.jsonsayssteps: 2. A cut with fewer than two clip frames either side of it cannot be read:skipped, counted underunread, never chosen. An explicit--max-lenstays the cut's ceiling (two_step_capped:max_len,lengths_over), and counted steps read nothing twice as long.cycle.seam_pop.held_edgerecordsside,reference,measured,unread,doubled,chosenandtwo_step(read, lengths tried,measured,unread,top_pops,closing); a candidate row carriesheld_edge(nullwithheld_edge_skipped). A first choice whose top does not jump reads nothing new. docs/loop-repair.md. - New warning: a held part that no window one or two lengths long closes. The top band's cut stands and
jolt.warningsand stderr gainthe held part does not close at the wrap on the <side> side of the silhouette, below its top: …x its rows' median step (over 1.2); no window one or two lengths long closes it — it swings on a beat of its own(or, where--max-lenkept the longer windows from being read,no window one length long closes it, and windows two lengths long (…-… frames) are over --max-len N, so they were not read; where the steps were counted,no window of the counted length closes it); a held side that could not be read is said as well. Nothing fails on it. - Output change:
video-cycle-alignreads a loop's steps, and stops on a loop that may be one step. A loop whosestrip.jsonsayssteps: 2returns half way at its second step: that suspect is recordedstatus: "steps"(withsteps) and does not stop the set, and the loop is resampled to the set's length like the rest;--cycles <loop>=2on it takes one half out and dropssteps. A loop whose cut's report (beside the loop, or one directory up for avideo-setitem:align.cut_report) hascycle.step_screen.suspect, and whose steps nobody counted, is a suspect too (one_step:length,lag,seconds,ratio,depth,pairs,coverage,leg_peaks,why,report): stopped under--multi-cycle failwith its name andcut it again with sprite-gen video-loop … --steps 1, aligned and warned about underwarn;--cycles <loop>=1says it holds a whole cycle. Every loop with neither is aligned as before, its row,strip.jsonand cells byte for byte. video-set: an item whose cut's steps are known carriesloop.steps, one the step screen suspectsloop.step_screen(lag,ratio,depth,coverage), andtable.mdsays so in the cycle column (46 (2 steps),21 (one step?)); a state stopped on a loop that may be one step says<item> may be one step (cut it again with video-loop --steps 1 if it is). A cut two steps long now carriesratiolike any candidate, which the item reads.tests/video/test_explicit_window.pyholds one table of every path that sets a length — the first search, a window two steps long, the count, the gait fallback, the one-shot failover, a fixed cut — under an explicit--max-lenor--min-len, partial windows included (a held staff read only at 47 of 47-49 frames, a count read at 41-42 of 41-43): each run cuts inside the bounds or fails, and the report shows the path ran. Before this, the count (25 → 42), the one-shot failover (14 and 30 → 36) and the fixed cut (30 → 40) were cut outside them.tests/video/test_one_step_cut.pydraws a side walker with a 42-frame cycle, legs alike and arms shaded apart, over 73 frames: v2.35.0 cuts it at 21 and says nothing; now the cut is the same and the step screen names it (ratio0.48), the same drawing on 25 and 23.5 frames is written byte for byte as with no screen (23.5 a suspect that is a cycle),--steps 1cuts 15/42 where the arm's wrap is 0 against 7.6 for the step,--steps 2keeps the cut, a 50-frame clip is cut 8/42 and warned about its coverage,--min-len 41 --max-len 43is the window, and the set alignment stops on the step and aligns its re-cut.tests/video/test_loop_prop_seam_held.pydraws a walker whose legs come back every 24 frames with a staff turning about the hand every 48: every cut one step long whose top closes reads a held seam of 2.0 to 5.2, and the window two steps long taken reads 0 and is aligned at the set's length as one cycle. A staff swinging with the step below a pennant that sways on its own beat stays one step long; a staff whose foot swings every 37 frames is kept on the top band's cut and warned about; a walk without a staff reads nothing below its top; two loops without a staff are aligned with exactly thestrip.jsonandcycle_alignkeys v2.35.0 wrote.
v2.35.0 - A staff that swings on its own beat is not cut where it jumps
- Output change:
video-loop --anchor motion-autochooses its cut again when the top of the silhouette jumps into the first frame. A staff, a flag or a raised spear held above the head can sway on a beat slower than the steps; a cut one step long then ends with it elsewhere, the body closes and the held part jumps at the wrap. The seam ratio is an area measure and a thin rod hardly moves it, so such a cut passed. The search now weighs, for its first choice, the top band's step into the first frame over the loop's median step (repair.seam_pop, on the frames it chooses from, moved by the analysis translation; the median a pixel at least), counted only when the wrap is that band's largest step. Over the bound (10,repair.SEAM_POP_REFERENCE) every candidate is measured, and among those under it the cut is taken from the scores within the usual 15 % of the best, smallest jump first. The report'scycle.seam_poprecordsfirst_choice,applied,measured,unreadandchosen(orwhywhen every candidate read jumps and the first choice is kept). A cut whose top band cannot be read — a frame with nothing in it — has no jump to rank: it is recordedskipped(why) in place of apop(first_choice.skipped; a candidate row'sseam_popisnullwithseam_pop_skipped), counted underunread, and never chosen as one that closes; a first choice that cannot be read is kept. A first choice under the bound is kept and nothing past it is measured: a loop without such a part is cut, written and warned about byte for byte as before. docs/loop-repair.md. - New: every walk and run loop reports the seam pop and warns on it (
jolt.seam_pop: per axiswrap_pct,step_median_pct,wrap_over_median,wrap_is_largest;pop,reference,pops;seam_popin the printed summary'sjolt). Over the bound, on the loop as it plays,jolt.warningsand stderr gainthe top of the silhouette jumps into the loop's first frame up or down … (over 10x): a part held above the head swings on its own beat and does not close at this cut. The top line (up or down) had no bound at all; a sideways jump into frame 0 the head's 0.75 % bound already names is not said twice. Nothing fails on it, and a fixed or--cycle periodiccut is not chosen again. - New: a motion-auto search that finds no cycle reports the windows it measured and refused. The failed report's
cyclewasnull, so a caller that delivers anyway (a forced--cycle fixed) had no measured window and took the whole clip — which, for a walk, cannot loop. It now carriesstatus: "refused",window,refused_countand up to 12candidates(start,length,score,ratio,context_repeat_over_step,drift_line_residual_analysis_px,seam_pop, andrefused: why), best score first, those whose top could not be read (seam_pop: null,seam_pop_skipped) after those whose top closes, and those whose top jumps at the wrap last (local_cycle.REFUSED_SHOWN). The error, the exit code and every other gate are unchanged. docs/loop-review.md. tests/video/test_loop_prop_seam.pydraws a walker stepping every 24 frames with a staff above its head swaying every 61: v2.34.0 cuts it where the staff's tip jumps 11 times its largest step inside the loop, and now it is cut where the tip closes; a fixed cut whose staff tip rises and drops back at the wrap warns; a walker whose staff tip is flung out of the top band in one frame is not cut on a window holding that frame, which cannot be read (the branch's first take recorded those as jumping 0 and chose one whose tip jumps 8 times its largest step); a walk whose legs never come back fails with measured windows in its report.
v2.34.0 - A foot the set alignment names by too small a margin is left for whoever looks
- Output change: a side or diagonal loop whose shade parts its two strikes by less than 0.025 in luma is no longer named (
video-cycle-align,video-set --align-cycles;align.SHADE_MARGIN, was 0.015). The shade cue (the far leg drawn darker) named a foot whenever the strikes differed by 0.015; on drawn walks checked by eye it named feet wrong at margins under the new bar and right above it. A foot named wrong is not asked about — the loop ships half a cycle off — so a margin under the bar now leaves the foot unnamed: the loop starts on its larger strike withstart_foot: null, is listed under the report'sunnamed_feetwith its two candidate strike frames, and is told back with--foot <loop>=left|right(video-set --align-foot) by a person or a vision call. Its frames, strip, GIF and WebP are those of its larger strike as before; only who named the foot changes. Front and back loops (the depth cue, 1 % of the body's height) and every loop whose margin clears the bar come out byte for byte as they were. docs/loop-repair.md. foot_whyof a margin too small startslow-margin, with the margin, the cue and the bar (low-margin: the two strikes differ by 0.0235 in shade, under the 0.025 it takes to name a foot;align.LOW_MARGIN), in place ofthe two strikes look alike in shade (…), for both cues — in the loop row,unnamed_feet, the warning, andfoot_unnamed_whyonce told.tests/video/test_cycle_align_foot_margin.pydraws the side walker with its far leg 3 levels darker (margin 0.0235: named under 0.015, unnamed now — listed, warned, told back by--foot) and 4 levels darker (0.0314: named as before).
v2.33.0 - A horse's sheet does not swing its arms, and it does not strike with its hands
- Fix: the sheet rows
preparewrites gave every body a person's arms, shoulders and hands. 2.32.0's body plan reached the clip's walk, idle and still but not the rows an image model draws a sheet from: the walk and run rows moved "body, arm, leg, hair, and prop", the front and three-quarter-front walks "alternating leg, arm, shoulder", the diagonal runs traded "foot-contact phases" of "the left and right legs", the wave was "arm pose only: arm down, arm raised, hand tilted" (default action "friendly hand wave gesture"), every row's anchor lock spent its motion on "arm counter-swing" and turned "the body, feet, shoulders", and a diagonal row read its facing by "shoulder overlap, hand/foot placement". A horse's walk sheet came with arms. - Fix: an animal's attack was made with its hands. The clip's attack (
MOTION_TEXT["attack"]) struck "with what it is already holding (bare hands only if it holds nothing)", and its hold (HOLD_TEXT["attack"], after a caller's--motiontoo) said "one hand stays one hand, both hands stay both hands … A hand the motion does not use stays where it is drawn", whatever the body. - New
prepare --body-plan(the samebiped/quadruped/legless/"<figure>=<plan>"asvideo-set; repeatable; over the request'sbody_plan): any body but one biped gets rows without the parts it lacks (STATE_REQUIREMENTS_ANY_BODY,ANCHOR_LOCK_ANY_BODY, the diagonal facing line; the wave lifts one side as the clip's wave does, and its default action isDEFAULT_ACTIONS_ANY_BODY["wave"]where the request names none) and every row ends its state requirements with what it stands on (body_plan.text).sprite-request.jsonrecordsbody_plan(absent without one) and a run prepared again from it keeps it.video-set/video-prompt --body-plannow also give the attackATTACK_TEXT_ANY_BODY("with what it is already holding, or with its own body if it holds nothing") andHOLD_TEXT_ANY_BODY(anything it holds stays held the same way; no hand counted); which part strikes is left to the caller's--motion. No body plan, or one biped, keeps every clip prompt byte for byte (2.22.0's) and every sheet row byte for byte (2.32.0's, newtests/fixtures/prepare-rows-v2.32.0.json.gzdrawn bytests/gen/prepare_freeze_table.py). The new sentences are not yet measured on an image or clip model. docs/video-pipeline.md. tests/gen/test_body_plan_sheets.pydraws every sheet row (each state with a sentence of its own, the default states, a state with none, with and without a base image, a direction-contract run) and every clip prompt of every state (built-in and--motion, every view and model,video-prompt) for a quadruped, a body without legs and a man leading a horse, and finds no arm, hand, fist, wrist, shoulder, chest, hip, knee, shoe, heel, toe or counted foot in any (no leg or foot at all for a body without legs, apart from the sentence saying it has none); against 2.32.0 it fails on the attack's hands and onprepare, which took no body plan.
v2.32.0 - A horse is not told a person's walk
- Fix: an animal's walk and idle named a person's arms and feet. The walk and run sentences have named no limb since 2.0.0 ("
video-setmotion templates no longer assume a biped"), but four sentences added later were measured on people and said to every body: the Lite walk calm ("a gentle arm swing close to the body", 2.18.0), the Lite back-diagonal head hold ("only the legs, arms and the ends of the hair move", 2.18.0), the idle ("both feet planted flat", chest, shoulders and arms, 2.9.0) and the front or back walk's mid-step redraw ("one foot … directly under its own hip … the arms swing", 2.18.0). Said of a horse, they walk it on a person's legs or stand it up on two. Not a regression of the 2.0.0 fix: these paths came after it. - Fix: the still a front, back or diagonal clip starts from counted a person's feet. The view sentence a still is drawn with (
still_view_text,gen --direction; an app that draws its own still takes it too) said "the chest, hips and the toes of both feet" (front), "the shoulders, the hips and the heels of both feet" (back), "the face looking the same way as the chest" (front diagonal) and "the backs of the shoes" (back diagonal). The clip starts from that still, so a horse drawn on two feet stands up before the walk begins. - New
--body-planonvideo-set,video-promptandgen(build_prompt(body_plan=...),walk_start_prompt(body_plan=...),still_view_text(body_plan=...),gen.still_prompt(body_plan=...),sprite_gen/video/body_plan.py; ongenit needs--direction):biped(default),quadrupedorlegless, or one"<figure>=<plan>"per figure of a scene (--body-plan "the man=biped" --body-plan "the horse=quadruped"). Any body but one biped gets those four sentences without the parts it lacks (IDLE_TEXT_ANY_BODY,LITE_WALK_TEXT_LEGGED/LITE_WALK_TEXT_LEGLESS,LITE_HEAD_TEXT_ANY_BODY,WALK_START_TEXT_ANY_BODY) and, after the motion sentence or the caller's--motion, what it stands on: "It stays on all four legs, as in the image, and never rises onto its hind legs."; a scene says it per figure. The still's view sentence becomesSTILL_VIEW_TEXT_ANY_BODY(where the body and head point, no feet, chest, hips, shoulders or shoes) ending in what it stands on (body_plan.still_text): "…, standing on all four legs, not rearing onto its hind legs". A body without legs has no mid-step redraw.video-set,video-prompt --jsonandgen'sextra.viewrecordbody_plan. No body plan, or one biped, keeps every prompt byte for byte (tests/gen/test_prompt_freeze.py). The new sentences are not yet measured on clips. docs/video-pipeline.md. tests/video/test_body_plan.pydraws every walk, run, idle and jump prompt (built-in and--motion, every model,video-prompt, the mid-step redraw) and every still view sentence (still_view_textandgen.still_prompt, every view and facing) for a quadruped, a body without legs and a person leading a horse, and finds no arm, hand, wrist, shoulder, chest, hip, knee, shoe, heel, toe or counted foot in any (no foot at all for a body without legs); seven of them are pinned as snapshots.
v2.31.0 - A loop whose foot the set alignment cannot name is told it, one loop at a time
- New
video-cycle-align --foot <loop>=left|right(repeatable; the loop named as for--cycles: its--loop-dir, its strip's name, its directory's name or avideo-setitem's name) andvideo-set --align-foot <item>=left|right: which own foot lands on a loop's first strike, as seen by whoever looked at it — a person, the agent, or a vision call. Where a loop's view cannot tell its feet apart (start_foot: null),--start-footwas set-wide and there was no way to say "this loop's larger strike is its left foot". Now that loop alone starts as the set's start foot lands — on its first strike, or half a cycle on — and every other loop comes out byte for byte as without it. The answer is about the loop as filmed (its strikes are read fromcycle.source/), so it holds for a later alignment at the same length; like--cyclesit is not remembered. A foot given for a loop the view did name is taken too, and where it disagrees the row carriesfoot_disagreesand a warning. A--footthat names no loop or two, or is notleft/right, is refused before anything is rewritten;video-setrefuses an--align-footitem that is not a walk or run filmed in two or more directions before filming, and names one given for an item that failed or whose state was not aligned in that state'sfeet_unusedand a warning. The way feet are named from the pixels is unchanged. - New in the alignment report:
unnamed_feet, per loop whose foot nobody named:dir,name,view,foot_why,candidates(its two strikes:strike0 and 1,framein the rebuiltcycle/and thepathto that frame — the frame to show whoever looks; the first is the frame the loop starts on) andsettle(the two--footarguments). The report also gainsfeet_given; every loop row and itsstrip.jsoncycle_aligngainstart_foot_source("engine"where the view's cue named the foot,"given"from--foot,nullwhere nobody did) andstrikes(the two strikes as frames of the rebuiltcycle/), and a told rowfoot_givenand, where the engine had not named it,foot_unnamed_whyinstead offoot_why.video-setcarriesunnamed_feetandfeet_givenper state andstart_foot_sourceper item; a stopped set'scommandcarries the--footgiven. The warning for an unnamed loop now names the frame to look at and the--footthat settles it. Without--foot, the cycle, strip, GIF and WebP are unchanged. docs/loop-repair.md, docs/video-pipeline.md.
v2.30.0 - A held loop is judged on the cycle cut out of its clip, not on the whole clip
- Output change: which loops
video-cycle-alignnames for a retake (held-drawings). The hold was read over the whole clip and given to the cut cycle, so a clip held for part of its length and drawn every frame for the rest was judged by the clip: a cycle cut from its every-frame part and stretched could be named (the clip reads as held), and one cut from its held part was passed (the clip reads as drawn every frame).video-loopnow also reads the hold over the cut, on the clip's own steps as keyed from the cut's first frame into the frame after its last (cycle_drawingsin the loop report and instrip.json:start,length,steps,hold,drawings_per_second,contrast), and the alignment uses it (drawings.source: "span", with the clip's reading underdrawings.clip). A cut of fewer than 12 steps (held.SPAN_MIN_STEPS, one window of the clip's reading) is not read on its own: the clip's reading stands (source: "clip"), and the row'sspan_whysays so, as it does for a loop cut by 2.29.0. A clip held or drawn every frame throughout reads the same over its cut as over the whole: the cut, the strip, the GIF and the WebP are unchanged, and the loop report andstrip.jsongaincycle_drawings. docs/loop-repair.md.
v2.29.0 - A clip that shows each drawing for two or three frames is read as such, and the set alignment names a held loop it could not fill as a take to film again
- New:
video-cycle-alignnames a loop to film again (retake, reasonheld-drawings). A loop whose clip holds each drawing for two or three frames ("on twos", "on threes"), that the set's length leaves at under 13 drawings a second (align.RETAKE_DRAWINGS_MIN; a clip on twos shows 12), with one or more frames between its drawings not made (align.RETAKE_UNMADE_MIN: taken from the nearer source frame under--between autoornearest, made with a fault and kept underrife), is listed in the report'sretake(dir,name,hold,source,drawings,drawings_per_second_filmed,drawings_per_second,frames_per_drawing,unmade,limits) and in a warning line ("film this direction again (held-drawings) — …"). Where the legs swap places between two drawings no interpolator draws them, so each frameautotook from the nearer source frame holds a drawing a frame longer and the loop halts there; only a new take drawn every frame fixes it. The set is still aligned and written, exit 0: the reason is for the caller to act on, never silent. Each loop row and itsstrip.jsoncycle_aligngaindrawings(the hold, read from the clip's record) andretake(the record, ornull);video-setcarriesretakeper state and per item. A held loop at its own length (nothing made), a held loop whose made frames all kept their outline, one squeezed to 13 drawings a second or more, and a loop drawn every frame with a replaced frame are not named. - New:
video-looprecords the clip's drawings (drawingsin the loop report and instrip.json,hold/drawings_per_secondin the printed summary): whether the clip shows each drawing for one, two or three frames, how many drawings a second, the held steps, andcontrastper hold as the evidence (sprite_gen/video/held.py), read over the whole clip as keyed, before the cut. The alignment reads the hold fromstrip.json: a cut cycle is short, and--anchor motion-autoshifts each cut frame so a pair's repeat may no longer read as one; a loop cut before this record is measured on its own cycle. The cut, the strip, the GIF and the WebP are unchanged. - Why a rhythm and not a threshold: a model rarely repeats a drawing as a byte copy — it redraws the second frame of a pair a little — and a rule that calls a step held under a fraction of the median step misses exactly that, because with half the steps held the median falls between the two kinds. The judgement reads, for a hold of 2 or 3, the phase whose every second or third step is the change, in windows of 12 steps: the held steps' median over the change steps' median, under 0.3 (
held.CONTRAST_MAX). A clip drawn every frame whose steps alternate long and short, and a frame repeated now and then (a 20 fps clip carried at 24), read above it. docs/loop-repair.md, docs/video-pipeline.md.
v2.28.0 - A frame RIFE made whose legs melted is caught by the outline it lost, and the set alignment takes the nearer source frame there
- Output change: which frames
video-cycle-alignkeeps from RIFE.--betweengainsauto, now the default (video-set --align-betweentoo): every frame between two source frames is still made by RIFE and measured, and one that smeared or lost its outline takes the nearer source frame instead, named in the warnings. A set whose made frames all keep their outline comes out byte for byte as 2.27.0's; where one melted, that frame is now the nearer filmed frame, the loop'scycle_aligngainsnearest_atbesidemade_at, andmade_by_rifecounts only the frames kept.--between rifegives 2.27.0's frames, with the new warnings;nearestis unchanged. - Fix: a frame RIFE melted passed without a word. Where two drawings are too far apart for the flow — legs crossing a long way, as a clip drawn on twos gives between its drawings — RIFE draws the legs as one shape of fill with no outline between or around them. 2.25.0's smear check warns only on dark pixels added, and a melted frame has fewer: it lost its outline.
rife.smearnow also measuresoutline_loss: of the frame's coverage edge (alpha from 0.1, so a pale ghost limb's edge counts), the share with no dark pixel within 2 px, beyond the less outlined neighbour's. Over 5 % (align.OUTLINE_WARN) the frame has the faultoutline; over 0.1 % dark, as before,smear(align.faults). The dark count's other side does not do this: a clean frame half way between two drawings has fewer dark pixels than the darker one wherever they differ, and on two outlined legs RIFE's clean frames of a short step readdark_excess−1.3 %, lower than its melted frame of a long crossing (−1.1 %);outline_lossreads under 3 % and 32 % (tests/video/test_rife.py).partial_excessis still reported and not judged: a melted frame and a clean one read alike on it. - Every made frame says what became of it:
cycle_align.smearrows gainmethod(rife, kept, ornearest, the nearer source frame taken instead),outline_lossandfaults; the report gainsreplaced, andvideo-set'scycle_alignper state too. A fault is a line inwarningsunder every--between: underautoit says the nearer source frame was taken there, underrifethat the frame is kept and where to look.autoruns RIFE whereverrifedoes and needs it installed the same way. docs/loop-repair.md.
v2.27.0 - A set is not aligned with a loop that may hold two cycles until someone counts them, and only that count takes one cycle out of it
- Output change: which sets
video-cycle-alignrewrites.video-loop's output is 2.25.0's and 2.26.0's: every cut keeps its period, length and start, whatever its legs or shading (the report gainscycle.fundamental, andstrip.jsongainsstate).video-cycle-alignnow stops a set — nothing rewritten, exit status 1 — where one of its loops may hold two or three cycles (a half or a third of it repeats and is no shorter than the gait floor), and 2.26.0 aligned it; the report is written withapplied: false,refused: "cycle-suspects"and the typedsuspects. A set with no suspect is aligned as before, every loop resampled from all of its filmed frames.video-set --align-cycles autoskips such a state with a warning (applied: false,reason: "cycle-suspects",suspects) where it aligned it, and the RIFE skip now carriesreason: "rife-not-installed". The number of cycles in a loop changes only through the new--cycles. - Fix: a walk filmed through two strides walked twice as fast as its set, without a word. A clip drawn on twos whose stride is an odd number of frames repeats better two strides on than one, so
video-loopcut two strides as one loop, andvideo-cycle-align, which gives every loop one length on the assumption that each holds one cycle, squeezed both into it. The engine does not cut such a loop shorter on the pixels' word: half a stride on, the legs are back in place with near and far swapped, and where they are drawn alike that one step and a true stride half a drawing late are the same picture, so every rule that took the half took some one-stride walk or run to its half step. Instead the shorter repeat is screened (sprite_gen/video/period.py:screenmeasures the half and the third —periodicity,poseoff the motion's path, and for the record the legs'stepsandfollow— and one rule,period.verdict, decides: a half or a third that repeats is asuspect, whatever its pose; nothing says "a cycle" and nothing says "not one").video-looprecords it (cycle.fundamental:checked,suspects,legs), and so does the local search of--anchor motion-auto.video-cycle-alignscreens each loop as a ring (align.cycle_screen) and stops a set on a suspect, naming the loop, where it returns (frames and seconds), the evidence and the command that settles it (command, the same alignment with--cycles <loop>=<1|2>to fill in);--multi-cycle warnaligns it as it is with a warning per suspect. The pose is not a reason to refuse: a rule that refused "another pose" missed most two-stride loops whose second stride was redrawn a pixel aside or a few per cent lighter, which in pixels is off the motion's path just as a swapped step is. The cost is the other way: a run's half step repeats too, so a run set stops nearly every time until its loops are counted (docs/video-pipeline.md section 4, "The fundamental period"). - New
video-cycle-align --cycles <loop>=k(repeatable; the loop by its--loop-dir, its strip's name, its directory's name or avideo-setitem's name): how many cycles a loop holds, as counted by whoever looked at it (a person, or a vision call asked how often each foot lands).1aligns it as it is;2or3takes one cycle out of the loop as filmed (cycle.source/,align.take_cycle: round(L/k) frames from the start whose frame one cycle on is the most like it) and aligns that, without cutting the clip again. Loop rows recordcycles_given,cycle_screenandcycle_taken; the reportcycles_given,suspectsandmulti_cycle. Also new:--multi-cycle fail|warnand--state(the gait floor for loops cut beforestrip.jsoncarriedstate). - The foot-strike signals moved to
sprite_gen/video/legs.py(align.strike_signalsand thealignconstants still name them), with one more per frame,gap(the widest empty run in the foot band). The turn reads them as before. - Docs: docs/loop-repair.md section 4 (two cycles in one loop are stopped and counted;
--cycles), docs/video-pipeline.md section 4 ("The fundamental period": the engine does not cut shorter on the pixels' word, because a gait's half step with the legs alike and a cycle half a drawing late are the same picture) and section 5, docs/loop-review.md.
v2.26.0 - The size hold reads a walk's change of size one cycle on, and a follow-through that would fold its region can take the largest gain that does not
- Output change: which walk and run loops are held at their size.
video-loop --anchor motion-autowith--size-hold auto(the default) reads the clip's change of size one cycle on instead of off a line fitted through the clip (gait_fallback.cycle_drift). A clip whose reading crosses 1 % one way or the other is cut differently: one that starts from a standing pose and settles into the walk is no longer held (the line read the settle as a shrinking body), and one whose settle pulled the line under 1 % while the body did grow is now held. A clip held either way is scaled back by the change one cycle on, not by the line's, so its frames differ too: a clip whose first frames zoom in reads its walk's own change, not the zoom, and can find a cycle it did not find scaled by the line. A clip under 1 % both ways, and every clip with--size-hold off, is cut exactly as before.video-followwith its default--on-fold refusewrites what 2.24.0 wrote. - Fix: a first pose that settles into the walk read as a change of size. The hold fitted a line to the subject's height over the clip, and a clip that stands tall in its first frames and then walks a few pixels lower read as a body shrinking the whole way: at 1 % or more it was scaled back. The hold now finds the lag at which the pose (cut out about its feet) matches itself best, compares each frame's height — to a fraction of a pixel, the rows' coverage summed — with the frames one, two, … of those lags later, and carries the median change per frame over the clip; the few frames of the first pose do not move the median of the rest. On a synthetic walker that stands 6 px taller for its first frames and walks at one size, the line read −2.2 % and, scaled back by it, the clip found no cycle; it now reads 0 and is cut as filmed. A walker that settles and grows 2.5 % read +0.6 % on the line and was not held, and found no cycle either; it is now held and cut.
size_holdin the report carries the evidence:method,lag,pose_match,pairs,per_laganddrift_fitted_line(what the line would have read). The gait fallback after a failed search still reads the line at 3 %. docs/video-pipeline.md. - New
video-follow --on-fold lower: a move that would fold a region over itself is no longer only refused. The move is the gain times the move at gain 1, so the gain at which a region folds is known (2 · radius / (π · move at gain 1));lowertakes the largest gain under it, in steps of 0.01 and no more than--gain, one gain for the strip set by the region with the smallest radius, and names it on stderr. It never goes under 1, the mass as measured: a region too small for that is still refused, and the message names the largest gain that would not fold. The record says what was asked and what was used (gain_requested,gain,on_fold, andfold: lowered or not, the move asked for, the move at gain 1, per region the smaller radius, how near the used move is to folding it, and the gain at which it folds). The default stays--on-fold refuse: the same strip, GIF, WebP and refusal message as 2.24.0, byte for byte; the record only gains those keys. docs/video-pipeline.md. - Docs: a clip from a video MCP on your agent goes through the set stage and the size hold. That route stopped at
video-loop, so whatvideo-setdoes for a set was left out. It now cuts a walk or run with--anchor motion-auto(the anchor that holds a clip with no end frame at its first frame's size;video-loop's default for a walk,body, does not), takes--fpsfrom the frames report, and ends withvideo-cycle-align --view …once a walk or run is cut in two or more directions (SKILL.mdroutes, docs/video-pipeline.md withSetandSizerows in its ZCRE table, docs/user-workflow.md, the READMEs).video-cycle-alignis in the pipeline's diagram and verb table.SKILL.mdforbids replacing any engine stage — extraction, the loop cut, set alignment, loop repair — with a script of your own: the engine's own options first, the defect reported, a new clip only for what no stage can reach. docs/qa-motion.md says its "regenerate that row" is for image rows; a video loop is repaired and aligned by the engine first. No code or output changes.
v2.25.0 - Every view of an aligned walk starts as the same foot lands, read off the legs, and RIFE leaves no black between crossing legs
- Output change: every frame RIFE makes, and where every aligned loop starts. Frames made by RIFE (
video-cycle-align,video-set --align-cycles auto,video-loopjump repair) are drawn differently wherever the legs cross or the flow is unsure; frames taken as filmed are untouched. Every loopvideo-cycle-alignturns may start on a different frame: on its legs instead of its top edge, and, with views, on one foot for the whole set. A loop already aligned starts where the new rule says the next time it is aligned (it is read fromcycle.source/). - Fix: a black smear between crossing legs in a frame RIFE made. RIFE runs its flow twice, once for the colour and once for the coverage, and where two legs pass each other the runs disagree: the coverage says body where the colour still carries what lay around the body. 2.24 premultiplied the colour over black, so the disagreement came out black. The colour image now carries the body's own colour around the body (
rife.bleed: the colour from 0.8 % of the body's height inside its solid edge, past a drawn outline, pushed out over the transparent area), so a disagreement reads as the body's fill; inside the body the colour is the frame's own, outline included. On two outlined legs walking through each other the made frame at t = 0.5 had 6 % of its body dark beyond either neighbour; now none (tests/video/test_rife.py). A limb RIFE cannot follow is still soft and pale, never black. docs/loop-repair.md. - A smear is measured on every made frame, never passed over quietly.
cycle_align.smearlists per made framedark_excess(dark pixels inside the body beyond the darker neighbour's count — a moved hat or watch keeps its count) andpartial_excess(part-covered pixels beyond the more ragged neighbour's); over 0.1 % dark, the frame is named in the alignment report'swarnings, on stderr and invideo-set'swarnings(rife.smear,align.SMEAR_WARN). - New
video-cycle-align --between nearest(video-set --align-between nearest): a time between two source frames takes the nearer source frame, so nothing is made and no RIFE is needed; the motion keeps the filmed frames up to half a frame off their time.rifestays the default. A loop stretched this way shows a frame twice; its GIF and WebP are checked for one frame per run of identical cells, since both hold a repeated frame as one of twice the delay. - Fix: the loop started where an ear tip was lowest. The turn took the frame whose alpha box top was lowest, and a long ear, a hat's point or an antenna owns that edge and flops on its own rhythm, so each view started at another point of its step. The start is now read off the legs (
align.foot_strike,turned_onin the loop row): side and diagonal views on the widest stride of the foot band (the lowest 8 %), a heel landing in front; front and back views on the lowest solid row, the foot nearer the viewer drawn lowest; and only for a body with no legs to read, the body's top line, the first row at least half as wide as the frame's widest, so a narrow ear is passed over. With--view(and invideo-set, always) the view picks the signal and the swings only say whether there are legs: a side or diagonal view where the foot band swings by 15 % of the body's height or the lowest row by 1.5 %, a front or back view where the lowest row swings by 1.5 %. A short-legged walk misleads a threshold either way — from the front the foot behind lifts out of the foot band, which then swings like a side stride mid-step; from the side a short step opens the feet by less than 15 % — so the thresholds choose the signal only without--view: the stride where it swings by 15 % or more, otherwise the lowest row where it swings by 1.5 % or more. A body that hardly bobs turns on its legs as one that bobs does (tests/video/test_cycle_align.py: a drawn walker whose ears are lowest half a step off its heel strike, with and without a bob; a big-headed, short-legged walker from the front and from the side). - New: every view starts as the same own foot lands (
video-cycle-align --view front --view side@right …, one per--loop-dir,--start-foot right|left, default right;video-setpasses each item's view and facing). A walk lands twice a cycle, half a cycle apart, and until now the turn took either. The foot is told by how the view draws it (align.strike_foot, withhandedness.placementfor which own side is where): front and back by which foot is drawn lower (nearer the viewer), side and diagonal by which leg is shaded (the far one). Where the cue does not follow the step (its once-a-cycle swing under a quarter of its spread) or the two strikes do not differ enough, the foot is not named rather than guessed: the loop starts on its larger strike withstart_foot: nullandfoot_why, and the report'swarningssay so; without--viewthe report says once that no foot was chosen. Each loop row carriesview,start_footandfoot(the cue, its values and margin). docs/loop-repair.md.
v2.24.0 - A walk filmed from its first frame loops at one size, a frame scaled up keeps its crown, and a soft part can follow the body
- Output change: a walk or run loop whose clip changes size by 1 % or more is cut differently.
video-loop --anchor motion-autonow holds the clip at its first frame's size before the cycle search (--size-hold auto, the default;size_holdin the report): the subject's fitted height over the clip is measured (gait_fallback.scale_drift) and, at 1 % or more (SIZE_HOLD_MIN), every frame is scaled back to the first frame's height about its fitted foot point (undo_scale). Until now that ran only in the gait fallback, after the search had failed and at 3 % or more, so a clip that grew 1–3 % and still looped was cut on frames of changing size: the frame one cycle on was larger than the first, and the loop popped at the wrap. A clip under 1 % is cut exactly as before;--size-hold offgives the old cut. A clip that grows 2.5 % now loops at its size where it found no cycle before (tests/video/test_gait_fallback.py); a front catwalk filmed from its first frame (+2.0 %) went from a seam ratio of 1.44 to 1.19. docs/video-pipeline.md. - Fix: scaling a frame back up cut off what it carried past the frame's edge. A clip that shrinks is scaled up about its feet; when the feet also rose in the frame (a back walk going away), the crown landed above the frame and was cut in every frame it reached. Frames are now widened by the room the furthest one needs (
gait_fallback.undo_padding, the same for every frame,padding_ltrbinsize_holdandgait_fallback), so nothing is lost; a clip that needs no room keeps its frame size and bytes. - New
sprite-gen video-follow: a soft part of a looping body (a chest, a belly, a pouch on a strap) follows the body's motion. An ellipse in the strip's first cell (--region cx,cy,rx,ry, repeatable) is moved as a damped mass on the body's own bob — the crown's row and the head's middle read off the cells, the periodic steady state of x'' + 2ζωx' + ω²x = −body'' per harmonic of the cycle (--freq2.4 Hz,--zeta0.6,--gain2.5 times the physical answer) — so it lags and settles with no kick, and the last frame leads into the first. Only the region's pixels change; a move that would fold it over is refused. The strip, GIF and WebP are rewritten and checked,followis recorded in the strip meta, and the strip as it was is kept asfollow.source.png, so a second run never moves a moved strip. The region is the caller's to give: the engine does not find it. docs/video-pipeline.md. video-cycle-alignclears a follow-through: it rebuilds the strip from the cut, so it removesfollow.source.pngand thefollowrecord and saysfollow_clearedin the loop's row; a newvideo-loopcut removes them too. Runvideo-followafter the alignment.
| Before / after | |
|---|---|
| A back walk going away, scaled back up: 2.23.0 cut the crown at the cell's top (red line); 2.24.0 widens the frames first | |
video-follow on a hip pouch (zoomed): as cut, and following the walk's bob as a damped mass |
v2.23.0 - A walking side view shows the far wrist's item each time that arm swings forward; without --handed every prompt is 2.22.0's
- Without
--handed, every prompt is 2.22.0's, byte for byte. Clips (built-in or--motion, every model and pin),video-prompt, stills (view, facing, reference, key line, layout guide, the--facing-fix regenregeneration),video --direction sideand the mid-step redraw send what 2.22.0 sent.tests/gen/test_prompt_freeze.pyholds every prompt string in that table totests/fixtures/prompts-v2.22.0.json.gz, drawn from the 2.22.0 tag's source. The engine's pieces go on through one place (sprite_gen/gen/prompt_parts.py,Prompt.add), which puts them on as 2.22.0 did; with--handedthe prompt is that same prompt with the handed sentences put in, and nothing else changes. docs/prompt-assembly.md lists the faults of the 2.22.0 prompts kept until a before-and-after comparison says to change them. - Fix: a watch on the far wrist was in no frame of a side walk. 2.22.0 said every item on the far side of a side view hidden, and never named it in the clip ("the wrist in front of the body stays bare"). A walking character's far arm comes forward of the body with every step, and what its wrist or hand wears shows then. An item on a wrist, a hand, a forearm or an elbow (
handedness.limb, one table:SWINGING_ARM_PARTS) on the far arm is now said to show wherever that arm is out in front of the body: in the still ("wherever the far arm reaches out in front of the body, clear of its outline, the black smartwatch shows whole on it; where the body covers that arm, it is hidden") and in a walk or run ("stays on the wrist that wears it in the image, on the arm on the far side of the body, and shows each time that arm swings forward; the arm nearer the viewer stays bare, exactly as in the image"). On the near arm the walk says the other arm stays bare "both where it shows behind the body and where it swings out in front of it". Both start "Both arms swing back and forth with each step, opposite to the legs." (handedness.ARMS_SWING_TEXT, the one place that sentence lives), and no sentence holds an arm still. An item anywhere else — an ear, the head, a tail, the body, a leg, a shoulder, the upper arm — gets no arm sentence and keeps the 2.22.0 sentences, as does a state that does not step (idle, attack). docs/video-pipeline.md. - A side view names the near part "nearer the viewer", not "in front of the body" (still and clip sentences): in a mid-stride still the far arm is the one in front of the body, so "the wrist in front of the body stays bare" named the wrist with the watch.
- A clip keeps what its first frame shows: for a walk or run with an item on the far wrist or hand of a side view,
video-prompt --json(still_needs, and stderr) andvideo-set(each item'sstill_needs) say the still must be drawn mid-stride with that arm out in front of the body and the item in view. The docs give the pose sentence for the prompt. - One handed sentence per wrist, not per item: with an item on each wrist a side clip said "the wrist in front of the body stays bare" and "the red ribbon stays on the wrist in front of the body" together, and with two items on one wrist it said the same sentence twice. Items on one part share a sentence, a part another item is on is not called bare, and a still says "none of it" there. A diagonal's clip sentence also reads "…, nearer the viewer, for the whole clip" (the comma was missing). A start still's prompt handed back to
gen --direction --handedcarries the handed sentences once. handed-checkpasses a far wrist's item in view and fails the near arm's (side views): 2.22.0 failed every frame that showed the far item whole ("in full view on the far side"). An item on a far wrist, hand, forearm or elbow must now be out in front of the body in every frame it shows — on the facing side of the body's centre by at least a tenth of the body's height (far_in_front); at or behind the centre it is on the near arm. With the new--state walk|runit must also show in at least a quarter of the frames (far_shown; unchecked without--stateor for a state that does not step). A side view's near item must show in three quarters of the frames, not half: a far item turned over to face the other way shows in about half. Any other far item keeps the hidden-or-a-sliver rule (far_hidden), and a diagonal's near side keeps half.- The caller's own words are reported, not edited. Text that turns the subject another way than
--facing(or to a side in a front or back view), or puts a--handeditem on its other side, is sent as written with a warning; text that repeats an option gets a note.genprints them and recordsextra.prompt_notes;video-prompt --jsonlists conflicts inwarningsand all of them innotes;video-setrecordsprompt_notesper item. The prompt is the same with or without them. tests/gen/test_prompt_assembly.pydraws every prompt in the option table as text — views, facings, items on a wrist or an ear, what the caller's text already says, states, clip models, the start still and the hand-offs between verbs — and checks each for the prompt without--handedplus the handed piece and nothing else, a handed sentence said twice, a limb called bare and dressed at once, an arm sentence where no wrist item is or no step swings it, and the notes.
v2.22.0 - A character with an item on one side has its left-facing views drawn, not mirrored, and an attack is filmed with less room above
- Handedness, said once (
sprite_gen/gen/handedness.py):--handed "<item>=<left|right> [part]"names an item on one of the character's own sides ("the black smartwatch=left wrist"); the engine works out where that side is in each view — the picture's right or left in a front, back or diagonal view, near or far in a side or diagonal view (placement) — and says it in the prompts (text).sprite-gen gen --direction <view> [--facing …] --handed …adds the engine's still view sentence and, per item, which side it is on, where that is in the view, and that the sentence outranks an attached picture; with--handed,--facing-fix mirroris refused andregennever falls back to a mirror.video-prompt --handedandvideo-set --handedend the clip prompt with where the item stays, anchored to the first frame and named once where it shows; on the far side of a side view it is not named at all — the near arm "stays bare, exactly as in the image" — since a clip prompt that names a hidden item draws it on the near arm. docs/video-pipeline.md. - Left-facing views drawn, not mirrored — opt-in:
video-set --facing right,leftfilms every side and diagonal view both ways, each from its own still (--base side@right=… --base side@left=…); a turned view missing a still for one facing is refused, naming thegen --direction … --facing …call that draws it. Items are named<view>-<facing>-<state>, the table names the facing, each side still is inspected for its own facing, and gaits are aligned across all eight. With--handed, a front or back walk's mid-step redraw is told the item's side as well. Mirroring stays the default (drawing costs as much again); one facing keeps the item names and table as before. - New
sprite-gen handed-checkchecks a still or loop frame by frame: a colour-marked item (--marker, a saturated colour nothing else on the character has) must sit on its view's picture side of the body's centre, in one place only, showing in at least half the frames on a near side and, against a--referencefront or back picture, no more than a sliver on the far side of a side view and more than a sliver on its near side — a side view has no picture side, so a far sliver turned over to face the other way does not count as the near item shown. Without a reference both size rules are reported unchecked (far_hidden,near_whole).--strap --zoneadds the item's band seen without its marker (a bare strap on the other arm) within the rows it sits in. Specks of the marker's hue left on outlines by a clip's colour blocks are recorded, not judged.--boarddraws every frame with its verdict; exit 1 on a failure. Drawn test figures pass as they should look and fail turned over in every view, a side view's far sliver against--reference(tests/qa/test_handed_check.py). - Fix: a diagonal facing left was filmed heading right. The diagonal walk and run sentences said "to the right" and "toward the upper right" whatever
--facingwas; they now take the facing ("heading diagonally toward the viewer and to the left").video-promptandvideo-setalso cut a left-facing diagonal's loop with--facing left(it was alwaysright), which mirrors the jump repair's hair box. Right-facing prompts are unchanged. - A
gen --transparentrun with--refkeeps the alpha it comes back with:autostill plans a chroma key before the model runs (2026-09-08: codex drew a checkerboard in 5 of 6 ref runs asked for alpha), but the raw is read before the key is applied (chroma.classify_raw_alpha). A raw with an alpha band, at least 5 % of it at alpha 0 and at least half of its border at alpha 0 is published on its own alpha through the native check, withalpha.strategy: "native"andalpha.strategy_source: "refs-attached-raw-alpha". Keying it read the RGB under alpha 0 as the background and took the outline and light fills off: a transparent reference is answered with alpha, and a fox redrawn from one lost its outline and cream belly. A checkerboard, a key background or an opaque RGBA (no alpha band, or no alpha 0) is keyed as before (refs-attached); alpha 0 that misses either bar is keyed as before with awarning.alpha.raw_alpharecords the verdict and its numbers on every ref run that planned the key.--alpha-mode chromakeys whatever comes back. docs/gen.md. - Measured 2026-10-04 on codex
image_gen(subscription), one transparent front still as the reference, three takes per arm: with the planned key's prompt, a transparent reference came back with real alpha 3/3 and the same still on white came back on opaque white 3/3; asked for alpha (--alpha-mode native), both came back with real alpha 3/3, with no checkerboard in 6 runs. The step down is kept until a larger measurement replaces the 2026-09-08 one. - The step down asks for the key it plans: a
gen --transparent --refprompt that names no key background gets the--chroma-keykey's line (chroma.KEY_BACKGROUND_TEXT, moved fromvideo.batchso a clip's mid-step redraw and this run say the same sentence); a prompt that names a key — its hex code, or "magenta/green background", "chroma key", "screen" — is left as it is, with no second line.alpha.key_backgroundrecordsinjectedand the key. A reference on white with no key in the prompt came back on opaque white (3/3) and keying it took the outline and the cream fills; with the line, five takes (three on that reference, two on the transparent one) came back on a magenta key and kept both.--alpha-mode chromaand native runs are unchanged. docs/gen.md. --decontamis skipped, not refused, on a ref raw that came back transparent: it has no key to remove, and the refusal came after the paid generation.alpha.decontamrecords what was asked and why it was skipped, and stderr says so (a warning forpalette).chroma.classify_raw_alphajudges on the pixel counts, not the rounded percentages: a raw with alpha 0 under 0.005 % wasno-alphaand keyed with no warning; it isambiguousnow.- An attack canvas keeps 20 % of its height above the still, not 35 % (
STATE_CANVAS["attack"]; 28 % in front and 20 % behind are unchanged). The extra room only made the body a smaller part of the clip, sovideo-loop --body-heightscaled it up to the delivery height; with 20 % the body is larger in the clip and is scaled down. A 1024 px square still now pads to 2276×1280 instead of 2800×1575. 20 % still holds a weapon raised about a third of the body above the head: the canvas adds at least a quarter of the still's height above it, and the still's own margin over the crown does the rest (8 % of its height is enough). A still cropped at the crown needs--headroom 0.26or more for an overhead swing. At this headroom the 16:9 ratio, not--lead, sets the width of a square still's canvas. docs/video-pipeline.md. --shape widekeeps 35 % above (WIDE_OVERRIDE, no longer the attack row): it is forced on states whose own row is another shape —video-set --shape wideacross a batch, or a canvas widened after the subject touched a side edge — and a jump is one of them; 35 % on 16:9 keeps about the room a jump's tall row leaves above the still. A forced-wide canvas is the same as before; an attack in a--shape widebatch gets that row, as a cheer or a projectile already did.
v2.21.0 - A clip made by a video MCP on your agent (ZCRE) becomes a loop: the prompt comes out, the mp4 goes in
- New
sprite-gen video-promptprints the clip promptvideo-setsends for one (direction, state) —build_promptwith--character,--motionand--model— so an agent that makes the clip itself, with a video MCP connected to it, sends the same sentence.--jsonadds the duration (the state's own), whether the clip ends on the canvas (last_frame), the loop cut (cycle), the canvas, clip, frames and loop steps with placeholders, and for a front or back walk the mid-step redraw (start_still). sprite-gen never calls the MCP: the agent uploads thevideo-canvasstill, quotes, asks the user, generates and saves the mp4, andvideo-framesandvideo-looptake it from there. docs/video-pipeline.md. - ZCRE (지크) is that route's first source: its remote MCP, signed in with your own ZCRE account and credits, has
grok-imagine-video-1.5(Grok Imagine Pro) for image-to-video, with no end frame and no Lite model.--no-last-framerefuses whatvideo-setfilms pinned — idle, attack, a walk or run in a diagonal — and--unpinnedfilms one anyway with a warning (the loop is searched instead of cut whole and may not close). Walk, run and jump from the side, front and back are supported. video-framesreads the picture of a clip that carries more: it takes the first video stream that is not a cover image (attached_pic,stream_index), and recordscodec,pix_fmt,audio_streamsandcover_streams. A ZCRE clip always has an AAC track and an mjpeg cover; the audio is never extracted and the loop outputs carry no sound.- Measured once end to end: one side walk, 720p 3 s, 52 credits, 33.6 s to generate; the clip was 960×960 H.264
yuv420pwith an AAC track and a cover, and it cut to a periodic 20-frame loop. - The places that moved or scaled a keyed picture with BICUBIC map it with coverage and colour apart (
transform_cell, besideresize_cellinsprite_gen/util/resample.py): the gait fallback's scaled-back frames (video-loop --anchor motion-autoon a walk that grows or shrinks through the clip) and a curated move, scale, rotation or shear baked on a smooth row (curation.apply_transform, socompose, the GIF, the PNG export and the cycle bake). BICUBIC over premultiplied RGBA has the same negative lobe as LANCZOS, smaller, and drew the same lighter rim and key tint at the edge. On the synthetic outlined figure (tests/keyed_figure.py) it left 1,088 to 1,864 pixels with a colour none of the four source pixels under them had when a frame was scaled back by 0.84x to 1.19x, and 840 to 2,102 for a half-pixel move, a 10° rotation, a 0.75x shrink, a shear and a 1.3x grow with a 15° rotation; none are left. Coverage keeps BICUBIC's edge, held to the coverage of the 2 x 2 source pixels the colour mixes from; colour is a BILINEAR mix of premultiplied colour, so it is no longer sharpened. A pixel row's curated transform (fit.pixel_unfake, NEAREST and re-snapped) and an identity transform are unchanged. The scene GIF's downscale stays LANCZOS: it scales opaque composited frames, where there is no coverage to divide by. docs/video-pipeline.md, docs/loop-review.md, docs/curation.md, docs/pixel-unfake.md.
v2.20.0 - A keyed picture is scaled without a light rim or a green tint at the edge wherever the engine scales one: a row frame, a sliced sheet, a scene layer
- The places that scaled a keyed picture with LANCZOS now use the loop's resample (
resize_cell, now insprite_gen/util/resample.py): a row frame shrunk into its cell (extract,fit.resample: lanczos, the default), the plain and original-quality twins beside a pixel-unfake frame (.plain.png,orig/), a sliced sheet's figures (slice-sheet) and a scene's layers (scene-render). Each used LANCZOS over premultiplied RGBA and drew the same lighter rim and key tint at the edge as the loop's strip did before 2.19.0. On the synthetic outlined figure (tests/keyed_figure.py), LANCZOS left 137 pixels at 0.2x, 543 at 0.5x, 978 at 0.75x and 7,315 at 2x with a colour none of the source pixels under them had; none are left at any of them.fit.resample: lanczoskeeps its name and stays the smooth shrink (coverage is still LANCZOS);nearest,kcentroidand pixel-unfake frames are unchanged, and a picture at its own size is copied as it is. Colour is no longer sharpened, so a scaled scene layer with no transparency (a painted background) is a little softer than LANCZOS drew it. A tween's scale (normalize_tween_scale) is left on LANCZOS: it scales an opaque canvas before the key is removed, where there is no coverage to divide by. docs/video-pipeline.md, docs/pixel-unfake.md, docs/sheet-slicing.md, docs/scene.md.
v2.19.0 - A loop's cells are scaled without a light rim or a green tint at the edge, and front and back stills keep their view
video-loopscales its cells with coverage and colour taken apart (resize_cell, used bybuild_strip, so the strip, the GIF, the WebP andvideo-cycle-align's rebuild all get it). The strip used LANCZOS over premultiplied RGBA, whose negative lobes weigh the colours across an edge against each other and then divide by the edge's low coverage; on a keyed frame, whose edge holds a light rim outside a dark outline and ink with a little of the key's green, a scaled cell drew a lighter rim and greener ink than the frame had. Coverage now keeps LANCZOS's edge, held between the least and the most coverage of the source pixels the colour mixes from (no halo outside the silhouette, no hole inside it); colour is a Hamming mix of premultiplied colour, which has no negative lobe, so every pixel's colour is a mix of the colours under it. On a synthetic outlined figure (tests/video/test_strip_resample.py), LANCZOS left 1,462 pixels at 0.97x and 1,750 at 1.03x with a colour none of the source pixels under them had, and none are left now; the strands, 0.5-1.4 px wide, keep LANCZOS's coverage. Colour is no longer sharpened, so a 1 px line inside the body is a little softer when a cell is enlarged. A cell at its own size is copied as it is, as before. docs/video-pipeline.md.- A front or back still keeps its view when redrawn from another picture (
STILL_VIEW_TEXT["front"],["back"], read bystill_view_text): redrawn from a side picture with the clip's one line, a front still could keep part of the picture's turn — feet frontal, head and chest turned a little toward the side the picture faces. The still sentence now says the whole body and head face the viewer squarely, the chest, hips and toes point straight at the viewer, the face is centred between both ears and it is not turned toward either side even when a reference picture shows the character from another angle; the back one says the same from behind, the face hidden and not looking back over the shoulder. It is used whatever the reference's view (a caller does not always know it). The clip'sVIEW_TEXTis unchanged. - Measured on codex
image_gen(subscription), five humanoid characters, three takes per arm, judged blind on full-resolution crops plus an eye-offset metric: side reference to front, 15 of 15 frontal with the old line (the turn did not reproduce on this model) and 15 of 15 with the new; side reference to back, 15 of 15 straight backs either way; front reference to front, 14 of 15 old and 15 of 15 new. Method: docs/video-pipeline.md.
v2.18.0 - A walk's jumping frames are remade by RIFE, its jolt is measured, and a direction set shares one cycle
- Jump frames are repaired (
video-loop --repair auto, the default for walk and run): a step whose coverage change is 1.4x the loop's median, over the whole body or the hair behind it (--facing leftmirrors that box), is a jump, and the frame that broke it is replaced by the RIFE frame half way between its two neighbours — at most three, worst first, never next to a frame already made; every other frame stays the video's own. A single stray frame, which breaks the step into it and out of it, is the one remade. The report'sjump_repairnames the frames, the scores before and after and the interpolator; with a frame replaced the seam gate reads the rendered cells.--repair offcuts as filmed. On the 2026-10-03 eight-direction set it replaces the frames the experiment did in 8 of 10 views (the other two differ by one frame). - RIFE is
rife-ncnn-vulkan20221029 withrife-v4.6, found bySPRITE_GEN_RIFE, thenPATH, then wheresprite-gen rife installputs it, and located only when a frame is to be made. Colour is interpolated premultiplied and coverage separately. Measured: 0.33-0.41 s a call on an M4 Max GPU; 2.8-3.0 s in a Modal Linux container through Mesa llvmpipe, with the same frame; the binary's own CPU path (-g -1) is wrong and never passed. Code and weights are MIT. CI installs it withsprite-gen rife installand runs it on llvmpipe. - Install RIFE in one line: new
sprite-gen rife installdownloads the release zip for macOS, Linux or Windows (x86-64), checks its pinned SHA-256 before unpacking, keeps the binary, the model and the licence (about 35 MB), and puts them in the user data directory (SPRITE_GEN_DATA_DIR, else~/.local/share/sprite-genor$XDG_DATA_HOME,%LOCALAPPDATA%on Windows), staged and renamed into place. It ends with a check frame through the installed binary.--zipinstalls from a zip already downloaded,--dirinstalls elsewhere and prints theSPRITE_GEN_RIFEline,--forceunpacks again. - A walk still cuts without RIFE, and says so: where a frame is to be made and no RIFE is installed,
video-loop --repair autocuts the loop as filmed —jump_repairreadsapplied: falsewith the reason and the install line, and stderr carries one warning — andvideo-setskips that state's cycle alignment (cycle_align.<state>.applied: false, listed under the set report'swarnings, one warning line). Asked for by name, it fails:video-loop --repair onandvideo-cycle-align. A RIFE that is found and then fails is an error in every mode. Cutting a loop again removes itscycle.source/, so the next alignment reads the new cut. - The jolt index is reported on every walk and run (
joltin the loop report), read after the repair: how far each step strays from its neighbours' mean over the median step, the hair's, and the head's frame-to-frame moves sideways and up and down in % of the body height (largest, median, largest over median, range). Beyond the reference bounds (index 0.43, head sideways 0.75 %) it is a warning line and the loop is kept;--jolt-max/--head-step-maxturn a bound into a gate (video-loop: loop jolts — …). As a default gate the bounds would have refilmed 16 of 30 Lite takes on two refusals' evidence, and the index does not separate an alternating side walk from a kept Pro walk (0.414), so they stay a reference. - One cycle per direction set: new
sprite-gen video-cycle-align --loop-dir … --loop-dir …resamples every loop to the set's median length at times k·L/L* — a time on a source frame keeps that frame, only times between frames are made by RIFE — turns each to start on a foot strike, and rebuilds its cycle, strip, GIF and WebP in place (cycle_aligninstrip.json). The cut as filmed is kept incycle.source/, so a second run never resamples a resampled loop.video-setruns it for every walk or run filmed in two or more directions (--align-cycles auto, default). Strip metadata now recordscell_height_cap. - Measured walk defaults:
build_prompt(model=...)calms a Lite walk (LITE_WALK_TEXT; Lite read "walks naturally" as a run) and holds a Lite back-diagonal walk's head (LITE_HEAD_TEXT; sideways sway 2.7-3.8 % fell to 1.7-3.1 %, Pro 0.88 %); Pro prompts are unchanged. A front or back walk films from its base still redrawn mid-step (WALK_START_TEXT,walk_start_prompt,starts_mid_step; 1 of 14 front clips walked straight from a standing still, 14 of 16 from a mid-step one);video-set --walk-start redraw(default) draws it with onesprite-gen gen --refcall. - Method, measurements and the regression on the eight-direction set: docs/loop-repair.md.
video-frames --decontam paletteadds no edge contact: within the edge band the gate reads (4 px of the top, left and right edges), a pixel the matte left transparent stays transparent (decontaminate(edge_band=...),cutout(decontam_edge_band=...),edge_bandin the report'sdecontam). A decoded frame's blur runs the subject on into the key as a smooth tail that the video fit reads as a faint blend, so a head a few pixels under the frame edge got faint flank coverage on the edge band and a clip that passes with decontam off was refused with it on, as "the key survived the matte". No floor tells that tail from a strand's side, so the rule is positional; the flank keeps what it recovers everywhere else, and the still fit is unchanged. docs/chroma-alpha.md.
v2.17.0 - Two three-quarter views: a character walks down and up to the right as in an isometric game
front_diagonalandback_diagonaljoinside,frontandback(VIEW_TEXT): three-quarter views turned to the right, the two an isometric game adds between the side and the front or back. Turned over (video-loopoutputs mirrored), they give the left-hand two, so five views make eight directions.- A walk or run in a diagonal names its heading on the screen (
VIEW_MOTION_TEXT): "heading diagonally away from the viewer toward the upper right, like a character walking up and to the right in an isometric game … It keeps the exact three-quarter back angle of the image the whole time … It never turns into a side view." It is filmed pinned to its first frame with the return sentence (PINNED_GAIT_VIEWS,pins_last_frame, used byvideo-settoo) and cut as any walk. A caller's own gait in a diagonal is held to the angle (GAIT_HOLD_TEXT). - A still drawn at a diagonal from another picture has its own view sentence (
STILL_VIEW_TEXT,still_view_text(direction, facing)): the whole body and head turned about 45 degrees, the face hidden for the back one, the feet pointing the same way. The clip's view sentence points at the image instead ("turned exactly as in the image"). - Measured on the API, 480p 3 s, pinned, five humanoid characters twice each: the front and the back diagonal walk kept their angle in 10 of 10 each; the sentence that only said to walk "toward the way its body faces in the image" kept a back diagonal in 0 of 2. Idle and attack keep a diagonal angle (4 of 4). A diagonal run kept it in 2 of 4. Method: docs/video-pipeline.md.
v2.16.0 - Every walk and run moves naturally in place, and a caller's own gait is held there
- Every walk and run, from every view, now says only that it moves naturally, which way it faces and that it stays in place (
MOTION_TEXT,VIEW_MOTION_TEXT): the side walk "walks naturally in place, as if on a treadmill, without moving across the screen", the side run "runs naturally in place …", and the front and back runs "runs naturally in place, facing (away from) the viewer, as if on a treadmill …". The side sentences said "moves in place on a treadmill" as a place (the form that sometimes drew a treadmill under the feet) and the side walk asked for "an even left-right or front-back rhythm" (the wording that made front walks step sideways before 2.13); the front run spelled its strides out (the form that made front walks march before 2.15) and said "toward the viewer" and "without coming any closer" in one clause. On one character, 480p 3 s on the API: the front run kept facing in 2 of 2, the side run ran in 2 of 2, the back run kept facing away in the one clip whose frames passed, and the side walk walked in 2 of 2. - A caller's own walk or run paragraph (
build_prompt(motion=...)) is followed byGAIT_HOLD_TEXTfor its view: it stays in place as if on a treadmill and keeps facing the viewer, away from the viewer or{facing}the whole time. A request interpreter can now ask for a sneak, a march or a lazy stroll and the engine keeps it on the spot and turned the way the image faces, as it already held an attack's grip (HOLD_TEXT). On one character, one clip each: a march lifted the knees high and stayed in place, a stroll from behind kept facing away, a tiptoe sneak kept facing the viewer but read only as a slightly hunched walk. build_prompt(..., pinned=True)gives any state the pinned template (PINNED_LOOP_TEXT, the return to the first pose) instead of the evenly paced repeat; left out, onlyPINNED_LOOP_STATESget it, as before. A caller that pins a walk or run (video --last-frame) says so; two pinned front walks closed on their first frame. Method: docs/video-pipeline.md.
v2.15.0 - A front walk walks naturally, and a slow or drifting walk still finds its loop
- A walk seen from the front or from behind now says only that it walks naturally, which way it faces and that it stays in place (
VIEW_MOTION_TEXT): "walks naturally in place, facing the viewer, as if on a treadmill, without coming any closer". The 2.13 sentence spelled out the steps, and some takes marched in place with the knees lifted to the waist and the arms held stiff. On one character, two clips per sentence on the API: the 2.13 sentence marched in one of two; "walks naturally" swung the arms, kept the knees low and kept facing the viewer in both. How a character walks is the caller's to say, so the default stays generic. The front run keeps its sentence. docs/video-pipeline.md. - When
video-loop --anchor motion-autofinds no walk or run cycle, it now looks once more (sprite_gen/video/gait_fallback.py). A front walk asked to stay in place sometimes comes toward the camera, and the body grows through the clip, so the same pose never matches itself in size: when a straight-line fit of the subject's height changes by 3 % or more over the clip, every frame is scaled back to the first frame's height about its foot point, and the search, the cells and the seam gate all read the scaled-back frames. A calm walk in long clothing can also take longer than half the clip per cycle, the most the first search confirms: the second search allows up to 60 % of the clip and at most 2 s (43 frames of a 3 s clip at 24 fps, where the first stops at 36). - Only a failed search reaches this, so a clip that looped before is cut exactly as before, and every gate, the seam limit included, is unchanged. An explicit
--max-lenstays the ceiling. The report records what was tried ingait_fallback; when the second search fails too, the error still starts withvideo-loop: no periodic cycle foundand says what was tried. - Measured on six stored 3 s front walks that had failed with
no periodic cycle found: four loop now. Three takes of a kimono that hides the legs walked a 27 to 39 frame cycle (one clip grew 3.9 %, two grew 11 % and 16 %), and a front horse walk grew 6.4 % with a 42 frame cycle. One of the other two still shows no repeat; the other finds a 38 frame candidate that the seam gate refuses. On the walk clips we have kept, the median height change is 0.5 % and nine in ten stay under 2.7 %. Method: docs/loop-review.md.
v2.14.0 - A single still can be drawn to a layout guide with crown and floor lines
gen --layout-guideattaches the one-slot form of the row layout guide after any--ref: the frame, the inner safe box at the row guide's 9.4 % margin, the centre line, and an orange crown line and a teal floor line one margin inside the safe box (about 19 % and 81 % of the frame height). The prompt says what each line means: the anatomical top of the skull on the orange line, ignoring hair, hats, raised limbs and props; the supporting soles on the teal line, which is a ground-contact line and not a frame edge; nothing of the guide in the output. A still drawn from words tends to fill its frame top to bottom, and an in-place motion then has no room above the head. The lines sit inside the box because on its edges a crown line leaves hair and hats to fill the room above it and a floor line reads as a border the feet float above.- The guide is an attached image: openai sends the call to
/images/editsand bills the guide as image input, and--transparentsteps down to chroma keying as with any--ref. Models differ in how closely they follow it; measure the one you use. The report records the guide's cell inextra.layout_guide. Usage: docs/gen.md.
v2.13.0 - A front or back walk walks straight, and a walk loop is cut in seconds
- A walk seen from the front or from behind, and a run seen from the front, now have their own sentence (
VIEW_MOTION_TEXTinsprite_gen/video/batch.py): the steps lift and land straight forward and back under the body, toward the viewer or away from it "as if on a treadmill", and the body never turns to the side, steps sideways or crosses its feet. A walk also asks for a calm, natural cycle with small, even steps that never kick a leg out to the side. The walk sentence every view shared asked for "an even left-right or front-back rhythm", and a character facing the viewer read it as stepping sideways: crossed feet, side kicks, a body turned to three-quarters. A side view and a run seen from behind keep the state's sentence. - Measured on Grok (subscription), 480p 3 s, nine humanoid characters twice each, judged on frame sheets with the variant hidden: a front walk kept its facing and walked in 7 of 18 clips with the old sentence and 16 of 18 with the new one (12 to 13 of 18 without the calm-steps clause, which still crossed its feet or kicked sideways in five); a back walk in 8 of 10 and 10 of 10; a front run in 11 of 18 and 15 of 18. "on a treadmill" said as a place was sometimes drawn under the feet; "as if on a treadmill" was not. A walk drawn at a three-quarter angle still turns to a side view in about half the clips with every sentence tried. Method: docs/video-pipeline.md.
video-loop --anchor motion-autofinds its two tracking regions with FFT correlations instead of copying the masked patch out once per offset. On three 3 s walk clips at 544 px the region search took 1.0 to 1.4 s of CPU instead of 22.6 to 37.4 s, and full loops from the same frames gave the same cycle and byte-identical strips. Costs agree with the direct form to about 1e-6, so two offsets that tie within that may swap. docs/loop-review.md.
v2.12.1 - The error body is masked as the provider sent it, before it is put on one line
- The error body is now masked string by string, as the provider sent it, before sprite-gen puts it on one line. v2.12.0 masked the finished line, where JSON,
reprand the line join had already written a line break, a tab or another control or invisible character as\n,\t,\x..or\u....(and the video verbs' JSON fallback any non-ASCII character as\u....). A key, aBearervalue or a URL query right after one of those kept a letter or digit in front of it and was printed as sent, so v2.12.0's "only a letter or digit in front makessk-/xai-/bearerpart of a word" was wrong there. It holds now, and the letter or digit is the provider's own:task-…andxbearer …are still words, and so is a key after the two characters\nor%0Athe provider wrote itself. ABearervalue after a tab or a line break, and the credential the request carried when it holds a quote or a non-ASCII character, are masked too. An API key or login token of the usual shape that the request carried was masked in every case in v2.12.0 too, and still is (a number in the body equal to it included). - A URL query is masked wherever the URL starts; after
_, a letter or a non-ASCII letter it was printed as sent. - Nothing else in the line changes: a body with nothing to mask prints byte for byte what v2.12.0 printed. When two field names of one error object mask to the same text, the line keeps the later one. A body nested some 500 levels deep can exceed Python 3.11's recursion limit while it is masked; the line then turns into a traceback (with no body text in it) instead of a refusal line. Provider error bodies are a few levels deep.
v2.12.0 - A refusal names the provider's code, and says when it was the content policy
- A provider refusal line now carries the provider's own code after the status:
openai-gen: image request failed (HTTP 400) code=invalid_value; no retry or provider fallback. The code iserror.code(or, for xAI's synchronous errors, a top-levelcode) and is printed only when it matches^[A-Za-z0-9_.:-]{1,64}$. The video verbs read the code out of a failed poll'serrorobject too. - The image paths now print the provider's error body too, as received, at the end of the line:
openai-gen: image request failed (HTTP 400) code=invalid_value; no retry or provider fallback: {"error": {...}}(JSON on one line, other text with its line breaks as\n, nothing for an empty body; this includes 401/403). Before, the body was dropped and a failure was hard to diagnose. Two things are masked with[redacted]: strings shaped like an API key (sk-…,xai-…, aBearervalue, the credential the request carried; a key the provider already masked is left alone) and URL query strings, where signatures live. The video verbs, which already printed what xAI said, now go through the same mask, applied before their 300-character cut so a key the cut would split is still masked. A key or aBearervalue right after_or-(api_key_sk-…,x_Bearer …) is masked too; only a letter or digit in front makessk-/xai-/bearerpart of a word. The body can repeat the prompt: a product that shows sprite-gen's stderr to its own users decides what to keep. Everything in front of the body is unchanged. - A code the provider documents as a content-policy block turns the line into
<verb>: refused by the provider's content policy (HTTP <n>) code=<code>; no retry or provider fallback, so a caller can tell "change the request" from an auth, quota or parameter error by one fixed phrase. OpenAI'smoderation_blockedis the only such code (the image guide callserror.codethe stable discriminator); itsmoderation_details.moderation_stagefollows asmoderation_stage=input|output|unknown. xAI'sinvalid_argumentis not one: it covers moderation and parameter errors alike. - An xAI clip that finishes with
video.respect_moderation: falseis now<verb>: generation <id> refused by the provider's content policy (HTTP 200) respect_moderation=false; nothing was writteninstead of "done but reported no video url". The xAI REST image answer has no moderation field, so a grok image refusal carries its code only. (HTTP <n>)is unchanged, and the body comes after it and everything else, so anything that finds the status with\(HTTP (\d{3})\)reads these lines as before, whatever the body says. The policy table issprite_gen/gen/refusal.pyPOLICY_CODES. Line shape: docs/gen.md.
v2.11.0 - An attack is one strike, and its whole clip is the loop
MOTION_TEXT["attack"]asks for one attack (windup, strike, held impact pose, recovery to the exact starting stance) instead of the same attack twice, andbuild_prompt(motion=...)no longer adds a repeat sentence after a caller's paragraph (REPEAT_TEXTis empty;HOLD_TEXTstill follows it once). The clip is pinned to the canvas as before, so it runs stance -> strike -> stance, andvideo-setcuts it whole withvideo-loop --cycle pinned, as it already did an idle (PINNED_LOOP_STATES= idle, attack). The attack keeps its own template (ACTION_TEXT_STATES). Before, the one-shot or period search cut a two-strike clip into loops that started mid-strike, held both strikes, or kept only the held pose, and some of those passed the seam gate.video-setasks attack clips for 2 s (STATE_DURATION_SECONDS), down from 4. One strike at the stated timing is about 1.6 s; asked for 3 or 4 s, the clip still struck once and held the impact pose for about half of it.- Measured on Grok (subscription), 13 characters pinned to their canvas: 13 of 13 loops at 2 s in 480p and in 720p, 13 of 13 at 3 s, 12 of 13 at 4 s (one clip touched the frame edge); every loop is the whole clip and starts on the ready stance. A 2 s clip is half the video seconds of the 4 s one.
v2.10.3 - An attack keeps what the other hand holds where it is drawn
- What stays still in an attack is one sentence,
HOLD_TEXT["attack"]: every grip stays the one the image shows (one hand stays one hand, both hands stay both hands, nothing let go or switched to the other hand), a hand the strike does not use stays where it is drawn with whatever it holds, and the body keeps facing the same direction. The built-in attack sentence ends with it instead of naming the grip twice, andbuild_prompt(motion=...)now adds it once after a caller's own motion paragraph, before the repeat count. A request interpreter writes its motion before the still exists, so it cannot know where a shield or a lantern is drawn; asked to keep "the shield raised in front", a clip brought a shield drawn behind the body to the front and the strike read as a shield bash. The caller writes the choreography, the engine says what stays put. - Measured on Grok (subscription), 4 s 480p pinned to the canvas: a sword-and-shield knight whose shield is drawn behind the body kept it there in 4 of 4 clips with the built-in sentence and 6 of 7 with a caller's choreography followed by the hold sentence. Characters holding a shield and a hand axe, a spear and a shield, and a lantern and a dagger kept the second item where it was drawn, and a two-handed axe stayed two-handed. Method: docs/video-pipeline.md.
v2.10.2 - The spill judgment keys only the subject, and decontam keeps gold
video-frames --spill auto(andvideo-set, which judges each item'scanvas.png) keys only the subject window of the reference still instead of the whole still. A canvas padded for motion room is mostly key, and keying all of it cost about 0.14 GiB more per megapixel of canvas, past 4 GiB for a 30-megapixel canvas, while keying the frames themselves stays near 1 GiB. The window is the box of pixels the hard cut cannot erase plus one keyed pixel all round, and the painted key is read on the whole still, so it gives exactly the whole still's counts: the decision and the frames do not change. A window over 6 megapixels is judged on every n-th pixel instead; the report recordsreference_size,reference_windowandreference_stride. Background-key detection now reads an image a band of rows at a time. On synthetic padded canvases the judgment peaks at 0.42 to 0.56 GiB from 8 to 39 megapixels, and a synthetic 1080p clip judged against a 39-megapixel canvas runsvideo-frames --decontam palettein 1.1 GiB.--decontamkeeps gold and yellow on stills. A gold a little darker or yellower than the palette's own read as a warmer palette gold with some green mixed in, so gold edges and small gold drops came out orange and partly see-through. The still fit now counts a palette colour at the pixel's own luma as the subject's colour within the subject's own spread (how far its interior sits from the palette); a pixel deeper than a still's antialiased edge (2 px) without the key's hue, or an edge pixel with the colour of the material right behind it, is the subject's own colour; and where the matte changed such a pixel it gets its source colour and coverage back. That last part matters forcutout, whose RGB matte scores key tint on the channel average: that calls yellow green, so the matte unmixed gold by itself. On a synthetic gold scene every decontam path now matches the clean YCbCr matte, wherecutout --decontam paletteleft 39 % of the solid gold edge see-through. On the procedural ground-truth set key contamination falls from 0.07 % to 0.03 % (RGB matte) and from 0.16 % to 0.12 % (YCbCr matte), halos shrink and recall stays the same. The video fit is unchanged. Reports gainmaterial_spreadandrestored_px. Method: docs/chroma-alpha.md.
Gold showcase
A synthetic gold scene (the fixture of tests/frames/test_decontam_gold.py) through cutout --decontam palette (RGB matte) and gen's YCbCr matte with decontam, v2.10.1 then v2.10.2, on dark and on white.
![]()
v2.10.1 - Attacks keep the grip the image shows
MOTION_TEXT["attack"]no longer names one hand. What the subject holds is kept exactly as gripped in the image — one hand stays one hand, both hands stay both hands — and is never let go, switched to the other hand or taken in an extra hand. Naming the hand nearest the viewer for a weapon the still draws in both hands made the clip let go of it on the windup and grab it again for the strike.
v2.10.0 - Edge decontamination gives thin strands their own colour back
- Add opt-in edge decontamination,
--decontam auto|palette(requestchroma.decontamfor the row extractor andinspect). After the matte, each edge pixel is explained as a blend of the locally measured key background with one colour from a palette learned on the subject's own interior. The colour written is that palette colour at the pixel's observed luma, so thin hair strands and outlines come back in the subject's hue: not green, and not the orange that despill's channel gain produces.palettedemands the pass and fails where it cannot run;autoruns it wherever it applies and records why it did not elsewhere. Available oncutout,gen --transparent(chroma keying),video-frames/video-set(video fit, one palette per clip) and the row extractor. Every default staysoff, which returns existing output byte for byte. On a procedural ground-truth set, key contamination at the edge falls from 22.5 % to 0.07 % on stills and from 33 % to 11 % on H.264 frames; halo against the true composite shrinks on dark and white backgrounds, and strand recall rises from 84 % to 99 % (stills) and from 82 % to 91 % (frames). Method, guards and limits: docs/chroma-alpha.md.
v2.9.0 - Idle stands still and closes on its first frame
MOTION_TEXT["idle"]keeps both feet planted flat for the whole clip, limits the motion to breathing, a settle of the arms, hair and loose cloth and one blink, and names walking and marching in place as what not to do. A side-view full body asked for "a subtle weight sway" and an evenly paced loop tended to step in place.- Idle is pinned to end on its first frame (
PIN_LAST_FRAME_STATES) and its template (PINNED_LOOP_TEXT) asks for that return instead of an evenly paced repeating motion. video-loop --cycle pinnedkeeps a pinned clip whole as the loop (every frame but the last, which re-renders the first) and gates it on the pin: the last frame has to land withinmax(seam_max x the mean step, PIN_NOISE_MAX)of the first. A near-still idle moves so little per frame that the seam ratio read its re-render noise as a jump. A clip that ends in another pose fails with its own message.video-setcuts idle this way (PINNED_LOOP_STATES).
Idle showcase
Nine side-view idles before and after this release, each strip played at its own speed (idle-nine.mp4 is the same comparison as video).
![]()
v2.8.1 - Tight clips pass their own edge and corner checks
video-frames --allow-subject-edge-contactfails only on a frame where the key alone reaches the edge. A frame where the subject touches the edge carries key-tinted pixels beside it (its antialiased fringe, or the key reflected on metal) and is accepted with them, the same reading a mixed contact already had in the refusal message. Before, a few such pixels failed a tight clip as leftover background.video-loopkeeps its 8 transparent columns on both sides of every cell even when the subject reaches the frame's side edge, so no cell corner is the subject and the GIF/WebP corner check holds. A crop that stays inside the frame is unchanged.
v2.8.0 - Tight framing for a fixed body height
video-canvas --fit tightframes a still with no room for the motion: it drops the empty rows above and below the subject (keeping headroom of 4 % of the subject's height), keeps the still's width, and pads to the nearest framing the video model returns (9:16, 1:1, 16:9). The subject is never scaled or cut. A long, low subject in a square still becomes a 16:9 frame it fills, so a--body-heighttarget is reached at a low clip resolution by scaling down rather than up. A motion that leaves the frame is clipped. The default--fit stateis unchanged, and the report now says whichfitframed it.video-frames --allow-subject-edge-contactaccepts the subject at the frame edge and still refuses leftover key background there. The report'sedge_policynames the rule that applied.video-set --fit tightframes every item that way and lets its subject reach the edge. It refuses--shape, and a cached canvas framed with another fit is not reused.--body-heightmeasures the standing height on the clip's first frame, the base still's pose that every clip starts from. The tallest grounded frame, used before, is an attack's windup with the weapon overhead, and scaling that to the target made the character smaller in its attack than in its walk. The strip sidecar recordsbody_ref,body_src_h(the standing height as filmed) andscale, so a strip whose cells were upscaled says so. Without a target nothing changes.
v2.7.0 - Timed attack clips pinned to their start
- Attack clips are timed strikes pinned to their start.
MOTION_TEXT["attack"]asks for the same attack twice, each a windup, one strike in front, a held impact pose and a recovery to the exact starting stance with approximate times, keeps what the subject holds in the hand nearest the viewer, and forbids turning. The attack template drops the "evenly paced" line, keeps what the subject holds inside the frame and asks for crisp frames.video-setasks attack clips for 4 s by default (other states keep 3 s;--durationstill sets one length for all) and passes the canvas as--last-frame, so the clip ends where it began. The item report records the clip'sdurationandlast_frame. build_prompt(..., motion=...)accepts a caller's own motion paragraph in place of the built-in state sentence, keeping the engine's frame, camera, background and design rules.video-set --body-height Npasses one standing-height target to every state's loop (video-loop --body-height), so a character comes out the same size in every state even though states use differently shaped canvases.
v2.6.0 - Automatic local gait selection and XY motion correction
In
motion-auto, an uncertain fine XY search-boundary match can emit the selected frames unchanged only after the existing rendered-cell seam gate and animation checks pass. Reports and the CLI expose the rejected measurement and unapplied correction. Other failures and explicitmotionregistration remain strict.Add explicit
video-loop --anchor motionfor reviewed fixed cuts with head and torso regions. Masked XY registration and boundary velocity determine one integer translation ramp; padded cycle PNGs retain the original keyed pixels. Reports record the inputs and shifts, and the unchanged seam threshold measures the rendered output. Automatic cycle selection and existing anchor defaults are unchanged; batch generation rejects this review-only mode before provider work.Add opt-in
--anchor motion-autofor walk/run invideo-loopandvideo-set: discover stable texture regions, separate drift during local repeat analysis, and apply the same XY boundary-velocity ramp without manual cut/region inputs. Keep source motion and pixels in padded cycle frames; gate the rendered cells. Reports expose automatic tracking, candidate selection, and correction. Existing defaults stay unchanged.
Gait showcase
Human and animal loops produced by video-loop --anchor motion-auto, shown at their original playback speed.
| Humans | Animals |
|---|---|
v2.5.6 - Walk and run loops close their wrap with one ramp
- Walk and run loops close their wrap with one ramp.
video-loop --anchor body(now the default forwalkandrun) measures how far the last frame's head and torso sit from the first's, once, by whole-pixel registration over the top of the first frame's box, and shifts frame k by that offset times k/L. It never fits frame by frame: per-frame fitting turns a head bob into a full-body shiver, and the feet anchor pins the planted foot, which a quadruped moves every step. A cycle whose wrap already lands (most bipeds) is left byte-identical; the strip sidecar recordswrap_dx_pxandseam_ratio_after_anchor.--anchor feetand--anchor noneare unchanged, and other states keepnone.
v2.5.5 - A lone step under the gait floor is refused, not looped
- Gait loop selection no longer keeps a lone step. When the deepest repeat sits under the gait floor and no repeat near twice it is about as good,
video-looprefuses withno periodic cycle found(the same words as a flat profile) instead of looping half a stride; the failure report carries the guard's verdict and the minima it weighed. A quadruped whose near and far legs read alike produced exactly this on a walk clip. The doubled period is now searched among the profile's own minima within three frames of twice the step, since a real stride rarely lands on exactly 2x. Clips whose full gait repeats are selected as before.
v2.5.4 - Room behind the attack canvas
- Attack canvases keep 20 % of their width empty behind the subject (
--trail, a new wide-canvas margin next to--lead). A long weapon drawn back before the strike reached the back edge of the old layout and the frames gate refused the clip; the samurai and katana samples that needed hand-padded stills in v2.5.3 now pass from the raw still. Headroom, lead and every other profile are unchanged, and--trail 0restores the previous placement. video-set --baserefuses a direction the prompt table does not know (back,front,side) instead of acceptingleft=and animating it with the default facing.- The facing test suite names its orchestrator scrub sample neutrally.
v2.5.3 - Reference facing controls and observed action returns
Reference edits can opt into
gen --facing right|leftto request orientation in the generation prompt. The defaultpreserveleaves existing generation callers unchanged.Facing inspection is record-only by default:
gen,videoandvideo-setuse--facing-fix none. Explicitmirrorcorrects an observed opposite in the output copy;gen --facing-fix regenregenerates once, rechecks and mirrors a remaining observed opposite.video --direction sideand batch side inputs inspect the still before animation. Batch uses one shared observation per side still; the requested facing drives canvas placement and motion prompts independently of the observation. Original inputs stay intact; cached canvases and prompts must match the requested policy.Direction reports include model, requested direction, model-reported confidence and correction evidence.
final_direction_sourcedistinguishes observations from values derived by mirroring; none is independent verification. Failed or uncertain calls recordunknownwith a reason and continue without correction.Known limitation: direction detectors can misclassify a correctly oriented still even at high confidence. Prompts request direction but cannot guarantee it; inspect the still before opting into correction. Front-facing observations are unchanged, and mirroring does not preserve accessory handedness.
Synthetic regressions cover incorrect observations with byte-preserving defaults, explicit mirror pixel symmetry, regeneration rechecks, prompt/canvas agreement and existing callers.
Attack loop selection searches longer action periods with observed repeat context and raises the periodicity requirement when less than a full repeat is available. The seam limit remains 2.0; walk and run selection are unchanged.
One-shot selection requires an observed departure and return with resting frames on both sides. Endpoint-relative motion can identify a return after a held strike, while truncated actions, stationary clips and incoherent jitter are refused. These pixel measurements do not establish anatomical correctness.
Loop selection and seam failures write structured reports with the rejected candidate, search window and repeat/return evidence. Successful reports explicitly record
status: passed; undefined ratios are represented as JSONnull.Attack canvases reserve overhead room as well as forward room for raised weapon swings. Wide padding now honors headroom while preserving 16:9 and the still pixels; idle, walk, run and jump defaults are unchanged.
The attack motion prompt now tells the video model to strike with the weapon the character already holds and to keep its gear and outfit as drawn, so an armed sprite does not fall back to punching or grow new equipment mid-clip.
Attack showcase:
docs/assets/attack-slime.gif,attack-fox-hood.gif,attack-paladin.gif,attack-claudecy-samurai.gif(two-handed cut) andattack-claudecy-samurai-onehand.gifwere produced by this release's pipeline (still, canvas, Grok Imagine clip, frames gate, loop selection) with no manual cut points. On a ten-character side-view sample every attack closed its loop; two clips needed the built-in single regeneration because the model framed the raised weapon above the top edge.
v2.5.2 - Cleaner video spill correction
- Automatic spill selection distinguishes the key hue from yellow/cyan or red/blue material and discounts dark contamination in the reference matte edge band. Bright key-coloured details still count as material.
- Full correction removes faint key casts while recovering brightness without amplifying residual colour differences into secondary casts. The declared key defines channel groups even when the painted background is dim or asymmetric.
- Alpha, conservative
smallcorrection and gait selection logic are unchanged. Existing source colours without the key hue remain; this does not reconstruct the original material palette. - Synthetic regressions cover colour preservation, bright edge details, secondary-cast amplification and imperfect painted keys.
v2.5.1 - More consistent automatic walk and run loops
- Automatic gait cuts now score whether neighbouring poses repeat one cycle later as well as the last-to-first transition. This reduces selection of irregular motion that happens to have a plausible seam, without preferring an earlier or later part of the clip.
- Loop reports expose the selected neighbourhood, normalized repeat error and combined score in
cycle.selection. Existing period detection, manual cuts, non-gait states and source playback speed are preserved. - Synthetic regressions cover steady and irregular motion in both time directions. The repeat metric measures temporal consistency; it does not identify anatomical left/right limbs or repair malformed source motion.
v2.5.0 - API image generation and smoother loop cuts
New
openaiimage provider:sprite-gen gen --provider openaicalls the OpenAI Images REST API with nothing butOPENAI_API_KEY— the credential a headless container (a Modal worker, CI, a SaaS backend) can have, where thecodexroute's interactive ChatGPT login cannot exist. New images go to/v1/images/generations,--refswitches to/v1/images/editsas multipart with the references as repeatedimage[]parts in order (up to 16), and gpt-image's inline base64 is decoded and published as a verified PNG without resizing. Default modelgpt-image-2.5-flare.--transparentasks forbackground: transparentwithoutput_format: png— the same measurednativestrategy as codex, and a live run came back 84 % alpha-0 with the subject at alpha 251–254.--aspect-ratiomaps to one of the gpt-imagesizevalues that satisfy the API's constraints (both sides divisible by 16, ratio within 1:3..3:1, 655,360–8,294,400 pixels); a ratio with no exact size is refused rather than rounded to a nearby one you would be billed for. A missing or empty key, a rejected key and a failed request are all terminal: this provider never falls back to codex, to another credential, or to a retry.sprite-gen stays subscription-first.
codexandgrokrun on a subscription you already pay for;openaibills per call, so it runs only when--provider openainames it.SPRITE_GEN_DEFAULT_PROVIDER=openaiis refused rather than honoured, the guidedworkflowflow neither offers it nor saves it as a preference, no availability fallback targets it (a codex outage still reaches grok, never metered credit), and havingOPENAI_API_KEYin the environment changes no route by itself. Every call that does spend API credit — image or video — prints one stderr line naming the charge before the request leaves.gen --quality low|medium|high|xhigh|max|autoandgen --resolution 1k|1.5k|2k: the two knobs an image is billed on, as one shared vocabulary with a per-provider subset. grok Imagine carriesauto|low|mediumand all three resolution tiers and prices an image on the pair; openai carries the whole quality range and takes its size from--aspect-ratio; codeximage_genexposes neither dial. A knob a provider cannot honour fails loudly instead of being dropped from a request body you are about to pay for. Omitting both keeps every existing call byte-identical. The resolution names are tiers, not pixel counts —1.5krendered 1408x1408 at 1:1 (2026-09-20 measurement) — and the grok subsets were read off the server rather than the prose:qualitydeserializes the wider shared enum and then refuses per model (high→ HTTP 400 "This model only supports the following quality value(s): low, medium, auto."),resolution: 1.5krenders although the capability guide lists only 1k and 2k, and an unknown field is not refused at all, which is why these names are checked locally. Grok image reports carryextra.qualityandextra.resolutionwhen the request sent them.video,video-extendandvideo-editannounce the per-call charge on stderr when they run onXAI_API_KEYinstead of the Grok subscription login — one line per submitted job, naming the duration and resolution it is priced on. The subscription route stays silent and no other video behaviour changed.Registering a provider now fails loudly when the workflow catalog has no label for it. The guided flow built its provider choices by zipping labels onto the provider tuple positionally, so a third provider was dropped without a word; labels are a checked mapping (a missing one fails at import) and the flow offers the subscription routes only.
workflowaccess probing knowsopenai— ready when the key is set, withbilling: api-creditand the billing confirmation that goes with it.video-loopautomatic cuts now score the transition actually played from the last displayed frame back to the first. The chooser prefers a step comparable to the cycle's ordinary motion rather than the smallest distance, which could repeat a pose and pause at the wrap. Reports retainnext_frame_distanceas a separate diagnostic.video-frames --spill fullnow lowers the tint threshold as well as lifting the cluster-size limit, so faint key-colour reflections are corrected.--spill autoexamines the reference at the same threshold before selecting full correction, preserving the character's own key-coloured material. The conservativesmallmode and the default 3-second video-set duration are unchanged.Gait auto-detection now considers an ambiguous double-period candidate even when the short candidate exceeds the duration floor. It preserves both phase occurrences at source speed when the longer local minimum is similarly credible and passes the periodicity gate; near-exact short repeats, worse doubles, non-gait states and caller window bounds are preserved. Reports identify this conservative choice with
half_period_guard.reason = "ambiguous-harmonic"andcycle.review_recommended, rather than claiming anatomical stride certainty.Added a loop review guide defining what numeric gates establish, when sequential visual review is needed, and how to record explicit cut/alignment choices without presenting them as automatic decisions.
v2.4.1 - A visible hop is no longer refused as "never leaves its rest pose"
video-loopone-shot detection no longer refuses a visible hop because the rest pose is not one pose. The excursion is admitted by either the peak's height in MADs of the rest noise (as before) or the fraction of the subject's pixel mass the peak moves (new, ≥ 0.4); the report recordsexcursion_movedandexcursion_rule. A body that walked a few steps, hopped 42 px and froze scored 1.8 MADs because the walking preamble and the frozen tail inflate the "rest noise"; by moved mass it scores 1.07. A jittering stand still fails both rules, and clips the MAD rule already accepted are cut exactly as before.
v2.4.0 - Three-second clips and gait windows in seconds
video-set --durationdefaults to 3 seconds (was 6). A repeating motion holds two or more cycles at 3 s (walk strides measured at 0.6–1.3 s across seven bodies), a single action is one hop or swing that the one-shot cut already handles, and 6 s bought only a longer wait — and, for jump, more idle standing between hops.--duration 6still asks for a longer clip.video-loopwalk and run take their period window in seconds (walk 0.5–1.6 s, run 0.3–1.2 s, capped at half the clip) instead of a fraction of the clip length. At 3 s the old 6–31 % window topped out at 0.96 s and put a 1.0–1.3 s stride out of reach: on four walks generated at 3 s it refused one outright and cut another at a half step; with the bounds in seconds all four pass with equal or better seams, and the 6 s results are unchanged. Idle, jump and attack keep their windows.- The strip sidecar (
<name>.strip.json) recordskind(periodic/one-shot/fixed) andloop(falsefor a one-shot), and the spec asset loader readsloopfrom it, so a jump or attack cut as a single action plays once on a trigger instead of repeating. A sidecar without the key is a loop, as before. - The GIF/WebP never ask for more frames than the strip has cells. A cycle longer than the 64-cell cap is subsampled into the strip; the GIF/WebP are cut from those cells, so requesting the cycle length repeated cells back to back, the writer merged the identical neighbours, and verification refused its own output ("64 frames, expected 68" on a 2.8 s jump cycle).
v2.3.1 - Key reflections removed from video sprites
video-frames --spill small|full|autoandvideo-set --spill(defaultauto): remove the key colour a video model paints into the subject — a reflection across metal, a tint on a pale surface — which the chroma engine's trapped-spill pass leaves alone once the patch is larger than its small-cluster cap.autokeys the still the clip was made from and measures its own key-coloured material; none worth the name means every key tint in the clip is spill (full), otherwise the still-pipeline rule stays (small). Colour only — alpha is unchanged — and colours without key tint are untouched.video-framesdefaults tosmall, byte-identical to before; the frames report records the decision underspill.- Known limitation: on pixels where the reflection is removed, colour can lean warm. The correction solves observed = (1-k)·subject + k·key for the subject and so scales the unkeyed channels by 1/(1-k), which amplifies any warm light already mixed in (a pale armour piece can come out slightly reddish instead of neutral silver). A correction that keeps the source still's palette is open for contributions.
v2.3.0 - Grok video modes: first-last, reference, extend, edit
sprite-gen videogains the other Grok Imagine generation modes:--last-framepins the closing frame (alone or with--image), and--reference(repeatable, up to 7) guides the clip with reference images named<IMAGE_0>,<IMAGE_1>, … in the prompt.--imageis no longer required on its own. The image-only request body is unchanged and pinned by a snapshot test; the video → loop pipeline (video-canvas,video-frames,video-loop,video-set) is untouched.- New
video-extend(POST /v1/videos/extensions) continues a 2–15 s clip by 2–10 s and newvideo-edit(POST /v1/videos/edits) changes a clip of at most 8.7 s with a prompt. Both force the classicgrok-imagine-videomodel (the 1.5 model refuses both endpoints), take no resolution / aspect / model flags because the output inherits the input's, check the input with ffprobe before uploading, andvideo-extendrefuses a result shorter than its input. - Local pre-checks refuse, before any call: no input at all, more than 7 references,
<IMAGE_n>tags outside the given references (or with none), 1080p with references, andlast_frame/image+referenceon the classic model. - The
sprite-gen-video-reportcarriesmode(image-to-video,first-last,last-frame,reference,extend,edit),inputs(local paths by role) and, for extend / edit,input_duration; every existing field stays. - Removed the retired
sprite_gen/gen/generate_image.pyshim. It shared its name with thegenerate_image()function thatsprite_gen.genexports, soimport sprite_gen.gen.generate_imagereplaced the function with the shim module for the rest of the process and the nextsprite_gen.gen.run()died withTypeError: 'module' object is not callable— at runtime, not only under pytest. Nothing routed to the shim (no CLI verb, no-mstep, no MCP entry), so the fix is deletion: the old module path now fails withModuleNotFoundError, and the only image-generation entry point remainssprite_gen.gen/sprite-gen gen.sprite_gen._modules.MODULE_DOMAINand the packaging import-surface list drop the row; theimport_probefixture stays as a general isolation device. - Test isolation: the packaging import-surface probe now restores the parent package attribute and
sys.modulesentry it touched, so importing the retiredsprite_gen.gen.generate_imageshim no longer replaces thegenerate_image()function for latertests/genruns.pytest tests/packaging tests/genis green in any order. - Test isolation:
tests/curateimports its shared helper fromtests/framesthrough thetests/root instead of by bare module name, sopytest tests/curatepasses on its own instead of depending ontests/frameshaving been collected first. - The expired-login prescription for Grok video and images no longer names a bare prompt (
grok -p ok): on the grok CLI that starts the coding agent in the current directory, which can read, write and spend on its own. The prescription is now a non-agent round-trip (grok models) run from an empty directory, withgrok loginas the fallback, and the message says so. A test pins the prescription to a non-agent command.
v2.2.1
video-loopgait half-period guard: awalk/runperiod shorter than the state's floor (LoopProfile.min_seconds: 0.6 s / 0.35 s) is treated as one step of a two-step gait and doubled when the doubled period repeats within 25 % of it — the case where a costume hides the legs and the half period dips as deep as the full one, which the depth rule alone returned as a one-legged loop. The report carriescycle.half_period_guard(applied,from,to, depth ratio, orbelow_floor+ why it was left alone).--min-lenstill overrides.video-loopone-shot detection no longer refuses an excursion shorter than the periodic window's lower edge; only a cut under 4 frames or longer than the clip is refused. Short performed actions (a set-down, a nod) come back as the frames they are.video-loop --anchor feet(alsovideo-set --anchor): remove the slow in-canvas drift of a subject the model walked across an "in-place" canvas, so the strip stops sliding once per cycle. A straight line fitted to the body's centre across the cycle carries the drift and not the step; only that line is removed and every cell stands on the mean foot line. Strip meta gainsfoot_anchor,drift_px(drift removed),foot_sway_px(the planted foot's in-gait movement, kept and reported) andfoot_x, and declares the spec loader'sanchoras[foot_x, h]so scenes stand the sprite on its feet; the video-set table row carriesdrift_px. Defaultnonekeeps existing output byte-identical. The first implementation pinned each frame's own foot line instead; in an in-place walk that line jumps to the planted foot every step, so a body that stood still lurched back and forth by the stride. That version never shipped.video-canvas/video-set:cheer,waveandcelebratenow take the wide canvas (raised limbs leave a 1:1 frame at the top corners),video-set --shapeforces one shape for a whole batch (wide costumes), andvideo-setcarriescheer/wavemotion templates that name no limbs.gen --trim-alpha(with--transparent): crop the published PNG to its opaque bbox so the bottom edge is the foot line; the report recordsextra.trim_alpha(bbox,before,after,margin_px). The.raw.pngis untouched.
v2.2.0 - Independent asset tools and optional scenes
Added standalone
background-tile,shadowandinspect-motioncommands. They accept existing artwork and report tile joins, anchor-preserving shadow projections, repeated poses and explicit foot-contact measurements without changing source animation.Added optional
scene-renderandscene-inspectwith asset references, planes, placement, playback rate, camera, lighting, PNG/MP4/GIF output and layer/placement export. Scene applies only verified stride for the matching asset and an explicitly chosen direction.Added one read-only adapter for PNGs, external frame descriptors, existing loop strips and runtime atlases, preserving native timing and anchors. Source fingerprints bind measurements to loaded content; output publication uses shared locking and atomic writes.
Split the command catalog into ordered sprite pipelines, independent tool groups and optional workflows. Added background recipes and asset/scene contracts to the skill and documentation, plus a 20 fps, 256-colour village GIF below the existing README showcase.
Raised the Pillow minimum to 12.3.0 for its upstream security fixes; existing environments must update separately to satisfy the new requirement.
Grok images now call xAI Imagine directly for generation and one-to-five-reference editing, without spawning Grok Build. The default image model is
grok-imagine-image-2.0;--modelnow selects the image API model. Responses are decoded and published as verified PNGs with existing chroma cleanup preserved.Images and videos share one credential reader: the user's Grok subscription login first (
GROK_HOMEsupported), even withXAI_API_KEYconfigured. Only an absent login file permits API-credit use; invalid, expired or rejected logins never fall back to it. Image reports expose the auth source and API endpoint. The workflow guide checks the same source and explicitly confirms API-credit billing for either media type. Expired login and request failures stop without agent fallback or automatic image request retries.Standalone image-to-video requests are routed by the sprite-gen skill itself; no separate video skill is needed.
Flat-border key detection accepts imbalanced chroma channels using the shared
is_border_key_candidaterule in cutout, extraction and video preparation. Interior subject-colour classification remains unchanged.Painted-key removal is limited to the key family and its connected antialiased rim, preserving isolated look-alike colours inside the subject. The declared-key removal radius remains unchanged.
v2.1.1 - Chroma keying follows the painted background
- Chroma keying measures the key distance from the background colour the generator actually painted (detected from the flat borders,
detect_background_key_rgb) as well as from the pure key, incutout,extract,slice-sheetandvideo-frames. Image models paint#00FF00as (8, 162, 24) and darker; that colour sat on the 96 radius from pure green and keyed half-and-half pixel by pixel. The radius is unchanged. Reports carrychroma_key_painted. Documented cost: key-family dark subject colours are erased on darker painted backgrounds — choose the key away from the subject's hues. video-canvasnormalizes a green/magenta still's flat background to the exact declared key and pads with that key (--key auto|green|magenta|white; the repaint mask is thecutoutmatte's own alpha-0 set, the subject is byte-identical). The report recordskey,key_painted,normalized_px.video-framestells leftover key background at the frame edge (residual, points atvideo-canvas) from a subject that was framed too tight (subject, points at a taller/wider canvas) instead of reporting both as "framed too tight".
v2.1.0 - Guided requests and saved defaults
- Added two user journeys: sprites (base-image provider, then GPT rows or Grok video) and ordinary images (provider). The read-only
workflowcommand checks credentials, resolves request choices over saved defaults and returns the next questions and existing engine route. - Added
defaults show|save|clearwith separate sprite/image preferences. Saves require the observed revision, use the existing cross-platform file lock and publish atomically. A stale concurrent writer is rejected; one-off requests and reads never change defaults. - Results are delivered before optional curation. The first completed selection can be saved for future requests; saved curation choices skip repeat questions. Subscription and quota remain unknown when not independently verified, and configured video API-credit billing requires its own explicit choice.
- Simplified the skill entry point, separated conversation and row execution contracts, refreshed all six README entry pages, and removed the retired PR-specific subject-profile proof script. Existing pipeline and utility commands remain available.
- Removed stick-pose motion guides and obsolete rendering-style bans from generated prompts. Fixed GIF inspection to read each frame's metadata before advancing the decoder.
v2.0.3 - One standing height
video-loopchecks thatimg2webpactually supports-exact(libwebp >= 1.5; Ubuntu 24.04 ships 1.3.x) and fails by name otherwise instead of writing WebP with rewritten RGB under alpha; CI installsffmpegand the official libwebp 1.6.0 binaries so the video tests run there, and those tests skip cleanly where support is absent.video-loopbody_his the standing height (tallest floor-contact frame) instead of the cycle's median bbox height, which under-measured jumps and over-scaled them by ~22 %;--body-height Nscales every state to the same standing height directly in the pipeline (--strip-heightremains the cap). README heroes regenerated at one standing height.
v2.0.2 - Heroes from the pipeline
video-loopGIF/WebP default rate is now 24 fps (the source rate): every cycle frame is kept, so fast actions never read slow;--gif-fps 12restores the lighter output.video-loop --cycle fixed --start N --length Lcuts an explicitly named cycle without detection (reported askind = "fixed", seam gate still applied) — for clips with too few repeats for the periodicity gate.video-loop --strip-heightcaps the cell/strip/GIF height so an output can be produced at its display size directly from the pipeline.- README hero GIFs are
video-loopoutputs verbatim; the jump<img>height matches its taller file.
v2.0.1 - Jump loops play at the same rate
video-loopGIF/WebP frame count follows the cycle length at a fixed playback rate (--gif-fps, default 12) instead of a per-state fixed count: a 2.5 s jump now gets ~30 frames at ~84 ms instead of 12 frames at 210 ms, so every state plays at the same density.--n-outstill overrides; the report recordsgif_fps.
v2.0.0 - Four pipelines, one taxonomy
Highlights
- Video → sprite loops. One still becomes a whole motion set:
video-canvaspads it into the canvas the state needs,videoanimates it in place through Grok Imagine,video-frameskeys every frame,video-loopfinds the true period (or the one performed action) and emits a strip, a transparent GIF and a WebP, andvideo-setruns directions × states with per-item reports. Every stage is measured and fails by name. - Parallel row generation is a command.
gen-setgenerates every state row of a prepared run N at a time with the run's own identity ref, one report per row, a table and a non-zero exit on any failure — what the skill used to describe in prose. - One taxonomy.
sprite-gen --helpopens with the four named pipelines (A atlas rows · B video → loop · C utilities · D post-processing) and groups every verb by domain; the grouping, thescripts/map and the pipeline list derive fromsprite_gen/_modules.py(MODULE_DOMAIN,PIPELINES), and the docs classification is catalogued indocs/README.mditself, checked by tests against the file set and the pipeline catalog. - Documentation you can navigate.
docs/README.mdindexes every doc once under its branch with a one-line owner;docs/architecture.mdopens with a domain diagram and a four-pipeline diagram; the largest docs carry a table of contents; the repo README shrinks to an entry page and the sections it carried live in the docs that own them.
Breaking
New required binaries for pipeline B:
ffmpeg(frame extraction) andimg2webpfrom libwebp (WebP with exact alpha). Pipelines A, C and D do not need them.Removed the
scripts/aliases that pointed at library modules or verb-less modules. Use the verb or module instead:Removed Use scripts/extract.pysprite-gen extract(scripts/extract_sprite_row_frames.py)scripts/gif_utils.pyfrom sprite_gen.util import gif_utilsscripts/runio.pyfrom sprite_gen.spec import runioscripts/reroll_state_row.pysprite_gen.effects.reroll(module;interpolate_frames.pycovers the take workflow)Maintainer experiments moved to
scripts/dev/(breathe_mutation_battery.py,measure_align_sigma.py,validate_pr6_subject_profile.py,check_visible_magenta.py); they are not verbs and the skill no longer requires them.docs/static-pose-recipe.mdmerged intodocs/breathing.md(one contract, one owner); links to the old file are gone.
Added
sprite_gen/video/domain and the verbsvideo-canvas,video-frames,video-loop,video-set(contract:docs/video-pipeline.md).video-loop --cycle auto|periodic|one-shot: action states (jump,attack, unknown) whose clip performs the action once get a recorded one-shot cut (rest → excursion → rest) instead of a hard failure; the report keeps the rejected periodic attempt andtable.mdgains akindcolumn.walk,run,idlestill fail loud without a period.sprite-gen gen-set(sprite_gen/gen/gen_set.py,scripts/gen_set.py): 6 rows at a time by default (the lead-verified batch width), anchors before rows on direction runs, reuse unless--force,reports/gen-set/table.md+set.report.json,--providerhonoured verbatim withgen's own default resolution and its recorded codex → grok availability failover per row.sprite_gen._modules.DOMAINS/domain_of(): display order and one-line meaning per domain;cli.command_domains()derives the help groups. A verb whose module is not in the table fails loudly.docs/README.md(documentation index) with a test that pins it to the file set and resolves every relative markdown link; tables of contents inrun-contract.md,layer-tracks.md,curation.md,directional-anchor-workflow.md,architecture.md;scripts/dev/README.md.
Changed
SKILL.mdis a route-first hub (still / atlas / video-to-loop / utilities) under the 24 KB skill budget; the interpreter rationale, the rename gate and the breathing contract moved verbatim todocs/interpreter.md,docs/rename-gate.md,docs/breathing.md.video-loopstrips are capped by pixel width (32 000 px) as well as by cell count: a 650 px-wide cell now yields 49 cells instead of a 41 664 px image Chrome refuses; the strip meta recordscell_capandsubsampled.- Walk detection window floor 10 % → 6 % of the clip so a legless body's fast bounce resolves; the 15 % depth rule keeps rejecting the one-step half period (verified on a biped and a quadruped).
video-setmotion templates no longer assume a biped. README.mdis an entry page: what it is, the four pipelines, one quickstart each, install. Breathe, chroma-alpha quality, Backbone Lattice and the curation webview tour moved verbatim todocs/breathing.md,docs/chroma-alpha.md,docs/pixel-unfake.md,docs/curation.md.
Removed
- See Breaking for the removed
scripts/aliases and the merged doc.
v1.61.0 - Image to Video
- Added
sprite-gen video: one still + prompt → a verified mp4 through Grok Imagine (POST /v1/videos/generations), with duration 1–15 s, 480p/720p/1080p, optional aspect ratio and audio flag, and asprite-gen-video-reportJSON. - Credentials are the user's own and never part of the repo:
XAI_API_KEYwhen set, otherwise thegrokCLI login file (~/.grok/auth.json,GROK_HOMEhonoured). The report recordsauth_source; tokens and download URLs are never printed or written. - An expired grok login fails before any upload with the exact refresh command; a set-but-empty
XAI_API_KEY, a missing credential, a refused request, a failed/expired generation, a poll timeout, or a non-mp4 download each fail by name and write nothing. - New wrapper
scripts/generate_sprite_video.pyand docs atdocs/video.md.
v1.60.0 - Native Alpha
sprite-gen gen --transparentnow follows a per-provider transparency strategy declared once on each adapter (Provider.transparency).codexasksimage_genfor a genuinely transparent background and publishes the measured alpha (native, first choice);grokkeeps deterministic chroma keying because Grok Imagine returns JPEG only.- Added
--alpha-mode auto|native|chroma.autoreads the provider's strategy,chromaforces keying on codex for prompts that already carry a key background, andnativeon a chroma-only provider fails before any model call. With--refattached,autokeys instead of asking codex for native alpha (measured 1/6 real alpha with references vs 6/6 chroma); the report records why underalpha.strategy_source. - Native output is verified before publishing: no alpha channel or 0% transparent pixels refuses the run (a drawn checkerboard is never keyed silently), RGB under alpha 0 is scrubbed, and partial alpha is reported untouched.
- Reports carry an
alphablock (strategyplus stats) next to the existingchromastats, and codex's owntransparentBackgroundclaim underextra.transparent_background_reported. - Sprite-row generation is unchanged: rows still carry the request chroma key and are keyed at extraction.
v1.59.0 - Contributor Collection
This release incorporates accepted work from eight community pull requests. Thanks to @devswha for chroma color preservation, @bokjk for portable manifest paths, @Dongkyu-ES for deterministic CLI tests, engine export, and subject-aware sparse-frame handling, @napkn34 for the Windows provider and publish-lock fixes, and @monibu1548 for pixel-unfake vertical centering and grounding controls.
- Added
sprite-gen export-asepritefor Phaser-compatible Aseprite JSON and Flame-compatible hash files split by state. Curated frame geometry and timing remain canonical, and exports are confined to the run'sexports/directory. - Added a Windows
LockFileExbackend that preserves shared readers and exclusive publishers across processes without weakening the fail-loud isolation contract. - Fixed provider CLI resolution and UTF-8 subprocess I/O on Windows, including npm
.cmdshims and non-UTF-8 console code pages. - Made Python 3.14 CLI option tests deterministic under colored shell output.
- Added
characterandeffectsubject profiles. Their sparse-frame floors scale with cell resolution:ceil(sqrt(width * height))for characters and half that value for effects. Explicit--min-used-pixelsstill wins.
v1.58.0 - Compose canvas and domain package layout
- Added the human-facing
sprite-gen composeassembly canvas and handoff to the curation view. - Reorganized the Python package and tests into domain subpackages. CLI and script entrypoints remain stable; Python imports intentionally use
sprite_gen.<domain>.<module>paths derived fromsprite_gen._modules. - Split request loading from schema migration so reads no longer mutate run state.
v1.57.0 - First Pixel Breath
- Added deterministic breathing, pixel-grid measurement, curation editing, and run repair contracts.
- Added deterministic palette-swap recolor baking (
sprite-gen recolor/recolor-palette) and curation-side colourway selection. - Added package entrypoints, declared runtime dependencies, and install smoke coverage.
Earlier public milestones are summarized above. Historical tags remain published only where their contents pass the current public-data policy.