VIREA

Conversation that speaks, moves, and continues.

An experimental embodied-character runtime: dialogue, voice, expressive gestures and spatial motion, planned together and performed by a persistent VRM character.

English · 简体中文 · Live demos · Character runtime · Get started · CLI reference · Models · Platforms · Architecture · Evidence · Documentation

From motion generation to embodied conversation

VIREA has grown from a motion-data and retargeting pipeline, through isolated multi-model generation, into Motion Studio: an ongoing conversation with a moving character. The earlier foundations still matter: native model histories, skeleton conversion, isolated workers and observable execution now support one performance.

The language model composes the response and a coarse activity plan. Audio8-TTS 0.6B clones the voice from a reference recording. Import audio and its exact transcript in Settings, then preview and select the voice. See the deployment and migration guide. Choose SentiAvatar + ARDY, MotionCraft, or SynTalker before starting a session. The existing SentiAvatar + ARDY route retains activity execution and model handoffs. Each new route uses one motion family with independently timed motion segments and cloned speech: multiple actions can outlast speech, and speech can start anywhere or cross action boundaries. Native history continues between windows; audio EOF does not stop the body. See the technical synopsis for implementation, setup and measured limitations.

This stage is experimental. The demos below show actual local runs, including their timing and limitations; they are not a claim of universal physical interaction, all-terrain locomotion, or production readiness.

Single-family routes: 16 complex task demos

Eight recordings per family, each in two columns × four rows. Click a cover for the complete MP4. Audio8-TTS uses the supplied audio_reference_chu2.mp3 and chu2.txt voice reference. These are actual Studio replays at normal speed; preparation latency is separate.

These are actual model outputs, not a certification of task fidelity or naturalness. Complex travel, foot contact and fine gestures remain limited. See the technical synopsis and reproduction guide for architecture, measured latency and limitations.

MotionCraft

Welcome and introduction 32s · 6 actions · 2 speech clips · motioncraft + Audio8-TTS	Warm-up coach 36s · 6 actions · 2 speech clips · motioncraft + Audio8-TTS
Garden story 35s · 6 actions · 2 speech clips · motioncraft + Audio8-TTS	Dance lesson 32s · 6 actions · 2 speech clips · motioncraft + Audio8-TTS
Fashion presentation 34s · 7 actions · 2 speech clips · motioncraft + Audio8-TTS	From tension to celebration 33s · 6 actions · 2 speech clips · motioncraft + Audio8-TTS
Walking guide 38s · 6 actions · 2 speech clips · motioncraft + Audio8-TTS	Boxing practice 36s · 7 actions · 2 speech clips · motioncraft + Audio8-TTS

SynTalker

Welcome and introduction 32s · 6 actions · 2 speech clips · syntalker + Audio8-TTS	Warm-up coach 36s · 6 actions · 2 speech clips · syntalker + Audio8-TTS
Garden story 35s · 6 actions · 2 speech clips · syntalker + Audio8-TTS	Dance lesson 32s · 6 actions · 2 speech clips · syntalker + Audio8-TTS
Fashion presentation 34s · 7 actions · 2 speech clips · syntalker + Audio8-TTS	From tension to celebration 33s · 6 actions · 2 speech clips · syntalker + Audio8-TTS
Walking guide 38s · 6 actions · 2 speech clips · syntalker + Audio8-TTS	Boxing practice 36s · 7 actions · 2 speech clips · syntalker + Audio8-TTS

Video gallery · Execution manifest

Avatar: Unnamed Character 6 — Reira. Source: VRM-Model-1.vrm.

Motion Studio demos

These recordings used the earlier Kokoro stack. Current speech defaults to Audio8-TTS 0.6B; the historical timing measurements do not describe the new model.

8 complete recordings · two columns, four rows. Play each video directly here without downloading; use the player controls to enable sound and expand to full screen. Model-directed plans retain pauses within playback; generation latency is reported separately.

