Tempusxr Français
Menu
  1. Docs
  2. Build with the SDK

Photo and video capture

Let people take a photo or record a video of your experience. What is saved is what they see: the real camera picture and the 3D content together, in one file. The buttons and menus of the interface are not in the picture.

It is opt in: a page that does not import it pays nothing. Try it on a phone: the A-Frame example and the Three.js example.

Three.js

import { create } from '@tempusxr/sdk-three';
import { enableCapture } from '@tempusxr/sdk-capture'; // the opt in line

const ar = create({ container: '#ar' });
const capture = enableCapture(ar);

// Your own button, if you prefer:
const photo = await capture.photo();   // { blob, url, width, height, type }
await capture.startVideo();
const clip = await capture.stopVideo();
await capture.share(photo);            // the share sheet on a phone, a download on a computer

With loadScene(), give the experience it returns: enableCapture(experience.session).

A-Frame

Two more script tags and one attribute, no JavaScript:

<script src="tempusxr-capture.min.js"></script>
<script src="tempusxr-aframe-capture.min.js"></script>

<a-scene tempusxr="tracker: image; targets: poster.txr" tempusxr-capture="video: true; maxSize: 1920">

The scene sends tempusxr-photo and tempusxr-video events with the file in event.detail. In a script, the capture is scene.components['tempusxr-capture'].capture.

The shutter

Like Snapchat, one big round button sits at the bottom center of the screen:

After a shot, a preview opens with Share, Save and Close. The shutter hides while the preview is open, and while the experience is loading or shows an error. A short hint under the button ("Tap for a photo, hold for a video") fades after a few seconds. From a keyboard, Enter or Space takes a photo.

Your own look: put an element with data-tx-shutter in your overlay and it gets the same gestures instead. data-tx-action="photo" and data-tx-action="record" are plain buttons (photo; start and stop). Turn the built in interface off with ui: false.

The timer

A Timer button in the right capsule cycles off, 3 seconds and 10 seconds, like Snapchat's. With a timer on, a tap on the shutter shows a big number counting down over the camera, then shoots. A hold starts a video hands free after the countdown, and a tap on the shutter stops it. A tap during the countdown cancels it. In code: capture.photo({ delay: 3 }), capture.startVideo({ delay: 3 }), the countdown event, capture.cancelCountdown(), and the timer option for a default.

Sound

Videos carry the sound of the experience: the sound of the videos and audio files of a scene is recorded with the picture. With loadScene, give the experience to capture and it works by itself:

const experience = await loadScene(url, { container: '#ar' });
enableCapture(experience); // the scene's sound is in the videos

The audio option picks the sound: 'experience' (default), 'microphone' (the phone asks first), 'both' (mixed into one track), or 'none'. microphone: true is a shortcut for 'both'. A sound file from another site must allow reading from another address (Access-Control-Allow-Origin), or the browser keeps it out of the recording.

Options

OptionWhat it does
maxSizeLongest side of a photo, in pixels. Default 1920.
photoTypeimage/jpeg (default) or image/png.
video{ maxSize: 1280, fps: 30, maxSeconds: 60, bitsPerSecond }. A recording stops by itself at maxSeconds.
audioThe sound of videos: 'experience' (default), 'microphone', 'both' or 'none'.
timerSeconds of countdown before a shot (0, 3 or 10 in the interface). Default 0.
watermark{ image, text, position, size }: a logo or a text in a corner.
holdMsHow long the last camera picture is kept while the camera restarts. Default 5000.
uiAdd the shutter and the preview. Default on.

How it works

The page shows two layers: the camera video, and above it the transparent 3D canvas. Capture draws both into a hidden canvas, cropped the way the screen crops them and mirrored for the front camera, in the same frame, right after the 3D is drawn (that is the only moment a 3D canvas still holds its picture). That canvas becomes the photo, or the frames of the video. When you are not shooting, it does nothing.

Restarts and world tracking

A recording does not depend on the camera or on tracking, only on its own canvas. So it goes on when the camera restarts, when tracking restarts, when you swap tracker, or when the session is created again. During the gap the last camera picture and the last 3D picture are held, so the video does not blink. If the 3D stops rendering for a moment, a photo is still made.

With a tracker where the platform owns the image (world tracking with WebXR, or the iOS bridge), the camera has no video frame to copy. A camera provider can then offer drawBackdrop(context, width, height) to draw the real world picture itself. When it cannot (a browser that gives no access to the camera image), the files hold the 3D content only, and photos are PNG files with a transparent background. capture.hasCamera says which one you get.

Formats and limits