Videos: an animation drives a sprite's video picture by picture (#404)

- Videos: new section "Following an animation" with Video clock,
  Video time, the two ways of following, sound and the own player per
  sprite.
- Animations: a pointer to it.
- Development: 1999 checks.

Animations.md

@@ -49,7 +49,8 @@ the keys are in time.
 
 **Values.** Numbers and colours blend linearly between keys; a texture, a boolean, a text or a
 choice holds until the next key (that is how a picture sequence works: a `texture` row keyed
-frame by frame). Before the first key a row holds its first value, after the last one its last. A
+frame by frame). A sprite wearing a video keys its **Video time** to show the picture of a moment
+(see [Videos](Videos#following-an-animation)). Before the first key a row holds its first value, after the last one its last. A
 row may be **relative**: its numbers are added to what the target held when the animation
 started, so one walk cycle can bob every enemy where it stands. Rotation blends like any number —
 from 350 to 10 goes backwards over 340°, a full turn is 0 → 360. A row

Development.md

@@ -21,7 +21,7 @@ php tests/php/releases.test.php                               # the release stor
 php tests/php/files.test.php                                  # uploaded files in a folder per account (#344), the same way
 php tests/php/videos.test.php                                 # the video store, its queue and the worker (#402), with the
                                                               #   real ffmpeg: the CI image and game-maker-video have it
-node tools/seed-e2e.mjs && node tools/e2e.mjs                 # 1996 editor checks, screenshots in /tmp/gm-e2e-*.png
+node tools/seed-e2e.mjs && node tools/e2e.mjs                 # 1999 editor checks, screenshots in /tmp/gm-e2e-*.png
 GM_STEPS=20 node tools/e2e.mjs                                # or 1-12, or 6,20 — a subset while working on one step
 ./e2e.sh start [GM_STEPS]                                     # the same run detached, see below
 ./e2e.sh status                                               # live progress, or the last run's result

Videos.md

@@ -77,6 +77,48 @@ take pictures only.
 
 Not yet: nodes to play, pause or jump in a video, or to hear when it ends. That is a follow-up.
 
+## Following an animation
+
+A video that plays by itself runs on its own clock, so an [animation](Animations) cannot say which
+picture shows when. For a cut, the sprite's **Video clock** row says who keeps the time (#404). Both
+rows show only while the Texture is a video or a clip of one.
+
+| Row | |
+|---|---|
+| **Video clock** | **Free** (the default): the video plays by itself, as above. **Driven**: it shows the picture at its Video time |
+| **Video time** | seconds into the clip, shown while the clock is Driven. A number like any other, so an animation keys it |
+
+What the keys on Video time do:
+
+| Keys | Result |
+|---|---|
+| frame 0 at 0 s, frame 300 at 10 s (at 30 fps), linear | plays normally, in step with the animation |
+| two keys with the same value, or `step` | a still |
+| a flatter or a steeper line | slow motion or fast motion |
+| an easing or a curve | ramps |
+
+Past the end of its clip the time goes round with Loop and holds the last picture without; before
+0 it shows the first one. A cut is then: clip A and clip B each on a sprite, **Enabled** keyed to
+switch between them, Video time keyed on each, texts above, transitions over Alpha, Color or a
+shader's parameters. Or one sprite whose Texture is keyed from clip to clip.
+
+- **Each driven sprite has a player of its own**, per view: two sprites with the same clip can show
+  it at different times.
+- **The Scene tab and the inspector's PREVIEW** show the still at the sprite's Video time.
+- **The Animations tab** follows the playhead: scrubbing shows the picture of that moment, Play
+  plays the video along, heard while it runs at about 1x so a cut can be timed by its sound.
+- **In a game** `Play animation` sets Video time like any other row, and so can a behavior. A
+  paused game holds the time, so the video stands too.
+- **How it keeps up:** while the time runs forward at 0.25x to 4x the video plays at that speed and
+  is nudged by a few percent, and only seeks when it is more than 0.25 s off. A time that stands,
+  jumps or runs back holds the video and seeks; while a seek runs, only the newest one waits.
+  Seeking every frame would be too slow, a seek decodes from the last keyframe, up to 14 pictures.
+- **Heard** only at about 1x (0.9x to 1.1x); a still, scrubbing, slow and fast motion are quiet.
+- **Exact while it runs live in the browser**, as far as Chrome keeps up: a picture that comes too
+  late leaves the one before it on screen. Exporting a cut as a video file is #405.
+- A driven sprite switched off for more than 2 s loses its player, like any video nothing shows. On
+  again, it seeks to its time and shows nothing until that picture is there.
+
 ## The worker
 
 Converting is a job, not a request. The API puts the upload into `data/videos/queue/` (hidden