Cartoon: rig, movimento e lip sync dos personagens

- cartoon/src/rig.ts, motion.ts e lipsync.ts: esqueleto do personagem,
  curvas de movimento e sincronia labial no estilo Cartoon (Remotion)
- CharacterFigure/CharacterCard/Shot/overlays e spec atualizados
- Painel: estúdio de personagens e montagem cartoon ajustados
- Documentação em doc/cartoon/animacao.md e personagens.md; skill atualizada

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-17 23:39:12 -03:00
co-authored by Claude Opus 5.5
parent 0050cf60a7
commit 3f600c55b1
25 changed files with 1418 additions and 215 deletions
+216
View File
@@ -0,0 +1,216 @@
// Movimento do personagem: uma LINHA DO TEMPO de ações que se combinam (não animações prontas). Cada ação tem
// início (segundos `at`, fração do trecho `atP` ou a palavra da narração `cue`) e duração; o estado em cada
// quadro sai de aplicar as ações em ordem sobre a expressão/pose de base, mais a "vida" (piscar, respirar).
// Ações permanentes mudam o estado dali em diante (express, pose, walk, sit, fall, turn, look); as momentâneas
// voltam ao fim (nod, shake_head, tremble, bounce, wave, jump, talk, emote).
import { emphasisAt, speak, visemeAt, type SpokenWord } from "./lipsync";
import { blendBody, blendFace, bodyOf, faceOf, withBody, withFace, type BodyParams, type BodyPatch, type FaceParams, type FacePatch } from "./rig";
export const ACTIONS = ["express", "pose", "walk", "run", "enter", "exit", "jump", "nod", "shake_head", "tremble", "bounce", "fall",
"sit", "stand_up", "turn", "talk", "look", "emote", "wave"] as const;
export type ActionKind = (typeof ACTIONS)[number];
export type Action = {
do: ActionKind;
/** Início: segundos, fração do trecho (0–1) ou a 1ª palavra da narração que começa com `cue`. */
at?: number; atP?: number; cue?: string;
dur?: number;
/** talk: termina no fim desta palavra da narração (a fala vai de `cue` até `cueEnd`). */
cueEnd?: string;
expression?: string; face?: FacePatch;
pose?: string; body?: BodyPatch;
/** walk/run/enter: x de destino (fração). */
to?: number;
/** look: para onde; fall: para que lado. */
dir?: "left" | "right" | "up" | "down";
/** nod/shake_head/bounce/wave: repetições. jump: altura (fração da altura do quadro). */
times?: number; height?: number;
/** emote: símbolo sobre a cabeça ("!", "?", "…", "♥", "zzz", "💢"). talk: o texto falado (sem tempos de palavra, é
* repartido pela duração). */
text?: string;
};
export type ActorInput = {
x: number; expression?: string; pose?: string; face?: FacePatch; body?: BodyPatch; flip?: boolean; timeline?: Action[];
};
export type ActorState = {
face: FaceParams; body: BodyParams;
x: number; dy: number; dx: number; rot: number; sx: number; sy: number; flip: boolean;
emote: { text: string; k: number } | null;
};
const DEFAULT_DUR: Record<ActionKind, number> = {
express: 0.25, pose: 0.35, walk: 1.6, run: 0.9, enter: 1.2, exit: 1.2, jump: 0.8, nod: 0.7, shake_head: 0.8, tremble: 1, bounce: 0.8,
fall: 0.6, sit: 0.5, stand_up: 0.5, turn: 0.3, talk: 1.5, look: 0.3, emote: 1.2, wave: 1.2,
};
const clamp01 = (v: number) => Math.max(0, Math.min(1, v));
const ease = (p: number) => (p < 0.5 ? 2 * p * p : 1 - (-2 * p + 2) ** 2 / 2);
/** Passa um pouco do alvo e volta (dá vida às poses). */
const easeBack = (p: number) => { const c = 1.4; return 1 + (c + 1) * (p - 1) ** 3 + c * (p - 1) ** 2; };
const norm = (s: string) => s.normalize("NFD").replace(/[̀-ͯ]/g, "").toLowerCase().replace(/[^a-z0-9]/g, "");
/** Início da ação em segundos (cue = palavra falada; sem a palavra, cai para atP/at/0). */
export function startOf(a: Action, durationS: number, words: { text: string; startS: number }[] = []): number {
if (a.cue) {
const c = norm(a.cue);
const w = words.find((x) => norm(x.text).startsWith(c));
if (w) return w.startS;
}
if (a.atP !== undefined) return a.atP * durationS;
return a.at ?? 0;
}
/** Piscar em intervalos variados (2,4–4,6 s), determinístico pela semente. */
function blinkAt(t: number, seed: number): number {
let s = 0.6 + (seed % 7) * 0.13;
let k = 1;
while (s < t + 0.2) {
const d = t - s;
if (d >= 0 && d < 0.13) k = Math.min(k, Math.abs(d - 0.065) / 0.065);
s += 2.4 + ((Math.sin(s * 12.9898 + seed) + 1) / 2) * 2.2;
}
return k;
}
/** Fala do trecho: palavras com tempo (narração) e, se houver, o volume do áudio quadro a quadro. */
export type Speech = { words: SpokenWord[]; env?: { values: number[]; fps: number } };
/** Fim da fala: o fim da palavra `cueEnd` (depois do início), senão início + dur. */
function endOf(a: Action, s: number, words: SpokenWord[]): number | null {
if (!a.cueEnd) return null;
const c = norm(a.cueEnd);
const w = words.find((x) => x.startS >= s - 0.01 && norm(x.text).startsWith(c));
return w ? w.endS : null;
}
export function evaluate(actor: ActorInput, t: number, durationS: number, seed = 1, speech: Speech = { words: [] }): ActorState {
const words = speech.words;
const st: ActorState = {
face: faceOf(actor.expression, actor.face), body: bodyOf(actor.pose, actor.body),
x: actor.x, dy: 0, dx: 0, rot: 0, sx: 1, sy: 1, flip: !!actor.flip, emote: null,
};
const timeline = (actor.timeline ?? []).map((a) => ({ a, s: startOf(a, durationS, words) })).sort((p, q) => p.s - q.s);
for (const { a, s } of timeline) {
if (t < s) break;
const end = a.do === "talk" ? endOf(a, s, words) : null;
const d = Math.max(0.05, end !== null ? end - s : a.dur ?? DEFAULT_DUR[a.do]);
const p = clamp01((t - s) / d);
const active = t - s < d;
const env = active ? Math.min(1, (t - s) / 0.15, (s + d - t) / 0.15) : 0; // entra e sai suave (momentâneas)
switch (a.do) {
case "express": {
const target = a.expression ? faceOf(a.expression, a.face) : withFace(st.face, a.face);
st.face = blendFace(st.face, target, ease(p));
break;
}
case "pose": {
const target = a.pose ? bodyOf(a.pose, a.body) : withBody(st.body, a.body);
st.body = blendBody(st.body, target, clamp01(easeBack(p)));
break;
}
case "walk": case "run": case "enter": case "exit": {
const from = a.do === "enter" ? (a.to ?? st.x) < 0.5 ? -0.25 : 1.25 : st.x;
const to = a.do === "exit" ? (st.x < 0.5 ? -0.3 : 1.3) : a.to ?? st.x;
const run = a.do === "run";
st.x = from + (to - from) * (run ? p : ease(p));
if (to !== from) st.flip = to < from;
if (active) {
const phase = (t - s) * Math.PI * 2 * (run ? 3.2 : 2.1);
const amp = run ? 1.6 : 1;
const sw = Math.sin(phase);
st.body = withBody(st.body, {
armL: { raise: 8 + sw * 20 * amp, bend: run ? 85 : 15 }, armR: { raise: 8 - sw * 20 * amp, bend: run ? 85 : 15 },
legL: { raise: 3 + Math.max(0, sw) * 6, bend: Math.max(0, sw) * 38 * amp }, legR: { raise: 3 + Math.max(0, -sw) * 6, bend: Math.max(0, -sw) * 38 * amp },
lean: (to < from ? -1 : 1) * (run ? 8 : 3),
});
st.dy -= Math.abs(Math.sin(phase)) * (run ? 0.012 : 0.006);
}
break;
}
case "jump": {
if (!active) break;
const h = a.height ?? 0.08;
if (p < 0.15) { st.sy *= 1 - 0.1 * (p / 0.15); st.sx *= 1 + 0.06 * (p / 0.15); st.body = withBody(st.body, { crouch: 0.35 * (p / 0.15) }); }
else if (p < 0.85) {
const q = (p - 0.15) / 0.7;
st.dy -= h * 4 * q * (1 - q);
st.sy *= 1.07; st.sx *= 0.95;
st.body = withBody(st.body, { arms: { raise: 120, bend: -10 }, legs: { raise: 6, bend: 30 } });
} else { const q = (p - 0.85) / 0.15; st.sy *= 1 - 0.08 * (1 - q); st.sx *= 1 + 0.05 * (1 - q); }
break;
}
case "nod": st.body = withBody(st.body, { headNod: st.body.headNod + Math.sin(p * Math.PI * 2 * (a.times ?? 2)) * 0.6 * env }); break;
case "shake_head": st.body = withBody(st.body, { headTurn: st.body.headTurn + Math.sin(p * Math.PI * 2 * (a.times ?? 2)) * 0.7 * env }); break;
case "tremble": if (active) { st.dx += Math.sin(t * 77.7) * 0.004 * env; st.dy += Math.cos(t * 91.3) * 0.002 * env; } break;
case "bounce": st.dy -= Math.abs(Math.sin(p * Math.PI * (a.times ?? 2))) * 0.02 * env; break;
case "fall": {
const side = a.dir === "right" ? 1 : -1;
st.rot = side * 88 * ease(p);
st.dy += 0.02 * ease(p);
st.face = blendFace(st.face, faceOf("shocked"), Math.min(1, p * 3));
break;
}
case "sit": st.body = blendBody(st.body, withBody(st.body, { crouch: 1, arms: { raise: 14, bend: 40 } }), ease(p)); break;
case "stand_up": st.body = blendBody(st.body, withBody(st.body, { crouch: 0 }), ease(p)); break;
case "turn": {
const flipped = !st.flip;
if (p >= 0.5) st.flip = flipped;
if (active) st.sx *= Math.max(0.15, Math.abs(Math.cos(p * Math.PI)));
break;
}
case "talk": {
if (!active) break;
// Palavras da narração dentro da fala; sem elas, o texto da ação repartido pela duração (vogal pesa mais).
let spoken = words.filter((w) => w.endS > s && w.startS < s + d);
if (!spoken.length && a.text) {
const list = a.text.split(/\s+/).filter(Boolean);
const total = list.reduce((n, w) => n + w.length + 1, 0);
let c = s;
spoken = list.map((w) => { const len = (d * (w.length + 1)) / total; const out = { text: w, startS: c, endS: c + len * 0.88 }; c += len; return out; });
}
if (spoken.length) {
st.face = speak(st.face, visemeAt(spoken, t, speech.env), Math.min(1, (t - s) / 0.08, (s + d - t) / 0.08 + 0.2), emphasisAt(t, speech.env));
} else {
const flap = Math.abs(Math.sin((t - s) * Math.PI * 2 * 4.3 + seed)) * (0.6 + 0.4 * Math.sin((t - s) * 9.1 + seed));
st.face = { ...st.face, mouthOpen: Math.max(st.face.mouthOpen, (0.12 + 0.5 * flap) * env), teeth: st.face.teeth || flap > 0.6 };
}
// Quem fala mexe a cabeça de leve e acompanha as sílabas fortes.
st.body = withBody(st.body, { headTilt: st.body.headTilt + Math.sin((t - s) * 5.3) * 2 * env, headNod: st.body.headNod + emphasisAt(t, speech.env) * 0.25 });
break;
}
case "look": {
const gx = a.dir === "left" ? -0.9 : a.dir === "right" ? 0.9 : 0;
const gy = a.dir === "up" ? -0.8 : a.dir === "down" ? 0.8 : 0;
const k = ease(p);
st.face = { ...st.face, gazeX: st.face.gazeX + (gx - st.face.gazeX) * k, gazeY: st.face.gazeY + (gy - st.face.gazeY) * k };
st.body = withBody(st.body, { headTurn: st.body.headTurn + (gx * 0.5 - st.body.headTurn) * k, headNod: st.body.headNod + (gy * -0.4 - st.body.headNod) * k });
break;
}
case "emote": if (active) st.emote = { text: a.text ?? "!", k: env }; break;
case "wave": if (active) st.body = withBody(st.body, { armR: { raise: 140 * Math.min(1, env * 1.5), bend: -25 + Math.sin(p * Math.PI * 2 * (a.times ?? 3)) * 30 } }); break;
}
}
// Vida: piscar (a não ser de olhos quase fechados), respirar e um balanço leve de cabeça.
const blink = blinkAt(t, seed);
if (blink < 1) st.face = { ...st.face, eyeL: st.face.eyeL * Math.max(0.08, blink), eyeR: st.face.eyeR * Math.max(0.08, blink) };
st.body = withBody(st.body, { headTilt: st.body.headTilt + Math.sin(t * 0.9 + seed) * 1.2 });
return st;
}
/** Confere uma linha do tempo (lista de problemas; vazia = ok). */
export function validateTimeline(timeline: unknown): string[] {
if (timeline === undefined) return [];
if (!Array.isArray(timeline) || timeline.length > 40) return ["timeline: lista de até 40 ações"];
const errors: string[] = [];
timeline.forEach((a: Partial<Action>, i) => {
if (!a || !ACTIONS.includes(a.do as ActionKind)) errors.push(`timeline[${i}].do: ${ACTIONS.join(", ")}`);
for (const k of ["at", "atP", "dur", "to", "times", "height"] as const) {
if (a[k] !== undefined && (typeof a[k] !== "number" || !Number.isFinite(a[k]))) errors.push(`timeline[${i}].${k}: número`);
}
if (a.atP !== undefined && !(a.atP >= 0 && a.atP <= 1)) errors.push(`timeline[${i}].atP entre 0 e 1`);
if (a.dur !== undefined && !(a.dur > 0 && a.dur <= 30)) errors.push(`timeline[${i}].dur entre 0 e 30 s`);
});
return errors;
}