editorbrain 0.28.2 → 0.30.0

package/skill/editorbrain-motion/references/motion-craft.md

@@ -0,0 +1,79 @@
+# Motion craft
+
+Read when designing, adapting or reviewing an animated scene with any method. These starting values come from EditorBrain's own code-drawn library scenes and a few reference analyses, not yet validated on customer projects or phones; sound was checked only as data. They are judgment, not a template, effects checklist or quality score. The user's current request, effective media/audio preferences (including reduced or disabled motion and on-screen text density), the output profile, the selected style's `effects.md`, the approved direction, brand tokens and readability measured in this output override every number; a value outside a range is a reason to look, not an automatic defect.
+
+Pixels are per 1080 px short side at 30 fps; scale with resolution and halve per-frame values at 60 fps. Drift is the scale or position change over a hold, as a percentage of the frame.
+
+## Intent before look
+
+State four lines per meaningful shot before choosing a component, effect or palette:
+
+1. **Understand:** the sentence the viewer must get, with its real numbers.
+2. **Action:** the visible action that demonstrates it, such as an object performing the comparison.
+3. **Consequence:** what visibly changes because of it, in the same shot.
+4. **Exit:** the final state and what carries into the next shot.
+
+They sharpen the intention and action of the motion skill's shot description (entry, hold and exit still apply) and fit the [code motion](code-motion.md) record; they are not a schema. If the viewer would understand the sentence equally without the action, reconsider whether the motion is decoration and restage.
+
+Explanatory mechanism comes before surface treatment (palette, texture, glow); the selected style's own mechanisms still apply. For code/compositing, derive geometry, counters, labels, camera targets and cues from one data model ([code motion](code-motion.md) covers deterministic time) and recompute every figure. When a beat reads weak, change travel, scale, composition or timing before adding effects.
+
+**Honest data.** The data must demonstrate the claim (a difference of about 10 % or more, a threshold actually crossed) or the payoff changes; keep the before state credible. Map quantity to the visible dimension (area by √value), compare on one scale, clock and cost basis, and declare exaggerated or non-linear scales on screen. Leaders end at measured endpoints, emphasis follows the message target rather than the maximum, and data-dependent wording follows the computed values.
+
+## Starting values
+
+**Easing and springs.** No linear spatial motion: ease-out for entrances, in-out and arcs for travel; interpolate data values monotonically. Start springs from rest: no jump after a standstill (one fix capped that first step near 30 px) and no frame stepping several times its neighbors. A damping ratio ζ ≈ 0.8 gives about 1.5 % overshoot (convert to the engine's stiffness/damping/mass) over a 0.22–0.26 s main travel; large elements overshoot 2 % at most, and springs settle within their beat. Anticipate major moves with a 1–8 % counter-move (15–20 % for large rotations). Reveals take 0.18–0.45 s with a strong ease-out; related elements stagger 2–4 frames, secondary parts follow through 2–4 frames late, and edges on separate springs stretch and catch up. Squash only the hero, by 2 % at most. Large elements stay well under about 140 px per frame; above about 100 px per frame add directional blur (ghosts only on small objects, never over text). For exact endpoints, see [targeted motion review](../../editorbrain/references/motion-review.md).
+
+**Staging and holds.** One primary move and focal point at a time; dim the rest 40–60 % and start the next move at 80–90 % settled. Hold 0.4–0.8 s after intermediate payoffs and 1.5–2.5 s at the end of a standalone piece or before a hard end (under 1.2 s is a warning); a shot that hands off, or an insert under continuing voice, keeps its readable hold and designs its exit. Outside planned holds, over about 1 s with no readable change and nothing else carrying the beat (narration, action) is a dead-air candidate; keep holds alive with 0.5–2 % drift, never above 3 %, unless motion is reduced or disabled. Nothing appears, disappears or swaps for one unintended frame; deliberate cuts, stepped motion and reduced-motion states are exempt. Switch layers on time, never on a spring threshold. Keep full-frame flashes to three per second or fewer, timed in seconds; a count does not certify photosensitivity safety.
+
+**First and last frames.** Shots enter already in motion unless stillness is the design or motion is reduced. When the first frame may be seen alone (autoplay, preview, thumbnail), compose it with subject and title present. Do not reserve visible holes; bring later content in from an on-screen object or a motivated pull-back, and show an empty container only when its emptiness is the information (about 0.25–0.3 s). When a piece or beat closes, end on a designed state: scaffolding gone, deformations eased back.
+
+**Payoff.** Design a separate end-state layout, not the first layout minus elements: the answer at least as large as the setup figure, about twice its neighbors and legible at rest without a push. During action keep the protagonist near 25 % of frame height in 16:9 and 30–40 % in narrower ratios. A measuring gesture landing on the computed value makes a strong payoff; craft must not delay or shrink the answer.
+
+**Object-driven transitions.** Keep one protagonist and change its function: a row becomes a ticket, a total a stamp. Leave states accelerating: content out, container moves and settles, content in. Move the same object between layouts rather than fading one out and another in; replace busy crossfades and hue tweens with a wipe, mask or occluder starting at the cause. Causes precede effects: objects lead their labels, counters change when a visible carrier lands, a source shows the gap left behind, and a state a transition introduces persists until another removes it.
+
+**Camera.** Without style direction, push in on one subject and pull back to show the system; avoid moves that only add energy. Interpolate zoom in log space. Emphasis pushes start around 1.4–4.5 % and follows around 1.3–1.75×, lower in 9:16; if cropping would force a push below about 1.15×, dim the rest or scale the focal element instead. Pans stay under about 25 px per frame with continuous velocity and finish 0.15 s before cuts. At every hold, each label and title is wholly inside the safe margin or wholly off-frame; text that must not crop lives in screen space and crosses the frame edge only while moving. Start a beat once its element is framed.
+
+**Type as objects.** Unless the type is the action (kinetic type, beat-locked or word-synced words, line or letter mask reveals), move phrases or lines as blocks with one behavior each; text exits before its container moves and returns after it settles. Fit text at its final rendered size and font settings: shrink to the size floor (see Ratios), then two balanced lines, then a short alternate; never truncate a number. Same-role labels share the smallest fitted size, and anything placed or animated from a text block follows its measured line count. Size masks from measured ink with descender and accent room; test g, j, p, y, ¿, ¡, Á, É, Ñ and currency in the actual fonts, and never synthesize italics. Use tabular figures for changing numbers, one locale-aware formatter (no −0, singular and zero forms), no-break spaces before units, no orphaned units, and differences from the rounded values shown; rolling numbers show each value 0.25 s or more.
+
+**Text over imagery and color.** Choose the text color among the resolved brand text roles by measured contrast with the actual backdrop; if no permitted role passes, treat it as a project decision (see [component library](component-library.md)), never silent recoloring. Over footage or busy texture, small text gets a scrim, veil or knockout band, and HUD readouts or values in flight an opaque plate; a translucent plate must not show text behind it. Key text ends at 4.5:1 or more. Temporary dims, veils and ghosts exit before the hold; one accent per meaning. Derive shadows, highlights and flashes from the palette's luminance rather than fixed values.
+
+**Labels and drawn objects.** Place labels, stamps and resting props against everything printed (text, credit, HUD, moving props and their rest poses) at every beat and ratio. Anchor stamps to the object's drawn bounds, not a data level; no decorative impact covers primary text; leaders never cross text. Overlaps happen only in motion, for about 0.4 s or less. Name each hero object from a small grayscale still at its smallest size and ask what else it could be; give it defining cues (edge, binding, cap, sheen), one light direction and highlights that add light rather than desaturate; textures move with their object, and decorative strokes never look like data marks.
+
+**Copy and density.** About 3–4 words per beat, a new idea every 1.5–2 s, and each text fully visible 0.6 s plus 0.25 s per word beyond three; lengthen the shot, or cut copy when timing is locked to voice, rather than compress reading. These figures apply to graphic copy, not word-synced captions, and `onScreenText` sets the density. Leave 0.35 s between text events, let the outgoing line leave before the next enters, and give the last item of each sequence 0.4 s clean before a transition covers it. Individually read events need about 0.3 s each; when faster, or beyond about eight labeled items (about 35 anonymous tokens), show two or three slowly, then an aggregate. Text below the size floor is texture and carries no message. Scroll-first formats may need the answer within 1–2 s unless the brief's hook deliberately withholds it.
+
+**Sound-first timing.** When narration exists, lock it first (see [audio production](../../editorbrain/references/audio-production.md)) and anchor events to it; voice-synced text lands 0–5 frames after the word, never before (one measured reel). With SFX or music, derive cues from the motion's event list; for rhythmic or physical scenes without locked narration, a beat grid can lead, without every cut on a beat. Align each sample's measured peak or attack, not its file start: impacts on contact, whooshes at peak velocity, chimes and swells on the settle or resolve. Cluster trains above about 6–8 cues per second; gain follows magnitude. Respect exclusions; every SFX needs a visible cause, the scene must read muted, and aligned data still needs listening.
+
+**Ratios.** Recompose graphic layers per ratio from one model with identical beat times instead of cropping another ratio's render; reframing footage or cropping an asset inside the layout is fine. In 9:16, transpose the main axis rather than shrink; no band over about 15–20 % of the height stays empty beyond about 1 s. Carry moves under about 40 px in secondary cues (lean, tension, counters); a protagonist leaving a system travels about a third of the frame height. No hero state is a sliver beyond about 0.5 s, text never rotates 90° to fit, key actions stay in frame, and narrow ratios get gentler camera moves. The size floor is a font size at final on-screen scale of about 20 px in 16:9 and 1:1 and 22 px in 9:16 and other portrait ratios: a floor, not a target, confirmed at delivery size. Take platform UI zones from the output profile or destination.
+
+## Failure modes
+
+| Failure | Detect with |
+|---|---|
+| Text overflows, wraps badly or sibling sizes differ | Longest copy and maximum counts in every ratio |
+| Numbers contradict each other, the copy or the claim | Recompute derived figures and differences from visible operands |
+| Narrow ratios inherit the wide layout | Empty bands and margins on mid and last frames |
+| Labels, stamps or props land on text | Stills at every beat and rest pose in each ratio |
+| Moving values or labels cross text | Dense 10–30 fps strips over each flight |
+| Camera crops text at a hold | Label boxes against the safe margin at every hold |
+| Empty opening or unfinished ending | First and last frames alone at thumbnail size |
+| Rushed events or one-frame pops | Shortest event interval; frame-exact grids at state changes |
+| Dead air | Freeze scan, e.g. ffmpeg `freezedetect`, against planned holds |
+| Under-weighted payoff or misread object | One dominant element in the last seconds; grayscale silhouette at phone size |
+| Unmotivated effects | Glow, particles, blur-in or stock dashboard card without a cause |
+| Sound drifting from picture | Retime one event, compare cue and event frames, listen |
+| File size balloons | Size after the first render; unsettled motion tails, per-frame grain |
+
+Those effects are fine when the style, the user or a fitting component calls for them.
+
+## Self-review order
+
+1. Four lines, recomputed numbers, density arithmetic (count × interval fits the beat).
+2. Stills at every beat and mid-transition in each ratio, narrowest first, with zoomed crops of the smallest text.
+3. For parameterized or reused scenes, stress inputs: longest copy, extreme counts, descenders and accents, each applicable brand theme.
+4. Numeric checks where claims matter: text boxes, recomputed numbers, out-of-order seeks.
+5. Dense strips around transitions; every frame for events under 0.2 s.
+6. The whole export at delivery size, first and last frames included, listening to any audio.
+7. A fresh-context second pass, or a separate reviewer, on the final export's strips (tiles of 480 px or more, times inside the duration). Edge-cropped text is blocking; fix self-noted legibility or payoff weaknesses before reporting.
+8. Fix the cause (layout rule, data, timing) behind a defect; recheck that interval, the other ratios and the delivered whole.
+
+Record findings in the [code motion](code-motion.md) format and finish with [production and review](../../editorbrain/references/production-and-review.md). Clean engine diagnostics, where available, are necessary but not sufficient; passing checks is not artistic approval, and measured audio is not listened audio.