VIREA

Cross-platform motion generation, one auditable motion contract, real VRM playback

VIREA detects the machine, installs each model into an isolated Runtime, preserves its native skeleton and representation, converts the result through Motion IR, and exports validated VRMA for browser playback.

Get started · Models · Platforms · Architecture · Evidence · Documentation

What VIREA is

Motion generation projects usually ship incompatible Python stacks, output tensors, skeletons and coordinate conventions. VIREA treats every model as an isolated, versioned capability and makes the conversion path explicit:

• Model — tasks, official artifacts, native skeleton/representation, license and exact acceptance request;
• Execution Domain — where detector, builder and Worker actually run: Windows, Linux, WSL2 or macOS;
• Result — immutable model/runtime/checkpoint identity plus native → target skeleton and representation;
• Playback — validated Motion IR/Canonical211/VRMA loaded with a real VRM in the browser.

The checkout contains source, lightweight registries, locks, tests and documentation. Environments, checkpoints, caches, logs, jobs, results and QA workspaces live under an external VIREA_HOME.

Choose your path

I want to…	Start here
Generate motion with an integrated model	Installation → First generation
Pick the correct model and skeleton	Model directory → generated support matrix
Deploy on Windows, Linux, WSL2 or macOS	Platform and execution-domain guide
Load a result in a real Avatar	Browser playback
Integrate another model	Model adapter guide
Audit claims or release evidence	Production E2E contract
Explore datasets and retargeting	Dataset pipeline and showcase

Architecture

flowchart LR
    A[Startup domain detection] --> B[Selectable domain candidates]
    B --> C[User selects execution domain]
    C --> D[Resolve matching Runtime and profile]
    M[OS-neutral model asset snapshot] --> D
    D --> E0[Domain-local Runtime and Worker]
    E0 --> E[Native ModelResult]
    E --> F[Motion IR]
    F --> G[Target skeleton and Canonical211]
    G --> H[Validated VRMA]
    H --> I[Real VRM browser playback]

    A -. OS / device / free resources .-> J[Observed evidence]
    M -. asset / revision identity .-> J
    E -. model / runtime / checkpoint identity .-> J
    I -. screenshot / WebGL / console .-> J

Loading

The control plane never imports model frameworks. Each Worker owns its locked environment, validates official artifacts offline, emits a versioned ModelResult, and can be cancelled or recovered as an isolated process tree. A model and its checkpoint do not belong to an operating system: the selected execution domain determines the Runtime, path view and accelerator backend. Observed evidence reports where one exact configuration ran; it never chooses or hides domains.

Model support

