# wagefolabessy/ai-agent-animation-studio architecture

> Architecture diagram of the GitHub repository wagefolabessy/ai-agent-animation-studio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wagefolabessy/ai-agent-animation-studio
- Repository: https://github.com/wagefolabessy/ai-agent-animation-studio

## Overview

AI-Agent Animation Studio turns audio and timestamped lyrics into deterministic, procedurally directed 2.5D music videos. The main workflow analyzes audio, develops a story specification, compiles it into staged shots and choreography, builds frame state, composites SVG frames, then rasterizes and streams video for encoding and audio muxing. Separate capabilities include genre-aware staging, reusable character and environment generation, chunked rendering with checkpoint/resume, and schema/invariant validation. The graph uses README statements and SOURCE INDEX references; unsampled subsystems are represented only at the directory level where supported.

Main entry points: [`src/engine/director/production-pipeline.ts`](https://github.com/wagefolabessy/ai-agent-animation-studio/blob/main/src/engine/director/production-pipeline.ts) (Production pipeline), [`src/agents/orchestrator.ts`](https://github.com/wagefolabessy/ai-agent-animation-studio/blob/main/src/agents/orchestrator.ts) (Studio orchestration), [`src/engine/audio`](https://github.com/wagefolabessy/ai-agent-animation-studio/tree/main/src/engine/audio) (Audio analysis), [`src/agents/story-spec-agent.ts`](https://github.com/wagefolabessy/ai-agent-animation-studio/blob/main/src/agents/story-spec-agent.ts) (Story specification)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Audio Intelligence"]
  node_audio["Audio analysis"]
  node_lyrics["Lyric parsing<br/>[lrc-parser.ts]"]
  node_python_audio["Python audio analysis<br/>[analyze_audio.py]"]
end

subgraph group_story["Story and Direction"]
  node_spec_agent["Story specification"]
  node_llm["LLM providers<br/>[llm-provider.ts]"]
  node_orchestrator["Studio orchestration<br/>[orchestrator.ts]"]
  node_compiler["Verb compiler<br/>[verb-compiler.ts]"]
  node_direction["Shot and choreography"]
end

subgraph group_engine["Procedural Scene Engine"]
  node_library["Cast and environments"]
  node_rigging["Character rigging"]
  node_camera["3D camera<br/>[camera-3d.ts]"]
  node_compositor["Scene compositor"]
end

subgraph group_output["Rendering and Output"]
  node_production["Production pipeline"]
  node_chunks["Chunk rendering and resume"]
  node_renderer["Raster and video pipeline<br/>[pipeline.ts]"]
  node_ffmpeg["FFmpeg streaming<br/>[ffmpeg-streamer.ts]"]
end

subgraph group_contracts["Contracts and Validation"]
  node_schemas["Data contracts"]
  node_invariants["Invariant validation<br/>[invariants.ts]"]
end

node_creator(("Audio and lyrics"))
node_video["Rendered music video"]

node_creator -->|"provides audio"| node_audio
node_creator -->|"provides lyrics"| node_lyrics
node_audio -->|"informs story"| node_spec_agent
node_lyrics -->|"profiles lyrics"| node_spec_agent
node_spec_agent -->|"requests drafts"| node_llm
node_orchestrator -->|"runs agent"| node_spec_agent
node_orchestrator -->|"compiles story"| node_compiler
node_compiler -->|"uses archetypes"| node_library
node_compiler -->|"builds choreography"| node_direction
node_direction -->|"evaluates shots"| node_camera
node_library -->|"generates motion"| node_rigging
node_production -->|"runs orchestration"| node_orchestrator
node_production -->|"loads analysis"| node_audio
node_production -->|"renders chunks"| node_chunks
node_production -->|"builds frames"| node_compositor
node_compositor -->|"projects scene"| node_camera
node_compositor -->|"emits SVG frames"| node_renderer
node_renderer -->|"streams frames"| node_ffmpeg
node_ffmpeg -->|"encodes and muxes"| node_video
node_orchestrator -->|"validates output"| node_invariants
node_invariants -->|"checks contracts"| node_schemas
node_python_audio -.->|"alternate analysis"| node_audio

click node_audio "https://github.com/wagefolabessy/ai-agent-animation-studio/tree/main/src/engine/audio"
click node_lyrics "https://github.com/wagefolabessy/ai-agent-animation-studio/blob/main/src/engine/audio/lrc-parser.ts"
click node_python_audio "https://github.com/wagefolabessy/ai-agent-animation-studio/blob/main/python/analyze_audio.py"
click node_spec_agent "https://github.com/wagefolabessy/ai-agent-animation-studio/blob/main/src/agents/story-spec-agent.ts"
click node_llm "https://github.com/wagefolabessy/ai-agent-animation-studio/blob/main/src/agents/llm-provider.ts"
click node_orchestrator "https://github.com/wagefolabessy/ai-agent-animation-studio/blob/main/src/agents/orchestrator.ts"
click node_compiler "https://github.com/wagefolabessy/ai-agent-animation-studio/blob/main/src/engine/director/verb-engine/verb-compiler.ts"
click node_direction "https://github.com/wagefolabessy/ai-agent-animation-studio/tree/main/src/engine/director"
click node_library "https://github.com/wagefolabessy/ai-agent-animation-studio/tree/main/src/engine/library"
click node_rigging "https://github.com/wagefolabessy/ai-agent-animation-studio/tree/main/src/engine/rigging"
click node_camera "https://github.com/wagefolabessy/ai-agent-animation-studio/blob/main/src/engine/camera/camera-3d.ts"
click node_compositor "https://github.com/wagefolabessy/ai-agent-animation-studio/blob/main/src/engine/compositor/scene-compositor.ts"
click node_schemas "https://github.com/wagefolabessy/ai-agent-animation-studio/tree/main/src/schemas"
click node_invariants "https://github.com/wagefolabessy/ai-agent-animation-studio/blob/main/src/schemas/invariants.ts"
click node_production "https://github.com/wagefolabessy/ai-agent-animation-studio/blob/main/src/engine/director/production-pipeline.ts"
click node_chunks "https://github.com/wagefolabessy/ai-agent-animation-studio/tree/main/src/engine/director"
click node_renderer "https://github.com/wagefolabessy/ai-agent-animation-studio/blob/main/src/renderer/pipeline.ts"
click node_ffmpeg "https://github.com/wagefolabessy/ai-agent-animation-studio/blob/main/src/renderer/ffmpeg-streamer.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_audio,node_lyrics,node_python_audio toneBlue
class node_spec_agent,node_llm,node_orchestrator,node_compiler,node_direction toneAmber
class node_library,node_rigging,node_camera,node_compositor toneMint
class node_production,node_chunks,node_renderer,node_ffmpeg toneRose
class node_schemas,node_invariants,node_creator,node_video toneIndigo
```

## Components

### Audio Intelligence

- [Audio analysis](https://github.com/wagefolabessy/ai-agent-animation-studio/tree/main/src/engine/audio): `src/engine/audio`
- [Lyric parsing](https://github.com/wagefolabessy/ai-agent-animation-studio/blob/main/src/engine/audio/lrc-parser.ts): `src/engine/audio/lrc-parser.ts`
- [Python audio analysis](https://github.com/wagefolabessy/ai-agent-animation-studio/blob/main/python/analyze_audio.py): `python/analyze_audio.py`

### Story and Direction

- [Story specification](https://github.com/wagefolabessy/ai-agent-animation-studio/blob/main/src/agents/story-spec-agent.ts): `src/agents/story-spec-agent.ts`
- [LLM providers](https://github.com/wagefolabessy/ai-agent-animation-studio/blob/main/src/agents/llm-provider.ts): `src/agents/llm-provider.ts`
- [Studio orchestration](https://github.com/wagefolabessy/ai-agent-animation-studio/blob/main/src/agents/orchestrator.ts): `src/agents/orchestrator.ts`
- [Verb compiler](https://github.com/wagefolabessy/ai-agent-animation-studio/blob/main/src/engine/director/verb-engine/verb-compiler.ts): `src/engine/director/verb-engine/verb-compiler.ts`
- [Shot and choreography](https://github.com/wagefolabessy/ai-agent-animation-studio/tree/main/src/engine/director): `src/engine/director`

### Procedural Scene Engine

- [Cast and environments](https://github.com/wagefolabessy/ai-agent-animation-studio/tree/main/src/engine/library): `src/engine/library`
- [Character rigging](https://github.com/wagefolabessy/ai-agent-animation-studio/tree/main/src/engine/rigging): `src/engine/rigging`
- [3D camera](https://github.com/wagefolabessy/ai-agent-animation-studio/blob/main/src/engine/camera/camera-3d.ts): `src/engine/camera/camera-3d.ts`
- [Scene compositor](https://github.com/wagefolabessy/ai-agent-animation-studio/blob/main/src/engine/compositor/scene-compositor.ts): `src/engine/compositor/scene-compositor.ts`

### Rendering and Output

- [Production pipeline](https://github.com/wagefolabessy/ai-agent-animation-studio/blob/main/src/engine/director/production-pipeline.ts): `src/engine/director/production-pipeline.ts`
- [Chunk rendering and resume](https://github.com/wagefolabessy/ai-agent-animation-studio/tree/main/src/engine/director): `src/engine/director`
- [Raster and video pipeline](https://github.com/wagefolabessy/ai-agent-animation-studio/blob/main/src/renderer/pipeline.ts): `src/renderer/pipeline.ts`
- [FFmpeg streaming](https://github.com/wagefolabessy/ai-agent-animation-studio/blob/main/src/renderer/ffmpeg-streamer.ts): `src/renderer/ffmpeg-streamer.ts`

### Contracts and Validation

- [Data contracts](https://github.com/wagefolabessy/ai-agent-animation-studio/tree/main/src/schemas): `src/schemas`
- [Invariant validation](https://github.com/wagefolabessy/ai-agent-animation-studio/blob/main/src/schemas/invariants.ts): `src/schemas/invariants.ts`

### Other components

- **Audio and lyrics**
- **Rendered music video**

## Connections

- Audio and lyrics → Audio analysis: provides audio (evidence: `README.md`)
- Audio and lyrics → Lyric parsing: provides lyrics (evidence: `README.md`)
- Audio analysis → Story specification: informs story (evidence: `src/agents/story-spec-agent.ts`)
- Lyric parsing → Story specification: profiles lyrics (evidence: `src/agents/story-spec-agent.ts`)
- Story specification → LLM providers: requests drafts (evidence: `src/agents/story-spec-agent.ts`)
- Studio orchestration → Story specification: runs agent (evidence: `src/agents/orchestrator.ts`)
- Studio orchestration → Verb compiler: compiles story (evidence: `src/agents/orchestrator.ts`)
- Verb compiler → Cast and environments: uses archetypes (evidence: `src/engine/director/verb-engine/verb-compiler.ts`)
- Verb compiler → Shot and choreography: builds choreography (evidence: `src/engine/director/verb-engine/verb-compiler.ts`)
- Shot and choreography → 3D camera: evaluates shots (evidence: `src/engine/director/shot-sequencer.ts`)
- Cast and environments → Character rigging: generates motion (evidence: `src/engine/library/archetype-factory.ts`)
- Production pipeline → Studio orchestration: runs orchestration (evidence: `src/engine/director/production-pipeline.ts`)
- Production pipeline → Audio analysis: loads analysis (evidence: `src/engine/director/production-pipeline.ts`)
- Production pipeline → Chunk rendering and resume: renders chunks (evidence: `src/engine/director/production-pipeline.ts`)
- Production pipeline → Scene compositor: builds frames (evidence: `src/engine/director/production-pipeline.ts`)
- Scene compositor → 3D camera: projects scene (evidence: `src/engine/compositor/scene-compositor.ts`)
- Scene compositor → Raster and video pipeline: emits SVG frames (evidence: `README.md`)
- Raster and video pipeline → FFmpeg streaming: streams frames (evidence: `src/renderer/pipeline.ts`)
- FFmpeg streaming → Rendered music video: encodes and muxes (evidence: `README.md`)
- Studio orchestration → Invariant validation: validates output (evidence: `src/agents/orchestrator.ts`)
- Invariant validation → Data contracts: checks contracts (evidence: `src/schemas/invariants.ts`)
- Python audio analysis → Audio analysis: alternate analysis (evidence: `README.md`)
