Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
Merge origin/main (11827ad, 2.45.0) into main: the release carries the UTF-8 output fix as unreleased
Soohong Kimf4b7cd7c08d0
diff --cc CHANGELOG.mdindex 809b838,6daed34..575ab57--- a/CHANGELOG.md+++ b/CHANGELOG.md@@@ -2,11 -2,30 +2,34 @@@All notable public changes to `sprite-gen` are recorded here. Versions track the `version:` field in `SKILL.md` and `pyproject.toml`.+## Unreleased++- **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`.- - **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 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](docs/loop-repair.md#4-one-cycle-for-a-direction-set--video-cycle-align-video-set---align-cycles-auto)).- - **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 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.+++ ## 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](docs/loop-repair.md) 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](docs/loop-repair.md#the-overlapped-wrap--a-part-on-its-own-beat-that-no-cut-of-two-steps-closes)).+ - **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](docs/loop-repair.md) 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](docs/loop-repair.md) 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](docs/loop-repair.md) 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](docs/loop-repair.md) 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](docs/loop-repair.md#2-jump-frames--video-loop---repair-auto)).+ - **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](docs/loop-repair.md#4-one-cycle-for-a-direction-set--video-cycle-align-video-set---align-cycles-auto)).+ - **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](docs/gen.md#when-codex-cannot-run--ask-or-what-you-chose), [SKILL](SKILL.md#when-codex-cannot-run--exit-75)).- **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.diff --cc sprite_gen/video/stop.pyindex cbdee5e,5ffe9c7..4f1af04--- a/sprite_gen/video/stop.py+++ b/sprite_gen/video/stop.py@@@ -72,8 -72,7 +72,8 @@@ from sprite_gen.video import gait_fallbfrom sprite_gen.video import loop as loop_modfrom sprite_gen.video import nonloopfrom sprite_gen.video.interpolation_quality import ghost_screen- from sprite_gen.video.repair import ALPHA_SOLID, JUMP_RATIO+ from sprite_gen.video.repair import ALPHA_SOLID+from sprite_gen.util.console import utf8_streamsPROG = "video-stop"KIND = "stop"