01 · Stage host Opening speech → walking, turning and greeting → invite the audience. 01-host.mp4 Full performance · 39.2s SentiAvatar ↔ ARDY · Kokoro	02 · Warm-up coach Explain the technique → side steps and stretching → review and encouragement. 02-warmup.mp4 Full performance · 42.3s SentiAvatar ↔ ARDY · Kokoro
03 · Acted story Set a garden story → silently search and discover → tell the ending. 03-story.mp4 Full performance · 54.6s SentiAvatar ↔ ARDY · Kokoro	04 · Dance lesson Explain rhythm and balance → improvised combination → review common mistakes. 04-dance.mp4 Full performance · 49.9s SentiAvatar ↔ ARDY · Kokoro
05 · Fashion presentation Introduce colors and fabrics → walk, turn and pose → explain the mood. 05-fashion.mp4 Full performance · 51.6s SentiAvatar ↔ ARDY · Kokoro	06 · From doubt to joy Respond to uncertainty → celebrate through movement → close with reassurance. 06-celebration.mp4 Full performance · 32.2s SentiAvatar ↔ ARDY · Kokoro
07 · Walking guide Introduce an artwork → walk, speak and point → summarize the exhibition. 07-tour.mp4 Full performance · 55.3s SentiAvatar ↔ ARDY · Kokoro	08 · Boxing practice Explain stance and guard → punches, evasion and recovery → review breathing and rhythm. 08-boxing.mp4 Full performance · 48.1s SentiAvatar ↔ ARDY · Kokoro

Tasks, measurements and limitations · Two-column video gallery (serve locally over HTTP) · Execution manifest

Architecture

flowchart LR
    U[User request + conversation] --> L[LLM: motion intent + independent speech]
    L --> V[Audio8-TTS: cloned voice / measured PCM duration]
    L --> E{Selected motion route}
    V --> E
    E --> S[Existing: SentiAvatar + ARDY]
    E --> M[MotionCraft: text backbone + speech control]
    E --> T[SynTalker: latent diffusion + RVQ]
    S --> R[VRM: one body source / shared playback clock]
    M --> R
    T --> R
    V --> R
    R --> F[Progress / pause / interruption / recording]

Loading

Layer	Responsibility
Dialogue and intent	Understand the conversation; author the reply, activities and their ordering.
Planning	Existing route: coarse activity execution. New routes: independently timed motion and speech tracks.
Generation	Preserve native window history. New routes prepare the whole performance before playback; they do not claim online streaming.
Presentation	Maintain one body owner, independent speech timing, continuous sample clocks and an inspectable execution trace.
Runtime foundation	Keep model environments separate; retain native identities, retarget through Motion IR and play real VRM assets.

See the coarse-activity design and window-continuity measurements for the implementation and measured boundaries.

Motion infrastructure

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	Clone-to-result tutorial → CLI reference
Run a persistent speaking VRM character	Character deployment and capability boundaries
Pick the correct model and skeleton	Model directory → generated support matrix
Deploy on Windows, Linux, WSL2 or macOS	Platform and execution-domain guide
Update an already-deployed device without redownloading models	Persistent-root update procedure
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

Runtime and retargeting foundation

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