The table is generated from plugins/models/*/manifest.yaml; status, native skeleton and native representation are not hand-written README claims. Full task, license and upstream details are in the model matrix.

Model	Status	Native motion identity	Declared Runtime capability	Known deployment blockers	Observed evidence coverage
ACMDM-S-PS22 HumanML3D Absolute XYZ acmdm-humanml3d	Integrated · experimental	humanml3d.body22.v1 humanml3d.body22.positions.v1 · 20.0 FPS	acmdm-humanml3d-cu128 · Windows x86_64, Linux x86_64 · cuda_full (VRAM 6 GiB, RAM 8 GiB) acmdm-humanml3d-cpu · Windows x86_64, Linux x86_64, macOS arm64, macOS x86_64 · cpu (RAM 12 GiB)	No structured blocker recorded	No model-scoped observation recorded
CMDM HumanML3D cmdm-humanml3d	Integrated · experimental	humanml3d.body22.v1 humanml3d.vector263.v1 · 20.0 FPS	cmdm-humanml3d-cu128 · Windows x86_64, Linux x86_64 · cuda_full (VRAM 6 GiB, RAM 8 GiB) cmdm-humanml3d-cpu · Windows x86_64, Linux x86_64, macOS arm64, macOS x86_64 · cpu (RAM 12 GiB)	No structured blocker recorded	No model-scoped observation recorded
FloodDiffusion Tiny flood-diffusion-tiny	Integrated · experimental	humanml3d.body22.v1 humanml3d.vector263.v1 · 20.0 FPS	flood-diffusion-tiny-cu128 · Windows x86_64, Linux x86_64 · cuda_full (VRAM 16 GiB, RAM 8 GiB) flood-diffusion-tiny-cpu · Windows x86_64, Linux x86_64, macOS arm64, macOS x86_64 · cpu (RAM 16 GiB)	No structured blocker recorded	No model-scoped observation recorded
MARDM SiT-XL HumanML3D mardm-humanml3d	Integrated · experimental	humanml3d.body22.v1 mardm.humanml3d.ric67.v1 · 20.0 FPS	mardm-humanml3d-cu128 · Windows x86_64, Linux x86_64 · cuda_full (VRAM 12 GiB, RAM 16 GiB) mardm-humanml3d-cpu · Windows x86_64, Linux x86_64, macOS arm64, macOS x86_64 · cpu (RAM 24 GiB)	No structured blocker recorded	No model-scoped observation recorded
MoMADiff HumanML3D momadiff-humanml3d	Integrated · experimental	humanml3d.body22.v1 humanml3d.vector263.v1 · 20.0 FPS	momadiff-humanml3d-cu128 · Windows x86_64, Linux x86_64 · cuda_full (VRAM 6 GiB, RAM 8 GiB) momadiff-humanml3d-cpu · Windows x86_64, Linux x86_64, macOS arm64, macOS x86_64 · cpu (RAM 12 GiB)	No structured blocker recorded	No model-scoped observation recorded
PRISM TP2M 1.4B prism-tp2m-1-4b	Integrated · experimental	smplh.body22.v1 prism.smplh_body22.axis_angle69.v1 · 30.0 FPS	prism-tp2m-1-4b-cu128-component-split · Linux x86_64 · cuda_component_split (VRAM 12 GiB, RAM 28 GiB) prism-tp2m-1-4b-cpu · Windows x86_64, Linux x86_64, macOS arm64, macOS x86_64 · cpu (RAM 96 GiB)	No structured blocker recorded	No model-scoped observation recorded

Status dimensions are deliberately separate:

• integrated_experimental means a real VIREA Worker and bounded production-acceptance path exist;
• supported requires broader platform/configuration evidence and an explicit distribution decision;
• external_assets_only or license_review_required limits acquisition/redistribution, not technical deployability;
• a Runtime platform declaration is not the same as a completed real-device E2E.

Model status can preserve a previous bounded acceptance, while the current release still requires a fresh browser/backend record for the latest manifest and Runtime selection. Read the versioned production evidence registry through the E2E documentation; never infer current evidence from this table alone.

The current validated-evidence and validator policy is v1.1.0. The six legacy v1.0.0 records are invalid for current promotion because they do not bind both acceptance and generation to the installed Runtime core epoch; until new records are actually written, the current-policy passed count is zero. Raw browser observation remains a separate v1.0.0 telemetry contract and is never promotion evidence by itself.

See status semantics for the complete contract.

Execution-domain selection and evidence

VIREA treats Windows, Linux, WSL2 and macOS as first-class execution domains. The common flow is: detect available domains at startup → let the user select one → reuse the same OS-neutral model assets → resolve and lazily build or reuse the matching isolated Runtime → re-check resources in that domain before Worker launch. Selecting a new domain does not reinstall or redownload the model asset snapshot. An explicit selection must fail with a model-level reason when no compatible Runtime exists; it must not silently switch operating system, accelerator or resource profile.

Selectable execution domain	Declared Runtime capability	Known deployment blockers	Observed evidence coverage
Windows native	detector=implemented, resolver=implemented, builder=implemented, worker=implemented matching models: acmdm-humanml3d, cmdm-humanml3d, flood-diffusion-tiny, mardm-humanml3d, momadiff-humanml3d, prism-tp2m-1-4b cpu (RAM 12 GiB); cpu (RAM 16 GiB); cpu (RAM 24 GiB); cpu (RAM 96 GiB); cuda_full (VRAM 12 GiB, RAM 16 GiB); cuda_full (VRAM 16 GiB, RAM 8 GiB); cuda_full (VRAM 6 GiB, RAM 8 GiB)	No structured blocker recorded	No model-scoped observation recorded
WSL2 (Linux runtime)	detector=implemented, resolver=implemented, builder=implemented, worker=implemented matching models: acmdm-humanml3d, cmdm-humanml3d, flood-diffusion-tiny, mardm-humanml3d, momadiff-humanml3d, prism-tp2m-1-4b cpu (RAM 12 GiB); cpu (RAM 16 GiB); cpu (RAM 24 GiB); cpu (RAM 96 GiB); cuda_component_split (VRAM 12 GiB, RAM 28 GiB); cuda_full (VRAM 12 GiB, RAM 16 GiB); cuda_full (VRAM 16 GiB, RAM 8 GiB); cuda_full (VRAM 6 GiB, RAM 8 GiB)	No structured blocker recorded	No model-scoped observation recorded
Linux native	detector=implemented, resolver=implemented, builder=implemented, worker=implemented matching models: acmdm-humanml3d, cmdm-humanml3d, flood-diffusion-tiny, mardm-humanml3d, momadiff-humanml3d, prism-tp2m-1-4b cpu (RAM 12 GiB); cpu (RAM 16 GiB); cpu (RAM 24 GiB); cpu (RAM 96 GiB); cuda_component_split (VRAM 12 GiB, RAM 28 GiB); cuda_full (VRAM 12 GiB, RAM 16 GiB); cuda_full (VRAM 16 GiB, RAM 8 GiB); cuda_full (VRAM 6 GiB, RAM 8 GiB)	No structured blocker recorded	No model-scoped observation recorded
macOS native	detector=implemented, resolver=implemented, builder=implemented, worker=implemented matching models: acmdm-humanml3d, cmdm-humanml3d, flood-diffusion-tiny, mardm-humanml3d, momadiff-humanml3d, prism-tp2m-1-4b cpu (RAM 12 GiB); cpu (RAM 16 GiB); cpu (RAM 24 GiB); cpu (RAM 96 GiB)	No structured blocker recorded	No model-scoped observation recorded

Four statements must never be conflated:

1. Selectable execution domain — a detected, user-chosen command/filesystem/resource boundary.
2. Declared Runtime capability — a particular lock/Worker implements a platform ABI and memory strategy.
3. Known deployment blocker — a structured model/domain/stage reason prevents a declared option from becoming ready.
4. Observed evidence coverage — an identified model/configuration ran a named scope on one domain; current promotion still comes only from the production evidence registry.

All six integrated models now declare whole-model CPU Runtime variants across win-64, linux-64, osx-arm64 and osx-64. For ACMDM, MARDM, FloodDiffusionTiny and PRISM, this is a locked contract/import baseline only: real CPU model load/inference and native Linux/macOS observations have not run. PRISM uses a conservative fail-closed 96 GiB RAM floor. The current structured portability blocker lists are empty, but an empty blocker list is not validation. Therefore VIREA still cannot claim that every model has completed operation on every target system.

Quick start

1. Keep the checkout clean

Set UV_PROJECT_ENVIRONMENT to an external directory before syncing a source checkout.

Windows PowerShell

$env:UV_PROJECT_ENVIRONMENT = "$env:LOCALAPPDATA\VIREA\dev-venv"
$vireaHome = "$env:LOCALAPPDATA\VIREA\home"
uv sync --locked --all-packages --extra dev
pnpm install --frozen-lockfile
pnpm --filter @virea/web build
uv run virea setup --virea-home $vireaHome
uv run virea doctor --json --record --explain --repair-plan --virea-home $vireaHome

Linux / WSL2

export UV_PROJECT_ENVIRONMENT="${XDG_DATA_HOME:-$HOME/.local/share}/virea/dev-venv"
VIREA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}/virea/home"
uv sync --locked --all-packages --extra dev
pnpm install --frozen-lockfile
pnpm --filter @virea/web build
uv run virea setup --virea-home "$VIREA_HOME"
uv run virea doctor --json --record --explain --repair-plan --virea-home "$VIREA_HOME"

macOS

export UV_PROJECT_ENVIRONMENT="$HOME/Library/Application Support/VIREA/dev-venv"
VIREA_HOME="$HOME/Library/Application Support/VIREA/home"
uv sync --locked --all-packages --extra dev
pnpm install --frozen-lockfile
pnpm --filter @virea/web build
uv run virea setup --virea-home "$VIREA_HOME"
uv run virea doctor --json --record --explain --repair-plan --virea-home "$VIREA_HOME"

2. Install one real model

Inspect the model first; installation performs resource admission before downloading artifacts.

uv run virea model info flood-diffusion-tiny
uv run virea model install flood-diffusion-tiny --execution-domain windows-native --runtime flood-diffusion-tiny-cu128 --resource-profile cuda-full --apply --virea-home <external-home>
uv run virea model verify flood-diffusion-tiny --virea-home <external-home>

Use a domain ID returned by doctor --json: windows-native, linux-native, macos-native, or a concrete wsl:<distribution>. --runtime and --resource-profile are optional advanced overrides, but when present they require --execution-domain. The same flags are available on model repair and generate; VIREA never silently changes a selection that fails.

The admission decision checks free VRAM, free physical RAM, swap/pagefile and storage independently. RAM is used only when the selected Worker genuinely implements CPU or offload placement; the resolver never adds RAM and VRAM together to make an impossible configuration appear sufficient.

3. Generate and validate

uv run virea generate --model flood-diffusion-tiny --execution-domain windows-native --runtime flood-diffusion-tiny-cu128 --resource-profile cuda-full --task text_to_motion --prompt "A person walks forward, turns left, and waves with the right hand." --seconds 4 --fps 20 --seed 42 --timeout 1800 --virea-home <external-home>
uv run virea validate-real-e2e --virea-home <external-home> --job-id <job-id>

The persisted result identifies the model/version/runtime/checkpoint, native skeleton/representation, target skeleton/representation, execution domain, resource profile and device.

4. Play the result

uv run virea serve --host 127.0.0.1 --port 8000 --virea-home <external-home>

Open http://127.0.0.1:8000/app/, load a local .vrm, and select the generated result. Production browser evidence must show a visible full Avatar, advancing animation time, validated duration, finite tracks and zero console errors. A client cannot promote itself by reporting playing=true; see the E2E contract.

Resource admission and fallback

RuntimeSpec resource profiles (ordered)
  ├─ accelerator and ABI
  ├─ minimum free VRAM
  ├─ minimum free physical RAM
  ├─ minimum free swap/pagefile
  └─ minimum free storage

Examples include full CUDA placement, whole-model CPU, component-split CPU/CUDA, and model-specific offload. A strategy is advertised only after the Worker implements it; insufficient resources stop installation before a transaction or download is created. Before spawning a Worker, the authoritative ControlPlane for one shared VIREA_HOME acquires a durable resource lease and re-detects live resources while holding that lease. This closes the install-to-inference race among VIREA processes that share that home; separate VIREA_HOME values and unrelated external processes do not interlock, and resources can still change after observation, so this is not a machine-global guarantee against OOM.

Motion and result contracts

VIREA does not erase model-native information in order to make every model look identical.

• ModelResult stores native arrays and provenance with the correct source skeleton and representation.
• Motion IR v2 provides typed actor tracks, time, space and artifact references.
• Canonical211 v3 is the current VRM humanoid compatibility carrier: root translation/rotation, body rotations and hand rotations.
• VrmMotionResult binds canonical tracks, native artifacts and per-actor VRMA exports.
• VRMA export includes canonical rest translations and absolute hips translation so three-vrm-animation can play finite tracks.

The resulting filename carries a readable source → target identity while the result ULID remains the database key.

Repository structure

Path	Responsibility
apps/api	FastAPI control plane and versioned result/artifact API
apps/cli	setup, doctor, model lifecycle, generation, validation and support commands
apps/web	model catalog, generation UI and real VRM/VRMA Viewer
packages/contracts	Python and JSON contracts
packages/bootstrap	machine detection and execution-domain/resource resolution
packages/model_pool	artifact staging, installation transactions and READY verification
packages/runtime	isolated runtime build, Worker supervision, cancellation and recovery
packages/compatibility	model-native adapters into Motion IR
packages/retarget, packages/vrm	target retargeting and validated VRMA export
plugins/models	one manifest and optional isolated Runtime per model
registries	model, runtime, skeleton, representation, bundle and evidence facts
doc	tutorials, how-to guides, reference, explanation, decisions and evidence

Validation

No generated fixture or protocol-only check counts as real-model production evidence. A complete model record links one doctor report, installation, exact real-checkpoint job/result, native artifacts, Motion IR, Canonical211, VRMA validation and browser run. The browser run stores Playwright JSON, screenshots, WebGL information and console output outside the checkout.

python scripts/generate_docs.py --check
python scripts/check_docs.py
python -m pytest tests/refactor tests/characterization -q
pnpm --filter @virea/web test
pnpm --filter @virea/web exec tsc --noEmit
pnpm --filter @virea/web build

Exact current release evidence and any unvalidated platforms are recorded in the quality documentation, not copied into multiple README paragraphs.

Documentation

The Documentation Hub is organized by task:

• Getting started
• Models and skeleton identities
• Platforms and execution domains
• Runtime data and retention
• Troubleshooting
• Motion/retarget mathematics
• Documentation design
• Research registry
• Dataset showcase

Contributing, security and distribution

Contributions must update contracts, implementation, tests and evidence together. See CONTRIBUTING.md and SECURITY.md. Third-party model, dataset and Avatar terms are listed in THIRD_PARTY_NOTICES.md and per-model notices.

The repository does not currently declare a project-code license. Public redistribution and open-source GA remain pending an explicit maintainer license decision; third-party licenses cannot be used to infer one for VIREA itself.