Skip to content

Session Replay Models

Upload the egocentric (head in XR, robot in Physical AI) and controller (optional for robotics) models Session Replay shows for your sessions using the Upload Web App. Without custom models, Session Replay shows generic models for your project type.

What are Session Replay Models?

Session Replay draws the participant's headset and controllers as 3D models. A scene version can carry its own models in three slots:

Slot Shown as
head The participant's headset or the robot model
controller_left The left controller, optional for robots
controller_right The right controller, optional for robots

A slot is empty until you upload a model into it; an empty slot shows the generic model based on your project type. Models are per scene version: a new scene version starts with empty slots.

Prerequisites

  1. An existing scene - the models belong to a scene version. See Scene Uploads.
  2. A glTF 2.0 model per slot - a single .glb, or a .gltf with its .bin and textures.

Required Files

Each slot takes one model:

File Required Description
{any-name}.glb One model form The model as a single glTF 2.0 Binary file, textures included
{any-name}.gltf One model form The model in glTF 2.0 Separate format
.bin file With a .gltf The buffer the .gltf references
Texture files With a .gltf PNG, JPG or WEBP images referenced by the .gltf

One model per slot

Upload either a single .glb or a .gltf with its files, not both. A .glb is converted to glTF Separate on the platform. The file names do not matter: the model is stored under the slot's name.

Not accepted: .obj models, .jpeg textures (rename them to .jpg, and in the .gltf), a pre-compressed .glb.gz, and, beside a .glb, a loose file named {slot}_{n}.{ext} (those names are used for the images extracted from the .glb).

Uploading a Model

  1. Go to upload.cognitive3d.com
  2. Enter your developer API key and click Get Started
  3. Select Session Replay Models from the upload menu
  4. Choose the Scene. The latest version is selected; pick another version if the scene has several
  5. In the slot you want to fill, drag and drop the model files, or the folder that holds them, or click to browse
  6. Check the file list for errors, then click Upload

The slot shows the model name and its file count. To change a model, drop new files into its slot and click Replace; to remove one, click Delete and confirm.

A new scene version while you work

The page keeps the scene list fresh. If a newer version of the scene appears while you have an older one open, a notice names it and offers Switch to v{n} or Stay on v{n}. An upload started on the older version is held: the page switches to the new version and asks you to check the slot and upload again, so a model is never sent to a version you did not see.

Optimization

Models uploaded here are optimized for Session Replay in the background, the way dynamic objects are. The slot shows Optimizing… for up to two minutes after an upload, then Optimized once the optimized copy exists. A small model may stay Not optimized: it is used as uploaded, which is fine.

Replacing during optimization

Replacing a model while it says Optimizing… can leave the previous optimization in place. Wait for the status to settle before replacing a model you just uploaded.

Troubleshooting

The upload button is disabled and the file list shows an error

The files were refused before upload. The message names the file: two models, a .glb beside a .gltf, an .obj, a .jpeg, an unsupported extension, or a file named like an extracted image. Fix the selection and try again.

The file list says the model references a file that is stored under another name

A .gltf names its .bin and textures by path, and Session Replay fetches exactly those names. When the selected file would be stored under a different name (it sits in a subfolder, or its name needed cleaning), the message names both. Edit the .gltf to reference the stored name, or move the file next to it.

The upload fails with "Could not convert …"

The .glb passed the file checks but the platform could not convert it: it references texture or buffer files outside itself, it is malformed, or its JSON is over 8 MB. Re-export it from your 3D editor with textures embedded, or export glTF Separate instead.

Session Replay still shows the old model

Reload the Session Replay page. A model that was just replaced can take a minute to reach every viewer.

The model is the wrong size or faces the wrong way

Export the model centred at the origin, facing forward along the negative Z axis, in metres, with transforms applied, as you would for a dynamic object.

intercom If you have a question or any feedback about our documentation please use the Intercom button (purple circle) in the lower right corner of any web page or join our Discord.