Skip to content

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

781 KB
Raw Blame

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-plate finds 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-plate now reads prop_plate.rgb along with prop_plate.box from the canvas report (refusing a report without rgb before anything is keyed with video-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, find locates the side and top: pixels that are a shade of the plate's colour, meaning the plate's colour times a least-squares brightness k (pixel dot colour over colour dot colour) between 0.4 (SHADE_LEAST) and 1, with each channel within k * 48 of k times 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_px is 0 in every frame of the synthetic clips without a side); a sliver of side the subject hides all but less than PIECE_SHARE of (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 reported box spans the front and the side and top (seeding the next frame's search window), while tilt is measured on the front alone. Erasure and --decontam palette 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-plate prints 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 prints video-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_plate adds side_touching (the frames with side_touch_px above 0), and each found row in rows adds side_px (pixels of the side and top found joined to the front; plate_px stays the front's) and side_touch_px (opaque pixels that stay within 4 px of the side and top).
  • Python callers: sprite_gen.video.prop_plate: new shade(rgb, colour) and SHADE_LEAST (0.4); read(report) returns rgb too and refuses a report without it; find rows gain side_px; region(row, size, part="pixels") gains part ("sides": the reach round the side and top alone); erase reports side_touching and rows side_touch_px; warnings adds the third line.
  • Docs: video-pipeline.md "Prop plate: --prop-plate" subsection and canvas paragraph, SKILL.md plate paragraph, and the module docstring of sprite_gen/video/prop_plate.py.
  • Tests: tests/video/test_prop_plate.py (28 synthetic tests, up from 19 in 4.2.0). Adds the boxed clip: 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's side_px between 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), and plate_px within 5% of the drawn front where the figure is clear of it; side_touching naming 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 the boxed clip 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_LEAST at 0 or 0.3 reads black or too dark a colour as a shade (1 fails); a tolerance not darkened with k fails 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-loop keeps the cut with --fill-held off beside a filled loop as cycle.source/. When a cut is a loop at the clip's rate (no --out-fps) and its held cells were made again (held_fill.made or held_fill.again.made), once the filled cut has passed every gate and its GIF and WebP are written video-loop cuts the clip's frames again with --fill-held off from the report's cut_args and frames_dir through loop.cut_again. It builds the cut in .cycle.source.cut/ beside the loop; if it takes the same clip frames (cycle_drawings start and length), its frames, <name>.strip.png, and <name>.strip.json are put in place as cycle.source/ by one rename and .cycle.source.cut/ is removed. Stderr prints video-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's before the second cut's lines and video-loop: <name>: the cut with the fill off is kept as cycle.source/ after; if the second cut fails or takes other frames, stderr prints video-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 them and the filled loop is still delivered.
  • Fix: video-cycle-align aligns filled loops from cycle.source/ without needing the clip's frames. Up to 4.1.0, aligning a loop whose held cells video-loop made again always re-cut the clip's frames with --fill-held off, stopping when a set was aligned away from those frames. Where cycle.source/ beside a loop holds a strip record showing no cell was made, video-cycle-align now aligns from it directly and cuts nothing, giving byte for byte the same cycle frames, strip, GIF, WebP, and cycle.source/ as aligning from the clip's frames, and the same strip record except cycle_align.cut_again (written only when the alignment itself cuts again). Only where cycle.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 the cycle.source/ video-loop kept beside it (its cut with the fill off) or cut it again with video-loop --fill-held off and align that.
  • The loop report and printed summary JSON record cycle_source when 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), and made_before (held_fill.made), or kept (false) and why when no cut with the fill off is kept. Loops with no cell made and cuts with --fill-held off record no cycle_source.
  • Python callers: sprite_gen.video.loop: new keep_unfilled(report, out_dir, name, cut, **asked) (the cut again with the fill off kept as cycle.source/; ValueError naming why it is not), new filled(meta) and CUT_AGAIN_DIR (both moved from align); sprite_gen.video.align.filled and align.CUT_AGAIN_DIR keep their names and refer to those; align.unfilled_source aligns from a kept cut and otherwise calls keep_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-held help of video-loop and video-cycle-align.
  • Tests: tests/video/test_no_repeat_default.py adds test_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, and test_a_filled_loop_whose_cut_with_the_fill_off_fails_is_delivered_and_says_why_nothing_is_kept, and removes cycle.source/ first in two existing alignment tests (covering 4.1.0 loops and the updated stop message); tests/video/test_loop_prop_seam_held.py checks cycle_source on the loop report and no cycle_align.cut_again on the aligned strip record; tests/video/test_ghost_given_way.py moves 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-plate tracks 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's prop_plate.box scaled 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 and video-loop cuts (strip, GIF, WebP). The 3.12.0 whole-clip channel median rule (within 40) is removed because it assumed a stationary plate. Now, start_box maps the canvas box to frame coordinates rounded outward without a rim. Each frame searches within a window extending the plate's diagonal (on start_box) past the reference box on every side: start_box on 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-loop cuts of erased frames carry no plate; video-set does 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 (default auto in video-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-plate prints warning lines for undetected plates and subject contact. A run prints video-frames: warning: --prop-plate: no plate found in N frame(s) (...) naming frames where no plate was found (nothing erased), and video-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, and rows. Replaces erase_box with start_box and per-frame entries in rows: frame, found, and where found box (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, and touch_px.
  • Python callers: sprite_gen.video.prop_plate: new find(files, plate), region(row, size), not_subject(row, size), warnings(done); erase(files, decoded, rows, plate) (was erase(files, plate)); frame_box no longer adds the rim; new constants KEY, BLEND_REACH, PLATE_TOLERANCE, PIECE_SHARE, LUMA_SLACK, BLEND_BALANCE, BLEND_SLOPE, NAMED; RIM is 4; STILL_TOLERANCE removed. 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) and extract_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.md plate 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 (box within 2 px of drawn plate, plate_px within 5% and tilt within 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_box arithmetic; palette exclusion ensuring no palette colour within 48 of the plate and preserving pink within 24 (versus plate colour included without --prop-plate); and clean video-loop cuts. 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-loop once cut, the loop, hold_last and end_frame metadata, the play modes), effects (pixel-draw --kind effect, brightness alpha, lifetime cuts), video-stop, slice-sheet --scale sheet and --fit contain, the alpha haze cleanup, the refusal of a painted transparency checkerboard, logo, compose-atlas and export-aseprite.
  • Command line: sprite-gen sound, sprite-gen game-pack and sprite-gen ui-kit end as an unknown command with argparse exit code 2; gen --layout-guide ui-kit and background-tile --axis xy end as an invalid choice with argparse exit code 2.
  • Dependencies: the removed features declared no Python dependency. ffmpeg, ffprobe and 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.md and docs/ui-kit.md now point at those files in the v2.45.0 tag 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.py and tests/background/test_tile_xy.py; the game pack test of tests/video/test_stop.py and of tests/frames/test_slice_sheet_scale.py, the load_asset_states test of tests/spec/test_assets.py, the three UI kit guide tests of tests/gen/test_layout_guide.py, and the ElevenLabs cases of tests/gen/test_provider_address.py and tests/workflow/test_capabilities.py. Changed: tests/gen/test_painted_checkerboard.py refuses the checkerboard through gen with the figure layout guide; tests/workflow/test_capabilities.py reads a flag's --no- alias off prepare and a required exclusive group off video-sway; tests/packaging/test_curation_asset_packaging.py checks that the wheel carries the face player sprite_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.

Two panels side by side, looping at 24 fps, show 26 cells of a synthetic test figure from the repository's tests (a blue torso, a skin-coloured head, a dark foot going round a circle) walking on a white background, with no real footage.

  • Changed: video-loop reads 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 than HOLD_MAX 3 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 a warning: line names them and the faults. held_fill.before.wrap records the run across the wrap (start, length, joined, filled, made), held_fill.wrap_held says 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 and source_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 as held_fill.again in the loop report and the strip metadata (before, made, frames, cells, poses, held_runs); its warning: lines start with read 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 off turns 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.KEEPS names the kinds, and the strip metadata gains holds and fps (held_fill.intended, held_fill.strip_holds). The rules for a hold the motion means are unchanged: a run longer than HOLD_MAX 3 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 carries keep (its kind) in held_fill.before.held_runs, and held_fill.KEEPS names the kinds: motion-hold, drawn, opening, closing. The strip metadata (<name>.strip.json) gains holds: a list of {from, to, kind, reason}, one per kept run, as cells of the strip (from and to both included), the same list form a renderer's hold list uses; inspect-holds and scene-render read it as holds meant. held_fill.intended(record) gives the runs, held_fill.strip_holds maps them onto the strip's cells. The strip metadata also gains fps, the strip's exact rate (cells over the cycle's seconds, rounded to 6 places), next to delay_ms, which stays rounded to hundredths.
  • New: the loop report records cut_args, and loop.cut_again cuts the same frames again. cut_args is 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 example fill_held="off"), with no provider call. It refuses a report from before cut_args was recorded, and frames that moved.
  • Changed: video-cycle-align (and video-set --align-cycles auto) aligns as filmed and fills at the end (cycle_align.cut_again, cycle.source/, --fill-held); new video-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 cells video-loop made again (held_fill.made, or held_fill.again.made) is cut again from its frames with --fill-held off, using its report's cut_args (no provider call); that cut is kept as cycle.source/ (its frames, strip and strip record) and aligned, and cycle_align.cut_again records report, 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 with video-loop --fill-held off and align that. Then each loop as aligned is read for held cells and filled at the end (--fill-held auto, the default), as video-loop fills 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 the held fault 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's held_fill say what was done; holds lists what was kept. --fill-held off delivers the aligned loops as they come out of the alignment. --out-fps F gives 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 says out_fps and source_fps; a rate not above the loops' own is refused; a loop already aligned at a higher rate is aligned again from its cycle.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-set cuts the walks and runs it aligns with --fill-held off and lets the alignment fill them; an item no alignment took is cut again filled (loop.cut_again.why not aligned); video-set --out-fps with 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 standalone video-loop and 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-fps once aligned (video-cycle-align --out-fps), the rest by video-loop --out-fps. Each item's loop.poses and loop.held_fill are those of the loop as delivered (after the alignment where it ran).
  • Changed: an effect's lifetime is named, not filled. A lifetime cut is read for held cells and each run is named in a warning: 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-stop fills held cells by default (--fill-held auto); its sidecar records held_fill and holds. Before, a stop was read for held cells and recorded held_fill with mode off; 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, as video-loop makes 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 off plays 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 and held_fill.unmade. A RIFE that is found but fails stops the stop (report status: 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) and face-bake read for a frame shown again and warn; the report gains held, bake.json gains held. The published mp4 is read for a frame shown again (frames decoded by ffmpeg, the held_fill.same_steps rule; 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 prints video: warning: clip.mp4 shows one picture on frames A-B .... Nothing is filled: the clip is kept as the provider made it; video-loop makes such cells again when the clip is cut. Without ffmpeg the report says read: false and a warning line, and the clip is published as before. face-bake reads the baked body cells; a run within a clip, across the loop's wrap or where a clip comes back to the loop prints face-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 as holds) are recorded without a warning. No frame is made and the verdict does not change.
  • Fixed: scene-render and scene-inspect read a strip's cells at delay_ms, rounded to hundredths, so a scene frame on a cell boundary showed the cell before it (spec.assets.frame_seconds, SNAP_MS). delay_ms is 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's fps where its sidecar gives one, and a strip from before (no fps) whose delay_ms is within 0.01 ms of a whole rate is read at that whole rate. Those boundary frames change; --fill-held off does not undo this. Strips at 25, 20, 30, 12 and 48 fps render byte for byte as before (pinned).
  • New: scene-render --fill-held auto gives a layer cut from a filmed clip at the scene's times; the report gains inspection.repeats and fill_held; new scene-render --between-cache DIR. By default, a layer whose asset is a cut of a filmed clip (a video-loop or video-stop strip, its sidecar names source_cut) and would show a cell again at the scene's frames (a 24 fps cut in a 60 fps scene, a playback_rate under 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 as video-loop judges a frame made for a held cell. Held on purpose stays held: before the layer's start, a one-shot's end and hold_last, a run its strip lists in holds, 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 off gives every layer's cells as its timing picks them. inspection.repeats is 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_held is in the report. --between-cache DIR keeps 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's between_cache counts 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 --log and --log-figure, with the same rule as held_fill.same_steps on the figure's pixels. It compares them with hold lists (--holds, a strip's holds, the list form a renderer uses) and reports listed and unlisted holds; --gate exits 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 is docs/asset-tools.md "Frames shown again".
  • Fixed: inspect-holds reads a frame's largest part as a figure however few pixels it has, reads nothing in a --box that holds no pixel, exits 2 where no frame was read against the frame before, and reports steps and inspected; the Grok clip reading of video, video-extend, video-edit and video-resume does 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 --gate exited 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 --gate exited 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 --gate exits 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's steps (its frames read against the frame before; on a loop read across its wrap, the wrap is one step) and inspected (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, --frames that 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-figure keys 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 --report with inspected 0, 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 --frames past 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(...) and read(...) in sprite_gen.qa.holds raise NothingRead, a ValueError whose report attribute is the report, with inspected 0. The Grok clip reading of video, video-extend, video-edit and video-resume read 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's held is read false with frames, background and a why, the warning line says its frames were not read for a picture shown again, and the clip is still published.
  • New: sprite-gen video-chain plays 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; --refuse names 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 a warning: line; the judge and its bars do not change. held_fill gains FAULTS and a refuse argument on at_times and fill, loop.fill_cut gains refuse, frames gains KEYS_READ and key_kind, a held_fill try gains judged and, with refuse, kept_faults, and the video-frames report gains key_read.
  • Python callers. held_fill: new wrap_same, KEEPS, intended, again, strip_holds; premultiplied (was _premultiplied); fill(..., wrap=, drawn_on=); reading(..., wrap=). loop: new cut_again; fill_cut, fill_lines, out_fps_lines (were _fill_held, _fill_lines, _out_fps_lines). align: new filled, unfilled_source, CUT_AGAIN_DIR; align_set(..., fill_held=, out_fps=). batch: new held_summary, loop_summary, cut_again_unaligned; align_gaits(..., fill_held=, out_fps=). spec.assets: new frame_seconds, SNAP_MS, FrameSequence.index_at. scene.render.Renderer(..., fill_held=, interpolate=, between_cache=). New module sprite_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.py covers a loop's last cells, a cut one cell too long, the read again after the repairs, the strip's holds, cut_args and cut_again, the lifetime warning, the alignment's end fill, its cut again with the fill off and its refusal, --out-fps once aligned, a set with no held cell aligned as before, and video-set cutting 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 off it is the pictures pinned before. test_face_layer.py, test_root_motion.py and test_loop_prop_seam_held.py: the strip metadata grows fps and holds, 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 off to 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_is in test_loop_prop_seam_held.py and test_the_first_alignment_records_the_cut_it_was_made_from_and_later_ones_keep_it in test_follow_read_on.py. Like the other tests the default fill sends to the binary often (the rule in docs/release.md), each now has a timeout of its own, @pytest.mark.timeout(900), and pins the binary's calls by model with as_pinned (exactly for rife-v4.6, between a floor and a top for rife-v4.25), and the second test is now marked slow, so the fast bundle (a plain pytest) 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.RELEASE 20250112, 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, over align.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_NAME names the model (rife.model_name(), rife.held_model()). rife-v4.25 (the default) or rife-v4.6. SPRITE_GEN_RIFE_MODEL names 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 -z and SPRITE_GEN_RIFE_TTA; rife-v4.25 refuses any augmentation (TNTwise's README marks -x and -z deprecated with it). rife.TTA is gone (rife.MODELS[...].tta).
  • Changed: sprite-gen rife install downloads 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 against rife.MODEL_SHA256, now {model: {file: {platform: sha256}}} (the Windows zip's flownet.param has CRLF line ends). It keeps the binary, rife-v4.25/, rife-v4.6/, LICENSE and README.md (and the DLLs on Windows); the check frame and the report's model are 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's rife-v4.25 files (the published flownet.pkl, SHA-256 6615790efd627772917205db291f51cd392528a157ecbb2ecaeec3bff8eb6de2, 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.model in reports; the torch runner's and executor's identity carry model, 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: NOTICE gains 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.py adds the unheld-bytes test above; Tests that pin the binary's calls pin them by model through as_pinned in tests/conftest.py (0 calls where the binary is not found, the same as rife_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.py holds how as_pinned reads 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 in tests/fixtures/rife-walkers/walkers.json under alike: 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 of local_cycle.TOP_LINES ({'top': 'its top line', 'first_row': 'its first solid row'}), in that order, with local_cycle.bob_word(signals, interval, feet=False, line='top') in both places of local_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_cycles reads it on the crossing interval, and cut_word reads it on the cut L, L/2 and 2L through local_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 because top passes 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. why strings that said "its top line" now say the line's name, and the cut's why where nothing says is each place's why, repeated ones once, joined by "; ".
  • New: the rows down the middle of the body (legs.body_signals first_row, strips, legs.STRIP, legs.DEEP, local_cycle.body_depth, BOB_RIGID, STRIP_FLOOR, STRIP_SHIFT, STRIP_SHIFT_MIN). legs.body_signals(frames) also returns first_row (per frame, the first solid row) and strips (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, and legs.strike_signals and gait.silhouette.signals are 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 most STRIP_SHIFT (0.03) of the body's height either way and at least STRIP_SHIFT_MIN (3) rows. It returns need, risen, rigid, zoom, ratio (zoom of rigid), moved and frames, 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_beat reads the body's own on less_lowest alone where ratio is BOB_RIGID (1.0) or more, holds where it is under, and leaves the bands to decide where it is not read: no depth, or moved under STRIP_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_OWN of what is left against the lowest row on the screen (local_cycle.bob_word). After the less_lowest gate and before the bands, where beat is under BOB_OWN (0.3) times less_lowest, nothing is witnessed, and why says "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.bob gains top_line, the line that said so, where it says "cycles", and feet, the record over the feet, its says and top_line the same. body in bob, lines.*.bob and lines.*.on gains depth: null or {need, risen, rigid, zoom, moved, ratio, frames} (need, rigid, zoom and moved rounded to 5 places, risen to 2, ratio to 3), a measure recorded as the other measures are, not a verdict. cycle.cut_witness.by is ["screen", "feet"] or ["order"], never one place; cut_witness.lines.screen.says and lines.feet.says are the body's word, the same in both, the cut's word where by is ["screen", "feet"] and the body's reading as it stood where it is ["order"]; lines.*.bob, lines.*.on and on carry top_line. No report key tells a right hold from a false one. why strings changed as docs/loop-repair.md says: 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, and mark read of the line that stood.
  • Changed: Python callers. New local_cycle.body_word, local_cycle.body_depth and local_cycle.TOP_LINES; local_cycle.bob_word takes line, a TOP_LINES key; local_cycle._cut_line and local_cycle.CUT_WORDS are gone.
  • Tests (tests/video/test_walk_steps.py, tests/video/test_cycle_align.py, tests/video/test_loop_silent_pass.py). Renamed test_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) and test_a_walk_whose_arms_swing_past_its_sides_reads_as_one_whose_arms_swing_within_them (was test_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_steps now 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, and video-cycle-align on 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.overlap over crossings.HIDE_SHARE, 0.5) or when the view is given and is not side, 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 by span over the clip's mean step from frame to frame. Comparing distances at half, one, and two intervals, crossings mark cycles when one < half and one <= 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_signals top) less its flow, read against its lowest row and upper body. New function local_cycle.off_flow(values, interval) returns values (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 last ceil(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; swing is the range of the line left over the body's median height, and rows is that range in pixel rows. Where the clip is under an interval long so nothing is left, says is null and why says its top line less its flow is not read; where swing is under BOB_FLOOR (0.005) or rows is under BOB_ROWS (2), says is null, why says 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), and half and quarter are not read. Otherwise it reads the line left's correlation half an interval on (half) and a quarter of an interval on (quarter), both with crossings.correlation_on (each the larger of the two whole lags about the span), saying "cycles" only where half is BOB_TWICE (0.28) or more and quarter is -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 with why giving both values. Where any frame's lowest solid row is the frame's last row (legs.body_signals edge), says is 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) reads values (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 than BEAT_FRAMES (8) frames are left; where none, says is 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 with twice_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 and zoom, in pixels, beat in pixels, reads is the band's beat over its zoom (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. less is 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_lowest times (1 - reads), and nothing where reads is 1 or more, so a band whose width moves against the line adds nothing to what is left, reads and less null where the band is not seen), less_bands (the least less, null where no band is seen), still_bands (the number of bands seen whose reads is at most 1 - BOB_SCALE, 0.4: they hold still on the beat), and own, the smaller of less_lowest and less_bands (None where a line is not read). The floor is the larger of BOB_ROWS and BOB_FLOOR of the body's median height; where less_lowest is under the larger of BOB_OWN (0.3) times beat and the floor, says is 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_bands null), says is 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"; where less_bands is under the largest of BOB_OWN times beat, the floor, and BOB_SCALE (0.6) times less_lowest, says is 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"; otherwise says "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 (its reads over 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. New legs.body_signals(frames) reads per frame bands, 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))), and edge, 1 where the lowest solid row is the frame's last row, else 0; only the step count's witness reads them, merged by loop.read_steps into the signals it passes to local_cycle.read_cycles; legs.strike_signals is unchanged, so the loop report's gait.silhouette.signals is unchanged, and --anchor none still gives the old cut, its pictures and reports byte for byte apart from the engine hash. The directional foot cue (legs.shade_cue from the side or diagonal, legs.depth_cue from the front or back) is read with a view given by local_cycle.cue_word(cue, interval, step=None) and can only refuse cycles: under CUE_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_on at or below CUE_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 with unwitnessed true (local_cycle.UNWITNESSED) and a warning (cycle-unwitnessed). When cycles are marked, Reading.mark_cycles sets per to 2 and halves step and step_range: a cut one interval long is two steps, and the search's cut (--anchor motion-auto) taken on it writes steps: {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 no steps.
  • Removed: the same-picture rule (local_cycle.same_picture, local_cycle.same_picture_count, local_cycle.SAME_PICTURE_MAX, count code same-picture, report fields step_count.search.same_picture and step_count.same_picture). It kept the search's cut, with no steps, where the count said one step; it never cut one cycle where the search had found two. local_cycle.read_cycles takes its place.
  • New: walk start-stop retake reporting (loop.stand_retake, crossings.Reading.stands). In gap mode, runs where the feet stay together longer than run_limit (√2 times the median whole pass run) are recorded in Reading.stands. Where a clip shows its steps, contains stands, and the cut kept does not count two steps (verdict is not two) with no two-step cut closing between the standing frames, loop.stand_retake emits a retake report (reason: "start-stop", remedy: "retake"), keeping the cut as cut without refusal under --unfixed refuse. Where a part also pops, one retake names 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-set defaults gait anchoring to motion-auto (batch.anchor_for). Without an explicit --anchor, video-set cuts each walk and run item whose loop is searched (cycle_for returns auto or periodic) with motion-auto, and assigns none to idle, attack, once-hold, lifetime, and once-return items; explicit --anchor options are applied to every item as before. video-set passes each item's view to video-loop. Any item whose loop names a retake carries loop.retake, appears in the set's warnings, and appends (film again: <reasons>) to table.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 with start-stop retakes 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, which video-cycle-align reads 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 under left_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), as video-cycle-align says when it stops on such a loop, and batch.left_out_why takes one_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). In video-loop --anchor motion-auto (--cycle auto or periodic), after loop._by_steps chooses the cut and before frames are cut, loop._witnessed(cycle, frames=...) holds the cut s/L to local_cycle.cut_word(signals, length), which reads local_cycle.bob_word on two lines, local_cycle.CUT_LINES ('screen' on the screen, less its flow, and 'feet' over its feet with local_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 in local_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 carries mark; it holds nothing), and a cut of four steps (two cycles), its strip still counting two steps, makes local_cycle.four_steps(cycle) true, and video-set leaves 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), setting cut_witness.held to "unwitnessed", warning cycle-unwitnessed (local_cycle.held_verdict(cycle) via local_cycle.step_verdict), and marking local_cycle.unwitnessed(cycle) true so video-set leaves the item out of cycle alignment (left_out ["cycle-unwitnessed"]), while cuts the step count already held record held: "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_lengths handed 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_signals sole, legs.OPAQUE, local_cycle.own_beat). legs.body_signals(frames) now returns sole per frame, taking the lowest row with an alpha of legs.OPAQUE (255) or the lowest solid row where none is opaque. local_cycle.own_beat(signals, interval) reads sole with twice_an_interval and takes less_lowest as the top line's rise and fall less the lowest solid row's or less the lowest opaque row's, whichever leaves less, returning sole as 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_order tracks which foot is drawn lower in each frame, and local_cycle.order_word gates 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_cycles and cut_word read 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_word leaves out frames whose contacts touch no column of anything standing on the lowest row in any frame, recorded in off_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-align stops on held or four-step cuts (align.held_cut). video-cycle-align run on its own reads the cut report beside each loop through align.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 under held and the aligner stops under --multi-cycle fail before rewriting any files, adding "and nothing witnessed some of the cuts whole cycles". Under --multi-cycle warn it aligns the loop with a warning, matching video-set instead 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}, where cue and bob are recorded only where the picture passes, cue: {range, floor, swapped, one, says, why} only with a view, one absent where says is "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, edge and body absent under the floors, body absent where under 8 frames are left, and why absent where it says "cycles", and unwitnessed true only where nothing witnessed); the loop's warnings (jolt.warnings); step_count.stands and step_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 item loop.retake ({reason, reasons, remedy}) and item loop["cycle-unwitnessed"] (true), and its state's cycle_align.<state>.left_out ({item: reasons}); the loop report's cycle.cut_witness ({cut, says, by, lines, on, why, held, mark}, lines ({screen, feet}, each {says, bob, on, why}), the feet line's bob and on with over, by only where it says a word, on with its line and interval only for four steps or one step, why only where says is null, held only where held, and mark only where marked); the printed summary's cycle.cut_witness ({cut, says, by, held, mark}, each where present). cycle.step_count.cycles.order and cut_witness.order record foot-order metrics (apart, swing, floor, changes, slides, spacing, travel, sway, tilt, per, says, why, off_ground), and video-cycle-align reports held suspect loops under held with {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 a ValueError a cut held on one step whose record names no line it was read on (no by or lines)), 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._alternation is now public crossings.correlation_on(values, span); align._feet, align._depth_cue, align._shade_cue, and align.SHADE_BAND are moved to legs.feet_halves, legs.depth_cue, legs.shade_cue, and legs.SHADE_BAND (align keeps _depth_cue and _shade_cue aliases); crossings.Reading gains interval, per, cycles, hides, and mark_cycles(said). local_cycle.read_cycles and local_cycle.cut_word take order, cut_word takes declined, and align.held_cut checks loop cut reports.
  • Tests: tests/video/test_walk_steps.py covers 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 cycles true, steps: 2, and no cue read with no view, its bob's body.share at least 0.3, body.scale at least 0.6, edge 0, every band seen holds still on the beat (still_bands equals the bands seen), and its why naming 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_diagonal cut to one cycle because its foot cue moves over the floor and does not turn over one interval on (says null) 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 says steps: 2, and local_cycle.four_steps is 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 under BOB_FLOOR of the body's height and under BOB_ROWS rows), keeping two intervals (two cycles) with cycles false, unwitnessed true, 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 --view set to front, front_diagonal, back, and back_diagonal: the picture passes, the cue says "alike", and its top line rises and falls once an interval (a step), so its half correlation is negative, leaving nothing to witness and keeping two steps at 46 frames with unwitnessed true 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 --view set to side, front_diagonal, and back, keeping two steps at 46 frames with unwitnessed true 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 --view set to side, front_diagonal, and back_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 --view set to front, front_diagonal, back, and back_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 side or front_diagonal the 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 with unwitnessed true 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 unwitnessed and the warning; for the bobbing walker its half is -0.28 or less (less its flow its line rises and falls once an interval); for the still one its rows is under BOB_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 its quarter at -0.28 or 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) with unwitnessed true and the warning; brief meetings with no view or side are 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; and bob_word on 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 reading half or quarter (swing and rows are the range of off_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 under BOB_ROWS, and off_flow over 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's half is 0.28 or more and its quarter -0.28 or less (the top line alone rises and falls twice an interval), its body.share is under 0.3, and its why says 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's half is 0.28 or more and quarter -0.28 or less, and its why says 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, edge over 0 and a why naming the frame's last row;
    • twice_an_interval over 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_word over 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" (share over 0.9, scale 1); 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, its why naming 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, under BOB_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, scale under 0.6, its why naming 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, edge 1, why "in 1 of 73 frames";
    • read off drawn frames with legs.strike_signals and legs.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_lowest at least BOB_OWN of body.beat, body.scale under 0.6, the largest band reads over 0.4, still_bands fewer 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's why naming 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 side and --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 (half at least BOB_TWICE, quarter at 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 stands when feet only pass.
    • cut_word units 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.interval 8), "one step" (on.interval 32), 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, by is both lines; where null, each line's why is in why.
    • a record held on one step with no by or lines (built from cut_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, a ValueError, through held_verdict and through step_verdict; the same with nothing read (says null, its why kept) gives one warning naming its why and cycle-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 says null 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_word on 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 (half at least BOB_TWICE, quarter at 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 (over sole) its top line holds still (under BOB_ROWS rows: "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 (by includes feet), read over reach or sole, 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 (cycles true, 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" (by the 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 (says null), 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, steps 2, cycles.order.says "two steps", zero slides, travel under ORDER_TRAVEL of 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 --view front, front_diagonal, back, and back_diagonal: cut 46 frames, steps 2; crossing check has cycles false, order.why value 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, says value "two steps", "four steps", and "one step", span 22 none, also checking that no foot slides and that the upper body's sway stays under ORDER_SWAY of the tilt; picture rocked 10 degrees either way about feet once a cycle, feet drawn level and still, says null, why value 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, says null, why value 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, says null, why value stating a foot passes under the body; rear walker with soles on one row, says null, why value stating feet are drawn level.
    • the walker whose feet stay apart cut 20 frames, --view front, under loop._witnessed: cut stands on order, by ["order"]; with step count declined record set: cut held, cut_witness.held "unwitnessed", order.read "two steps", order.why value 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_step is 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_word over 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, with off_ground exactly 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_ground is the tail's frames, says is 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-loop stopped on the division by zero).
    • the walker meeting once a cycle (cycle 30, body still, no tail): cut_word returns 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).
  • Tests: tests/video/test_gait_guard_anchor_wide.py and tests/video/test_cycle_align.py cover batch anchoring and cycle alignment:
    • batch.anchor_for assigns motion-auto to walk and run loops while assigning none to cheer, walk with --anchor none, and pinned idle items, propagating loop retakes to item records, warnings, and markdown tables;
    • batch.align_gaits excludes loops with a start-stop retake, a loop with cycle-unwitnessed, or a loop with both, names its reasons under left_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_gaits with three directions, two loops of one cycle (20 and 24 frames) and one loop of two cycles (40 frames) whose strip says steps: 2 and whose cut witness says four steps: the two-cycle loop is left out under left_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", strip steps: 2, walker two cycles long): standalone video-cycle-align stops with one suspect, held value {reason, report}, settle value =1 and =2, nothing rewritten; --multi-cycle warn aligns and names reason; --cycles 1 or 2 aligns it, suspect status "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 (no steps and no warning about steps), whereas now there are still no steps, the walker is carried whole on its legs, so its cut witness holds the cut (cut_witness.held is "unwitnessed", local_cycle.unwitnessed is true), and the one warning that speaks of steps is the witness's (local_cycle.held_verdict), naming cycle-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 marks run_set records (cycle-unwitnessed from local_cycle.unwitnessed, and step_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 with video-loop --steps 1 if it is), video-cycle-align run 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-align now stops on both loops, each named held, 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.py and tests/video/test_loop_prop_seam_held.py cover standalone video-cycle-align on 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 as video-loop writes 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, reason cycle-unwitnessed, with the report's path: it may hold half a cycle, one or two, and the message names video-loop to 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 no held and no mention of video-loop, both offering settle =1 and =2 with nothing rewritten (previously one run, NE named only for its return, and the message never named video-loop); --multi-cycle warn aligns 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=2 aligns 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, strip steps: 2, and one cut one cycle with no steps, 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_witness saying "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", steps 2, 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 saying steps: 2, the other none; on the loops as cut, video-cycle-align stops on both, each named held with reason cycle-unwitnessed; a count of one cycle for each (cycles, the caller's word) aligns them as they are, to the same median length, each suspect status "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 says steps; two copies of the loop with no held part, aligned with a count of one cycle each, are written as before: no cycles_kept and no steps in 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-align to 17 cells, in tests/video/test_sway_read_on_recut.py (with --between rife (a blend standing in for RIFE) the aligned strip record holds no cell_record, cycle_align.cells_from gives 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.json is the cut's record with 13 cells, source frames 1 to 13, and video-sway --read-on-cut is refused uncertain on the pair the kept record gives (source frame 4), naming the first made cell, the loop as it was; with --between nearest every one of the 17 cells is one of the cut's, and --read-on-cut pairs source frame 4 with the cut's cell 3 at shift (3, 2) and carries it through, cut_cells equal to the cells_from sources).

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 extractOk spelt extractOK made 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 the X-Filename download header) and serve_compose.Wire (16 keys, plus TYPE_DIR, TYPE_IMAGE); the heal report and progress file keys in frames/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_OPENAI in gen/base.py, with gen.PROVIDERS and the other provider sets written with them; the curator's two buttons gated by one set, serve_curation.CURATOR_PROVIDERS; the reroll default is gen.HARD_DEFAULT_PROVIDER; the interpolate default is interpolate.DEFAULT_PROVIDER (codex, its own documented choice from the three-way comparison); the HTTP host names address.OPENAI, XAI, ANTHROPIC, ELEVENLABS; retry.ELEVENLABS_BUSY; audio.manifest.KIND, SFX, BGM; the workflow guide's journey, field and access names in workflow/catalog.py and workflow/access.py; video-prompt takes gen.video.DEFAULT_MODEL instead of a second copy; the choice to stop and ask when codex cannot run is gen.CODEX_UNAVAILABLE_ASK, which gen.CODEX_UNAVAILABLE_CHOICES, gen.CODEX_UNAVAILABLE_DEFAULT and the workflow catalogue read; the guide reports that choice under gen.CODEX_UNAVAILABLE_SETTING, the name it is saved by; xai.AUTH_SOURCE_API_KEY is xai.AUTH_ENV; claude_login.CHILD_DROP reads anthropic_api.AUTH_ENV; the codex binary's name is codex_provider.BINARY; pixel_draw.EFFORTS is anthropic_api.EFFORTS, the copy removed.
    • key colours and modes: cutout.KEY_TARGETS with MAGENTA and GREEN beside it is the one table of key colours (gen.chroma.KEYS is built from it, logo_matte.KEYS is it, slice_sheet.CHROMA_KEYS is removed, the hex values in prepare, unpack-atlas and the curation server are derived from it); cutout.KEYS is cutout's own --key set; OFF, AUTO, PALETTE = DECONTAM_MODES and CHROMA_RGB, CHROMA_YCBCR = CHROMA_MODES are declared in frames/extract.py, and frames.decontam.DECONTAM_MODES and video.frames.DECONTAM_MODES are that same tuple; every --decontam, --chroma-mode and --key choice reads its declaration; logo_matte.LETTERING_BOX, UNMIX; prompt_parts.CONFLICT, REPEAT; gen.chroma.KEY_BACKGROUND_TEXT, gen.logo.KEY_COLOUR_WORDS and a scene report's key_like_pixels are keyed by cutout.GREEN and MAGENTA; prop_plate.RGB reads KEY_TARGETS[MAGENTA]; video.frames.DECONTAM_DEFAULT is extract.AUTO and video-frames' decontam branches read OFF, AUTO and PALETTE; video-frames --alpha-mode reads effect.ALPHA_MODES; the method a gen.chroma report states reads extract.CHROMA_YCBCR and base.TRANSPARENCY_NATIVE.
    • kinds: loop.REPORT_KIND, loop.REPORT_PASSED; spec.assets.ASSET_KIND, SET_SHEET_KIND (set_sheet.KIND names it); qa.motion.REPORT_KIND; video.evidence.SOURCE_KIND; nonloop.GAIT_STATES (the copies in qa.handed and video.batch removed); body_plan.BIPED, QUADRUPED, LEGLESS; effect.STATE read by video-set and video-prompt; pixel_gates.SPRITE, ICON, TILE, EFFECT (pixel_draw.KINDS is that tuple); new names spec.runio.REQUEST_KIND, video.frames.REPORT_KIND, video.align.REPORT_KIND, unpack_atlas.UNPACK_SOURCE_KIND; video-canvas writes prop_plate.CANVAS_REPORT, the name the report is read by; the kind of a pixel-draw effect strip is pixel_gates.EFFECT; a video-cycle-align same-foot refusal states align.RETAKE_FEET_REASON.
    • other copies: sprite-request.json and curation.json are read as runio.REQUEST_FILENAME and curation.CURATION_FILENAME everywhere they are written, opened or checked; pixel_grid.PNG_MAGIC is base.PNG_MAGIC; restoration.ARTIFACT_SUFFIXES is the one table of a restoration's five files (restoration.ARTIFACTS is its keys, the demo script reads it); game_pack.SIDES is ui_kit.SIDES; video-canvas --facing, video-loop --facing and a lateral view's check in gen.handedness read gen.facing.FACINGS; effects.breathe.SIDE_NAMES is keyed by extract.FRAME_SIDES.
    • Values that no test bound before and that now cannot drift: the legless anatomy sentence key, effect in video-set's states pinned to their first frame, the pixel-draw pick sheet's tile branch, the loop report kind video-cycle-align reads (its typo passed the fast bundle).
  • 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 (use cutout.KEY_TARGETS). clip_prompt.DEFAULT_MODEL is gen.video.DEFAULT_MODEL, imported (the same object). qa.handed.GAIT_STATES is now a frozenset (was a tuple); every use is a membership test. sprite_gen.frames.cutout now imports frames.extract when it loads (for the decontam defaults), so importing it loads more modules than before; pixel_draw.EFFORTS, game_pack.SIDES and pixel_grid.PNG_MAGIC stay importable as the same objects; loop.FACINGS is removed (use sprite_gen.gen.facing.FACINGS).
  • Curator: the JS mirror BREATHE_MODES moved from store.js to breathe.js, with BREATHE_SMOOTH beside it; gen-trigger.js's provider select mirrors serve_curation.CURATOR_PROVIDERS. No screen changes; BREATHE_ROUND_KEYS moved from store.js to breathe.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; every Wire.X the servers name exists. tests/serve/test_curation_view_contract.py: the reroll and interpolate buttons follow CURATOR_PROVIDERS and their declared defaults, and node runs gen-trigger.js to hold its select to CURATOR_PROVIDERS in order. tests/effects/test_breathe_sidecar_roundtrip.py: the curator's save payload kind is CURATION_KIND. tests/frames/test_cutout.py and tests/frames/test_chroma_decontam.py: every key table is the one table, every --key, --decontam and --chroma-mode flag reads its declaration, cutout.KEYS pinned as written. tests/gen/test_codex_unavailable.py (the codex-unavailable choices in order), tests/gen/test_openai_provider.py (adapter names equal gen.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 searched serve_curation.py for 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 in serve_curation.py and 55 in serve_compose.py; 8 --decontam parsers held their own copy; video-set's --key was 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 of sprite_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 are ui_kit's), tests/gen/test_facing.py (video-loop --facing takes the facings gen.facing declares), tests/effects/test_breathe_reference_key.py (the JS frame sides and border share equal extract.FRAME_SIDES and BORDER_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 said the 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 is the 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 reads frames 0-34, is 1.12 of its departure away, over 0.25 (moved 0.36, need 0.4). The report written with --report gains cycle.closest_return with keys pair, ratio, seam, departure and moved. 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_MAX names the return bound (0.25). The CycleSelectionError diagnostics of detect_one_shot carry closest_return where 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 L from the closest return's frames. SKILL.md updates its single-play motion guidance with the same command and refusal quote.
  • Tests: tests/video/test_one_shot_refusal.py adds 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 matching closest_return in 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 no closest_return. Red first: on 3.12.0, 2 failed and 3 passed (tests 1 and 3 refused with moved 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-plate paints 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 by canvas.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, state effect, or plates extending past the canvas edge. The report records prop_plate with box, rgb, subject, and of_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-loop cuts of erased frames carry no plate; video-set does not paint or erase a plate. The report records prop_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; constants RGB, 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-over lays 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-mask leaves pixels the region mask does not cover out of the layer and band while pixels it covers move with the region. --region-shear S widens 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-over records lifted_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_kept is gone). Now --region-crease ends 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's mask.box ends --region-shrink rows above the crease row (2 rows at the default), as it did before crease_kept. New, under --region-over only: 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-over nothing 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-solid frees 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-round holds 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 N moves 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 STRIP pairs 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_record in the strip's record (<name>.strip.json), which video-loop now writes, bound to the strip by cell_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_hold and gait_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) and as_filmed (true where the cell's pixels at the end of the cut are its pixels anchored before any repair, the receipt source_projection.before_repair_pixels_sha256 in 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, which video-cycle-align now 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 no cell_record (any cut made before this release), a record bound to another strip, a record that does not give its cells as video-loop writes 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-unpin makes 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 N sets 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 G grows 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-mask leaves 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_record in strip records, source_projection for motion anchors, and kept cut strip records. video-loop now writes cell_record into every strip record it writes (the fields above). The strip PNG, the GIF, the WebP and the frames of cycle/ keep their bytes; the strip record gains this one key. A cut's report gains source_projection (recipe, wrap_dx_px, before_repair_pixels_sha256) at --anchor motion and --anchor motion-auto too, with recipe motion-anchor-correction-v1 there; it was written only at --anchor none and body before (unchanged there). cell_record is 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 writes cycle.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 with video-loop removes it with cycle.source/. The aligned strip's record does not carry cell_record (it is the record of another strip). The pair policy RECUT_POLICY is now same-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-fps with the air retimed, the report's held_fill.out_fps gains source_frames (per cell, the frame of the cut it is, or null where it was made), and cell_record now reads a retimed cut the same way as a cut at --out-fps: source_frame is 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's anchor_move_px and scale. as_filmed is 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, and video-sway --read-on-cut does 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_request and read_ask accept region_over (bool; default False) and region_shear (float; None: off). New in sprite_gen.video.sway: shear_floor, layer_sets, lay_over, cover_depth, still_strip, tip_shape and move_steps; constants OVER_POLICY, TIP_COLS, TIP_AIR, TIP_RING, TIP_OFF and TIP_SEARCH; RegionMask gains over, shear, hold and edges(); Masked gains sheared, left_out and left_out_in(k); rim_bands gains floor (None: as before).
  • Python callers: sway_loop, sway_frames, read_request and read_ask accept region_over_solid (bool; default False), region_rim_round (bool; default False) and region_membrane (int; None: off); sway_loop and read_request accept read_on_cut (Path; None: off, refused by sway_frames). New in sprite_gen.video.sway: membrane_sets, membrane_move(free, figure, own, outline, move, reach), recut_pair, recut_ask and read_cut; new in sprite_gen.video.loop: ramp_offset; new in sprite_gen.video.motion_anchor: laid_at; constants OVER_SOLID_POLICY, MEMBRANE_POLICY, RECUT_POLICY, RECUT_DRIFT and RIM_ROUND_POLICY; RegionMask gains over_solid, membrane and rim_round; Request gains read_on_cut; layer_sets(..., solid_only=False) gains solid_only and returns the new set below; read_on_relation(..., cut=False) gains cut; and transported_motion(..., paired=None) gains paired. New in sprite_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) and aligned_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_cut returns the strip picture under strip; Request gains aligned_from; new in sprite_gen.video.loop: constants CELL_RECORD, CELL_SCALE_STEPS and MOTION_RECIPE.
  • Tests: new file tests/video/test_sway_region_over.py covers 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-crease the 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-over the 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-mask with --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 auto with 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-shear 0.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_steps reads the most step both ways where both pixels are shown;
    • --frames gives 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.py now names --region-over and --region-shear among the arguments video-sway takes and video-sway-inspect does not.
  • Tests: updates to tests/video/test_sway_region_over.py and new file tests/video/test_sway_read_on_recut.py cover 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 names step_px and passes_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-round the 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-alpha 0 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 6 and --region-shear 0.35: with --region-membrane-unpin and --region-clear-alpha 8 the 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.4 and --region-membrane 6: with --region-own-outline 2 those 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 on layer_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 no cell_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 body whose 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 body whose ramps move no frame (both wrap_dx_px 0) 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's anchor_move_px is the correction's place and every cell is as filmed; the report's source_projection names the motion recipe;
    • video-loop records 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-cut the relation's refusal as ever, each leaving the loop as it was;
    • a record of its cells not there or not as video-loop writes 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, its source_frame, anchor_move_px, scale, and as_filmed missing 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-loop records 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-loop with and without the size hold: the record gives the factor the size hold scaled each cell by, equal to the report's size_hold.cut_frames, and calls none of the held cells as filmed;
    • the same walk cut twice by video-loop as 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's state, the report's strip's state, the strip record's state) is refused by the record of its cells; with the record's factors and as_filmed taken out too, refused naming the field; with the strip record's cell_record taken 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.py now names --region-over-solid, --region-membrane, --read-on-cut, --region-rim-round, --region-membrane-unpin, --region-clear-alpha, --region-floor-beside and --region-own-outline among the arguments video-sway takes and video-sway-inspect does 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 recorded filled: true, its cells listed in made, 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 fault held and is refused. A refused frame is made again at the nearest other fractions of RETIME_T within 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 a warning: line naming its cells. At --out-fps and in an air retimed with --air-retime, a cell refused this way is the nearer frame, listed in shown_again and named in a warning: 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 names shows (which of a, b and before the frame shows again). Each try the loop report records (tries) names shows where 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-fps cells. video-pipeline.md and SKILL.md are 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 with rife_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-fps 60 from 24 with eight cells listed in out_fps.shown_again; synthetic fall refused as held at 0.5 and 0.55 and made at 0.6 in changed test test_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 in air_retime.shown_again and 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 of tests/video/test_explicit_window.py, two tests of tests/video/test_gait_fallback.py, tests/video/test_ghost_given_way.py, one test of tests/video/test_one_step_cut.py, tests/video/test_play.py; and four more: the step screen test of tests/video/test_one_step_cut.py, the checkpoints test of tests/video/test_wrap_blend.py, a test of tests/video/test_once.py, and a test of tests/video/test_ghost_screen.py marked real_rife that hands frames to rife.Rife itself; 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 through rife_runs in tests/conftest.py (0 where rife_located() finds no binary), the tests/video/test_ghost_screen.py test through Rife.calls. With no binary found, every count is 0 and the two tests marked real_rife skip. 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 of tests/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.py and tests/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_motion gives each cell's root (the subject's mass centre, as inspect-motion's centroid_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 M it adds each root in metres from the first cell's (root_m) and each apex in metres. A game reads root to place each cell and moves the body on its own physics. video-loop prints each air in one line (air 0.42 s, apex 0.21 m) and video-set puts loop.air on each item.
  • New: video-loop --air-retime gravity=G,air=T,speed=V (and video-set --air-retime). Each air with its take-off and landing in the cut is given T seconds, G m/s² and V m/s along, any of them, each the clip's own where not given; G and V need --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's air_retime records 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 L plays 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 --start and --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 of upsample); qa.motion.centroid and qa.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.py with tests/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 cuts tests/video/test_held_fill.py pins 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-set hands 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 and video-resume; Anthropic messages and Message Batches; ElevenLabs sound. A value that is not an http:// or https:// 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_URL set, the finished clip is downloaded as GET <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. With SPRITE_GEN_ANTHROPIC_BASE_URL set, 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 (and GROK_HOME) is not looked at and XAI_API_KEY is used, claude auth status is not run and ANTHROPIC_API_KEY is used, and codex is not usable (codex login status is not run; a default codex asks or runs what you chose for a codex that cannot run, naming the variable, and --provider codex stops). 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 is on, 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-resume calls 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 --help together is 158,857.
  • Python callers: new module sprite_gen.gen.address (PROVIDERS, base, url, fetched, FETCH_PATH), sprite_gen.gen.base.LOGINS_ENV, LOGINS_OFF and logins_on, new module sprite_gen.workflow.capabilities (document, PROVIDER_CALLS, NO_PURCHASE). Removed: the module constants xai.API_BASE, openai_provider.API_BASE, anthropic_api.API_BASE and sprite_gen.audio.provider.BASE, which kept a provider's address where a variable could not move it; video no 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-loop prints poses/cells in its summary and video-set puts loop.poses on 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 as video-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 fault contact). 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, as video-cycle-align reads 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 and sprite-gen rife install.
  • New: video-loop --out-fps F and video-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 says out_fps and source_fps, and source_cut.times in place of samples. With no RIFE the cut is delivered at its own rate with a warning. video-cycle-align and video-stop refuse such a loop; video-set refuses 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), and video-cycle-align reads 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 off byte 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 through video-loop and video-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 depth d 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 (or depth) × 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 breathe records the row's range ({"width": [min, max], "height": [min, max]}) in breathe.json for 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_lift is the chest's rise from rest to the top, which video-sway --breathe and --avoid-region read: (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_x and torso_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 in tests/effects/test_breathe_js_mirror.py (minimum and maximum parity, breatheRange), the value-shape matrix over the four keys and the kept depth_x and band in tests/effects/test_breathe_sidecar_roundtrip.py, and the mirrored constants in tests/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-loop names 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 (no cycle.steps) is kept, recorded in cycle.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-auto cuts 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 1 cuts 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, recorded cycle.steps {"count": 2, "by": "two-lengths", ...} and cycle.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-auto no longer refuses a walk or run for its opening frames alone. Where auto_motion.discover finds no two regions through the whole clip (automatic motion anchor needs two separated regions trackable throughout the clip, or found 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 exception auto_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 new untracked_opening (frames, first, shorter_than, refused) and, once a cut is found, a warning line video-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-loop detects 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 as video-loop: no periodic cycle found, so an app could not name that the body turned as the reason to film it again. The new module sprite_gen/video/body_turn.py introduces reading torso-side-v2 on 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 within GUARD (2.5 px) and TOL (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 constant MASS_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. Under HEAD_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 within HEAD_REACH as 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's side correlation is (v.s - v.m) / (1 - s.m), where each correlation is taken at its nearest about the axes within TOL. Under module constants SIDE_SHOWN_MIN = 0.08, TURN_SIDE_MAX = 0, and TURN_RUN_MIN = 4 consecutive frames, candidate windows whose cut holds a frame of a turn are refused with the 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 within HEAD_REACH of 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) prints video-loop: the body turns in the walk as its first line, prescribes filming it again with the torso and hips kept at the still's angle, hands over nothing, and sets status: failed, supporting app retake rules such as loop-body-turned.
  • Report fields (<name>.loop.report.json): every walk or run report under --anchor motion-auto adds the body_turn object containing reading (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 (warn or refuse), verdict, refused (how many windows were refused for it), cut (frames, the cut's first and last clip frame, and holds, the turned frames it holds), avoiding (the search's refusal where the search that avoided the turn found nothing), and unread (a list of {frames, why}, each reason with the frames it applies to, appearing only where at least one frame was not read). The verdict field records one of none (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), or refused (--body-turn refuse). Where the still passes SIDE_SHOWN_MIN and the walk is seen square, video-loop prints one warning line under --body-turn warn and refuse alike, beginning video-loop: warning: the walk reads square against a still that shows a side (still_side and ending check the loop's facing. The command's JSON summary also gains body_turn (verdict, turns, cut) where a turn was read.
  • Python callers: new module sprite_gen.video.body_turn provides read(frames), square(reading), turns(side), turned(reading), neck(body), torso_rows(at), class Turn(reading, skip=0) (callable as (start, length), returning the refusal reason or None, held(start, length), counter refused), refusal(...), kept(...), unfound(...), constants READING, 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 as frames.SPECK_MIN_FRACTION), HEAD_CORE (0.5), GUARD (2.5), TOL (2.0) and STEP (0.25). Functions local_cycle.detect, local_cycle.by_steps and local_cycle.counted take a new keyword argument turn (a Turn, default None: as before). Function loop.run_loop takes body_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. With HEAD_REACH it reads no turn (least +0.11) and is cut as before. Where no solid pixel of those rows lies within HEAD_REACH of 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 by video-loop under 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 field walk_side in body_turn keep 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 within GUARD (2.5 px); walk_side is the median of frame nearness to the still minus nearness to the mirror (v.s - v.m), where a frame that flips under HELD_MAX (0.5 %) of the drawing last counted's solid pixels (alpha 128 or more) is not counted, so each drawing counts once and walk_side is 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 and video-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 under HELD_MAX it 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 moved HELD_MAX from 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) its walk_side lies under WALK_SIDE_MIN and it is not read; seen at an angle its walk_side lies over WALK_SIDE_MIN and it is read. Where the still passes SIDE_SHOWN_MIN and walk_side lies between -0.045 and +0.045, the walk is seen square: read is false, verdict is not-read, why starts "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-loop prints one warning line under --body-turn warn and refuse alike, beginning video-loop: warning: the walk reads square against a still that shows a side (still_side, giving the still's side and walk_side in 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 ending check the loop's facing. Reading walk_side costs 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-read from 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 by WALK_SIDE_MIN: that square walker's still is read when SIDE_SHOWN_MIN is lowered to 0.06 (or GUARD set to 2, or STEP to 1), but its walk is not (walk_side 0.000); only with WALK_SIDE_MIN also at 0 does it read turns (frames 15 to 21 and 39 to 43). GUARD and TOL are 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 under HELD_MAX of 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 over HELD_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; over WALK_SIDE_MIN it is read and reads turns it does not make. And a drawing that flips under HELD_MAX of 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's chest_* keys) moves out from its peak by chest_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_round plus arms_x in 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 by arms_x on 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 refuses depth, depth_x, lag and smooth-only shape keys; smooth refuses chest_round and arms_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 full arms_x of 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-mask piece (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 in props.pieces[i].hidden and hidden_max of breathe.json, printing one warning line on stderr of the form breathe: 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 drawn followed by breathe.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 in props.pieces[i].filled and filled_max of breathe.json (held cells themselves are never counted), printing one warning line on stderr of the form breathe: 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 moved followed by a space and breathe.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 in props_behind.pieces[i].filled and filled_max with a warning line on stderr of the form breathe: 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 moved followed by a space and breathe.json props_behind.pieces[K-1].filled; its hidden cells (under held cells, the body, or a front piece) are counted in props_behind.pieces[i].hidden and hidden_max with a warning line reading goes under held cells, the body or a piece held in front of it and 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 lower chest_round or arms_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 colour or 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-mask or 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 (default piece; 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.json records hold, props, and props_behind (path, sha256, cells, each piece's shift_px, hidden, hidden_max, filled, filled_max), with each piece carrying colour and the mask carrying groups: "colour" and colours when grouped by colour. sprite-gen breathe also takes --axis-x and --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|auto keeps 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 of PX px past it, leaving pixels outside the band unchanged byte for byte. --band-margin PX|auto (default auto, ceil(reach) + 1) sets how far past the ellipse the weight stays 1. --band auto sets the band to ceil(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 where reach x pi / (2 x band) >= 1 or lowering gain under --on-fold lower. --band-up FLAT[,PX|auto] shapes the area above the centre separately, stopping the flat part FLAT of the vertical radius above the centre and falling over PX px (defaulting to the band or HANG_PAST of 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 gain g keeps 1 - g x steepest of its area, so a region folds where g x steepest >= 1. Then --on-fold refuse refuses, 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 --gain or give a wider --band (or --band-up, when it was given); --on-fold lower lowers that region's gain to the largest whole number of 0.01 steps, 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 within CARRY_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|DIR leaves pixels as they are while a band moves its regions round them, requiring --band and 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 within CARRY_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 by HOLD_GROW (3) px. Each cell keeps byte for byte the mask pixels, soft edges, and air within ceil(reach) + HOLD_EDGE (2) px. Other pixels are read short of kept pixels along the move direction by f = min(s, h) px, where h is HOLD_SLOPE (0.5) times free distance to kept or margin pixels (HOLD_MARGIN of 1 px), bounded to rise by at most HOLD_SLOPE per pixel (read_share). Reads touching forbidden pixels are renormalised or walked back by 1/HOLD_STEPS (1/16) of their move. Metadata gains follow.hold (and sway.json gains hold for --frames), while stdout JSON gains hold with pieces, lay_cells, and read_folded_px_max.
  • New: a region given as a mask (--region-mask, --region-rim, --region-shrink, --region-crease). --region-mask MASK.png|DIR gives 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-crease aligns the mask's lower edge to the median darkest row from CREASE_UP (5) rows above to CREASE_DOWN (3) rows below over CREASE_SPAN (2) columns either way, and --region-shrink PX (default SHRINK_DEFAULT, 2) wears the mask in by 4-neighbour steps. One mask is carried into each cell by its own solid pixels within CARRY_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 within REGION_SOFT, 2, px of the region, not beside another solid pixel) move, and the air (clear pixels within ceil(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 by sin²(pi/2 x d) from 0 at held pixels to 1 across a rim scaled by --region-rim SCALE (default RIM_DEFAULT, 1.0) and widened until slope is at most RIM_SLOPE (0.9), preventing folding. With --band-up, weight is the lesser of the rim and the upper yield. Strip metadata gains follow.region_mask (and sway.json gains region_mask for --frames), while stdout JSON gains region_mask with kept_cells, rim_px, move_most_px, and walked_px_max. See video-pipeline section 6.
  • Python callers: sway_loop, sway_frames, read_request, and read_ask accept band, band_margin, and band_up (band_up as (flat, px_or_"auto") or command-line string). New in sprite_gen.video.sway: band_weight, band_shapes, carry_match, carry_own, band_steepest, steepest_gain, band_ledger, band_notes, and jacobian (moved from sway_inspect, which retains it under the same name); constants BAND_POLICY, CARRY_BASIS_BAND, CARRY_SEARCH, HANG_PAST, PRESSED, STRETCHED, MOVED_PX, and AUTO; and methods Answer.band_field(k, xx, yy) and Answer.band_record(). sway_loop, sway_frames, read_request, and read_ask accept hold_mask (a Path to a PNG or folder; None: off); new in sprite_gen.video.sway: Hold, read_hold, Held, hold_sets, free_back, read_share, draw_held, hold_ledger, hold_notes, and carry_mask; constants HOLD_POLICY, HOLD_GROW, HOLD_EDGE, HOLD_MARGIN, HOLD_SLOPE, HOLD_ROUND, and HOLD_STEPS; Ask.hold, Answer.hold, Answer.held_cell(k), and Answer.hold_record(); and carry_own now calls carry_mask (same behaviour).
  • Python callers: sway_loop, sway_frames, read_request, and read_ask accept region_mask (a Path to a PNG or a folder; None: off), region_rim (float; None: 1.0), region_shrink (int; None: 2), and region_crease (bool); new in sprite_gen.video.sway: RegionMask, Masked, crease_of, carry_region, rim_bands, rim_distance, region_sets, region_ledger, and region_notes; constants REGION_POLICY, RIM_SLOPE, RIM_DEFAULT, SHRINK_DEFAULT, REGION_SOFT, REGION_AIR, CREASE_UP, CREASE_DOWN, and CREASE_SPAN; Ask.mask, Answer.mask, Answer.mask_field(k, xx, yy), Answer.masked_cell(k), and Answer.mask_record(); and draw_held gains short (default true; false reads every pixel at its whole move).
  • Record fields: follow.band in strip metadata and band in sway.json record policy (own-pixels/margin-band-cos2/1), asked ({band, margin, up}), reach_px, band_px, and margin_px. They record per-region flat_px and band_px (across, above, below); per region in follow.band.regions[i], steepest: per_gain (the slope per unit of gain), cell, and ratio (the region's gain times per_gain, under 1 on any written strip); carry with search_px (9) and per-cell, per-region px, from (base, pixels, or lay), why for lay, least, and curvature; lay entries for cells carried by lay; and ledger lists per cell (with <key>_max values) for band_on_regions_px, pressed_px, stretched_px, pressed_box, stretched_box, area_least, area_most, outside_moved_px, and jacobian_min. Only the four counts warn: band_on_regions_px, pressed_px, stretched_px, and outside_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 (for pressed_px and stretched_px also 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.lay on --loop-dir, sway.json band.lay on --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 gains band containing band_px, margin_px, and lay_cells.
  • Record fields: follow.hold in strip metadata and hold in sway.json record policy (own-pixels-grown/kept-edge-air/read-short-sloped/1), asked (per_cell, and sha256: 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), and steps (16). They record pieces with each piece's px and box (x0, y0, x1, y1) on the cell it was drawn on (empty for a folder); carry with search_px (9) and per-cell, per-piece px, from (base, pixels, or lay), why for lay, least, and curvature (null for a folder); lay entries ({cell, piece, why}) for pieces carried by lay; and ledger lists per cell (with <key>_max values) for held_px, soft_px, air_px, short_px, renormalised_px, walked_px, read_folded_px, read_folded_edge_px, read_least, read_turn_folded_px, and read_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.lay on --loop-dir, sway.json hold.lay on --frames. For renormalised_px, walked_px, and read_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 gains hold containing pieces, lay_cells, and read_folded_px_max.
  • Record fields: follow.region_mask in strip metadata and region_mask in sway.json record policy (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, and up: {flat, band} or null), soft_px (2), and air_px (ceil(reach) + 2). They record rim (across_px for Lx, down_px for Ly, least_px: the two bands it started at, slope: the steepest (pi/2) x sqrt(...) over the cells, and slope_bound: 0.9); mask (px: its pixel count as worn in, box, and carried_by_px: the solid pixels it was carried by; null for a folder); crease (per mask, rows: each column's row, keyed by column, and free_columns; null when not asked); carry (search_px of 9 and cells: per cell px, from: base, pixels or before, guess: before or lay where carried by its pixels, why where it kept the cell before's carry, least, and curvature; null for a folder); kept entries ({cell, why}) for cells keeping the carry of the cell before; up containing the upper yield's shape as a band's record (reach_px, band_px, margin_px, per region flat_px, band_px and steepest, its carry and lay; null without --band-up); and ledger lists per cell (with <key>_max values) for region_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) with move_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, and walked_px. Warning lines on stderr report cells that kept the carry of the cell before (ending follow.region_mask.kept), a region whose --band-up yield was carried by the lay (ending follow.region_mask.up.lay), and for held_changed_px, pressed_px, stretched_px, read_held_half_px, renormalised_px and walked_px when 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 with follow.region_mask.ledger.<key> on --loop-dir or sway.json region_mask.ledger.<key> on --frames. Command stdout JSON gains region_mask containing kept_cells, rim_px ([Lx, Ly]), move_most_px, and walked_px_max.
  • Tests: synthetic tests in new test file tests/video/test_loop_body_turn.py verify 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; and SIDE_SHOWN_MIN set 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's body_turn.reference is 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 with WALK_SIDE_MIN at 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 at HEAD_REACH 0.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, warn keeps the cut the search took before, byte for byte, with the warning line, while refuse refuses it with video-loop: the body turns in the walk as 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; warn refuses it in the words it was refused in before (video-loop: no periodic cycle found), after the warning line naming the turn; refuse refuses it with video-loop: the body turns in the walk. Passing --body-turn refuse without --anchor motion-auto is refused. New synthetic tests in tests/video/test_loop_body_turn.py verify 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 default warn, 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. For torso-side-v2, new synthetic tests in tests/video/test_loop_body_turn.py verify 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_SHARE on 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_CORE on 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 than TOL and the walk still reads no turn; at 0.35 the ornament moves it less than TOL and 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); with GUARD 2, STEP 1 or SIDE_SHOWN_MIN 0.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 with WALK_SIDE_MIN at 0 as well it reads turns; TOL 0 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 at TOL 1 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 over SIDE_SHOWN_MIN, walk_side under 0.005, and is not read, while with WALK_SIDE_MIN at 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 its walk_side is the same as drawn on ones (within 0.002 with a piece); with WALK_SIDE_MIN at 0 it reads turns. The plain, hooded, turning and hooded turning walkers held the same way have the same walk_side as 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 same walk_side as without the noise and is not read (with HELD_MAX at 0 it is read, with turns), while the turning walker held the same way with the same noise has the same walk_side as without it and reads its turn over the frames that hold drawings 30 to 40. Through libx264 (its default crf 23) and video-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_side under WALK_SIDE_MIN), and seen at an angle is read (walk_side over WALK_SIDE_MIN). walk_side lies 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, and WALK_SIDE_MIN is 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_side under 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_side under 0 and no warning. Cut by video-loop, the walker turned square at frame 24 and held to the end is not read (verdict not-read, walk_side under 0.01), prints exactly one warning line beginning video-loop: warning: the walk reads square against a still that shows a side (still_side and ending check the loop's facing that gives the still's side and walk_side and 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 in breathe.json and 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 colour follows 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-mask slides out from behind a held arm with its rim cell filling the space and no gap, while given as --props-mask the held arm's outline fills that space instead; --props-groups without 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 in breathe.json and 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) and tests/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.py covers 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 (no band, no carry_basis);
    • auto reads 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-up keeps the gain asked;
    • --band-up stops 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 --band is refused with its reason (a flat share, --stretch-floor, --band-margin or --band-up alone) 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;
    • --frames gives the strip's cells, and a turned loop under --read-on is the cut's banded sway cell for cell. tests/video/test_follow_inspect.py now names --band, --band-margin and --band-up among the arguments video-sway takes and video-sway-inspect does not.
  • Tests: new file tests/video/test_sway_hold.py covers 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-mask the band is as before (no hold in 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_px 0 in every cell, and where the read turns from the whole move to its share, read_turn_folded_px 0 and the least area over 0);
    • a folder of the carried masks gives the same strip and ledger as the one mask;
    • --frames gives 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-on on 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 relation transported and 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.py now names --hold-mask among the arguments video-sway takes and video-sway-inspect does not.
  • Tests: new file tests/video/test_sway_region.py covers 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-mask the sway is as before, plain and with --band (no region_mask in 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-up yields 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-crease ends 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;
    • --frames gives the strip's cells and the same record;
    • a loop turned from a cut and moved under --read-on on 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.py now names --region-mask, --region-rim, --region-shrink and --region-crease among the arguments video-sway takes and video-sway-inspect does not.

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-frames refused the clip, and the walk had to be filmed again with --shape wide. The walk and run rows 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 its GAIT_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's room records the view, the silhouette, the room on each side, the bound, short, added_px (columns per side) and added_rows, and a widened canvas's why says why. --shape square keeps the still's own square. --shape wide is still the walk's 16:9 row (GAIT_WIDE). See video-pipeline section 1.

  • Changed: canvas.subject_rows is now canvas.subject_box, which reads the columns as well as the rows. --fit tight reads 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|magenta and extract_route on a background the engine does not recognise as that key. Such a background was keyed against the pure key and nothing came off, and cutout exited 0; a green behind dark edge strips was routed to the white matte. It is now measured (route: measured, chroma_key_painted the measured colour), so video-canvas repaints such a still to the exact key, and cutout keys the frames of such a clip one by one. video-frames keeps 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 with video-canvas now works on these backgrounds.

  • Fixed: cutout fails when it made nothing transparent, like gen/chroma.py, instead of reporting success.

  • CLI: cutout --key measured forces the measured matte; auto sends 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) and cutout(..., measure_unrecognised=True, refuse_empty=True) (video-frames passes both False); new cutout.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 through extract_route, cutout and video-canvas; a cutout that keys nothing fails.

  • Tests: tests/video/test_walk_canvas_room.py covers 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 tight and another state are not read;
    • --view works from the command line.

    Four video-set tests' canvas stubs now take view, and test_edge_speck_lead_in.py reads the walk's own row.

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 retake record. 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, reason part-pop): remedy is retake where the engine's search chose the cut, and recut-or-retake where the cut was given (--cycle fixed, or pinned); searched says 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, constant rife.GHOST_BAND = 0.10) to catch limbs seen through. On frames the cycle alignment makes, rife.ghost_window counts the same part-covered pixels in regions at least rife.GHOST_THICK (5 px) thick that rife.ghost counts, 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). Over interpolation_quality.GHOST_WINDOW_WARN = 0.014 (1.4 % of a window's solid pixels), the made frame has the fault ghost (though whole-body ghost stays 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 on video-loop's jump repair frames or filmed frames.
  • New: video-cycle-align reads the loop's beat and keeps frames given way on it under --between auto, checks for the same foot stepping twice, and video-loop records whether each cut steps the same foot twice (clip_feet). On every aligned loop, video-cycle-align reads the leg path over the lowest LEG_PATH_BAND = 0.10 of the figure box (BLOCK 8 x 8 px, SEARCH 12 px, MATCH_BAD 40 of 255, READ_HEIGHT 410 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) within BEAT_JOLT of 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 under align.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 in beat.named, and carry the broken-beat reason under --between auto in the retake record when beat gaps remain at BEAT_JOLT or more. On views where feet stand side by side (STEP_VIEWS = back, back_diagonal), video-cycle-align reads 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 reason same-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's retake list carries these loops like the others (under --between nearest a broken beat is recorded in beat but is no reason). video-loop reads 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) in strip.json and its report.
  • New: video-cycle-align reads 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 lowest cadence.SCREEN_ROWS = 0.30 (legs; a strip cell's lowest 125 of its 406 px), read at READ_HEIGHT 410 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. Under cadence.screen_record, a step is a jump when, over the box or on its leg rows, it is at least cadence.SCREEN_JUMP = 2.0 times the cycle's typical step and at least cadence.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 the retake reason filmed-jump (details filmed_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 gives seam-jump (details seam_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 (limits screen_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.beat in strip.json and report row beat record jolt, gap, over, jolts, limit (0.25), band (0.1), and path (read, on-time, or unread with why). Each smear row (and a frame made again, under retimed) records ghost_window and ghost_window_at ([from, to] fractions of the body); both are null where the ghost screen does not read the loop. A retimed frame's row in smear has method: "retimed" (beside rife kept and nearest given way), keeps its first frame's measures and faults, and gains retimed: t, from_t, off, measures, faults: [], look. Every frame given way in a loop whose beat broke gains retime: between, tried (each fraction recording ghost_window, and window_over where it had no fault but read over the bar), off_nearest. Retimed frames count in made_at and made_by_rife, not nearest_at or replaced; the report gains a set-wide retimed count, and beat.retimed lists them per loop. Widened runs record in beat.widened (run, width, and moved with at, off, new source or pair and fraction); moved frames carry smear method: "moved" with moved and count in made_at. Runs kept on the nearer source frame record in beat.named. cycle_align.same_foot in strip.json and the report row records read, order, steps (half, frames, peak, lift), twice, and clip. clip_feet in strip.json and the video-loop report records length, cuts, same_foot, alternate, unread, seam_in_step, and same_foot_at. Each loop row and strip.json cycle_align gain screen: whole and legs (every step), typical (per region), jumps (each: step [i, i + 1] as frames of cycle.source/, seam true for the last step, whole and legs each [change, times the typical step, times the next largest step], at the gaps [k, k + 1] of the aligned (turned) loop that show it), and limits (jump, alone, rows). Under --same-foot refuse, a refused report is written with applied: false, refused: "same-foot", and same_foot; the report's same_foot key names the mode. A loop's retake record (keeping its shape: reason the first, reasons all, details under each reason's snake_case key, limits) gains reasons filmed-jump (details filmed_jump: steps, at, whole, legs, remedy), seam-jump (details seam_jump: steps, at, whole, legs, remedy; limits screen_jump, screen_alone, screen_rows), broken-beat under --between auto (details broken_beat: jolt, gap, over, named, remedy; limit beat_jolt) and same-foot (details same_foot: order, twice, clip counting length, cuts, same_foot, alternate, unread, seam_in_step, or null, remedy; limits lift_min, lift_cells, down_max), in order: held-drawings, filmed-ghost, filmed-jump, seam-jump, broken-beat, same-foot; remedy is "retake", "recut", or "recut-or-retake", and the report's retake list carries these loops like the others.
  • Python callers: new module sprite_gen/video/cadence.py with leg_path, Beat, beat_record, turned, same_foot, clip_feet, view_reads_feet, screen_steps, screen_record and constants LEG_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), and SCREEN_ALONE (1.3); in sprite_gen/video/rife.py ghost_window and GHOST_BAND (0.10); in sprite_gen/video/interpolation_quality.py GHOST_WINDOW_WARN (0.014); in sprite_gen/video/align.py measure_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"), and resample facts gaining beat.
  • Output changes: under default --between auto, alignment outputs where frames given way broke the beat change when retimed or widened to keep the beat under BEAT_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 nearest and rife keep their exact bytes across strip PNG, GIF, WebP, and cycle frames (gaining the beat record, ghost_window, retake reasons, and where --view is back or back_diagonal same_foot in strip.json and reports; under --between rife the alignment keeps the made frame and names it a ghost); every aligned loop's strip.json and report gain screen, and loops whose cut jumps gain the reasons, frames unchanged. For video-loop (and the loops video-set cuts), strip.json and report files gain clip_feet on every walk or run cut, while strip PNG, GIF, WebP, and cycle frames keep their exact bytes. All outputs from video-loop-compare and video-loop-repair are unchanged, bytes included.
  • Tests: synthetic test suite in tests/video/test_cycle_align_beat.py uses 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 recording window_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 nearest recording the jolt it leaves; same foot detection on back loops reading "RRL" (twice) and alternating "RL" round the ring, dipping under LIFT_MIN without reaching DOWN_MAX reading one step and reaching DOWN_MAX reading 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_step 1, 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 reasons broken-beat and same-foot with remedies (--between nearest and a beat with no gap over being no reason); integration through video-loop and video-cycle-align recording clip_feet, --same-foot refuse stopping the set with strip untouched and report refused, and naming the same-foot loop "film this direction again (same-foot)", with remedy "retake" and the clip's counts. New synthetic test suite in tests/video/test_inbetween_seen_through.py uses 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 judged ghost; under --between rife the 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 carry broken-beat among their retake reasons (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 in tests/video/test_screen_jump.py exercise 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 through video-loop and video-cycle-align at the cut's own length, the jump is named with the aligned loop's frames that show it, recorded in strip.json, while a cut whose changes are alike names nothing. Also tests/video/test_loop_prop_seam_held.py now expects screen among cycle_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, retake recut-or-retake, --unfixed refuse refuses, and under warn it is the bytes it was; a clip whose fist drifts through every cut keeps the search's cut to the bytes it was, retake retake; 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=torch runs 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's IFNet_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's RIFE::process_v4 (MIT, notice in NOTICE). SPRITE_GEN_RIFE_DEVICE names cuda (default) or cpu. SPRITE_GEN_RIFE_TTA means 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 to SPRITE_GEN_RIFE_BACKEND). This unpacks the model, and makes a check frame through PyTorch on SPRITE_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. cuda where 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 auto the 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-cache never 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 reaches sprite_gen.video.rife_torch.serve on 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 a video-loop makes 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-cache is 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 with SPRITE_GEN_RIFE_DEVICE (the device is the executor's), a send that cannot be imported, and an executor whose rife.py or 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 with allow_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 name executor and the executor's device and gpu; the overlapped wrap counts runs and executor_calls. Measured on an NVIDIA T4 rented from Modal, from a host of two CPUs without PyTorch: a 960 x 960 -x -z frame 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.sh tests PyTorch 2.13.0 CPU after the suite. After the suite, PyTorch 2.13.0 CPU is installed into the same environment. It runs sprite-gen rife install --backend torch's check frame. It runs every test marked torch_rife with SPRITE_GEN_RIFE_DEVICE=cpu, with none skipped. --rife-only runs the same. --rife-unmeasured lets torch_rife tests skip as it lets real_rife ones. CUDA is not measured by this lane.
  • Lane: scripts/t4_lane.py tests the torch backend on an NVIDIA T4, rented from Modal. modal run scripts/t4_lane.py builds 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 by sprite-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 marked torch_rife and not real_rife on CUDA, with none skipped. --whole-suite first 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; -z and -x give 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 in tests/fixtures/rife-walkers are 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 what pack writes 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); marked torch_rife: rife_torch.serve makes 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 torch installs 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 carries real_rife or torch_rife); tests/release/test_t4_lane.py (the T4 lane installs the PyTorch and the Python the Linux lane does); new pytest mark torch_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-align now reads a new hole fault 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-align reads 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 rife the frame is kept and named in the warnings. video-set --align-cycles auto runs 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 (no smear), there is no part coverage (no ghost), and the leg's own fill is the only line round the band. The fault outline needs 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 reading rife.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 fraction t of the way from source frame a to source frame b, a pixel of it lay in a at t of the motion back and lies in b at 1 - t of 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 at t on 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 fault hole is 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 smear list in the video-cycle-align report (and in cycle_align in strip.json) gains hole. A frame given way for it carries faults: ["hole"] and method: "nearest", and gets a line in warnings; 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 --between help 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), and rife.HOLE_PAIR_STEPS (5000); new interpolation_quality.HOLE_WARN (0.0); interpolation_quality.faults(measure) returns "hole" where the measure carries a hole reading over HOLE_WARN, and measures without a hole key 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 replaced and nearest_at rather than made_by_rife and made_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 gains hole on 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 reads outline_loss 0, outline_shift 11.3 % (so no outline fault, which needs both over 5 %), ghost 0, and hole 2.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 read hole 0 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: hole 0, 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 read hole 0. 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: hole 0 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 reads hole 0.10 % (its 64 pixels) and both made cells are given way to the nearer source frame, with faults: ["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, reads hole 0 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 read hole 0. A frame between with a hole unlike both source frames' (the gap drawn 16 by 40 px: hole 1.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 with hole among 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, read hole 0 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 reads hole 0 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 reads hole 0 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 reads hole 0 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 reads hole 0 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 reads hole 0 and gives way for outline, 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 read hole 0.29 % and 0.45 % and give way as in 3.1.0, now with hole among their faults besides outline. The jump repair of video-loop, its eased retime and overlapped wrap, video-loop-compare, and video-loop-repair do not read hole; their measures and outputs are as in 3.1.0. A --between-cache directory written by 3.1.0 is not taken from by this version: the code of rife.py is 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_loss 0, outline_shift over 5 %, dark_excess below 0, ghost 0, partial_excess 0, no fault) and that with hole the fault is ["hole"]; that resampling the two frames to four under --between auto takes the nearer source frame at both made cells (cells 1 and 3) with the fault named in the warning words, while --between rife keeps 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 reads hole 0, 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 and hole among 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) reads hole 0 and is marked slow, so it runs with pytest --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) reads hole 0 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 with faults: ["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 reads hole 0. A test marked slow (it runs with pytest --full) checks that 125 frames read hole 0: 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 with hole among 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 with hole among 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 with hole among their faults; and that with rife.HOLE_PAIR_STEPS set 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 reads hole 0 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 with hole among 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-align now reads a new doubled fault 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-align reads 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 rife the frame is kept and named. video-set --align-cycles auto runs 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 (no ghost), nothing darker is added (no smear), the line is inside the body and the edge keeps its line (no outline), 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 reading rife.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 fault doubled is 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 smear list in the video-cycle-align report (and in cycle_align in strip.json) gains doubled. A frame given way for it carries "doubled" in faults and method: "nearest", and gets a line in warnings with 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 --between help 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); new interpolation_quality.DOUBLED_WARN (0.03); interpolation_quality.faults(measure) returns "doubled" where the measure carries a doubled reading over DOUBLED_WARN, and measures without a doubled key 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 replaced and nearest_at rather than made_by_rife and made_at. Other made frames are delivered as before with the same bytes; the report gains doubled on 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 reads outline_loss 0, outline_shift 0, ghost 0, hole 0, crossfade 0 and doubled 0.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 read doubled 0 and are kept. The jump repair of video-loop, its eased retime and overlapped wrap, video-loop-compare, and video-loop-repair do not read doubled; their measures and outputs are as before. A --between-cache directory written before this version is not taken from: the code of rife.py is 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 reads doubled 0.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 auto takes the nearer source frame at both made cells with the fault in the warning's words, while --between rife keeps 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 of tests/video/test_crossfade.py keeps 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 under auto as 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 under auto is kept with doubled under 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_ltrb before scrub, small-component cleanup, optional integer body ramp, one shared integer crop, and standard resampling. Unmodified cells must reproduce exactly, and cut frames must match source_projection hashes; a changed move on a replaced cell is refused as source-processing-receipt-mismatch. Reports without cut_frames stay unknown and source-processing-unsupported. Malformed cut_frames exit 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_hold records cut_frames on held fixed cuts, giving an ordered list of exact float entries with scale, foot_point_px ([x, y]), and lift_px (or null).
  • Repair records: projection in repair reports and candidate restoration receipts gain size_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, and gait_fallback.hold_frame(frame, move, pad) applies it to one frame. gait_fallback.undo_scale uses 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 verdict improved and 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 ended unknown, source-processing-unsupported with no candidate. For six synthetic cuts (174 files), video-loop matches 3.1.0 except producer and size_hold.cut_frames. For five non-held cuts (110 files), video-loop-repair matches 3.1.0 except measurement_engine and candidate report digests.
  • Tests: tests/video/test_held_cut_restoration.py checks that the synthetic walk away cut on frames 24 to 47 with --anchor body restores smeared cell 9 byte for byte with verdict improved, 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 lacking cut_frames stay source-processing-unsupported; checks that four malformed records exit nonzero with no candidate; checks that a 1 % scale alteration triggers source-processing-receipt-mismatch; and checks that frame_hold round-trips through JSON to match undo_scale with 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 fixed with 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's size_hold gains at_cut on 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 off keeps filmed frames pixel for pixel, recording size_hold: {"applied": false, "why": "--size-hold off"}. Automatic searches with --anchor body, feet, or none, --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_hold records feet (min: 0.01, method: one-cycle-on, change_px, held).
  • Note: What --size-hold off leaves in place. With --size-hold off, motion-auto keeps 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 with off keep their previous bytes.
  • Changed: Held fixed cuts are not restored from source frames. video-loop-repair reads cuts through source projection, which treats size_hold.applied as source-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-auto cuts of clips with climbing or sinking feet change bytes when size changes by 1 % or more. Across ten synthetic walkers cut four ways with auto and off, 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 %), plus motion-auto of 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 under motion-auto at 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 under motion-auto moves 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) returns min, method, change_px, held, and lift (frame shifts in px, None when not held). gait_fallback.FOOT_HOLD_MIN (0.01) is added. gait_fallback.undo_padding and undo_scale take lift=None. gait_fallback.held_box(box, k, measured, pad, lift=None) maps filmed frame k boxes 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-auto on the 96 px climbing walk passes held on row with motion anchor applied; --size-hold off gives filmed frames pixel for pixel and records why; stable walkers keep identical bytes under auto and off and record not held; idle fixed cuts omit size_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 and held_box aligns head boxes; --anchor motion regions 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_cut shows 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, and feet for 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. In tests/video/test_loop_silent_pass.py: the walk away jitter test passes --size-hold off so 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. pixel still 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 smooth or sidecar mode: "smooth" for an illustration cut by its frame. It advises a wider cell margin or lower depth for 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. smooth solves displacement only for pixels that move. Anatomy and settings checks run once per row, and sprite-gen breathe shares 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 for smooth. For an outlined figure with arms in pixel, it fell from 0.98 s to 0.05 s. These measurements exclude PNG reading and writing. bake_breathe_sequence(images, cfg, anat=None) and anatomy_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 --frames moves full-size frames and writes them with sway.json to a new folder. A whole cycle/ can supply its frame time; other damped-mass runs require --fps.

  • New: Sway on the breath. --breathe drives the move from a checked smooth breathe.json, with --lag setting how late the part follows. The first cell, rests and close have zero offset.

  • New: A region moved whole. A fifth --region number, flat, keeps the centre at full weight before the weight falls to the rim.

  • New: Across apart from down. --gain-across sets 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-inspect drops a pair's seam points covered by a third moving region. Its record uses schema_version 3.

  • New: Breathe beat chosen to miss the hands. In smooth mode, --avoid-region chooses a breath beat whose peaks keep the chest above the hands' own rise and records the choice in breathe.json.

  • New: The in-breath share. The smooth sidecar key inhale is 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. With breath_peaks, the rest between peaks p and q is at p + (1 - inhale) x (q - p). sprite-gen breathe --inhale S sets it, and the normalized smooth config in breathe.json always carries it. --avoid-region scores every candidate on the row's own inhale curve, the curve the bake uses. Sway --breathe takes the chest curve, the late curve and the phase check at the record's share, so breath_peaks phases 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's drive now also carries inhale. The curator sidecar round trip keeps inhale as 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_cells is the number of cells of the loop the row carries the breath of, an integer of 2 or more, and start_cell is 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, or breath_peaks whose cells are cells of that loop) is the loop's, and the row's first cell is then not necessarily at rest. With loop_cells left 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 in breathe.json always carries start_cell: 0 and loop_cells: null. sprite-gen breathe --loop-cells N --start-cell K sets them; --avoid-region is 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, and breathe.json records reference with the file's path and sha256. Sway --breathe reads start_cell and loop_cells from 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-floor read 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's reach_px, fold block and least_cell are the loop's, and least_cell is 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_px and body_bob_px come from or span it, and sway.json records reference with path and sha256. The sway record's drive now also carries start_cell and loop_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 integer start_cell, a loop_cells under 2 or non integer, start_cell at or above loop_cells, start_cell at or above the row's cell count with loop_cells left out (at the bake), breath_peaks whose last peak is within one cell of the end of loop_cells, a --reference of another size on either command, and --reference with --loop-dir. The curator sidecar round trip keeps start_cell and loop_cells as written and its range check mirrors the Python refusals.

  • Changed: Breath curve functions. breathe.smooth_wave(t, inhale) and breathe.smooth_shoulder_wave(t, lag, inhale) now require the share. The module constant breathe.INHALE is removed; the default lives in curation.BREATHE_SMOOTH_SHAPE["inhale"], and breathe.smooth_inhale(cfg) returns a row's share. breath_beat.choose(images, lift, inhale, avoid, anchor, frame_ms) and breath_beat.nudged(n, k, inhale) take it as well.

  • Tests: tests/effects/test_breathe.py checks border counts, advice, smooth edge preservation, and the second face search. tests/effects/test_breathe_js_mirror.py checks curator refusal wording and byte identity with the pixel bake. tests/effects/test_breathe_smooth.py checks 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_peaks rests at the share, out-of-range and pixel values are refused, and the CLI flag is honoured. tests/effects/test_breathe_smooth_curator.py checks that the sidecar round trip keeps inhale. tests/effects/test_breathe_publish.py checks 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, and tests/video/test_sway_seams.py check the Sway paths, drives, weights, gains and seams. tests/video/test_sway_breath.py also checks that the sway follows the share the record says for breaths and breath_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.py also checks that a stretch's cell i has the loop cell (start_cell + i) mod loop_cells phase for breaths and breath_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 --reference measures the anatomy on that frame, bakes with it and records it. tests/effects/test_breathe_smooth_curator.py also checks that the round trip keeps start_cell and loop_cells and that rows the bake refuses are kept and reported. tests/video/test_sway_breath.py also 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 --reference the carry is off by where the body lies in the first frame; that old records without the keys sway as before; and the --reference size and --loop-dir refusals. tests/effects/test_breath_beat.py checks beat choice and refusals, and that each beat candidate is read on the row's share. tests/video/test_follow_stretch_floor.py and tests/video/test_follow_inspect.py cover the changed inspection schema and frames options.

  • Tests: A plain pytest runs a fast bundle: tests marked slow are deselected, the header points to pytest --full, and the summary counts deselections. pytest --full runs every test. The release lane, scripts/linux_lane.sh, passes --full to both pytest calls, including -m real_rife, so its gate still runs every test. tests/release/test_fast_bundle.py checks both calls and probes selection with and without --full. The slow rule in pyproject.toml is 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 of video-stop, workflow, defaults, video-sway, and export-aseprite. Three fixture-first tests remain unmarked because other fast tests build their fixtures. In tests/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.py extracts 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. Removed tests/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". Removed tests/video/test_walk_steps.py::test_cycle_align_takes_a_loop_cut_two_steps_as_one_cycle and tests/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_is covers alignment from recorded steps: 2. Merged tests/video/test_loop_overlap.py::test_the_cli_passes_overlap_wrap_off_and_on_is_its_default into tests/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 --full now 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 is unverified as before. With a misreading before it, the misreading stands and the image is refused. A refusal message names every reading, for example the 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.mood and text_check.logo keep the deciding reading's verdict and read and gain max_reads and readings, each reading in order with its reading number, verdict and read lines, or reason when it could not be read. calls lists a check's call once per reading, each with reading (1 or 2) and effort (null where 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 recorded model: null. The values are facing_vision.CODEX_READ_MODEL and facing_vision.CODEX_READ_EFFORT. --model still 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_text returns (check, calls), a list of call records, instead of (check, call). facing_vision.codex_inspect takes optional model and effort keyword 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_key rules 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 --style or --scene names 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 at key (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-key is kept; when it is one of the title's colours, a warning says so. Before, such a cut passed with status: ok, no warning, key_hue_left 0 and a matching text check.
  • A cut that is see-through inside its letters is refused at matte. logo_matte.see_through_inside measures 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 as logo.rejected.png and 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> gains named, clash_at_pct and clashes, and steps.key.key is null when refused at key. logo gains see_through_inside with px, pct_of_visible, glow_reach_px, max_pct and wide. refused_at can now be key.
  • Python callers: logo_matte.choose_key(mood, box=None, named=None) takes named, the brief's colour words per key from logo.named_colours(style, scene), and returns key: None when both keys are the title's colours. logo_matte.see_through_inside(image) is new.
  • Tests: tests/gen/test_logo.py checks 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 than MAX_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.py checks 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.py checks 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.py checks that a title in both keys' hues is refused at key before 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 at matte and 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.py gains the quilt fixture: square fabric patches in outlined pixel letters, one with a counter, on a key. It also gains walled_patch (a navy letter with a mint patch on pure green, with squares or a pixel of the key painted in) and hollow_letters (the big O and A shapes), which lettering draws through its new shapes argument.

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-face builds a face pack from a reference, a keyed talking clip, and keyed body motions.
  • sprite-gen face-bake runs 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.mjs contains 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 play and say request, 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 plan planScene makes and face-bake --play bakes, and its voice and layer start at the plan's line_start after the own-mouth span. The queue has no length limit and drops nothing: a request whose sound does not load or decode, or whose line planScene refuses, 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.py uses tests/talking_face.py to 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-frames and video-set now 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 auto pass restores the subject's own colour to those edges.

    The video default stayed off until 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 in docs/chroma-alpha.md (its decontam section) 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), auto reduced 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 to off. The row extractor frames are a derived cache that heal re-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 off remained 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 with off follows codec noise smoothly, staying calm despite keeping an olive rim.

    video-frames and video-set now maintain a clip history in clip order. This history passes to each frame through decontaminate as history (decontam_history in cutout and remove_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_SETTLE 0.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 % with off, 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, and settled_px. held_px counts pixels where a held outcome or colour differed from an independent fit. blending_px counts pixels showing a mix of two calls rather than this frame's call. settled_px counts pixels the settle or a still step moved from the previous frame's output. In video, recovered_px is 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 with off, 3.25 s with the hold and settle alone, and 3.36 s now. Peak memory was about 400 MB with off, 945 MB with the hold and settle alone, and 1155 MB now, adding about 365 MB over off per megapixel. Because video-set keys three items at once by default, it can use about 2.3 GB more than off at 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 palette runs 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 off and 0.82 now. Its colour error was 41.7 with off and 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-frames prints a single line on stderr after its JSON summary when edge decontamination warrants attention. The line starts with video-frames: warning: decontam auto ... and ends by naming --decontam off as the way to keep the matte as it is.

    The warning prints when auto ran on no frames, when auto skipped 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-set prefixes this warning line with the item name and records it under warnings in the set report.

    The JSON report adds decontam.reason for the first skip reason and decontam.skipped_frames when frames are skipped. Per-frame stats and clip totals in the video fit add key_part_kept_px, behind_kept_px, held_px, blending_px, and settled_px. Where auto cannot 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, auto defaults to off, recording {"mode": "auto", "applied_frames": 0, "reason": "brightness alpha has no key colour to remove"}. Explicit --decontam palette with 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 off leaves. 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 off keeps 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.py checks that both video verbs default to auto and that still verbs and the row extractor do not. It checks that off gives the engine's original bytes. It checks that video-set hands its value to video-frames and lists the warning. It checks that a white key, a subject with no interior, and brightness alpha give the same bytes as off with 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 of off'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 than VIDEO_STEP in one frame in premultiplied colour or coverage, plus one for uint8 rounding. It arrives by the last frame. Clip totals count blending_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 off while 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-frames prints the warning line on stderr.

    tests/video/test_gait_guard_anchor_wide.py has its stand-in for run_frames take decontam and checks that the set's auto reaches 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 with video-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 filmed before — regenerate the clip where 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 most STEP_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 records step_gate on every walk or run loop (drawings, hold, mean_step, largest_ratio, largest_from, largest_into, wrap_ratio, max, jitter, lifted, kept; skipped for fewer than three drawings). The bound is the larger of 2.5 and --seam-max, so any --seam-max past 2.5 lifts it; a scan or forced delivery with --seam-max 1000 keeps a loop whose largest step is over 2.5 with warning video-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 gate and step_gate.kept.

  • Behavior change: Fixed cuts fail when foot crossings count an odd number of steps. Manual walk or run cuts using --cycle fixed now read the clip's foot crossings and evaluate the cut, matching --anchor motion-auto. The report records cycle.step_count with chosen_by: caller. A cut counted an odd number of steps fails with video-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-auto makes for a pass hidden among feet held together (the clip a cut on the same picture) applies identically through shared local_cycle.same_picture_count. The strip is unchanged, and there is no steps field. Any --seam-max past 2.5 lifts this refusal; a scan or forced delivery with --seam-max 1000 keeps an odd step cut with warning video-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 gate and records cycle.step_count.lifted.

  • New: Refused jump repair drawings are listed in jump_repair.unfixed and 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 in jump_repair.unfixed alongside refused (the faults). Every unfixed drawing prints warning line video-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 (default warn) controls handling: refuse fails such a loop with an error line starting video-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-auto cut 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 example video-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 records seam_refusal in the report (reading: wrap, steps or count). For wrap, it records ratio, max, reason (own-beat or null), and overlap_wrap. For steps, it records ratio, max, into, reason (repair-refused, unfixed or null), plus frames and refused where a reason was found. For count, it records cut, verdict, k, why, and two_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, recording step_gate and seam_refusal, kept by --seam-max 1000 with 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 stay unfixed with faults, cite the refused frame in step gate lines, and fail under --unfixed refuse; CLI tests confirm --unfixed defaults to warn and 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 and seam_refusal; a sideways wrap shift keeps its line word for word with seam_refusal.reason null. 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 in step_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. In tests/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.lock inside 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 bare OSError (EACCES or EINVAL) 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 is tests/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_overlap before 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-manifest and shadow. Inputs include paths given to read and files found inside them (such as frames in --frames-dir), followed via runio.follow_path. Outputs include each file written, folder replaced or emptied, and report, but not folders only added to (which is why --out-dir for video-loop and video-stop is 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 as out/cycle.source/../keyed) are permitted. In logo, the folder's own mood.png and lettering.png remain permitted for --mood and --lettering while any other output file is refused, and correction-loop permits an --out-dir inside 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-loop compared only --out-dir itself with the run dir, so with a link attempt-1 in its --out-dir leading 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-loop now takes an earlier loop's candidate away before the provider makes the next one there. video-sway-inspect now refuses an --out-dir that 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-manifest and shadow now call runio.refuse_overlap so reports or outputs spelt in capitals on volumes that ignore case are refused instead of overwriting inputs, while background-tile, inspect-motion, scene-inspect, scene-render, game-pack, ui-kit and video-sway-inspect verify their single output with runio.same_folder and runio.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_stage and named .<name>.<pid>-<random><suffix>. These include the frames video-loop scales 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 for video-loop, video-stop, video-cycle-align, video-sway and video-loop-repair (.<name>.webp.<pid>-<random>.frames), the working folder video-frames keys into (.keyed.<pid>-<random>.work), and the working folder of logo (.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-atlas never touches its inputs, refusing before making anything and with or without --force any 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, _base image, _refs PNG, 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 as run/../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.lock itself (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 on repair.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_cells through loop.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_read records read (cells or drawings), drawings, and hold. When --anchor body ramps cells and triggers a re-read, seam_after_anchor records those same three fields for the cells that play, and its largest_step_into names the first frame of a drawing. Strip sidecar strip.json does 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 body sliding 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, see docs/loop-review.md section "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 pop is 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 is video-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 to jolt.warnings. Loops whose top band cannot be read pass with verdict unreadable and retain their warning line. The flag --seam-max does not lift this gate, because seam pop measures top band placement rather than seam ratio distance.
  • New: --seam-pop-max flag. video-loop --seam-pop-max BOUND|off sets the seam pop bound. It defaults to 10 (repair.SEAM_POP_REFERENCE) and accepts any number over 0, or off to turn the gate off.
  • Behavior change: --anchor motion-auto evaluates candidates for seam pop before cutting. Before a cut is taken, candidate cuts are evaluated using loop.corrected_cut and repair.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_gate record and step count fields. Walk and run reports and CLI summaries add seam_pop_gate containing verdict (passed, refused, unreadable, off, or not-applicable), max, pop, and why. Failed reports include this record as well. Motion-auto searches record cycle.seam_pop_gate with max, tried, applied, and why. In addition, step_count.seam_gate.tried rows and step_count.search gain pop, pop_gate, and pop_skipped.
  • Tests: synthetic and unit coverage. Synthetic tests in tests/video/test_seam_pop_gate.py verify 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 off keeps the 11 px loop with identical files, --seam-max 1000 alone does not keep it, unreadable tops pass as unreadable, pinned clips report not-applicable, and --anchor motion-auto switches from a cut with pop 6.0 (5.0 on twos) to a passing cut with pop 0.0 under bound 3. Unit tests cover repair.seam_pop_gate, local_cycle._pop_gate, detect, and by_steps. In tests/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".
  • prepare drops the retired keys from --request and --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. --apply removes them from the file; a second apply has nothing to move. The changed bytes move run_revision, and the command names the curation rows it will drop before writing. The command also retains its existing fit.pixel_perfect to fit.pixel_unfake migration. runio.migrate_request_file now 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.py to check the one-time stderr note and unchanged old request bytes, migration dry runs and repeated applies, preservation on unrelated edits, and named drops in prepare. Removed tests/compose/test_layer_compose.py, tests/compose/test_layer_contract.py and tests/packaging/test_layer_cli_entrypoint.py with 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-max after blending also gets a warning: line. New flag (default auto, and video-set takes the default): video-loop --wrap-blend auto|off New report key wrap_blend on 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.py on 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-loop bridges 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.py covers 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 in jump_repair and a warning: line, a wrap that reads as a step saying nothing, --repair on refusing 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 on run without RIFE, in an output folder where an earlier cut passed, refused on a wrap needing the bridge and leaving none of that cut's cycle/, strip, strip metadata, GIF or WebP, and no cycle.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-frames edge 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_policy is now border, was refuse) 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 gains edge_border (frame, sides, outer_px, min_fraction, rim_reach, rim_under_px); each contact row gains rim, and under the default border (pixels taken) and off (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-frames run left its keyed frames in keyed/ 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 refused video-loop run 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. Now video-frames keys into a hidden working folder and hands over keyed/ only when the run passes. A refused run (the edge check, or a frame keyed to 0 % transparency) leaves its frames as keyed.refused/ and no keyed/, not even an earlier run's. A pass removes keyed.refused/. The report is written either way, with status (passed or refused); a refused report adds error, refused_dir and keyed_dir: null. Keyed frames that pass are the same bytes as before. Every video-loop refusal that writes status: 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) removes cycle/, <name>.strip.png, <name>.strip.json, <name>.gif, <name>.webp, cycle.source/ and follow.source.png from the output folder. A cut it had already written is kept as cycle.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_contact counts the rim; a refused video-frames run leaves keyed.refused/, no keyed/ and a refused report; a pass after a refusal leaves keyed/ 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; a video-loop cut refused after it was written hands nothing over and keeps cycle.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.py and tests/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 from keyed.refused/), tests/video/test_edge_speck_lead_in.py (the default policy is named border, and the refused frames are read from keyed.refused/), tests/frames/test_chroma_key_relative.py (the edge-contact split states the rim count classify_edge_contact now 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 green the whole background stayed opaque, and video-canvas refused --key green on such a still; but with --key auto the old rule did not take the green route at all: cutout and video-frames routed the frame to the white (position-based) matte, and video-canvas treated the still as a non-key base and did not normalize it. video-frames --spill auto did not always choose full: when the reference still had the same leaning green, auto read the surviving background as key material and chose small; when it chose full (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 rule extract.is_border_key_candidate held 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 new threshold argument of detect_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 window video-frames --spill auto keys, 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 the video-frames edge-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 auto and video-canvas --key classify 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 rule is_key_family is 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 and cutout --key green key the leaning greens out with the subject byte-identical; cutout --key auto routes a leaning green to extract: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-canvas repaints a leaning-green still to the exact key and accepts --key green on it), and tests/video/test_video_spill.py (on a leaning green, --spill auto reads the reference as full with no key material, and the frame keys with no opaque background pixel and no edge contact, the subject byte-identical, with --decontam off and palette).
  • New: The Breathe layer adds mode: "smooth" for large illustrations and video frames. Set per row: states.<state>.breathe = {"mode": "smooth", "depth": ..., "breaths": ...}. pixel stays 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 at chest_y of the body below the neck. The weight is chest_rx x torso half width wide, and chest_ry x the body below the neck tall. The chest centre rises by depth x basis rows at the in-breath and puffs out by depth_x from P (not from the ellipse centre). Two shoulder weights, on either side just below the neck, rise by shoulder x the chest's rise. They rise shoulder_lag of 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_x moves 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) and chest_dir (degrees from straight up, negative = up-left). chest_bias moves 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_y moves 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_bias and chest_bias_y together at most 0.9 of the radii (refused otherwise). chest_flat is 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. breaths is a whole number. breath_peaks is 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: lag on 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_bias and chest_bias_y together 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, mismatched breaths, and shape keys or breath_peaks on 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: depth 0.0085 (about 0.5 % of the frame height on a bust illustration), depth_x 0.028, chest_y 0.31, chest_rx 0.83, chest_ry 0.28, shoulder 0.5, shoulder_lag 0.08, and chest_tilt, chest_bias, chest_bias_y, chest_dir, chest_x, and chest_flat 0. 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 and breathe.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-follow with video-sway. video-sway and video-sway-inspect replace video-follow and video-follow-inspect. Their Python modules are sprite_gen.video.sway, sway_loop, sway_offsets, and sprite_gen.video.sway_inspect. video-follow and video-follow-inspect remain as aliases with the same results and their own name in messages. A loop's record is read under sway or follow. Behaviour is unchanged.
  • New: Anatomy gains origin and neck_span values. It does not put these two values in the sidecar or the manifest. origin records where the measured frame's figure sits. neck_span records 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-tile on 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 every main() and by sprite-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 body no 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_px is 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 gains seam_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, none and feet do 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 none gives the same cut; a wrap the ramp does not close is refused with the same error line as --anchor none gives 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 off turns 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 stays on) nothing is read or made for the wrap: the report's wrap_overlap says skipped: "turned off (--overlap-wrap off)" with no tries and calls 0, a warning: 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 off still 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-auto corrects 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 explicit on; video-loop's argv carries --overlap-wrap off with no RIFE installed, on is 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 (and on) 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's beat); otherwise it is refused for the body off its beat and 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, through video-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-auto keeps 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 with steps: 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 count uncertain (same-picture, step_count.search.same_picture), no steps written. 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, no steps; 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; on by_steps itself, 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-auto closes 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 (and on), where such a cut's wrap reads over --seam-max on 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 as torn where 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 carries wrap_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 on refuses). 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 off refused as before; without RIFE cut as filmed with a warning, and with --repair on refused 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 (marked real_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.read makes 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.torn reads 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-auto cuts 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; refuted one or three steps; anything else uncertain, 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 under repair.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 records cycle.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 records cycle.steps {count: 2, by: crossings} and strip.json steps: 2, so video-cycle-align reads 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. --steps is still the word on the search's cut. repair.clip_flow_states and repair.ring_scores read the flow of every cut of a clip on one path; flow_scores and 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 saying steps: 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; detect refuses what the crossings refute and orders a refusal by the count), the step screen's tests in tests/video/test_one_step_cut.py and the pixel search's in tests/video/test_auto_motion.py, tests/video/test_loop_prop_seam.py and tests/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), and tests/video/test_explicit_window.py refuses a --max-len 25 that holds one step of the 42-frame walker.

  • New: video-loop --repair auto (and on) 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.surges reads 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 as video-loop-compare reads back as the repair's): repair.ease_times gives 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.discover on 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_repair carries surge, surge_after, ease_skipped, ease_calls and the round why: ease (its rest: per window the rush is not read in, step_max_before, step_max_after and faster), replaced its frames, and the summary eased; without RIFE the rush is cut as filmed with a warning line, and --repair on refuses (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-loop playing the frames made in a loop as long, a rush without RIFE cut as filmed with a warning line, --repair on without RIFE refused), and tests/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 outline read the made frame's edge against one dark line (a solid pixel under 70/255 within 2 px, outline_loss over 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 auto refused 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 fault outline now 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 reads outline_loss 57 % and outline_shift 0 (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); elsewhere outline_shift is null and 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 reads outline_loss 7.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's smear rows carry outline_shift, and the alignment's warning line names it where it was read; video-loop-compare and video-loop-repair keep their versioned measures, rife.smear alone, 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). -x runs the pair as its eight flips and transposes and -z both 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 stays rife-v4.6. On the synthetic pairs of tests/video/test_rife.py, -x -z is 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_TTA names 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's interpolator) carries tta. 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 -z and never -g; SPRITE_GEN_RIFE_TTA names 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 hold held.measure's. flow_targets takes 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 is unfixed. 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 (and on) 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_targets now 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_repair reads reading: flow, limit, span, hold, drawings, refused, unfixed, left, off_max_before / off_max_after (in place of score_max_before / score_max_after, also in the summary and in video-set's item record), and per round why: flow with its group and made (per drawing: frames, t, original, proposal, faults, look); unmade names the group's frames, neighbours and off. repair.JUMP_RATIO is gone; repair.jump_scores stays, the size reading video-loop-compare's jump guard reads with the recorded facing (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) and tests/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-loop playing 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 of tests/video/test_ghost_screen.py, tests/video/test_crossfade.py and the real-RIFE case of tests/video/test_rife.py read 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 named unfixed; a loop of three drawings left alone; a loop with no body refused).

  • New: video-cycle-align --between-cache DIR caches frames made between source frames so later alignments take kept frames instead of making them again. Previously, running alignment a second time to specify --foot or 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 in DIR as 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 (or between_cache=path in Python) and removes DIR when the alignment is done. The summary and report record dir, hits, misses, unreadable, and not_kept under between_cache, which is null without the flag (loop repair).

  • Tests: tests/video/test_between_cache.py (two passes under --between rife and --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 one rife.Rife object, 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 -z and under -z alone, and taken again without; a RIFE whose model directory is gone fails as a RIFE that fails; under one rife.Rife: another host name or OS build, NumPy or Pillow version, or engine code loaded anew make the frame again, while rife.py written 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 an identity() method are refused; the summary and report record the cache counts; a real_rife run 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-set and video-set's mid-step redraw run on codex when no --provider is named. When codex was not signed in, they used to switch to grok without asking (said on stderr, kept in the report) — and with no Grok login that meant XAI_API_KEY, billed per call. Now codex that cannot run — not signed in (codex login status), or its usage used up (codex exec ends 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; grok or openai runs that provider, said on stderr and kept in the report as provider_fallback (now with cause and chosen_by), openai with its per-call charge line as always. The choice is SPRITE_GEN_CODEX_UNAVAILABLE, else sprite-gen defaults save --codex-unavailable ask|grok|openai, else ask; the guided workflow asks it once and saves it. A usage limit is known only after codex exec ran, so the call runs again on the chosen provider. A named --provider runs as named: a named codex whose usage is used up still fails with codex's own words, exit 1. gen-set and video-set whose child asked stop with the same question and exit 75 (naming --provider, or --still-provider), their reports and tables keep it under asked, and gen-set --provider now takes openai. openai runs 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.1 and rust-v0.153.4): codex exec --json carries only the message of codex's usage-limit errors (UsageLimitReached, QuotaExceeded, UsageNotIncluded, which codex classes as UsageLimitExceeded), so codex_provider.usage_limit matches 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.json keeps, beside the sprite and image profiles, the general settings 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-unavailable needs no --kind.

  • Tests — tests/gen/test_codex_unavailable.py (no codex on PATH and nothing chosen: a real gen exits 75 with one question line and no image or report; each of codex's usage-limit sentences, synthesized as codex exec --json prints them, asks the same; a codex failure that is not its usage limit fails and is not switched; saved grok runs grok and the report and stderr say whose choice; saved openai runs the API on a fake transport with one charge line; a usage limit with saved grok runs grok after codex; the environment before the saved choice, an unknown value refused; settings read only when codex cannot run; logo resolves the same way; a named provider runs as named whatever was chosen; a real gen-set whose rows asked exits 75 with one question naming --provider, its report and table keeping it; a video-set whose 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; the defaults CLI; 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_SECONDS bounded 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 count SPRITE_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 realtime pixel-draw call 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's retry-after counted 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 hands retry its limit; the Grok facing check and a Message Batch read whose wait woke past their limit send nothing), tests/gen/test_openai_provider.py and tests/gen/test_grok_provider.py (with 20 s, the second send waits only the 12 s left and the second 429 ends the call sent 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.py is 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 assets list (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, assets may now be empty or absent when sound is declared (see docs/game-pack.md#sound-only-packs). A sound-only request writes exactly game-pack.json, audio-<id>.ogg, audio-<id>.m4a and sprite-gen-audio-v2.mjs without atlas pages; its manifest sets textures to [] and animations to {} (version 2 also keeps empty images, tiles and ui), 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 with assets empty or absent write only the manifest, sound files and helper; manifest matches image packs except for empty textures and animations; 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-stop cuts 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 within SAME_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 by video-stop with exit code 1 and status: "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 within SAME_POSE (0.35 steps) of a pose the clip had left by TURN_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 than RUN_UP_MAX_CYCLES (1.5 cycles) — source_cut.length frames, 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-max bounds 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 2 plays every other frame (still kept last), --max-frames N spaces 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_cell then placed it with its align_x anchor (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_cell takes it for a frame alone, the row takes it over every pose, and qa/inspect fits a row the same way instead of pose by pose. With bbox-center nothing 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 — and video-set --motion gives 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=MODE or ITEM=MODE and video-prompt --play MODE take the mode as a value of the request, and video-set --motion STATE=TEXT or ITEM=TEXT the 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 new video-loop --cycle once-return (every frame, the last too, gated by the pin), its strip.json saying loop: false, hold_last: false, returns: true with 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 once is 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 --play every 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.json records each item's play (and motion); video-prompt --json records play. 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 as cast still 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-set modes 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 in tests/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_on and squeezed pip_off) with an 18 px and a 60 px dot, refused by split_ui_kit and the CLI; the control sheet cut as pip_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_on above, pip_off below), 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 no layout_fit.

  • Fix: the test suite runs on Windows. pyproject.toml named pytest-timeout's signal method, and Windows has no SIGALRM, so pytest stopped with an internal error before its first test unless -o timeout_method=thread was given. The method is now left to pytest-timeout, which takes signal where SIGALRM exists (Linux, macOS: unchanged) and thread on Windows. Test: tests/packaging/test_project_metadata.py. tests/video/test_one_step_cut.py skips where img2webp is missing, as the other loop tests do, instead of failing all twelve of its tests.

  • Fix: sprite-gen prepare --request keeps the request's style. The subcommand declared its own copy of prepare's options, with --style defaulting to the default style sentence and --cell-size to 256, so a flag nobody gave counted as given: the request's style was replaced by the default sentence under a note that --style, --cell-size were given both ways (scripts/prepare_sprite_run.py and prepare.run were right). The subcommand now takes prepare's own declaration (prepare.add_arguments), which also gives it --directions and --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 (through sprite-gen prepare: a request alone keeps its style and cell with no note, a given --style wins and says so, the subcommand takes every option prepare declares).

  • New verb: logo makes 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 as logo.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) and logo.report.json (status, every step's prompt and numbers, the alpha coverage, the key hue left, both text checks, and every call with its route: subscription or per-call). --mood starts from a picture you have; --lettering cuts a lettering image again with nothing generated. --chroma-key auto scores 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; logo asks 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, --lettering in 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) and tests/gen/test_vision_read.py (the question and detail carried on codex, grok and openai; the facing body unchanged).

  • Behavior change: pixel-draw runs on your Claude subscription first, and on ANTHROPIC_API_KEY only without one — the order codex and grok keep. When claude auth status says Claude Code is signed in with a subscription (claude.ai or oauth_token), every call — the drawings, the row repairs, the pick — goes through the unmodified claude binary 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.json says auth_source: claude-login, each call's mode is subscription and its cost_usd 0, its usage kept. The child never sees ANTHROPIC_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. --batch is 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 its result, which holds only the last part; one it cannot finish is read as stop_reason: max_tokens, so the one redraw one effort lower happens on either route. One call may take up to SPRITE_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's auth_source is what the calls ran on by their records, mixed (with auth_sources) for a run resumed under the other credential. A --resume that 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 and workflow: 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 before codex exec runs, its report records extra.auth_source: codex-api-key (codex-login on ChatGPT), and workflow asks to confirm the API credit. A codex that is not signed in is refused with the reason before it runs. gen-set and video-set keep 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), each gen-set row records auth_source, and each video-set clip result too. sound prints the same billing line as every other metered route (it printed its own) and its receipt records auth_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), so gen --provider grok now gives the same grok models refresh as video. workflow probes 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's XAI_API_KEY route in the help and SKILL.md, the sound billing line, SPRITE_GEN_GEN_TIMEOUT_SECONDS and SPRITE_GEN_CLAUDE_READ_TIMEOUT_SECONDS, and gen-set --provider (codex or grok).

  • 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 in tests/gen/test_pixel_draw.py, and gen.base.env_api_key in tests/gen/test_gen.py; tests/gen/test_codex_login.py (ChatGPT, an API key and not signed in; the default resolution, generate and workflow read the same login; an API-key login announces the charge and records it), base.run_logged in tests/gen/test_gen.py, the ElevenLabs billing line and key refusals in tests/audio/test_sound.py.

  • New: background-tile --axis xy makes 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, status and reasons); the top-level status is needs-review when 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-draw draws 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's recovered (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, --resume reads every call back, and stderr says before the first request how many calls and tokens the set may take. A --spec frame 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 carry parts. An effect stays 2–8 frames in one call (pixel-draw).

  • New: pixel-draw --style TEXT draws 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 --style both prompts are byte for byte what they were. Same name and meaning as prepare --style; spec key style; request.style in 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 of pixel_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 reading video-loop --body-height already makes of a cut (video.gait_fallback.size_change on 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.G6 then has rule: "motion", size_change, resized, posed and holds. Same name and meaning as video-prompt --motion; spec key motion; also on --grid (pixel-draw).

  • Behavior change: a pixel-draw --walk-cycle is 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 N times anim.gif (and an effect's delay_ms), 150 ms by default as before, at least 10; spec key duration_ms, also on --grid. Same name and meaning as compose-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; --style in the drawing and the pick of every kind with the structure kept; the default drawing and pick prompts frozen byte for byte from before; --motion refused 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 --grid with --motion, and failing without it; --duration-ms in anim.gif and 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) and tests/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-draw answer 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 and END with 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's recovered as block_many with 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 in tests/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 by ui-kit (on by default) and slice-sheet --alpha-floor N (off by default; writes <prefix>alpha-cleanup.json). slice-sheet --chroma-key none cuts a sheet that is already transparent on its own alpha (sheet-slicing).

  • New verb: ui-kit splits a game UI kit sheet into nine-slice elements. gen --layout-guide ui-kit attaches 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 and ui-kit.json (or --report PATH, which must end in .json; each element's file is its PNG's path from the report's directory, so a report written outside --out-dir still finds its elements): its rectangle, its stretch (xy, x for the bars, none for 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-guide alone is still the one-slot figure guide.

  • New: game-pack request and manifest version 2 with images, tiles and ui. 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.kit reads a ui-kit report into nine-slice entries (frame, size, stretch, insets, padding) and ui.icons adds 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 sheet keeps the sizes a sheet was drawn at, and --fit contain keeps 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 sheet takes 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 contain lowers the factor until the whole cut fits the canvas, with the main subject still centred on its base; with --scale sheet the 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 one display height keeps their sizes too (sheet-slicing).

  • New: slice-sheet writes <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, the anchor (the centre of the main subject's base, ready for a game pack's images[].anchor) and clipped_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:3 draws the square layout's seven frames at the same places and, in a band below them, hp_bar_fill and xp_bar_fill (x), slot and badge (xy), pip_on, pip_off, joystick_base and joystick_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 report needs-review). ui-kit picks 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 get 0. Each fill's report entry has inside: its bar frame, that frame's content rectangle and the factor that makes the fill as tall as it, and the report is needs-review when 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, with inside in 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 fails ui-kit with <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 no elements entry, the report names it under missing (every 2:3 report has missing, [] when nothing is missing), and the command's line ends with ; missing, left out of the kit: …. status stays about the elements that are there. game-pack is unchanged: it packs the elements a report has, so a missing element has no ui.nine_slice entry 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 no missing (ui-kit).

  • Behavior change: ui-kit writes a kit whole into a new directory and refuses one that holds anything. --out-dir must 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-dir and 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-dir the second is refused. A --report outside --out-dir must 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-dir holds 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-kit refused the sheet with <element>: its box holds no element although every element was drawn. When a box is left empty, ui-kit now 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 as layout_fit, and each box is 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 gen now 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-dir and --out-dir absent 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-dir and --out-dir absent, 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-dir or 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 no missing), 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_transparent and a --layout-guide ui-kit run refuse a checkerboard before the matte runs and publish nothing), and the drawn-checkerboard ref run in tests/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-dir names 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-kit cases in tests/gen/test_layout_guide.py (square and 2:3, any other ratio refused), the 2:3 sheet in tests/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 in tests/compose/test_game_pack_v2.py, and tests/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 contain while the default still cuts it and says so; one factor every cut fits; sliced cells packed as game-pack images keep 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, record normalization.pcm_lufs and pcm_true_peak_dbtp required 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 in sprite-gen sound while reusing cached provider audio.

  • Bump audio processing recipe to version 3, require ffprobe on PATH, export M4A with -movie_timescale 48000, and validate AAC stream duration with ffprobe.

  • 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 createAudioSource using an internally cached L+1 guard frame buffer while preserving prepareAudioBuffer frame 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 playback coordinates, removed legacy loop seconds and taper metadata, and bundled standalone runtime helper sprite-gen-audio-v2.mjs for Web Audio loop preparation.

  • Added sprite-gen sound CLI 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 once nonloop motion support with automatic selection for death, fall, land, cast, hurt_hold, and transform, 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 for death/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) and video-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 --force regenerates.

  • 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 via source_cut.samples) and once preview handling, with nonloop cycles insisting on existing --anchor none and --fit state while 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-json and pixel-draw --spec alike. pixel-draw refused the pair; prepare let the flag win for most keys in silence, and let the request win for three: --style, --cell-size and --safe-margin were 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's subject among 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, and pixel-draw's Anthropic transport sent 429 and every 5xx again after 10 s and 30 s. Now each asks gen.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's retry-after when 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 saying sent 3 times, no provider fallback in place of no retry or provider fallback. A request with no answer it could read is still never sent again. video-set runs each clip once: its own rerun of a clip whose log said HTTP 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 on 529.

  • Fix: a refusal whose body broke on the way is no answer on every transport. xai.http_json already said so; openai-gen let the broken read escape as a traceback, and pixel-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 / --strap and the curation view's pixel edits took a sign or an underscore as a digit (#-1-1-1 read 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-key also takes RRGGBB without the #, as the other flags did. Written colours are unchanged: upper case, and lower case in recolor's report and palette draft.

  • Fix: a Python call of gen.run, the video verbs' run, pixel-draw's run or inspect-motion's run without 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 with None. 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.G8 is unchanged.

  • New: anthropic_api.billed_tokens(usage) — a Claude call's tokens by the price each is billed at, the split cost_usd priced inline, now one public function cost_usd asks: 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 as PRICE_PER_MTOK prices 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_usd is 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), --size 8–48 (32), --kind sprite|icon|tile, --frames (up to four, drawn in one call; --walk-cycle for 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 its FRAME line 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 from prepare rather 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 row prepare'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 verdict gen reads a generated raw by (chroma.alpha_verdict, out of classify_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 is background-tile's join measure (inspect_tile), asked of a tile along x and along y, and warns with its reasons where it says needs-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_fit in frames/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, info in 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 holds grid.txt (the truth: edit it and re-render with --grid), palette.json, frame-<name>.png written by an encoder whose bytes depend on the pixels alone, preview-x<s>.png, tiled-3x3.png for a tile, anim.gif for several frames, every call under calls/ and report.json with 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 --resume collects it — and reads every answered call back — instead of buying it twice. It runs on ANTHROPIC_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-extend and video-edit ended the run on any non-2xx poll, after xAI had accepted the request and may bill it, and the line read (HTTP 429) — what video-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 answered 429, 500, 502, 503 or 504 is now asked again on the same request_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 a 400 or 404 poll still ends the run with its status (a 401 or 403 poll 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 names request_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 --report the run leaves a sprite-gen-video-unfinished report there (verb, auth_source, model, request_id, out, polls, polls_refused, last_poll, elapsed_seconds) and prints nothing on stdout; Python callers catch GenerationUnfinished, a SystemExit. The success report gains polls_refused, how many of its polls xAI answered 429 or 5xx (docs/video.md, An unfinished generation).

  • tests/gen/test_video.py scripts 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 with polls_refused 2; 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 no HTTP 429 on 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-resume asks again for a generation a run left unfinished — by its request_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] polls GET /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 the XAI_API_KEY route prints no charge notice. Its report is a sprite-gen-video-report with mode: "resume", the same request_id, inputs: {} and duration_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 answered 401 ended 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 answered 401 or 403 — 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 check XAI_API_KEY) before the request to ask for. A POST that gets no answer ends as before: no request_id came back. xai.http_json raises xai.TransportError for a request that got no answer, still a SystemExit with the same line, the socket's words in reason.

  • 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 gain polls_unanswered, how many of polls got no answer, each asked again; the unfinished report's last_poll gains error, what the socket said, when its last poll got none (http then null).

  • tests/gen/test_video.py asks again by id and loses polls: xai.http_json raises xai.TransportError with 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 with polls_unanswered 2; lost until a 30 s timeout waits 8 and 16 and ends unfinished with last_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-resume polls 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 under gen.

  • 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 its Content-Length (http.client.IncompleteRead), a status line that is not one (BadStatusLine), a refusal's body cut the same way — escaped video, video-extend, video-edit and video-resume as a raw exception, with no request_id, no unfinished report and no resume command, so a caller could only submit the clip again and buy it twice; a 200 poll whose body is not JSON ended the run on xai: 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 same request_id with 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 in polls_unanswered, and unfinished at the poll timeout with that reason in last_poll.error. A POST so answered still ends at once and is never sent again — no request_id could 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_json raises xai.TransportError for every answer it cannot read whole, each with the line it always had; reason is the http.client exception's repr for a broken answer, response was not valid JSON for the other.

  • tests/gen/test_video.py answers over a real socket from a local server: xai.http_json raises xai.TransportError for 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-JSON 200 (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 with polls_unanswered 4; a resumed poll cut short is asked again and published; cut until a 30 s timeout, the CLI leaves the unfinished report with last_poll.error the IncompleteRead and 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 ended video, video-extend, video-edit and video-resume with no request_id, no unfinished report and no resume command: a refused connection on video: cannot download the clip: …, a body cut short of its Content-Length (http.client.IncompleteRead) or a read that timed out as a raw exception, a refused download on video: 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 with 429, 500, 502, 503 or 504, 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 (a 401 or 403 still 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-resume polls afresh, so it downloads from the URL the new poll names. video.http_download raises xai.TransportError (its line still video: cannot download the clip: <reason>) for a download that got no answer and video.DownloadRefused, a SystemExit carrying status, for a refused one; xai.NO_ANSWER and xai.no_answer are 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: false on the done poll, read before any download; anything else at the clip's URL — an expired link's page, a proxy's error page served 200 — is a fault in delivering a clip that is made, and the request_id is the only way back to it. video-resume costs 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_mp4 is 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 gains downloads and last_download — http the status the clip's host refused it with, else null; error what the transport said, or not an mp4 (no ftyp box) with the bytes that came — and its last_poll is the done poll; an unfinished report of a poll is unchanged.

  • tests/gen/test_video.py downloads 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 with downloads 3, last_download.error the transport's words and an empty stdout; a cut download, then a 503, then the whole clip publishes with downloads 3; a 503 three times and a 404 once end unfinished with last_download.http, no (HTTP n); 34 whole bytes of HTML end unfinished at once with last_download.bytes; and a run left unfinished by its downloads is published by video-resume on 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_id back 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: no request_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 the request_id then: … 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; …, polls 0). xai.http_json and video.http_download take deadline=, a time.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 a url that 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 no http(s):// URL — none, empty, null, not a string, no video object — 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's last_poll the done poll and no downloads; video-resume polls it afresh. respect_moderation: false is still the content-policy refusal it was.

  • tests/gen/test_video.py runs 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.error timed out, elapsed_seconds under 2.5); a poll that stalls or trickles is cut the same way. A 503 download 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 no video object is unfinished on its id for video and video-resume. xai.http_json reads 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 empty video expects the unfinished line.

  • Output change: an openai image 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_limit now holds every x-ratelimit-* header the response carried, names lower-cased and values as sent, and {} when none came (docs/gen.md). openai_provider.http_image returns the response headers as a third value.

  • tests/gen/test_openai_provider.py answers with headers: the report holds exactly the x-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-only runs every test of the real RIFE, not one file. It ran tests/video/test_rife.py alone, while --rife-unmeasured skips every test that needs the real rife-ncnn-vulkan — so a real-RIFE test in another file (2.43.0's in tests/video/test_crossfade.py and tests/video/test_ghost_screen.py) was measured by neither run. Such a test now carries one mark, real_rife (registered in pyproject.toml): tests/conftest.py skips the marked tests where rife.locate() finds no RIFE, and scripts/linux_lane.sh --rife-only runs pytest -m real_rife over the whole suite, none skipped. A new real-RIFE test is run by --rife-only once it is marked. docs/release.md says what each run measures.
  • The lane's RIFE-less run fails a skip that --rife-only will not run. --rife-unmeasured runs the suite as pytest --rife-unmeasured, where tests/conftest.py reads 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 marked real_rife fails by name, unless NOT_RIFE_SKIPS in the same file names it as skipping for an input the lane does not give (the SPRITE_GEN_CHROMA_REAL_STILLS stills). Such a skip would be measured by neither run.
  • tests/release/test_lane_rife_collection.py collects the suite twice, once with a stand-in RIFE where rife.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 marked real_rife fails 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 through pytest --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.crossfade docstring and docs/loop-repair.md section 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 — retake reason filmed-ghost. Since 2.43.0 video-cycle-align delivers 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's retake stayed null, so a pipeline that films a direction again on retake delivered the ghost. Such a loop is now named: its row's retake (and the report's, and video-set's) reads reason: "filmed-ghost" with ghost — the cells kept, their frames of cycle.source/ (sources), the highest reading (ghost_max) and the screen's limit — and limits.ghost_kept_min (one cell, align.RETAKE_GHOST_KEPT_MIN), with a line "film this direction again (filmed-ghost) — …". retake stays one object: reason is the first that applies (held-drawings, then filmed-ghost), the new reasons lists every one (["held-drawings"] for a held loop as before), and the held numbers stand only where that reason applies. Each ghost_at cell that keeps its ghost says why (kept: no-clean-frame, under any --between, or between-rife where --between rife kept 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.md section 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 rife kept with no clean frame beside it is named "film this direction again", no longer told to align with auto for 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 meets video-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 a warning: 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_screen names 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 say why: "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 records neighbours, outcome (accepted, given-way, kept) and no_proposal where no frame was made. A cell given way is in jump_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's seam_ratio_after_anchor reads the wrap the same way. The report and its summary carry ghost_given_way (frame, ghost, taken) and ghost_kept (frame, ghost), and the strip metadata each where it is not empty — cycle/ is the alignment's cycle.source/, whose screen no longer sees a ghost given way, so an alignment carries the record over. A warning: 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 auto still 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_jumps with no interpolator no longer raises on a jump); --repair on refuses a ghost between two clean frames as it refuses a jump. --repair off and 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-loop checked 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-loop and video-follow now check for one frame per run of identical cells, as video-cycle-align already 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); its strip_indices still lists every scheduled cell.
  • Output change: source restoration reads the ghost — the ghost guard. A cell video-loop gave 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 — so source-restoration-v4 could propose the cell and accept the ghost back. Now no cell whose source frame the cut's ghost screen names (interpolation_quality.ghost_screen on 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 new axes.ghost reads each cell's own rife.ghost on final pixels (baseline, candidate, reference, threshold 0.003, filmed — the screen), any rise of the excess over the limit regressed with ghost: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, policy key-protected-source-copy-one-step-cap-jump-ghost-guard-v1. A restored cell's pixels are made as in v4. Evidence and receipts of source-restoration-v4 (2.40.0 – 2.43.0) are refused, never 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. The origin itself is still a valid first request. Proposal IDs change with the versions. video-loop-compare without the origin and the source (same-sample-defects-v1) is unchanged.
  • tests/video/test_ghost_given_way.py draws the walk of tests/video/test_cycle_align.py with 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 off and --repair on without 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 none and --anchor body; under --anchor body, the walk's default, the strip's seam_ratio_after_anchor reading a ghost given way at the cut's first frame, its last or both as --repair off reads it (read on cycle/ before: 0.0 at the last); the side walker of tests/video/test_one_step_cut.py cut with the application's walk flags (--anchor motion-auto --size-hold auto --body-height 160), through a stand-in and through the real RIFE (marked real_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.py adds 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.py reproduces on the synthetic legs of tests/video/test_ghost_screen.py a 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, marked real_rife), and a held loop on twos that keeps ghosts too (both reasons, held-drawings first); under --between rife only 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-align takes 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 auto judged 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_screen per loop row and in cycle_align: limit, thick_px, the loop's own level, reads, and each filmed ghosts frame of cycle.source/); a loop whose median frame is over the limit is drawn part-covered (a glow, a translucent cape) and is not judged. Under auto and nearest a 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 (fault ghost), and where that nearer frame is the ghost the other frame beside the time is taken; rife keeps both, named. Each such cell is listed in ghost_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 in smear carry their ghost reading.
  • The same screen in the other loop paths. video-loop records the screen of the cut it delivers for a walk or run (ghost_screen in its report and summary, a warning: line per ghost naming cycle/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' original and proposal carrying ghost. video-loop-compare and video-loop-repair keep their versioned rife.smear measures 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-loop prints a warning: line for its cut (and carries ghost_screen in its summary), and video-cycle-align a line in warnings per 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.smear rows carry crossfade and look, and a kept frame gets a warnings line ("may cross-fade two drawings inside its outline … kept"). It is no fault — auto keeps 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's look, the proposal's crossfade, a video-loop warning: line). video-loop-compare and video-loop-repair keep their versioned measures.
  • tests/video/test_crossfade.py draws 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 by video-loop and in the alignment's warnings. tests/video/test_rife.py pins the real RIFE's whole verdict on the melted crossing (outline and ghost one way, outline the other, no cross-fade either way), where it pinned only the first fault.
  • tests/video/test_ghost_screen.py draws 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 under rife or with no clean frame beside it, screens a loop already that long and leaves a loop drawn part-covered as before; video-loop names 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 as video-cycle-align takes them; a strip turned over to face the other way is a direction like any other) writes <name>.sheet.png and <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, as video-loop reads 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 is video-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 their body_h, against the still's own as video-loop reads 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, with same_length: false and a warning. The record carries order, columns, cell_w, cell_h, baseline_y, anchor, same_length, per row its code, view, frames, delay_ms, strip name, input, strip_sha256, body_h and body_bottom_y, and the centre's png, input, sha256, standing_h, body_h, scale and box. A direction given twice, a front or back view with a side, a --view count other than the loops', a loop directory without one strip and its sidecar, an opaque centre still and a centre beside rows without body_h are 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.py lays 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-align refuses 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, or follow.source.png where a follow-through moved it) to record cycle_align.origin. A loop directory holding cycle/ and its strip.json without that PNG ended in a FileNotFoundError traceback, with no report and cycle.source/ already copied into every loop of the set. It is now refused as a loop cut before cell_height_cap was recorded is: video-cycle-align: <loop dir>: no <name>.strip.png — …, exit 1, every loop of the set file for file as it was (under video-set, that state's alignment fails and its loops stay as cut). It is still not aligned without its origin, which video-follow --read-on carries 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.py takes the strip out of one loop of a synthetic set: the refusal names it, and both loop directories are as they were, with no cycle.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-align turns a loop to start on a foot strike, so its first cell is another, and video-follow given 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-on names the strip they were read on by its file's sha256 (as cut, before any follow-through). This loop's own strip as cut is same: the follow-through is the one without the flag, byte for byte. The cut this loop was aligned from is transported: 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 refused uncertain: 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 refused no-match. Without --read-on nothing of this is read or written and the record holds no new key; with it the record carries read_on (sha256, relation, and for transported its policy and cut_cells). video-follow-inspect takes it too. docs/video-pipeline.md.
  • Output change: video-cycle-align records the cut it aligns from and where every cell is from. cycle_align.cells_from holds, per cell of the rebuilt strip, {"source": i} (frame i of cycle.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 as video-follow reads 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 refuse refuses 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 carries stretch (policy, floor, per region per_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-inspect writes 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, with bend_deg = atan G; the same number as fold_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].seams and the record's seams give, per pair of moving regions that meet, the largest jump of the move's gradient on that curve and its angle (jump, deg, the point at, the cell); a held region has none. regions[i] adds the largest bend and bend_deg. inputs.settings adds read_on and stretch_floor, inputs.policy the names of the ways a reading is carried and a floor kept, both in input_id; and carry_basis says what carries a region (outline-lay) and that whose pixels it holds is unverified. video-follow's own record changes only where a new flag is given, and then also carries carry_basis. docs/video-pipeline.md.
  • tests/video/test_follow_read_on.py and tests/video/test_follow_stretch_floor.py use synthetic strips. A runner turned by video-cycle-align and followed with --read-on is 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 refused uncertain with the loop left as it was; another clip and an unknown or malformed read_on are 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 in video-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 the facing the loop report's jump_repair recorded. A changed cell reads the larger score of the step into it and the step out of it; more than the baseline's is regressed, reason jump:regressed, as on every other axis. No bound is read (JUMP_RATIO included) 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.jump carries 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 (right or left) is shared unknown, 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, policy key-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 of source-restoration-v3 (2.39.0) are refused, never read as v4: a v3 repair report given to video-loop-compare is an input error, and a request whose baseline carries a v3 receipt in its loop report is shared unknown, restoration-receipt-policy-unsupported. The origin itself is still a valid first request. Proposal IDs change with the versions.
  • scripts/dev/source_restoration_demo.py still ends with both requests improved and 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's facing, as video-loop writes 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 is regressed with jump:regressed alone, while the other proposal stays improved; 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 shared unknown, 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 with rife.smear and adopted only without a fault: a smear inside the body (dark_excess over 0.001), a lost outline (outline_loss over 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's jump_repair adds attempts, blocked and, per round, target, the original and proposal measurements, faults and outcome (accepted or rejected). 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 adds source (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 run gait (cut-local silhouette signals, status: "unverified": they do not identify the character's own feet), and under --anchor none or body source_projection (the cleanup recipe, the body ramp and each frame's pixel digest before the jump repair). The strip's meta adds sample_indices, source_rect (null under --anchor feet) and source_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 (after video-follow, if that ran) and its loop report for provenance only, never for a seam score or a pass, and writes a sprite-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 is regressed. improved also 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 are unknown; equal pixels and timing are non_regressing, never improved; the gait stays unverified. Every verdict, unknown included, exits 0; invalid input, disagreeing geometry and I/O failures are errors. An application that replaces a result on its own should take only improved. docs/loop-comparison.md.
  • New source restoration: video-source-manifest, video-frames --source-manifest, video-loop-repair, and video-loop-compare given 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 ends unknown and 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 (or video-frames --source-manifest with --reference) receipts the clip, the canvas, the frames report, the ordered keyed PNGs and the clip's presentation timestamps. video-loop-repair takes 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-dir and 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-compare with the same origin, source and repair evidence measures the five final files again: improved needs 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) is unknown, not a guess; source, origin or evidence files that are missing or changed are an error. Only a final improved is grounds to adopt a candidate. Repair report schema 3, comparison schema 4, metric source-restoration-v3, policy key-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, two video-loop-repair requests, each compared improved by video-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. Its summary.json holds 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.py and tests/video/test_strip_resample.py use synthetic loops. Identical pixels are never improved; an outline restored with the bob kept is improved and its inverse regressed; 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-follow is 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 --board draws two cells. video-follow-inspect takes video-follow's arguments (all but --board), reads the strip as cut and solves it with the same code, and writes into --out-dir follow-inspect.json and 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 lower is 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 as video-follow records 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, and input_id, one sha256 over those — the same before and after video-follow is 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.png has the cells as cut and follow-inspect.moved.png the cells as video-follow would 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 a pixels_sha256 over its pixels beside its file's. The engine does not read what is inside an ellipse and does not guess it: every region is ownership: "unknown" in every cell, from its centre to its rim, and video-follow still moves every cell. The loop directory is only read — not the strip, not its meta, not the follow.source.png that video-follow keeps — and an --out-dir at or under it is refused; what video-follow refuses, the inspection refuses in the same words under its own name. video-follow writes what 2.38.0 writes: strip, GIF, WebP, record, printed summary, messages and --help, byte for byte. Its body is now follow.read_request (the request, read and checked), follow.solve (an Answer: the motion, each region's gain, every cell's move) and the writing, and the inspection reads the first two; follow.move_field and follow.region_weight are the move and the weight move_regions draws with. docs/video-pipeline.md.
  • tests/video/test_follow_inspect.py draws 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's follow is what video-follow then writes to the strip's meta; every pixel video-follow changed 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; after video-follow the 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. What video-follow refuses 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's follow as 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
A synthetic walker as delivered, two cells melted The same walker with both cells restored from their source frames

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 by still_view_text and gen --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 --motion alike. 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.py holds 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 by still_view_text and gen --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_TEXT takes {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.py holds 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.py lists 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-contact refused 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 pieces drop_specks reads): it is residual only when nothing in its piece is off the key's hue — background on its own — and subject when it is joined to the subject. A frame with such a rim in the band passes with --allow-subject-edge-contact and 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 wide gives 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 through STATE_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; --headroom still 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-loop leaves 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 auto and periodic — 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's start and context_pair_range, a refusal's windows too, so --cycle fixed --start taken from them cuts the frames they name. Every walk and run report gains lead_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.coverage counts 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_drift gains method: one-cycle-on in 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 and strip.json byte for byte. docs/video-pipeline.md, docs/loop-review.md.

  • Fix: --body-height reads 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-height now 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, and strip.json says so (body_ref: cut-first-frame, body_ref_frame, the clip frame); video-cycle-align rebuilds such a strip at the same height. The report gains cut_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 and strip.json are 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, and video-cycle-align keeps 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-frames erases 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, and video-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 gains specks, how many its frame lost, and the report specks (dropped, frames and 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.py keys 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-follow reads 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 gains body_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.py follows 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-follow replaces 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_loop given 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 as follow.source.png, as on a refusal). follow_loop reads its regions, gain, freq and zeta as 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.0 where it was 80). loop.verify_animation closes the file it checks. The command's output, its strip, GIF, WebP and record, and --help are as before, byte for byte. docs/video-pipeline.md.

  • tests/video/test_follow.py moves 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 float32 gain: 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 but follow.source.png.

  • Output change: video-follow --on-fold lower gives 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 --gain takes 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_regions takes groups of regions, each with its own offset), and the move there is nowhere steeper than either region's own. In the record each fold.regions entry gains gain (0 when held) and held, the strip's gain is the largest any region moved by (dx_px, dy_px and reach_px are that gain's), fold.ratio is the nearest any region came to folding and fold.lowered says whether any region was lowered or held; the printed summary gains region_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.py moves 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.9 the 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-auto reads 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, and tests/video/test_loop_prop_seam_held.py failed 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, now sprite_gen.util.lsq.line), not np.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.py perturbs 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 is np.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_long draws 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-auto scale 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 was np.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.polyfit on 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 line auto_motion already 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.py holds a synthetic walker whose feet stand on the frame's bottom edge with np.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.py checks the line against np.polyfit and in any order of its points (moved from test_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_screen on every walk and run video-loop --anchor motion-auto cuts. 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 (depth at least 0.15) better than at the cut (ratio at most 0.85, period.STEP_RATIO_MAX) is a suspect. 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's cycle and the printed summary gain step_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. 1 cuts 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). 2 keeps the cut. Either way cycle.steps records the count (by: "given", given, and for 1 first_cut and window), strip.json says steps: 2, and cycle.coverage is (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-len window is the window, on every path that sets a cut's length. --anchor motion-auto cut the caller's ceiling back to half the clip, so asking for a slow walk's cycle (--min-len 41 --max-len 43 on 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 auto one-shot failover of an action state widened an explicit --max-len to nine tenths of the clip (a 16-frame hop asked under --max-len 14 was cut 36 long) and the one-shot search took no --min-len at all; both are held to the caller's bounds now (detect_one_shot honours min_len; run_loop passes ONE_SHOT_MIN_LEN unless --min-len is 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 fixed and pinned included, 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 1 on a 21-frame step under --max-len 25 cut 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's cycle.steps with counted_window, window: null and refused). Where they share part of the window, only that part is read (cycle.steps.window, counted_window beside 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-auto reads 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_edge on 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.steps is {"count": 2, "by": "held-edge", "step_lengths": [...]} (the candidates it is two of, each one step), cycle.period_local its own length, cycle.coverage recorded, and strip.json says steps: 2. A cut with fewer than two clip frames either side of it cannot be read: skipped, counted under unread, never chosen. An explicit --max-len stays the cut's ceiling (two_step_capped: max_len, lengths_over), and counted steps read nothing twice as long. cycle.seam_pop.held_edge records side, reference, measured, unread, doubled, chosen and two_step (read, lengths tried, measured, unread, top_pops, closing); a candidate row carries held_edge (null with held_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.warnings and stderr gain the 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-len kept 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-align reads a loop's steps, and stops on a loop that may be one step. A loop whose strip.json says steps: 2 returns half way at its second step: that suspect is recorded status: "steps" (with steps) and does not stop the set, and the loop is resampled to the set's length like the rest; --cycles <loop>=2 on it takes one half out and drops steps. A loop whose cut's report (beside the loop, or one directory up for a video-set item: align.cut_report) has cycle.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 fail with its name and cut it again with sprite-gen video-loop … --steps 1, aligned and warned about under warn; --cycles <loop>=1 says it holds a whole cycle. Every loop with neither is aligned as before, its row, strip.json and cells byte for byte.
  • video-set: an item whose cut's steps are known carries loop.steps, one the step screen suspects loop.step_screen (lag, ratio, depth, coverage), and table.md says 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 carries ratio like any candidate, which the item reads.
  • tests/video/test_explicit_window.py holds 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-len or --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.py draws 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 (ratio 0.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 1 cuts 15/42 where the arm's wrap is 0 against 7.6 for the step, --steps 2 keeps the cut, a 50-frame clip is cut 8/42 and warned about its coverage, --min-len 41 --max-len 43 is the window, and the set alignment stops on the step and aligns its re-cut. tests/video/test_loop_prop_seam_held.py draws 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 the strip.json and cycle_align keys 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-auto chooses 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's cycle.seam_pop records first_choice, applied, measured, unread and chosen (or why when 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 recorded skipped (why) in place of a pop (first_choice.skipped; a candidate row's seam_pop is null with seam_pop_skipped), counted under unread, 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 axis wrap_pct, step_median_pct, wrap_over_median, wrap_is_largest; pop, reference, pops; seam_pop in the printed summary's jolt). Over the bound, on the loop as it plays, jolt.warnings and stderr gain the 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 periodic cut is not chosen again.
  • New: a motion-auto search that finds no cycle reports the windows it measured and refused. The failed report's cycle was null, 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 carries status: "refused", window, refused_count and up to 12 candidates (start, length, score, ratio, context_repeat_over_step, drift_line_residual_analysis_px, seam_pop, and refused: 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.py draws 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 with start_foot: null, is listed under the report's unnamed_feet with 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_why of a margin too small starts low-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 of the two strikes look alike in shade (…), for both cues — in the loop row, unnamed_feet, the warning, and foot_unnamed_why once told.
  • tests/video/test_cycle_align_foot_margin.py draws 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 prepare writes 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 --motion too) 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 same biped / quadruped / legless / "<figure>=<plan>" as video-set; repeatable; over the request's body_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 is DEFAULT_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.json records body_plan (absent without one) and a run prepared again from it keeps it. video-set / video-prompt --body-plan now also give the attack ATTACK_TEXT_ANY_BODY ("with what it is already holding, or with its own body if it holds nothing") and HOLD_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, new tests/fixtures/prepare-rows-v2.32.0.json.gz drawn by tests/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.py draws 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 on prepare, 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-set motion 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-plan on video-set, video-prompt and gen (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; on gen it needs --direction): biped (default), quadruped or legless, 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 becomes STILL_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 --json and gen's extra.view record body_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.py draws 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_text and gen.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 a video-set item's name) and video-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-foot was 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 from cycle.source/), so it holds for a later alignment at the same length; like --cycles it is not remembered. A foot given for a loop the view did name is taken too, and where it disagrees the row carries foot_disagrees and a warning. A --foot that names no loop or two, or is not left/right, is refused before anything is rewritten; video-set refuses an --align-foot item 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's feet_unused and 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: strike 0 and 1, frame in the rebuilt cycle/ and the path to that frame — the frame to show whoever looks; the first is the frame the loop starts on) and settle (the two --foot arguments). The report also gains feet_given; every loop row and its strip.json cycle_align gain start_foot_source ("engine" where the view's cue named the foot, "given" from --foot, null where nobody did) and strikes (the two strikes as frames of the rebuilt cycle/), and a told row foot_given and, where the engine had not named it, foot_unnamed_why instead of foot_why. video-set carries unnamed_feet and feet_given per state and start_foot_source per item; a stopped set's command carries the --foot given. The warning for an unnamed loop now names the frame to look at and the --foot that 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-align names 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-loop now 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_drawings in the loop report and in strip.json: start, length, steps, hold, drawings_per_second, contrast), and the alignment uses it (drawings.source: "span", with the clip's reading under drawings.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's span_why says 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 and strip.json gain cycle_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-align names a loop to film again (retake, reason held-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 auto or nearest, made with a fault and kept under rife), is listed in the report's retake (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 frame auto took 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 its strip.json cycle_align gain drawings (the hold, read from the clip's record) and retake (the record, or null); video-set carries retake per 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-loop records the clip's drawings (drawings in the loop report and in strip.json, hold/drawings_per_second in the printed summary): whether the clip shows each drawing for one, two or three frames, how many drawings a second, the held steps, and contrast per hold as the evidence (sprite_gen/video/held.py), read over the whole clip as keyed, before the cut. The alignment reads the hold from strip.json: a cut cycle is short, and --anchor motion-auto shifts 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-align keeps from RIFE. --between gains auto, now the default (video-set --align-between too): 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's cycle_align gains nearest_at beside made_at, and made_by_rife counts only the frames kept. --between rife gives 2.27.0's frames, with the new warnings; nearest is 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.smear now also measures outline_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 fault outline; 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 read dark_excess −1.3 %, lower than its melted frame of a long crossing (−1.1 %); outline_loss reads under 3 % and 32 % (tests/video/test_rife.py). partial_excess is 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.smear rows gain method (rife, kept, or nearest, the nearer source frame taken instead), outline_loss and faults; the report gains replaced, and video-set's cycle_align per state too. A fault is a line in warnings under every --between: under auto it says the nearer source frame was taken there, under rife that the frame is kept and where to look. auto runs RIFE wherever rife does 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-align rewrites. 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 gains cycle.fundamental, and strip.json gains state). video-cycle-align now 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 with applied: false, refused: "cycle-suspects" and the typed suspects. A set with no suspect is aligned as before, every loop resampled from all of its filmed frames. video-set --align-cycles auto skips such a state with a warning (applied: false, reason: "cycle-suspects", suspects) where it aligned it, and the RIFE skip now carries reason: "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-loop cut two strides as one loop, and video-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: screen measures the half and the third — periodicity, pose off the motion's path, and for the record the legs' steps and follow — and one rule, period.verdict, decides: a half or a third that repeats is a suspect, whatever its pose; nothing says "a cycle" and nothing says "not one"). video-loop records it (cycle.fundamental: checked, suspects, legs), and so does the local search of --anchor motion-auto. video-cycle-align screens 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 warn aligns 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 a video-set item'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). 1 aligns it as it is; 2 or 3 takes 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 record cycles_given, cycle_screen and cycle_taken; the report cycles_given, suspects and multi_cycle. Also new: --multi-cycle fail|warn and --state (the gait floor for loops cut before strip.json carried state).
  • The foot-strike signals moved to sprite_gen/video/legs.py (align.strike_signals and the align constants 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-auto with --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-follow with its default --on-fold refuse writes 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_hold in the report carries the evidence: method, lag, pose_match, pairs, per_lag and drift_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)); lower takes 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, and fold: 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 what video-set does 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 --fps from the frames report, and ends with video-cycle-align --view … once a walk or run is cut in two or more directions (SKILL.md routes, docs/video-pipeline.md with Set and Size rows in its ZCRE table, docs/user-workflow.md, the READMEs). video-cycle-align is in the pipeline's diagram and verb table. SKILL.md forbids 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-loop jump repair) are drawn differently wherever the legs cross or the flow is unsure; frames taken as filmed are untouched. Every loop video-cycle-align turns 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 from cycle.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.smear lists per made frame dark_excess (dark pixels inside the body beyond the darker neighbour's count — a moved hat or watch keeps its count) and partial_excess (part-covered pixels beyond the more ragged neighbour's); over 0.1 % dark, the frame is named in the alignment report's warnings, on stderr and in video-set's warnings (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. rife stays 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_on in 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 in video-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-set passes 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, with handedness.placement for 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 with start_foot: null and foot_why, and the report's warnings say so; without --view the report says once that no foot was chosen. Each loop row carries view, start_foot and foot (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-auto now holds the clip at its first frame's size before the cycle search (--size-hold auto, the default; size_hold in 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 off gives 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_ltrb in size_hold and gait_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 (--freq 2.4 Hz, --zeta 0.6, --gain 2.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, follow is recorded in the strip meta, and the strip as it was is kept as follow.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-align clears a follow-through: it rebuilds the strip from the cut, so it removes follow.source.png and the follow record and says follow_cleared in the loop's row; a new video-loop cut removes them too. Run video-follow after 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 crown kept
video-follow on a hip pouch (zoomed): as cut, and following the walk's bob as a damped mass pouch follows

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 regen regeneration), video --direction side and the mid-step redraw send what 2.22.0 sent. tests/gen/test_prompt_freeze.py holds every prompt string in that table to tests/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 --handed the 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) and video-set (each item's still_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 --handed carries the handed sentences once.
  • handed-check passes 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|run it must also show in at least a quarter of the frames (far_shown; unchecked without --state or 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 --handed item on its other side, is sent as written with a warning; text that repeats an option gets a note. gen prints them and records extra.prompt_notes; video-prompt --json lists conflicts in warnings and all of them in notes; video-set records prompt_notes per item. The prompt is the same with or without them.
  • tests/gen/test_prompt_assembly.py draws 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 --handed plus 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 mirror is refused and regen never falls back to a mirror. video-prompt --handed and video-set --handed end 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,left films 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 the gen --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-check checks 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 --reference front 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 --zone adds 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. --board draws 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 --facing was; they now take the facing ("heading diagonally toward the viewer and to the left"). video-prompt and video-set also cut a left-facing diagonal's loop with --facing left (it was always right), which mirrors the jump repair's hair box. Right-facing prompts are unchanged.
  • A gen --transparent run with --ref keeps the alpha it comes back with: auto still 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, with alpha.strategy: "native" and alpha.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 a warning. alpha.raw_alpha records the verdict and its numbers on every ref run that planned the key. --alpha-mode chroma keys 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 --ref prompt that names no key background gets the --chroma-key key's line (chroma.KEY_BACKGROUND_TEXT, moved from video.batch so 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_background records injected and 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 chroma and native runs are unchanged. docs/gen.md.
  • --decontam is 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.decontam records what was asked and why it was skipped, and stderr says so (a warning for palette).
  • chroma.classify_raw_alpha judges on the pixel counts, not the rounded percentages: a raw with alpha 0 under 0.005 % was no-alpha and keyed with no warning; it is ambiguous now.
  • 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, so video-loop --body-height scaled 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.26 or 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 wide keeps 35 % above (WIDE_OVERRIDE, no longer the attack row): it is forced on states whose own row is another shape — video-set --shape wide across 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 wide batch 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-prompt prints the clip prompt video-set sends for one (direction, state) — build_prompt with --character, --motion and --model — so an agent that makes the clip itself, with a video MCP connected to it, sends the same sentence. --json adds 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 the video-canvas still, quotes, asks the user, generates and saves the mp4, and video-frames and video-loop take 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-frame refuses what video-set films pinned — idle, attack, a walk or run in a diagonal — and --unpinned films 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-frames reads 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 records codec, pix_fmt, audio_streams and cover_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 yuv420p with 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, beside resize_cell in sprite_gen/util/resample.py): the gait fallback's scaled-back frames (video-loop --anchor motion-auto on 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, so compose, 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 in sprite_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: lanczos keeps its name and stays the smooth shrink (coverage is still LANCZOS); nearest, kcentroid and 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-loop scales its cells with coverage and colour taken apart (resize_cell, used by build_strip, so the strip, the GIF, the WebP and video-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 by still_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's VIEW_TEXT is 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 left mirrors 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's jump_repair names the frames, the scores before and after and the interpolator; with a frame replaced the seam gate reads the rendered cells. --repair off cuts 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-vulkan 20221029 with rife-v4.6, found by SPRITE_GEN_RIFE, then PATH, then where sprite-gen rife install puts 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 with sprite-gen rife install and runs it on llvmpipe.
  • Install RIFE in one line: new sprite-gen rife install downloads 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-gen or $XDG_DATA_HOME, %LOCALAPPDATA% on Windows), staged and renamed into place. It ends with a check frame through the installed binary. --zip installs from a zip already downloaded, --dir installs elsewhere and prints the SPRITE_GEN_RIFE line, --force unpacks 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 auto cuts the loop as filmed — jump_repair reads applied: false with the reason and the install line, and stderr carries one warning — and video-set skips that state's cycle alignment (cycle_align.<state>.applied: false, listed under the set report's warnings, one warning line). Asked for by name, it fails: video-loop --repair on and video-cycle-align. A RIFE that is found and then fails is an error in every mode. Cutting a loop again removes its cycle.source/, so the next alignment reads the new cut.
  • The jolt index is reported on every walk and run (jolt in 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-max turn 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_align in strip.json). The cut as filmed is kept in cycle.source/, so a second run never resamples a resampled loop. video-set runs it for every walk or run filmed in two or more directions (--align-cycles auto, default). Strip metadata now records cell_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 one sprite-gen gen --ref call.
  • Method, measurements and the regression on the eight-direction set: docs/loop-repair.md.
  • video-frames --decontam palette adds 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_band in the report's decontam). 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_diagonal and back_diagonal join side, front and back (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-loop outputs 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 by video-set too) 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 by GAIT_HOLD_TEXT for 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, only PINNED_LOOP_STATES get 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-auto finds 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-len stays the ceiling. The report records what was tried in gait_fallback; when the second search fails too, the error still starts with video-loop: no periodic cycle found and 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-guide attaches 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/edits and bills the guide as image input, and --transparent steps 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 in extra.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_TEXT in sprite_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-auto finds 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, repr and 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, a Bearer value 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 makes sk-/xai-/bearer part of a word" was wrong there. It holds now, and the letter or digit is the provider's own: task-… and xbearer … are still words, and so is a key after the two characters \n or %0A the provider wrote itself. A Bearer value 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 is error.code (or, for xAI's synchronous errors, a top-level code) and is printed only when it matches ^[A-Za-z0-9_.:-]{1,64}$. The video verbs read the code out of a failed poll's error object 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-…, a Bearer value, 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 a Bearer value right after _ or - (api_key_sk-…, x_Bearer …) is masked too; only a letter or digit in front makes sk-/xai-/bearer part 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's moderation_blocked is the only such code (the image guide calls error.code the stable discriminator); its moderation_details.moderation_stage follows as moderation_stage=input|output|unknown. xAI's invalid_argument is not one: it covers moderation and parameter errors alike.
  • An xAI clip that finishes with video.respect_moderation: false is now <verb>: generation <id> refused by the provider's content policy (HTTP 200) respect_moderation=false; nothing was written instead 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 is sprite_gen/gen/refusal.py POLICY_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, and build_prompt(motion=...) no longer adds a repeat sentence after a caller's paragraph (REPEAT_TEXT is empty; HOLD_TEXT still follows it once). The clip is pinned to the canvas as before, so it runs stance -> strike -> stance, and video-set cuts it whole with video-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-set asks 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, and build_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 (and video-set, which judges each item's canvas.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 records reference_size, reference_window and reference_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 runs video-frames --decontam palette in 1.1 GiB.
  • --decontam keeps 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 for cutout, 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, where cutout --decontam palette left 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 gain material_spread and restored_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.

Gold drops and strokes before and after

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 (request chroma.decontam for the row extractor and inspect). 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. palette demands the pass and fails where it cannot run; auto runs it wherever it applies and records why it did not elsewhere. Available on cutout, gen --transparent (chroma keying), video-frames / video-set (video fit, one palette per clip) and the row extractor. Every default stays off, 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 pinned keeps 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 within max(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-set cuts 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).

Nine idle loops before and after

v2.8.1 - Tight clips pass their own edge and corner checks

  • video-frames --allow-subject-edge-contact fails 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-loop keeps 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 tight frames 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-height target is reached at a low clip resolution by scaling down rather than up. A motion that leaves the frame is clipped. The default --fit state is unchanged, and the report now says which fit framed it.
  • video-frames --allow-subject-edge-contact accepts the subject at the frame edge and still refuses leftover key background there. The report's edge_policy names the rule that applied.
  • video-set --fit tight frames 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-height measures 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 records body_ref, body_src_h (the standing height as filmed) and scale, 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-set asks attack clips for 4 s by default (other states keep 3 s; --duration still 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's duration and last_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 N passes 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 explicit motion registration remain strict.

  • Add explicit video-loop --anchor motion for 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-auto for walk/run in video-loop and video-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
Nine human walk loops Nine animal walk loops

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 for walk and run) 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 records wrap_dx_px and seam_ratio_after_anchor. --anchor feet and --anchor none are unchanged, and other states keep none.

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-loop refuses with no 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 0 restores the previous placement.
  • video-set --base refuses a direction the prompt table does not know (back, front, side) instead of accepting left= 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|left to request orientation in the generation prompt. The default preserve leaves existing generation callers unchanged.

  • Facing inspection is record-only by default: gen, video and video-set use --facing-fix none. Explicit mirror corrects an observed opposite in the output copy; gen --facing-fix regen regenerates once, rechecks and mirrors a remaining observed opposite.

  • video --direction side and 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_source distinguishes observations from values derived by mirroring; none is independent verification. Failed or uncertain calls record unknown with 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 JSON null.

  • 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) and attack-claudecy-samurai-onehand.gif were 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 small correction 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 openai image provider: sprite-gen gen --provider openai calls the OpenAI Images REST API with nothing but OPENAI_API_KEY — the credential a headless container (a Modal worker, CI, a SaaS backend) can have, where the codex route's interactive ChatGPT login cannot exist. New images go to /v1/images/generations, --ref switches to /v1/images/edits as multipart with the references as repeated image[] parts in order (up to 16), and gpt-image's inline base64 is decoded and published as a verified PNG without resizing. Default model gpt-image-2.5-flare. --transparent asks for background: transparent with output_format: png — the same measured native strategy as codex, and a live run came back 84 % alpha-0 with the subject at alpha 251–254. --aspect-ratio maps to one of the gpt-image size values 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. codex and grok run on a subscription you already pay for; openai bills per call, so it runs only when --provider openai names it. SPRITE_GEN_DEFAULT_PROVIDER=openai is refused rather than honoured, the guided workflow flow neither offers it nor saves it as a preference, no availability fallback targets it (a codex outage still reaches grok, never metered credit), and having OPENAI_API_KEY in 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|auto and gen --resolution 1k|1.5k|2k: the two knobs an image is billed on, as one shared vocabulary with a per-provider subset. grok Imagine carries auto|low|medium and all three resolution tiers and prices an image on the pair; openai carries the whole quality range and takes its size from --aspect-ratio; codex image_gen exposes 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.5k rendered 1408x1408 at 1:1 (2026-09-20 measurement) — and the grok subsets were read off the server rather than the prose: quality deserializes 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.5k renders 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 carry extra.quality and extra.resolution when the request sent them.

  • video, video-extend and video-edit announce the per-call charge on stderr when they run on XAI_API_KEY instead 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. workflow access probing knows openai — ready when the key is set, with billing: api-credit and the billing confirmation that goes with it.

  • video-loop automatic 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 retain next_frame_distance as a separate diagnostic.

  • video-frames --spill full now lowers the tint threshold as well as lifting the cluster-size limit, so faint key-colour reflections are corrected. --spill auto examines the reference at the same threshold before selecting full correction, preserving the character's own key-coloured material. The conservative small mode 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" and cycle.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-loop one-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 records excursion_moved and excursion_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 --duration defaults 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 6 still asks for a longer clip.
  • video-loop walk 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) records kind (periodic / one-shot / fixed) and loop (false for a one-shot), and the spec asset loader reads loop from 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|auto and video-set --spill (default auto): 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. auto keys 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-frames defaults to small, byte-identical to before; the frames report records the decision under spill.
  • 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 video gains the other Grok Imagine generation modes: --last-frame pins 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. --image is 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 new video-edit (POST /v1/videos/edits) changes a clip of at most 8.7 s with a prompt. Both force the classic grok-imagine-video model (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, and video-extend refuses 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, and last_frame / image+reference on the classic model.
  • The sprite-gen-video-report carries mode (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.py shim. It shared its name with the generate_image() function that sprite_gen.gen exports, so import sprite_gen.gen.generate_image replaced the function with the shim module for the rest of the process and the next sprite_gen.gen.run() died with TypeError: 'module' object is not callable — at runtime, not only under pytest. Nothing routed to the shim (no CLI verb, no -m step, no MCP entry), so the fix is deletion: the old module path now fails with ModuleNotFoundError, and the only image-generation entry point remains sprite_gen.gen / sprite-gen gen. sprite_gen._modules.MODULE_DOMAIN and the packaging import-surface list drop the row; the import_probe fixture stays as a general isolation device.
  • Test isolation: the packaging import-surface probe now restores the parent package attribute and sys.modules entry it touched, so importing the retired sprite_gen.gen.generate_image shim no longer replaces the generate_image() function for later tests/gen runs. pytest tests/packaging tests/gen is green in any order.
  • Test isolation: tests/curate imports its shared helper from tests/frames through the tests/ root instead of by bare module name, so pytest tests/curate passes on its own instead of depending on tests/frames having 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, with grok login as the fallback, and the message says so. A test pins the prescription to a non-agent command.

v2.2.1

  • video-loop gait half-period guard: a walk/run period 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 carries cycle.half_period_guard (applied, from, to, depth ratio, or below_floor + why it was left alone). --min-len still overrides.
  • video-loop one-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 (also video-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 gains foot_anchor, drift_px (drift removed), foot_sway_px (the planted foot's in-gait movement, kept and reported) and foot_x, and declares the spec loader's anchor as [foot_x, h] so scenes stand the sprite on its feet; the video-set table row carries drift_px. Default none keeps 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, wave and celebrate now take the wide canvas (raised limbs leave a 1:1 frame at the top corners), video-set --shape forces one shape for a whole batch (wide costumes), and video-set carries cheer / wave motion 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 records extra.trim_alpha (bbox, before, after, margin_px). The .raw.png is untouched.

v2.2.0 - Independent asset tools and optional scenes

  • Added standalone background-tile, shadow and inspect-motion commands. 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-render and scene-inspect with 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; --model now 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_HOME supported), even with XAI_API_KEY configured. 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_candidate rule 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, in cutout, extract, slice-sheet and video-frames. Image models paint #00FF00 as (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 carry chroma_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-canvas normalizes 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 the cutout matte's own alpha-0 set, the subject is byte-identical). The report records key, key_painted, normalized_px.
  • video-frames tells leftover key background at the frame edge (residual, points at video-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 workflow command checks credentials, resolves request choices over saved defaults and returns the next questions and existing engine route.
  • Added defaults show|save|clear with 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-loop checks that img2webp actually 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 installs ffmpeg and the official libwebp 1.6.0 binaries so the video tests run there, and those tests skip cleanly where support is absent.
  • video-loop body_h is 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 N scales every state to the same standing height directly in the pipeline (--strip-height remains the cap). README heroes regenerated at one standing height.

v2.0.2 - Heroes from the pipeline

  • video-loop GIF/WebP default rate is now 24 fps (the source rate): every cycle frame is kept, so fast actions never read slow; --gif-fps 12 restores the lighter output.
  • video-loop --cycle fixed --start N --length L cuts an explicitly named cycle without detection (reported as kind = "fixed", seam gate still applied) — for clips with too few repeats for the periodicity gate.
  • video-loop --strip-height caps the cell/strip/GIF height so an output can be produced at its display size directly from the pipeline.
  • README hero GIFs are video-loop outputs verbatim; the jump <img> height matches its taller file.

v2.0.1 - Jump loops play at the same rate

  • video-loop GIF/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-out still overrides; the report records gif_fps.

v2.0.0 - Four pipelines, one taxonomy

Highlights

  • Video → sprite loops. One still becomes a whole motion set: video-canvas pads it into the canvas the state needs, video animates it in place through Grok Imagine, video-frames keys every frame, video-loop finds the true period (or the one performed action) and emits a strip, a transparent GIF and a WebP, and video-set runs directions × states with per-item reports. Every stage is measured and fails by name.
  • Parallel row generation is a command. gen-set generates 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 --help opens with the four named pipelines (A atlas rows · B video → loop · C utilities · D post-processing) and groups every verb by domain; the grouping, the scripts/ map and the pipeline list derive from sprite_gen/_modules.py (MODULE_DOMAIN, PIPELINES), and the docs classification is catalogued in docs/README.md itself, checked by tests against the file set and the pipeline catalog.
  • Documentation you can navigate. docs/README.md indexes every doc once under its branch with a one-line owner; docs/architecture.md opens 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) and img2webp from 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.py sprite-gen extract (scripts/extract_sprite_row_frames.py)
    scripts/gif_utils.py from sprite_gen.util import gif_utils
    scripts/runio.py from sprite_gen.spec import runio
    scripts/reroll_state_row.py sprite_gen.effects.reroll (module; interpolate_frames.py covers 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.md merged into docs/breathing.md (one contract, one owner); links to the old file are gone.

Added

  • sprite_gen/video/ domain and the verbs video-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 and table.md gains a kind column. walk, run, idle still 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, --provider honoured verbatim with gen'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 in run-contract.md, layer-tracks.md, curation.md, directional-anchor-workflow.md, architecture.md; scripts/dev/README.md.

Changed

  • SKILL.md is 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 to docs/interpreter.md, docs/rename-gate.md, docs/breathing.md.
  • video-loop strips 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 records cell_cap and subsampled.
  • 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-set motion templates no longer assume a biped.
  • README.md is 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 to docs/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 a sprite-gen-video-report JSON.
  • Credentials are the user's own and never part of the repo: XAI_API_KEY when set, otherwise the grok CLI login file (~/.grok/auth.json, GROK_HOME honoured). The report records auth_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.py and docs at docs/video.md.

v1.60.0 - Native Alpha

  • sprite-gen gen --transparent now follows a per-provider transparency strategy declared once on each adapter (Provider.transparency). codex asks image_gen for a genuinely transparent background and publishes the measured alpha (native, first choice); grok keeps deterministic chroma keying because Grok Imagine returns JPEG only.
  • Added --alpha-mode auto|native|chroma. auto reads the provider's strategy, chroma forces keying on codex for prompts that already carry a key background, and native on a chroma-only provider fails before any model call. With --ref attached, auto keys instead of asking codex for native alpha (measured 1/6 real alpha with references vs 6/6 chroma); the report records why under alpha.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 alpha block (strategy plus stats) next to the existing chroma stats, and codex's own transparentBackground claim under extra.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-aseprite for 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's exports/ directory.
  • Added a Windows LockFileEx backend 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 .cmd shims and non-UTF-8 console code pages.
  • Made Python 3.14 CLI option tests deterministic under colored shell output.
  • Added character and effect subject profiles. Their sparse-frame floors scale with cell resolution: ceil(sqrt(width * height)) for characters and half that value for effects. Explicit --min-used-pixels still wins.

v1.58.0 - Compose canvas and domain package layout

  • Added the human-facing sprite-gen compose assembly 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 from sprite_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.