- Docs
- 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:
- Tap it for a photo.
- Press and hold it for a video. A red ring fills around the button over the time limit, and a clock shows the time. Let go to stop.
- Slide up while holding to lock the recording: your hands are free, and a tap on the button stops it.
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
| Option | What it does |
|---|---|
maxSize | Longest side of a photo, in pixels. Default 1920. |
photoType | image/jpeg (default) or image/png. |
video | { maxSize: 1280, fps: 30, maxSeconds: 60, bitsPerSecond }. A recording stops by itself at maxSeconds. |
audio | The sound of videos: 'experience' (default), 'microphone', 'both' or 'none'. |
timer | Seconds 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. |
holdMs | How long the last camera picture is kept while the camera restarts. Default 5000. |
ui | Add 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
- Video format: the browser picks. iPhones record MP4, Chrome and Android record MP4 or WebM. Some apps do not take WebM; a page cannot convert it.
- Sound: a video carries the sound of the experience, and the microphone if you ask for it.
- Time: at most 60 seconds by default, so a forgotten recording does not fill the phone.
- Page hidden: if the person leaves the page, the recording ends and is kept (
interrupted: true). - Privacy: nothing is uploaded. Files stay on the device, and their addresses are freed when the preview closes.