Capture & Protection Guide

The useCapture hook is the primary interface for capturing media and applying cryptographic protection. It supports two modes: image (camera) and audio (microphone).

How Protection Works

When you trigger a capture, the SDK uses a background protection queue to keep your UI responsive:

1. onCapture fires immediately with a CaptureEvent containing the raw media blob and a unique captureId. Use this to show a preview or continue the user flow.
2. onProtected fires once the cryptographic seal (Trust Label) has been applied in the background. The ProtectedEvent contains the same captureId, allowing you to match the protected asset to the original capture.
3. onProtectError fires if protection fails for a specific capture.

Monitoring the Queue

Image Capture

Setup

import { useCapture } from "@trustnxt/protect-react";

function Camera() {
  const capture = useCapture({
    mode: "image",
    apiKey: "tnxt_live_...",
    apiSecret: "tnxt_secret_...",
    onCapture: (event) => preview(event.blob),
    onProtected: (event) => upload(event.protectedBlob),
  });

  return (
    <div>
      <video ref={capture.previewRef} autoPlay playsInline muted />
      <button onClick={capture.takePicture} disabled={capture.isCapturing}>📸</button>
    </div>
  );
}

Camera & UI State

Advanced Camera Controls

Audio Recording

Setup

const capture = useCapture({
  mode: "audio",
  waveformRef: myRef, // Required for visualization
  apiKey: "tnxt_live_...",
  apiSecret: "tnxt_secret_...",
  onCapture: (event) => console.log("Recorded duration:", event.duration),
  onProtected: (event) => upload(event.protectedBlob),
});

Recording Controls

Sensors & Location

Sensor data (GPS, accelerometer, gyroscope, orientation) is automatically collected and embedded in the Trust Label when the capture occurs.

const capture = useCapture({
  mode: "image",
  locationObfuscationRadius: 5000, // Optional privacy setting
  // ...
});

Deferred Protection

By default, the SDK automatically enqueues captures for protection. Set autoProtect: false if you need to perform additional logic (like user confirmation) before sealing.

const capture = useCapture({
  mode: "image",
  autoProtect: false,
  onCapture: (event) => { /* wait for user confirmation */ }
});

// Later, when confirmed:
capture.enqueueProtection(event.captureId, event.blob, event.sensorSnapshot);

Permissions Handling

The SDK handles most permission requests automatically, but you can also trigger them manually for a more controlled user experience.

Camera & Microphone

By default, the SDK requests camera (Image mode) or microphone (Audio mode) access as soon as the component using useCapture mounts.

If access was previously denied or blocked, or if you want to request access on a specific user action (like a "Start" button), use capture.requestPermissions():

if (capture.permissionStatus === "denied") {
  return (
    <div className="permission-error">
      <p>Camera access is required to capture trusted media.</p>
      <button onClick={capture.requestPermissions}>
        Grant Access
      </button>
    </div>
  );
}

Location (GPS)

By default, the SDK does not ask for location permission during initialization. It will only trigger the browser prompt when the user actually captures an asset.

Manual Location Request

You can use capture.requestLocationPermission() to ask for GPS access in advance. This is useful for "priming" the GPS permission on a landing page before the camera interface is even shown.

const capture = useCapture({ mode: "image" });

// ... elsewhere in your UI
<button 
  onClick={capture.requestLocationPermission}
  disabled={capture.locationPermissionStatus === "granted"}
>
  Enable GPS in Advance
</button>

Monitoring Status

Use these properties to provide real-time feedback to your users:

Values for both can be "unknown", "granted", "denied", or "error".