feat(character-animation): add local rigged character pipeline
New beta pipeline for reusable cartoon characters with SVG rigs, pose
libraries, action timelines, and Canvas/Remotion/HyperFrames rendering.
- pipeline_defs/character-animation.yaml: 11-stage manifest
- skills/pipelines/character-animation/: 11 stage director skills
- tools/character/: BaseTool implementations for char design, rigging,
pose libraries, action timelines, previews, and QA
- schemas/artifacts/{character_design,rig_plan,pose_library,
action_timeline,character_qa_report}.schema.json: canonical artifacts
- schemas/artifacts/scene_plan.schema.json: extended for character-led
scenes
- .agents/skills/{canvas-procedural-animation,character-animation-qa,
character-rigging,pose-library-design,svg-character-animation}/:
Layer 3 vendor knowledge
- AGENT_GUIDE / PROJECT_CONTEXT / README / ARCHITECTURE / PROVIDERS:
surface the new pipeline and its capability family
- tools/video/hyperframes_compose.py: SVG character rig support
- tests/contracts/test_character_animation_pipeline.py: contract tests
This commit is contained in:
calesthio
@@ -0,0 +1,57 @@
|
||||
# Asset Director - Character Animation Pipeline
|
||||
|
||||
## Goal
|
||||
|
||||
Produce `asset_manifest` with character parts, backgrounds, props, audio, music,
|
||||
and preview artifacts.
|
||||
|
||||
## Layer 3 Gate
|
||||
|
||||
Before authoring or generating animation assets, read the relevant Layer 3 skills:
|
||||
|
||||
- `character-rigging`
|
||||
- `svg-character-animation`
|
||||
- `pose-library-design`
|
||||
- `canvas-procedural-animation` when p5/canvas effects are used
|
||||
- `character-animation-qa` before review
|
||||
- `gsap-core`, `gsap-timeline`, and `gsap-react` for GSAP/Remotion work
|
||||
- `remotion` and `remotion-best-practices` for Remotion render work
|
||||
- `hyperframes` and `hyperframes-cli` for HyperFrames work
|
||||
|
||||
Before image/TTS/music generation, read the tool's `agent_skills` from the
|
||||
registry.
|
||||
|
||||
## Asset Organization
|
||||
|
||||
Write character assets under:
|
||||
|
||||
```text
|
||||
projects/<project-name>/assets/characters/<character-id>/
|
||||
```
|
||||
|
||||
Use subfolders:
|
||||
|
||||
```text
|
||||
parts/
|
||||
poses/
|
||||
previews/
|
||||
```
|
||||
|
||||
Generated backgrounds go under:
|
||||
|
||||
```text
|
||||
projects/<project-name>/assets/backgrounds/
|
||||
```
|
||||
|
||||
## Process
|
||||
|
||||
1. Produce or source only the parts required by `rig_plan`.
|
||||
2. Keep each moving part separate.
|
||||
3. Preserve transparent backgrounds for parts.
|
||||
4. Record prompts, seeds, providers, and model names.
|
||||
5. Build a small preview before full asset expansion.
|
||||
|
||||
## Quality Bar
|
||||
|
||||
All parts referenced by `rig_plan` must exist before compose. Missing parts are a
|
||||
blocker unless the action timeline removes the action requiring them.
|
||||
@@ -0,0 +1,32 @@
|
||||
# Character Design Director - Character Animation Pipeline
|
||||
|
||||
## Goal
|
||||
|
||||
Produce `character_design`: a small cast with clear silhouettes, roles,
|
||||
emotions, actions, and style anchors.
|
||||
|
||||
## Process
|
||||
|
||||
1. List every character with `id`, role, body type, and style.
|
||||
2. Identify the minimum emotional range needed by the story.
|
||||
3. Identify the minimum action list needed by the story.
|
||||
4. Decide required views: front, 3/4, side, back. Keep MVPs to one or two views.
|
||||
5. Note props attached to characters, such as scarf, feather, bag, glasses.
|
||||
|
||||
## Constraints
|
||||
|
||||
- One or two characters is the MVP sweet spot.
|
||||
- Animal characters need species-specific parts and action cycles.
|
||||
- More views multiply asset and pose requirements.
|
||||
- Do not invent more poses than the approved duration can use.
|
||||
|
||||
## Tool Use
|
||||
|
||||
Use `character_spec_generator` for structured drafts. Use `image_selector` only
|
||||
after the visual style and character sheet requirements are explicit. Before
|
||||
using image generation, read the tool's Layer 3 skills from the registry.
|
||||
|
||||
## Quality Bar
|
||||
|
||||
A character design is ready only when an animator or tool can infer what parts,
|
||||
expressions, and actions must exist.
|
||||
@@ -0,0 +1,49 @@
|
||||
# Compose Director - Character Animation Pipeline
|
||||
|
||||
## Goal
|
||||
|
||||
Render the approved character animation and prove it was reviewed.
|
||||
|
||||
## Runtime Routing
|
||||
|
||||
First read `edit_decisions.render_runtime`. It must match the runtime locked in
|
||||
proposal unless a `render_runtime_selection` decision explicitly changed it.
|
||||
|
||||
- `remotion`: stage assets into `remotion-composer/public`, build composition
|
||||
JSON, render via `video_compose`.
|
||||
- `hyperframes`: materialize a HyperFrames workspace and let `video_compose`
|
||||
delegate to `hyperframes_compose`. `hyperframes lint` and `validate` must pass.
|
||||
- `ffmpeg`: only for post-processing or simple video assembly; not enough for
|
||||
character acting by itself.
|
||||
|
||||
## Review Workflow
|
||||
|
||||
1. Run `character_rig_renderer` to produce or refresh the HyperFrames package.
|
||||
The browser preview is a QA/debug artifact only, not the render path.
|
||||
2. Verify the renderer emitted a HyperFrames `workspace_path`, composition HTML,
|
||||
`asset_manifest`, and `edit_decisions.render_runtime: "hyperframes"` handoff.
|
||||
3. Run `character_animation_reviewer` against rig, poses, timeline, and preview.
|
||||
4. Render final video through `video_compose` using the renderer handoff or the
|
||||
approved Remotion/HyperFrames package. The deliverable path is
|
||||
`projects/<project-name>/renders/final.mp4`, matching the standard
|
||||
OpenMontage project convention.
|
||||
5. Run standard `final_review`: ffprobe, frame sampling, visual spotcheck, audio
|
||||
spotcheck, promise preservation.
|
||||
|
||||
## Browser QA
|
||||
|
||||
When Playwright is available:
|
||||
|
||||
- open the preview,
|
||||
- capture opening/middle/end frames,
|
||||
- check for console errors,
|
||||
- verify characters are visible,
|
||||
- compare frame deltas to ensure motion exists.
|
||||
|
||||
When Playwright is unavailable, use static artifact checks and FFmpeg frame
|
||||
sampling, and report the reduced confidence.
|
||||
|
||||
## Quality Bar
|
||||
|
||||
Do not present the output as complete when `character_qa_report.status` is
|
||||
`revise` or `fail`.
|
||||
@@ -0,0 +1,33 @@
|
||||
# Edit Director - Character Animation Pipeline
|
||||
|
||||
## Goal
|
||||
|
||||
Produce `edit_decisions` and `action_timeline`.
|
||||
|
||||
## Process
|
||||
|
||||
1. Carry `render_runtime` forward from the approved proposal.
|
||||
2. Convert scene beats into timed character actions.
|
||||
3. Add anticipation, hold, action, and follow-through where appropriate.
|
||||
4. Align mouth/gesture beats to dialogue or music.
|
||||
5. Keep action density readable.
|
||||
|
||||
## Timing Pattern
|
||||
|
||||
Most acting beats need:
|
||||
|
||||
```text
|
||||
anticipation -> action -> hold/reaction -> settle
|
||||
```
|
||||
|
||||
Do not animate everything continuously. Holds are part of acting.
|
||||
|
||||
## Tool Use
|
||||
|
||||
Use `action_timeline_compiler` for a first pass, then revise the timeline if the
|
||||
acting or rhythm is weak.
|
||||
|
||||
## Quality Bar
|
||||
|
||||
Every scene has timed actions. Every action maps to a pose, action cycle, or
|
||||
procedural effect that the renderer can understand.
|
||||
@@ -0,0 +1,48 @@
|
||||
# Executive Producer - Character Animation Pipeline
|
||||
|
||||
## When To Use
|
||||
|
||||
Use this pipeline when the requested deliverable depends on reusable animated
|
||||
characters: cartoon shorts, mascot explainers, music-led character scenes,
|
||||
dialogue between simple characters, or reference-inspired local animation.
|
||||
|
||||
Do not use this pipeline for one-off motion graphics with no acting. Route those
|
||||
to `animation`. Do not use it for avatar presenter lip-sync. Route that to
|
||||
`avatar-spokesperson`.
|
||||
|
||||
## Contract
|
||||
|
||||
The pipeline produces local, deterministic character animation. It does not
|
||||
silently substitute still-image motion for acting. If the character motion cannot
|
||||
be built with the available rigs, assets, or runtime, surface a blocker.
|
||||
|
||||
## Stage Order
|
||||
|
||||
1. `research` - understand reference, technique, and feasibility.
|
||||
2. `proposal` - present concepts, runtime options, cost, music plan, sample plan.
|
||||
3. `script` - write action-friendly beats and dialogue/narration.
|
||||
4. `character_design` - define characters, silhouettes, emotions, actions.
|
||||
5. `rig_plan` - define parts, pivots, layers, constraints, poses.
|
||||
6. `scene_plan` - map story beats to character scenes.
|
||||
7. `assets` - produce or source character parts, backgrounds, props, audio.
|
||||
8. `edit` - compile timed action timeline.
|
||||
9. `compose` - render through the approved runtime and run QA.
|
||||
10. `publish` - package the final output.
|
||||
|
||||
## Governance Rules
|
||||
|
||||
- Run registry preflight before proposal.
|
||||
- If both Remotion and HyperFrames are available, present both before locking
|
||||
`render_runtime`.
|
||||
- Produce a 10-15 second sample before full asset generation.
|
||||
- Character differences belong in rig data, not one-off code paths.
|
||||
- Every generated or runtime-authored asset must list Layer 3 skills read.
|
||||
- Use `character_animation_reviewer` plus final `final_review` before delivery.
|
||||
|
||||
## Send-Back Triggers
|
||||
|
||||
- `character_design` lacks required actions or emotional range.
|
||||
- `rig_plan` lacks pivots for moving parts.
|
||||
- `pose_library` has no readable acting poses.
|
||||
- `action_timeline` has actions that cannot be rendered by the rig.
|
||||
- Compose used a runtime not approved in proposal.
|
||||
@@ -0,0 +1,58 @@
|
||||
# Proposal Director - Character Animation Pipeline
|
||||
|
||||
## Goal
|
||||
|
||||
Present character-animation concepts that are honest about local rigged motion,
|
||||
reuse, cost, and runtime choice.
|
||||
|
||||
## Required Proposal Elements
|
||||
|
||||
Each option must include:
|
||||
|
||||
- characters and roles,
|
||||
- visual style,
|
||||
- action complexity,
|
||||
- rig reuse strategy,
|
||||
- sample plan,
|
||||
- audio architecture,
|
||||
- music plan,
|
||||
- render runtime options,
|
||||
- cost estimate,
|
||||
- honest limitation note.
|
||||
|
||||
## Runtime Selection
|
||||
|
||||
Read `skills/meta/animation-runtime-selector.md` before recommending a runtime.
|
||||
|
||||
When both Remotion and HyperFrames are available:
|
||||
|
||||
- Remotion: best when the final composition needs deterministic React-rendered
|
||||
video, captions, audio, scene JSON, and final MP4 governance.
|
||||
- HyperFrames: best when the character scene is HTML/SVG/GSAP-heavy and benefits
|
||||
from web-native authoring, lint, validate, and registry blocks.
|
||||
- FFmpeg: post-processing only. Do not pick FFmpeg as the primary runtime for
|
||||
character acting.
|
||||
|
||||
Wait for user approval before locking `render_runtime`.
|
||||
|
||||
## Sample-First Rule
|
||||
|
||||
Before full production, propose a 10-15 second sample containing:
|
||||
|
||||
- one main character,
|
||||
- one expression change,
|
||||
- one body action,
|
||||
- one camera/background treatment,
|
||||
- one audio/music cue if relevant.
|
||||
|
||||
Do not batch-generate all assets until this sample is approved.
|
||||
|
||||
## Cost Honesty
|
||||
|
||||
Local rigging is cheap at render time but expensive in authoring complexity.
|
||||
Report the difference:
|
||||
|
||||
- asset generation cost,
|
||||
- TTS/music cost,
|
||||
- local render cost,
|
||||
- manual complexity risk.
|
||||
@@ -0,0 +1,26 @@
|
||||
# Publish Director - Character Animation Pipeline
|
||||
|
||||
## Goal
|
||||
|
||||
Package the final character-animation deliverable with honest metadata and a
|
||||
strong character-forward thumbnail concept.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Mention the actual visual treatment: local rigged character animation,
|
||||
procedural effects, Remotion/HyperFrames render, or mixed.
|
||||
- Pick a poster frame where the main character's emotion is readable.
|
||||
- If the output is a sample, label it as a sample.
|
||||
- If the final is inspired by a reference, describe the inspiration without
|
||||
claiming duplication.
|
||||
|
||||
## Output
|
||||
|
||||
Produce `publish_log` with:
|
||||
|
||||
- final video path,
|
||||
- thumbnail/poster-frame notes,
|
||||
- title ideas,
|
||||
- description,
|
||||
- platform-specific export notes,
|
||||
- limitations or follow-up recommendations.
|
||||
@@ -0,0 +1,45 @@
|
||||
# Research Director - Character Animation Pipeline
|
||||
|
||||
## Goal
|
||||
|
||||
Ground the character-animation plan in real references and current technique.
|
||||
For reference videos, start from `video_analysis_brief`: content, pacing, motion
|
||||
classification, keyframes, color, and production complexity.
|
||||
|
||||
## Process
|
||||
|
||||
1. Identify what the reference actually uses:
|
||||
- rigged local animation,
|
||||
- frame-by-frame traditional animation,
|
||||
- video generation,
|
||||
- still-image motion,
|
||||
- mixed techniques.
|
||||
2. Research 3-5 relevant examples or techniques.
|
||||
3. Separate what the pipeline can reproduce locally from what requires manual
|
||||
illustration, video generation, or a larger asset library.
|
||||
4. Record reusable animation primitives:
|
||||
- walk cycle,
|
||||
- blink,
|
||||
- head turn,
|
||||
- reach,
|
||||
- wing flap,
|
||||
- squash/stretch,
|
||||
- camera pan/parallax,
|
||||
- particles/weather.
|
||||
|
||||
## Output Guidance
|
||||
|
||||
The `research_brief` should include:
|
||||
|
||||
- `character_animation_fit`: high/medium/low,
|
||||
- `reference_motion_type`,
|
||||
- `required_character_actions`,
|
||||
- `rig_complexity`,
|
||||
- `manual_asset_risks`,
|
||||
- `local_runtime_candidates`.
|
||||
|
||||
## Quality Bar
|
||||
|
||||
Be explicit when a reference is hand-drawn or frame-by-frame. The user can still
|
||||
choose an inspired local rigged style, but the proposal must not imply exact
|
||||
traditional-animation quality from an automatic rig.
|
||||
@@ -0,0 +1,40 @@
|
||||
# Rig Plan Director - Character Animation Pipeline
|
||||
|
||||
## Goal
|
||||
|
||||
Produce `rig_plan` and `pose_library` from `character_design`.
|
||||
|
||||
## Process
|
||||
|
||||
1. Convert each character into rig parts:
|
||||
- body,
|
||||
- head,
|
||||
- eyes/pupils,
|
||||
- brows,
|
||||
- mouth shapes,
|
||||
- limbs/wings,
|
||||
- tail/accessories,
|
||||
- props.
|
||||
2. Define pivots for every moving part.
|
||||
3. Define layer order.
|
||||
4. Define constraints so limbs do not rotate into impossible positions.
|
||||
5. Define named poses for the approved scenes.
|
||||
6. Define action cycles only when reused at least twice or central to the story.
|
||||
|
||||
## Runtime Pattern
|
||||
|
||||
Character differences are data. The renderer should not need one-off code for a
|
||||
mouse versus a bird. A bird may have `wing_left`; a mouse may have `tail`, but
|
||||
both feed the same pose interpolation and timeline compiler.
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- Every moving part has a pivot.
|
||||
- Every required action has poses or a procedural strategy.
|
||||
- Every pose names the changed parts.
|
||||
- Risky actions are called out, not hidden.
|
||||
|
||||
## Tool Use
|
||||
|
||||
Use `svg_rig_builder` to draft rig data and `pose_library_builder` to draft the
|
||||
initial pose library. The agent may revise their output before checkpointing.
|
||||
@@ -0,0 +1,37 @@
|
||||
# Scene Director - Character Animation Pipeline
|
||||
|
||||
## Goal
|
||||
|
||||
Produce a `scene_plan` where each scene is feasible for rigged character
|
||||
animation.
|
||||
|
||||
## Scene Planning Fields
|
||||
|
||||
For each scene, include:
|
||||
|
||||
- character IDs,
|
||||
- emotional beat,
|
||||
- action sequence,
|
||||
- camera/framing,
|
||||
- background,
|
||||
- props,
|
||||
- effects,
|
||||
- required assets,
|
||||
- transition notes.
|
||||
|
||||
Use `type: "character_scene"` for rigged character acting scenes. Store
|
||||
character-specific detail in `character_actions`; do not put per-scene acting
|
||||
data in arbitrary metadata because the shared `scene_plan` schema rejects
|
||||
unknown per-scene fields.
|
||||
|
||||
## Complexity Budget
|
||||
|
||||
Prefer fewer, stronger shots:
|
||||
|
||||
- one establish,
|
||||
- one action beat,
|
||||
- one reaction beat,
|
||||
- one resolution beat.
|
||||
|
||||
Avoid scenes that require many unique views or complex physical contact unless
|
||||
the user approved that complexity.
|
||||
@@ -0,0 +1,37 @@
|
||||
# Script Director - Character Animation Pipeline
|
||||
|
||||
## Goal
|
||||
|
||||
Write scripts as performable animation beats, not just narration.
|
||||
|
||||
## Process
|
||||
|
||||
1. Lock audio architecture:
|
||||
- music-only,
|
||||
- narrator,
|
||||
- character dialogue,
|
||||
- narrator plus character sounds/dialogue.
|
||||
2. Break the story into beats that can be acted with poses.
|
||||
3. For each beat, state what changes visually:
|
||||
- emotion,
|
||||
- gaze,
|
||||
- body pose,
|
||||
- prop interaction,
|
||||
- camera,
|
||||
- environment.
|
||||
|
||||
## Writing Rules
|
||||
|
||||
- Prefer short visual beats with readable holds.
|
||||
- Avoid action that needs many unique hand-drawn poses unless approved.
|
||||
- Dialogue should be short enough for mouth-shape approximation.
|
||||
- Silent/music-led scenes need stronger physical acting notes.
|
||||
|
||||
## Output Notes
|
||||
|
||||
In the `script` artifact metadata, include:
|
||||
|
||||
- `audio_architecture`,
|
||||
- `character_beats`,
|
||||
- `required_emotions`,
|
||||
- `required_actions`.
|
||||
Reference in New Issue
Block a user