Skip to content

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

docs(face): the live player's one queue — requests in the order made, a request's sound loading while it waits, the one line after a clip with its own mouth planned with the clip, no length limit and nothing dropped (a failed request rejects and the next goes on); CHANGELOG v3.1.0 bullet and Tests line

Soohong Kimb5c8a2ec296e
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 70b2490..fbf48b4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,9 +17,10 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the
- Talking frames are assigned to smile or neutral sets by closed-mouth lift. Entry chooses a matching set and rest.
- The player `sprite-gen-face-v1.mjs` contains the voice flap, face pick, scene plan, and live canvas playback rules.
- A clip's own mouth and sound finish before a requested line starts. The voice and layer then wait together for the first frame whose switch to the chosen rest is within the 1.4 jump line. Layer exit also uses that jump line.
+- The live player keeps one queue of every `play` and `say` request, in the order the calls are made, and starts each request on the frame after the one before it has ended, so two voices never overlap. A line placed right after a clip with its own mouth is planned together with that clip, the plan `planScene` makes and `face-bake --play` bakes, and its voice and layer start at the plan's `line_start` after the own-mouth span. The queue has no length limit and drops nothing: a request whose sound does not load or decode, or whose line `planScene` refuses, rejects its promise when its turn comes, and the next request goes on.
- Bakes check pack digests, changed pixels outside the weight, and composite jumps. Refused bakes retain their frames for inspection.
- See [docs/face-parts.md](docs/face-parts.md) for the request, pack, player, commands, and limits.
-- **Tests**: `tests/video/test_face_layer.py` uses `tests/talking_face.py` to check smile and neutral sets; clip entry set and rest; own-mouth timelines, including a close during voiced sound and refusal of a missing or never-closing timeline; a head 60 px from its place and tilted 3 degrees; hand, headset boom, and choker keeps; a tongue in the body's own open mouth, joined to a hand by a finger at its corner, covered by the layer; unchanged pixels outside the weight; synthetic cells keeping the key's colour under no coverage; digests and new-folder pack writes; the player flap against its original numpy rule and the pick against the draft Viterbi over every frame; a line waiting for a clip's own mouth and for a frame its layer can come on at; loop and post-greeting bakes with greeting frames unchanged byte for byte; and refusal of a changed pack.
+- **Tests**: `tests/video/test_face_layer.py` uses `tests/talking_face.py` to check smile and neutral sets; clip entry set and rest; own-mouth timelines, including a close during voiced sound and refusal of a missing or never-closing timeline; a head 60 px from its place and tilted 3 degrees; hand, headset boom, and choker keeps; a tongue in the body's own open mouth, joined to a hand by a finger at its corner, covered by the layer; unchanged pixels outside the weight; synthetic cells keeping the key's colour under no coverage; digests and new-folder pack writes; the player flap against its original numpy rule and the pick against the draft Viterbi over every frame; a line waiting for a clip's own mouth and for a frame its layer can come on at; the live player run by node on a fake audio clock, with two lines requested during a greeting's own mouth, three lines requested on the loop, one line requested during the own mouth and one after it, a line whose voice loads late, a line requested right after a clip whose sound loads late, and a request that fails; loop and post-greeting bakes with greeting frames unchanged byte for byte; and refusal of a changed pack.
## v3.0.0 - Remove rig layer composition
diff --git a/docs/face-parts.md b/docs/face-parts.md
index e2a8f8d..63159df 100644
--- a/docs/face-parts.md
+++ b/docs/face-parts.md
@@ -198,7 +198,11 @@ The body at the end of that span names the line's set and rest. The voice and la
### Live
-The audio context supplies one frame clock. `play(name)` starts a body clip and its own sound. `say(voice)` decodes the voice, computes levels, and plays it at the plan's `line_start` with the layer. Requests run one after another. A line requested during a clip's own mouth is planned after that span.
+The audio context supplies one frame clock. `play(name)` starts a body clip and its own sound. `say(voice)` decodes the voice, computes levels, and plays it at the plan's `line_start` with the layer. The player keeps one queue of every `play` and `say` request, in the order the calls are made. As soon as a request is made, its sound starts to load and decode while the request waits: the clip's own sound for `play`, the voice for `say`. A request whose sound arrives late keeps its place in the queue.
+
+A request starts on the frame after the request before it has ended. A line ends when all of its frames have shown, and its voice has ended by then. So two voices never overlap, and a line never replaces another line's plan. There is one exception. A line placed right after a clip with its own mouth is planned together with that clip, the way `planScene` plans a clip and a line. This is the same plan that `face-bake --play` bakes. The line's voice and layer start at the plan's `line_start`, after the own-mouth span. The clip's scene then ends with the line. The exception needs the line's voice to be decoded before the clip's own-mouth span ends. It also applies when the line was requested just after `play`, before the clip started. If the voice is decoded only after the span has ended, the line waits for the clip to end, like any other request. Only the first line after such a clip joins it. A line requested after that waits until the first line has ended.
+
+Each call returns a promise that resolves when its scene ends. When a line joins a clip, both promises resolve together. The queue has no length limit and drops nothing. A request whose sound does not load or decode, or whose line `planScene` refuses, rejects its promise when its turn comes. The next request then goes on.
After a line, the layer stays at its rest until a loop frame can switch off within the jump line. Body cells load when first drawn. Each frame draws the body cell, then the sprite using the cell anchor times the sprite map as a canvas transform, then the keep image. These are plain source-over draws. Sprite colour is already matched in the pack, so live drawing does no colour step.