animsuite

An animation rendering tool that generates animated sequences from JSON specifications using Skia graphics library.

Features

• Render animations from JSON-based scene, rig, and animation definitions
• Configurable resolution, frame rate, and background color
• Export frames as PNG images and optionally combine into MP4 video
• Support for camera transformations and animated elements

Prerequisites

• Python 3.12+
• FFmpeg (for MP4 export)

Setup

Quick Setup

Run the setup script to create or reinitialize the virtual environment:

chmod +x setup.sh
./setup.sh

This will:

1. Remove any existing virtual environment
2. Create a new virtual environment named venv
3. Install all required dependencies

Manual Setup

Alternatively, you can set up manually:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Usage

Using the Run Script (Recommended)

After setup, use the run script for easy execution:

chmod +x run.sh
./run.sh                    # Render default shot with default settings
./run.sh --help            # Show all available options
./run.sh --width 1920 --height 1080  # Render in 1080p
./run.sh --shot-id shot_002 --overwrite  # Render specific shot with overwrite

Direct Usage

Activate the virtual environment and run directly:

source venv/bin/activate
python -m animbuild.cli render --overwrite

Validate a single shot:

python -m animbuild.cli validate --shot-id shot_006

Validate and emit JSON report:

python -m animbuild.cli validate --shot-id shot_006 --format json

Treat warnings as errors:

python -m animbuild.cli validate --shot-id shot_006 --warnings-as-errors

Suppress validation warnings:

python -m animbuild.cli validate --shot-id shot_006 --quiet

Validate all shots under a project root:

python -m animbuild.cli validate-examples --project-root example_project

Suppress warnings when validating all shots:

python -m animbuild.cli validate-examples --project-root example_project --quiet

By default, validation prints a warning count summary.

Validate all sequences under a project root:

python -m animbuild.cli validate-sequences --project-root example_project

Validate a single asset file (auto-detect type, with optional override):

python -m animbuild.cli validate-asset --asset-path example_project/shot_006/rig.json
python -m animbuild.cli validate-asset --asset-path example_project/sequence.json --asset-type sequence --project-root example_project

Render a shot sequence:

python -m animbuild.cli render-sequence --project-root example_project --sequence sequence.json --overwrite

Audio tracks and sequence events can be listed in sequence.json.

Sequence audio format:

{
  "audio": [
    { "path": "audio/score.wav", "start_frame": 0, "gain": 0.9 }
  ]
}

Notes:

• path: relative paths resolve relative to the sequence.json directory
• start_frame: integer >= 0, measured in sequence frames at sequence.fps (or inferred fps)
• gain: numeric linear volume multiplier (maps to ffmpeg volume=); default is 1.0
• Supported extensions: .wav, .mp3, .ogg, .flac, .m4a
• MP4 muxing uses ffmpeg with -shortest, so audio will not extend the video duration

When you render a sequence, audio will be mixed into the MP4 render (if enabled), and events are written to events.json in the sequence output.

Troubleshooting:

• MP4 export requires ffmpeg. If it is not installed, render frames only using --no-mp4.
• Sequence output defaults to output_sequence/ and includes manifest.json and (if present) events.json.

Render all sequences under a project root:

python -m animbuild.cli render-sequences --project-root example_project --overwrite

Render frames only (skip MP4):

python -m animbuild.cli render --shot-id shot_006 --no-mp4 --overwrite

Validate expression blocks in a scene:

python scripts/validate_exprs.py example_project/shot_013/scene.json

Import assets from other formats:

# Import a PSD file into a scene with layers
python -m animbuild.cli import-psd --input input.psd --output out_dir

# Import a glTF file into a rig (skeleton only)
python -m animbuild.cli import-gltf --input input.gltf --output out_dir

Asset Generators

Generate asset files from templates:

# Generate a character rig
python scripts/generate_rig.py --name hero --archetype hero --output-dir ./output

# Generate a rig with specific parts only
python scripts/generate_rig.py --name torso_only --parts head,torso --output-dir ./output

# Generate a scene with actors
python scripts/generate_scene.py --name forest_scene --actors hero,villain --output ./output/scene.json

# Generate a prop asset
python scripts/generate_prop.py --name crate --type box --output ./output/props/

Generator Options:

