Skip to content
Capture entity motions and replay them on other entities
Branch: master
Clone or download
wmurphyrd and dmarcos Updates for A-Frame v0.8.x compatibility (#40)
* Bypass deprecated gamepadconnected event.
Wrap new throttled version of updateControllerList
Provide real gamepad list to updateControllerList as it no longer
queries this on its own and doesn't clear out controller stubs otherwise

* Fix tests. Account for fp precision in rotation checks. Change controller injection to synchronous test to allow for multiple calls to controllersupdated from both original and wrapped updateControllerList

* Rework updateControllerList wrapper to avoid doubling
'controllersupdated' event
Stop filling in gaps in GamepadList with mock controllers as it was
preventing detection of replayer activation
Update matrix when updating controller pose as autoUpdate is now turned

* fix cleanup
Latest commit 3a3cbd7 May 11, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
dist log error if idb fails to open Sep 14, 2017
examples make avatar-recorder/avatar-replayer Inspector-ready (#32) Aug 18, 2017
src Updates for A-Frame v0.8.x compatibility (#40) May 10, 2018
tests Updates for A-Frame v0.8.x compatibility (#40) May 10, 2018
.gitignore First working version Jan 9, 2017
LICENSE Initial commit Dec 23, 2016 spectator mode query param Sep 4, 2017
index.html support specify recording with query param ?avatar-recording (#19) Apr 4, 2017
package.json make avatar-recorder/avatar-replayer Inspector-ready (#32) Aug 18, 2017


A-Frame motion capture components record pose and events from entities (e.g., camera and tracked controllers) that can be stored in JSON or localStorage and then later replayed.

The motion capture components allow us to emulate the presence of a VR headset and controllers. We can build test automation tools for VR experiences. We can replay the recorded user behavior and assert the state of the entities at the end. This can happen with no user intervention at all.

We can also record user interactions and develop on the go where there's no VR hardware available. We can iterate over the visual aspect or behavior of the experience using the recorded user input. Read more about the motion capture components and its use cases as development tools.

The A-Frame Inspector uses these components to power the Motion Capture Development Tools UI.



The motion capture components is most easily used by opening the A-Frame Inspector (<ctrl> + <alt> + i), and hitting m to open the Motion Capture Development Tools UI.

Avatar Recording

An avatar is the representation of a user. Use the avatar-recorder to record headset and tracked controller poses as well as controller events (i.e., button presses and touches).

  1. Set the avatar-recorder component on the <a-scene> element.
  2. Make sure your controllers have ids.
  3. Hit <space> to start recording.
  4. Record movements and controller events.
  5. Hit <space> again to stop recording.
  6. You'll have an option to save the JSON file or upload it by pressing u on the keyboard.
  7. The recording will play from localStorage.
<a-scene avatar-recorder>
  <a-entity id="controller1" hand-controls></a-entity>
  <a-entity id="controller2" hand-controls></a-entity>

Hit c on the keyboard to clear all recordings from localStorage.

Avatar Replaying

The avatar-recorder will automatically set the avatar-replayer component. Though we can specify the avatar-replayer explicitly if we want to configure it or if we don't need recording (i.e., production).

avatar-replayer can be manually disabled from the URL query parameter avatar-replayer-disabled (e.g., http://localhost:8000/?avatar-replayer-disabled). spectator-mode can be enabled using the URL query parameter specatatorMode.

From localStorage

By default, the avatar-recorder will save the recording into localStorage which the avatar-replayer will replay from by default. Recordings are stored in localStorage.getItem('avatarRecordings') and are keyed recordingName (defaults to default).

Hit p to toggle playback.

From File

We can specify the path to a recording file via the avatar-recording query parameter in the URL:

Or we can specify the path to a recording file in the HTML via the src property:

<a-scene avatar-replayer="src: recording.json">
  <a-entity id="controller1" hand-controls"></a-entity>
  <a-entity id="controller2" hand-controls"></a-entity>



Property Description Default Value
autoPlay Whether to play recording on page load. true
autoRecord Whether to start recording on page load. false
autoSaveFile Whether to prompt to save a JSON of the recording to file system. true
localStorage Whether to persist recordings in localStorage keyed as avatarRecordings. false
loop Whether to replay recording in a loop. false
recordingName Name of recording to store in localStorage.getItem('avatarRecordings'). default
spectatorMode Whether to replay recording in third person mode. false
spectatorPosition Initial position of the spectator camera. 0 0 0


Method Description
saveRecordingFile (recording) Save recording to file. recording can either be raw data or recording name stored in localStorage.
startRecording () Start recording
stopRecording () Stop recording.

Keyboard Shortcuts

Key Description
space Toggle recording.
q Toggle spectator mode camera.
c Clear recording from localStorage and memory.
u Upload recording to file host and get short URL.


For spectator mode, avatar-replayer will create a head geometry to make the camera visible, represented as a pink box with eyes. This set as cameraEl.getObject3D('replayerMesh') but is not visible by default.

Property Description Default Value
autoPlay Whether to play recording on page load. true
loop Whether to replay recording in a loop. false
recordingName Specify to replay recording from localStorage. default
spectatorMode Whether to replay recording in third person mode. false
spectatorPosition Initial position of the spectator camera. 0 0 0
src Path or URL to recording data. ''


Method Description
replayRecordingFromSource () Replay recording from either recordingName for localStorage or src for external file.
startReplaying (recordingData) Start replaying given passed recording data (object).
stopReplaying () Stop replaying.


Property Description Default Value
enabled true
loop The animation replays in a loop. false
recorderEl An entity that it's the source of the recording. null
src The recording data can be hosted in a URL. ''


Property Description Default Value
autoRecord The component start recording at page load. false
enabled true
hand The controller that will trigger recording. 'right'
recordingControls Recording is activated by the controller trigger false
persistStroke The recorded stroke is persisted as reference. false
visibleStroke The recorded stroke is renderered for visual feedback. true



Install and use by directly including the browser files:

  <title>Motion Capture</title>
  <script src=""></script>
  <script src=""></script>
  <a-scene avatar-recorder avatar-replayer>
    <a-entity id="leftHand" hand-controls="left"></a-entity>
    <a-entity id="rightHand" hand-controls="right"></a-entity>

Or with angle, you can install the proper version of the component straight into your HTML file, respective to your version of A-Frame:

npm install -g angle && angle install aframe-motion-capture-components


Install via npm:

npm install aframe-motion-capture-components

Then require and use.

You can’t perform that action at this time.