Expand the integrated model catalog and its evidence boundaries

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
DART BABEL SMPL-X Motion Primitives dart-smplx	Integrated · experimental	smplx.body22.v1 dart.smplx.body22.axis_angle_primitives.v1 · 30.0 FPS	dart-smplx-cu128 · Windows x86_64, Linux x86_64 · cuda_full (VRAM 10 GiB, RAM 16 GiB) dart-smplx-cpu · Windows x86_64, Linux x86_64, macOS arm64, macOS x86_64 · cpu (RAM 24 GiB, swap 8 GiB)	No structured blocker recorded	No model-scoped observation recorded
DisCoRD MoMask HumanML3D discord-humanml3d	Integrated · experimental	humanml3d.body22.v1 humanml3d.vector263.v1 · 20.0 FPS	discord-humanml3d-cu128 · Windows x86_64, Linux x86_64 · cuda_full (VRAM 8 GiB, RAM 10 GiB) discord-humanml3d-cpu · Windows x86_64, Linux x86_64, macOS arm64, macOS x86_64 · cpu (RAM 14 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 16 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
InterMask InterHuman intermask-interhuman	Integrated · experimental	interhuman.two_actor_smpl22.v1 interhuman.motion262.v1 · 30.0 FPS	intermask-interhuman-cu128 · Windows x86_64, Linux x86_64 · cuda_full (VRAM 8 GiB, RAM 12 GiB) intermask-interhuman-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
MoMask HumanML3D momask-humanml3d	Integrated · experimental	humanml3d.body22.v1 humanml3d.vector263.v1 · 20.0 FPS	momask-humanml3d-cu128 · Windows x86_64, Linux x86_64 · cuda_full (VRAM 6 GiB, RAM 8 GiB) momask-humanml3d-cpu · Windows x86_64, Linux x86_64, macOS arm64, macOS x86_64 · cpu (RAM 10 GiB)	No structured blocker recorded	No model-scoped observation recorded
MotionCraft MC-Bench SMPL-X 322D motioncraft-smplx	Integrated · experimental	motionx.smplx53.v1 motionx.smplx322.v1 · 30.0 FPS	motioncraft-smplx-cu128 · Windows x86_64, Linux x86_64 · cuda_full (VRAM 12 GiB, RAM 24 GiB) motioncraft-smplx-cpu · Windows x86_64, Linux x86_64, macOS arm64, macOS x86_64 · cpu (RAM 24 GiB, swap 8 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 · Windows x86_64, 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
ReMoMask HumanML3D remomask-humanml3d	Integrated · experimental	humanml3d.body22.v1 humanml3d.vector263.v1 · 20.0 FPS	remomask-humanml3d-cu128 · Windows x86_64, Linux x86_64 · cuda_full (VRAM 12 GiB, RAM 12 GiB) remomask-humanml3d-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
SentiAvatar SuSu sentiavatar-susu	Integrated · experimental	susu.body25_hands40.v1 susu.body25_hands40.cont6d_root_delta.v1 · 20.0 FPS	sentiavatar-susu-cu128 · Windows x86_64, Linux x86_64 · cuda_full (VRAM 8 GiB, RAM 12 GiB) sentiavatar-susu-cpu · Windows x86_64, Linux x86_64, macOS arm64, macOS x86_64 · cpu (RAM 16 GiB, swap 4 GiB)	No structured blocker recorded	No model-scoped observation recorded
Tencent HY-Motion 1.0 hy-motion-1	Integrated · experimental	hy_motion.wooden_body22.v1 hy_motion.body22.rot6d_translation.v1 · 30.0 FPS	hy-motion-1-cu128 · Windows x86_64, Linux x86_64 · cuda_full (VRAM 26 GiB, RAM 24 GiB) hy-motion-1-cpu · Windows x86_64, Linux x86_64, macOS arm64, macOS x86_64 · cpu (RAM 40 GiB, swap 16 GiB)	No structured blocker recorded	No model-scoped observation recorded

Status dimensions are deliberately separate:

• integrated_experimental means a real VIREA Worker, isolated Runtime, adapter and bounded target-acceptance contract exist; current real-checkpoint evidence is a separate fact;
• 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 records the implemented integration contract, 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

Expand execution domains, Runtime declarations and validation status

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. Runtime choices that are not implemented for the selected domain are diagnostic facts, not selectable menu items. For example, PRISM CUDA now declares both native Windows and Linux/WSL after its CUDA 12.8 lock and shared loader were audited for Windows. Its 28 GiB RAM / 12 GiB VRAM component-split profile is the correct path for a 64 GiB + 16 GiB Windows machine; the conservative 96 GiB CPU Runtime remains a fallback rather than a reason to reject that CUDA-capable host.

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, dart-smplx, discord-humanml3d, flood-diffusion-tiny, intermask-interhuman, mardm-humanml3d, momadiff-humanml3d, momask-humanml3d, motioncraft-smplx, prism-tp2m-1-4b, remomask-humanml3d, sentiavatar-susu, hy-motion-1 cpu (RAM 10 GiB); cpu (RAM 12 GiB); cpu (RAM 14 GiB); cpu (RAM 16 GiB); cpu (RAM 16 GiB, swap 4 GiB); cpu (RAM 24 GiB); cpu (RAM 24 GiB, swap 8 GiB); cpu (RAM 40 GiB, swap 16 GiB); cpu (RAM 96 GiB); cuda_component_split (VRAM 12 GiB, RAM 28 GiB); cuda_full (VRAM 10 GiB, RAM 16 GiB); cuda_full (VRAM 12 GiB, RAM 12 GiB); cuda_full (VRAM 12 GiB, RAM 16 GiB); cuda_full (VRAM 12 GiB, RAM 24 GiB); cuda_full (VRAM 16 GiB, RAM 16 GiB); cuda_full (VRAM 26 GiB, RAM 24 GiB); cuda_full (VRAM 6 GiB, RAM 8 GiB); cuda_full (VRAM 8 GiB, RAM 10 GiB); cuda_full (VRAM 8 GiB, RAM 12 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, dart-smplx, discord-humanml3d, flood-diffusion-tiny, intermask-interhuman, mardm-humanml3d, momadiff-humanml3d, momask-humanml3d, motioncraft-smplx, prism-tp2m-1-4b, remomask-humanml3d, sentiavatar-susu, hy-motion-1 cpu (RAM 10 GiB); cpu (RAM 12 GiB); cpu (RAM 14 GiB); cpu (RAM 16 GiB); cpu (RAM 16 GiB, swap 4 GiB); cpu (RAM 24 GiB); cpu (RAM 24 GiB, swap 8 GiB); cpu (RAM 40 GiB, swap 16 GiB); cpu (RAM 96 GiB); cuda_component_split (VRAM 12 GiB, RAM 28 GiB); cuda_full (VRAM 10 GiB, RAM 16 GiB); cuda_full (VRAM 12 GiB, RAM 12 GiB); cuda_full (VRAM 12 GiB, RAM 16 GiB); cuda_full (VRAM 12 GiB, RAM 24 GiB); cuda_full (VRAM 16 GiB, RAM 16 GiB); cuda_full (VRAM 26 GiB, RAM 24 GiB); cuda_full (VRAM 6 GiB, RAM 8 GiB); cuda_full (VRAM 8 GiB, RAM 10 GiB); cuda_full (VRAM 8 GiB, RAM 12 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, dart-smplx, discord-humanml3d, flood-diffusion-tiny, intermask-interhuman, mardm-humanml3d, momadiff-humanml3d, momask-humanml3d, motioncraft-smplx, prism-tp2m-1-4b, remomask-humanml3d, sentiavatar-susu, hy-motion-1 cpu (RAM 10 GiB); cpu (RAM 12 GiB); cpu (RAM 14 GiB); cpu (RAM 16 GiB); cpu (RAM 16 GiB, swap 4 GiB); cpu (RAM 24 GiB); cpu (RAM 24 GiB, swap 8 GiB); cpu (RAM 40 GiB, swap 16 GiB); cpu (RAM 96 GiB); cuda_component_split (VRAM 12 GiB, RAM 28 GiB); cuda_full (VRAM 10 GiB, RAM 16 GiB); cuda_full (VRAM 12 GiB, RAM 12 GiB); cuda_full (VRAM 12 GiB, RAM 16 GiB); cuda_full (VRAM 12 GiB, RAM 24 GiB); cuda_full (VRAM 16 GiB, RAM 16 GiB); cuda_full (VRAM 26 GiB, RAM 24 GiB); cuda_full (VRAM 6 GiB, RAM 8 GiB); cuda_full (VRAM 8 GiB, RAM 10 GiB); cuda_full (VRAM 8 GiB, RAM 12 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, dart-smplx, discord-humanml3d, flood-diffusion-tiny, intermask-interhuman, mardm-humanml3d, momadiff-humanml3d, momask-humanml3d, motioncraft-smplx, prism-tp2m-1-4b, remomask-humanml3d, sentiavatar-susu, hy-motion-1 cpu (RAM 10 GiB); cpu (RAM 12 GiB); cpu (RAM 14 GiB); cpu (RAM 16 GiB); cpu (RAM 16 GiB, swap 4 GiB); cpu (RAM 24 GiB); cpu (RAM 24 GiB, swap 8 GiB); cpu (RAM 40 GiB, swap 16 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 14 non-test catalog models now declare whole-model CPU Runtime variants across win-64, linux-64, osx-arm64 and osx-64, plus model-specific CUDA variants on win-64 and linux-64. These declarations prove that a locked build/Worker contract exists, not that every checkpoint has completed real inference on every platform. Current-policy real-checkpoint evidence remains a separate registry fact; manual assets, restricted licenses and model-specific resource floors still apply. PRISM, for example, keeps its conservative fail-closed 96 GiB CPU RAM floor. An empty structured blocker list is not validation, so VIREA still cannot claim that every model has completed operation on every target system.

Quick start

1. Keep the checkout clean

Start from a clean clone, then choose a data volume with enough free space before syncing or installing a model. VIREA_HOME owns model assets, isolated Runtimes, downloads, results and logs; it is not a small configuration directory. Persistent commands require --virea-home PATH or VIREA_HOME, so they never silently download models to LOCALAPPDATA, $HOME, or the clone. The full bilingual walkthrough and parameter tables are in the English tutorial, 中文教程, and CLI reference. See data-root paths and quotation marks before entering a copied Windows path.

Windows PowerShell

# List local file-system volumes and their free space before choosing a data volume.
Get-PSDrive -PSProvider FileSystem
# Read the selected data-volume root once; clone and all local dependency trees will live below it.
# At the prompt paste only the directory, for example X:\VIREA-DATA; outer ' or " quotation marks are not part of the path.
$vireaDataVolume = Read-Host "Enter the selected data-volume root"
# Create the root if needed, clone the source there, then make the clone the current directory.
New-Item -ItemType Directory -Force -Path $vireaDataVolume | Out-Null
Set-Location $vireaDataVolume
git clone https://github.com/Moonweave-AI/virea.git
Set-Location virea
# Persist VIREA_HOME, UV_PROJECT_ENVIRONMENT, UV_CACHE_DIR, HF_HOME and Node caches for this user and future terminals.
& .\scripts\configure-virea.ps1 -DataRoot $vireaDataVolume
# Install all locked Python workspace packages and the development dependencies.
uv sync --locked --all-packages --extra dev
# Install the Web workspace from its locked pnpm dependency graph.
pnpm install --frozen-lockfile
# Build the local browser UI without starting a server or downloading models.
pnpm --filter @virea/web build
# Start the guided workflow: it initializes state, detects domains, lets you choose a model/Runtime/profile, confirms installation, then offers generation and browser playback.
uv run virea

Linux / WSL2

# Read a mounted data-volume root once; clone and all local dependency trees will live below it.
# At the prompt paste only the directory, for example /mnt/virea-data; outer ' or " quotation marks are not part of the path.
printf '%s' "Enter the selected data-volume root: "
read -r virea_data_root
# Create the root if needed, clone the source there, then enter the clone.
mkdir -p "$virea_data_root"
cd "$virea_data_root"
git clone https://github.com/Moonweave-AI/virea.git
cd virea
# Create the VIREA layout and install a shell hook so future terminals inherit all persistent directory settings.
./scripts/configure-virea.sh --data-root "$virea_data_root"
# Load the generated settings in this shell immediately; future shells load them through the installed hook.
. "${XDG_CONFIG_HOME:-$HOME/.config}/virea/environment.sh"
# Install all locked Python workspace packages and the development dependencies.
uv sync --locked --all-packages --extra dev
# Install the Web workspace from its locked pnpm dependency graph.
pnpm install --frozen-lockfile
# Build the local browser UI without starting a server or downloading models.
pnpm --filter @virea/web build
# Start the guided workflow: it initializes state, detects domains, lets you choose a model/Runtime/profile, confirms installation, then offers generation and browser playback.
uv run virea

macOS

# Read a mounted data-volume root once; clone and all local dependency trees will live below it.
# At the prompt paste only the directory, for example /Volumes/VIREA-DATA; outer ' or " quotation marks are not part of the path.
printf '%s' "Enter the selected data-volume root: "
read -r virea_data_root
# Create the root if needed, clone the source there, then enter the clone.
mkdir -p "$virea_data_root"
cd "$virea_data_root"
git clone https://github.com/Moonweave-AI/virea.git
cd virea
# Create the VIREA layout and install a shell hook so future terminals inherit all persistent directory settings.
./scripts/configure-virea.sh --data-root "$virea_data_root"
# Load the generated settings in this shell immediately; future shells load them through the installed hook.
. "${XDG_CONFIG_HOME:-$HOME/.config}/virea/environment.sh"
# Install all locked Python workspace packages and the development dependencies.
uv sync --locked --all-packages --extra dev
# Install the Web workspace from its locked pnpm dependency graph.
pnpm install --frozen-lockfile
# Build the local browser UI without starting a server or downloading models.
pnpm --filter @virea/web build
# Start the guided workflow: it initializes state, detects domains, lets you choose a model/Runtime/profile, confirms installation, then offers generation and browser playback.
uv run virea

The wizard restores the last model/target, labels every model not installed, needs attention, or re-verified READY, and reuses a matching deployment without another download. Installation and generation show honest stage progress plus compact results instead of raw JSON; full evidence remains in the data root. Dependency download, reconstruction, and file-count bars are routed into one VIREA live line instead of scrolling the terminal. Acceptance failures show their error and failed stages before successful download notes. Press Enter to reuse a saved choice. NO_COLOR=1 or redirected output uses bounded plain-text snapshots (first, at most one per 15 seconds, and final).

2. Advanced: install one real model non-interactively

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

# Inspect declared Runtimes and resource profiles before selecting/installing a model.
uv run virea model info flood-diffusion-tiny
# Apply a reviewed installation in one explicit domain; replace <external-home> with your VIREA_HOME.
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>
# Verify that the latest installation is still READY and accessible.
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 hardware-capability decision checks total VRAM and total physical RAM. Current available RAM/VRAM are recorded as changing observations and may be used to prefer one of several capable GPUs, but another application using memory does not make the hardware itself undeployable. Free swap/pagefile and storage remain consumable-resource checks. 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. Advanced: generate and validate non-interactively

# Submit a bounded text-to-motion job; --timeout is an end-to-end limit in seconds.
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>
# Read-only validation of the persisted generation chain; replace <job-id> with the returned value.
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. Advanced: play the result manually

# Start the local API and browser UI on loopback; --port chooses the browser URL port.
uv run virea serve --host 127.0.0.1 --port 8000 --virea-home <external-home>

Open http://127.0.0.1:8000/; it redirects to the only current Motion Studio. Generation and diagnostics share one workbench: the model-space skeleton before retargeting and the final VRM/VRMA play side by side from the same immutable result. CLI deployments/results are synchronized automatically from the persistent state. Load a local .vrm. 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 total VRAM capacity
  ├─ minimum total physical RAM capacity
  ├─ 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 the domain 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	Motion Studio, playback/recording, model catalog and VRM/VRMA Viewer
src/virea/character	dialogue planning, event timing, native motion history and activity execution
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.