Script	Options	Description
generate_rig.py	--name	Rig name (required)
	--archetype	Character archetype: hero, villain, sidekick, custom (default: custom)
	--parts	Comma-separated parts to include (e.g., head,torso)
	--output-dir	Output directory (default: current directory)
	--no-validate	Skip validation
	--register	Register asset in database
generate_scene.py	--name	Scene name (required)
	--actors	Comma-separated actor IDs (e.g., hero,villain)
	--output	Output file path (default: ./scene.json)
	--no-validate	Skip validation
	--register	Register asset in database
generate_prop.py	--name	Prop name (required)
	--type	Prop type: box, circle, custom (default: custom)
	--output	Output directory (default: current directory)
	--no-validate	Skip validation
	--register	Register asset in database

Database Registration:

All generators support --register to add assets to the SQLite database:

python scripts/generate_rig.py --name hero --register --project mygame --db-path assets.db

Export a shot bundle (JSON):

python -m animbuild.cli export --shot-id shot_006 --format json --output export.json

Export a shot snapshot (SVG, props only):

python -m animbuild.cli export --shot-id shot_006 --format svg --output export.svg

Export a shot bundle directory (JSON + SVG):

python -m animbuild.cli export --shot-id shot_006 --format bundle --output export_bundle

Export a per-frame bake (props only):

python -m animbuild.cli export-bake --shot-id shot_006 --output bake.json

Export a specific frame (props only):

python -m animbuild.cli export --shot-id shot_011 --format svg --output export_23.svg --frame 23

Retarget animation tracks to a rig:

python -m animbuild.cli retarget-anim --source-anim example_project/shot_001/anim.json --target-rig example_project/shot_010/rig.json --output retargeted_anim.json

Strict retargeting (error on missing bone mappings):

python -m animbuild.cli retarget-anim --source-anim example_project/shot_001/anim.json --target-rig example_project/shot_010/rig.json --output retargeted_anim.json --strict

Report missing mappings as warnings:

python -m animbuild.cli retarget-anim --source-anim example_project/shot_001/anim.json --target-rig example_project/shot_010/rig.json --output retargeted_anim.json --report

Sequence renders write an output manifest.json with shot ranges (including end frames) and total frames.

Run sequence verification checks:

python scripts/verify_sequences.py

Run the full test suite:

python scripts/run_tests.py

Validate a shot sequence:

python -m animbuild.cli validate-sequence --project-root example_project --sequence sequence.json

Audit assets referenced by shots:

python -m animbuild.cli audit --project-root example_project

Audit assets referenced by a sequence:

python -m animbuild.cli audit --project-root example_project --sequence sequence.json

JSON output with summary:

python -m animbuild.cli audit --project-root example_project --format json --summary

Dependency graph (Graphviz DOT):

python -m animbuild.cli audit --project-root example_project --format dot

List missing assets only:

python -m animbuild.cli audit --project-root example_project --missing-only

Include dependencies in text output:

python -m animbuild.cli audit --project-root example_project --deps

Write audit output to a file:

python -m animbuild.cli audit --project-root example_project --format json --output audit.json

Command Line Options

Option	Description	Default
--project-root	Project root directory	example_project
--shot-id	Shot ID to render	shot_001
--width	Width of output frames	512
--height	Height of output frames	512
--bg	Background color in hex format	#20242a
--overwrite	Overwrite existing output files	Disabled

Project Structure

The project follows a structured format with JSON files defining different aspects of the animation. The example project represents an unzipped work package that animsuite takes as input:

example_project/                 # Root directory of the work package
└── shot_001/                   # Individual shot directory
    ├── shot.json               # Shot metadata (ID, FPS, duration)
    ├── scene.json              # Scene definition
    ├── rig.json                # Character/object rigging
    ├── anim.json               # Animation keyframes
    ├── camera.json             # Camera properties and movements
    └── output/                 # Generated frames and video (created during rendering)

The work package can be distributed as a ZIP archive and unzipped to this structure, or created directly in this format.

Work Package Format

animsuite accepts work packages in two formats:

1. Unzipped directory structure (as shown above)
2. Zipped archive with the same internal structure

When using a zipped work package, simply unzip it to a directory before processing with animsuite.

Packaging Example

To create a work package archive:

zip -r my_work_package.zip my_project/

To unpack and render:

unzip my_work_package.zip
./run.sh --project-root my_project

