Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
docs(no-repeat): loop-repair section 7 (the wrap read as a ring, the read again after the repairs, an alignment aligned as filmed and filled at the end, an effect's lifetime named and not filled, the paths at a higher rate), video-pipeline's held cells, scene.md's `--between-cache`, SKILL.md's rules for a fixed display rate and `inspect-holds` before delivering joined clips, and the CHANGELOG's Unreleased (v4.0.0)
Soohong Kim378ca6ffd60c
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex f0aec79..593f827 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -6,6 +6,8 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the**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 |@@ -24,6 +26,23 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the- **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++- **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".+- **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_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.+## 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.diff --git a/SKILL.md b/SKILL.mdindex 5bec389..eb7cb90 100644--- a/SKILL.md+++ b/SKILL.md@@ -128,7 +128,9 @@ Use existing automatic pipeline stages for background removal, extraction, alignFor attack repeat coverage, observed one-shot returns and structured loop failure reports, follow [video-pipeline](docs/video-pipeline.md#one-shot-actions----cycle-autoperiodicone-shot).-Every cut is read for held cells (neighbour cells showing the same picture), and by default they are filled with RIFE's frames between and the cut read again (`video-loop --fill-held auto`; `off` cuts as filmed). Tell the user each motion's poses over cells in one line from `held_fill` (`poses/cells`, before and after, e.g. `24/27` to `27/27`). A run whose frames between were all refused stays as filmed and is named in a `warning:` line: say so with its poses over cells. A cut wanted above its clip's rate is given with `--out-fps`, frames between, never repeats. Details in [loop repair](docs/loop-repair.md#7-held-cells-a-picture-shown-again-and-a-cut-at-a-higher-rate).+Every cut is read for held cells (neighbour cells showing the same picture), and by default they are filled with RIFE's frames between and the cut read again once its repairs have run (`video-loop --fill-held auto`; `off` cuts as filmed, with no read again). A loop is read as a ring: a run that ends on its last cell, or a last cell that shows its first cell's picture, is filled too, the first cell kept. A hold the motion means (a run longer than three cells, a cut drawn on twos or threes, the opening and closing pose of a cut played once) stays as filmed and is listed in the strip's `holds`. Tell the user each motion's poses over cells in one line from `held_fill` (`poses/cells`, before and after, e.g. `24/27` to `27/27`); for a set it aligns, that is the loop as delivered, filled at the end of the alignment. A run whose frames between were all refused stays as filmed and is named in a `warning:` line: say so with its poses over cells. An effect's lifetime, a Grok clip and `face-bake` are read and warned, not filled: pass the warning on. A cut wanted above its clip's rate is given with `--out-fps`, frames between, never repeats. Details in [loop repair](docs/loop-repair.md#7-held-cells-a-picture-shown-again-and-a-cut-at-a-higher-rate).++Two rules. When an asset will be shown at a fixed display rate above its clip's (a 60 fps game or scene), give it at that rate with `--out-fps` (`video-cycle-align --out-fps` for an aligned set) instead of letting a cell show over several frames. Before delivering clips joined one after another, or a render made from them, run `sprite-gen inspect-holds` on it (with `--log` and `--log-figure` where the renderer draws figures at a new scale or sub-pixel place each frame, and the strips' `holds` as `--holds`) and tell the user any unlisted hold; `--gate` exits 1 where any hold is on no list.A move played once (a jump, a vault: `once`, `once-return`, `one-shot`) carries its root motion in the strip sidecar by default, the cells unchanged: `root_motion` gives each cell's root (the body's mass centre, cell px), what it stands on, and each air's take-off, landing, seconds and apex; a game reads `root` to place each cell and moves the body on its own physics. A move cut out of a longer motion is named with `video-loop --cycle once --start S --length L`, a hand on something the clip does not draw with `--contact hand=A:B`, metres with `--meters-per-px`; a jump whose body crosses the canvas is named the same way, because it never comes back to a pose it left: the one-shot cut refuses it and its line names the closest return (`the closest return, frames A-B, is R of its departure away`), whose frames are where to start the range. To give the air its own length, gravity and speed, `--air-retime gravity=G,air=T,speed=V` redraws it on that parabola with RIFE's frames between; contacts and the take-off and landing stay as filmed. Tell the user each air in one line, its seconds and its apex (the summary's `air`, e.g. `air 0.42 s, apex 0.21 m`). Details in [video-pipeline](docs/video-pipeline.md#root-motion--a-cut-played-once-where-the-body-is-what-it-stands-on-its-air).diff --git a/docs/loop-repair.md b/docs/loop-repair.mdindex e2a5fbe..5808752 100644--- a/docs/loop-repair.md+++ b/docs/loop-repair.md@@ -3402,14 +3402,9 @@ A `video-loop: warning:` line is emitted under two conditions. When the after ch## 7. Held cells: a picture shown again, and a cut at a higher rate-A clip can show one frame two or three times in a row: a video model that stalls, a rate carried to another by-repeating frames (20 fps carried at 24 repeats one frame in six), or a cut mapped to a higher rate by taking the-nearer frame. Played, the motion stops on that picture and jumps on. `video-loop` reads every cut it makes for held-cells (loops that are periodic, fixed, or pinned; one-shot, once, and once-return cuts; and so every cut `video-set`-makes and every clip of `video` cut through `video-frames` and `video-loop`). By default, it makes those cells again-as the frames between the pose before them and the pose after (`sprite_gen/video/held_fill.py`). The default step-of the pipeline is: find the held cells, fill them, read the cut again; the cut's line to the person is its poses-over its cells.+A clip can show one frame two or three times in a row: a video model that stalls, a rate carried to another by repeating frames (20 fps carried at 24 repeats one frame in six), or a cut mapped to a higher rate by taking the nearer frame. Played, the motion stops on that picture and jumps on. Every way the engine delivers frames now delivers no picture shown again by default. `video-loop` reads every cut it makes for held cells (loops that are periodic, fixed, or pinned; one-shot, once, and once-return cuts; and so every cut `video-set` makes and every clip of `video` cut through `video-frames` and `video-loop`) and makes those cells again as the frames between the pose before them and the pose after (`sprite_gen/video/held_fill.py`). A loop is read as a ring: a run that ends on its last cell, and a last cell that shows its first cell's picture (a cut one cell too long), are made again too, the first cell never changed. Once the cut's repairs have run, it is read again and a run a repair left is made again the same way. `video-cycle-align` (and `video-set --align-cycles auto`) aligns loops as filmed and fills each loop as aligned at the end. `video-set` cuts the walks and runs it aligns as filmed and lets the alignment fill them. `video-stop` makes a stalled stop's held cells again. `scene-render` gives a layer cut from a filmed clip at the scene's times where its cells would show again.++An effect's lifetime, a Grok clip (`video`, `video-extend`, `video-edit`, `video-resume`) and `face-bake` are read and warned, not filled. A hold the motion means (a run longer than `HOLD_MAX` 3 cells, a cut drawn on twos or threes, the opening and closing pose of a cut played once, `hold_last`, atlas clones) stays as filmed and is listed in the strip's `holds`. The default step of the pipeline is: find the held cells, fill them, repair the cut, read it again; the cut's line to the person is its poses over its cells. `--fill-held off` cuts as filmed.### The reading@@ -3418,42 +3413,65 @@ over its cells.| The same picture | A step where at most `CHANGED_MAX` 0.5 % of the subject's pixels change by more than `PIXEL_SAME` 0.1 (premultiplied RGBA). This is read twice: on the analysis thumbnail used to choose the cut (96 px on the longer side) and on the frames as cut. It is the same picture only where both readings say so. | A textured synthetic figure, each pose shown three times, is encoded by libx264 at crf 18, 23 and 28 and keyed by `video-frames`. A frame shown again changes no thumbnail pixel by more than 0.008, 0.020 and 0.051, and changes 0.012 %, 0.049 % and 0.11 % of the frame's subject pixels by more than 0.1. An arm 8 px thick on a 120 x 140 figure grown by one pixel changes 1.2 % of the thumbnail's subject pixels over 0.1 and 0.38 % of the frame's: the thumbnail separates it. || Not a distance over the mass | `nonloop.STABLE_MAX` (0.025), the once cut's settled end, is not the rule | The arm's pixel reads 0.003 of the subject's mass: under it, so the rule would call it held. || Where read | On the cut's frames as loaded, before an anchor moves each frame apart, and again on the cells delivered | An anchor shifts each frame of a pair by its own amount: a picture shown again would no longer read as one. |-| Not read across the wrap | A loop's last cell and its first are not a run | The wrap is the seam gate's, not a hold. |+| Read as a ring | A loop's last cell and its first cell are read as a run when they show one picture, and a run that ends on the last cell has its next pose in the first cell, across the wrap. The first cell is never changed. A cut played once (one-shot, once, once-return) reads no wrap. | The wrap is a step the loop plays like any other: from a picture to the same picture it is a picture shown again. A cut one cell too long (its last cell shows its first cell's picture, `held_fill.wrap_same`) is only seen at that pair, so the wrap is read on the cut's frames as filmed. || A move under a thumbnail pixel | A whole figure that moves less than a thumbnail pixel is read on the frame as cut. It is not the same picture. A small part moved a pixel or so reads as the same picture on both. | A synthetic walker moving away in a frame 280 px wide changes 4.9 % of the frame's subject pixels over 0.1 in a step that changes none of the thumbnail's. Two or three pixels of a hand on a large frame play as a hold. Made again between its neighbours, it plays the same. |-The record, `held_fill` in the loop report and in the strip metadata (the strip's without each try): `cells`,-`poses` (the cells less the ones showing the picture before them) and `held_runs` (each run's first cell and how-many) of the cells as delivered; `before`, the same of the cut as filmed with each run `filled` or `why` not (and-the `faults` its frames between were refused for); `made`, the cells made; `unmade`, the cells left for want of-RIFE with the install line; `out_fps`, the rate asked (below). `video-loop` prints `held_fill.poses_cells` (`27/27`)-and `before` in its summary; `video-set` puts `loop.poses` on each item. In the curation view (a loop's `cycle/`-imported with `unpack-atlas --pngs-dir`), the card of each cell made says `(made)` and of each cell still showing the-picture before it `(held)`. A stop (`video-stop`) is read the same way and records `held_fill` with `mode` off: it-plays the clip's filmed frames, none made between two others, and names a run it shows in a warning.+The record, `held_fill` in the loop report and in the strip metadata (the strip's without each try): `cells`, `poses` (the cells less the ones showing the picture before them; a loop's last cell that shows its first cell's picture is not counted as a pose) and `held_runs` (each run's first cell and how many) of the cells as delivered; `before`, the same of the cut as filmed with each run `filled` or `why` not (and the `faults` its frames between were refused for), each run kept as the motion means it carrying `keep` (its kind; `held_fill.KEEPS` names the kinds: `motion-hold`, `drawn`, `opening`, `closing`), and `before.wrap`, the run across the wrap (`start`, `length`, `joined`, `filled`, `made`); `wrap_held`, which says the cut as filmed showed one picture across its wrap; `made`, the cells made; `unmade`, the cells left for want of RIFE with the install line; `again`, the cut read again after its repairs (`before`, `made`, `frames`, `cells`, `poses`, `held_runs`); `out_fps`, the rate asked (below). The loop report also records `cut_args`, every argument the cut was asked with, which `loop.cut_again` uses to cut the same frames again. The strip metadata (`<name>.strip.json`) also records `holds`, a list of `{from, to, kind, reason}`, one per kept run, as cells of the strip (`from` and `to` both included; `held_fill.intended(record)` gives the runs, `held_fill.strip_holds` maps them onto the strip's cells; `inspect-holds` and `scene-render` read it as holds meant), and `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. `video-loop` prints `held_fill.poses_cells` (`27/27`) and `before` in its summary; `video-set` puts `loop.poses` on each item, those of the loop as delivered. In the curation view (a loop's `cycle/` imported with `unpack-atlas --pngs-dir`), the card of each cell made says `(made)` and of each cell still showing the picture before it `(held)`. A stop (`video-stop`) is read the same way and by default (`--fill-held auto`) makes each held run's cells after its first 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 with a warning line for each held run, and its sidecar records `held_fill` and `holds`.### The fill: `--fill-held auto` (default), `off`| Rule | Value | Why ||---|---|---|-| A run's cells made | Cell c of a run from cell a to the next pose b, at t = (c - a)/(b - a) between a and b: a run of two half way, of three a third and two thirds | The cut keeps its length, its beat, its first and last cells and its wrap: a made cell stands where a held cell stood, on its own time. |+| A run's cells made | Cell c of a run from cell a to the next pose b, at t = (c - a)/(b - a) between a and b: a run of two half way, of three a third and two thirds | The cut keeps its length, its beat and its first cell: a made cell stands where a held cell stood, on its own time. || Kept: a hold the motion means | A run longer than `HOLD_MAX` 3 cells | A drawing held on threes is three frames ([held.py](../sprite_gen/video/held.py)); longer is a pause the motion makes. A shorter pause meant as one is filled: `--fill-held off` keeps it. || Kept: a cut drawn on twos or threes (`drawn`) | Every run, where the cut's held-drawings reading (`cycle_drawings`, else the clip's `drawings`: [held.py](../sprite_gen/video/held.py), which `video-cycle-align` reads) gives a hold of 2 or 3 and every run is that many cells, but one cut short at the cut's first or last cell | Limited animation: each drawing shown as long as the next, played at its own rate as filmed (section 4). A clip carried to a higher rate by repeating frames reads a hold too (a synthetic walk at 24 fps carried to 60 by the frame under each time reads a hold of 2), but its runs are two and three cells by turns: it is filled (60 poses over 60 cells). A clip that stalls now and then reads no hold (hold 1). || Kept: the ends of a cut played once | A run that opens or closes a one-shot, once or once-return cut | The rest before the action and the pose it ends on are the cut's. |-| Kept: a loop's last cells | A run that ends on a loop's last cell | Its next pose is across the wrap: made, the last cell would change and with it the wrap. A run that opens a loop is made (its first cell stays). A periodic cut chooses its wrap where the steps either side read alike, so a held run seldom closes it; a fixed cut whose last cells are held keeps them, and its wrap then steps from a held picture (cut it elsewhere, or `--fill-held off` to keep the whole cut as filmed). |+| The wrap | A loop is read as a ring. A run that ends on the loop's last cell is made again between the run's first cell and the loop's first cell (its next pose is the first cell, across the wrap); the first cell is never changed. A cut one cell too long, where the last cell (or last cells) shows the picture of the first cell: those last cells are made again between the cell before them and the first cell, and the first cell stays; this is 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. | Played, the wrap is a step like any other, and a step from a picture to the same picture stops the motion there. A run is made again toward the first cell, never over it. || A frame made, judged | `align.measure_made` and `interpolation_quality.faults` (smear, outline, ghost, hole, doubled), the alignment's own | One acceptance policy for every frame RIFE makes (section 4). || A part standing still, kept still (`still_kept`) | The outline pixels both frames draw in one place in one colour (solid at alpha 128, within 24 levels) must be drawn there in the frame made, within a pixel, for at least `STILL_KEPT_MIN` 0.8 of them in every window a tenth of the body high that holds 12 or more; else the fault `contact` | A foot planted or a hand on a ledge stays where it stood. A synthetic in-between that drags a planted foot 3 px along the floor keeps 0.50 of its window; one off by a pixel, 1.00. || A picture of its own (`same_picture`) | The frame made must not read as the same picture (the reading above) as either frame it is made between or as the cell delivered before it (in a run of three, at `--out-fps` or in an air retimed with `--air-retime`, that can be a frame made too); else the fault `held` | An interpolator that gives back a frame it was handed, or one picture at two times, makes no frame between. Taken, the cell would be counted as made and still show the picture beside it. On a synthetic stalled walk (runs of two and three cells) whose interpolator gives back the frame before, both runs are kept as filmed (24/27 poses/cells). Each first cell is tried at its own time and then only later within half a cell (0.5 to 0.7, and 0.3333 to 0.45). `warning:` lines name cells 5-6 and 14-16. A synthetic fall that sinks less than a pixel in half a frame shows the frame before it again at 0.5 and 0.55, and is made at 0.6. || A frame refused | Made again at the fraction of `RETIME_T` nearest its own within half a cell of it, its ghost band under `RETIME_WINDOW_MAX` (section 4's bar for a frame made off its time). One refused as `held` is made again 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. Else the run is kept as filmed, with a warning naming the cells and the faults | A frame half way that RIFE cannot draw is often clean nearer one side. The frames between run from one pose to the next, so a fraction nearer a picture a frame showed again shows it too. On the cuts of eight tests that reach the binary through the default fill (`rife-v4.6`), trying every fraction within half a cell ran the binary 214 times. The side rule runs it 124 times and makes the same cells (3.10.0, which took such frames, ran it 90 times). || Whole or not at all | A run is made whole or kept whole | Half made, it would step back to the held picture and on again. |-| Order | After the anchor and `source_projection`, before the ghost screen, the wrap blend, the part pop and the jump repair | Everything that reads the flow and the wrap reads the cut as it will play. |+| Order | After the anchor and `source_projection`, before the ghost screen, the wrap blend, the part pop and the jump repair. Then, 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 is made again the same way (`held_fill.again`, below). | Everything that reads the flow and the wrap reads the cut as it will play, and a run the repairs leave is filled too. || No RIFE | The held cells are delivered as filmed, the cut passes, and a `warning:` line names the motion, the cells and `sprite-gen rife install`; `held_fill.unmade` records them | Never a failure, never silent. |-| `--fill-held off` | Cut as filmed, byte for byte as before; the reading is recorded all the same | |-| Byte for byte | A cut with no held cell is delivered as before: six synthetic cuts (a fixed and a periodic walk, a one-shot hop, a pinned swing, a once fall, a once-return swing) are pinned to their decoded pictures on the engine before the change (commit 886936e): every frame of the strip PNG, the GIF, the WebP and the `cycle/` cells, decoded to RGBA, with each frame's size and the frame count. The test no longer pins the file bytes because the same pixels are written as different PNG bytes on Linux and on macOS (zlib differs), though on each platform the engine before the change and this one still write identical files (`tests/video/test_held_fill.py`). | |+| `--fill-held off` | Cut as filmed, byte for byte as before, with no read again after the repairs; the reading is recorded all the same. For `video-cycle-align` it delivers the aligned loops as they come out of the alignment; for `video-stop` it plays every frame as filmed, as before, with a warning line for each held run. | |+| Byte for byte | A cut with no held cell is delivered as before: six synthetic cuts (a fixed and a periodic walk, a one-shot hop, a pinned swing, a once fall, a once-return swing) are pinned to their decoded pictures on the engine before the change (commit 886936e): every frame of the strip PNG, the GIF, the WebP and the `cycle/` cells, decoded to RGBA, with each frame's size and the frame count. The test no longer pins the file bytes because the same pixels are written as different PNG bytes on Linux and on macOS (zlib differs), though on each platform the engine before the change and this one still write identical files (`tests/video/test_held_fill.py`). Those pins hold, the strip metadata only growing `fps` and `holds`. A stop with no held cell is the same pictures as before. 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). | |A cut whose cells were made is read by the seam gate on its rendered cells (`seam_measurement`), restoration fromthe source frames (`video-loop-repair`) reads it as `source-processing-unsupported`, and `video-cycle-align` readsits drawings on its own cells, not on the clip's hold.+### Read again after the repairs++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. The repairs that follow (the jump repair, the ghost RIFE frames, the eased retime, the overlapped wrap, the wrap blend, the part pop, the seam bridge) are unchanged: they keep the cut's cell count and beat and are not a fill. They can still leave a run the first fill did not see. So once they have run, the cut is read again for held cells, and a run a repair left is made again the same way, judged the same way, with the same keeps. This is `held_fill.again`, 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 (its frame between was already refused, `ghost_given_way`) is not tried again; its own warning already names it. `--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.++### An alignment: aligned as filmed, filled at the end++`video-cycle-align` (and `video-set --align-cycles auto`) 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. `cycle_align.cut_again` records it: `report`, `fill_held` (`off`), `cells`, `made_before`. Where 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. 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).++`--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.++| Step | Frames | Record |+| --- | --- | --- |+| The cut | As filmed. `video-set` cuts the walks and runs it aligns with `--fill-held off`; a loop cut filled before is cut again from its `cut_args` with `--fill-held off` and kept as `cycle.source/`. | `cycle_align.cut_again` (`report`, `fill_held`, `cells`, `made_before`) |+| The alignment | Frames between made from frames as filmed, never from frames the fill made. | |+| The fill at the end | Each loop as aligned read for held cells and filled as `video-loop` fills a loop (`--fill-held auto`); `--fill-held off` delivers the loops as aligned. | The strip record's and the report row's `held_fill`; `holds` |+| `--out-fps F` | Every loop at F once aligned, each cell made between the cells beside it, every loop the same number of cells. | The strip metadata's `out_fps` and `source_fps` |++`video-set`: 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; its `loop.cut_again.why` is `not aligned`. `video-set --out-fps` with alignment was refused before. Now the aligned walks and runs are given it 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).++### An effect's lifetime: named, not filled++A `lifetime` cut (an effect's lifetime) 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.++Why: 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.+### A rate above the clip's: `--out-fps F``video-loop --out-fps F` (and `video-set --out-fps F`) gives the cut at F, above the clip's `--fps`: every cell at a@@ -3475,10 +3493,12 @@ Where sprite-gen gives frames at a higher rate than it was given them:| Path | Before | Now ||---|---|---|| `video-loop --gif-fps`, `--n-out` | The GIF and WebP never hold more frames than the cut (a higher request is capped at the cut's frames, never repeated) | The same; `--out-fps` makes the cells themselves at the higher rate |-| `video-cycle-align --length` | RIFE's frames between; a frame shown again only with `--between nearest`, or where a frame made is refused and the nearer source frame is taken (named) | Unchanged: it already makes frames between |+| `video-cycle-align --length` | RIFE's frames between; a frame shown again only with `--between nearest`, or where a frame made is refused and the nearer source frame is taken (named) | Aligned as filmed, then each loop as aligned is read for held cells and filled at the end (`--fill-held auto`): a frame the resampling took twice is made again between the cells beside it; `--fill-held off` delivers the loops as they come out of the alignment || `video-loop --out-fps` (new) | None | RIFE's frames between, never a frame shown again |-| `scene-render` at a scene rate above an asset's | A cell of the asset shown over several scene frames | Unchanged: give the asset at the scene's rate (`--out-fps`) |-| `video-stop --fps` | The rate of the frames given, not an output rate | Unchanged |+| `scene-render` at a scene rate above an asset's | A cell of the asset shown over several scene frames | A layer whose asset is a cut of a filmed clip (a `video-loop` or `video-stop` strip, its sidecar names `source_cut`) is given at the scene's times by default (`--fill-held auto`): 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; 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, and strips at 25, 20, 30, 12 and 48 fps render byte for byte as before; a layer that is not a cut of a filmed clip (a still, an atlas row, a pixel drawing) holds its cells as drawn; `--fill-held off` gives every layer's cells as its timing picks them |+| `video-stop --fps` | The rate of the frames given, not an output rate | Unchanged; a stalled stop's held cells are made again by default (`video-stop --fill-held auto`) |+| `video-cycle-align --out-fps F` | None (new) | 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; `out_fps` and `source_fps` in the strip metadata; 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 |+| `video-set --out-fps` with an aligned set | Refused | The aligned walks and runs are given it once aligned (`video-cycle-align --out-fps`), the rest by `video-loop --out-fps` |### What it takes from sprite-gen@@ -3497,6 +3517,10 @@ Where sprite-gen gives frames at a higher rate than it was given them:| Whether a frame made shows a picture of its own (`same_picture`, the fault `held`) | `same_steps`, the reading above, on each pair | || A part standing still (`still_kept`) | New | `rife.hole` reads a hole through a limb, `inspect-motion` a foot's place in spans a person marks; neither reads whether an in-between keeps what both its frames hold still. || The times of a higher rate (`times`, `upsample`) | New | `align.resample` resamples a loop as a ring to a length; a cut played once runs from its first frame to its last. |+| The wrap reading (`held_fill.wrap_same`) | New | The step reading reads neighbours within the cut, so it cannot see a cut one cell too long. The wrap step pairs the last cell with the first, and only a reading of that pair, on the cut's frames as filmed, sees the last cell showing the first cell's picture. |+| Cutting again (`cut_args`, `loop.cut_again`) | The cut's own arguments, recorded in the loop report | The same frames cut again with those arguments and the changes given (for example `fill_held="off"`), with no provider call, give the alignment its cut as filmed and `video-set` its unaligned item filled. It refuses a report from before `cut_args` was recorded, and frames that moved. |+| The holds list (`held_fill.intended`, `held_fill.strip_holds`) | New | The runs kept as the motion means it (`keep` on each, the kinds in `held_fill.KEEPS`) are one list in the strip's cells, `{from, to, kind, reason}`, the same list form a renderer's hold list uses, so `inspect-holds` and `scene-render` read a hold meant straight from the strip. |+| The alignment's end fill | `held_fill.fill`, the fill itself | Not its own: a loop as aligned is filled as `video-loop` fills a loop, with the same keeps and the same judge (the `held` fault among the others), so the alignment's `held_fill` and `holds` read as a loop's do. |## Relateddiff --git a/docs/scene.md b/docs/scene.mdindex 414ec3b..2fdde9d 100644--- a/docs/scene.md+++ b/docs/scene.md@@ -101,6 +101,8 @@ The output directory is dedicated to one render and must be empty. Rendering and`--fill-held auto` (the default) gives a layer cut from a filmed clip at the scene's times where it would show a cell again ([Cells at the scene's times](#cells-at-the-scenes-times)); `--fill-held off` gives every layer's cells as its timing picks them. `scene-inspect` takes the same flag and measures what that render would show. What was not made — no RIFE, a frame refused, `--fill-held off` — is printed as `scene-render: warning:` lines once the render is published.+`--between-cache DIR` keeps the frames made between cells across renders, in `DIR`, and takes them from there on the next render. A frame is kept under the bytes of its two cells, the time, and the RIFE that made it (its identity: the model, the binary or backend, the engine code and the machine). Another cell, time, RIFE or machine is another key, so a frame kept for other inputs is never taken. It is the same cache `video-cycle-align --between-cache` uses (`rife.Cache`). The report's `between_cache` gives the directory and four counts: `hits` (frames taken), `misses` (frames made), `unreadable` and `not_kept`. The key is written only when the flag is given. Without the flag nothing is kept, and each frame between two cells at one fraction is made once a render. An interpolator handed in from Python that names no identity is refused with `--between-cache`. `DIR` belongs to the caller: nothing removes it.+GIF defaults preserve the scene frame rate, use 256 colours without dithering (for flat pixel-art colours), and cap width at 640 pixels. `--gif-width`, `--gif-fps`, `--gif-colors` and `--gif-dither` make those choices explicit; `sierra2_4a` can preserve gradual tones in painted scenery. GIF fps cannot exceed scene fps; more samples require rendering the scene itself at a higher rate. `--gif-max-bytes` defaults to 8,000,000: an oversized result fails and asks for an explicit budget or quality change. The encoder never silently lowers frame rate, resolution or colours.```bashdiff --git a/docs/video-pipeline.md b/docs/video-pipeline.mdindex f170339..52694ce 100644--- a/docs/video-pipeline.md+++ b/docs/video-pipeline.md@@ -430,19 +430,7 @@ them fails rather than being written.See [loop review](loop-review.md)for the visual review contract and manual overrides.-**Held cells: found, filled, read again: the default step of every cut.** A cut whose neighbour cells show the same-picture (a frame shown twice or three times: a model that stalls, a rate carried to another by repeating frames)-stops on it as it plays. `video-loop` reads each cut it makes for them (loop, one-shot, once, once-return, so every-cut of `video-set` and of a clip from `video`) and by default makes each run of them again with RIFE's frames between-the pose before and the pose after (`--fill-held auto`), the cut's length, beat, first and last cells and wrap kept,-a part standing still in both kept still; a run longer than three cells, the ends of a cut played once, a loop's last-cells and a cut drawn on twos or threes (limited animation, `held_fill.drawn`) stay as filmed, and so does a run no-frame between is taken for (a fault, or a frame that shows the picture beside it again), named in a warning. Then it-reads the cut again. The report and the strip metadata record the held runs (first cell, how many) and the poses over-the cells (`held_fill`); tell the person that one line: `poses/cells`, e.g. `24/27` before and `27/27` after. With no-RIFE the cells are delivered as filmed and a warning names the motion and the install line; `--fill-held off` cuts as-before. A cut asked for above its clip's rate (`--out-fps 60` on a 24 fps clip) is made of frames between, never-frames shown again ([loop repair](loop-repair.md) section 7).+**Held cells: found, filled, repaired, read again: the default step of every cut.** A cut whose neighbour cells show the same picture (a frame shown twice or three times: a model that stalls, a rate carried to another by repeating frames) stops on it as it plays. `video-loop` reads each cut it makes for them (loop, one-shot, once, once-return, so every cut of `video-set` and of a clip from `video`) and by default makes each run of them again with RIFE's frames between the pose before and the pose after (`--fill-held auto`), the cut's length, beat and first cell kept, a part standing still in both kept still. A loop is read as a ring: a run that ends on its last cell is made again toward its first cell, and a last cell that shows the first cell's picture (a cut one cell too long) is made again too, the first cell never changed. A run longer than three cells, a run joined across the wrap longer than three cells, the ends of a cut played once and a cut drawn on twos or threes (limited animation, `held_fill.drawn`) stay as filmed, and so does a run no frame between is taken for (a fault, or a frame that shows the picture beside it again), named in a warning; a hold the motion means is listed in the strip's `holds` (`{from, to, kind, reason}`). Then the repairs run and the cut is read again for a run they left, made again the same way (`held_fill.again`). The report and the strip metadata record the held runs (first cell, how many, `keep` on a kept one) and the poses over the cells (`held_fill`); tell the person that one line: `poses/cells`, e.g. `24/27` before and `27/27` after. With no RIFE the cells are delivered as filmed and a warning names the motion and the install line; `--fill-held off` cuts as before, with no read again. The walks and runs a set aligns (`video-set --align-cycles auto`, `video-cycle-align`) are cut as filmed, aligned from frames as filmed, and filled at the end, each loop as aligned read and filled as `video-loop` fills a loop, the cut as filmed kept as `cycle.source/`. A cut asked for above its clip's rate (`--out-fps 60` on a 24 fps clip; `video-cycle-align --out-fps` for an aligned set) is made of frames between, never frames shown again ([loop repair](loop-repair.md) section 7).**The fundamental period: recorded, never cut on the pixels' word.** A motion that repeats everyP frames repeats every 2P as well, and 2P can be the better repeat: a clip drawn on twos (a new