System design

Architecture

One engine-neutral C++ core with thin host-specific rendering and Editor integrations.

Layers

Layer	Responsibility
`OpenVolumetricCore`	MP4 access, FFmpeg decoding, Draco decoding, buffering, timestamps, seeking, synchronization, HTTP input, and adaptive coordination
`OpenVolumetricAuthoringCore`	Presets, source validation, Draco encoding, FFmpeg command construction, MP4 packaging, adaptive manifests, and output verification
Unity integration	C ABI registry, managed component, native rendering uploads, DSP audio, and Editor window
Unreal integration	Runtime component, dynamic assets, procedural audio, Blueprint API, SDK module, and Editor window

The core includes no Unity or Unreal headers or types. Engine adapters receive complete CPU-side presentations and own host resources.

Runtime data flow

local file or HTTP byte source
              ↓
   MP4 container and one demux order
       ↙          ↓           ↘
 video decode   audio PCM   vvge packets
       ↓          ↓           ↓
 texture queue  audio ring  Draco worker
          ↘       ↓       ↙
       timestamp-matched presentation
                    ↓
          Unity or Unreal adapter

The FFmpeg demux worker owns mutable container and codec state. Draco decoding runs on a dedicated worker. Engine threads consume bounded, complete presentations rather than manipulating codec objects.

Ownership and lifecycle

OpenVolumetricPlayer owns media decoding, geometry decoding, queues, timing, seek state, and complete presentations. Start, stop, close, and destruction are designed to be idempotent. Failed initialization rolls back partially created resources.

Playback generations isolate asynchronous work across seek, loop, reopen, and adaptive switching. Old-generation packets and presentations are discarded.

Memory model

Compressed packets, decoded video, decoded meshes, audio samples, and HTTP blocks use bounded queues or caches. Shared-topology decoding retains one active reference mesh per decoder generation. Adaptive switching temporarily owns a second player session while preparing a candidate representation.

Extensibility

The installed C++17 SDK exports:

OpenVolumetric::Core
OpenVolumetric::Authoring

Concrete FFmpeg, Draco, HTTP, queue, and fragment-index headers remain private. Additional engine or production integrations should consume the public façade rather than copy codec and synchronization logic.