File Formats

• shot.json: Contains shot ID, frames per second, and total duration in frames
• rig.json: Defines bone hierarchy and part attachments for asset substitution (unitless pivots and offsets)
• anim.json: Contains animation tracks for bones (e.g., bone.torso.position.x, bone.arm.rotation) using unitless translations and degree rotations
• camera.json: Specifies camera properties and transformations
• scene.json: Defines layered draw order; drawables can be actors or props.
  • Optional actors array can bind drawables to specific rigs/animations and apply a unitless transform (position as normalized canvas coords, scale as fraction of canvas).
  • Prop drawables can be objects like { "type": "prop", "asset": "parts/sky.json", "transform": { ... } } or strings pointing to a JSON asset path.
  • Layers can include optional scale and parallax to control per-layer camera scaling and parallax (use parallax < 1 for background drift).
  • Layers can include optional opacity, blend, order, clip, and mask for compositing.
  • Layers can include optional blur (pixels). If scene.dof is present and blur is omitted, blur is derived from parallax distance to focus.
  • Optional dof object can set focus_parallax and max_blur for automatic depth-of-field blur.
  • Actors can use anim_action to reference assets/animations/catalog.json (or override via anim_catalog) instead of a direct anim path.
• assets/animations/catalog.json: Maps action names to default animation files, tags, and durations for scene composition.

Animation Catalog

assets/animations/catalog.json provides the default action dictionary. The schema is schemas/animation_catalog.schema.json. Action keys follow action__modifier (double underscore) when combined behaviors are present.

Notes: rigs use unitless pivots and offsets ("units": "rig"), and are scaled per-actor using the scene actor transform; camera zoom is centered on the canvas and camera x/y offsets are applied in that same space.

For detailed information about each file format and their structure, see the documentation in example_project/shot_001/README.md.

See spec/v0.1.md for the current syntax spec, and ROADMAP.md for planned language, runtime, and tooling milestones.

Example Output

The renderer produces:

1. Individual PNG frames in output/frames/
2. An optional MP4 video file in output/ (when enabled)

Development

To contribute to animsuite:

1. Set up the environment using the setup script

Asset Validation

Validate assets and the default animation catalog:

python scripts/validate_assets.py

Include example project data:

python scripts/validate_assets.py --include-examples

Asset Audit

Report missing assets referenced by shots:

python scripts/asset_audit.py --project-root example_project

Schema Validation

Validate all example shots against JSON schemas:

python scripts/validate_examples.py

2. Make your changes to the code
3. Test with the example project or create your own
4. Submit a pull request with your improvements

Project Structure

For detailed information about the codebase structure, see docs_structure.md. For detailed information about the sample project files, see example_project/shot_001/README.md.

Asset Management

animsuite includes a structured asset management system:

assets/
├── characters/     # Character rigs and animations
├── props/          # Prop objects and accessories
├── scenes/         # Scene compositions and layouts
├── textures/       # Texture images and materials
├── animations/     # Animation sequences and keyframe data
├── cameras/        # Camera presets and movement data
├── rigs/           # Rig templates and skeleton definitions
└── templates/      # Project templates and boilerplate files

For detailed information about asset naming conventions and management, see assets/naming_conventions.md. For detailed information about the asset structure, see assets/README.md.

AI/LLM Integration

AnimSuite is designed to be highly compatible with AI agents and LLMs for automated animation generation.

LLM Context Guide

A dedicated semantic guide for AI agents is available at docs/LLM_CONTEXT.md. This document provides concise format descriptions and guidelines for generating valid AnimSuite JSON files.

Audio Playbook

Step-by-step sequence audio guidance is available at docs/playbooks/audio.md.

Asset Catalog

To help an LLM know which assets are available, you can generate a full catalog index:

python -m animbuild.cli catalog

This produces assets/catalog_full.json, which lists all rigs, props, animations, and images with their metadata.

Bootstrapping a Shot

You can quickly scaffold a new shot directory with minimal boilerplate for an LLM to populate:

python -m animbuild.cli init-shot --project-root example_project --shot-id my_new_shot

Troubleshooting

• If you get import errors, ensure the virtual environment is activated: source venv/bin/activate
• If FFmpeg is not found, install it using your system's package manager
• For rendering issues, check that all required JSON files exist in the project directory