Skip to Content
APICapture SDK

Capture SDK

@capturly/capture-sdk records on your user’s own device, from inside your own product. It is the browser half of the capture request flow: your backend creates the request and mints a per-person link, and the SDK records against it.

npm install @capturly/capture-sdk

Public package with no dependencies. The recording engine is bundled in.

Where the credentials live

Your secret key never reaches a browser. It grants your whole organization.

What the browser gets is the per-person capability from POST /v1/capture-requests/{id}/contacts — the contact id and the k query parameter of the returned URL. That capability is scoped to one person, revocable by removing the contact, and dead once the request’s deadline passes.

For a link anyone can use, take the request’s openLink.url and pass { mode: 'open', campaignId, key } instead. See Open links.

Hosting on your own site

The SDK calls capturly.app from your page, so your page’s origin has to be on the capture request’s allowed sites. Set them when you create the request:

body: JSON.stringify({ title: 'Customer stories', prompt: 'How did it go?', status: 'active', allowedOrigins: ['https://example.com', 'https://staging.example.com'], }),

Or set an organization-wide list once, on the Capture requests page under Sites that can embed your requests. A request with no allowedOrigins of its own uses that list. When the organization has a list, a request’s own allowedOrigins can only narrow it: every origin it names must already be on the organization’s list, or the create or update is refused with 400 origin_not_in_organization_list. With no organization list, the request’s own list applies as given. Each entry is an origin, https://host[:port], with no path. Takes upload straight from the page to Capturly’s storage, which accepts only sites Capturly has enabled. Ask us to enable each site before you go live; until then its uploads fail even when the request lists it. Test from an enabled, deployed site rather than http://localhost, which is never enabled.

A page that is not listed gets origin_not_allowed. The list decides which sites may embed your requests; it is not what keeps them private. That is the per-person key, so keep treating it like a password.

Calls carry no cookies or credentials, and baseUrl stays https://capturly.app unless Capturly gave you another.

An open link records anyone who has it, with no roster. Turn it on with openLinkEnabled: true; the request’s openLink.url is then https://capturly.app/c/open/<campaignId>?k=<key>. Pass those two values:

const client = new CaptureClient({ access: { mode: 'open', campaignId, key } }); // ... await client.submit({ releaseAccepted: true, displayName: 'Jane Doe' });

An open link has no contact to name the take, so submit needs displayName; without it, submit throws nothing_to_submit before anything uploads. Open links are capped per request and rate-limited per IP more tightly than personal links; for a room full of people on one network, give each person a contact.

Recording

import { CaptureClient } from '@capturly/capture-sdk'; if (!CaptureClient.isSupported()) { // No amount of retrying fixes this. Offer another browser. } const client = new CaptureClient({ access: { mode: 'contact', contactId, key }, }); const stream = await client.preview(); // triggers the permission prompt videoEl.srcObject = stream; await client.start(); // … const take = await client.stop(); // nothing has left the browser yet previewEl.src = take.previewUrl; // let them watch it back await client.submit({ releaseAccepted: true, onProgress: (fraction) => setBar(fraction), }); client.destroy();

preview() is separate from start() so people can see themselves before anything records. Between stop() and submit() the file sits in the browser’s own storage, so a take can be reviewed and re-recorded with discard() without anything reaching a server.

Capture requests need the respondent on camera. preview({ audioOnly: true }) is deprecated and logs a warning: an audio-only take is refused at submit with camera_required.

Call destroy() on unmount, or the camera light stays on after the person has navigated away.

If the request requires a release, read its release.text from the API and show it before recording, then pass releaseAccepted: true only if the person actually accepted it.

A consent record is written only when the request requires a release and you pass true. Passing true without showing them anything records an agreement that never happened, which is worse than none. Passing false on a request that requires a release refuses the submission rather than storing an unconsented take.

Errors

Every failure is a CaptureError with a code. What matters is whether retrying can work, and who has to act:

CodeMeaningRetry?
unsupported_browserNo MP4 recording in this browserNo — offer another browser
permission_deniedCamera or microphone refusedNo — your user must allow it
no_devicesNo camera or microphone foundNo — your user must connect one
not_recording, nothing_to_submitCalled out of orderNo — fix the call sequence
invalid_requestThe call or its payload was rejected — missing release, missing name, take too longNo — fix the input
link_expiredUnknown link, or a key that no longer matchesNo
origin_not_allowedThis page’s site is not on the request’s allowed sitesNo — add it (see above)
request_closedThe capture request is closed, past its deadline, revoked, or the workspace has lapsedNo
supersededAnother take for this person landed firstNo — their other submission is the live one
quota_exceededNo room right now: take too large, or the request is at its capNo — the workspace owner must act
camera_requiredThe take has no video; capture requests need the cameraNo — record again with the camera on
abortedYou aborted submit with its AbortSignal; the take stays in local storageYes, when you choose to submit again
unknownCapturly sent a response the SDK could not read. After submit, the take may already have landedNot blindly — check the request’s submissions first
rate_limitedToo many requestsYes, after a pause
upload_failedStorage or the API failed server-sideYes
networkThe request never reached CapturlyYes

Only the last three are worth retrying as-is. Retrying anything above them (other than a take you aborted yourself) re-uploads the whole take to fail the same way.

What it does not do

Multi-participant sessions. One person at a time. A room where several people record at once needs signaling, TURN and a join ceremony, and is not part of this package. Use the sessions API and the hosted recorder for that.

UI. You get a MediaStream and state events; you render the interface.

Transcription. Capturly delivers masters; transcription is your pipeline’s.

Learning that a take landed

The SDK is not told the recording id, and your backend should not trust the browser for it. Use the capture_request.submission_received webhook, or read GET /v1/capture-requests/{id}/submissions, then download through GET /v1/recordings/{id}.

Browser support

CaptureClient.isSupported() is the check to run before showing a record button. It tests capabilities, not browser names or versions: it needs MP4 recording (MP4 MediaRecorder, or WebCodecs with MediaStreamTrackProcessor), OPFS, and getUserMedia, which requires a secure context. Current Chrome, Edge and Safari 16.4+ pass it. Firefox lacks both MP4 paths today, so it returns false there.

In-app browsers

isSupported() reports what the browser actually exposes. Many in-app browsers, the ones social and QR-scanner apps open links in, hide the camera or local storage, so it returns false there. Offer a link that opens the page in the device’s own browser. The iOS Camera app’s QR scanner opens Safari, which works.

Last updated on